@ultimat3/entity 0.0.1 → 1.1.0

package/src/pg-row.ts

@@ -0,0 +1,110 @@
+// Single responsibility: the two-way map between a physical Postgres row and an entity row.
+// Three things are not one-to-one and all three live here: the property key is camelCase while
+// the column is snake_case, money is one property over two columns, and a value that came back
+// from the driver is re-parsed by the column that declared it rather than trusted — int8 arrives
+// as a string, timestamptz may arrive as one, and a silent `NaN` is worse than a loud throw.
+
+import { snake } from './column';
+import type { EntityCore } from './entity';
+import { invariantViolated } from './errors';
+import type { AnyColumn, MoneyValue } from './types';
+
+export type PhysicalRow = Readonly<Record<string, unknown>>;
+
+const MONEY_PARTS = new Set(['minor', 'currency']);
+
+/** `price` -> `price_minor`, `price_currency`. Everything else is one snake_case column. */
+export const columnsOf = (property: string, column: AnyColumn): readonly string[] =>
+  column.$meta.kind === 'money'
+    ? [`${snake(property)}_minor`, `${snake(property)}_currency`]
+    : [snake(property)];
+
+/**
+ * A predicate or sort key names a property, never a physical column — so `orgId` becomes
+ * `org_id` in exactly one place, and a name the entity never declared cannot reach the SQL.
+ */
+export const physicalName = <Row>(entity: EntityCore<Row>, path: string): string => {
+  const [property = path, part] = path.split('.');
+  const column = entity.$columns[property];
+  if (column === undefined) {
+    throw invariantViolated(
+      entity.$name,
+      'column',
+      `no column "${path}" — pick from: ${Object.keys(entity.$columns).join(', ')}`,
+    );
+  }
+  const isMoney = column.$meta.kind === 'money';
+  if (part === undefined) {
+    if (!isMoney) return snake(property);
+    throw invariantViolated(
+      entity.$name,
+      property,
+      `${property} is money: name ${property}.minor or ${property}.currency`,
+    );
+  }
+  if (!isMoney || !MONEY_PARTS.has(part)) {
+    throw invariantViolated(entity.$name, property, `${property} has no part "${part}"`);
+  }
+  return `${snake(property)}_${part}`;
+};
+
+/** Every physical column of the entity, in declaration order. */
+export const allColumns = <Row>(entity: EntityCore<Row>): readonly string[] =>
+  Object.entries(entity.$columns).flatMap(([property, column]) => columnsOf(property, column));
+
+/**
+ * Row (or patch) -> the columns to write. Absent properties are skipped rather than nulled,
+ * which is what makes the same function serve `insert` and a partial `update`.
+ */
+export const bindValues = <Row>(
+  entity: EntityCore<Row>,
+  values: Partial<Row>,
+): ReadonlyMap<string, unknown> => {
+  const bound = new Map<string, unknown>();
+  const record = values as Readonly<Record<string, unknown>>;
+  for (const [property, column] of Object.entries(entity.$columns)) {
+    if (!Object.hasOwn(record, property)) continue;
+    const value = record[property];
+    if (column.$meta.kind !== 'money') {
+      bound.set(snake(property), value ?? null);
+      continue;
+    }
+    const money = value as MoneyValue | null | undefined;
+    bound.set(`${snake(property)}_minor`, money?.minor ?? null);
+    bound.set(`${snake(property)}_currency`, money?.currency ?? null);
+  }
+  return bound;
+};
+
+const moneyOf = (source: PhysicalRow, minor: string, currency: string): unknown => {
+  const amount = source[minor];
+  if (amount === null || amount === undefined) return null;
+  return { minor: amount, currency: String(source[currency] ?? '').trim() };
+};
+
+/**
+ * Physical row -> entity row. A column the projection left out is left out here too, so a
+ * `select` narrows the object as well as the statement.
+ */
+export const decodeRow = <Row>(entity: EntityCore<Row>, source: PhysicalRow): Row => {
+  const row: Record<string, unknown> = {};
+  for (const [property, column] of Object.entries(entity.$columns)) {
+    const [head, tail] = columnsOf(property, column);
+    if (head === undefined || !(head in source)) continue;
+    const value = tail === undefined ? source[head] : moneyOf(source, head, tail);
+    if (value !== null && value !== undefined) {
+      row[property] = column.$parse(value);
+      continue;
+    }
+    if (column.$meta.notNull) {
+      throw invariantViolated(
+        entity.$name,
+        property,
+        'the database returned null for a not-null column — the table no longer matches the entity',
+      );
+    }
+    row[property] = null;
+  }
+  // Every property present was validated by the column that declared it, so this is the row.
+  return row as Row;
+};

package/src/pg-sql.ts

@@ -0,0 +1,162 @@
+// Single responsibility: compile a `QueryPlan` into parameterised SQL. Nothing here builds a
+// string from a value — `sql` binds every scalar to `$n` and refuses anything else — and every
+// identifier is resolved through the entity, so a column name can only ever be one the entity
+// declared. That is the whole reason this file exists instead of a template literal per method.
+
+import { identifier, join, raw, type SqlFragment, sql } from '@ultimat3/db';
+import { snake } from './column';
+import type { EntityCore } from './entity';
+import { SOFT_DELETE_COLUMN } from './entity';
+import { allColumns, columnsOf, physicalName } from './pg-row';
+import type { Predicate, QueryPlan, SortKey } from './tenancy';
+
+/** Nothing matches. `in ()` is a syntax error in Postgres, so an empty set needs a constant. */
+const NEVER = sql`1 = 0`;
+
+export interface ReadShape {
+  /** Soft-deleted rows are hidden unless the caller asked for them. */
+  readonly includeDeleted: boolean;
+  /** The keyset position, already revived to typed values. */
+  readonly seek?: readonly unknown[] | undefined;
+}
+
+const columnRef = <Row>(entity: EntityCore<Row>, path: string): SqlFragment =>
+  identifier(physicalName(entity, path));
+
+const predicateSql = <Row>(entity: EntityCore<Row>, predicate: Predicate): SqlFragment => {
+  const column = columnRef(entity, predicate.column);
+  const value = predicate.value;
+  switch (predicate.op) {
+    case 'eq':
+      return value === null ? sql`${column} is null` : sql`${column} = ${value}`;
+    case 'neq':
+      // `is distinct from` so a null on either side compares as a value, not as unknown.
+      return sql`${column} is distinct from ${value}`;
+    case 'in': {
+      const values = Array.isArray(value) ? value : [value];
+      return values.length === 0
+        ? NEVER
+        : sql`${column} in (${join(values.map((each) => sql`${each}`))})`;
+    }
+    case 'gt':
+      return sql`${column} > ${value}`;
+    case 'gte':
+      return sql`${column} >= ${value}`;
+    case 'lt':
+      return sql`${column} < ${value}`;
+    case 'lte':
+      return sql`${column} <= ${value}`;
+    case 'like':
+      return sql`${column} like ${value}`;
+    case 'is-null':
+      return sql`${column} is null`;
+    case 'is-not-null':
+      return sql`${column} is not null`;
+  }
+};
+
+/**
+ * The keyset seek, spelled out rather than as a row comparison: `(a, b) > (x, y)` requires every
+ * key to sort the same way, and a listing that is `published_at desc, id asc` does not.
+ */
+const seekSql = <Row>(
+  entity: EntityCore<Row>,
+  orderBy: readonly SortKey[],
+  seek: readonly unknown[],
+): SqlFragment => {
+  const terms = orderBy.map((entry, index) => {
+    const equal = orderBy
+      .slice(0, index)
+      .map((earlier, position) => sql`${columnRef(entity, earlier.column)} = ${seek[position]}`);
+    const after = raw(entry.direction === 'desc' ? '<' : '>');
+    return sql`(${join(
+      [...equal, sql`${columnRef(entity, entry.column)} ${after} ${seek[index]}`],
+      ' and ',
+    )})`;
+  });
+  return sql`(${join(terms, ' or ')})`;
+};
+
+const conditions = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  shape: ReadShape,
+): SqlFragment => {
+  const parts = plan.where.map((predicate) => predicateSql(entity, predicate));
+  if (entity.$softDelete && !shape.includeDeleted) {
+    parts.push(sql`${identifier(snake(SOFT_DELETE_COLUMN))} is null`);
+  }
+  if (shape.seek !== undefined) parts.push(seekSql(entity, plan.orderBy, shape.seek));
+  return parts.length === 0 ? sql`true` : join(parts, ' and ');
+};
+
+const orderSql = <Row>(entity: EntityCore<Row>, orderBy: readonly SortKey[]): SqlFragment =>
+  join(
+    orderBy.map(
+      (entry) =>
+        sql`${columnRef(entity, entry.column)} ${raw(entry.direction === 'desc' ? 'desc' : 'asc')}`,
+    ),
+  );
+
+/**
+ * A projection always carries the primary key and the sort keys even when the caller did not
+ * ask for them: without those values the page cannot produce the cursor that continues it.
+ */
+const projection = <Row>(entity: EntityCore<Row>, plan: QueryPlan): SqlFragment => {
+  if (plan.select === undefined) return join(allColumns(entity).map(identifier));
+  const wanted = new Set([
+    ...plan.select,
+    ...entity.$primaryKey,
+    ...plan.orderBy.map((entry) => entry.column.split('.')[0] ?? entry.column),
+  ]);
+  const names = [...wanted].flatMap((property) => {
+    const column = entity.$columns[property];
+    return column === undefined ? [] : columnsOf(property, column);
+  });
+  return join(names.map(identifier));
+};
+
+export const selectStatement = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  shape: ReadShape,
+  limit: number,
+): SqlFragment =>
+  sql`select ${projection(entity, plan)} from ${identifier(entity.$table)} where ${conditions(
+    entity,
+    plan,
+    shape,
+  )} order by ${orderSql(entity, plan.orderBy)} limit ${limit}`;
+
+export const countStatement = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  shape: ReadShape,
+): SqlFragment =>
+  sql`select count(*) as count from ${identifier(entity.$table)} where ${conditions(entity, plan, shape)}`;
+
+export const insertStatement = <Row>(
+  entity: EntityCore<Row>,
+  values: ReadonlyMap<string, unknown>,
+): SqlFragment => {
+  const entries = [...values];
+  return sql`insert into ${identifier(entity.$table)} (${join(
+    entries.map(([column]) => identifier(column)),
+  )}) values (${join(entries.map(([, value]) => sql`${value}`))}) returning *`;
+};
+
+export const updateStatement = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  values: ReadonlyMap<string, unknown>,
+  shape: ReadShape,
+): SqlFragment =>
+  sql`update ${identifier(entity.$table)} set ${join(
+    [...values].map(([column, value]) => sql`${identifier(column)} = ${value}`),
+  )} where ${conditions(entity, plan, shape)} returning *`;
+
+/** Only reached when the entity has no soft-delete column, so there is no filter to apply. */
+export const deleteStatement = <Row>(entity: EntityCore<Row>, plan: QueryPlan): SqlFragment =>
+  sql`delete from ${identifier(entity.$table)} where ${conditions(entity, plan, {
+    includeDeleted: true,
+  })}`;

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.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.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/seed.ts

@@ -0,0 +1,69 @@
+// A seed is the fixture graph, written once and replayed anywhere. `id('post:tenancy')` is a
+// UUID v5 of the label, so the same row gets the same id on every machine and a bug reproduced
+// locally reproduces in CI. Rows go through `entity.$parse` and the invariants, which makes a
+// seed a test of the schema as well as data for one.
+
+import { createHash } from 'node:crypto';
+import type { Driver } from './database';
+import { memoryDriver } from './database';
+import type { EntityCore } from './entity';
+import type { ColumnMap, Insertable } from './types';
+
+/** Framework namespace for seed labels. Fixed forever: changing it moves every seeded id. */
+const NAMESPACE = 'a3c1f0d6-5c2b-4a3e-9f1b-6d4e7c8a9b02';
+
+const bytesOf = (uuid: string): Uint8Array =>
+  Uint8Array.from((uuid.replaceAll('-', '').match(/../g) ?? []).map((pair) => parseInt(pair, 16)));
+
+/** RFC 4122 v5: SHA-1 of namespace + name, with the version and variant bits pinned. */
+export const seedId = (label: string): string => {
+  const name = new TextEncoder().encode(label);
+  const input = new Uint8Array(16 + name.length);
+  input.set(bytesOf(NAMESPACE));
+  input.set(name, 16);
+  const digest = new Uint8Array(createHash('sha1').update(input).digest());
+  const bytes = digest.slice(0, 16);
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x50;
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+  const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20, 32),
+  ].join('-');
+};
+
+export interface SeedContext {
+  insert<Row, C extends ColumnMap>(
+    entity: EntityCore<Row, C>,
+    rows: readonly Insertable<C>[],
+  ): Promise<void>;
+  /** Deterministic id for a label. Same label, same uuid, every run. */
+  id(label: string): string;
+}
+
+export interface SeedOptions {
+  /** Defaults to a fresh in-memory driver, so a seed runs with no database at all. */
+  readonly driver?: Driver;
+}
+
+export interface Seed {
+  readonly name: string;
+  run(options?: SeedOptions): Promise<void>;
+}
+
+export const defineSeed = (name: string, build: (context: SeedContext) => Promise<void>): Seed => ({
+  name,
+  run: async (options = {}) => {
+    const driver = options.driver ?? memoryDriver();
+    await build({
+      insert: async (entity, rows) => {
+        const repo = driver.repo(entity);
+        for (const row of rows) await repo.insert(entity.$parse(row));
+      },
+      id: seedId,
+    });
+  },
+});