@ultimat3/entity 0.0.1 → 1.0.0

package/src/cursor.ts

@@ -0,0 +1,187 @@
+// Single responsibility: what an entity cursor *means*. The codec is `@ultimat3/core`'s — this
+// file decides what a page position is bound to (the plan that produced it) and how a sort value
+// survives the round trip (the column's kind).
+//
+// Both drivers call `cursorFor` and `seekFrom` and nothing else, so a rule added to one is added
+// to both. The cursor carries the sort VALUES, not just an id: seeking by id alone needs the row
+// to still exist, and a row deleted between two pages would silently restart pagination.
+
+import { CursorInvalidError, decodeCursor, encodeCursor } from '@ultimat3/core';
+import type { EntityCore } from './entity';
+import { invariantViolated } from './errors';
+import type { QueryPlan } from './tenancy';
+import type { AnyColumn, ColumnKind } from './types';
+
+const MONEY_PARTS: Readonly<Record<string, ColumnKind>> = { minor: 'bigint', currency: 'char' };
+
+/** Resolves `price.minor` as well as `title`; money is the one property with two parts. */
+const partsOf = (path: string): { readonly property: string; readonly part?: string } => {
+  const [property = path, part] = path.split('.');
+  return part === undefined ? { property } : { property, part };
+};
+
+const columnAt = <Row>(entity: EntityCore<Row>, path: string): AnyColumn => {
+  const column = entity.$columns[partsOf(path).property];
+  if (column === undefined) {
+    throw invariantViolated(entity.$name, 'orderBy', `no column "${path}"`);
+  }
+  return column;
+};
+
+/** The physical type a sort key holds — what tells `revive` how to read its string back. */
+const kindAt = <Row>(entity: EntityCore<Row>, path: string): ColumnKind => {
+  const { part } = partsOf(path);
+  const kind = columnAt(entity, path).$meta.kind;
+  if (part === undefined) {
+    // Money is two physical columns, so the property alone names no single sort value: the
+    // cursor would carry `String({ minor, currency })` and the next page would fail parsing it
+    // as a bare `SyntaxError` from `BigInt`, with no code and no fix. `entity()` refuses the
+    // same path in `resolve()`; refusing it here keeps one answer for one mistake.
+    if (kind !== 'money') return kind;
+    throw invariantViolated(
+      entity.$name,
+      'orderBy',
+      `${path} is money: order by ${path}.minor or ${path}.currency`,
+    );
+  }
+  const money = kind === 'money' ? MONEY_PARTS[part] : undefined;
+  if (money === undefined) {
+    throw invariantViolated(entity.$name, 'orderBy', `${path} names no column part`);
+  }
+  return money;
+};
+
+export const valueAt = (row: unknown, path: string): unknown => {
+  const { property, part } = partsOf(path);
+  const record = typeof row === 'object' && row !== null ? (row as Record<string, unknown>) : {};
+  const base = record[property];
+  if (part === undefined) return base;
+  return typeof base === 'object' && base !== null
+    ? (base as Record<string, unknown>)[part]
+    : undefined;
+};
+
+/** Stringified so the cursor is JSON; `revive` restores the type from the column's kind. */
+const serializeSortValue = (value: unknown): string => {
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === 'bigint') return value.toString();
+  return String(value);
+};
+
+// No `money` case: `kindAt` resolves a money sort key to the kind of the part being ordered by
+// (`minor` is bigint, `currency` is char) and refuses the bare property, so the composite kind
+// never reaches here. A case for it could only ever revive "[object Object]".
+const reviveSortValue = (kind: ColumnKind, text: string): unknown => {
+  switch (kind) {
+    case 'timestamptz':
+      return new Date(text);
+    case 'bigint':
+      return BigInt(text);
+    case 'integer':
+      return Number(text);
+    case 'boolean':
+      return text === 'true';
+    default:
+      return text;
+  }
+};
+
+/**
+ * A keyset seek only has a total order when every sort column is present on every row —
+ * `null > 'x'` is unknown in SQL and would drop rows from the middle of a listing.
+ *
+ * Checked when a cursor is minted as well as when one is decoded: an ordering that cannot carry
+ * a position is the author's mistake, and reporting it on the *second* page hides it behind
+ * whatever page size the caller happened to use.
+ */
+export const assertSeekable = <Row>(
+  entity: EntityCore<Row>,
+  orderBy: readonly { readonly column: string }[],
+): void => {
+  for (const key of orderBy) {
+    // Resolving the kind is the other half: it refuses a column the entity never declared and a
+    // money property named without its part — both mint a cursor nothing can decode.
+    kindAt(entity, key.column);
+    if (columnAt(entity, key.column).$meta.notNull) continue;
+    throw invariantViolated(
+      entity.$name,
+      'cursor',
+      `${key.column} is nullable and cannot carry a cursor — order by a not-null column ` +
+        `(add .orderBy('${entity.$primaryKey[0] ?? 'id'}') or make ${key.column} not null)`,
+    );
+  }
+};
+
+/** Deterministic, and total over the value shapes a predicate can hold. */
+const renderValue = (value: unknown): string => {
+  if (value === null || value === undefined) return 'null';
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === 'bigint') return `${value}n`;
+  if (Array.isArray(value)) return `[${value.map(renderValue).join(',')}]`;
+  if (typeof value === 'object') {
+    const record = value as Readonly<Record<string, unknown>>;
+    const keys = Object.keys(record).sort();
+    return `{${keys.map((key) => `${key}:${renderValue(record[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(String(value));
+};
+
+/**
+ * What a cursor is bound to: this entity, these filters, this sort order. Not the page size — a
+ * client may legitimately ask for a bigger next page — and not the projection, which cannot move
+ * a row's position. Filters are sorted because `and` is commutative, so two chains that build the
+ * same predicate set page each other's cursors.
+ *
+ * Hashed rather than spelled out: a cursor is base64, not encrypted, and the caller's filter
+ * values are not the client's to read.
+ */
+export const planScope = (plan: QueryPlan): string => {
+  const where = plan.where
+    .map((predicate) => `${predicate.column} ${predicate.op} ${renderValue(predicate.value)}`)
+    .sort()
+    .join('&');
+  const order = plan.orderBy.map((key) => `${key.column} ${key.direction}`).join(',');
+  return new Bun.CryptoHasher('sha256')
+    .update(`${plan.entity}|${where}|${order}`)
+    .digest('hex')
+    .slice(0, 16);
+};
+
+/** The cursor that continues this plan after `row`. Signed by core, scoped by the plan. */
+export const cursorFor = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+  row: unknown,
+  id: string,
+): string => {
+  assertSeekable(entity, plan.orderBy);
+  return encodeCursor({
+    scope: planScope(plan),
+    key: plan.orderBy.map((entry) => serializeSortValue(valueAt(row, entry.column))),
+    id,
+  });
+};
+
+/**
+ * The keyset position a plan resumes from, revived to the types its columns hold — `undefined`
+ * when the plan has no cursor. A cursor that was tampered with, or taken from another entity,
+ * another filter or another sort order, is `X_CURSOR_INVALID` here rather than a silent page one.
+ */
+export const seekFrom = <Row>(
+  entity: EntityCore<Row>,
+  plan: QueryPlan,
+): readonly unknown[] | undefined => {
+  if (plan.cursor === undefined) return undefined;
+  const { key } = decodeCursor(plan.cursor, planScope(plan));
+  assertSeekable(entity, plan.orderBy);
+  // Unreachable through the scope check, which already pins the sort order — kept because the
+  // alternative to a bad arity is `?? ''`, and that seeks from an empty string.
+  if (key.length !== plan.orderBy.length) {
+    throw new CursorInvalidError(
+      `it carries ${key.length} sort values, this order needs ${plan.orderBy.length}`,
+    );
+  }
+  return plan.orderBy.map((entry, index) =>
+    reviveSortValue(kindAt(entity, entry.column), String(key[index])),
+  );
+};

package/src/database.d.ts

@@ -0,0 +1,21 @@
+import type { EntityCore } from './entity';
+import type { Table } from './query';
+import type { Repo } 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 declare const memoryDriver: () => Driver;
+export declare const database: <E extends EntitySet>(entities: E, options?: DatabaseOptions) => Database<E>;
+//# sourceMappingURL=database.d.ts.map

package/src/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["database.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAGnC,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;AAE7D,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,SAAS,IAAI;IAC1C,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;CAC/D,CAAC;AAEF,+FAA+F;AAC/F,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAO,MAa/B,CAAC;AASF,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,SAAS,YAChC,CAAC,YACF,eAAe,KACvB,QAAQ,CAAC,CAAC,CAQZ,CAAC"}

package/src/database.js

@@ -0,0 +1,38 @@
+// 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 { tableFor } from './query';
+import { memoryRepo } from './repo';
+/**
+ * The default driver: correct semantics, no database, so `x dev` and every test run before
+ * the first migration exists.
+ */
+export const memoryDriver = () => {
+    const repos = new Map();
+    return {
+        repo(entity) {
+            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;
+            const created = memoryRepo(entity);
+            repos.set(entity.$name, created);
+            return created;
+        },
+    };
+};
+let shared;
+const defaultDriver = () => {
+    shared ??= memoryDriver();
+    return shared;
+};
+export const database = (entities, options = {}) => {
+    const driver = options.driver ?? defaultDriver();
+    const tables = {};
+    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;
+};
+//# sourceMappingURL=database.js.map

package/src/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["database.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,6FAA6F;AAI7F,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAiBpC;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,GAAW,EAAE;IACvC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAmB,CAAC;IACzC,OAAO;QACL,IAAI,CAAM,MAAuB;YAC/B,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACzC,sFAAsF;YACtF,8CAA8C;YAC9C,IAAI,QAAQ,KAAK,SAAS;gBAAE,OAAO,QAAqB,CAAC;YACzD,MAAM,OAAO,GAAG,UAAU,CAAM,MAAM,CAAC,CAAC;YACxC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YACjC,OAAO,OAAO,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC,CAAC;AAEF,IAAI,MAA0B,CAAC;AAE/B,MAAM,aAAa,GAAG,GAAW,EAAE;IACjC,MAAM,KAAK,YAAY,EAAE,CAAC;IAC1B,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,QAAW,EACX,OAAO,GAAoB,EAAE,EAChB,EAAE;IACf,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,aAAa,EAAE,CAAC;IACjD,MAAM,MAAM,GAA4B,EAAE,CAAC;IAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrD,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IACtD,CAAC;IACD,kFAAkF;IAClF,OAAO,MAAqB,CAAC;AAC/B,CAAC,CAAC"}

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

@@ -0,0 +1,16 @@
+import type { Invariant } from './invariants';
+import type { EntityDescription } from './registry';
+import type { AnyColumn, 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;
+}
+export declare const describeEntity: <Row>(input: DescribeInput<Row>) => EntityDescription;
+//# sourceMappingURL=describe.d.ts.map

package/src/describe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.d.ts","sourceRoot":"","sources":["describe.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAqB,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAc,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/D,MAAM,WAAW,aAAa,CAAC,GAAG;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC;IAC5D,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AA8DD,eAAO,MAAM,cAAc,GAAI,GAAG,SAAS,aAAa,CAAC,GAAG,CAAC,KAAG,iBAmB9D,CAAC"}

package/src/describe.js

@@ -0,0 +1,79 @@
+// 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';
+const referenceOf = (entityName, property, meta) => {
+    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 = (input, property, meta) => {
+    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 = (input) => ({
+    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,
+});
+//# sourceMappingURL=describe.js.map

package/src/describe.js.map

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

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

@@ -0,0 +1,58 @@
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { Expr, InvariantColumns } from './expr';
+import type { Invariant, InvariantDef } from './invariants';
+import type { EntityDescription } from './registry';
+import type { ColumnMap, IndexDef, RowOf } from './types';
+/** Presence of this column is what makes an entity soft-deletable — not a flag. */
+export declare 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;
+    /** 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[];
+}
+/**
+ * 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;
+    /** 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;
+    /** Fills declared defaults, then validates every column. Throws on a bad value. */
+    $parse(value: unknown): Row;
+    /** Runs every invariant. Called by the repository on insert and update. */
+    $assert(row: Row): void;
+    /** The CHECK/UNIQUE statements the migration emits for this entity. */
+    $migration(): string;
+    $describe(): EntityDescription;
+}
+export type Entity<Row, C extends ColumnMap = ColumnMap> = EntityCore<Row, C> & C;
+export declare const entity: <const C extends ColumnMap>(name: string, init: EntityInit<C>) => Entity<RowOf<C>, C>;
+//# sourceMappingURL=entity.d.ts.map

package/src/entity.d.ts.map

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