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

CHANGELOG.md

@@ -679,4 +679,8 @@ All notable changes to this project will be documented in this file. Breaking ch
 
 ## [3.9.2]
 ### Fixed
-- [Issue #578](https://github.com/tywalch/electrodb/issues/578); Watchers no longer do unnecessary work for methods they don't define: a watcher only runs on `get` if it has a getter, and on `set` if it has a setter. This also fixes a setter-only `watch` attribute (e.g. an `updatedAt` timestamp) being returned as `undefined` on reads when absent from the item.
+- [Issue #578](https://github.com/tywalch/electrodb/issues/578); Watchers no longer do unnecessary work for methods they don't define: a watcher only runs on `get` if it has a getter, and on `set` if it has a setter. This also fixes a setter-only `watch` attribute (e.g. an `updatedAt` timestamp) being returned as `undefined` on reads when absent from the item.
+
+## [3.10.0]
+### Added
+- [Issue #585] Opt-in JIT compilation of the item format path. When enabled, ElectroDB compiles a per-schema formatter that replaces the interpreted formatter used to shape `get`/`query`/`scan`/`parse` responses, reducing per-item overhead on reads. Enable per-entity with `{ compile: true }`, or control it globally with the `ELECTRODB_COMPILE` environment variable: `on` forces compilation (and throws where runtime code generation is unavailable), `off` disables it, and `verify` runs both the compiled and interpreted paths on every read and throws if their output diverges. Compilation is skipped automatically for schemas with user-defined getters and falls back to the interpreted path in environments without `new Function` (e.g. a strict CSP), so behavior is unchanged when it is off or unavailable.

index.d.ts

@@ -5490,6 +5490,8 @@ export type EntityConfiguration = {
     version?: string;
   };
   ignoreOwnership?: boolean;
+  /** JIT-compile the read-path formatter (default false); env ELECTRODB_COMPILE=off|on|verify overrides */
+  compile?: boolean;
 };
 
 export class Entity<
@@ -6097,6 +6099,8 @@ export type ServiceConfiguration = {
   client?: DocumentClient;
   listeners?: Array<ElectroEventListener>;
   logger?: ElectroEventListener;
+  /** JIT-compile member entities joined as raw models (no-op for pre-built Entity instances) */
+  compile?: boolean;
 };
 
 declare function createWriteTransaction<

package.json

@@ -1,17 +1,20 @@
 {
   "name": "electrodb",
-  "version": "3.9.2",
+  "version": "3.10.0",
   "description": "A library to more easily create and interact with multiple entities and heretical relationships in dynamodb",
   "main": "index.js",
   "scripts": {
     "build": "sh buildbrowser.sh",
     "build:browser": "browserify playground/browser.js -o playground/bundle.js",
     "test": "./test.sh",
     "test:ci": "npm install && npm test",
-    "test:run": "npm run test:types && npm run test:init && npm run test:unit",
+    "test:run": "npm run test:types && npm run test:init && npm run test:unit:verify",
     "test:init": "node ./test/init.js",
     "test:init:hard": "node ./test/init.js --recreate",
     "test:unit": "mocha -r ts-node/register ./test/**.spec.*",
+    "test:unit:verify": "ELECTRODB_COMPILE=verify mocha -r ts-node/register ./test/**.spec.*",
+    "test:snapshots": "mocha -r ts-node/register test/offline.compile.spec.js",
+    "test:snapshots:update": "UPDATE_SNAPSHOTS=1 mocha -r ts-node/register test/offline.compile.spec.js",
     "test:types": "tsd",
     "test:format": "prettier -c src/**/*.js examples/**/*",
     "coverage": "npm run test:init:hard && nyc npm run test:unit && nyc report --reporter=text-lcov | coveralls",

src/entity.js

@@ -37,6 +37,7 @@ const { FilterOperations, ExpressionState, formatExpressionName } = require("./o
 const { WhereFactory } = require("./where");
 const { clauses, ChainState } = require("./clauses");
 const { EventManager } = require("./events");
+const { resolveCompileOptions } = require("./format");
 const validations = require("./validations");
 const c = require("./client");
 const u = require("./util");
@@ -60,6 +61,10 @@ class Entity {
     this._validateModel(model);
     this.version = EntityVersions.v1;
     this.model = this._parseModel(model, this.config);
+    const compileOptions = resolveCompileOptions(this.config.compile);
+    if (compileOptions !== null) {
+      this.model.schema.compileRetrievalFormatters(compileOptions);
+    }
     /** start beta/v1 condition **/
     this.config.table = config.table || model.table;
     /** end beta/v1 condition **/
@@ -1076,10 +1081,9 @@ class Entity {
     if (item === undefined || item === null) {
       return null;
     }
-    const config = {
-      ignoreOwnership: true,
-      ...(options || {}),
-    };
+    const config = this._normalizeExecutionOptions({
+      provided: [{ ignoreOwnership: true }, options || {}],
+    });
     return this.formatResponse(item, TableIndex, config);
   }
 
@@ -1754,7 +1758,7 @@ class Entity {
       }
     }
 
-    return provided.filter(Boolean).reduce((config, option) => {
+    const normalized = provided.filter(Boolean).reduce((config, option) => {
       if (typeof option.order === "string") {
         switch (option.order.toLowerCase()) {
           case "asc":
@@ -2033,6 +2037,12 @@ class Entity {
       config.params = Object.assign({}, config.params, option.params);
       return config;
     }, config);
+
+    const returnAttributes = new Set(normalized.attributes);
+    normalized._returnAttributesFilter =
+      returnAttributes.size > 0 ? returnAttributes : null;
+
+    return normalized;
   }
 
   _applyParameterOptions({ params = {}, options = {} } = {}) {

src/errors.js

@@ -169,6 +169,12 @@ const ErrorCodes = {
     name: "InvalidIndexDefinition",
     sym: ErrorCode,
   },
+  CompilationFailed: {
+    code: 1027,
+    section: "compilation-failed",
+    name: "CompilationFailed",
+    sym: ErrorCode,
+  },
   MissingAttribute: {
     code: 2001,
     section: "missing-attribute",