Core rewrite for v0.2.0 (and v1.0.0)

[doseofted]

The current v0.1.0 version of Prim+RPC is a low-level RPC library for JavaScript/TypeScript with a lot of features, a lot of integrations, and fairly extensive documentation. There are many other features that I would like to add to Prim+RPC that the current structure of the code wouldn't allow, without a rewrite. This is that rewrite.

It started as a refactor of existing functionalities but the code needs to broken down into its most basic functionalities to build out these new features. The goals of the next version v0.2.0 (to be followed with v1.0.0) are:

Library rewrite

• Break down the core library into reusable utilities (so you could theoretically "build-your-own-RPC")
  • The new version will be built upon these utilities
• Write tests for every reusable utility, integration, and the core library
  • The new library will be incredibly flexible so this is critical
• Make core library less specific to the communication channel
  • The previous version used "method" handlers (request/response), callback handlers (server push) to handle RPC
  • While these handlers were generic, they were built around limitations of HTTP and WS
  • In the next version, a single handler should be used for each supported channel
  • When a feature is unsupported on a channel, an error can be thrown (to be caught by the next provided handler)
  • A list of "fallback" handlers may be used if one handler doesn't support a feature but another provided handler does
• Improve IPC support and integrations
  • The integrations for Workers should be improved
  • Add support for Electron (two-way support for main/renderer via preload script)
• Provide better support for sanitization
  • The previous version of the library allowed for RPC to be validated by other libraries through generic hooks
  • While this worked as intended, support for "Standard Schema" directly may be more straight forward
  • Previous hooks will still be supported to use any validation library
• Add ability to stream data between server/client (full duplex, where supported by handler)
  • Generator functions and iterators will now be streamed between server and/or client
  • Streams of data (Streams API) will become a new argument and return type
  • Promises inside of a returned value or given argument will become streamed
  • Integrations will either provide support for streaming or provide relevant errors if channel doesn't support a feature
  • The library will try to close abandoned streams where possible, to ensure server-side resources are freed
• Add support for chaining and currying function calls
  • With streaming support, this now becomes possible
  • The core rewrite will restructure the returned proxy to make chaining possible
• Provide compatibility layer for v0.1.0
  • All existing features and integrations should continue to work
  • New features (like streaming/chaining/currying) will require migration to new version
  • This will likely be a "compatibility" export for v0.1.0 built upon v0.2.0
  • While v0.2.0 is in development, updates should be made to v0.1.0 to support latest versions of integrations
• Consider inline RPC compilation with build plugin (this may be moved to v0.3.0 depending on complexity)
  • The previous attempt (unpublished) used Babel for transforms but this became too complex
  • The new transform could be written with GritQL
  • Run-time RPC will still be prioritized, compile-time will only be additional feature
  • At a minimum, the plugin should prevent builds when server-side RPC is detected client-side (a feature today)
• Drop experimental features
  • Generated RPC documentation was an additional utility with limited functionality, rely instead on "Standard Schema"
  • The "Prevent Build" plugin will be removed, instead will favor compilation plugin that will include feature

Documentation changes

• Rewrite documentation website to be simpler to maintain
  • Consider a docs generator, like Starlight (Astro) or Nuxt Content (once Nuxt UI Pro becomes open-source)
  • Drop StackBlitz example, replace with CodeSandbox
  • Fix performance of "dancing lights" effect or replace with similar effect
  • Fix navigation issue where lights disappear slowly and then suddenly reappear
  • Remove scroll effects (fun for marketing, annoying for technical documentation)
• Rewrite documentation for updated v0.2.0
  • Original documentation was fairly wordy, could be dramatically simpler
  • Guide with examples first, then explain as necessary
  • Remove any "marketing speak" from technical documentation
  • Favor succinct documentation and get to the point
  • Include a link back to v0.1.0 documentation, to be maintained in separate branch