Coincident v4

[WebReflection]

You are probably thinking something like "... but mate, you just came out with v3 a couple of months ago ... another rewrite?"

Yes because v3 was still not clean and "nightmarish" to maintain:

• too many encoder and decoder ... having flatted, structured-clone, buffered and/or json meant maintaining 4 versions for no real winner, just a mix and match and use and maybe debug all scenarios where any of those could've failed: this is "hell" for me and I've squashed all the best things from each approach into reflected-ffi/direct/encoder and its decoder utilities which are always fast, work with buffers, shared or not, but also arrays, and use always the fastest/easiest compromise that ensure correctness and it's 100% test covered. encoder and decoder are still part of the options though but the default is not JSON anymore, it's something that can travel at native speed as buffer in both postMessage and/or WebSocket messages and it's still as fast as it can get in most common cases. A buffer extra option has been added to also pass buffers as these are and avoid bloat and conversion of typed views which was crucial to unlock some use case.
• the proxy bit was a project a part very hard to test in isolation due its presence behind the coincident API/options scene ... the reflected-ffi project is instead 100% code covered via both NodeJS (or bun) and manually tested on browsers so that it's easier to maintain, validate, improve and whatnot. This also split responsibilities because in here there's just the orchestration of how, when and where, roundtrips are performed, so that the whole story about FFI, GC, Reflect and Proxy utilities and behaviors are confined into a project which goal is just one: provide the fastest and best way to have a remote FFI implemented in workers to drive either the main thread or the server one
• isolating the FFI side of affairs allowed me to both get rid of all 3rd party dependency, focus on ever single ad-hoc case, bring in tons of performance improvements and all still with the ease of code-coverage without needing actual workers or complex, socket based, scenarios to be able to replicate and solve issues

Long story short, this module is now way more essential, the reflected-ffi has zero dependencies so that it can keep pace with ease and it doesn't even need to be bundled (which is always suggested, still ...) so that it can be tested in isolation out of the box without needing import maps or other things.

New in v4

• the returned namespace has been enriched with an ffi field that contains:
  • ffi.assign to assign multiple values at once (single roundtrip)
  • ffi.gather to retrieve multiple references at once (single roundtrip)
  • ffi.evaluate to run the body of a function elsewhere and return whatever is needed to be returned at once (still single roundtrip)
  • ffi.query to crawl paths all at once, as in document.body.children[2].outerHTML (single roundtrip)
• the default encoder now supports recursion and complex data out of the box, returning a flat uint8 like based array that can be passed as view, or its buffer, and parsed back the same way. All references and strings are parsed/stored once recursively to speed up homogeneous collections (db results, as example), common strings, or preserve references in the most correct/accurate way, reducing when possible the amount of GC operations
• the architecture has been described to help understanding how the reflected FFI works and coincident is the one orchestrating postMessage and WebSockets synchronous and asynchronous dances, nothing else

Breaking in v4

All encoders and decoders, all dependencies that are not used/needed, and the whole proxy folder has been removed, making the package.json easier to reason about and follow but if you were reaching out this module to use any of those dependencies these are not available anymore but of course, v3 still offer those and encoder or decoder are still compatible with this API so you can eventually port previous code to work with this latest version of the library.