@ultimat3/entity 0.0.1 → 1.0.0

package/src/invariants.js

@@ -0,0 +1,53 @@
+// A domain invariant is written once and enforced twice: in the app on every write, and in
+// Postgres as a CHECK or a unique index emitted into the migration. The database can therefore
+// never disagree with the code — a bulk import, a psql session or a second service all hit the
+// same rule.
+//
+// `invariant()` is unbound on purpose: it is written next to the columns, and `entity()` binds
+// it to their physical names. That is what keeps a physical name from being typed twice.
+import { invariantViolated } from './errors';
+/** `invariant('post_like_count_non_negative', (c) => c.likeCount.atLeast(0))` */
+export const invariant = (name, build) => ({ name, build });
+const asRow = (value) => typeof value === 'object' && value !== null ? value : {};
+/** Called by `entity()`: resolves property paths to physical names and freezes the rule. */
+export const bindInvariant = (def, columns, resolve, partialWhere) => {
+    const expr = def.build(columns);
+    const sql = expr.toSql(resolve);
+    const kind = expr.kind === 'unique' ? 'unique' : sql === null ? 'assert' : 'check';
+    return {
+        name: def.name,
+        kind,
+        message: expr.message,
+        sql,
+        columns: expr.paths.map(resolve),
+        // A soft-deleted row must not keep a slug reserved, so uniqueness is partial there.
+        ...(kind === 'unique' && partialWhere !== undefined ? { where: partialWhere } : {}),
+        holds: (row) => expr.holds(asRow(row)),
+    };
+};
+export const constraintName = (table, inv) => `${table}_${inv.name}_${inv.kind === 'unique' ? 'key' : 'check'}`;
+/** The DDL the migration emits. One statement, terminated, ready to diff. */
+export const toSql = (table, inv) => {
+    if (inv.sql === null)
+        return null;
+    const name = constraintName(table, inv);
+    if (inv.kind === 'check') {
+        return `ALTER TABLE "${table}" ADD CONSTRAINT "${name}" CHECK (${inv.sql});`;
+    }
+    const where = inv.where === undefined ? '' : ` WHERE ${inv.where}`;
+    const columns = inv.columns.map((column) => `"${column}"`).join(', ');
+    return `CREATE UNIQUE INDEX "${name}" ON "${table}" (${columns})${where};`;
+};
+export const invariantsToSql = (table, invariants) => invariants
+    .map((inv) => toSql(table, inv))
+    .filter((statement) => statement !== null)
+    .join('\n');
+/** Runs on every write. Reports every violation at once so one round trip fixes all. */
+export const assertInvariants = (entityName, invariants, row) => {
+    const failed = invariants.filter((inv) => !inv.holds(row));
+    const first = failed[0];
+    if (first === undefined)
+        return;
+    throw invariantViolated(entityName, first.name, failed.map((inv) => inv.message).join('; '));
+};
+//# sourceMappingURL=invariants.js.map

package/src/invariants.js.map

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

package/src/invariants.ts

@@ -1,10 +1,16 @@
-// A domain invariant is written once and enforced twice: in the app on every write,
-// and in Postgres as a CHECK or UNIQUE constraint emitted into the migration. The
-// database can therefore never disagree with the code — a bulk import, a psql
-// session or a second service all hit the same rule.
+// A domain invariant is written once and enforced twice: in the app on every write, and in
+// Postgres as a CHECK or a unique index emitted into the migration. The database can therefore
+// never disagree with the code — a bulk import, a psql session or a second service all hit the
+// same rule.
+//
+// `invariant()` is unbound on purpose: it is written next to the columns, and `entity()` binds
+// it to their physical names. That is what keeps a physical name from being typed twice.
+
 import { invariantViolated } from './errors';
+import type { Expr, InvariantColumns, Resolve, Row } from './expr';
 
-export type InvariantKind = 'check' | 'unique';
+/** `assert` is a rule only the app can run — a JS predicate with no SQL translation. */
+export type InvariantKind = 'check' | 'unique' | 'assert';
 
 export interface Invariant<T> {
   /** Becomes the constraint name: `<table>_<name>_check`. Keep it snake_case. */
@@ -12,64 +18,60 @@ export interface Invariant<T> {
   readonly kind: InvariantKind;
   /** Safe to log and useful to an agent: says what was expected, not what leaked. */
   readonly message: string;
-  /** SQL predicate for `check`, or the column list for `unique`. */
-  readonly sql: string;
+  /** SQL predicate for `check`, the column list for `unique`, `null` for `assert`. */
+  readonly sql: string | null;
+  /** Physical column names the rule reads. */
   readonly columns: readonly string[];
   /** Partial-constraint predicate, e.g. `deleted_at is null`. */
   readonly where?: string;
   readonly holds: (row: T) => boolean;
 }
 
-export interface CheckInit<T> {
-  readonly message: string;
-  /** Postgres predicate over physical column names. */
-  readonly sql: string;
-  readonly holds: (row: T) => boolean;
-  readonly columns?: readonly string[];
-  readonly where?: string;
+/** What `invariant()` returns: a rule that does not yet know its physical column names. */
+export interface InvariantDef {
+  readonly name: string;
+  readonly build: (columns: InvariantColumns) => Expr;
 }
 
-/** `invariant('price_positive', { sql: 'price_minor > 0', holds: (p) => p.priceMinor > 0n })` */
-export const invariant = <T>(name: string, init: CheckInit<T>): Invariant<T> => ({
-  name,
-  kind: 'check',
-  message: init.message,
-  sql: init.sql,
-  columns: init.columns ?? [],
-  ...(init.where === undefined ? {} : { where: init.where }),
-  holds: init.holds,
-});
+/** `invariant('post_like_count_non_negative', (c) => c.likeCount.atLeast(0))` */
+export const invariant = (
+  name: string,
+  build: (columns: InvariantColumns) => Expr,
+): InvariantDef => ({ name, build });
 
-export interface UniqueInit<T> {
-  readonly message: string;
-  readonly columns: readonly string[];
-  /** In-app duplicate detection needs the store, so the app check defaults to true. */
-  readonly holds?: (row: T) => boolean;
-  readonly where?: string;
-}
+const asRow = (value: unknown): Row =>
+  typeof value === 'object' && value !== null ? (value as Row) : {};
 
-/**
- * Uniqueness cannot be decided from a single row, so the app-side check is a no-op
- * by default and the database is the authority. The unique index is still declared
- * here so it lives next to the rule it implements.
- */
-export const unique = <T>(name: string, init: UniqueInit<T>): Invariant<T> => ({
-  name,
-  kind: 'unique',
-  message: init.message,
-  sql: init.columns.join(', '),
-  columns: init.columns,
-  ...(init.where === undefined ? {} : { where: init.where }),
-  holds: init.holds ?? (() => true),
-});
+/** Called by `entity()`: resolves property paths to physical names and freezes the rule. */
+export const bindInvariant = <T>(
+  def: InvariantDef,
+  columns: InvariantColumns,
+  resolve: Resolve,
+  partialWhere: string | undefined,
+): Invariant<T> => {
+  const expr = def.build(columns);
+  const sql = expr.toSql(resolve);
+  const kind: InvariantKind = expr.kind === 'unique' ? 'unique' : sql === null ? 'assert' : 'check';
+  return {
+    name: def.name,
+    kind,
+    message: expr.message,
+    sql,
+    columns: expr.paths.map(resolve),
+    // A soft-deleted row must not keep a slug reserved, so uniqueness is partial there.
+    ...(kind === 'unique' && partialWhere !== undefined ? { where: partialWhere } : {}),
+    holds: (row) => expr.holds(asRow(row)),
+  };
+};
 
 export const constraintName = (
   table: string,
   inv: { readonly name: string; readonly kind: InvariantKind },
-): string => `${table}_${inv.name}_${inv.kind === 'check' ? 'check' : 'key'}`;
+): string => `${table}_${inv.name}_${inv.kind === 'unique' ? 'key' : 'check'}`;
 
 /** The DDL the migration emits. One statement, terminated, ready to diff. */
-export const toSql = <T>(table: string, inv: Invariant<T>): string => {
+export const toSql = <T>(table: string, inv: Invariant<T>): string | null => {
+  if (inv.sql === null) return null;
   const name = constraintName(table, inv);
   if (inv.kind === 'check') {
     return `ALTER TABLE "${table}" ADD CONSTRAINT "${name}" CHECK (${inv.sql});`;
@@ -80,7 +82,10 @@ export const toSql = <T>(table: string, inv: Invariant<T>): string => {
 };
 
 export const invariantsToSql = <T>(table: string, invariants: readonly Invariant<T>[]): string =>
-  invariants.map((inv) => toSql(table, inv)).join('\n');
+  invariants
+    .map((inv) => toSql(table, inv))
+    .filter((statement): statement is string => statement !== null)
+    .join('\n');
 
 /** Runs on every write. Reports every violation at once so one round trip fixes all. */
 export const assertInvariants = <T>(
@@ -89,7 +94,6 @@ export const assertInvariants = <T>(
   row: T,
 ): void => {
   const failed = invariants.filter((inv) => !inv.holds(row));
-  if (failed.length === 0) return;
   const first = failed[0];
   if (first === undefined) return;
   throw invariantViolated(entityName, first.name, failed.map((inv) => inv.message).join('; '));

package/src/pg-driver.ts

@@ -0,0 +1,154 @@
+// The production driver. Same `Repo` contract as `memoryRepo`, same plans, same cursor — the
+// only difference is where the rows are, which is the point: a test that passes against memory
+// means something about Postgres.
+//
+// It never takes a connection as an argument. `db()` from `@ultimat3/db` returns the open
+// transaction when there is one, so a repository call inside `withTransaction` joins it without
+// being told — which is how `ctx.jobs.enqueue()` lands its outbox row atomically with the write
+// that caused it. `RepoOptions.tx` is the in-memory driver's undo hook and is ignored here.
+
+import { type DbClient, db, type TransactionOptions, withTransaction } from '@ultimat3/db';
+import { snake } from './column';
+import { cursorFor, seekFrom, valueAt } from './cursor';
+import type { Driver } from './database';
+import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
+import { notFound } from './errors';
+import { bindValues, decodeRow, type PhysicalRow } from './pg-row';
+import {
+  countStatement,
+  deleteStatement,
+  insertStatement,
+  type ReadShape,
+  selectStatement,
+  updateStatement,
+} from './pg-sql';
+import { idPlan, readPlan } from './plan';
+import type { FindManyArgs, Repo, Transactor } from './repo';
+import type { QueryPlan } from './tenancy';
+
+export interface PostgresDriverOptions {
+  /**
+   * Pin a client. Left out, every call resolves `db()` — the ambient pool, or the open
+   * transaction when one is in scope. Tests pass `createRecordingClient()` here or install one
+   * globally with `setDbClient()`.
+   */
+  readonly client?: DbClient | undefined;
+}
+
+const shapeOf = (args: FindManyArgs, seek?: readonly unknown[]): ReadShape => ({
+  includeDeleted: args.includeDeleted === true,
+  ...(seek === undefined ? {} : { seek }),
+});
+
+export const postgresRepo = <Row>(
+  entity: EntityCore<Row>,
+  config: PostgresDriverOptions = {},
+): Repo<Row> => {
+  const client = (): DbClient => config.client ?? db();
+  const idOf = (row: Row): string =>
+    entity.$primaryKey.map((property) => String(valueAt(row, property))).join('');
+
+  const one = async (plan: QueryPlan, args: FindManyArgs): Promise<Row | null> => {
+    const [found] = await client().query<PhysicalRow>(
+      selectStatement(entity, plan, shapeOf(args), 1),
+    );
+    return found === undefined ? null : decodeRow(entity, found);
+  };
+
+  return {
+    async findById(id, options) {
+      const plan = idPlan(entity, id, options, 'findById');
+      return one(plan, options ?? {});
+    },
+
+    async findMany(args = {}) {
+      const plan = readPlan(entity, args, 'findMany');
+      // One row past the page: the presence of that row is what says there is a next cursor,
+      // and it costs one row instead of a second `count(*)` over the same predicate.
+      const found = await client().query<PhysicalRow>(
+        selectStatement(entity, plan, shapeOf(args, seekFrom(entity, plan)), plan.limit + 1),
+      );
+      const rows = found.slice(0, plan.limit).map((row) => decodeRow(entity, row));
+      const last = rows.at(-1);
+      return {
+        rows,
+        nextCursor:
+          found.length > plan.limit && last !== undefined
+            ? cursorFor(entity, plan, last, idOf(last))
+            : null,
+      };
+    },
+
+    async insert(values) {
+      entity.$assert(values);
+      const written = await client().one<PhysicalRow>(
+        insertStatement(entity, bindValues(entity, values)),
+      );
+      // `returning *` is the row Postgres actually stored, defaults included.
+      return written === null ? values : decodeRow(entity, written);
+    },
+
+    async update(id, patch, options) {
+      const plan = idPlan(entity, id, options, 'update');
+      const values = bindValues(entity, patch);
+      if (values.size === 0) {
+        const current = await one(plan, options ?? {});
+        if (current === null) throw notFound(entity.$name, id);
+        return current;
+      }
+      const written = await client().one<PhysicalRow>(
+        updateStatement(entity, plan, values, shapeOf(options ?? {})),
+      );
+      if (written === null) throw notFound(entity.$name, id);
+      const after = decodeRow(entity, written);
+      // SQL-expressible invariants are CHECK constraints, so Postgres already rejected the
+      // statement. A JS-only one (`kind: 'assert'`, `sql: null`) can only be judged on the
+      // result — inside `withTransaction` the throw takes the row with it.
+      entity.$assert(after);
+      return after;
+    },
+
+    async delete(id, options) {
+      const plan = idPlan(entity, id, options, 'delete');
+      // Soft delete hides the row without losing it; the column's presence is the switch.
+      const statement = entity.$softDelete
+        ? updateStatement(
+            entity,
+            plan,
+            new Map([[snake(SOFT_DELETE_COLUMN), new Date()]]),
+            shapeOf({}),
+          )
+        : deleteStatement(entity, plan);
+      if ((await client().execute(statement)) === 0) throw notFound(entity.$name, id);
+    },
+
+    async count(args = {}) {
+      const plan = readPlan(entity, args, 'count');
+      const row = await client().one<{ count: unknown }>(
+        countStatement(entity, plan, shapeOf(args)),
+      );
+      return Number(row?.count ?? 0);
+    },
+  };
+};
+
+/**
+ * `database(entities, { driver: postgresDriver() })` — the one line that moves an app off the
+ * in-memory default. Repos are stateless, so there is nothing to memoise.
+ */
+export const postgresDriver = (config: PostgresDriverOptions = {}): Driver => ({
+  repo: <Row>(entity: EntityCore<Row>) => postgresRepo(entity, config),
+});
+
+/**
+ * A real Postgres transaction behind the same `Transactor` the in-memory one implements. The
+ * `Tx` handed to the callback is a token: repositories find the transaction through `db()`, so
+ * nothing has to thread a connection through the call stack.
+ */
+export const postgresTransactor = (options: TransactionOptions = {}): Transactor => ({
+  run: (work) =>
+    withTransaction(
+      (tx) => work({ id: tx.id, onRollback: (undo: () => void) => tx.onRollback(undo) }),
+      options,
+    ),
+});

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,
+  })}`;