@ultimat3/entity 29.4.0 → 30.1.0

package/src/describe.ts

@@ -5,12 +5,20 @@
 // Money is the one place the projection is not one-to-one: one property becomes the two
 // physical columns that back it.
 
-import { columnName, moneyColumns, referenceBinding } from './column';
+import { type Binding, bindingOf, columnName, moneyColumns, referenceBinding } from './column';
 import { currencyCheck, scaleCheck } from './columns';
+import { EntityError, invariantViolated } from './errors';
 import type { Invariant } from './invariants';
-import type { ColumnDescription, EntityDescription, ReferenceDescription } from './registry';
+import type { LifecycleDescription } from './lifecycle';
+import type {
+  ColumnDescription,
+  EntityDescription,
+  ReferenceDescription,
+  SameTenantKey,
+} from './registry';
 import type { SearchVector } from './search';
 import type { AnyColumn, ColumnMeta, IndexDef } from './types';
+import type { ViewQuery } from './view-entity';
 
 export interface DescribeInput<Row> {
   readonly name: string;
@@ -28,6 +36,16 @@ export interface DescribeInput<Row> {
   readonly search?: SearchVector | null;
   /** `entity({ appendOnly: true })` — projected only when true. */
   readonly appendOnly?: boolean;
+  /** `entity({ retired: [...] })` — physical names, projected only when there are any. */
+  readonly retired?: readonly string[] | undefined;
+  /** `entity({ shared: '<why>' })` — projected only when declared. */
+  readonly shared?: string | undefined;
+  /** `entity({ scan: '<why>' })` — projected only when declared. */
+  readonly scan?: string | undefined;
+  /** `entity({ view })` — projected only when declared. */
+  readonly view?: ViewQuery | null | undefined;
+  /** `retain`, `history`, `countedIn` counters — each projected only when declared (`lifecycle.ts`). */
+  readonly lifecycle?: LifecycleDescription | undefined;
 }
 
 /**
@@ -54,6 +72,42 @@ const describeSearchColumn = (search: SearchVector): ColumnDescription => ({
   generated: search.expression,
 });
 
+/**
+ * Whether this edge holds its two ends to one tenant. Decided here because a thunk can only be
+ * answered once both modules evaluated, and from the bindings because they alone know each side's
+ * physical tenant column.
+ *
+ * Both ends scoped, and neither end IS the tenant column: `orgId -> orgs.id` is the tenant's own
+ * root, where a composite would pair a column with itself. A `crossTenant` reason on an edge that
+ * could never be same-tenant is refused, or it would state a reason for nothing and read as a
+ * decision someone took.
+ */
+const sameTenantOf = (
+  entityName: string,
+  property: string,
+  meta: ColumnMeta,
+  own: Binding | undefined,
+  target: Binding,
+): SameTenantKey | null => {
+  const column = own?.tenant ?? null;
+  const targetColumn = target.tenant;
+  const eligible =
+    own !== undefined &&
+    column !== null &&
+    targetColumn !== null &&
+    own.name !== column &&
+    target.name !== targetColumn;
+  if (!eligible) {
+    if (meta.crossTenant === undefined) return null;
+    throw new EntityError({
+      code: 'X_INVARIANT_VIOLATED',
+      cause: `${entityName}.${property} states crossTenant on an edge that is not same-tenant: ${target.table} and ${entityName} do not both carry a tenant, or the column is the tenant column itself`,
+      fix: `references(() => ${target.table}.${target.property}) — in the columns of ${entityName}, with the crossTenant option removed`,
+    });
+  }
+  return meta.crossTenant === undefined ? { column, targetColumn } : null;
+};
+
 /**
  * The foreign keys an entity declares, resolved through the one binding resolver. Money is
  * skipped for the reason the DDL projection drops a reference there too: one property is two
@@ -75,9 +129,11 @@ export const describeReferences = (
         column: columnName(property, meta),
         nullable: !meta.notNull,
         targetEntity: target.table,
+        targetTable: target.physicalTable,
         targetProperty: target.property,
         targetColumn: target.name,
         onDelete: meta.onDelete ?? null,
+        sameTenant: sameTenantOf(entityName, property, meta, bindingOf(column), target),
       },
     ];
   });
@@ -108,6 +164,75 @@ export const sqlTypeOf = (meta: ColumnMeta): string => {
   return meta.kind;
 };
 
+/**
+ * At declaration, on the physical names: the same word in both lists is a column read by the release
+ * that says it stopped, and `x db gen` could only answer later and further away. Never through
+ * `describeEntity`: that answers a `references()` thunk, and a self-reference or a schema cycle is
+ * still in its temporal dead zone at this point.
+ */
+export const assertNotRetired = (
+  entityName: string,
+  entries: readonly (readonly [string, AnyColumn])[],
+  retired: readonly string[] | undefined,
+): void => {
+  for (const [property, column] of entries) {
+    const parts = column.$meta.kind === 'money' ? moneyColumns(property, column.$meta) : null;
+    const physical =
+      parts === null
+        ? [columnName(property, column.$meta)]
+        : [parts.minor, parts.currency, ...(parts.scale === null ? [] : [parts.scale])];
+    const held = physical.find((each) => retired?.includes(each) === true);
+    if (held !== undefined) {
+      throw invariantViolated(
+        entityName,
+        held,
+        'is listed under retired and still declared in columns; a column is one or the other',
+      );
+    }
+  }
+};
+
+/**
+ * `shared` is a reason, so a blank one is no reason: refused where it was written, never read as a
+ * declaration someone took. On an entity WITH a tenant column it states a reason for nothing — the
+ * stance `sameTenantOf` takes on a `crossTenant` reason for an edge that cannot be same-tenant.
+ */
+export const assertShared = (
+  entityName: string,
+  table: string,
+  shared: string | undefined,
+  tenantColumn: string | null,
+): void => {
+  if (shared === undefined) return;
+  if (shared.trim() === '') {
+    throw new EntityError({
+      code: 'X_ENTITY_TENANT_UNDECLARED',
+      cause: `${entityName} declares shared with no reason: a blank reason says nothing about why its rows belong to no tenant`,
+      fix: `entity('${entityName}', { shared: '<why it belongs to no tenant>' }) — or drop shared, add orgId: uuid().tenant() to its columns, then x db gen "${table} tenant"`,
+    });
+  }
+  if (tenantColumn !== null) {
+    throw new EntityError({
+      code: 'X_INVARIANT_VIOLATED',
+      cause: `${entityName} declares shared and has the tenant column ${tenantColumn}: its rows belong to a tenant, so the reason explains nothing`,
+      fix: `entity('${entityName}', { … }) — with the shared option removed`,
+    });
+  }
+};
+
+/**
+ * `scan` is a reason, like `shared`: a blank one is no reason, and a table a plan check skips with
+ * no argument is a silenced finding nobody can tell from a considered one.
+ */
+export const assertScan = (entityName: string, scan: string | undefined): void => {
+  if (scan === undefined || scan.trim() !== '') return;
+  throw new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName} declares scan with no reason: a blank reason says nothing about why the table stays small enough to read whole`,
+    fix: `entity('${entityName}', { scan: '<why it stays small, e.g. a closed catalog of 8 rows>' }) — or drop scan and add the index x exercise --json names`,
+  });
+};
+
 const describeColumn = <Row>(
   input: DescribeInput<Row>,
   property: string,
@@ -179,10 +304,12 @@ const describeColumn = <Row>(
       // Rendered from the resolved record, so the string a migration reads and the record a
       // traversal reads can never disagree about what a `references()` points at.
       references:
-        reference === undefined ? null : `${reference.targetEntity}.${reference.targetColumn}`,
+        reference === undefined ? null : `${reference.targetTable}.${reference.targetColumn}`,
       // Off the resolved reference, never off `meta` again: a rule with no key is not a thing, and
       // reading the option twice is two places for the pair to disagree.
       onDelete: reference?.onDelete ?? null,
+      // `true`-or-absent's cousin: absent, so no entity without such an edge moves the hash.
+      ...(reference?.sameTenant == null ? {} : { sameTenant: reference.sameTenant }),
     },
   ];
 };
@@ -241,5 +368,19 @@ export const describeEntity = <Row>(input: DescribeInput<Row>): EntityDescriptio
     // `true` or absent, never `false`: `x verify`'s source drift hashes this projection as JSON,
     // and an entity that never said `appendOnly` must hash exactly what it hashed before.
     ...(input.appendOnly === true ? { appendOnly: true as const } : {}),
+    ...((input.retired ?? []).length === 0 ? {} : { retired: input.retired }),
+    // Absent unless declared, like `appendOnly`: no entity that never said it moves the hash.
+    ...(input.shared === undefined ? {} : { shared: input.shared }),
+    ...(input.scan === undefined ? {} : { scan: input.scan }),
+    // Absent on every table, so no entity that never said `view` moves the hash.
+    ...(input.view === null || input.view === undefined
+      ? {}
+      : {
+          view: {
+            sql: input.view.sql,
+            ...(input.view.materialized ? { materialized: true as const } : {}),
+          },
+        }),
+    ...input.lifecycle,
   };
 };

package/src/entity-error.ts

@@ -40,6 +40,14 @@ export const ENTITY_ERROR_CODES = [
   'X_ENTITY_SEALED_IN_VIEW',
   'X_ENTITY_APPEND_ONLY',
   'X_ENTITY_OPERATOR_UNKNOWN',
+  'X_LOCK_UNSUPPORTED',
+  'X_TEST_DRIVER_CLIENT_CHANGED',
+  'X_ENTITY_TENANT_UNDECLARED',
+  'X_ENTITY_SERIES_UNSUPPORTED',
+  'X_ENTITY_SERIES_INVALID',
+  'X_ENTITY_VIEW_READ_ONLY',
+  'X_ENTITY_RETAIN_UNINDEXED',
+  'X_ENTITY_COUNTS_INVALID',
 ] as const;
 
 export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
@@ -74,6 +82,15 @@ export const ENTITY_ERROR_TITLES: Readonly<Record<EntityErrorCode, string>> = {
   X_ENTITY_SEALED_IN_VIEW: 'a sealed column is named in a view',
   X_ENTITY_APPEND_ONLY: 'an append-only entity was asked to rewrite or remove a row',
   X_ENTITY_OPERATOR_UNKNOWN: 'a predicate names an operator outside the vocabulary',
+  X_LOCK_UNSUPPORTED: 'a repository has no lock',
+  X_TEST_DRIVER_CLIENT_CHANGED: 'The installed client changed inside a testDriver() transaction',
+  X_ENTITY_TENANT_UNDECLARED: 'a child of a tenant-owned table has no tenant',
+  X_ENTITY_SERIES_UNSUPPORTED: 'a repository has no series',
+  X_ENTITY_SERIES_INVALID: 'a time series asked for something no bucket can answer',
+  X_ENTITY_VIEW_READ_ONLY: 'a view entity was asked to write a row',
+  X_ENTITY_RETAIN_UNINDEXED: 'entity({ retain }) names a column no index leads with',
+  X_ENTITY_COUNTS_INVALID:
+    'references(…, { countedIn }) names no integer of its parent, or is no key to its primary key',
 };
 
 // Registered at module load, unconditionally, in one call. Without this the registry humanises the
@@ -147,6 +164,22 @@ export const invariantViolated = (
     fix: `x entities show ${entityName} --json   # shows the invariant and its SQL CHECK`,
   });
 
+/**
+ * A `$view` key naming no column. Its own fix, never `describeCommand`: `x entities show` loads the
+ * app, and this throw is what stops the load, so that line re-failed with this finding. The file
+ * is the loader's to name (`Finding.at`): a view is built with no idea where it was called.
+ */
+export const viewKeyUnknown = (
+  entityName: string,
+  key: string,
+  columns: readonly string[],
+): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.view: $view(['${key}']) names no column — pick from: ${columns.join(', ')}`,
+    fix: `$view(['${columns[0] ?? ''}'])   # edit the call on ${entityName}, in the file this finding names; pick from: ${columns.join(', ')}`,
+  });
+
 export const entityDuplicate = (name: string, existingTable: string): EntityError =>
   new EntityError({
     code: 'X_ENTITY_DUPLICATE',

package/src/entity-parse.ts

@@ -0,0 +1,89 @@
+// Single responsibility: an entity's two row parsers — `$parse`, the whole row with declared
+// defaults filled, and the wire parser `$schema` validates with, which neither requires nor copies a
+// sealed column. Split from `entity.ts` at its line ceiling; both close over the same column list.
+
+import { describeValue } from '@ultimat3/schema';
+import { entityNow } from './clock';
+import { newId } from './columns';
+import { invariantViolated } from './errors';
+import { sealedMissing } from './sealed-errors';
+import type { AnyColumn, ColumnMeta } from './types';
+
+const defaultValue = (meta: ColumnMeta): unknown => {
+  const declared = meta.default;
+  if (declared === undefined) return undefined;
+  if (declared.kind === 'value') return declared.value;
+  return declared.by === 'uuid-v7' ? newId() : entityNow();
+};
+
+export const rowParsers = <Row, Wire>(
+  name: string,
+  entries: readonly (readonly [string, AnyColumn])[],
+  sealedKeys: ReadonlySet<string>,
+): { readonly parse: (value: unknown) => Row; readonly parseWire: (value: unknown) => Wire } => {
+  /** The columns that leave the server: every one that is not sealed. */
+  const wireEntries = entries.filter(([property]) => !sealedKeys.has(property));
+
+  const parse = (value: unknown): Row => {
+    if (typeof value !== 'object' || value === null) {
+      // `describeValue`, never `String(value)`: this message is a `$parse` failure, which reaches
+      // the caller and the log line — and the whole row is the last value in the framework that
+      // may be echoed there. Same renderer as the column builders (`columns.ts`) use.
+      throw invariantViolated(name, 'row', `expected an object, got ${describeValue(value)}`);
+    }
+    const input = value as Readonly<Record<string, unknown>>;
+    const row: Record<string, unknown> = {};
+    for (const [property, column] of entries) {
+      // `=== undefined`, never `??`: an explicit `null` is the caller CLEARING a nullable column,
+      // and `??` read it as absence and wrote the column's declared default straight back — so
+      // `update(id, { status: null })` reported success and stored `'draft'`, with nothing on any
+      // surface to say otherwise. A present `undefined` still means absence, which is what a
+      // spread of an omitted optional key produces and is the shape every existing caller has.
+      const raw = input[property];
+      const given = raw === undefined ? defaultValue(column.$meta) : raw;
+      if (given === undefined || given === null) {
+        if (column.$meta.notNull) {
+          // A required sealed column ABSENT from a row is nearly always a spread of a repository
+          // row, which does not enumerate it — so the refusal names that, and the rewrite.
+          throw given === undefined && sealedKeys.has(property)
+            ? sealedMissing(name, property)
+            : invariantViolated(name, property, 'is required and has no default');
+        }
+        row[property] = null;
+        continue;
+      }
+      row[property] = column.$parse(given);
+    }
+    // Every property was validated by its own column above, so the shape is the derived row.
+    return row as Row;
+  };
+
+  /**
+   * The row as `$schema` validates it: the sealed columns are neither required nor returned, so a
+   * handler's row — which holds their plaintext — parses to a value that does not.
+   */
+  const parseWire = (value: unknown): Wire => {
+    if (sealedKeys.size === 0) return parse(value) as unknown as Wire;
+    if (typeof value !== 'object' || value === null) {
+      throw invariantViolated(name, 'row', `expected an object, got ${describeValue(value)}`);
+    }
+    const input = value as Readonly<Record<string, unknown>>;
+    const row: Record<string, unknown> = {};
+    for (const [property, column] of wireEntries) {
+      const raw = input[property];
+      const given = raw === undefined ? defaultValue(column.$meta) : raw;
+      if (given === undefined || given === null) {
+        if (column.$meta.notNull) {
+          throw invariantViolated(name, property, 'is required and has no default');
+        }
+        row[property] = null;
+        continue;
+      }
+      row[property] = column.$parse(given);
+    }
+    // Every wire property was validated by its own column, and no sealed one was copied.
+    return row as Wire;
+  };
+
+  return { parse, parseWire };
+};

package/src/entity-patch.ts

@@ -0,0 +1,42 @@
+// Single responsibility: a patch judged by the columns it names, with the same issues `$parse`
+// raises for a whole row. Absent stays absent: a patch fills no default, or `update(id, { a })`
+// would rewrite every column it did not name.
+
+import { invariantViolated } from './errors';
+import { copyRow } from './sealed';
+import type { AnyColumn } from './types';
+
+/**
+ * The patch, each named column parsed. A property present with `undefined` is absent, the reading
+ * `namedColumns` and `bindValues` both give it. `copyRow`, because a row passed back whole keeps
+ * its server-only (sealed) properties: they are named by own key, enumerable or not, and parsed
+ * like the rest. A key no column declares stays for the statement builder's own refusal, and an
+ * empty patch reaches `X_PATCH_EMPTY` as it did.
+ */
+export const parseEntityPatch = <Patch>(
+  name: string,
+  columns: Readonly<Record<string, AnyColumn>>,
+  patch: Patch,
+): Patch => {
+  if (typeof patch !== 'object' || patch === null) return patch;
+  const parsed = copyRow(patch as object);
+  for (const [property, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(parsed))) {
+    const column = Object.hasOwn(columns, property) ? columns[property] : undefined;
+    const value: unknown = descriptor.get === undefined ? descriptor.value : descriptor.get();
+    if (column === undefined || value === undefined) continue;
+    if (value === null) {
+      if (column.$meta.notNull) {
+        throw invariantViolated(name, property, 'is required and has no default');
+      }
+      continue;
+    }
+    const { enumerable } = descriptor;
+    Object.defineProperty(parsed, property, {
+      value: column.$parse(value),
+      enumerable: enumerable === true,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return parsed as Patch;
+};