@ultimat3/entity 2.0.0 → 4.0.0

package/src/seed.ts

@@ -1,17 +1,28 @@
-// 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.
+// A seed is the fixture graph, written once and REPLAYED anywhere: a second run writes nothing new
+// and raises nothing. Two write verbs, because only the author knows which key identifies a row —
+// `insert` where the seed owns the id (`id('post:tenancy')` is a v5 uuid of the label, the same on
+// every machine), `upsert` where the table owns it and a natural key is all there is.
 
 import { createHash } from 'node:crypto';
+import { type Environment, resolveEnvironment } from '@ultimat3/core';
+import { entityNow } from './clock';
 import type { Driver } from './database';
 import { memoryDriver } from './database';
-import type { EntityCore } from './entity';
+import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
+import { EntityError } from './errors';
+import type { Predicate } from './tenancy';
 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';
 
+/**
+ * What a replay never overwrites, unless `preserve` says otherwise. Spelled here as a constant for
+ * the reason `SOFT_DELETE_COLUMN` is: the timestamp convention is the framework's, so the column a
+ * seed must not reset is decided once.
+ */
+const CREATED_AT_COLUMN = 'createdAt';
+
 const bytesOf = (uuid: string): Uint8Array =>
   Uint8Array.from((uuid.replaceAll('-', '').match(/../g) ?? []).map((pair) => parseInt(pair, 16)));
 
@@ -35,35 +46,294 @@ export const seedId = (label: string): string => {
   ].join('-');
 };
 
+/**
+ * Which deploys a seed belongs to, declared as DATA on the seed and never inferred from its name.
+ *
+ * `reference` is data the app is wrong without — currencies, plans, service tiers, locations — and
+ * it ships to production through this same mechanism. `dev` is fixture data, and production is the
+ * one environment it must not reach by accident. The word is the seed's; the refusal is the
+ * caller's (`x db seed`), because an app that seeds its own database from its boot code has
+ * DECIDED to (axiom 8) and a library that overruled that would break it.
+ */
+export const SEED_TIERS = ['reference', 'dev'] as const;
+
+export type SeedTier = (typeof SEED_TIERS)[number];
+
+/**
+ * The tiers a run takes when nothing asked for one: everything, except that production leaves
+ * `dev` out. `requested` is both the selection AND the consent, one word doing one job — a cluster
+ * that sets `ULTIMATE_ENV=production` on every box (staging included) still loads its dev seeds by
+ * naming the tier, instead of by lying about the environment.
+ */
+export const seedTiersFor = (
+  environment: Environment,
+  requested?: SeedTier | undefined,
+): readonly SeedTier[] => {
+  if (requested !== undefined) return [requested];
+  return environment === 'production' ? ['reference'] : [...SEED_TIERS];
+};
+
+/** What one `upsert` did. `skipped` is a row already stored with these values — no statement. */
+export type SeedWrite = 'inserted' | 'updated' | 'skipped';
+
+/** One run's tally, in the three words every seed report is built from. */
+export interface SeedMetrics {
+  inserted: number;
+  updated: number;
+  skipped: number;
+}
+
+export interface SeedKey<Row> {
+  /**
+   * The columns of the unique constraint this row is identified by — its NATURAL key, which is the
+   * only key a seed writing into an existing table can know. A target no declared constraint
+   * matches is refused by `upsertPlan` before a statement is sent (`42P10` otherwise).
+   */
+  readonly by: readonly (keyof Row & string)[];
+  /**
+   * Columns a collision leaves alone. `createdAt` by default, and that default is the point: a
+   * replay must not reset when a row first arrived. The conflict target, the primary key and the
+   * soft-delete stamp are spared by `upsertPlan` already.
+   */
+  readonly preserve?: readonly (keyof Row & string)[];
+}
+
 export interface SeedContext {
+  /**
+   * Rows whose ids the SEED chose, written in one statement and replayable by primary key: a row
+   * already stored is left exactly as it is (`on conflict … do nothing`). The bulk verb — one
+   * statement per call, not one per row.
+   */
   insert<Row, C extends ColumnMap>(
     entity: EntityCore<Row, C>,
     rows: readonly Insertable<C>[],
   ): Promise<void>;
+  /**
+   * One row whose id the TABLE owns, matched on the natural key `by` names. Reads first so the
+   * answer can be `'skipped'`, then writes with a single `on conflict … do update`, which is what
+   * settles the race between two containers booting at once — the read is for the report, never
+   * for the decision.
+   */
+  upsert<Row, C extends ColumnMap>(
+    entity: EntityCore<Row, C>,
+    key: SeedKey<Row>,
+    values: Insertable<C>,
+  ): Promise<SeedWrite>;
+  /**
+   * The other unit of idempotency: the FILE. Bulk volume data has no natural key worth upserting
+   * ten thousand rows against, so the guard is a sentinel — `if (await exists(reports)) return;`
+   * at the top of the seed.
+   */
+  exists<Row, C extends ColumnMap>(
+    entity: EntityCore<Row, C>,
+    where?: Partial<Row>,
+  ): Promise<boolean>;
+  count<Row, C extends ColumnMap>(
+    entity: EntityCore<Row, C>,
+    where?: Partial<Row>,
+  ): Promise<number>;
+  /** Scoped wipe before a regenerate. Refused on a soft-deleting entity — see `softDeleteWipe`. */
+  deleteWhere<Row, C extends ColumnMap>(
+    entity: EntityCore<Row, C>,
+    where: Partial<Row>,
+  ): Promise<number>;
   /** Deterministic id for a label. Same label, same uuid, every run. */
   id(label: string): string;
+  /** One instant for the whole run, so every row a bulk pass stamps carries the same timestamp. */
+  readonly now: Date;
+  readonly environment: Environment;
+  readonly tier: SeedTier;
+  /** Reads still run; every write short-circuits and is counted as what it WOULD have written. */
+  readonly dryRun: boolean;
+  readonly metrics: SeedMetrics;
 }
 
 export interface SeedOptions {
   /** Defaults to a fresh in-memory driver, so a seed runs with no database at all. */
   readonly driver?: Driver;
+  readonly dryRun?: boolean;
+  /** Injected for a test; `process.env` otherwise. Read once, by `resolveEnvironment`. */
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+}
+
+export interface SeedRun {
+  readonly name: string;
+  readonly tier: SeedTier;
+  readonly metrics: SeedMetrics;
 }
 
 export interface Seed {
   readonly name: string;
-  run(options?: SeedOptions): Promise<void>;
+  readonly tier: SeedTier;
+  run(options?: SeedOptions): Promise<SeedRun>;
 }
 
-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,
-    });
-  },
-});
+export interface SeedInit {
+  /** Defaults to `dev`: fixture data is what a seed is until its author says otherwise. */
+  readonly tier?: SeedTier;
+}
+
+/** What `x db seed` picks out of a module. Same shape rule as `isRouteConfig`. */
+export const isSeed = (value: unknown): value is Seed =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof (value as { name?: unknown }).name === 'string' &&
+  typeof (value as { run?: unknown }).run === 'function' &&
+  (SEED_TIERS as readonly unknown[]).includes((value as { tier?: unknown }).tier);
+
+/** Property access on a parsed row without `any`: `$parse` fills every declared column. */
+const cellOf = (row: unknown, property: string): unknown =>
+  (row as Readonly<Record<string, unknown>>)[property];
+
+/**
+ * Two cells, as a replay has to compare them: a `Date` is not `===` a `Date` and money is an
+ * object, so both are compared by value and everything else by identity.
+ */
+const sameCell = (left: unknown, right: unknown): boolean => {
+  if (left instanceof Date || right instanceof Date) {
+    return left instanceof Date && right instanceof Date && left.getTime() === right.getTime();
+  }
+  if (typeof left === 'object' && left !== null && typeof right === 'object' && right !== null) {
+    return JSON.stringify(left) === JSON.stringify(right);
+  }
+  return left === right;
+};
+
+const equalityPredicates = <Row>(where: Partial<Row>): readonly Predicate[] =>
+  Object.entries(where).map(([column, value]): Predicate => ({ column, op: 'eq', value }));
+
+/**
+ * The entity's own key as a conflict target. `$primaryKey` is `readonly string[]` because an
+ * entity does not know its row type at that field, and `onConflict` is typed by the row.
+ */
+const primaryKeyTarget = <Row>(entity: EntityCore<Row>): readonly (keyof Row & string)[] =>
+  entity.$primaryKey as readonly (keyof Row & string)[];
+
+/**
+ * A primary key the row leaves to a GENERATED default is a different id on every run, so the
+ * conflict target finds nothing and each replay inserts one more copy. `$parse` refuses a key with
+ * no value at all; this is the half it cannot see, because filling that column is what it does.
+ */
+const generatedKey = (entity: EntityCore, missing: string, position: number): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entity.$name} seed row ${position + 1} leaves "${missing}" to a generated default, and a primary key generated fresh on every run is a row every replay inserts a second copy of`,
+    fix: `insert(${entity.$name}, rows.map((row, index) => ({ ...row, ${missing}: id(\`${entity.$name}:\${index}\`) })))   # id() is a uuid v5 of the label: same row, same id, every run`,
+  });
+
+/**
+ * Deleting from a soft-deleting entity inside a seed, refused rather than documented. The stamp is
+ * what makes it unrecoverable: `upsertPlan` spares the soft-delete column on purpose and the stored
+ * row still occupies its unique key, so the replay that was supposed to bring the rows back writes
+ * nothing at all and the fixture is gone until the database is.
+ */
+const softDeleteWipe = (entity: EntityCore): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entity.$name} declares ${SOFT_DELETE_COLUMN}, so deleteWhere() would stamp its seeded rows rather than remove them — the stamped row keeps its unique key, and no replay of this seed can clear it`,
+    fix: 'x db reset --json   # the only wipe a soft-deleting entity has; drop the deleteWhere() call from the seed',
+  });
+
+/** The row an update may write: everything the caller named, less what a match must not move. */
+const withoutPreserved = <Row>(row: Row, preserve: readonly string[]): Row => {
+  const copy: Record<string, unknown> = { ...(row as Record<string, unknown>) };
+  for (const property of preserve) delete copy[property];
+  // `Repo` is typed for whole rows, and a partial one is exactly what keeps a column OUT of the
+  // update set — `namedProperties` reads what the row owns. Same assertion the bulk live test takes.
+  return copy as Row;
+};
+
+export const defineSeed = (
+  name: string,
+  build: (context: SeedContext) => Promise<void>,
+  init: SeedInit = {},
+): Seed => {
+  const tier = init.tier ?? 'dev';
+  return {
+    name,
+    tier,
+    run: async (options = {}) => {
+      const driver = options.driver ?? memoryDriver();
+      const dryRun = options.dryRun ?? false;
+      const metrics: SeedMetrics = { inserted: 0, updated: 0, skipped: 0 };
+      const context: SeedContext = {
+        insert: async (entity, rows) => {
+          // Judged on the row as WRITTEN, before `$parse` fills the column that would hide it.
+          for (const [position, row] of rows.entries()) {
+            const missing = entity.$primaryKey.find(
+              (property) =>
+                entity.$columns[property]?.$meta.default?.kind === 'generated' &&
+                !Object.hasOwn(row, property),
+            );
+            if (missing !== undefined) throw generatedKey(entity, missing, position);
+          }
+          const parsed = rows.map((row) => entity.$parse(row));
+          if (dryRun) {
+            metrics.inserted += parsed.length;
+            return;
+          }
+          const written = await driver.repo(entity).upsertAll(parsed, {
+            onConflict: primaryKeyTarget(entity),
+            // Never `'update'`: a do-nothing conflict needs no tenant column in the target, so this
+            // is the one form that replays on a tenant-scoped entity whose unique keys are global.
+            onMatch: 'nothing',
+          });
+          metrics.inserted += written.length;
+          metrics.skipped += parsed.length - written.length;
+        },
+
+        upsert: async (entity, key, values) => {
+          const row = entity.$parse(values);
+          const repo = driver.repo(entity);
+          const where = Object.fromEntries(
+            key.by.map((property) => [property, cellOf(row, property)]),
+          );
+          const found = await repo.findMany({ where: equalityPredicates(where), limit: 1 });
+          const stored = found.rows[0];
+          const preserve: readonly string[] = key.preserve ?? [CREATED_AT_COLUMN];
+          const compared = Object.keys(row as Record<string, unknown>).filter(
+            (property) => !preserve.includes(property),
+          );
+          if (
+            stored !== undefined &&
+            compared.every((property) => sameCell(cellOf(stored, property), cellOf(row, property)))
+          ) {
+            metrics.skipped += 1;
+            return 'skipped';
+          }
+          const write: SeedWrite = stored === undefined ? 'inserted' : 'updated';
+          if (!dryRun) {
+            await repo.upsertAll([stored === undefined ? row : withoutPreserved(row, preserve)], {
+              onConflict: key.by,
+              onMatch: 'update',
+            });
+          }
+          metrics[write === 'inserted' ? 'inserted' : 'updated'] += 1;
+          return write;
+        },
+
+        count: async (entity, where) =>
+          driver
+            .repo(entity)
+            .count(where === undefined ? {} : { where: equalityPredicates(where) }),
+
+        exists: async (entity, where) => (await context.count(entity, where)) > 0,
+
+        deleteWhere: async (entity, where) => {
+          if (entity.$softDelete) throw softDeleteWipe(entity);
+          if (dryRun) return context.count(entity, where);
+          return driver.repo(entity).deleteWhere(where);
+        },
+
+        id: seedId,
+        now: entityNow(),
+        environment: resolveEnvironment({ env: options.env }),
+        tier,
+        dryRun,
+        metrics,
+      };
+      await build(context);
+      return { name, tier, metrics };
+    },
+  };
+};

package/src/types.ts

@@ -6,17 +6,39 @@
 // A column carries its TypeScript type in `$parse`, which is what lets the row type be derived
 // from the column set instead of being written a second time as a hand-maintained schema.
 
-/** Postgres types the blessed builders emit. `money` expands to `bigint` + `char(3)`. */
-export type ColumnKind =
-  | 'uuid'
-  | 'text'
-  | 'char'
-  | 'boolean'
-  | 'integer'
-  | 'bigint'
-  | 'timestamptz'
-  | 'jsonb'
-  | 'money';
+/**
+ * Postgres types the builders emit. `money` expands to `bigint` + `char(3)` (+ a nullable
+ * `integer` scale); `array` expands to its element's type with `[]` after it.
+ *
+ * The four beyond the blessed set exist for ONE reason: a schema Ultimate did not generate already
+ * has them. A table with a `numeric(18,8)` rate, a `date` a rate takes effect on, a `jsonb` payload
+ * and a `bytea` blob cannot be declared at all without them, and an entity that cannot be declared
+ * is a rewrite instead of an adoption.
+ */
+export const COLUMN_KINDS = [
+  'uuid',
+  'text',
+  'char',
+  'boolean',
+  'integer',
+  'bigint',
+  'numeric',
+  'timestamptz',
+  'date',
+  'jsonb',
+  'bytea',
+  'array',
+  'money',
+] as const;
+
+/**
+ * Derived from the array and never written twice — the same shape `PRIMITIVE_KINDS` in
+ * `@ultimat3/core`'s `registrar.ts` uses, and for the same reason: a package that has to answer
+ * "one case per kind" needs a RUNTIME list, and a list written beside the type is one that drifts
+ * from it. `@ultimat3/query`'s `shape-order.test.ts` spelled its own out and counted nine against
+ * thirteen — `9 === 9`, a test that could not fail.
+ */
+export type ColumnKind = (typeof COLUMN_KINDS)[number];
 
 export type ColumnDefault =
   | { readonly kind: 'value'; readonly value: string | number | boolean | null }
@@ -48,6 +70,22 @@ export type { MoneyValue };
  * needs no conversion at the call site. A float throws, and so does a `bigint` past
  * `Number.MAX_SAFE_INTEGER` — see `parseMinor` in `columns.ts`.
  */
+/**
+ * The physical columns behind a money property, when they are not `<name>_minor`,
+ * `<name>_currency` and `<name>_scale`. Named per part and merged over those defaults, so a table
+ * that renamed one column does not have to restate the other two.
+ */
+export interface MoneyColumnNames {
+  readonly minor?: string;
+  readonly currency?: string;
+  /**
+   * `null` says this table has NO scale column — the ordinary shape of a money column written
+   * before scale existed. Every amount in it is then at the currency's own minor unit, which is
+   * what an absent scale already means, so nothing is lost but the ability to store a sub-cent one.
+   */
+  readonly scale?: string | null;
+}
+
 export interface MoneyInput {
   readonly minor: bigint | number;
   readonly currency: string;
@@ -71,7 +109,20 @@ export interface ColumnMeta {
   readonly index: boolean;
   /** Presence of a tenant column is what turns tenancy on. See `tenancy.ts`. */
   readonly tenant: boolean;
+  /**
+   * The physical column, when it is not `snake(property)`. The whole of what makes an existing
+   * table addressable: `githubLogin` on a row, `gh_login` in every statement, decided once here
+   * and read through `columnName()` by every projection.
+   */
+  readonly name?: string;
   readonly length?: number;
+  /** `numeric(precision, scale)` — both, or neither. A bare `numeric` is unbounded on purpose. */
+  readonly precision?: number;
+  readonly numericScale?: number;
+  /** The element column of an `array`, which carries the element's own kind and `$parse`. */
+  readonly element?: AnyColumn;
+  /** Where money's three physical columns live, when the table already named them. */
+  readonly parts?: MoneyColumnNames;
   readonly values?: readonly string[];
   readonly default?: ColumnDefault;
   readonly onUpdate?: ColumnDefault;
@@ -99,6 +150,13 @@ export interface Column<T, Optional extends boolean = false> {
   tenant(): Column<T, Optional>;
   references(target: () => AnyColumn, options?: ReferenceOptions): Column<T, Optional>;
   default(value: T): Column<T, true>;
+  /**
+   * The physical column name, when the table does not spell it `snake(property)`. Name it LAST in
+   * a chain: this link returns the general column, so a builder's own methods (`defaultNow()`,
+   * a uuid key's narrowed `primaryKey()`) are declared before it — `uuid()` and `timestamp()`
+   * override it to keep theirs, and nothing else has any.
+   */
+  column(name: string): Column<T, Optional>;
 }
 
 /**
@@ -111,11 +169,13 @@ export interface Column<T, Optional extends boolean = false> {
 export interface UuidColumn<T extends string = string, Optional extends boolean = false>
   extends Column<T, Optional> {
   primaryKey(): Column<T, true>;
+  column(name: string): UuidColumn<T, Optional>;
 }
 
 export interface TimestampColumn<Optional extends boolean = false> extends Column<Date, Optional> {
   defaultNow(): TimestampColumn<true>;
   onUpdateNow(): TimestampColumn<Optional>;
+  column(name: string): TimestampColumn<Optional>;
 }
 
 export type AnyColumn = Column<unknown, boolean>;
@@ -169,6 +229,38 @@ export type Insertable<C extends ColumnMap> = {
   readonly [K in DefaultedKeys<C> | NullableKeys<C>]?: InputOf<TypeOf<C[K]>>;
 };
 
+/**
+ * A patch or a filter: every property optional, **and every property allowed to be present and
+ * `undefined`**.
+ *
+ * `Partial<Row>` cannot say the second half. Under `exactOptionalPropertyTypes` — which this repo
+ * has on — `{ k?: T }` means "absent, or a `T`", so `{ postId: undefined }` is a type error, and
+ * that is the ONE value every filtered write in this package is built to refuse:
+ *
+ * - `plan.ts`'s `namedColumns` drops `value !== undefined`, so `deleteWhere({ postId: undefined })`
+ *   yields no predicate and throws `X_WRITE_UNFILTERED` rather than deleting the table. That
+ *   refusal exists for exactly one caller — a variable that came back `undefined` — and
+ *   `Partial<Row>` made the caller unable to spell it and the test unable to prove it.
+ * - `updateWhere(filter, { createdAt: undefined })` is `X_PATCH_EMPTY`, one argument over.
+ * - `bulk-write.ts`'s `owns()` is `Object.hasOwn`, so for a batch a present-`undefined` property
+ *   IS a named column — the opposite reading, deliberately, and equally unspellable.
+ *
+ * A type that forbids the value its own runtime is written to catch is a type that documents
+ * nothing: `bulk-write.test.ts` carried `as Partial<Item>` with the comment
+ * "`exactOptionalPropertyTypes` is why it takes a cast to say", which is the defect written down.
+ *
+ * Money goes through `InputOf`, for the reason `Insertable` does: a patch is a WRITE, and money's
+ * write shape is the wider one. `conflictKeyOf`'s own `cellKey` renders a `bigint` minor unit
+ * (`${part}n`), so refusing one here would have been a type refusing a value one function down
+ * spells out how to serialise. The row's own type stays in the union rather than being replaced by
+ * `InputOf<Row[K]>`: a conditional type over an unresolved `Row` never reduces, so `Row` itself
+ * stopped being assignable to its own patch and every internal caller reddened. Both spellings are
+ * accepted here, which is the honest statement anyway — a patch may carry either.
+ */
+export type RowPatch<Row> = {
+  readonly [K in keyof Row]?: Row[K] | InputOf<Row[K]> | undefined;
+};
+
 export interface IndexDef {
   readonly name: string;
   readonly columns: readonly string[];