Please open a v3.0.0-dev branch for breaking changes

[TheYuriG]

A few of the issues opened here (#30, #29) require a change in the name of some functions, which would break the current version.

I guess this would mean that we also need to separate the documentation website in v2 and v3, with a section for breaking changes for new, incoming users.

Lastly, should we put a deprecation warning on the current functions so users looking into upgrading to v3 are ready for the change?

PS: Amazing library. I intend to contribute a lot here starting mid-March. Currently building a massive trophy database backend using this. Flawless work.

[wescopeland]

Hi! Thank you for your feedback. Contributions are of course welcome!

Now that the library has gained some traction, versioned docs would make sense.

I am happy to create a v3.0.0 canary branch for breaking changes, however I'm inclined to believe that as soon as those changes are in we should just ship 3.0.0. This would render the creation of such a branch as a moot point.

It might be best to add exports with the new names and mark the existing ones as deprecated in a patch release. If you are looking for a first PR, this would be a great candidate.

[wescopeland]

Other thoughts on a potential v3:

• Transitioning from dts-cli to microbundle
• Transitioning from Docusaurus to VitePress

I have recently built https://github.com/RetroAchievements/retroachievements-api-js, where I had great success with both of these. This library originally began as a fork of psn-api.

[TheYuriG]

I am happy to create a v3.0.0 canary branch for breaking changes, however, I'm inclined to believe that as soon as those changes are in we should just ship 3.0.0. This would render the creation of such a branch as a moot point.

Not my library so none of my business how you run it, but I think we still have a bunch of good features we could add that could be ported to 2.x.x, like universal game search from #88. I don't think we have any big changes yet that justify going to 3.0.0 right away? Maybe you could provide some clarification here about the 2 things you mentioned, as I trust you know more about them.

I've created my own singleton component that handles the entire connection management process behind the scenes and reconnects and refreshes when necessary, which I think could be a great addition to this library as well. We can discuss this better halfway through March, as I'm currently laser-focused on creating my backend. Maybe I can even bring some other upgrades I'm yet to discover by then.

[wescopeland]

I think we still have a bunch of good features we could add that could be ported to 2.x.x

My perception is these function renames would not be earth-shattering changes, especially if a deprecation notice lands in 2.x.x. Of course I am happy to minimize breaking changes as much as possible. The best path forward might be to rename the functions themselves, then re-export them under the old names with a @deprecated tag. Then all references to the old names would be scrubbed from the documentation. New library consumers will use the new names, while existing library consumers will see an annoying strike through the old name in VSCode.

Maybe you could provide some clarification here about the 2 things you mentioned, as I trust you know more about them.

microbundle is generally better maintained than dts-cli and I've seen a ~45% reduction in bundle sizes using it over dts-cli.

Docusaurus is kind of a pain to work with; I've found VitePress to generally be a faster and more productive docs site generator.

[TheYuriG]

The best path forward might be to rename the functions themselves, then re-export them under the old names with a @deprecated tag. Then all references to the old names would be scrubbed from the documentation. New library consumers will use the new names, while existing library consumers will see an annoying strike through the old name in VSCode.

Yeah, this sounds like the perfect solution to me!

microbundle is generally better maintained than dts-cli and I've seen a ~45% reduction in bundle sizes using it over dts-cli.

Docusaurus is kind of a pain to work with; I've found VitePress to generally be a faster and more productive docs site generator.

Alright man, looks exciting. Looking forward to getting to work on this with you soon. :)

PS: I forgot to suggest this, but one of the ideas I had for 3.0.0 is removing entirely the need to pass the authorization as a parameter to functions, also being able to set a set user to fetch data from (that is not the same as the logged-in user, as I know some people are afraid of using this with their actual gaming account, doing something wrong, getting rate limited or even banned from PSN for API abuse).

[wescopeland]

Looking forward to getting to work on this with you soon. :)

Likewise!

PS: I forgot to suggest this, but one of the ideas I had for 3.0.0 is removing entirely the need to pass the authorization as a parameter to functions, also being able to set a set user to fetch data from (that is not the same as the logged-in user, as I know some people are afraid of using this with their actual gaming account, doing something wrong, getting rate limited or even banned from PSN for API abuse).

I would definitely be open to suggestions on this. One reason it currently works this way is to keep the functions pure so dead code elimination can work properly when someone imports the library. By keeping everything pure, if someone only uses two functions from psn-api, those will be the only two functions that make it into their build.

One potential approach could be to have some kind of authorized client class, where authorization is handled in the constructor. Then users could decide if they want better DX for slightly larger bundle sizes.

[TheYuriG]

I would definitely be open to suggestions on this. One reason it currently works this way is to keep the functions pure so dead code elimination can work properly when someone imports the library. By keeping everything pure, if someone only uses two functions from psn-api, those will be the only two functions that make it into their build.

Oh, that's cool, you had tree shaking in mind when you did it this way.

One potential approach could be to have some kind of authorized client class, where authorization is handled in the constructor. Then users could decide if they want better DX for slightly larger bundle sizes.

Yeah that sounds like a good compromise, that way users can opt for smaller bundle sizes or DX comfort.

[TheYuriG]

As a heads-up, I'm mocking this library on Postman so people (and us too!) can easily test stuff without constantly having to start a node server, change code, save, restart the server, etc.

Maybe this is something you will want to add to the V3 milestone docs?

Tested Endpoints collection fork prompt:

[wescopeland]

This is cool! I did something similar with https://insomnia.rest when I was building the library. I am not too familiar with Postman and don't know how additions to this could be automatically enforced when new functions are added to the library. It also doesn't seem like I can connect my GitHub account to Postman.

Currently my perception is this is a helpful tool but also slightly beyond the scope of the library offering itself. An advantage of the playground (yarn playground) is it forces a developer to poke and prod at the library the same way a user would.

The playground should not require a server restart. It should update automatically in real time. If you're seeing a situation where a restart is required for changes to kick in, we should fix that.

[TheYuriG]

Currently my perception is this is a helpful tool but also slightly beyond the scope of the library offering itself.

Huh, that's actually true. Maybe it would be better off on @andshrew's Playstation-Trophies library instead, since that's agnostic like Postman (sorta, since they have a javascript playground).

EDIT: Made an issue on their library to check for interest.

An advantage of the playground (yarn playground) is it forces a developer to poke and prod at the library the same way a user would.

The playground should not require a server restart. It should update automatically in real-time. If you're seeing a situation where a restart is required for changes to kick in, we should fix that.

Oh, I haven't messed with yarn playground at all, maybe I should try that at some point. My dev environment is honestly a mess as it is.

[wescopeland]

I agree now that you mention it andshrew's repo is probably a good fit 👍

[TheYuriG]

@wescopeland Ok, so here is my idea for V3.0.0.

V2 stays tree-shakeable as it is, very low level and controllable. Most features brought over to V3 will be backported to be used in V2 if users prefer to not need to update their code / keep functions low level.

V3 should be high-level. The authorization will be completely handled behind the scenes automatically, as it was requested here and it's how I use it myself. Needing to manage the authentication state is some really boring chore, I don't see the reason to enforce our users to do that. In fact, being low-level as it is was what pushed me away from even trying the library for the past several months, but then I had no choice when my Discord bot got killed by PSN Profiles' Cloudflare DDoS protection last month. Do or die it was, and I'm not dying.

While I do understand the reasoning behind tree-shaking, this is not a library that will be shipped to clients, so it really shouldn't be our biggest worry if our bundle size is 3kb or 7kb. Instead, we should worry about developer experience and make the library fun/intuitive to use.

The Python library uses an approach that I think would also benefit us a lot, which is the ability to chain commands one after the other with the Builder Design Pattern. A design pattern like that would probably fit our use case as well.

Let me know what you think, for now, I'm gonna start the branch to add the functionality of getting Gamer playtime in games.

[wescopeland]

V2 stays tree-shakeable as it is, very low level and controllable. Most features brought over to V3 will be backported to be used in V2 if users prefer to not need to update their code / keep functions low level.

V3 should be high-level. The authorization will be completely handled behind the scenes automatically, as it was requested #34 (comment) and it's how I use it myself. Needing to manage the authentication state is some really boring chore, I don't see the reason to enforce our users to do that. In fact, being low-level as it is was what pushed me away from even trying the library for the past several months, but then I had no choice when my Discord bot got killed by PSN Profiles' Cloudflare DDoS protection last month. Do or die it was, and I'm not dying.

Thanks for sharing your ideas on the future of psn-api! I agree that high-level abstractions would be beneficial for improving DX, especially for the most common tasks like authentication.

I would like to suggest that we maintain the focus of psn-api as a collection of low-level utilities that excel at doing one thing and one thing only. This approach has proven to be quite advantageous in the past, as it allows consumers to compose functionality with the utilities we provide, rather than relying on abstractions that may be more prone to breaking when Sony inevitably makes changes to their API. Such breakages have unfortunately occurred multiple times in psn-api's history, often without warning. I anticipate it will keep happening, and I anticipate the current code for every function in the library today has an expiration date where it'll just randomly stop working until myself or someone else gets frustrated enough to reverse engineer the mobile app again.

My ultimate vision was one day someone would come along and create abstractions on top of psn-api as a separate library altogether. To my knowledge, this vision has yet to be realized.

That being said, I do agree that there is room for improvement in certain areas, such as authentication (or any of the most common identified use cases). Therefore, I propose we create abstractions for these most common and pressing operations that users tend to perform, while still prioritizing the use of utility-first design wherever possible.

The Python library uses an approach that I think would also benefit us a lot, which is the ability to chain commands one after the other with the Builder Design Pattern. A design pattern like that would probably fit our use case as well.

Regarding the builder pattern, I am intrigued. Could you please provide some pseudocode examples of how it might be used with the context of the library? I'm interested in exploring this further.

Your contributions and insight here are valued and appreciated. Overall, I think we should prioritize the balance between providing high-level abstractions and maintaining a low-level utility-first approach that has served the library well so far. Thank you for your continued stream of ideas!