Post v1.0.0 features

[KenEucker]

@kaimallea,

Last night I went through and looked at all 44 forks of the repository to see what people had been doing with their versions of the repo over the last 10 years or so. I've compiled a small list of notable changes that were found in other versions of this imgur code that we might consider implementing as well.

This user added a method for the /account/me/albums endpoint, and named it getAlbums:

• marciocesarcorrea@d92272e

This user added a method for the /gallery/r endpoint, and named it searchReddit:

• Kostargy@772ce3f

This user included a fix that we may not have addressed before. I did see an issue covering this but it was from many years back:

• Dcard-Fork@d7d7f85

This user added the setAccessToken method that I added recently. They also include a getAccessToken method which we might consider adding as well.

• Crecket@7933726

@cacheflow was helping you with the TS rewrite, from what I understand. They've got the most work going on in their fork but this was something I felt was worth including here. This code implements an LRU cache, which I might personally disable as I handle my own caching (and I want my requests to Imgur to always be fresh), but I could see this being a useful feature:

• cacheflow@f7f25e1

https://www.npmjs.com/package/imgur-v2
This is a fork of the repo, created by user @Crecket, that had made its way to npm. I've considered reaching out to them and encouraging their return to origin now that the package is up to date and supports what they need.

Anywho, I just wanted to put this information out there and see if we might include some of this in a sort of roadmap. One thing that has been on my mind, given the new testing abstraction of creating individual handler files for each function of the API. I feel that it would be good to break down the lib into each of the Imgur-specific endpoint bases. This would turn lib/imgur.js from being one large file into a file that includes the functionality from other files and wraps it all into a single API. We would then end up with:

account.js // /account
album.js  // /album
auth.js <--- auth methods
comment.js  // /comment
gallery.js  // /gallery
image.js  // /image
imgur.js <--- loader

Thoughts?

[kaimallea]

Wow, amazing research and insights into the forks. I think there is definitely some things we can pull back into this package.

I definitely want to restructure the project, use ES6 classes, break things out into their own modules for testability and maintainability, etc., and adopt things like TypeScript.

One mistake I made in the past was trying to make too many, big breaking changes at once and not planning to release it until it was done™. I think that contributed to losing steam/motivation. I'd like to take a more iterative approach, i.e. starting a 2.x or next branch now, and set up continuous releases, even if it's unfinished. That way people can choose to use the stable 1.x branch, but also have the option to use a new, possibly unfinished release if they want -- and maybe even contribute to it themselves.

It'd be great to spell out the ideas in a dedicated place (maybe this is it), and once in agreement, we can make a project/issues list and start picking them off.

TL;DR --

• Maintain two continuously deployed versions (1.x in support/maintenance mode, and next is unstable, but working, with the major refactoring until it stabilizes and then it's 2.x)

Made possible with https://docs.npmjs.com/cli/v7/commands/npm-dist-tag

e.g., npm install [email protected] and npm install imgur@next

[KenEucker]

@kaimallea I do think that this is the place to spell out the ideas and come to an agreement. From here we can create issues and assign them to whichever project.

I like the idea of maintaining two CD versions with 1.x for all minor and patch updates while next is for the next major version.

I would like to see organization and code coverage + supporting all Imgur endpoints prioritized over larger projects like moving to TypeScript, but that's just a preference.

I'm happy to be involved and hope to see this package help more people as time goes on.

[kaimallea]

Also worth pointing out that the dev branch (tree view)-- albeit 2 years old -- has already done some of the things suggested here. It also includes contributions from @cacheflow , including a few other PRs that I closed recently but can easily be reopened.

Might just require some dusting and tweaking (i.e., updating dependencies, tests). Imgur API hasn't really changed in years.

[kaimallea]

@cacheflow welcome back! +1 to optional caching

@KenEucker i'd love to have you work on the next branch rather than just maintain 1.x.

Re: the dev branch, we could also just use it as a reference/for inspiration, cherry-picking things here and there as needed. I also don't want to fall into the rabbit hole of trying to revive an abandoned branch. I think continuity is important, so using 1.x as a starting point for next and incrementally improving it might be more productive and won't have missing context.

[cacheflow]

Is there a list of remaining tasks that we have to get done? I couldn't find any on Github. @kaimallea. @KenEucker

[KenEucker]

@cacheflow I haven't had a chance to contribute since my last PR, which committed the same mistakes that @kaimallea pointed out in their first reply to this thread: too many breaking changes at once. I fear that may have derailed the momentum we had at the beginning of the year. My PR, #172, aimed to replace the use of got with axios after having discovered that got is not isomorphic, in order to support compiling this API for both node and the browser.

It does appear that all of the proposed goals outlined below have been met with v2. From my view, what would be remaining would be to add the remaining tests for all API endpoints: https://apidocs.imgur.com/

[cacheflow]

Yeah, I agree we lost a lot of momentum. We should add the remaining tests for the endpoints and release v2.

[KenEucker]

@cacheflow in addition to releasing v2 with all of the endpoint tests, there are a few bugs with @next that could be addressed. I have tried to look into them but haven't had the time to really resolve anything.

@kaimallea you around?

[kaimallea]

Alrighty, I tried to write out the goals, problems and proposals, just for future reference and transparency for potential contributors:

Goals

• We want to continue building out the library to support as much of the public Imgur API as possible.

• Want the project to be approachable by contributors of all experience levels. The code should be structured
  in a way that makes it relatively easy maintain, extend, and test (i.e., a good developer experience).

Blockers/Hurdles in the Way of Goals:

imgur.js is currently a single, giant module containing all logic. It's basically an object literal with a bunch of functions as props.

The lack of modularity has made the development experience cumbersome. Difficult to maintain, extend, and write tests for.

Proposals:

To achieve the aforementioned goals, the following is proposed, not in any particular order:

Modularize

• Break out functions into modules.
• Organize modules in directories that match Imgur API categories (e.g., directores named image, account, album).
• Use barrel files (i.e., image/index.js) to roll up adjacent modules files so that consumers can use a single import

Breaking Refactor

• Remove built-in CLI support (will be a separate package)
• Rename Imgur -> ImgurClient and make it an ES6 class that extends EventEmitter.
  • Extending EventEmitter will allow us to emit custom events. It will also allow consumers to add listeners to track things like upload progress when uploading multiple files.

Build/Dev Infra

• Rename lib to src and move __tests__ into src. A suggestion to follow modern conventions.
• Integrate Babel to enable use of use newer JS features (e.g., import).
  • import will make using barrel files nicer
  • in general, enabling use of new features via Babel also makes the repo more approachable by contributors
• Generate types directory with TypeScript so that consumers of the library have a great developer experience in, e.g. VS Code. This doesn't require migrating to TypeScript. We'd just use the tsc command to generate types from our JSDoc comments.

Stretch

• Migrate to TypeScript
  • Moving to TS can be its own chore. I definitely want to do it eventually, and I'm happy to do it later, so that it that doesn't interfere with the momentum of building out support for more features/API endpoints. We should at least generate type info for consumers. This will require we continue to use JSDoc to document code so that we can automate type output.

[kaimallea]

@KenEucker Sorry for being MIA. Lots of personal/family stuff has gotten in the way of being active here. Would you be interested in transfer of ownership of this project? You have been the most active contributor and have more time and care than I do these days. LMK

[KenEucker]

@kaimallea I think that is all the steps needed. I will fork over to a project called "imgur" on my end, dropping the "node-" if that's okay!

[KenEucker]

Welp. It seems I can only fork this code once. I renamed my branch:
https://github.com/KenEucker/imgur

[kaimallea]

Okay, all set. On your next publish, the readme and repo information on the npm page should be updated to reflect what is in your package.json file

[kaimallea]

@KenEucker I'll leave this repo as is for a few days before I archive. Thanks again for all of your support and contributions and best of luck continuing the development! I will be looking on and cheering and maybe even contribute back myself when I get free time again. Happy Holidays!

[KenEucker]

@kaimallea I logged into npm and the project shows up under my account. I think we're all set.

Thank YOU, for taking the time to put attention back into this project when needed. I know it's been one of those things that sort of came back from the grave to haunt you, and I will readily admit that I went searching the internet for a way to get your attention. Even through all of that, you have been courteous and collaborative and I appreciate you for that. Additionally, I learned a lot in the process, and I feel grateful for that.

Thank you so much for contributing to Free and Open-Source Software and for demonstrating all of the core tenants that the open-source community is well known for. I wish you all the best in your future endeavors.

~ Ken

[KenEucker]

@cacheflow, see the thread above?

I am ready to publish v2.0.0, the new (unofficial) imgur API, by the end of 2021. Wanna come help me out on that project? Before I launch I would like to be able to write the CLI project so that users have a migration path to v2 that doesn't force them to write fs.createReadStream on their own.

After 2.0.0, I would like to target a 2.1.0 release that covers all of the API endpoints as we previously discussed and I think that's a pretty achievable goal for end of 2022.

[cacheflow]

Yeah, I do. I'm down to provide some help in releasing 2.0.0 @KenEucker.

[KenEucker]

@cacheflow come join me: https://GitHub.com/keneucker/imgur