graphddb 0.5.2 → 0.5.3

package/dist/testing/index.js

@@ -1,13 +1,14 @@
 import {
   createCdcEmulator
-} from "../chunk-QBXLQNXY.js";
+} from "../chunk-M6URQOAW.js";
 import {
   ClientManager,
   MetadataRegistry,
-  TableMapping,
   resolveModelClass
-} from "../chunk-W3GEJPPV.js";
-import "../chunk-MCKGQKYU.js";
+} from "../chunk-CCIVET5K.js";
+import {
+  TableMapping
+} from "../chunk-PDUVTYC5.js";
 
 // src/memory/memory-store.ts
 function deepClone(value) {

package/docs/doc-sample.md

@@ -0,0 +1,263 @@
+# UserPermissions Table Specification
+
+> Generated by `graphddb generate docs`
+
+---
+
+## Table Overview
+
+| Item | Value |
+|------|-------|
+| Table | `UserPermissions` |
+| Description | User / Group / Permission Management |
+| Billing Mode | PAY_PER_REQUEST |
+| Streams | NEW_AND_OLD_IMAGES |
+| TTL | Disabled |
+| PITR | Enabled |
+| Table Class | STANDARD |
+| Encryption | AWS Managed SSE |
+| CloudFormation | `cloudformation.yaml` |
+
+---
+
+## Entity Relationship Diagram
+
+```mermaid
+graph TD
+  User -->|hasMany| Membership
+  Membership -->|belongsTo| Group
+  User -->|hasMany| Permission
+```
+
+---
+
+## Physical Key Schema
+
+| Model | PK | SK | GSI1 PK | GSI1 SK |
+|------|------|------|------|------|
+| User | `USER#{userId}` | `PROFILE` | `EMAIL#{email}` | `USER#{userId}` |
+| Group | `GROUP#{groupId}` | `PROFILE` | | |
+| Membership | `GROUP#{groupId}` | `USER#{userId}` | `USER#{userId}` | `GROUP#{groupId}` |
+| Permission | `USER#{userId}` | `PERMISSION#{permission}` | | |
+
+---
+
+## Property Matrix
+
+| Property | Type | Description | User | Group | Membership | Permission |
+|----------|------|-------------|------|------|------|------|
+| userId | string | User ID | PK | | GSI1 PK | PK |
+| groupId | string | Group ID | | PK | PK | |
+| permission | string | Permission Name | | | | SK |
+| email | string | Login Email | GSI1 PK | | | |
+| name | string | Display Name | ✓ | ✓ | | |
+| role | string | Group Role | | | ✓ | |
+| createdAt | datetime | Created Time | ✓ | ✓ | ✓ | ✓ |
+
+Legend: **PK** primary partition key · **SK** primary sort key · **GSI1 PK/SK** GSI1 keys · **✓** normal attribute
+
+---
+
+## Entity Details
+
+### User
+
+- **Key**: `PK = USER#{userId}` / `SK = PROFILE`
+- **GSI1**: `PK = EMAIL#{email}` / `SK = USER#{userId}`
+- **Relations**: `groups` → Membership → Group (hasMany), `permissions` → Permission (hasMany)
+
+| Field | Type | Description |
+|------|------|------|
+| userId | string | User ID |
+| email | string | Login Email |
+| name | string | Display Name |
+| createdAt | datetime | Created Time |
+
+### Group
+
+- **Key**: `PK = GROUP#{groupId}` / `SK = PROFILE`
+- **Maintained**: `memberCount` (counter), `groupSnapshots` on User (embedded snapshot)
+
+| Field | Type | Description |
+|------|------|------|
+| groupId | string | Group ID |
+| name | string | Display Name |
+| createdAt | datetime | Created Time |
+
+### Membership
+
+- **Key**: `PK = GROUP#{groupId}` / `SK = USER#{userId}`
+- **GSI1**: `PK = USER#{userId}` / `SK = GROUP#{groupId}`
+
+| Field | Type | Description |
+|------|------|------|
+| groupId | string | Group ID |
+| userId | string | User ID |
+| role | string | Group Role |
+| createdAt | datetime | Created Time |
+
+### Permission
+
+- **Key**: `PK = USER#{userId}` / `SK = PERMISSION#{permission}`
+
+| Field | Type | Description |
+|------|------|------|
+| userId | string | User ID |
+| permission | string | Permission Name |
+| createdAt | datetime | Created Time |
+
+---
+
+## Access Patterns
+
+Each query resolves to a physical operation, an index (PK or GSI), and a projection.
+The matrix summarizes; the contracts below give the input/output and execution for each.
+
+| Query | Index | Relation | BatchGet | Cursor |
+|------|------|------|------|------|
+| `User.query(userId)` | PK | | | |
+| `User.queryByEmail(email)` | GSI1 | | | |
+| `User.groups(userId)` | PK | ✓ | ✓ | ✓ |
+| `Group.members(groupId)` | PK | ✓ | ✓ | ✓ |
+| `User.permissions(userId)` | PK | ✓ | | ✓ |
+
+### `User.query(userId)`
+
+Returns a single user by primary key.
+
+```yaml
+Input:  { userId: string }
+Output: User
+Resolve: PK = USER#{userId} → Query → Projection(name, email)
+```
+
+```mermaid
+flowchart LR
+  In["userId"] --> Key["PK = USER#{userId}"] --> Q["Query"] --> Out["User"]
+```
+
+### `User.queryByEmail(email)`
+
+Returns a single user by email (unique GSI).
+
+```yaml
+Input:  { email: string }
+Output: User
+Resolve: GSI1 PK = EMAIL#{email} → Query → Projection(userId, name)
+```
+
+```mermaid
+flowchart LR
+  In["email"] --> Key["GSI1 PK = EMAIL#{email}"] --> Q["Query"] --> Out["User"]
+```
+
+### `User.groups(userId)`
+
+Returns the groups a user belongs to (paged).
+
+```yaml
+Input:  { userId: string, limit?: number, cursor?: string }
+Output: Page<Group>
+Resolve: Query(User) → Query(Membership by PK) → BatchGet(Group)
+```
+
+```mermaid
+flowchart LR
+  User -- "PK" --> Membership -- "BatchGet" --> Group
+```
+
+### `Group.members(groupId)`
+
+Returns the members of a group (paged).
+
+```yaml
+Input:  { groupId: string, limit?: number, cursor?: string }
+Output: Page<User>
+Resolve: Query(Group) → Query(Membership by PK) → BatchGet(User)
+```
+
+```mermaid
+flowchart LR
+  Group -- "PK" --> Membership -- "BatchGet" --> User
+```
+
+---
+
+## Mutation Contracts
+
+### `User.update()`
+
+```yaml
+Input:  { userId: string, name?: string, email?: string }
+Output: User
+Resolve: TransactWrite → User item
+```
+
+### `Membership.create()`
+
+Creating a membership also maintains `Group.memberCount` in the same transaction.
+
+```yaml
+Input:  { groupId: string, userId: string, role: string }
+Output: Membership
+Resolve: TransactWrite → Membership item + Group.memberCount (ADD +1)
+```
+
+```mermaid
+flowchart LR
+  Create["Membership.create"] --> TW["TransactWrite"]
+  TW --> M["Membership"]
+  TW --> C["Group.memberCount (+1)"]
+```
+
+---
+
+## Maintained Access Paths
+
+Write-side projections kept in sync automatically, within the source write's transaction
+(or via the CDC stream for `updateMode: 'stream'`).
+
+| Source | Target | Pattern | Update |
+|---------|--------|--------|--------|
+| Membership | Group.memberCount | counter | ADD +1 / −1 on create / remove |
+| Group | User.groupSnapshots | embeddedSnapshot | project Group fields into User |
+
+```mermaid
+flowchart LR
+  Membership -- "create / remove" --> Counter["ADD ±1"] --> MC["Group.memberCount"]
+  Group -- "projection" --> Snap["Embedded Snapshot"] --> GS["User.groupSnapshots"]
+```
+
+---
+
+## CDC
+
+`@cdcProjected` models expose `fromChange` / `subscribe` to parse the change stream into
+typed records. Delivery and idempotency are the consumer's responsibility.
+
+```yaml
+Contract: User.subscribe
+Input:    ChangeEvent<User>
+Output:   [User | null, User | null]   # [oldRecord, newRecord]
+```
+
+```mermaid
+flowchart LR
+  Mutate --> Stream["DynamoDB Stream"] --> CE["ChangeEvent"]
+  CE --> FC["User.fromChange()"] --> Sub["subscribe()"] --> Consumer
+```
+
+---
+
+## CloudFormation
+
+Generated by `graphddb generate cloudformation` (see `cloudformation.yaml`).
+
+| Resource | Description |
+|------|------|
+| `AWS::DynamoDB::Table` | Physical table |
+| GlobalSecondaryIndexes | GSI definitions (GSI1 …) |
+| StreamSpecification | NEW_AND_OLD_IMAGES |
+| TimeToLiveSpecification | TTL (when a TTL attribute is declared) |
+| PointInTimeRecovery | PITR |
+| Auto Scaling | Optional (PROVISIONED mode) |

package/docs/docs-generation.md

@@ -0,0 +1,183 @@
+# GraphDDB — Docs generation
+
+`graphddb generate docs` renders a **human-facing model specification** —
+Markdown with embedded Mermaid diagrams — directly from your TypeScript models.
+It reads the same serializable manifest / operations the Python bridge and the
+CloudFormation generator use (it loads your entry model, builds the manifest and
+operation specs from the shared metadata registry, and renders the document), so
+the spec never drifts from the code: your models are the single source of truth.
+
+Output is **deterministic** — the same model set always produces the same
+document — and the layout is defined by **Handlebars** templates you can override
+per-section and extend with your own helpers.
+
+> This document is the reference for the shipped `generate docs` command: its
+> options, the sections it produces, and how to customize the templates.
+
+### Related specifications
+
+- [`spec.md`](./spec.md) — the core API: entities, structured keys / GSIs,
+  relations, queries.
+- [`cloudformation.md`](./cloudformation.md) — the sibling generator; the
+  `--billing-mode` / `--stream` flags are shared with it.
+- [`design-patterns.md`](./design-patterns.md) — maintained access paths and the
+  `updateMode: 'stream'` signal that drives `--stream auto`.
+
+## Overview
+
+```bash
+graphddb generate docs --entry models.ts --out doc.md
+```
+
+- **`--entry`** loads the TypeScript (or pre-compiled `.js`/`.mjs`) module that
+  registers your entity models as a side effect of import. TypeScript modules are
+  transpiled on demand via `tsx` (an optional peer dependency — install it with
+  `npm i -D tsx`).
+- **`--out`** accepts either a **file** or a **directory**. A path ending in
+  `.md` (e.g. `--out doc.md`) writes the single Markdown file at exactly that
+  path, creating parent directories as needed — this is the preferred usage.
+  Any other value is treated as a **directory** and the document is written as
+  `<dir>/index.md` (backward compatible). Either way the command prints a JSON
+  result (`{"status":"ok","outDir":…,"files":[…]}`) to stdout, where `files`
+  reports the written path(s).
+- **`--queries`** (optional) points at the module exporting your `queries` /
+  `commands` (the `defineQueries` / `defineCommands` maps). It powers the Access
+  Patterns and Mutation Contracts sections; omit it and those sections are empty.
+  Defaults to the entry module.
+
+To also document your access patterns and mutations:
+
+```bash
+graphddb generate docs --entry models.ts --queries definitions.ts --out docs/
+```
+
+## Output sections
+
+The generated `index.md` is composed, in this fixed order, from:
+
+| Section | Source | Contents |
+| --- | --- | --- |
+| **Table Overview** | manifest + flags | Table name, billing mode, streams, TTL, and the deploy-time settings. |
+| **Entity Relationship Diagram** | manifest relations | A Mermaid `graph TD` of the `hasMany` / `hasOne` / `belongsTo` edges. |
+| **Physical Key Schema** | manifest keys / GSIs | A table of each model's `PK` / `SK` and per-GSI key templates. |
+| **Property Matrix** | manifest fields | Each property's role (PK / SK / GSI key / plain attribute) across entities. |
+| **Entity Details** | manifest | Per-entity key, GSIs, relations, maintained fields, and field table. |
+| **Access Patterns** | operations | A summary matrix plus, per query, the input/output contract, a `Resolve:` line, and a Mermaid execution flowchart. |
+| **Mutation Contracts** | operations | Per command, the input/output and resolution. |
+| **Maintained Access Paths** | metadata registry | Write-side projections kept in sync (counter / embedded snapshot), with a Mermaid diagram. |
+| **CDC** | metadata registry | For each `@cdcProjected()` model, the `subscribe` / `fromChange` contract and a stream diagram. |
+| **CloudFormation** | manifest | A summary of the resources `generate cloudformation` emits. |
+
+The Table Overview's **billing** and **streams** are resolved from the CLI flags
+(shared with `generate cloudformation`); deploy-time-only settings that have no
+flag (PITR, table class, encryption) render as `as configured at deployment`.
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--entry <file>` | (required) | Entry module registering the entity models. |
+| `--out <path>` | (required) | Output path. A `*.md` file is written verbatim at that path; any other value is a directory and `index.md` is written inside it. |
+| `--queries <file>` | entry module | Module exporting `queries` / `commands` for Access Patterns / Mutation Contracts. |
+| `--format <format>` | `markdown` | Output format (only `markdown` today). |
+| `--split <mode>` | `none` | `none` emits a single `index.md`. `entity` is reserved for a future per-entity split. |
+| `--template-dir <dir>` | — | Directory of override `<partial>.hbs` templates. |
+| `--helpers <file>` | — | JS module exporting extra Handlebars helpers. |
+| `--billing-mode <mode>` | `PAY_PER_REQUEST` | Billing mode shown in the Table Overview (shared with `generate cloudformation`). |
+| `--stream <mode>` | `auto` | Streams state in the Table Overview: `auto` detects stream-based maintenance (`updateMode: 'stream'`); `on` / `off` force it. |
+
+## Customizing the templates
+
+The document is rendered from a set of bundled **Handlebars partials**, one per
+section:
+
+```
+index · table-overview · er-diagram · key-schema · property-matrix
+      · entity · access-pattern · maintained · cdc · cloudformation
+```
+
+`index` is the document skeleton; it renders each section partial in order. All
+partials reference only a normalized **view model** (the section headings, table
+rows, diagram nodes are precomputed), so a custom template is just a loop over
+ready-to-print data — you never have to reach into the raw manifest.
+
+### `--template-dir` (per-section override)
+
+Point `--template-dir` at a directory containing any `<partial>.hbs` files. Each
+file whose name matches a bundled partial **replaces** it; every partial you do
+**not** provide falls back to the bundled default. You only write the sections
+you want to change — there is no need to copy the whole set.
+
+For example, to replace just the CloudFormation section:
+
+```
+doc-templates/
+  cloudformation.hbs
+```
+
+```handlebars
+{{! doc-templates/cloudformation.hbs }}
+## Infrastructure
+
+The table `{{table}}` is provisioned by our platform team — see the internal
+runbook. Generated CloudFormation lives in `{{cfnFile}}`.
+```
+
+```bash
+graphddb generate docs --entry models.ts --out docs/ --template-dir doc-templates/
+```
+
+Every other section still renders from the bundled partials.
+
+### `--helpers` (extra Handlebars helpers)
+
+The generator registers a small built-in helper set — `eq`, `join`, `pascal`,
+`mermaidId`, and `codeOrEmpty`. Pass `--helpers` a JS module to register more (a
+custom helper of the same name overrides a built-in). The module exports its
+helpers as a `helpers` named export (or the default export):
+
+```js
+// doc-helpers.mjs
+export const helpers = {
+  shout: (value) => String(value).toUpperCase(),
+  badge: (text) => `![${text}](https://img.shields.io/badge/-${text}-blue)`,
+};
+```
+
+```bash
+graphddb generate docs --entry models.ts --out docs/ \
+  --template-dir doc-templates/ --helpers doc-helpers.mjs
+```
+
+Your helpers are then callable from any partial (bundled or overridden):
+
+```handlebars
+{{shout table}}
+```
+
+## The view model
+
+Templates receive a single normalized view model with these top-level fields —
+the vocabulary a custom template can rely on:
+
+| Field | Shape | Used by |
+| --- | --- | --- |
+| `title` / `table` | strings | headings, Table Overview |
+| `overview` | `{ item, value }[]` | Table Overview |
+| `entityNames` | `string[]` | Property Matrix columns |
+| `relationEdges` | `{ source, target, label }[]` | ER diagram |
+| `gsiColumns` / `keySchema` | GSI names / `{ model, pk, sk, gsis }[]` | Key Schema |
+| `propertyMatrix` | `{ property, type, description, cells }[]` | Property Matrix |
+| `entities` | per-entity `{ name, pk, sk, gsis, relations, maintained, fields }` | Entity Details |
+| `accessMatrix` / `accessPatterns` | matrix rows / `{ signature, input, output, resolve, diagram, … }` | Access Patterns |
+| `mutationContracts` | `{ signature, input, output, resolve }[]` | Mutation Contracts |
+| `maintainedPaths` | `{ source, target, pattern, update }[]` | Maintained Access Paths |
+| `cdcEntries` | `{ model }[]` | CDC |
+| `cfnResources` / `cfnFile` | `{ resource, description }[]` / string | CloudFormation |
+
+## Scope
+
+The Access Patterns are described to the extent resolvable at generation time —
+the operation type, the index, the key template, the projection, and the
+cardinality (single vs. paged). Actual read-capacity cost and row counts require
+runtime information and are out of scope.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphddb",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Graph data modeling on DynamoDB with adjacency list pattern",
   "type": "module",
   "main": "dist/index.js",
@@ -17,6 +17,18 @@
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "import": "./dist/testing/index.js"
+    },
+    "./spec": {
+      "types": "./dist/spec/index.d.ts",
+      "import": "./dist/spec/index.js"
+    },
+    "./linter": {
+      "types": "./dist/linter/index.d.ts",
+      "import": "./dist/linter/index.js"
+    },
+    "./cdc": {
+      "types": "./dist/cdc/index.d.ts",
+      "import": "./dist/cdc/index.js"
     }
   },
   "bin": {
@@ -41,9 +53,36 @@
     "gen:cli": "cli-contracts generate",
     "gen:cli:check": "cli-contracts generate --dry-run",
     "clean": "rm -rf dist",
+    "size": "size-limit",
+    "size:why": "size-limit --why",
     "docker:up": "docker compose -f docker-compose.test.yml up -d",
     "docker:down": "docker compose -f docker-compose.test.yml down"
   },
+  "size-limit": [
+    {
+      "name": "runtime core (DDBModel + authoring)",
+      "path": "dist/index.js",
+      "import": "{ DDBModel, model, string, number, key, k, executeQuery, executeList, executeExplain }",
+      "limit": "42 KB"
+    },
+    {
+      "name": "runtime core (import *)",
+      "path": "dist/index.js",
+      "limit": "80 KB"
+    },
+    {
+      "name": "graphddb/testing",
+      "path": "dist/testing/index.js",
+      "import": "{ createTestDB }",
+      "limit": "12 KB"
+    },
+    {
+      "name": "graphddb/spec (build-time)",
+      "path": "dist/spec/index.js",
+      "import": "{ buildBridgeBundle }",
+      "limit": "20 KB"
+    }
+  ],
   "peerDependencies": {
     "@aws-sdk/client-dynamodb": "^3.0.0",
     "@aws-sdk/lib-dynamodb": "^3.0.0",
@@ -63,11 +102,13 @@
   "devDependencies": {
     "@aws-sdk/client-dynamodb": "^3.700.0",
     "@aws-sdk/lib-dynamodb": "^3.700.0",
+    "@size-limit/preset-small-lib": "^11.0.0",
     "@types/node": "^22.20.0",
     "cli-contracts": "^0.33.14",
     "dynamodb-onetable": "^2.7.7",
     "dynamodb-toolbox": "^2.9.0",
     "electrodb": "^3.9.1",
+    "size-limit": "^11.0.0",
     "tsup": "^8.0.0",
     "tsx": "^4.22.4",
     "typescript": "^5.5.0",
@@ -79,9 +120,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "commander": "^15.0.0"
+    "commander": "^15.0.0",
+    "handlebars": "^4.7.9"
   },
   "optionalDependencies": {
     "typescript": "^5.5.0"
-  }
+  },
+  "sideEffects": false
 }

package/dist/chunk-MCKGQKYU.js

@@ -1,15 +0,0 @@
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-var __commonJS = (cb, mod) => function __require2() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
-};
-
-export {
-  __require,
-  __commonJS
-};