graphddb 0.5.2 → 0.6.0

package/README.md

@@ -22,6 +22,7 @@ TypeScript types.
 - ✅ **CDC projection** —— `@cdcProjected()` + `fromChange` / `subscribe` parse CDC change events into typed records (sink delivery / idempotency stay with the consumer).
 - ✅ **Maintained access paths** —— keep embedded snapshots / aggregate counters synchronized atomically.
 - ✅ **CloudFormation generation** —— emit a CloudFormation template for the DynamoDB table(s) a model set maps onto (GSI union / Streams / TTL / PITR / TableClass / SSE / PROVISIONED / Auto Scaling).
+- ✅ **Docs generation** —— generate a model specification (Markdown + Mermaid) from the TS models; templates are Handlebars and user-overridable.
 
 ## 🤔 Philosophy
 
@@ -214,6 +215,11 @@ Each capability is summarized here only. For details, operator lists, and proced
 - **CloudFormation generation** —— `graphddb generate cloudformation` emits a CloudFormation template for
   the DynamoDB table(s) a model set maps onto (GSI union / Streams / TTL / PITR / PROVISIONED / Auto
   Scaling). [`docs/cloudformation.md`](./docs/cloudformation.md).
+- **Docs generation** —— `graphddb generate docs` renders a human-facing model specification (Table
+  Overview / ER diagram / Key Schema / Property Matrix / Entity Details / Access Patterns / Mutation
+  Contracts / Maintained Access Paths / CDC / CloudFormation) as Markdown + Mermaid. The layout is
+  defined by bundled Handlebars templates that users can customize with `--template-dir` (per-partial
+  override) and `--helpers` (extra helpers). [`docs/docs-generation.md`](./docs/docs-generation.md).
 
 ## 📚 Documentation
 
@@ -234,6 +240,7 @@ documentation available offline at hand. On GitHub, follow the links in the tabl
 | [CDC emulator](./docs/cdc-emulator.md) | A change-event emulator for differential aggregation patterns (dev/test). |
 | [CDC projection](./docs/cdc-projection.md) | The `@cdcProjected()` + `fromChange` / `subscribe` typed-consumer-IF: a contract that parses CDC change events into typed records. Boundary (parse→typed is graphddb; subscription, sink delivery, idempotency are the consumer's). |
 | [CloudFormation generation](./docs/cloudformation.md) | The `generate cloudformation` command: emit a CloudFormation template for the DynamoDB table(s) a model set maps onto (GSI union / Streams / TTL / PITR / TableClass / SSE / PROVISIONED / Auto Scaling). All options, derivation rules, and scope boundary. |
+| [Docs generation](./docs/docs-generation.md) | The `generate docs` command: generate a model specification (Markdown + Mermaid) from the TS models. All options, output sections, and customizing the Handlebars templates with `--template-dir` / `--helpers`. |
 | [Benchmark](./benchmark/RESULTS.md) | Library comparison against hand-written AWS SDK, ElectroDB, DynamoDB Toolbox, and OneTable. |
 
 ## 💡 Examples
@@ -264,6 +271,7 @@ flowchart LR
     M --> PY["Python client + runtime"]
     M --> CQ["CQRS Contract"]
     M --> CFN["CloudFormation template"]
+    M --> DOC["Model docs (Markdown + Mermaid)"]
 ```
 
 ## 📄 License

package/dist/cdc/index.d.ts

@@ -0,0 +1,37 @@
+export { C as CdcEmulator, M as MAINT_OUTBOX_PK_PREFIX, a as MaintenanceDrain, b as MaintenanceDrainOptions, c as createCdcEmulator, d as createMaintenanceDrain, e as createMaintenanceDrainHandler, p as parseChange } from '../from-change-CFzBy7aU.js';
+export { B as BatchResult, C as CdcEmulatorOptions, a as CdcMode, b as ChangeBatch, c as ChangeEvent, d as ChangeEventName, e as ChangeHandler, f as ClockMode, g as ConcurrentRecomputeRef, E as EventLog, F as FaultSpec, R as ReplayOptions, S as ShardId, h as StartingPosition, i as StreamViewType, j as SubscribeHandler, k as SubscribeHandlers, U as Unsubscribe, l as buildSubscribeHandler } from '../maintenance-view-adapter-CFeasCKo.js';
+import '@aws-sdk/client-dynamodb';
+
+/**
+ * Deterministic primitives for the CDC emulator (issue #72). All fault
+ * injection and shard assignment route through these so a given `seed`
+ * reproduces the exact same event ordering, duplicates, delays, and failures
+ * (spec §8, AC3).
+ */
+/**
+ * mulberry32 — a small, fast, fully deterministic 32-bit PRNG. Given the same
+ * seed it produces the same sequence on every platform, which is what AC3
+ * ("…deterministically reproducible with a seed") requires.
+ */
+declare class SeededRandom {
+    private state;
+    constructor(seed: number);
+    /** Next float in [0, 1). */
+    next(): number;
+    /** Integer in [min, max] inclusive. */
+    int(min: number, max: number): number;
+    /** Bernoulli trial: true with probability `p`. */
+    chance(p: number): boolean;
+    /** In-place Fisher–Yates shuffle, deterministic for the seed state. */
+    shuffle<T>(items: T[]): T[];
+}
+/**
+ * Stable 32-bit string hash (FNV-1a). Used for `shardId = hash(pk)` so the same
+ * partition key always lands in the same shard (spec §6), independent of the
+ * fault PRNG.
+ */
+declare function hashString(value: string): number;
+/** Compute the shard id for a partition key over `shardCount` shards. */
+declare function shardIdFor(pk: string, shardCount: number): string;
+
+export { SeededRandom, hashString, shardIdFor };

package/dist/cdc/index.js

@@ -0,0 +1,29 @@
+import {
+  CdcEmulator,
+  MAINT_OUTBOX_PK_PREFIX,
+  MaintenanceDrain,
+  SeededRandom,
+  createCdcEmulator,
+  createMaintenanceDrain,
+  createMaintenanceDrainHandler,
+  hashString,
+  shardIdFor
+} from "../chunk-5NXNEW43.js";
+import {
+  buildSubscribeHandler,
+  parseChange
+} from "../chunk-F2DI3GTI.js";
+import "../chunk-PDUVTYC5.js";
+export {
+  CdcEmulator,
+  MAINT_OUTBOX_PK_PREFIX,
+  MaintenanceDrain,
+  SeededRandom,
+  buildSubscribeHandler,
+  createCdcEmulator,
+  createMaintenanceDrain,
+  createMaintenanceDrainHandler,
+  hashString,
+  parseChange,
+  shardIdFor
+};

package/dist/{chunk-QBXLQNXY.js → chunk-5NXNEW43.js}

@@ -7,7 +7,7 @@ import {
   buildMaintenanceGraph,
   buildPutInput,
   resolveModelClass
-} from "./chunk-W3GEJPPV.js";
+} from "./chunk-F2DI3GTI.js";
 
 // src/cdc/prng.ts
 var SeededRandom = class {
@@ -793,6 +793,9 @@ function createMaintenanceDrainHandler(opts = {}) {
 }
 
 export {
+  SeededRandom,
+  hashString,
+  shardIdFor,
   CdcEmulator,
   createCdcEmulator,
   pathField,