@ultimat3/entity 23.0.0 → 25.0.0

package/src/sealed.ts

@@ -30,9 +30,9 @@ export interface SealedField {
   /** NOT NULL — and a sealed column takes no default, so a row to insert must carry it. */
   readonly required: boolean;
   /**
-   * The column's own parser, which judges a PLAINTEXT — `text({ max })` included. Run before a
-   * value is sealed, because nothing after that point can: the driver only ever sees the sealed
-   * string, which is longer than any bound the author wrote.
+   * The parser the column had before `.sealed()`, which judges a PLAINTEXT — `text({ max })`
+   * included. Run before a value is sealed, because nothing after that point can: the driver only
+   * ever sees the sealed string, which is longer than any bound the author wrote.
    */
   readonly parse: (value: unknown) => unknown;
 }
@@ -50,7 +50,9 @@ const describeField = (table: string, property: string, column: AnyColumn): Seal
       purpose: sealedPurpose(table, physical),
       lookup: sealed.lookup,
       required: column.$meta.notNull,
-      parse: column.$parse,
+      // The UNWRAPPED parser: `column.$parse` passes anything shaped like a sealed value, so a
+      // lookalike plaintext skipped `text({ max })` on its way to being sealed.
+      parse: sealed.plaintext,
     },
   ];
 };

package/src/seed.ts

@@ -10,6 +10,7 @@ import type { Driver } from './database';
 import { memoryDriver } from './database';
 import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { EntityError } from './errors';
+import type { Tx } from './repo';
 import type { Predicate } from './tenancy';
 import type { ColumnMap, Insertable } from './types';
 
@@ -112,7 +113,8 @@ export interface SeedContext {
    * 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.
+   * for the decision. On an `appendOnly` entity the write is `on conflict do nothing`: an absent
+   * row is appended, and a stored row the seed would CHANGE is refused (`X_ENTITY_APPEND_ONLY`).
    */
   upsert<Row, C extends ColumnMap>(
     entity: EntityCore<Row, C>,
@@ -143,7 +145,7 @@ export interface SeedContext {
   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. */
+  /** Every verb runs for real, inside a transaction `run()` rolls back: counted, never kept. */
   readonly dryRun: boolean;
   readonly metrics: SeedMetrics;
 }
@@ -209,6 +211,14 @@ const equalityPredicates = <Row>(where: Partial<Row>): readonly Predicate[] =>
 const primaryKeyTarget = <Row>(entity: EntityCore<Row>): readonly (keyof Row & string)[] =>
   entity.$primaryKey as readonly (keyof Row & string)[];
 
+/**
+ * Thrown out of the dry run's own transaction to roll it back; never leaves `run()`. A dry run IS
+ * the real run, in a transaction (`Driver.transactor()`) that is then rolled back — one rule, so
+ * what it reports is what a real run would do: a key another tenant holds is skipped, a second
+ * verb sees the first one's rows, and a seed that would fail fails.
+ */
+const UNDO = Object.freeze({ seedDryRun: 'undo' });
+
 /**
  * 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
@@ -256,89 +266,118 @@ export const defineSeed = (
       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(
+      /** The context a seed body writes through; `tx` is the dry run's, and absent otherwise. */
+      const contextFor = (tx: Tx | undefined): SeedContext => {
+        // The in-memory driver undoes through the `tx` a write is handed; Postgres finds the open
+        // transaction itself and ignores it.
+        const undo = tx === undefined ? {} : { tx };
+        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));
+            const written = await driver.repo(entity).upsertAll(parsed, {
+              ...undo,
+              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];
+            // Only what the CALLER named, and never a key the table generates: `$parse` fills a
+            // fresh uuid and a `defaultNow()` into `row`, which no stored row can equal — so a
+            // re-run reported every row `'updated'` and never once `'skipped'`.
+            const compared = Object.keys(row as Record<string, unknown>).filter(
               (property) =>
-                entity.$columns[property]?.$meta.default?.kind === 'generated' &&
-                !Object.hasOwn(row, property),
+                !preserve.includes(property) &&
+                Object.hasOwn(values, property) &&
+                (!entity.$primaryKey.includes(property) || key.by.includes(property as never)),
             );
-            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];
-          // Only what the CALLER named, and never a key the table generates: `$parse` fills a
-          // fresh uuid and a `defaultNow()` into `row`, which no stored row can equal — so a
-          // re-run reported every row `'updated'` and never once `'skipped'`.
-          const compared = Object.keys(row as Record<string, unknown>).filter(
-            (property) =>
-              !preserve.includes(property) &&
-              Object.hasOwn(values, property) &&
-              (!entity.$primaryKey.includes(property) || key.by.includes(property as never)),
-          );
-          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) {
+            if (
+              stored !== undefined &&
+              compared.every((property) =>
+                sameCell(cellOf(stored, property), cellOf(row, property)),
+              )
+            ) {
+              metrics.skipped += 1;
+              return 'skipped';
+            }
+            if (stored === undefined && entity.$appendOnly) {
+              // An appendOnly table refuses `do update` outright, even with nothing to update; a
+              // do-nothing conflict still settles two boots racing on the key, and the loser's row
+              // was the winner's — the same seed — so it is reported skipped, never a refusal.
+              // A CHANGED stored row still falls through below, to the append-only refusal.
+              const written = await repo.upsertAll([row], {
+                ...undo,
+                onConflict: key.by,
+                onMatch: 'nothing',
+              });
+              const outcome: SeedWrite = written.length > 0 ? 'inserted' : 'skipped';
+              metrics[outcome] += 1;
+              return outcome;
+            }
+            const write: SeedWrite = stored === undefined ? 'inserted' : 'updated';
             await repo.upsertAll([stored === undefined ? row : withoutPreserved(row, preserve)], {
+              ...undo,
               onConflict: key.by,
               onMatch: 'update',
             });
-          }
-          metrics[write === 'inserted' ? 'inserted' : 'updated'] += 1;
-          return write;
-        },
+            metrics[write === 'inserted' ? 'inserted' : 'updated'] += 1;
+            return write;
+          },
 
-        count: async (entity, where) =>
-          driver
-            .repo(entity)
-            .count(where === undefined ? {} : { where: equalityPredicates(where) }),
+          count: async (entity, where) =>
+            driver
+              .repo(entity)
+              .count(where === undefined ? {} : { where: equalityPredicates(where) }),
 
-        exists: async (entity, where) => (await context.count(entity, where)) > 0,
+          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);
-        },
+          deleteWhere: async (entity, where) => {
+            if (entity.$softDelete) throw softDeleteWipe(entity);
+            return driver.repo(entity).deleteWhere(where, undo);
+          },
 
-        id: seedId,
-        now: entityNow(),
-        environment: resolveEnvironment({ env: options.env }),
-        tier,
-        dryRun,
-        metrics,
+          id: seedId,
+          now: entityNow(),
+          environment: resolveEnvironment({ env: options.env }),
+          tier,
+          dryRun,
+          metrics,
+        };
+        return context;
       };
-      await build(context);
+      if (!dryRun) {
+        await build(contextFor(undefined));
+        return { name, tier, metrics };
+      }
+      try {
+        await driver.transactor().run(async (tx) => {
+          await build(contextFor(tx));
+          throw UNDO;
+        });
+      } catch (thrown) {
+        if (thrown !== UNDO) throw thrown;
+      }
       return { name, tier, metrics };
     },
   };

package/src/transition.ts

@@ -113,6 +113,9 @@ export const transitionRow = async <Row, C extends ColumnMap>(
   // Keyed on the entity's OWN primary key, never the literal `id`: a `code`-keyed entity has no
   // `id` column, so the filter matched nothing in memory (a false `X_STATE_CONFLICT`) and named a
   // column Postgres does not have (`X_INVARIANT_VIOLATED`).
+  // An absent id names no row, and is refused HERE: `namedColumns` drops an `undefined` filter
+  // value, so the predicate below would be the from-state alone and move every row in it.
+  if (id === undefined || id === null) throw notFound(entity.$name, String(id));
   const key = singleKeyOf(entity, 'transition');
   const filter = { [key]: id, [property]: move.from } as unknown as RowPatch<Row>;
   const values = { [property]: move.to } as unknown as RowPatch<Row>;

package/src/type-pins.ts

@@ -451,3 +451,28 @@ export type _MarkerSurvivesNullable = Assert<
 export type _SealedTableIsAReadBuilder = Assert<
   typeof sealedTable extends ReadBuilder<SealedPinRow> ? true : false
 >;
+
+/**
+ * Entity exports no `Page` (owner decision O-12, 25.0.0): `@ultimat3/core`'s is the ONE page
+ * shape, and `findMany` answers it — import it from core (or `@ultimat3/query`, which re-exports
+ * it). A second spelling here is a second door to one name; re-exporting it from this barrel
+ * makes this directive unused, which is the build error.
+ */
+// @ts-expect-error — `Page` is not an export of `@ultimat3/entity`.
+export type _EntityExportsNoPage = import('./index').Page<unknown>;
+
+/**
+ * `findMany` answers core's `Page`, both halves of the union: a repo page whose `nextCursor` could
+ * be set on the last page (entity's 24.x `Page` had no `hasMore` at all) fails here.
+ */
+export type _FindManyAnswersCorePage = Assert<
+  [Awaited<ReturnType<Repo<{ id: string }>['findMany']>>] extends [
+    import('@ultimat3/core').Page<{ id: string }>,
+  ]
+    ? [import('@ultimat3/core').Page<{ id: string }>] extends [
+        Awaited<ReturnType<Repo<{ id: string }>['findMany']>>,
+      ]
+      ? true
+      : false
+    : false
+>;

package/src/types.ts

@@ -167,6 +167,12 @@ export interface ColumnMeta {
 export interface SealedMeta {
   /** Deterministic seal: equality in `where` and `.unique()` are allowed, and nothing else. */
   readonly lookup: boolean;
+  /**
+   * The parser the column had BEFORE it was sealed — the one that judges a plaintext, `max`
+   * included. The column's own `$parse` passes any string shaped like a sealed value (a driver
+   * hands it one), so a value about to be sealed is judged by this instead.
+   */
+  readonly plaintext: (value: unknown) => unknown;
 }
 
 export interface SealedOptions<Lookup extends boolean = boolean> {

package/src/unique-constraints.ts

@@ -0,0 +1,44 @@
+// Single responsibility: the non-partial unique constraints an entity declares, beside its primary
+// key — ONE list, read by the upsert's conflict-target check (`bulk-write.ts`) and by the in-memory
+// driver's own enforcement (`memory-unique.ts`), so a unique the one accepts as a target is a
+// unique the other refuses a duplicate under.
+
+import { constraintNameFor } from '@ultimat3/db';
+import type { EntityCore } from './entity';
+
+export interface UniqueConstraint {
+  /** Physical column names, in declaration order. */
+  readonly columns: readonly string[];
+  /** The constraint's name in the database — asked for only once a collision is being reported. */
+  name(): string;
+}
+
+/**
+ * Two sources, because this framework has two ways to declare a unique index beside the key and a
+ * rule honoured for one of them only sends its author to declare the constraint a second time:
+ * `unique()` / `indexes: [{ unique: true }]` (both land in `$indexes`), and
+ * `invariant(name, c.unique([…]))`, which emits its `create unique index` out of `$invariants`.
+ *
+ * A PARTIAL unique is excluded from both: its predicate is SQL the memory driver cannot evaluate
+ * and an `on conflict` clause here does not spell. `bindInvariant` stamps that `where` on a
+ * soft-deleting entity, so the one rule covers both lists.
+ */
+export const uniqueConstraints = <Row>(entity: EntityCore<Row>): readonly UniqueConstraint[] => [
+  ...entity.$indexes
+    .filter((index) => index.unique && index.where === undefined)
+    .map((index) => ({ columns: index.columns, name: () => index.name })),
+  ...entity.$invariants
+    .filter((rule) => rule.kind === 'unique' && rule.where === undefined)
+    .map((rule) => ({
+      columns: rule.columns,
+      // `@ultimat3/db` names it, as it does in the DDL: `<table>_<name>_key`.
+      name: () =>
+        constraintNameFor(entity.$table, {
+          name: rule.name,
+          kind: 'unique',
+          message: rule.message,
+          sql: rule.sql,
+          where: null,
+        }),
+    })),
+];