@ultimat3/entity 22.15.0 → 24.0.0

package/src/type-pins.ts

@@ -5,15 +5,25 @@
 // enforcement this repo counts (axiom 3).
 
 import type { Id } from '@ultimat3/core';
-import type { MoneyValue as SchemaMoneyValue } from '@ultimat3/schema';
+import type { Schema, MoneyValue as SchemaMoneyValue } from '@ultimat3/schema';
 import type { uuid } from './columns';
 import type { EntitySet } from './database';
 import type { Entity, EntityCore, EntityInit } from './entity';
 import type { ColumnExpr, InvariantColumns } from './expr';
 import type { Invariant, InvariantDef } from './invariants';
-import type { Table } from './query';
+import type { ReadBuilder, Table } from './query';
 import type { Repo } from './repo';
-import type { AnyColumn, IdOf, Insertable, MoneyInput, MoneyValue, RowOf } from './types';
+import type {
+  AnyColumn,
+  IdOf,
+  Insertable,
+  MoneyInput,
+  MoneyValue,
+  RowOf,
+  SealedColumn,
+  TextColumn,
+  WireRow,
+} from './types';
 
 /** Fails to compile when `T` is anything but `true`. The whole mechanism. */
 type Assert<T extends true> = T;
@@ -345,3 +355,99 @@ type _RepoBatchWritesTakeABigIntMinor = Assert<
 type _RepoAnswersTheValueType = Assert<
   [Awaited<ReturnType<Repo<PinMoneyRow>['insert']>>] extends [PinMoneyRow] ? true : false
 >;
+
+// --- Sealed columns (plan 101, slice 03) ---------------------------------------------------------
+// The row keeps `string`; the wire schema loses the column; a predicate naming it does not compile.
+
+declare const sealedPin: Entity<RowOf<SealedPinColumns>, SealedPinColumns>;
+type SealedPinColumns = {
+  readonly id: ReturnType<typeof uuid>;
+  readonly label: TextColumn;
+  readonly password: SealedColumn<string, false, false>;
+  readonly email: SealedColumn<string, false, true>;
+};
+type SealedPinRow = RowOf<SealedPinColumns>;
+declare const sealedTable: Table<SealedPinRow, SealedPinColumns>;
+
+/** The server row is the whole row, plaintext included. */
+export type _SealedRowKeepsTheColumn = Assert<
+  SealedPinRow['password'] extends string ? true : false
+>;
+
+/** `$schema` parses to the row WITHOUT its sealed columns — what an `output` sends. */
+type SealedWire = WireRow<SealedPinRow, SealedPinColumns>;
+export type _SealedWireDropsBoth = Assert<
+  'password' extends keyof SealedWire ? false : 'email' extends keyof SealedWire ? false : true
+>;
+export type _SealedWireKeepsTheRest = Assert<'label' extends keyof SealedWire ? true : false>;
+export type _SealedSchemaIsTheWireRow = Assert<
+  (typeof sealedPin)['$schema'] extends Schema<unknown, SealedWire> ? true : false
+>;
+/** …and an entity with no sealed column keeps `Row` itself, not a mapped copy. */
+export type _UnsealedWireIsTheRow = Assert<
+  WireRow<PinRow, PinColumns> extends PinRow
+    ? PinRow extends WireRow<PinRow, PinColumns>
+      ? true
+      : false
+    : false
+>;
+
+/** A sealed entity is still an `EntityCore`, so `database()` and every driver take it. */
+export type _SealedEntityIsACore = Assert<
+  typeof sealedPin extends EntityCore<SealedPinRow, SealedPinColumns> ? true : false
+>;
+export type _SealedEntityIsInASet = Assert<
+  { readonly x: typeof sealedPin } extends EntitySet ? true : false
+>;
+
+type WhereFilter = Parameters<(typeof sealedTable)['where']>[0];
+/** An opaque column is absent from the filter; a lookup column and a plain one are present. */
+export type _OpaqueIsNotFilterable = Assert<'password' extends keyof WhereFilter ? false : true>;
+export type _LookupIsFilterable = Assert<'email' extends keyof WhereFilter ? true : false>;
+export type _PlainIsFilterable = Assert<'label' extends keyof WhereFilter ? true : false>;
+
+type AndWhereColumn = Parameters<(typeof sealedTable)['andWhere']>[0];
+export type _OpaqueIsNotAPredicate = Assert<'password' extends AndWhereColumn ? false : true>;
+export type _LookupIsAPredicate = Assert<'email' extends AndWhereColumn ? true : false>;
+/** …but a NULL test names any column: presence is not sealed. The overload is the first one. */
+declare const nullTested: ReturnType<typeof nullTest>;
+declare function nullTest(): ReturnType<(typeof sealedTable)['andWhere']>;
+export type _NullTestTakesAnOpaqueColumn = Assert<
+  (typeof sealedTable)['andWhere'] extends (column: 'password', op: 'is-null') => typeof nullTested
+    ? true
+    : false
+>;
+
+type OrderColumn = Parameters<(typeof sealedTable)['orderBy']>[0];
+/** Neither kind orders: ciphertext has no order worth asking for. */
+export type _SealedDoesNotOrder = Assert<
+  'password' extends OrderColumn ? false : 'email' extends OrderColumn ? false : true
+>;
+export type _PlainOrders = Assert<'label' extends OrderColumn ? true : false>;
+
+/** `.sealed()` is `text()`'s: no other builder has it, so a sealed number does not compile. */
+export type _OnlyTextSeals = Assert<
+  'sealed' extends keyof TextColumn
+    ? 'sealed' extends keyof ReturnType<typeof uuid>
+      ? false
+      : true
+    : false
+>;
+/** It survives the links that may precede it, and keeps its marker across the ones that follow. */
+export type _SealedAfterNullable = Assert<
+  ReturnType<TextColumn['nullable']> extends { sealed: unknown } ? true : false
+>;
+export type _MarkerSurvivesNullable = Assert<
+  ReturnType<SealedColumn<string, false, true>['nullable']>['$sealed'] extends 'lookup'
+    ? true
+    : false
+>;
+
+/**
+ * A sealed table is still a `ReadBuilder<Row>`: `backfill({ source })`, `preload` and every other
+ * consumer that names the chain without the columns takes it. The refusal is in the PARAMETERS,
+ * which a method compares bivariantly, so the narrower chain is assignable to the wider one.
+ */
+export type _SealedTableIsAReadBuilder = Assert<
+  typeof sealedTable extends ReadBuilder<SealedPinRow> ? true : false
+>;

package/src/types.ts

@@ -155,6 +155,33 @@ export interface ColumnMeta {
    * indexes by a data key.
    */
   readonly machine?: StateMachine;
+  /**
+   * Presence is what makes this column SEALED: stored as `@ultimat3/core`'s `seal()` output, opened
+   * on read, absent from every schema that leaves the server. `sealed-repo.ts` is the one reader
+   * that seals and opens; everything else reads it to refuse (`sealed-declaration.ts`).
+   */
+  readonly sealed?: SealedMeta;
+}
+
+/** What `.sealed(options)` declared, resolved. */
+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> {
+  /**
+   * Seal deterministically so the column can be matched by equality (`where`, `in`, `.unique()`).
+   * It REVEALS EQUALITY: two rows holding the same value store the same string. Never for a
+   * low-entropy value — a boolean, a status, a PIN.
+   */
+  readonly lookup?: Lookup;
 }
 
 /**
@@ -230,6 +257,85 @@ export interface TimestampColumn<Optional extends boolean = false> extends Colum
   column(name: string): TimestampColumn<Optional>;
 }
 
+/**
+ * `text()`'s own column: the one that may be sealed, because a sealed value is a string and no
+ * other kind has a use for it. `nullable()`, `unique()`, `default()` and `column()` keep the
+ * builder, so `.sealed()` reads the same wherever it sits among them.
+ */
+export interface TextColumn<T extends string | null = string, Optional extends boolean = false>
+  extends Column<T, Optional> {
+  nullable(): TextColumn<T | null, Optional>;
+  unique(): TextColumn<T, Optional>;
+  default(value: T): TextColumn<T, true>;
+  column(name: string): TextColumn<T, Optional>;
+  /**
+   * Seal this column under the app's master key: the row still reads `string`, the database holds
+   * `x1.<keyId>.<iv>.<ciphertext>`, and no view, `$schema`, record or predicate carries it.
+   * `.sealed({ lookup: true })` allows equality at the cost of revealing it.
+   */
+  sealed<const Lookup extends boolean = false>(
+    options?: SealedOptions<Lookup>,
+  ): SealedColumn<T, Optional, Lookup>;
+}
+
+/**
+ * A sealed column. `$sealed` is the phantom the typed handle reads: `'opaque'` is refused in every
+ * predicate, `'lookup'` in everything but equality. It is a real string at runtime too.
+ */
+export interface SealedColumn<
+  T extends string | null = string,
+  Optional extends boolean = false,
+  Lookup extends boolean = false,
+> extends Column<T, Optional> {
+  readonly $sealed: Lookup extends true ? 'lookup' : 'opaque';
+  nullable(): SealedColumn<T | null, Optional, Lookup>;
+  /** `lookup` only: uniqueness over ciphertext needs equal values to seal equal. */
+  unique(): SealedColumn<T, Optional, Lookup>;
+  column(name: string): SealedColumn<T, Optional, Lookup>;
+}
+
+/** The columns no predicate may name, and the ones only equality may. Read by `query.ts`. */
+export type OpaqueKeys<C extends ColumnMap> = {
+  [K in keyof C]-?: C[K] extends { readonly $sealed: 'opaque' } ? K : never;
+}[keyof C];
+export type SealedKeys<C extends ColumnMap> = {
+  [K in keyof C]-?: C[K] extends { readonly $sealed: string } ? K : never;
+}[keyof C];
+
+/**
+ * Which keys the typed chain refuses: `opaque` in every predicate, `sealed` (opaque and lookup
+ * both) in an order or a group. A pair rather than the column map itself, so `ReadBuilder` stays
+ * row-shaped and a `select()` or a `preload()` carries it along unchanged.
+ */
+export interface SealedKeySet {
+  readonly opaque: PropertyKey;
+  readonly sealed: PropertyKey;
+}
+
+/** The default: an entity with no sealed column, and every row-agnostic consumer. */
+export interface NoSealedKeys {
+  readonly opaque: never;
+  readonly sealed: never;
+}
+
+export interface SealedKeysOf<C extends ColumnMap> {
+  readonly opaque: OpaqueKeys<C>;
+  readonly sealed: SealedKeys<C>;
+}
+
+/** A filter's shape: the row without the columns no predicate may name. */
+export type Filterable<Row, S extends SealedKeySet> = [S['opaque']] extends [never]
+  ? Row
+  : Omit<Row, S['opaque']>;
+
+/**
+ * The row as it leaves the server: without its sealed columns. `[…] extends [never]` so an entity
+ * with none — and every row-agnostic `EntityCore` — keeps `Row` itself, not a mapped copy of it.
+ */
+export type WireRow<Row, C extends ColumnMap> = [SealedKeys<C>] extends [never]
+  ? Row
+  : Omit<Row, SealedKeys<C>>;
+
 export type AnyColumn = Column<unknown, boolean>;
 
 export type ColumnMap = Readonly<Record<string, AnyColumn>>;

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