@ultimat3/entity 0.0.1 → 1.0.0

package/src/entity.js

@@ -0,0 +1,160 @@
+// `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 { bindColumn, snake } from './column';
+import { newId } from './columns';
+import { describeEntity } from './describe';
+import { invariantViolated } from './errors';
+import { invariantColumns } from './expr';
+import { assertInvariants, bindInvariant, invariantsToSql } from './invariants';
+import { registerEntity } from './registry';
+import { tenantColumnOf } from './tenancy';
+/** Presence of this column is what makes an entity soft-deletable — not a flag. */
+export const SOFT_DELETE_COLUMN = 'deletedAt';
+const MONEY_PARTS = new Set(['minor', 'currency']);
+const indexName = (table, columns, unique) => `${table}_${columns.join('_')}_${unique ? 'key' : 'idx'}`;
+const defaultValue = (meta) => {
+    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 = (name, init) => {
+    const entries = 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 = tenantColumnOf(init.columns);
+    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 = (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, entries.map(([property]) => property));
+    const partialWhere = softDelete ? `${snake(SOFT_DELETE_COLUMN)} is null` : undefined;
+    const invariants = (init.invariants ?? []).map((def) => bindInvariant(def, columnsExpr, resolve, partialWhere));
+    const declared = [
+        ...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 = declared.filter((index, position) => declared.findIndex((other) => other.name === index.name) === position);
+    const tags = [cacheTag, ...(init.tags ?? [])];
+    const describe = () => describeEntity({
+        name,
+        columns: entries,
+        primaryKey,
+        invariants,
+        indexes,
+        tags,
+        cacheTag,
+        softDelete,
+        tenantColumn,
+    });
+    const parse = (value) => {
+        if (typeof value !== 'object' || value === null) {
+            throw invariantViolated(name, 'row', `expected an object, got ${String(value)}`);
+        }
+        const input = value;
+        const row = {};
+        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;
+    };
+    const core = {
+        $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() {
+            // 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,
+        $assert: (row) => assertInvariants(name, invariants, row),
+        $migration: () => invariantsToSql(name, invariants),
+        $describe: describe,
+    };
+    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);
+};
+//# sourceMappingURL=entity.js.map

package/src/entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.js","sourceRoot":"","sources":["entity.ts"],"names":[],"mappings":"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"}

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.d.ts

@@ -0,0 +1,18 @@
+import { UltimateError } from '@ultimat3/core';
+export declare const ENTITY_ERROR_CODES: readonly ['X_ENTITY_DUPLICATE', 'X_INVARIANT_VIOLATED', 'X_TENANCY_UNSCOPED', 'X_DB_DRIFT', 'X_NOT_FOUND'];
+export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
+export declare const ENTITY_ERROR_TITLES: Readonly<Record<EntityErrorCode, string>>;
+export declare class EntityError extends UltimateError {
+    readonly name = "EntityError";
+    constructor(init: {
+        code: EntityErrorCode;
+        cause: string;
+        fix: string;
+    });
+}
+export declare const entityDuplicate: (name: string, existingTable: string) => EntityError;
+export declare const invariantViolated: (entityName: string, invariantName: string, message: string) => EntityError;
+export declare const tenancyUnscoped: (entityName: string, operation: string) => EntityError;
+export declare const dbDrift: (tableName: string, columnName: string) => EntityError;
+export declare const notFound: (entityName: string, id: string) => EntityError;
+//# sourceMappingURL=errors.d.ts.map

package/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEnE,eAAO,MAAM,kBAAkB,YAC7B,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,EACpB,YAAY,EACZ,aAAa,CACL,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAMzE,CAAC;AASF,qBAAa,WAAY,SAAQ,aAAa;IAC5C,SAAkB,IAAI,iBAAiB;IAEvC,YAAY,IAAI,EAAE;QAAE,IAAI,EAAE,eAAe,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAOtE;CACF;AAED,eAAO,MAAM,eAAe,SAAU,MAAM,iBAAiB,MAAM,KAAG,WAKlE,CAAC;AAEL,eAAO,MAAM,iBAAiB,eAChB,MAAM,iBACH,MAAM,WACZ,MAAM,KACd,WAKC,CAAC;AAEL,eAAO,MAAM,eAAe,eAAgB,MAAM,aAAa,MAAM,KAAG,WAKpE,CAAC;AAEL,eAAO,MAAM,OAAO,cAAe,MAAM,cAAc,MAAM,KAAG,WAK5D,CAAC;AAEL,eAAO,MAAM,QAAQ,eAAgB,MAAM,MAAM,MAAM,KAAG,WAKtD,CAAC"}

package/src/errors.js

@@ -0,0 +1,59 @@
+// 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 { registerErrorCodes, UltimateError } from '@ultimat3/core';
+export const ENTITY_ERROR_CODES = [
+    'X_ENTITY_DUPLICATE',
+    'X_INVARIANT_VIOLATED',
+    'X_TENANCY_UNSCOPED',
+    'X_DB_DRIFT',
+    'X_NOT_FOUND',
+];
+export const ENTITY_ERROR_TITLES = {
+    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, like every other package's errors.ts. Without this the
+// registry humanises the code (`X_DB_DRIFT` → "db drift") and the terminal, the overlay
+// and `--json` all render a title this package never wrote.
+registerErrorCodes(Object.fromEntries(Object.entries(ENTITY_ERROR_TITLES).map(([code, title]) => [code, { title }])));
+export class EntityError extends UltimateError {
+    name = 'EntityError';
+    constructor(init) {
+        super({
+            code: init.code,
+            cause: init.cause,
+            fix: init.fix,
+            docs: `https://ultimate.dev/errors/${init.code}`,
+        });
+    }
+}
+export const entityDuplicate = (name, existingTable) => new EntityError({
+    code: 'X_ENTITY_DUPLICATE',
+    cause: `entity "${name}" is already registered for table "${existingTable}"`,
+    fix: `x entities list --json   # then rename one of the two entity({ name }) declarations`,
+});
+export const invariantViolated = (entityName, invariantName, message) => new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.${invariantName}: ${message}`,
+    fix: `x entity explain ${entityName} --json   # shows the invariant and its SQL CHECK`,
+});
+export const tenancyUnscoped = (entityName, operation) => new EntityError({
+    code: 'X_TENANCY_UNSCOPED',
+    cause: `${entityName}.${operation}() was built without an org predicate but the entity has an orgId column`,
+    fix: `pass { orgId } to ${entityName}.${operation}(), or wrap the plan with orgScoped(entity, orgId, plan)`,
+});
+export const dbDrift = (tableName, columnName) => new EntityError({
+    code: 'X_DB_DRIFT',
+    cause: `table "${tableName}" has column "${columnName}" not present in any migration`,
+    fix: `x db gen "add ${columnName}"`,
+});
+export const notFound = (entityName, id) => new EntityError({
+    code: 'X_NOT_FOUND',
+    cause: `${entityName} ${id} does not exist (or is soft-deleted)`,
+    fix: `x db query "select id from ${entityName} limit 5" --json   # confirm the id you expect`,
+});
+//# sourceMappingURL=errors.js.map

package/src/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,mFAAmF;AACnF,uCAAuC;AACvC,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEnE,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,oBAAoB;IACpB,sBAAsB;IACtB,oBAAoB;IACpB,YAAY;IACZ,aAAa;CACL,CAAC;AAIX,MAAM,CAAC,MAAM,mBAAmB,GAA8C;IAC5E,kBAAkB,EAAE,kCAAkC;IACtD,oBAAoB,EAAE,sCAAsC;IAC5D,kBAAkB,EAAE,4CAA4C;IAChE,UAAU,EAAE,gCAAgC;IAC5C,WAAW,EAAE,oBAAoB;CAClC,CAAC;AAEF,oFAAoF;AACpF,wFAAwF;AACxF,4DAA4D;AAC5D,kBAAkB,CAChB,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAClG,CAAC;AAEF,MAAM,OAAO,WAAY,SAAQ,aAAa;IAC1B,IAAI,GAAG,aAAa,CAAC;IAEvC,YAAY,IAA2D;QACrE,KAAK,CAAC;YACJ,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,IAAI,EAAE,+BAA+B,IAAI,CAAC,IAAI,EAAE;SACjD,CAAC,CAAC;IACL,CAAC;CACF;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAY,EAAE,aAAqB,EAAe,EAAE,CAClF,IAAI,WAAW,CAAC;IACd,IAAI,EAAE,oBAAoB;IAC1B,KAAK,EAAE,WAAW,IAAI,sCAAsC,aAAa,GAAG;IAC5E,GAAG,EAAE,qFAAqF;CAC3F,CAAC,CAAC;AAEL,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,UAAkB,EAClB,aAAqB,EACrB,OAAe,EACF,EAAE,CACf,IAAI,WAAW,CAAC;IACd,IAAI,EAAE,sBAAsB;IAC5B,KAAK,EAAE,GAAG,UAAU,IAAI,aAAa,KAAK,OAAO,EAAE;IACnD,GAAG,EAAE,oBAAoB,UAAU,mDAAmD;CACvF,CAAC,CAAC;AAEL,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,UAAkB,EAAE,SAAiB,EAAe,EAAE,CACpF,IAAI,WAAW,CAAC;IACd,IAAI,EAAE,oBAAoB;IAC1B,KAAK,EAAE,GAAG,UAAU,IAAI,SAAS,0EAA0E;IAC3G,GAAG,EAAE,qBAAqB,UAAU,IAAI,SAAS,0DAA0D;CAC5G,CAAC,CAAC;AAEL,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,SAAiB,EAAE,UAAkB,EAAe,EAAE,CAC5E,IAAI,WAAW,CAAC;IACd,IAAI,EAAE,YAAY;IAClB,KAAK,EAAE,UAAU,SAAS,iBAAiB,UAAU,gCAAgC;IACrF,GAAG,EAAE,iBAAiB,UAAU,GAAG;CACpC,CAAC,CAAC;AAEL,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,UAAkB,EAAE,EAAU,EAAe,EAAE,CACtE,IAAI,WAAW,CAAC;IACd,IAAI,EAAE,aAAa;IACnB,KAAK,EAAE,GAAG,UAAU,IAAI,EAAE,sCAAsC;IAChE,GAAG,EAAE,8BAA8B,UAAU,gDAAgD;CAC9F,CAAC,CAAC"}