Opt-in JIT-compiled formatter for the read path - reduce item formatting by 98%

[anatolzak]

Closes #585

What

Adds an opt-in, JIT-compiled document formatter for the read path (get / query / scan / parse). Instead of re-walking the schema for every item through the interpreted formatter, ElectroDB compiles a formatter specialized to a single entity's schema once, at Entity construction, and reuses it. Output is byte-for-byte identical; only the per-item formatting cost changes.

Design & safety

• Opt-in, off by default. Enable per entity with new Entity(schema, { table, client, compile: true }), or globally via the ELECTRODB_COMPILE env var.
• Graceful fallback. If compilation isn't possible or fails, ElectroDB silently falls back to the interpreted formatter — same behavior as today. The only exception is ELECTRODB_COMPILE=on, which forces compilation and throws CompilationFailed where runtime codegen is unavailable (e.g. strict CSP, new Function blocked).
• Skips schemas with user getters. Custom getters run arbitrary code, so any schema with a user-defined getter is never compiled and stays on the interpreted path.

Correctness

ELECTRODB_COMPILE=verify runs every read through both the compiled and interpreted paths and throws on any divergence. The full suite now runs under verify mode by default (npm run test:unit:verify, wired into test:run), so both paths are exercised on every CI run in a single pass.

The generated function body is snapshotted in test/snapshots/compile/*.txt so codegen changes surface as a reviewable diff:

• npm run test:snapshots — verify the generated source hasn't drifted from the committed snapshots.
• npm run test:snapshots:update — regenerate the snapshots (review the diff to confirm the change makes sense, then commit).

[netlify]

✅ Deploy Preview for electrodb-dev canceled.

Name	Link
🔨 Latest commit	73fd0cc
🔍 Latest deploy log	https://app.netlify.com/projects/electrodb-dev/deploys/6a782bf60ec6a50008037269

[anatolzak]

hey @tywalch 👋!

finally got to work on the JIT optimization I shared with you a while ago. to give you an idea of the improvement, I have an API route, which takes in total under a second, that processes a lot of items, and I measured the total time spent in formatResponse across that one request at ~175ms. this PR cuts that by about ~95%, so in my case formatting drops from 175ms to single-digit ms.

there's still more on the table. right now the doc client unmarshalls the raw DynamoDB response, which is also quite slow because it's megamorphic, and then ElectroDB walks the result again to format it. we can fold the unmarshalling into the JIT formatter so it will be monomorphic. in my benchmarks that unmarshall pass costs as much as ~50% of ElectroDB's normal formatting (in the same route, 88ms unmarshalling on top of the 175ms format). I manually tested a fused unmarshall + JIT formatter and it's also about ~95% faster.

so combined, that's ~263ms of unmarshall+format CPU per request on this route today.

I will try to work on the unmarshall stuff at some point, but even this PR should already provide much relief and reduce the cpu work done in the formatter.

one nice thing about this PR is that the whole test suite now runs with ELECTRODB_COMPILE=verify, which runs every read through both the JIT-compiled formatter and the default interpreted one and throws if their output ever diverges. so the two paths are checked against each other on every test. I also ran my private repo's full test suite against these changes with the verify flag on, and everything passed

thanks in advance for taking the time to review this 🙏