Perform a software evaluation

Thanks for staring this issue @D34dMan. Here are some quick thoughts on the topics above that I have opinions on.

Target Platform / Execution Environment support.
- For 1.0 I think we should target Node.js and Web (basically Server and Client js).
- Longer term I think it would be interesting to look at supporting emerging edge runtimes.

Source Code:
- I think we should write this in TypeScript - I think offering a great set of types for use could be a big feature of this library and I think we'll do a better job of that if we're always thinking in TS. We'd bundle to JS so users of the package could use either TS or regular JS.
- Possibly worth considering - I've seen a bit of a trend of libraries using JSDoc to define types rather than actually writing in TS. Something like: https://dev.to/thepassle/using-typescript-without-compilation-3ko4. Still lean on the side of actually writing in TS though.

Compiler / Transpiler:
* My recommendation here would be to use Vite (https://vitejs.dev/) which supports things like TypeScript out of the box.

Authentication Support
- This feels like a slightly different topic - I think we should create another issue to discuss in detail.

Developer Tooling
- I think we should set this project up as a monorepo - a single codebase for what will be published as multiple packages.
- Standardizing on a package manager - on projects at Pantheon we've had a great experience using pnpm, specifically with it's monorepo/workspaces related features.
- Changesets - similarly have found Changesets (https://github.com/changesets/changesets) very useful, but specifically have been using it with Github Actions. Not sure if hosting our source on Gitlab will change the story there.

I'm sure I forgot some things - will chime in later if so.

TypeScript vs JavaScript with JSDocs for Types

TypeScript has loads of benefits which can outweigh some shortcomings or dis-pleasures I encounter now and then :P.

E.g., for supporting web and server from same codebase, we need often need to load correct method/library based on platform on which the code is being executed. Such support needs dynamic typing, which is quite complex to achieve in TypeScript. Example, using native fetch if available when in web environment, vs some library. Same goes for localStorage and other platform specific quirks.

I have not tried JavaScript with JSDocs for types, but looks like it would help me at least not bother about such un-necessary work-arounds when we need dynamic Typing.

---

For Authentication Support, created this issue for following it up https://www.drupal.org/project/api_client/issues/3365476 →

I'm really excited about this!

I have not tried JavaScript with JSDocs for types, but looks like it would help me at least not bother about such un-necessary work-arounds when we need dynamic Typing.

TypeScript and JSDoc types should both be able to handle this dynamic typing. That being said, I would lean towards TypeScript over JSDoc typings for this project. We should use both (or TSDoc) to ensure code is documented in editor and available for API reference generation.

Here are some of my picks:

- code written in TypeScript with detailed TSDoc comments
- tsc for typechecking
- tsup or esbuild for bundling. tsup uses esbuild + rollup under the hood similar to vite, but in my experience it handles a few things better like treeshaking.
- vitest + cypress or playwright for tests. If we only have unit tests I suggest vitest only.
- pnpm and pnpm workspaces for the monorepo setup
- lint-staged + husky for git hooks - or lint+format in CI

Took a pass at updating some of the things that we seem to have early consensus on, or are leaning in the direction of.

Coding standards seems to be the thing with the least consensus. I don't think the existing Drupal JS standards give us what we need, but not sure where that leaves us.

Is it worth creating an issue on Drupal core to update the JS coding standards?

> Is it worth creating an issue on Drupal core to update the JS coding standards?

Long term, I think yes. But I also think it would be most effective if we created the issue with some pre-existing opinion.

Also, should this be a discussion about modifications to the existing Drupal coding standards (things that apply to core) or a new set of coding standards for JS projects that aren't a direct dependency of Drupal core itself? My guess is the latter.

I don't think we should limit ourselves to the core standards, by any means, but I do think we should keep them in mind when defining them for the API client. I think it would be cool/helpful if they eventually became one and the same standard, but only if our new API standard is compatible with and an "upgrade" to the core standard.

Seems like we are somewhat set for the toolchain we want to use, so it seems like a good time to ask: Should we use Deno?

Should we use Deno?

Deno is "edge first" and the APIs are all browser compatible, so it would check those two platform boxes. Recently(?) deno released denoland/dnt which lets you easily publish your Deno module to `npm` for use in Node.js projects. Does the increased interop between Deno and Node give us a good reason to write this in Deno first?

pros

I think all or at least most of the features listed here are pros of Deno compared to Node.js: Deno features

Also
- Supports edge runtime
- Supports publishing the code to npm via `denoland/dnt`
- build in doc generator
- `deno vendor` allows fetching remote dependencies to a `vendor` dir that can be committed with the code, and a flag can be set to only run a program with those deps.

cons

- It's not node – some things may work slightly differently in Deno than we are used to
- It is opinionated – might be an upside?
- It's new so there is less info about it compared to node
- no native workspace support, might need some hacks for the "monorepo" things we get with pnpm workspaces. `nx` could work as a monorepo solution for deno. (Honestly, with the way deno does modules and import maps, no native monorepo/workspace support is not that bad).

Summary

So if we pick Deno, we don't have to worry about picking or configuring these things as they are included in Deno itself:
- linter/formatter
- TypeScript
- API reference generation/typedoc
- test runner
- most of the dev tooling

In addition, we could write the package to support the browser/edge first and build that output to support node via the `denoland/dnt` module.

Just wanted to throw out this option, what do ya'll think?

Thanks for researching this @coby.sher!

My two-ish cents:

Strong pre-configured opinions on tooling make this tempting, as does setting ourselves up for an edge compatible version in the future. That said, I think I lean in the direction of 'regular' node primarily due to:

- It's not node – some things may work slightly differently in Deno than we are used to
- It's new so there is less info about it compared to node

Based on your POC it seems like a pretty direct port from our perspective from node to deno, but I worry about it being a point of confusion for contributors who may have some limited amount of node experience but have never heard of Deno. I also worry about it being a possible point of contention when we share this work with the Drupal JS maintainers.

Happy for related discussion to continue, or any of these decisions to evolve during implementation, but we've fleshed this out enough that we were able to scaffold the initial project. Marking as fixed.

Automatically closed - issue fixed for 2 weeks with no activity.