@zmdb/orm 1.0.0-beta.1

package/dist/transactions/index.js

@@ -0,0 +1,249 @@
+// Transactions — implementation (#36 transaction context primitive).
+// createTransactionalDb.transaction() issues BEGIN/COMMIT/ROLLBACK and
+// tx.savepoint() issues SAVEPOINT / RELEASE / ROLLBACK TO SAVEPOINT.
+import { dialectTraits } from '@zmdb/sql';
+import {} from '../index.js';
+export function markTransactionClosed(tx) {
+    const stream = typeof tx.stream === 'function' ? tx.stream : undefined;
+    return {
+        _state: 'closed',
+        ...(tx.dialect === undefined ? {} : { dialect: tx.dialect }),
+        execute: (query, opts) => tx.execute(query, opts),
+        ...(stream === undefined
+            ? {}
+            : {
+                stream: (query, opts) => stream.call(tx, query, opts),
+            }),
+        savepoint: (fn) => tx.savepoint(innerTx => fn(markTransactionClosed(innerTx))),
+    };
+}
+function nonNegativeInteger(name, value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(`${name} must be a non-negative safe integer`);
+    }
+}
+function retryPolicy(options) {
+    const policy = options?.retry;
+    if (policy === undefined)
+        return undefined;
+    const baseDelayMs = policy.baseDelayMs ?? 10;
+    const maxDelayMs = policy.maxDelayMs ?? 1000;
+    nonNegativeInteger('retry.maxRetries', policy.maxRetries);
+    nonNegativeInteger('retry.baseDelayMs', baseDelayMs);
+    nonNegativeInteger('retry.maxDelayMs', maxDelayMs);
+    return { maxRetries: policy.maxRetries, baseDelayMs, maxDelayMs };
+}
+function errorCode(error) {
+    if (error === null || typeof error !== 'object')
+        return undefined;
+    const code = Reflect.get(error, 'code');
+    return typeof code === 'string' ? code : undefined;
+}
+function canRetry(retryableCodes, error, retries, policy) {
+    if (retryableCodes === undefined || policy === undefined || retries >= policy.maxRetries)
+        return false;
+    const code = errorCode(error);
+    return code !== undefined && retryableCodes.includes(code);
+}
+function backoff(policy, retry) {
+    return Math.min(policy.baseDelayMs * 2 ** (retry - 1), policy.maxDelayMs);
+}
+async function wait(milliseconds) {
+    if (milliseconds === 0)
+        return;
+    await new Promise(resolve => {
+        setTimeout(resolve, milliseconds);
+    });
+}
+function transactionClosedError() {
+    return new Error('cannot continue a stream after its transaction scope has closed');
+}
+function trackedTransactionStream(source, active, isOpen) {
+    let started = false;
+    let closed = false;
+    let iterator;
+    let closing;
+    const stream = {
+        close() {
+            if (closing !== undefined)
+                return closing;
+            if (closed)
+                return Promise.resolve();
+            closed = true;
+            active.delete(stream);
+            const current = iterator;
+            iterator = undefined;
+            closing = (async () => {
+                if (current?.return !== undefined)
+                    await current.return();
+            })();
+            return closing;
+        },
+    };
+    return {
+        [Symbol.asyncIterator]() {
+            if (started)
+                throw new Error('transaction stream is single-shot');
+            if (!isOpen())
+                throw transactionClosedError();
+            started = true;
+            iterator = source[Symbol.asyncIterator]();
+            active.add(stream);
+            return {
+                async next() {
+                    if (!isOpen())
+                        throw transactionClosedError();
+                    const current = iterator;
+                    if (current === undefined)
+                        return { done: true, value: undefined };
+                    try {
+                        const result = await current.next();
+                        if (!isOpen()) {
+                            await stream.close();
+                            throw transactionClosedError();
+                        }
+                        if (result.done) {
+                            closed = true;
+                            iterator = undefined;
+                            active.delete(stream);
+                        }
+                        return result;
+                    }
+                    catch (error) {
+                        await stream.close();
+                        throw error;
+                    }
+                },
+                async return() {
+                    await stream.close();
+                    return { done: true, value: undefined };
+                },
+                async throw(error) {
+                    const current = iterator;
+                    try {
+                        if (current?.throw !== undefined)
+                            return await current.throw(error);
+                        throw error;
+                    }
+                    finally {
+                        await stream.close();
+                    }
+                },
+            };
+        },
+    };
+}
+export function createTransactionalDb(conn) {
+    let savepointSeq = 0;
+    const retryableCodes = conn.dialect === undefined ? undefined : dialectTraits(conn.dialect).retryableCodes;
+    const makeContext = () => {
+        let open = true;
+        const activeStreams = new Set();
+        const connectionStream = typeof conn.stream === 'function' ? conn.stream : undefined;
+        const assertOpen = () => {
+            if (!open)
+                throw transactionClosedError();
+        };
+        const close = async () => {
+            if (!open)
+                return;
+            open = false;
+            let firstFailure;
+            let failed = false;
+            for (const stream of activeStreams) {
+                try {
+                    await stream.close();
+                }
+                catch (error) {
+                    if (!failed)
+                        firstFailure = error;
+                    failed = true;
+                }
+            }
+            if (failed)
+                throw firstFailure;
+        };
+        const context = {
+            ...(conn.dialect === undefined ? {} : { dialect: conn.dialect }),
+            execute: (query, opts) => {
+                assertOpen();
+                return conn.execute(query, opts);
+            },
+            ...(connectionStream === undefined
+                ? {}
+                : {
+                    stream: (query, opts) => {
+                        assertOpen();
+                        return trackedTransactionStream(connectionStream.call(conn, query, opts), activeStreams, () => open);
+                    },
+                }),
+            savepoint: async (fn) => {
+                assertOpen();
+                const name = `s${++savepointSeq}`;
+                await conn.raw(`SAVEPOINT ${name}`);
+                const nested = makeContext();
+                try {
+                    const result = await fn(nested.context);
+                    await nested.close();
+                    await conn.raw(`RELEASE SAVEPOINT ${name}`);
+                    return result;
+                }
+                catch (error) {
+                    let failure = error;
+                    try {
+                        await nested.close();
+                    }
+                    catch (closeError) {
+                        failure = closeError;
+                    }
+                    await conn.raw(`ROLLBACK TO SAVEPOINT ${name}`);
+                    throw failure;
+                }
+            },
+        };
+        return { context, close };
+    };
+    return {
+        async transaction(fn, options) {
+            const policy = retryPolicy(options);
+            let retries = 0;
+            while (true) {
+                savepointSeq = 0;
+                await conn.raw('BEGIN');
+                const scope = makeContext();
+                try {
+                    const result = await fn(scope.context);
+                    await scope.close();
+                    await conn.raw('COMMIT');
+                    return result;
+                }
+                catch (error) {
+                    let failure = error;
+                    try {
+                        await scope.close();
+                    }
+                    catch (closeError) {
+                        failure = closeError;
+                    }
+                    await conn.raw('ROLLBACK');
+                    if (!canRetry(retryableCodes, failure, retries, policy))
+                        throw failure;
+                    retries++;
+                    await wait(backoff(policy, retries));
+                }
+            }
+        },
+    };
+}
+// #39 — explicit write-batching helper. Runs the given operations inside a
+// single transaction / one flush: all-or-nothing. Each op receives the tx
+// context and performs its own execute(s).
+export function batch(db, ops) {
+    return db.transaction(async (tx) => {
+        const results = [];
+        for (const op of ops)
+            results.push(await op(tx));
+        return results;
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/transactions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/transactions/index.ts"],"names":[],"mappings":"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"}

package/dist/typed-populate/nested.fixtures.d.ts

@@ -0,0 +1,34 @@
+import { type ManyToMany, type ManyToOne, type OneToMany, type OneToOne, type Physical, type PrimaryKey, type References, type Sql, type Table } from '@zmdb/schema/tags';
+export interface NestedUser extends Table<'nested_users'>, Physical<'app_users'> {
+    tenantId: number & Sql<'integer'> & PrimaryKey & Physical<'tenant_id'>;
+    id: number & Sql<'integer'> & PrimaryKey;
+    name: string & Sql<'text'>;
+    posts?: NestedPost[] & OneToMany<'nested_posts', 'tenantId,userId'>;
+    profile?: NestedProfile & OneToOne<'nested_profiles', 'tenantId,userId'>;
+    groups?: NestedUser[] & ManyToMany<'nested_users', 'user_groups'>;
+}
+export interface NestedPost extends Table<'nested_posts'>, Physical<'blog_posts'> {
+    tenantId: number & Sql<'integer'> & PrimaryKey & References<'nested_users.tenantId'> & Physical<'tenant_id'>;
+    id: number & Sql<'integer'> & PrimaryKey;
+    userId: number & Sql<'integer'> & References<'nested_users.id'> & Physical<'user_id'>;
+    title: string & Sql<'text'>;
+    comments?: NestedComment[] & OneToMany<'nested_comments', 'tenantId,postId'>;
+}
+export interface NestedComment extends Table<'nested_comments'>, Physical<'post_comments'> {
+    tenantId: number & Sql<'integer'> & PrimaryKey & References<'nested_users.tenantId'> & Physical<'tenant_id'>;
+    id: number & Sql<'integer'> & PrimaryKey;
+    postId: number & Sql<'integer'> & Physical<'post_id'>;
+    authorId: (number & Sql<'integer'> & References<'nested_users.id'> & Physical<'author_id'>) | null;
+    body: string & Sql<'text'>;
+    hidden: number & Sql<'integer'>;
+    author?: NestedUser & ManyToOne<'nested_users', 'tenantId,authorId'>;
+}
+export interface NestedProfile extends Table<'nested_profiles'>, Physical<'user_profiles'> {
+    tenantId: number & Sql<'integer'> & PrimaryKey & References<'nested_users.tenantId'> & Physical<'tenant_id'>;
+    id: number & Sql<'integer'> & PrimaryKey;
+    userId: number & Sql<'integer'> & References<'nested_users.id'> & Physical<'user_id'>;
+    bio: string & Sql<'text'>;
+    user?: NestedUser & ManyToOne<'nested_users', 'tenantId,userId'>;
+}
+export declare const NestedUserSchema: import("@zmdb/schema").TaggedSchema<NestedUser>, NestedPostSchema: import("@zmdb/schema").TaggedSchema<NestedPost>, NestedCommentSchema: import("@zmdb/schema").TaggedSchema<NestedComment>, NestedProfileSchema: import("@zmdb/schema").TaggedSchema<NestedProfile>;
+//# sourceMappingURL=nested.fixtures.d.ts.map

package/dist/typed-populate/nested.fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested.fixtures.d.ts","sourceRoot":"","sources":["../../src/typed-populate/nested.fixtures.ts"],"names":[],"mappings":"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"}

package/dist/typed-populate/nested.fixtures.js

@@ -0,0 +1,4 @@
+import { schemasFrom } from '@zmdb/compiler/testing';
+import {} from '@zmdb/schema/tags';
+export const { NestedUser: NestedUserSchema, NestedPost: NestedPostSchema, NestedComment: NestedCommentSchema, NestedProfile: NestedProfileSchema, } = schemasFrom(import.meta.url, ['NestedUser', 'NestedPost', 'NestedComment', 'NestedProfile']);
+//# sourceMappingURL=nested.fixtures.js.map

package/dist/typed-populate/nested.fixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested.fixtures.js","sourceRoot":"","sources":["../../src/typed-populate/nested.fixtures.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAUN,MAAM,mBAAmB,CAAC;AAqC3B,MAAM,CAAC,MAAM,EACX,UAAU,EAAE,gBAAgB,EAC5B,UAAU,EAAE,gBAAgB,EAC5B,aAAa,EAAE,mBAAmB,EAClC,aAAa,EAAE,mBAAmB,GACnC,GAAG,WAAW,CAKZ,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@zmdb/orm",
+  "version": "1.0.0-beta.1",
+  "description": "Auto-validating CRUD repository over a zmdb schema: transactions, populate, read-replicas, lifecycle events, and seeding. No proxies, no identity map.",
+  "keywords": [
+    "crud",
+    "data-layer",
+    "repository",
+    "transactions",
+    "typescript",
+    "zmdb"
+  ],
+  "homepage": "https://github.com/ambasta/zmdb#readme",
+  "bugs": {
+    "url": "https://github.com/ambasta/zmdb/issues"
+  },
+  "license": "GPL-3.0-or-later",
+  "author": "zmdb contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ambasta/zmdb.git",
+    "directory": "packages/orm"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./dto": {
+      "types": "./dist/dto/index.d.ts",
+      "import": "./dist/dto/index.js"
+    },
+    "./relations": {
+      "types": "./dist/relations/index.d.ts",
+      "import": "./dist/relations/index.js"
+    },
+    "./seeding": {
+      "types": "./dist/seeding/index.d.ts",
+      "import": "./dist/seeding/index.js"
+    },
+    "./transactions": {
+      "types": "./dist/transactions/index.d.ts",
+      "import": "./dist/transactions/index.js"
+    },
+    "./outbox": {
+      "types": "./dist/outbox/index.d.ts",
+      "import": "./dist/outbox/index.js"
+    },
+    "./replicas": {
+      "types": "./dist/replicas/index.d.ts",
+      "import": "./dist/replicas/index.js"
+    },
+    "./entity-modeling": {
+      "types": "./dist/entity-modeling/index.d.ts",
+      "import": "./dist/entity-modeling/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@zmdb/schema": "1.0.0-beta.1",
+    "@zmdb/sql": "1.0.0-beta.1",
+    "@zmdb/validator": "1.0.0-beta.1"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}

package/src/cache/index.ts

@@ -0,0 +1,188 @@
+import { isRecord } from '@zmdb/schema';
+import { type SchemaIR } from '@zmdb/schema/ir';
+import { dialectName, type CompiledQuery, type DialectTarget } from '@zmdb/sql';
+
+export interface CacheStore {
+  get(key: string): Promise<unknown | undefined>;
+  set(key: string, value: unknown, ttlMs: number, tags: readonly string[]): Promise<void>;
+  invalidateTags(tags: readonly string[]): Promise<void>;
+}
+
+export interface CacheOptions {
+  readonly ttlMs: number;
+  readonly tags?: readonly string[];
+}
+
+export interface CacheInvalidationOptions {
+  readonly invalidateTags?: readonly string[];
+}
+
+interface MemoryEntry {
+  readonly value: unknown;
+  readonly expiresAt: number;
+  readonly tags: readonly string[];
+}
+
+const DEFAULT_MAX_ENTRIES = 1_000;
+
+function positiveInteger(value: number, name: string): number {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new RangeError(`${name} must be a positive safe integer`);
+  }
+  return value;
+}
+
+function positiveDuration(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError('cache ttlMs must be a positive finite number');
+  }
+  return value;
+}
+
+/**
+ * A process-local TTL store with bounded least-recently-used eviction.
+ *
+ * The default is deliberately finite. Expired entries are removed on access;
+ * writes evict the oldest live-or-expired entry until the bound is restored.
+ */
+export function memoryStore(options?: { readonly maxEntries?: number }): CacheStore {
+  const maxEntries = positiveInteger(options?.maxEntries ?? DEFAULT_MAX_ENTRIES, 'cache maxEntries');
+  const entries = new Map<string, MemoryEntry>();
+
+  return {
+    async get(key) {
+      const entry = entries.get(key);
+      if (entry === undefined) return undefined;
+      if (entry.expiresAt <= Date.now()) {
+        entries.delete(key);
+        return undefined;
+      }
+
+      entries.delete(key);
+      entries.set(key, entry);
+      return entry.value;
+    },
+
+    async set(key, value, ttlMs, tags) {
+      entries.delete(key);
+      entries.set(key, {
+        value,
+        expiresAt: Date.now() + positiveDuration(ttlMs),
+        tags: [...tags],
+      });
+
+      while (entries.size > maxEntries) {
+        const oldest = entries.keys().next().value;
+        if (oldest === undefined) break;
+        entries.delete(oldest);
+      }
+    },
+
+    async invalidateTags(tags) {
+      if (tags.length === 0) return;
+      const invalidated = new Set(tags);
+      for (const [key, entry] of entries) {
+        if (entry.tags.some(tag => invalidated.has(tag))) entries.delete(key);
+      }
+    },
+  };
+}
+
+function frame(tag: string, payload = ''): string {
+  return `${tag}:${String(payload.length)}:${payload}`;
+}
+
+function binary(kind: string, value: Uint8Array): string {
+  const encoded = [...value].map(byte => byte.toString(16).padStart(2, '0')).join('');
+  return frame('x', frame('t', kind) + frame('v', encoded));
+}
+
+function taggedValue(value: unknown, ancestors: Set<object>): string {
+  if (value === null) return frame('z');
+  if (value === undefined) return frame('u');
+  if (typeof value === 'string') return frame('s', value);
+  if (typeof value === 'number') return frame('n', String(value));
+  if (typeof value === 'bigint') return frame('i', String(value));
+  if (typeof value === 'boolean') return frame('b', String(value));
+  if (typeof value === 'symbol' || typeof value === 'function') {
+    throw new TypeError(`cache keys cannot contain ${typeof value} values`);
+  }
+
+  if (value instanceof Date) return frame('d', String(value.getTime()));
+  if (value instanceof ArrayBuffer) return binary('ArrayBuffer', new Uint8Array(value));
+  if (ArrayBuffer.isView(value)) {
+    return binary(
+      Object.prototype.toString.call(value),
+      new Uint8Array(value.buffer, value.byteOffset, value.byteLength),
+    );
+  }
+  if (ancestors.has(value)) throw new TypeError('cache keys cannot contain cyclic values');
+  ancestors.add(value);
+
+  try {
+    if (Array.isArray(value)) {
+      return frame('a', value.map(item => frame('e', taggedValue(item, ancestors))).join(''));
+    }
+    if (value instanceof Map) {
+      const pairs = [...value].map(
+        ([key, item]) => frame('k', taggedValue(key, ancestors)) + frame('v', taggedValue(item, ancestors)),
+      );
+      return frame('m', pairs.toSorted().join(''));
+    }
+    if (value instanceof Set) {
+      return frame(
+        'q',
+        [...value]
+          .map(item => taggedValue(item, ancestors))
+          .toSorted()
+          .map(item => frame('e', item))
+          .join(''),
+      );
+    }
+
+    const kind = Object.prototype.toString.call(value);
+    const properties = Object.keys(value)
+      .toSorted()
+      .map(key => frame('k', taggedValue(key, ancestors)) + frame('v', taggedValue(Reflect.get(value, key), ancestors)))
+      .join('');
+    return frame('o', frame('t', kind) + properties);
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function stableValue(value: unknown): string {
+  return taggedValue(value, new Set());
+}
+
+function segment(name: string, value: unknown): string {
+  return frame(name, stableValue(value));
+}
+
+export function resultCacheKey(input: {
+  readonly dialect: DialectTarget;
+  readonly schema: SchemaIR;
+  readonly table: string;
+  readonly filters?: readonly string[];
+  readonly query: CompiledQuery;
+}): string {
+  return [
+    'z1',
+    segment('dialect', dialectName(input.dialect)),
+    segment('fingerprint', input.schema),
+    segment('table', input.table),
+    segment('filters', input.filters ?? []),
+    segment('text', input.query.text),
+    segment('params', input.query.parameters),
+  ].join('|');
+}
+
+export function cacheTags(table: string, callerTags: readonly string[] = []): readonly string[] {
+  return [...new Set([`table:${table}`, ...callerTags])];
+}
+
+/** Fresh row and array identities without the cost or promise of a deep clone. */
+export function copyCachedRows(value: unknown): unknown {
+  if (!Array.isArray(value)) return value;
+  return value.map(row => (isRecord(row) ? { ...row } : row));
+}

package/src/drivers/transactional.ts

@@ -0,0 +1,6 @@
+import { type Driver } from '../index.js';
+
+/** A driver that can pin every query in a callback to one database transaction. */
+export interface TransactionalDriver extends Driver {
+  transaction<Result>(run: (driver: Driver) => Promise<Result>): Promise<Result>;
+}