@ultimat3/entity 0.0.1 → 1.1.0

package/src/database.ts

@@ -0,0 +1,62 @@
+// The one typed database handle. `db.posts` exists because `posts` was declared — nobody
+// writes a repository class per entity, and nobody can reach a table that is not in the set.
+
+import type { EntityCore } from './entity';
+import type { Table } from './query';
+import { tableFor } from './query';
+import type { Repo } from './repo';
+import { memoryRepo } from './repo';
+
+export type EntitySet = Readonly<Record<string, EntityCore>>;
+
+export type Database<E extends EntitySet> = {
+  readonly [K in keyof E]: Table<E[K]['$row'], E[K]['$columns']>;
+};
+
+/** Where rows actually live. Postgres in production, memory in tests and before migrations. */
+export interface Driver {
+  repo<Row>(entity: EntityCore<Row>): Repo<Row>;
+}
+
+export interface DatabaseOptions {
+  readonly driver?: Driver;
+}
+
+/**
+ * The default driver: correct semantics, no database, so `x dev` and every test run before
+ * the first migration exists.
+ */
+export const memoryDriver = (): Driver => {
+  const repos = new Map<string, unknown>();
+  return {
+    repo<Row>(entity: EntityCore<Row>): Repo<Row> {
+      const existing = repos.get(entity.$name);
+      // Keyed by entity name and only ever written from that same entity, so the row type a
+      // caller asks for is the one that was stored.
+      if (existing !== undefined) return existing as Repo<Row>;
+      const created = memoryRepo<Row>(entity);
+      repos.set(entity.$name, created);
+      return created;
+    },
+  };
+};
+
+let shared: Driver | undefined;
+
+const defaultDriver = (): Driver => {
+  shared ??= memoryDriver();
+  return shared;
+};
+
+export const database = <E extends EntitySet>(
+  entities: E,
+  options: DatabaseOptions = {},
+): Database<E> => {
+  const driver = options.driver ?? defaultDriver();
+  const tables: Record<string, unknown> = {};
+  for (const [key, entity] of Object.entries(entities)) {
+    tables[key] = tableFor(entity, driver.repo(entity));
+  }
+  // Built key by key from `entities`, so each table is the one `Database<E>` names.
+  return tables as Database<E>;
+};

package/src/describe.ts

@@ -0,0 +1,106 @@
+// The projection an entity hands the rest of the toolchain: `x.manifest.json`, the migration
+// generator, the admin dashboard and `x entities`. It is a plain data snapshot on purpose —
+// a consumer must be able to read the whole domain without importing a single schema module.
+//
+// Money is the one place the projection is not one-to-one: one property becomes the two
+// physical columns that back it.
+
+import { bindingOf, snake } from './column';
+import { currencyCheck } from './columns';
+import { invariantViolated } from './errors';
+import type { Invariant } from './invariants';
+import type { ColumnDescription, EntityDescription } from './registry';
+import type { AnyColumn, ColumnMeta, IndexDef } from './types';
+
+export interface DescribeInput<Row> {
+  readonly name: string;
+  readonly columns: readonly (readonly [string, AnyColumn])[];
+  readonly primaryKey: readonly string[];
+  readonly invariants: readonly Invariant<Row>[];
+  readonly indexes: readonly IndexDef[];
+  readonly tags: readonly string[];
+  readonly cacheTag: string;
+  readonly softDelete: boolean;
+  readonly tenantColumn: string | null;
+}
+
+const referenceOf = (entityName: string, property: string, meta: ColumnMeta): string | null => {
+  if (meta.references === undefined) return null;
+  const target = bindingOf(meta.references());
+  if (target === undefined) {
+    throw invariantViolated(
+      entityName,
+      property,
+      'references a column that belongs to no entity — pass a column of an entity() result',
+    );
+  }
+  return `${target.table}.${target.name}`;
+};
+
+const describeColumn = <Row>(
+  input: DescribeInput<Row>,
+  property: string,
+  meta: ColumnMeta,
+): readonly ColumnDescription[] => {
+  const physical = snake(property);
+  if (meta.kind === 'money') {
+    const currency = `${physical}_currency`;
+    const shared = {
+      notNull: meta.notNull,
+      primaryKey: false,
+      unique: false,
+      hasDefault: false,
+      references: null,
+    };
+    return [
+      {
+        property: `${property}Minor`,
+        column: `${physical}_minor`,
+        kind: 'bigint',
+        check: null,
+        ...shared,
+      },
+      {
+        property: `${property}Currency`,
+        column: currency,
+        kind: 'char',
+        check: currencyCheck(currency),
+        ...shared,
+      },
+    ];
+  }
+  return [
+    {
+      property,
+      column: physical,
+      kind: meta.kind,
+      notNull: meta.notNull,
+      primaryKey: meta.primaryKey || input.primaryKey.includes(property),
+      unique: meta.unique,
+      hasDefault: meta.default !== undefined,
+      check: meta.check?.(physical) ?? null,
+      references: referenceOf(input.name, property, meta),
+    },
+  ];
+};
+
+export const describeEntity = <Row>(input: DescribeInput<Row>): EntityDescription => ({
+  name: input.name,
+  table: input.name,
+  primaryKey: input.primaryKey.map((property) => snake(property)),
+  columns: input.columns.flatMap(([property, column]) =>
+    describeColumn(input, property, column.$meta),
+  ),
+  invariants: input.invariants.map((inv) => ({
+    name: inv.name,
+    kind: inv.kind,
+    message: inv.message,
+    sql: inv.sql,
+    where: inv.where ?? null,
+  })),
+  indexes: input.indexes.map((index) => index.name),
+  tags: input.tags,
+  cacheTag: input.cacheTag,
+  softDelete: input.softDelete,
+  orgScoped: input.tenantColumn !== null,
+});

package/src/entity.ts

@@ -1,120 +1,267 @@
-// `entity()` is the first primitive: a table, its domain type, and the invariants
-// that hold for every row. Everything downstream (repo, admin UI, cache tags, the
-// manifest) is derived from this one declaration.
+// `entity(name, { columns })` is the first primitive. The row type is DERIVED from the columns —
+// there is no second declaration of the same shape to keep in sync — and everything downstream
+// (the typed db handle, migrations, cache tags, the admin UI, the manifest) is projected from
+// this one call.
+
 import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { bindColumn, snake } from './column';
+import { newId } from './columns';
+import { describeEntity } from './describe';
 import { invariantViolated } from './errors';
-import { assertInvariants, type Invariant, invariantsToSql } from './invariants';
-import { type EntityDescription, registerEntity } from './registry';
-import { isOrgScoped } from './tenancy';
-import type { ColumnMap, TableDef } from './types';
-
-export type EntitySchema<T> = StandardSchemaV1<unknown, T>;
-
-export interface EntityInit<T, C extends ColumnMap> {
-  /** Defaults to the table name. Must be unique across the app. */
-  readonly name?: string;
-  readonly table: TableDef<C>;
-  readonly type: EntitySchema<T>;
-  readonly invariants?: readonly Invariant<T>[];
+import type { Expr, InvariantColumns, Resolve } from './expr';
+import { invariantColumns } from './expr';
+import type { Invariant, InvariantDef } from './invariants';
+import { assertInvariants, bindInvariant, invariantsToSql } from './invariants';
+import type { EntityDescription } from './registry';
+import { registerEntity } from './registry';
+import { resolveTenantColumn } from './tenancy';
+import type { AnyColumn, ColumnMap, ColumnMeta, IndexDef, RowOf } from './types';
+import type { EntityView } from './view';
+import { viewFor } from './view';
+
+/** Presence of this column is what makes an entity soft-deletable — not a flag. */
+export const SOFT_DELETE_COLUMN = 'deletedAt';
+
+export interface IndexInit<C extends ColumnMap> {
+  readonly on: readonly (keyof C & string)[];
+  readonly order?: 'asc' | 'desc';
+  readonly unique?: boolean;
+  /** Partial index predicate, written in the same language as an invariant. */
+  readonly where?: (columns: InvariantColumns) => Expr;
+}
+
+export interface EntityInit<C extends ColumnMap> {
+  readonly columns: C;
+  /**
+   * The tenant column, said out loud. Omitted, it is inferred from `.tenant()` or a column named
+   * `orgId`, so silence never means unscoped.
+   */
+  readonly tenant?: keyof C & string;
+  /** Composite keys only — a single key is `uuid().primaryKey()` on the column itself. */
+  readonly primaryKey?: readonly (keyof C & string)[];
+  readonly invariants?: readonly InvariantDef[];
+  readonly indexes?: readonly IndexInit<C>[];
   /** Extra cache tags this entity participates in, beyond its own. */
   readonly tags?: readonly string[];
-  /** Defaults to the presence of a `deletedAt` column. */
-  readonly softDelete?: boolean;
 }
 
-export interface Entity<T, C extends ColumnMap = ColumnMap> {
-  readonly name: string;
-  readonly table: TableDef<C>;
-  readonly type: EntitySchema<T>;
-  readonly invariants: readonly Invariant<T>[];
-  readonly tags: readonly string[];
+/**
+ * The row-shaped half of an entity. Consumers that must name "some entity" without naming its
+ * row use `EntityCore`; `Entity` adds the columns themselves, so `orgs.id` is a column
+ * reference and `typeof orgs.$row` is the derived row type.
+ */
+export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
+  readonly $name: string;
+  readonly $table: string;
+  readonly $columns: C;
+  readonly $primaryKey: readonly string[];
+  readonly $indexes: readonly IndexDef[];
+  readonly $invariants: readonly Invariant<Row>[];
+  readonly $tags: readonly string[];
   /** `entity:<name>`. `@ultimat3/cache` invalidates by this string. */
-  readonly cacheTag: string;
-  readonly softDelete: boolean;
-  readonly orgScoped: boolean;
+  readonly $cacheTag: string;
+  readonly $softDelete: boolean;
+  /** Property key of the tenant column, or `null`. Presence is what turns tenancy on. */
+  readonly $tenantColumn: string | null;
+  /** Phantom: `type Post = typeof posts.$row`. Reading it at runtime throws. */
+  readonly $row: Row;
+  /** The Standard Schema the columns already describe — forms and actions hand input to it. */
+  readonly $schema: StandardSchemaV1<unknown, Row>;
   /** `entity:<name>:<id>` — row-level invalidation for live queries. */
-  tagFor(id: string): string;
-  /** Validates an unknown value into the domain type. Throws on failure. */
-  parse(value: unknown): T;
+  $tagFor(id: string): string;
+  /** Fills declared defaults, then validates every column. Throws on a bad value. */
+  $parse(value: unknown): Row;
+  /**
+   * `const PostView = posts.$view(['id', 'title'])` — the projection an action names as its
+   * `output`. An unknown key is a compile error, and a declaration error for a JS caller.
+   */
+  $view<K extends keyof Row & string>(keys: readonly K[]): EntityView<Row, K>;
   /** Runs every invariant. Called by the repository on insert and update. */
-  assert(row: T): void;
+  $assert(row: Row): void;
   /** The CHECK/UNIQUE statements the migration emits for this entity. */
-  migration(): string;
-  describe(): EntityDescription;
+  $migration(): string;
+  $describe(): EntityDescription;
 }
 
-interface LooseResult<T> {
-  readonly value?: T;
-  readonly issues?: readonly { readonly message: string }[] | undefined;
-}
+export type Entity<Row, C extends ColumnMap = ColumnMap> = EntityCore<Row, C> & C;
 
-const parseWith = <T>(schema: EntitySchema<T>, name: string, value: unknown): T => {
-  const result = schema['~standard'].validate(value);
-  if (result instanceof Promise) {
-    throw invariantViolated(name, 'schema', 'entity types must validate synchronously');
-  }
-  const outcome = result as LooseResult<T>;
-  if (outcome.issues !== undefined && outcome.issues.length > 0) {
-    throw invariantViolated(name, 'schema', outcome.issues.map((i) => i.message).join('; '));
-  }
-  return outcome.value as T;
+const MONEY_PARTS = new Set(['minor', 'currency']);
+
+const indexName = (table: string, columns: readonly string[], unique: boolean): string =>
+  `${table}_${columns.join('_')}_${unique ? 'key' : 'idx'}`;
+
+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() : new Date();
 };
 
-export const entity = <T, C extends ColumnMap>(init: EntityInit<T, C>): Entity<T, C> => {
-  const name = init.name ?? init.table.name;
-  const invariants = init.invariants ?? [];
-  const softDelete = init.softDelete ?? Object.hasOwn(init.table.columns, 'deletedAt');
-  const orgScoped = isOrgScoped(init.table);
+export const entity = <const C extends ColumnMap>(
+  name: string,
+  init: EntityInit<C>,
+): Entity<RowOf<C>, C> => {
+  type Row = RowOf<C>;
+  const entries: readonly (readonly [string, AnyColumn])[] = Object.entries(init.columns);
+  for (const [property, column] of entries) bindColumn(column, name, property);
+
   const cacheTag = `entity:${name}`;
+  const softDelete = Object.hasOwn(init.columns, SOFT_DELETE_COLUMN);
+  const tenantColumn = resolveTenantColumn(name, init.columns, init.tenant);
 
-  const describe = (): EntityDescription => ({
-    name,
-    table: init.table.name,
-    primaryKey: init.table.primaryKey,
-    columns: Object.entries(init.table.columns).map(([property, column]) => ({
-      property,
-      column: column.name,
-      kind: column.kind,
-      notNull: column.notNull,
-      primaryKey: column.primaryKey,
-      unique: column.unique,
-      hasDefault: column.default !== undefined,
-      check: column.check ?? null,
-      references:
-        column.references === undefined
-          ? null
-          : `${column.references.table}.${column.references.column}`,
-    })),
-    invariants: invariants.map((inv) => ({
-      name: inv.name,
-      kind: inv.kind,
-      message: inv.message,
-      sql: inv.sql,
-      where: inv.where ?? null,
-    })),
-    indexes: init.table.indexes.map((index) => index.name),
-    tags: [cacheTag, ...(init.tags ?? [])],
-    cacheTag,
-    softDelete,
-    orgScoped,
-  });
-
-  const built: Entity<T, C> = {
+  const primaryKey =
+    init.primaryKey ?? entries.filter(([, column]) => column.$meta.primaryKey).map(([key]) => key);
+  if (primaryKey.length === 0) {
+    throw invariantViolated(
+      name,
+      'primary-key',
+      'no primary key: mark a column .primaryKey() or pass primaryKey: [...] for a composite one',
+    );
+  }
+
+  // Property path -> physical name. The one place `orgId` becomes `org_id`.
+  const resolve: Resolve = (path) => {
+    const [property, part] = path;
+    const column = property === undefined ? undefined : init.columns[property];
+    if (property === undefined || column === undefined) {
+      throw invariantViolated(name, 'invariant', `no column "${String(property)}"`);
+    }
+    const isMoney = column.$meta.kind === 'money';
+    if (part === undefined) {
+      if (isMoney) {
+        throw invariantViolated(
+          name,
+          property,
+          `${property} is money: name ${property}.minor or ${property}.currency`,
+        );
+      }
+      return snake(property);
+    }
+    if (!isMoney || !MONEY_PARTS.has(part)) {
+      throw invariantViolated(name, property, `${property} has no part "${part}"`);
+    }
+    return `${snake(property)}_${part}`;
+  };
+
+  const columnsExpr = invariantColumns(
     name,
-    table: init.table,
-    type: init.type,
-    invariants,
-    tags: [cacheTag, ...(init.tags ?? [])],
-    cacheTag,
-    softDelete,
-    orgScoped,
-    tagFor: (id) => `${cacheTag}:${id}`,
-    parse: (value) => parseWith(init.type, name, value),
-    assert: (row) => assertInvariants(name, invariants, row),
-    migration: () => invariantsToSql(init.table.name, invariants),
-    describe,
+    entries.map(([property]) => property),
+  );
+  const partialWhere = softDelete ? `${snake(SOFT_DELETE_COLUMN)} is null` : undefined;
+  const invariants: readonly Invariant<Row>[] = (init.invariants ?? []).map((def) =>
+    bindInvariant<Row>(def, columnsExpr, resolve, partialWhere),
+  );
+
+  const declared: readonly IndexDef[] = [
+    ...entries.flatMap(([property, column]) => {
+      const meta = column.$meta;
+      if (!meta.unique && !meta.index) return [];
+      const physical = [meta.kind === 'money' ? `${snake(property)}_minor` : snake(property)];
+      return [
+        { name: indexName(name, physical, meta.unique), columns: physical, unique: meta.unique },
+      ];
+    }),
+    ...(init.indexes ?? []).map((index) => {
+      const columns = index.on.map((property) => resolve([property]));
+      const unique = index.unique === true;
+      const where = index.where?.(columnsExpr).toSql(resolve) ?? null;
+      if (index.where !== undefined && where === null) {
+        throw invariantViolated(
+          name,
+          'index',
+          'a partial index predicate must be expressible in SQL; a JS predicate cannot be one',
+        );
+      }
+      return {
+        name: indexName(name, columns, unique),
+        columns,
+        unique,
+        ...(index.order === undefined ? {} : { order: index.order }),
+        ...(where === null ? {} : { where }),
+      };
+    }),
+  ];
+  // A foreign key already indexes its column; naming it again in `indexes` is not two indexes.
+  const indexes: readonly IndexDef[] = declared.filter(
+    (index, position) => declared.findIndex((other) => other.name === index.name) === position,
+  );
+
+  const tags = [cacheTag, ...(init.tags ?? [])];
+  const describe = (): EntityDescription =>
+    describeEntity({
+      name,
+      columns: entries,
+      primaryKey,
+      invariants,
+      indexes,
+      tags,
+      cacheTag,
+      softDelete,
+      tenantColumn,
+    });
+
+  const parse = (value: unknown): Row => {
+    if (typeof value !== 'object' || value === null) {
+      throw invariantViolated(name, 'row', `expected an object, got ${String(value)}`);
+    }
+    const input = value as Readonly<Record<string, unknown>>;
+    const row: Record<string, unknown> = {};
+    for (const [property, column] of entries) {
+      const given = input[property] ?? defaultValue(column.$meta);
+      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 property was validated by its own column above, so the shape is the derived row.
+    return row as Row;
+  };
+
+  const core: EntityCore<Row, C> = {
+    $name: name,
+    $table: name,
+    $columns: init.columns,
+    $primaryKey: primaryKey,
+    $indexes: indexes,
+    $invariants: invariants,
+    $tags: tags,
+    $cacheTag: cacheTag,
+    $softDelete: softDelete,
+    $tenantColumn: tenantColumn,
+    $schema: {
+      '~standard': {
+        version: 1,
+        vendor: 'ultimate',
+        validate: (value) => {
+          try {
+            return { value: parse(value) };
+          } catch (error) {
+            return {
+              issues: [{ message: error instanceof Error ? error.message : String(error) }],
+            };
+          }
+        },
+      },
+    },
+    get $row(): Row {
+      // Type-only. Reading it means someone expected a value where a type was meant.
+      throw invariantViolated(name, '$row', '$row is a type, not a value — use typeof x.$row');
+    },
+    $tagFor: (id) => `${cacheTag}:${id}`,
+    $parse: parse,
+    $view: <K extends keyof Row & string>(keys: readonly K[]) =>
+      viewFor<Row, K>(name, init.columns, keys),
+    $assert: (row) => assertInvariants(name, invariants, row),
+    $migration: () => invariantsToSql(name, invariants),
+    $describe: describe,
   };
 
-  registerEntity({ name, tableName: init.table.name, describe });
-  return built;
+  registerEntity({ name, tableName: name, describe });
+  // The columns land on the entity itself so `orgs.id` is a column reference; every framework
+  // member is `$`-prefixed, which is why a column may be called `name`.
+  return Object.assign(core, init.columns);
 };

package/src/errors.ts

@@ -1,27 +1,49 @@
 // The entity layer's stable error codes. Each factory produces the exact command
 // that fixes the situation — `X_DB_DRIFT` is the flagship: it names the table, the
 // column and the generator invocation.
-import { UltimateError } from '@ultimat3/core';
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
 
-export const ENTITY_ERROR_CODES = [
+/** Codes this package declares and owns. */
+export const ENTITY_OWNED_ERROR_CODES = [
   'X_ENTITY_DUPLICATE',
   'X_INVARIANT_VIOLATED',
   'X_TENANCY_UNSCOPED',
-  'X_DB_DRIFT',
   'X_NOT_FOUND',
 ] as const;
 
+/**
+ * `X_DB_DRIFT` is `@ultimat3/db`'s — drift is a fact about migrations, and this package imports db
+ * rather than the other way round. `dbDrift()` below throws it; nothing here titles it, because a
+ * second copy of the title is what lets the two packages disagree about what the code means.
+ */
+export const ENTITY_BORROWED_ERROR_CODES = ['X_DB_DRIFT'] as const;
+
+/** Every code entity can throw: the ones it owns plus the one it borrows. */
+export const ENTITY_ERROR_CODES = [
+  ...ENTITY_OWNED_ERROR_CODES,
+  ...ENTITY_BORROWED_ERROR_CODES,
+] as const;
+
+export type EntityOwnedErrorCode = (typeof ENTITY_OWNED_ERROR_CODES)[number];
 export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
 
-export const ENTITY_ERROR_TITLES: Readonly<Record<EntityErrorCode, string>> = {
+export const ENTITY_ERROR_TITLES: Readonly<Record<EntityOwnedErrorCode, string>> = {
   X_ENTITY_DUPLICATE: 'two entities claim the same name',
   X_INVARIANT_VIOLATED: 'a domain invariant rejected this row',
   X_TENANCY_UNSCOPED: 'a tenant-scoped query has no org predicate',
-  X_DB_DRIFT: 'schema differs from migrations',
   X_NOT_FOUND: 'no row for that id',
 };
 
+// Registered at module load, unconditionally, in one call. Without this the registry humanises the
+// code and every surface renders a title this package never wrote; with a presence guard, a second
+// package claiming one of these codes would silently win instead of throwing X_ERROR_CODE_DUPLICATE.
+registerErrorCodes(
+  Object.fromEntries(Object.entries(ENTITY_ERROR_TITLES).map(([code, title]) => [code, { title }])),
+);
+
 export class EntityError extends UltimateError {
+  override readonly name = 'EntityError';
+
   constructor(init: { code: EntityErrorCode; cause: string; fix: string }) {
     super({
       code: init.code,
@@ -29,7 +51,6 @@ export class EntityError extends UltimateError {
       fix: init.fix,
       docs: `https://ultimate.dev/errors/${init.code}`,
     });
-    this.name = 'EntityError';
   }
 }