graphddb 0.6.0 → 0.7.0

package/docs/prepared-statements.md

@@ -0,0 +1,165 @@
+# GraphDDB Prepared Statements
+
+`DDBModel.prepare($ => ({...}))` → `.execute(params)` is the read/write-unified
+**prepared statement**: a declarative route body is compiled **once**, and each
+`execute(params)` binds the per-call values into the precompiled plan and runs
+it through the **same execution cores** `DDBModel.mutate` / `Model.query` /
+`Model.list` and the public CQRS contracts use — effects are identical by
+construction (design #203, runtime #205, compile-time transform #206).
+
+## The three execution layers (orthogonal, pick per use)
+
+| Use | API |
+|---|---|
+| ad-hoc one-shot | `DDBModel.mutate({...})` / `Model.query(...)` / `Model.list(...)` — recompiles per call |
+| repeated hot path (prepared statement) | `DDBModel.prepare($ => ({...}))` → `.execute(params)` |
+| public CQRS contract | `publicCommandModel({...})` / `publicQueryModel({...})` |
+
+`prepare` is the missing middle: **precompiled without the contract ceremony**.
+
+```ts
+// write
+const createPost = DDBModel.prepare(($) => ({
+  post: { create: () => Post, key: { threadId: $.threadId, postId: $.postId }, input: { body: $.body } },
+}));
+await createPost.execute({ threadId, postId, body });
+
+// read — symmetric; only the key values (+ limit/cursor/consistentRead) are dynamic
+const userById = DDBModel.prepare(($) => ({
+  user: { query: () => User, key: { userId: $.userId }, select: { userId: true, name: true } },
+}));
+await userById.execute({ userId });
+```
+
+## The key constraint: no runtime capture
+
+A prepared body must be **pure-declarative**: it may reference only
+
+- `$.<name>` — per-call values, bound at `execute`;
+- **module-static** references — imports, module-scope `const` / `class` /
+  `enum`, the `() => Model` model refs, shared `const` select templates;
+- static literals (string / number / boolean / bigint / `null`).
+
+Capturing a per-call runtime value into the body — an enclosing function's
+parameter or `let`, `p.foo`, `this`, mutable module state, any helper **call**
+(the indirect-capture channel; even `Date.now()` is a fresh per-call value) —
+breaks preparability and is rejected **loudly**:
+
+- **at build time** by the static lint (`graphddb transform prepared`, below) —
+  the primary, phase-2 enforcement, including indirect capture via same-file
+  helper constants (transitively verified);
+- **at runtime** by the phase-1 guard (`assertNoRuntimeCapture` and the
+  recording `$` proxy) as a backstop for what a per-file syntactic pass cannot
+  see (cross-module mutable state, mutated template objects).
+
+## Zero overhead vs. fallback: the compile-time transform
+
+**With the transform applied, prepared statements are zero-overhead per
+operation regardless of where you write them. Without it, they still behave
+identically — they just pay a small per-call memoization cost.** That is the
+whole contract:
+
+| Build | Per-op cost of an inline `prepare(fn).execute()` | Result |
+|---|---|---|
+| **transform applied** (`graphddb transform prepared --write`) | **zero** planning / compiling / structure hashing — the call site is normalized to a module-scope prepared slot; after the first call it is a nullish check + `.execute` | identical |
+| **no transform** (fallback) | phase-1 **structural memoization**: the body is re-evaluated and structure-hashed per call, then the compiled handle is reused from a bounded LRU (no recompile) | identical |
+| hand-hoisted module-level `const stmt = DDBModel.prepare(...)` | zero (already optimal; the transform leaves it untouched) | identical |
+
+The transform exists to remove the placement footgun: without it, an inline
+`prepare` is *correct but warmer* than a module-level one (silent-slow). With
+it, both spellings compile to the same optimal form.
+
+### CLI
+
+```bash
+# build lint (CI gate): verify no-runtime-capture, report hoistable inline
+# call sites as notes; exit 1 on violations
+graphddb transform prepared --src src/
+
+# apply: rewrite verified inline call sites in place (idempotent)
+graphddb transform prepared --src src/ --write
+```
+
+The rewrite normalizes each inline call site to a module-scope **lazy slot**:
+
+```ts
+// before (inline, per-call structural memoization)
+export async function getUser(userId: string) {
+  return DDBModel.prepare(($) => ({
+    u: { query: () => User, key: { userId: $.userId }, select: USER_SELECT },
+  })).execute({ userId });
+}
+
+// after `graphddb transform prepared --write`
+let __gddbPrepared1;
+export async function getUser(userId: string) {
+  return (__gddbPrepared1 ??= DDBModel.prepare(($) => ({
+    u: { query: () => User, key: { userId: $.userId }, select: USER_SELECT },
+  }))).execute({ userId });
+}
+```
+
+The body stays lexically in place (every reference resolves exactly as
+before — no TDZ / module-init-order hazards with models declared later in the
+file), the plan compiles once per module at first use, and every later call is
+a single nullish check straight into `.execute`. Files containing any
+violation are **never rewritten** — the build fails loudly instead.
+
+A file is scanned when it contains a `DDBModel.prepare` call site; detection
+follows import aliases (`import { DDBModel as M }`), namespace imports
+(`g.DDBModel`), module-const aliases, and same-file `extends DDBModel`
+subclasses. Call sites already evaluated once per module load (module-scope
+`const`, static class fields) are left as-is.
+
+### Programmatic API
+
+```ts
+import { transformPreparedSource, lintPreparedSource } from 'graphddb/transform';
+
+const result = transformPreparedSource(fileName, sourceText); // { text, changed, diagnostics, ... }
+const diagnostics = lintPreparedSource(fileName, sourceText); // check-only (the build gate)
+```
+
+Build-time only (requires the optional `typescript` dependency, like the JSDoc
+codegen pass); wire it into a bundler plugin or a pre-build step if you prefer
+that over the CLI.
+
+### What the static lint proves — and its limits
+
+The lint accepts only the declarative grammar the runtime itself accepts
+(object/array literals, static literals, `$.<name>`, module-static reference
+chains, `() => Model` thunks), applied **transitively** through same-file
+module-const templates. It therefore rejects, per-file and soundly: direct
+captures (enclosing-scope bindings, `this`), indirect captures via **any** call
+or `new`, mutable module state (`let` / `var`), unresolved globals, per-call
+control flow (conditionals, computed keys, substitution templates), and bodies
+it cannot statically see.
+
+Per-file syntactic analysis cannot prove two things: an **imported** binding is
+accepted as module-static (that is the design's allowance for `() => Model`
+refs — a pathological mutable re-export is invisible), and mutation of a
+same-file `const` **object** between calls. Both are backstopped by the
+phase-1 runtime guard (only `$`-refs and scalar static literals are bindable
+value leaves) and by the fallback's correctness: an undetected unhoistable
+site is never wrong, only warmer.
+
+Detection also does **not check the import's module specifier**: a binding
+imported as `DDBModel` from **any** package (`import { DDBModel } from
+'<other-package>'`) matches, so another library's same-named `DDBModel.prepare`
+call site is transformed / linted too (a false transform or a spurious lint
+error is possible). Take care in files that mix graphddb with a same-named
+foreign API.
+
+## Semantics (both layers, guaranteed identical)
+
+- **write** — the params-independent op template compiles once
+  (`compileWriteFragment`); `execute` runs the identical core the envelope and
+  `publicCommandModel` use: derived maintainers and atomic
+  `TransactWriteItems` semantics match exactly. Multi-alias bodies compose one
+  atomic transaction (`mode: 'parallel'` opts out per call).
+- **read** — the params-independent products (resolved model, normalized
+  select, validated relation structure) compute once; `execute` binds key
+  values + per-call pagination/consistency and runs `executeQuery` /
+  `executeList` exactly like `Model.query` / `Model.list`.
+- A body is all-read or all-write; an option the target core would ignore is a
+  loud compile-time reject (never a silent drop).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphddb",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Graph data modeling on DynamoDB with adjacency list pattern",
   "type": "module",
   "main": "dist/index.js",
@@ -29,6 +29,10 @@
     "./cdc": {
       "types": "./dist/cdc/index.d.ts",
       "import": "./dist/cdc/index.js"
+    },
+    "./transform": {
+      "types": "./dist/transform/index.d.ts",
+      "import": "./dist/transform/index.js"
     }
   },
   "bin": {