@ultimat3/entity 0.0.1 → 1.0.0

package/src/plan.ts

@@ -0,0 +1,82 @@
+// Single responsibility: turn repository arguments into the `QueryPlan` a driver executes.
+// It sits outside both drivers because memory and Postgres must agree on what a call means —
+// which rows are in scope, what the total sort order is, how big a page is. A guard only one
+// driver applies is worse than none: the test passes and production leaks another tenant's rows.
+
+import type { EntityCore } from './entity';
+import { invariantViolated } from './errors';
+import type { FindManyArgs, RepoOptions } from './repo';
+import type { Predicate, QueryPlan } from './tenancy';
+import { assertScoped } from './tenancy';
+
+/** A page is bounded by default; an unbounded read is a production incident waiting for traffic. */
+export const DEFAULT_PAGE_SIZE = 50;
+
+/** Id-addressed operations need exactly one key. A composite key is a `findMany({ where })`. */
+export const singleKeyOf = <Row>(entity: EntityCore<Row>, operation: string): string => {
+  const [only] = entity.$primaryKey;
+  if (entity.$primaryKey.length !== 1 || only === undefined) {
+    throw invariantViolated(
+      entity.$name,
+      operation,
+      `${entity.$name} has a composite primary key (${entity.$primaryKey.join(', ')}) — ` +
+        'use findMany({ where }) instead of an id',
+    );
+  }
+  return only;
+};
+
+export const planFor = <Row>(entity: EntityCore<Row>, args: FindManyArgs): QueryPlan => {
+  const scoped =
+    args.orgId === undefined || entity.$tenantColumn === null
+      ? []
+      : [{ column: entity.$tenantColumn, op: 'eq', value: args.orgId } satisfies Predicate];
+  const ordered = args.orderBy ?? [];
+  return {
+    entity: entity.$name,
+    where: [...(args.where ?? []), ...scoped],
+    // The primary key is always the final sort key: a cursor needs a total order, or two
+    // rows with the same sort value straddle a page boundary.
+    orderBy: [
+      ...ordered,
+      ...entity.$primaryKey
+        .filter((property) => !ordered.some((entry) => entry.column === property))
+        .map((property) => ({ column: property, direction: 'asc' as const })),
+    ],
+    limit: args.limit ?? DEFAULT_PAGE_SIZE,
+    ...(args.cursor === undefined || args.cursor === null ? {} : { cursor: args.cursor }),
+    ...(args.select === undefined ? {} : { select: args.select }),
+  };
+};
+
+/** The plan for a read. Throws `X_TENANCY_UNSCOPED` before a single row is considered. */
+export const readPlan = <Row>(
+  entity: EntityCore<Row>,
+  args: FindManyArgs,
+  operation: string,
+): QueryPlan => {
+  const plan = planFor(entity, args);
+  assertScoped(entity.$name, entity.$tenantColumn, operation, plan);
+  return plan;
+};
+
+/**
+ * The plan for an id-addressed write. A write is a query too: without the same guard,
+ * `update(id, patch)` on a tenant-scoped entity is a cross-tenant write that no read path
+ * would ever have allowed.
+ */
+export const idPlan = <Row>(
+  entity: EntityCore<Row>,
+  id: string,
+  options: RepoOptions | undefined,
+  operation: string,
+): QueryPlan =>
+  readPlan(
+    entity,
+    {
+      ...options,
+      where: [{ column: singleKeyOf(entity, operation), op: 'eq', value: id }],
+      limit: 1,
+    },
+    operation,
+  );

package/src/query.d.ts

@@ -0,0 +1,30 @@
+import type { EntityCore } from './entity';
+import type { Page, Repo, RepoOptions } from './repo';
+import type { Operator, QueryPlan, SortDirection } from './tenancy';
+import type { ColumnMap, Insertable } from './types';
+export interface ReadBuilder<Row> {
+    /** Equality on the columns given. `where({ orgId })` is what satisfies the tenancy guard. */
+    where(filter: Partial<Row>): ReadBuilder<Row>;
+    andWhere(column: keyof Row & string, op: Operator, value: unknown): ReadBuilder<Row>;
+    orderBy(column: keyof Row & string, direction?: SortDirection): ReadBuilder<Row>;
+    limit(rows: number): ReadBuilder<Row>;
+    /** The cursor from the previous page. */
+    after(cursor: string | null): ReadBuilder<Row>;
+    select<K extends keyof Row & string>(fields: {
+        readonly [P in K]: true;
+    }): ReadBuilder<Pick<Row, K>>;
+    /** The terminal: one bounded page and the cursor that continues it. */
+    page(): Promise<Page<Row>>;
+    all(): Promise<readonly Row[]>;
+    one(): Promise<Row | null>;
+    count(): Promise<number>;
+    /** The plan this chain describes. Safe to log — `describePlan()` elides values. */
+    plan(): QueryPlan;
+}
+export interface Table<Row, C extends ColumnMap = ColumnMap> extends ReadBuilder<Row> {
+    insert(values: Insertable<C>, options?: RepoOptions): Promise<Row>;
+    update(id: string, patch: Partial<Row>, options?: RepoOptions): Promise<Row>;
+    delete(id: string, options?: RepoOptions): Promise<void>;
+}
+export declare const tableFor: <Row, C extends ColumnMap>(entity: EntityCore<Row, C>, repo: Repo<Row>) => Table<Row, C>;
+//# sourceMappingURL=query.d.ts.map

package/src/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["query.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAa,SAAS,EAAE,aAAa,EAAW,MAAM,WAAW,CAAC;AACxF,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErD,MAAM,WAAW,WAAW,CAAC,GAAG;IAC9B,6FAA6F;IAC7F,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IACrF,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,MAAM,EAAE,SAAS,CAAC,EAAE,aAAa,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IACjF,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IACtC,yCAAyC;IACzC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC/C,MAAM,CAAC,CAAC,SAAS,MAAM,GAAG,GAAG,MAAM,EACjC,MAAM,EAAE;QAAE,QAAQ,EAAE,CAAC,IAAI,CAAC,GAAG,IAAI;KAAE,GAClC,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7B,uEAAuE;IACvE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,GAAG,IAAI,OAAO,CAAC,SAAS,GAAG,EAAE,CAAC,CAAC;IAC/B,GAAG,IAAI,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;IAC3B,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,mFAAmF;IACnF,IAAI,IAAI,SAAS,CAAC;CACnB;AAED,MAAM,WAAW,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,SAAS,GAAG,SAAS,CAAE,SAAQ,WAAW,CAAC,GAAG,CAAC;IACnF,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACnE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7E,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAkGD,eAAO,MAAM,QAAQ,GAAI,GAAG,EAAE,CAAC,SAAS,SAAS,UACvC,UAAU,CAAC,GAAG,EAAE,CAAC,CAAC,QACpB,IAAI,CAAC,GAAG,CAAC,KACd,KAAK,CAAC,GAAG,EAAE,CAAC,CAKb,CAAC"}

package/src/query.js

@@ -0,0 +1,74 @@
+// The chainable read. Every chain terminates in a cursor page — `page()` returns rows plus the
+// cursor for the next one, and `all()`/`one()` are that page's rows. There is no `offset()` and
+// there will not be one: under concurrent writes an insert before the offset shifts every later
+// page, so a client silently skips and repeats rows.
+const EMPTY = { where: [], orderBy: [], limit: 50, cursor: null, select: undefined };
+const asRecord = (value) => typeof value === 'object' && value !== null ? value : {};
+const builder = (entity, repo, state, pick) => {
+    const next = (patch) => builder(entity, repo, { ...state, ...patch }, pick);
+    const args = () => ({
+        where: state.where,
+        orderBy: state.orderBy,
+        limit: state.limit,
+        cursor: state.cursor,
+        ...(state.select === undefined ? {} : { select: state.select }),
+    });
+    return {
+        where: (filter) => next({
+            where: [
+                ...state.where,
+                ...Object.entries(asRecord(filter)).map(([column, value]) => ({ column, op: 'eq', value })),
+            ],
+        }),
+        andWhere: (column, op, value) => next({ where: [...state.where, { column, op, value }] }),
+        orderBy: (column, direction = 'asc') => next({ orderBy: [...state.orderBy, { column, direction }] }),
+        limit: (rows) => next({ limit: rows }),
+        after: (cursor) => next({ cursor }),
+        select(fields) {
+            // The predicate is what carries the literal key type through `Object.keys`.
+            const keys = Object.keys(fields).filter((key) => Object.hasOwn(fields, key));
+            return builder(entity, repo, { ...state, select: keys }, (row) => {
+                const source = pick(row);
+                const picked = {};
+                for (const key of keys)
+                    picked[key] = source[key];
+                return picked;
+            });
+        },
+        page: async () => {
+            const result = await repo.findMany(args());
+            return { rows: result.rows.map(pick), nextCursor: result.nextCursor };
+        },
+        all: async () => (await repo.findMany(args())).rows.map(pick),
+        one: async () => {
+            const { rows } = await repo.findMany({ ...args(), limit: 1 });
+            const row = rows[0];
+            return row === undefined ? null : pick(row);
+        },
+        count: () => repo.count(args()),
+        plan: () => ({
+            entity: entity.$name,
+            where: state.where,
+            orderBy: state.orderBy,
+            limit: state.limit,
+            ...(state.cursor === null ? {} : { cursor: state.cursor }),
+            ...(state.select === undefined ? {} : { select: state.select }),
+        }),
+    };
+};
+/** Columns declared `onUpdateNow()` are written by the framework, never by the caller. */
+const touch = (entity, patch) => {
+    const stamped = {};
+    for (const [property, column] of Object.entries(entity.$columns)) {
+        if (column.$meta.onUpdate !== undefined)
+            stamped[property] = new Date();
+    }
+    return Object.assign({}, patch, stamped);
+};
+export const tableFor = (entity, repo) => ({
+    ...builder(entity, repo, EMPTY, (row) => row),
+    insert: (values, options) => repo.insert(entity.$parse(values), options),
+    update: (id, patch, options) => repo.update(id, touch(entity, patch), options),
+    delete: (id, options) => repo.delete(id, options),
+});
+//# sourceMappingURL=query.js.map

package/src/query.js.map

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

package/src/query.ts

@@ -0,0 +1,144 @@
+// The chainable read. Every chain terminates in a cursor page — `page()` returns rows plus the
+// cursor for the next one, and `all()`/`one()` are that page's rows. There is no `offset()` and
+// there will not be one: under concurrent writes an insert before the offset shifts every later
+// page, so a client silently skips and repeats rows.
+
+import type { EntityCore } from './entity';
+import type { Page, Repo, RepoOptions } from './repo';
+import type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';
+import type { ColumnMap, Insertable } from './types';
+
+export interface ReadBuilder<Row> {
+  /** Equality on the columns given. `where({ orgId })` is what satisfies the tenancy guard. */
+  where(filter: Partial<Row>): ReadBuilder<Row>;
+  andWhere(column: keyof Row & string, op: Operator, value: unknown): ReadBuilder<Row>;
+  orderBy(column: keyof Row & string, direction?: SortDirection): ReadBuilder<Row>;
+  limit(rows: number): ReadBuilder<Row>;
+  /** The cursor from the previous page. */
+  after(cursor: string | null): ReadBuilder<Row>;
+  select<K extends keyof Row & string>(
+    fields: { readonly [P in K]: true },
+  ): ReadBuilder<Pick<Row, K>>;
+  /** The terminal: one bounded page and the cursor that continues it. */
+  page(): Promise<Page<Row>>;
+  all(): Promise<readonly Row[]>;
+  one(): Promise<Row | null>;
+  count(): Promise<number>;
+  /** The plan this chain describes. Safe to log — `describePlan()` elides values. */
+  plan(): QueryPlan;
+}
+
+export interface Table<Row, C extends ColumnMap = ColumnMap> extends ReadBuilder<Row> {
+  insert(values: Insertable<C>, options?: RepoOptions): Promise<Row>;
+  update(id: string, patch: Partial<Row>, options?: RepoOptions): Promise<Row>;
+  delete(id: string, options?: RepoOptions): Promise<void>;
+}
+
+interface State {
+  readonly where: readonly Predicate[];
+  readonly orderBy: readonly SortKey[];
+  readonly limit: number;
+  readonly cursor: string | null;
+  readonly select: readonly string[] | undefined;
+}
+
+const EMPTY: State = { where: [], orderBy: [], limit: 50, cursor: null, select: undefined };
+
+const asRecord = (value: unknown): Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : {};
+
+const builder = <Source, Row>(
+  entity: EntityCore<Source>,
+  repo: Repo<Source>,
+  state: State,
+  pick: (row: Source) => Row,
+): ReadBuilder<Row> => {
+  const next = (patch: Partial<State>): ReadBuilder<Row> =>
+    builder(entity, repo, { ...state, ...patch }, pick);
+
+  const args = () => ({
+    where: state.where,
+    orderBy: state.orderBy,
+    limit: state.limit,
+    cursor: state.cursor,
+    ...(state.select === undefined ? {} : { select: state.select }),
+  });
+
+  return {
+    where: (filter) =>
+      next({
+        where: [
+          ...state.where,
+          ...Object.entries(asRecord(filter)).map(
+            ([column, value]): Predicate => ({ column, op: 'eq', value }),
+          ),
+        ],
+      }),
+
+    andWhere: (column, op, value) => next({ where: [...state.where, { column, op, value }] }),
+
+    orderBy: (column, direction = 'asc') =>
+      next({ orderBy: [...state.orderBy, { column, direction }] }),
+
+    limit: (rows) => next({ limit: rows }),
+
+    after: (cursor) => next({ cursor }),
+
+    select<K extends keyof Row & string>(fields: { readonly [P in K]: true }) {
+      // The predicate is what carries the literal key type through `Object.keys`.
+      const keys = Object.keys(fields).filter((key): key is K => Object.hasOwn(fields, key));
+      return builder<Source, Pick<Row, K>>(entity, repo, { ...state, select: keys }, (row) => {
+        const source = pick(row);
+        const picked = {} as Pick<Row, K>;
+        for (const key of keys) picked[key] = source[key];
+        return picked;
+      });
+    },
+
+    page: async () => {
+      const result = await repo.findMany(args());
+      return { rows: result.rows.map(pick), nextCursor: result.nextCursor };
+    },
+
+    all: async () => (await repo.findMany(args())).rows.map(pick),
+
+    one: async () => {
+      const { rows } = await repo.findMany({ ...args(), limit: 1 });
+      const row = rows[0];
+      return row === undefined ? null : pick(row);
+    },
+
+    count: () => repo.count(args()),
+
+    plan: (): QueryPlan => ({
+      entity: entity.$name,
+      where: state.where,
+      orderBy: state.orderBy,
+      limit: state.limit,
+      ...(state.cursor === null ? {} : { cursor: state.cursor }),
+      ...(state.select === undefined ? {} : { select: state.select }),
+    }),
+  };
+};
+
+/** Columns declared `onUpdateNow()` are written by the framework, never by the caller. */
+const touch = <Row>(entity: EntityCore<Row>, patch: Partial<Row>): Partial<Row> => {
+  const stamped: Record<string, unknown> = {};
+  for (const [property, column] of Object.entries(entity.$columns)) {
+    if (column.$meta.onUpdate !== undefined) stamped[property] = new Date();
+  }
+  return Object.assign({}, patch, stamped);
+};
+
+// Every write is `async`, matching the repository contract: a failing call rejects and never
+// throws synchronously. `$parse` throws — without the wrapper, a bad row escapes at call time
+// while a bad id rejects, and every call site would need two error paths for one mistake.
+export const tableFor = <Row, C extends ColumnMap>(
+  entity: EntityCore<Row, C>,
+  repo: Repo<Row>,
+): Table<Row, C> => ({
+  ...builder<Row, Row>(entity, repo, EMPTY, (row) => row),
+  insert: async (values, options) => repo.insert(entity.$parse(values), options),
+  update: async (id, patch, options) => repo.update(id, touch(entity, patch), options),
+  delete: async (id, options) => repo.delete(id, options),
+});

package/src/registry.d.ts

@@ -0,0 +1,45 @@
+import type { InvariantKind } from './invariants';
+export interface ColumnDescription {
+    readonly property: string;
+    readonly column: string;
+    readonly kind: string;
+    readonly notNull: boolean;
+    readonly primaryKey: boolean;
+    readonly unique: boolean;
+    readonly hasDefault: boolean;
+    readonly check: string | null;
+    readonly references: string | null;
+}
+export interface InvariantDescription {
+    readonly name: string;
+    readonly kind: InvariantKind;
+    readonly message: string;
+    /** `null` for an `assert`: a JS predicate the database was never told about. */
+    readonly sql: string | null;
+    readonly where: string | null;
+}
+export interface EntityDescription {
+    readonly name: string;
+    readonly table: string;
+    readonly primaryKey: readonly string[];
+    readonly columns: readonly ColumnDescription[];
+    readonly invariants: readonly InvariantDescription[];
+    readonly indexes: readonly string[];
+    readonly tags: readonly string[];
+    readonly cacheTag: string;
+    readonly softDelete: boolean;
+    readonly orgScoped: boolean;
+}
+export interface RegistryEntry {
+    readonly name: string;
+    readonly tableName: string;
+    describe(): EntityDescription;
+}
+export declare const registerEntity: <E extends RegistryEntry>(entry: E) => E;
+export declare const getEntity: (name: string) => RegistryEntry | undefined;
+export declare const entityNames: () => readonly string[];
+/** Deterministic order: the manifest is a build artefact and must diff cleanly. */
+export declare const describeEntities: () => readonly EntityDescription[];
+/** Test seam. Production code never unregisters an entity. */
+export declare const clearRegistry: () => void;
+//# sourceMappingURL=registry.d.ts.map

package/src/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["registry.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACrD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,IAAI,iBAAiB,CAAC;CAC/B;AAID,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,aAAa,SAAS,CAAC,KAAG,CAOlE,CAAC;AAEF,eAAO,MAAM,SAAS,SAAU,MAAM,KAAG,aAAa,GAAG,SAA+B,CAAC;AAEzF,eAAO,MAAM,WAAW,QAAO,SAAS,MAAM,EAAiC,CAAC;AAEhF,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,QAAO,SAAS,iBAAiB,EAK1D,CAAC;AAEL,8DAA8D;AAC9D,eAAO,MAAM,aAAa,QAAO,IAAwB,CAAC"}

package/src/registry.js

@@ -0,0 +1,26 @@
+// The entity registry. Every `entity()` call registers here, which is what makes
+// `x.manifest.json`, the admin dashboard generator and the migration emitter able to see the
+// whole domain without importing it — and what makes a duplicate name a build error rather
+// than a silent last-one-wins.
+import { entityDuplicate } from './errors';
+const entities = new Map();
+export const registerEntity = (entry) => {
+    const existing = entities.get(entry.name);
+    if (existing !== undefined && existing !== entry) {
+        throw entityDuplicate(entry.name, existing.tableName);
+    }
+    entities.set(entry.name, entry);
+    return entry;
+};
+export const getEntity = (name) => entities.get(name);
+export const entityNames = () => [...entities.keys()].sort();
+/** Deterministic order: the manifest is a build artefact and must diff cleanly. */
+export const describeEntities = () => entityNames().map((name) => {
+    const entry = entities.get(name);
+    if (entry === undefined)
+        throw entityDuplicate(name, 'unknown');
+    return entry.describe();
+});
+/** Test seam. Production code never unregisters an entity. */
+export const clearRegistry = () => entities.clear();
+//# sourceMappingURL=registry.js.map

package/src/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["registry.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,6FAA6F;AAC7F,2FAA2F;AAC3F,+BAA+B;AAE/B,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AA2C3C,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAyB,CAAC;AAElD,MAAM,CAAC,MAAM,cAAc,GAAG,CAA0B,KAAQ,EAAK,EAAE;IACrE,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;QACjD,MAAM,eAAe,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;IACxD,CAAC;IACD,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAChC,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,IAAY,EAA6B,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAEzF,MAAM,CAAC,MAAM,WAAW,GAAG,GAAsB,EAAE,CAAC,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAEhF,mFAAmF;AACnF,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAiC,EAAE,CACjE,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;IACzB,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,eAAe,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAChE,OAAO,KAAK,CAAC,QAAQ,EAAE,CAAC;AAC1B,CAAC,CAAC,CAAC;AAEL,8DAA8D;AAC9D,MAAM,CAAC,MAAM,aAAa,GAAG,GAAS,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC"}

package/src/registry.ts

@@ -1,8 +1,10 @@
 // The entity registry. Every `entity()` call registers here, which is what makes
-// `x.manifest.json`, the admin dashboard generator and the migration emitter able to
-// see the whole domain without importing it — and what makes a duplicate name a
-// build error rather than a silent last-one-wins.
+// `x.manifest.json`, the admin dashboard generator and the migration emitter able to see the
+// whole domain without importing it — and what makes a duplicate name a build error rather
+// than a silent last-one-wins.
+
 import { entityDuplicate } from './errors';
+import type { InvariantKind } from './invariants';
 
 export interface ColumnDescription {
   readonly property: string;
@@ -18,9 +20,10 @@ export interface ColumnDescription {
 
 export interface InvariantDescription {
   readonly name: string;
-  readonly kind: 'check' | 'unique';
+  readonly kind: InvariantKind;
   readonly message: string;
-  readonly sql: string;
+  /** `null` for an `assert`: a JS predicate the database was never told about. */
+  readonly sql: string | null;
   readonly where: string | null;
 }
 

package/src/repo.d.ts

@@ -0,0 +1,54 @@
+import type { EntityCore } from './entity';
+import type { Predicate, SortKey } from './tenancy';
+export interface Tx {
+    readonly id: string;
+    /** Registered by drivers so a failed transaction can undo in-memory effects. */
+    onRollback(undo: () => void): void;
+}
+export interface RepoOptions {
+    readonly tx?: Tx;
+    /** Required for tenant-scoped entities; the guard throws without it. */
+    readonly orgId?: string;
+}
+export interface FindManyArgs extends RepoOptions {
+    readonly where?: readonly Predicate[];
+    readonly orderBy?: readonly SortKey[];
+    readonly limit?: number;
+    readonly cursor?: string | null;
+    readonly includeDeleted?: boolean;
+    readonly select?: readonly string[];
+}
+export interface Page<T> {
+    readonly rows: readonly T[];
+    /** Pass back as `cursor`. `null` means this was the last page. */
+    readonly nextCursor: string | null;
+}
+/**
+ * `T` defaults to `unknown` so a row-agnostic consumer (the generated admin, the manifest
+ * emitter) can name the shape without knowing the entity.
+ */
+export interface Repo<T = unknown> {
+    findById(id: string, options?: RepoOptions): Promise<T | null>;
+    findMany(args?: FindManyArgs): Promise<Page<T>>;
+    insert(values: T, options?: RepoOptions): Promise<T>;
+    update(id: string, patch: Partial<T>, options?: RepoOptions): Promise<T>;
+    delete(id: string, options?: RepoOptions): Promise<void>;
+    count(args?: FindManyArgs): Promise<number>;
+}
+export interface Transactor {
+    run<R>(work: (tx: Tx) => Promise<R>): Promise<R>;
+}
+export declare const encodeCursor: (key: string, id: string) => string;
+export declare const decodeCursor: (cursor: string) => {
+    key: string;
+    id: string;
+} | null;
+/**
+ * The default driver: correct semantics, no database. `x dev` uses it before the first
+ * migration and tests use it everywhere. Postgres is the production driver and implements
+ * this same interface.
+ */
+export declare const memoryRepo: <Row>(entity: EntityCore<Row>, seed?: readonly Row[]) => Repo<Row>;
+/** In-memory transactor: undo closures registered by drivers run on failure. */
+export declare const memoryTransactor: () => Transactor;
+//# sourceMappingURL=repo.d.ts.map

package/src/repo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["repo.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,OAAO,KAAK,EAAE,SAAS,EAAa,OAAO,EAAE,MAAM,WAAW,CAAC;AAG/D,MAAM,WAAW,EAAE;IACjB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,UAAU,CAAC,IAAI,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;IACjB,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,IAAI,CAAC,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,IAAI,CAAC,CAAC,GAAG,OAAO;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACrD,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACzE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,KAAK,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAClD;AAED,eAAO,MAAM,YAAY,QAAS,MAAM,MAAM,MAAM,KAAG,MACjB,CAAC;AAEvC,eAAO,MAAM,YAAY,WAAY,MAAM,KAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,IAS3E,CAAC;AAiDF;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,GAAG,UAAU,UAAU,CAAC,GAAG,CAAC,SAAQ,SAAS,GAAG,EAAE,KAAQ,IAAI,CAAC,GAAG,CAoI5F,CAAC;AAIF,gFAAgF;AAChF,eAAO,MAAM,gBAAgB,QAAO,UAYlC,CAAC"}