Notes from project refactor

[Greenheart]

Maybe write up as a blog post.

• Refactoring the library to package and make it easier to install in other projects
• Adding better documentation for how to get started.
• Refactoring the package from TS to JSDoc to work around limitations with dynamic imports and worker modules. The file paths didn't get transformed from worker.ts into worker.js on build, but the code was transpiled, making the import fail during runtime because it was still trying to import the nonexistent worker.ts.
  • To make this transition, I first used ts-to-jsdoc to get a rough baseline. However, it was using an older version of ts-morph not yet updated to the latest TS version this project is using, so the output was a good start but not perfect.
  • So I manually edited the output to fix type errors and improve the code.
  • This process helped me improve my understanding of how to use JSDoc types to get most of the benefits of TypeScript and generated d.ts declaration files while still allowing the code to be executed directly. In particular, the @template syntax and default type arguments were a great solution to implement one of the generic type arguments.
  • Also found out that arrow functions don't get JSDoc comments preserved in the generated output. At least with my particular build setup using @sveltejs/package. To preserve the JSDoc comments for exported functions in the public API, make sure they are all defined with the function keyword.
  • One tiny detail I found quite tricky was the fact that JSDoc @typedefs get included as part of the public API of a module when generating type definition files. I was looking for a JSDoc tag that could help make it private, reading and experimenting with both jsdoc.app and the TypeScript JSDoc supported types. I finally found a solution by moving the @typedef into a private module, and then importing it. It's a hack, but I'll take it because it's not too bad for this case.
  • Overall, JSDoc can be a good fit for small utility libraries. Especially if you need dynamic imports for workers and similar cases where TypeScript seemingly don't change the .ts extension into .js. However, I wouldn't use this for larger libraries since the TS syntax is much easier to work with than JSDoc.
• Maybe also write something about dealing with the issues from Keystatic loopback redirect. Documented the workaround for now, until my upstream PR has been merged.
• Last but not least, there were also significant improvements to the documentation for how to use the project.
• Releasing as a public npm package to make integration in other projects easy.