graphddb 0.1.0

package/dist/testing/index.d.ts

@@ -0,0 +1,182 @@
+import { E as Executor, D as DynamoDBOperation, a as ExecutorResult, B as BatchGetExecInput, P as PutInput, W as WriteExecOptions, b as WriteResult, U as UpdateInput, c as DeleteInput, d as BatchWriteExecItem, T as TransactWriteExecItem, M as ModelStatic, e as DDBModel, C as ChangeEvent } from '../types-CDrWiPxp.js';
+import '@aws-sdk/client-dynamodb';
+
+/**
+ * In-process physical store backing the GraphDDB Memory Test Adapter
+ * (issue #76). A table is a `Map<PK, Map<SK, Item>>`; items are kept in their
+ * **physical** form exactly as GraphDDB writes them (`PK` / `SK` / `GSI*PK` /
+ * `GSI*SK` plus attributes), with no marshalling and no hydration. Sort keys are
+ * compared lexicographically (byte order) at read time — numeric zero-padding is
+ * the model's responsibility, matching the proposal's fidelity non-goals.
+ *
+ * GSI secondary indexes are not stored separately: since GraphDDB projects ALL
+ * onto its GSIs, a GSI query is answered by filtering the base partition rows on
+ * their `{index}PK` / `{index}SK` attributes — equivalent to a maintained ALL
+ * projection, and trivially consistent on every write.
+ */
+/** A physical item as stored: a plain attribute map including PK/SK/GSI keys. */
+type Item = Record<string, unknown>;
+/** A structured-clone snapshot of the whole store, for save/restore isolation. */
+type MemorySnapshot = Record<string, Item[]>;
+declare class MemoryStore {
+    /** table → PK → SK → item. */
+    private tables;
+    private partition;
+    /** Insert/overwrite one physical item. Returns the prior item if present. */
+    putItem(table: string, item: Item): Item | undefined;
+    /** Fetch one physical item by base-table key. */
+    getItem(table: string, pk: string, sk: string): Item | undefined;
+    /** Delete one item by base-table key. Returns the removed item if present. */
+    deleteItem(table: string, pk: string, sk: string): Item | undefined;
+    /**
+     * All items in one base-table partition, sorted ascending by SK (byte order).
+     * Used by the Query path (PK eq + optional SK range).
+     */
+    partitionItems(table: string, pk: string): Item[];
+    /**
+     * All items in one GSI partition (rows whose `{index}PK` equals `pk`), sorted
+     * ascending by the GSI sort key (`{index}SK`, byte order). Filtering the base
+     * rows is equivalent to a maintained ALL-projection secondary index.
+     */
+    gsiPartitionItems(table: string, indexName: string, pk: string): Item[];
+    /** Every physical item in one table (unsorted; inspection only). */
+    allItems(table: string): Item[];
+    /** Names of every table that currently holds at least one partition. */
+    tableNames(): string[];
+    /** Item count for one table. */
+    count(table: string): number;
+    /** Clear all tables. */
+    reset(): void;
+    /** Structured-clone the whole store (save). */
+    snapshot(): MemorySnapshot;
+    /** Replace all store contents from a snapshot (load). */
+    restore(snapshot: MemorySnapshot): void;
+}
+
+/**
+ * In-process {@link Executor} over a {@link MemoryStore} (issue #76). It
+ * interprets the *structured* operations GraphDDB emits — never AWS SDK
+ * commands and never the compiled key-condition strings — so the planner,
+ * key resolver, projection, hydrator and relation traversal all run unchanged
+ * (proposal option B). Only the FilterExpression and Update/Condition
+ * expressions are interpreted (the boundary where GraphDDB hands the executor a
+ * compiled string), via the dedicated in-memory evaluators.
+ *
+ * Implements exactly the DynamoDB subset GraphDDB uses: PK-eq Query with an
+ * optional SK `=` / `begins_with` range, `limit` + `ExclusiveStartKey`
+ * pagination, `scanIndexForward`, GSI queries (ALL projection), BatchGet,
+ * projection, server-side filter, conditional writes, and atomic TransactWrite.
+ */
+
+declare class MemoryExecutor implements Executor {
+    private readonly store;
+    constructor(store: MemoryStore);
+    execute(operation: DynamoDBOperation): Promise<ExecutorResult>;
+    batchGet(input: BatchGetExecInput): Promise<ExecutorResult>;
+    private getItem;
+    private query;
+    put(input: PutInput, options?: WriteExecOptions): Promise<WriteResult>;
+    update(input: UpdateInput, options?: WriteExecOptions): Promise<WriteResult>;
+    delete(input: DeleteInput, options?: WriteExecOptions): Promise<WriteResult>;
+    batchWrite(tableName: string, items: BatchWriteExecItem[]): Promise<void>;
+    transactWrite(items: TransactWriteExecItem[]): Promise<void>;
+    private restoreTable;
+    /**
+     * Evaluate a transaction `ConditionCheck` (issue #81): read the keyed item and
+     * assert its `ConditionExpression` holds. Mutates nothing; a failed assertion
+     * throws {@link ConditionalCheckFailed}, which {@link transactWrite} catches to
+     * roll the whole transaction back — mirroring DynamoDB's atomic cancellation.
+     */
+    private conditionCheck;
+    private assertCondition;
+}
+
+/**
+ * `graphddb/testing` — the in-process test adapter entry point (issue #76).
+ *
+ * `createTestDB()` installs a {@link MemoryExecutor} as GraphDDB's I/O seam, so
+ * `Model.put/query/list/update/...`, the planner, hydrator and relation
+ * traversal all run against an in-memory store — **no DynamoDB, no Docker**.
+ * The returned `db.testing` is a {@link MemoryInspector} for asserting the
+ * **physical** layout (PK/SK/GSI as stored, no hydration), seeding fixtures,
+ * resetting, and snapshot/restore isolation between tests.
+ *
+ * With `{ cdc: true }`, a {@link CdcEmulator} (record mode) is attached over the
+ * configured models so writes flowing through the in-memory executor produce
+ * `ChangeEvent`s, readable via `db.testing.changes()` (Phase 3 of the proposal,
+ * enabled because CDC #72 exists on this branch).
+ */
+
+/** A scan filter over a single table's physical rows (inspection only). */
+interface ScanFilter {
+    /** Match the base-table `PK` exactly. */
+    pk?: string;
+    /** Match a base-table `SK` prefix. */
+    skPrefix?: string;
+    /**
+     * Inspect a GSI partition instead of the base table: rows are filtered on
+     * `{index}PK` (via {@link pk}) / `{index}SK` prefix (via {@link skPrefix}).
+     */
+    index?: string;
+}
+/**
+ * Direct, hydration-free inspection of the in-memory store (proposal
+ * §"inspection / dump IF"). `dump` / `scan` return **physical** items — the bytes GraphDDB
+ * stored, including `PK` / `SK` / `GSI*PK` / `GSI*SK` — for asserting model
+ * mapping. This is a test-observation path; the system-under-test still uses
+ * `Model.query` / `Model.list`.
+ */
+interface MemoryInspector {
+    /** Every physical item, keyed by physical table name. */
+    dump(): Record<string, Item[]>;
+    /** Every physical item in one table. */
+    dumpTable(table: string): Item[];
+    /** Raw physical rows of a table, optionally filtered by PK / SK-prefix / GSI. */
+    scan(table: string, filter?: ScanFilter): Item[];
+    /** Item count for a table. */
+    count(table: string): number;
+    /** One physical item by base-table key, or `null`. */
+    getRaw(table: string, key: {
+        PK: string;
+        SK: string;
+    }): Item | null;
+    /** Insert physical items directly (fixtures). */
+    seed(table: string, items: Item[]): void;
+    /** Clear every table. */
+    reset(): void;
+    /** Structured-clone the whole store (save). */
+    snapshot(): MemorySnapshot;
+    /** Restore a snapshot (load). */
+    restore(snapshot: MemorySnapshot): void;
+    /** ChangeEvents captured so far (requires `cdc: true`). */
+    changes(): ChangeEvent[];
+    /** Tear down: restore the default executor and detach CDC. */
+    close(): void;
+}
+/** A model reference: a `ModelStatic` (from `DDBModel.asModel()`) or its class. */
+type ModelRef = ModelStatic<DDBModel> | Function;
+interface CreateTestDBOptions {
+    /**
+     * Models whose physical table name should be inspectable by their logical
+     * name and (when `cdc: true`) be stream-enabled. Optional: the inspector also
+     * reflects any table the store has written to.
+     */
+    models?: ModelRef[];
+    /** Enable the CDC emulator (record mode) over the configured models. */
+    cdc?: boolean;
+}
+interface TestDB {
+    /** The inspection / fixture / isolation interface. */
+    testing: MemoryInspector;
+    /** The backing store (advanced use). */
+    store: MemoryStore;
+}
+/**
+ * Create an in-memory GraphDDB for tests. Installs a {@link MemoryExecutor} on
+ * the {@link ClientManager} seam and returns a {@link MemoryInspector}. Call
+ * `db.testing.close()` (or `ClientManager.resetExecutor()`) when done to restore
+ * the default DynamoDB executor.
+ */
+declare function createTestDB(options?: CreateTestDBOptions): TestDB;
+
+export { type CreateTestDBOptions, type Item, MemoryExecutor, type MemoryInspector, type MemorySnapshot, MemoryStore, type ModelRef, type ScanFilter, type TestDB, createTestDB };