@thomasfosterau/effect-drizzle-ext 0.0.0 → 0.1.0

package/dist/versioned-chain.d.ts

@@ -0,0 +1,524 @@
+import { F as Tree } from "./index-CFhgcF4N.js";
+import { ColumnBuilders, DeriveOptions, DerivedColumns } from "./derive.js";
+import { ColumnBuilderBase, GetColumnData, SQL } from "drizzle-orm";
+import { AnyPgColumn, ExtraConfigColumn, PgBigInt64Builder, PgBuildColumns, PgSchema, PgTable, PgTableExtraConfigValue, PgTableWithColumns, PgTextBuilder, PgTimestampBuilder, PgUUIDBuilder, PgViewWithSelection, SetHasDefault, SetIsPrimaryKey, SetNotNull } from "drizzle-orm/pg-core";
+/** A parent version table contributes its `(id, version)` key as the FK target. */
+type ParentVersionTable = PgTable & {
+  id: AnyPgColumn;
+  version: AnyPgColumn;
+};
+/** The stable row's `id` + `type` columns a discriminator hook constrains. */
+export interface DiscriminatorColumns {
+  id: AnyPgColumn;
+  type: AnyPgColumn;
+}
+/**
+ * Declaration accepted by a {@link makeSubtypeTables} builder.
+ *
+ * **The optional members below are NOT migrated to `Option`, and must not be.**
+ * Two reasons, either sufficient:
+ *
+ * 1. This is the config a hierarchy hands the Drizzle table builder, and it is
+ *    handed on unchanged to a consuming application's database package — a
+ *    signature change here is a signature change for every consumer.
+ * 2. Every one of them is threaded straight into a Drizzle builder call
+ *    (`bigint().default(versionDefault)`, `discriminator`, …). Drizzle reads
+ *    plain `undefined` as "not supplied"; an `Option` would be an object it
+ *    would try to emit as a value, producing wrong DDL that no type error and
+ *    no unit test would catch.
+ *
+ * The explicit `| undefined` on each is likewise deliberate: a configuring
+ * layer can thread its own optional overrides through without per-property
+ * conditional spreads (`exactOptionalPropertyTypes`).
+ *
+ * Constraint and column names are canonical (`${name}_version_pkey`,
+ * `${name}_version_${parentVersion}_fk`, an `id` column): no deployed schema
+ * needs the historical overrides (effect-drizzle-ext#112, decision 4).
+ */
+export interface SubtypeTablesConfig<TColumns extends Record<string, ColumnBuilderBase>, TDiscriminator> {
+  /** Leaf name; the version table is `${name}_version` (e.g. `video`). */
+  name: string;
+  /**
+   * The parent branch's stable `id` column the leaf's stable row references
+   * (cascade delete).
+   */
+  parentId: AnyPgColumn;
+  /**
+   * The parent branch's version table; the leaf version's `(id, version)`
+   * foreign-keys to its `(id, version)`. Its name seeds the FK constraint name
+   * (`${name}_version_${parentVersionName}_fk`).
+   */
+  parentVersion: ParentVersionTable;
+  /** The leaf's own domain columns (beyond the generated id/version). */
+  columns: TColumns;
+  /**
+   * Default for the `version` column — e.g. `0n` for branch-extending leaves
+   * whose first version row is written with an explicit `0`. Omitted leaves get
+   * a plain `NOT NULL` version.
+   */
+  versionDefault?: bigint | undefined;
+  /**
+   * Extra version-table constraints/indexes appended after the generated primary
+   * key and parent-version foreign key. The callback receives the version
+   * table's columns (including any generated column declared in `columns`).
+   */
+  extraConstraints?: ((table: Record<string, ExtraConfigColumn>) => PgTableExtraConfigValue[]) | undefined;
+  /**
+   * The discriminator declaration for this leaf's stable row. When present, the
+   * stable `type` column is made `NOT NULL` and the injected discriminator hook
+   * appends its constraints; when absent the stable row keeps a nullable `type`.
+   * Its shape is whatever the injected hook consumes.
+   */
+  discriminator?: TDiscriminator | undefined;
+}
+/**
+ * The stable identity row's generated column builders — `id` (the primary key
+ * that references the parent branch's stable `id`) and the denormalised leaf
+ * `type` discriminator.
+ *
+ * `type` is a plain {@link PgTextBuilder} rather than a union with its
+ * `.notNull()` form because the two reduce: `SetNotNull<T>` is `T & …`, so
+ * `SetNotNull<T> | T` collapses to `T` under union subtype reduction. This
+ * restates what the compiler already infers for the ternary in the body, it does
+ * not widen it — the `NOT NULL` a discriminator adds was never in the inferred
+ * type either.
+ */
+type SubtypeStableColumnBuilders = {
+  id: SetIsPrimaryKey<PgUUIDBuilder>;
+  type: PgTextBuilder<[string, ...string[]]>;
+};
+/**
+ * The version row's column builders: the generated `(id, version)` key columns
+ * plus the leaf's own domain columns. `version` is a plain
+ * `SetNotNull<PgBigInt64Builder>` for the same subtype-reduction reason `type`
+ * is above — `bigint().notNull().default(…)` is `HasDefault<SetNotNull<…>>`, a
+ * subtype of the no-default branch, so the union the ternary produces has
+ * already collapsed.
+ *
+ * This alias is referenced **both** by {@link SubtypeTables} and by the explicit
+ * type arguments at the `schema.table` call that builds the table, and it has to
+ * be: see the note on that call.
+ */
+type SubtypeVersionColumnBuilders<TColumns extends Record<string, ColumnBuilderBase>> = {
+  id: SetNotNull<PgUUIDBuilder>;
+  version: SetNotNull<PgBigInt64Builder>;
+} & TColumns;
+/**
+ * The `{ stable, version }` table pair a {@link makeSubtypeTables} builder
+ * returns.
+ *
+ * **Why this is written out rather than inferred.** Declaration emit cannot
+ * name the inferred form. `PgBuildColumns<TTableName, TColumnsMap>` is a
+ * homomorphic mapped type; when `TColumnsMap` is generic (it contains this
+ * builder's `TColumns`) the compiler cannot reduce it, and the declaration
+ * printer expands the mapped type's *body* while printing drizzle's own
+ * `TTableName` type parameter by name — a name that is not in scope in the
+ * emitted `.d.ts`. The result is an unbound type reference: `tsc` resolves it to
+ * the error type, `skipLibCheck: true` hides the `TS2304`, and every consumer
+ * reading these tables through the emitted declarations silently gets `any`
+ * where it should get the column's real type — a consuming application's
+ * database package degrading a table's `$inferSelect["id"]` from `string` to
+ * `any` with no type error anywhere in the chain (website #1579). This
+ * package's own `tests/dist-consumer` type-checks a consumer fixture against
+ * the emitted `dist/`, asserting the chain tables' row types precisely to
+ * catch this regression (an unbound name degrades them to `any`, and an
+ * `Equals<…>` assertion against `any` is false); it is the gate this module
+ * exists chiefly to satisfy.
+ *
+ * An explicit annotation is emitted verbatim as a type *reference*, so the
+ * printer never expands the mapped type and `TTableName` stays bound to
+ * drizzle's own declaration. Both `PgBuildColumns` instantiations below restate
+ * exactly the arguments the call sites already infer — the tables are still
+ * built by `schema.table(…)`, and this only names what it returns.
+ *
+ * Identical behaviour under TypeScript 6.0.3 and the 7.x tsgo build; this is a
+ * printer limitation in both, not a version-specific bug.
+ */
+export interface SubtypeTables<TColumns extends Record<string, ColumnBuilderBase>> {
+  stable: PgTableWithColumns<{
+    name: string;
+    schema: string;
+    columns: PgBuildColumns<string, SubtypeStableColumnBuilders>;
+    dialect: "pg";
+    isAlias: false;
+  }>;
+  version: PgTableWithColumns<{
+    name: `${string}_version`;
+    schema: string;
+    columns: PgBuildColumns<`${string}_version`, SubtypeVersionColumnBuilders<TColumns>>;
+    dialect: "pg";
+    isAlias: false;
+  }>;
+}
+/**
+ * Build a `defineSubtypeTables` bound to a discriminator hook. The hook turns a
+ * leaf's `discriminator` declaration into the stable-table constraints that
+ * enforce it (e.g. a `UNIQUE(id, type)` + composite `(id, type)` → parent FK +
+ * per-level CHECK trio); a hierarchy without a discriminator passes a hook that
+ * is simply never invoked (its leaves omit `discriminator`).
+ *
+ * The returned builder emits a regular subtype's `{ stable, version }` table
+ * pair with the composite-`(id, version)` FK chain to its parent branch.
+ */
+export declare const makeSubtypeTables: <TDiscriminator>(applyDiscriminator: (level: string, stable: DiscriminatorColumns, discriminator: TDiscriminator) => PgTableExtraConfigValue[]) => <TColumns extends Record<string, ColumnBuilderBase>>(schema: PgSchema, { name, parentId, parentVersion, columns, versionDefault, extraConstraints, discriminator }: SubtypeTablesConfig<TColumns, TDiscriminator>) => SubtypeTables<TColumns>;
+/** A version table participates in the chain via its `(id, version)` key. */
+interface VersionTable {
+  id: AnyPgColumn;
+  version: AnyPgColumn;
+}
+/** A stable identity table is joined on `id` alone. */
+interface StableTable {
+  id: AnyPgColumn;
+}
+/** The explicit, projection-shaped column selection a leaf authors. */
+type ViewColumns = Record<string, AnyPgColumn | SQL | SQL.Aliased>;
+/** Resolve one selected field to its inferred (nullability-aware) row type. */
+type ViewField<TField> = TField extends AnyPgColumn ? GetColumnData<TField> : TField extends SQL<infer U> ? U : TField extends SQL.Aliased<infer U> ? U : never;
+/** Inferred `$inferSelect` row for an explicit {@link ViewColumns} map. */
+type ViewRow<TColumns extends ViewColumns> = { [K in keyof TColumns]: ViewField<TColumns[K]>; };
+/**
+ * The view type a {@link makeCurrentVersionView} builder returns: a real Drizzle
+ * view (usable in `from` / `join` and exposing the column proxies for
+ * `eq(view.col, …)`) with `$inferSelect` pinned to the explicit column map plus
+ * the injected always-merged columns `TMerge`.
+ *
+ * The selection is built directly from `columns` + `merge`, so this never
+ * depends on the in-body select's nullability/table-name generics — which
+ * collapse to `{ [x: string]: never }` because the join chain is assembled
+ * untyped.
+ */
+type CurrentVersionViewResult<TColumns extends ViewColumns, TMerge extends ViewColumns> = Omit<PgViewWithSelection<{
+  name: string;
+  schema: string;
+  existing: false;
+  selectedFields: TColumns & TMerge;
+  isAlias: false;
+}>, "$inferSelect"> & {
+  $inferSelect: ViewRow<TColumns & TMerge>;
+};
+/**
+ * Declaration accepted by a {@link makeCurrentVersionView} builder.
+ *
+ * **The optional members below are NOT migrated to `Option`, and must not be** —
+ * for the same two reasons as {@link SubtypeTablesConfig}: the interface is
+ * handed on unchanged to a consuming application's database package, and each
+ * member is spread straight into the generated Drizzle join chain
+ * (`for (const table of through ?? [])`), where `undefined` means "no such
+ * join" and an `Option` would be a truthy object.
+ */
+export interface CurrentVersionViewConfig<TColumns extends ViewColumns> {
+  /** Leaf version table the view resolves to its latest row. */
+  leaf: VersionTable;
+  /**
+   * Intermediate version tables joined on the composite `(id, version)` key,
+   * ordered leaf → branch. The root version table is always appended after these
+   * by the builder. A **required fact table** (a 6NF satellite keyed
+   * `(id, version)` whose row must exist at every version) also joins here —
+   * the INNER JOIN doubles as its fail-closed witness.
+   */
+  through?: VersionTable[] | undefined;
+  /**
+   * **Optional fact tables** LEFT JOINed at the current `(id, version)`: 6NF
+   * satellites whose row-absence at a version encodes NULL (the fact-scoped
+   * version storage decision). Selected columns sourced from these must be
+   * projected nullability-aware (an `sql<T | null>` aliased expression), since
+   * the LEFT JOIN widens a NOT NULL fact column to nullable in the row.
+   */
+  optional?: VersionTable[] | undefined;
+  /** Stable identity tables joined on `id` (explicit `undefined` admitted, as above). */
+  on?: StableTable[] | undefined;
+  /** Explicit column selection, including `id`, `action`, and `timestamp`. */
+  columns: TColumns;
+}
+/** Injected dependencies for a {@link makeCurrentVersionView} builder. */
+export interface CurrentVersionViewDeps<TRoot extends PgTable & VersionTable, TMerge extends ViewColumns> {
+  /**
+   * The root version table currency resolves from — a `MAX(version)` sub-select
+   * groups it by `id`, and the leaf / intermediate version tables INNER JOIN at
+   * that current `(id, version)`. Also joined for the current row's own columns
+   * (e.g. an `action` soft-delete gate and a `timestamp`).
+   */
+  rootVersion: TRoot;
+  /** The always-joined identity row (joined on `id`). */
+  identity: StableTable;
+  /**
+   * Columns merged into every view's selection (sourced from `identity`), so no
+   * leaf needs to name them — e.g. a shared `slug`.
+   *
+   * Passing a **function** instead of a plain object additionally INNER JOINs a
+   * `version = 0` alias of `rootVersion` — the node's birth row — and hands it
+   * to the callback, so a hierarchy can merge in a true `createdAt` sourced
+   * from the first version's own timestamp, distinct from the current
+   * version's. The plain-object form skips that join entirely, leaving the
+   * emitted view definition byte-identical to before: this matters for a root
+   * version table whose current-version view is itself joined **as a view** by
+   * another hand-written view, where changing its definition would require
+   * drizzle-kit to DROP it — and drizzle-kit doesn't topologically order
+   * view-on-view DROPs, so it fails against the still-dependent view.
+   *
+   * That hazard is confined to a hierarchy's own hand-written views layered on
+   * top: the join chain this builder generates only ever reaches version and
+   * stable tables (`leaf`, `through`, `optional`, `on`, `identity`,
+   * `rootVersion`), never a {@link CurrentVersionViewResult} this module
+   * itself returns. No view built by `makeCurrentVersionView` may select from
+   * another view built by `makeCurrentVersionView` — that is a library-level
+   * rule, not just this comment's observation.
+   */
+  merge: TMerge | ((versionZero: TRoot) => TMerge);
+}
+/**
+ * Build a `currentVersionView` bound to a root version table + identity row.
+ * `schema.view(name).as(...)` with the uniform join chain generated from
+ * {@link CurrentVersionViewConfig}.
+ *
+ * The joins only widen the `FROM` clause; they never change the explicit
+ * `columns` selection, so the view's `$inferSelect` is derived directly from
+ * `columns` + the injected `merge` via {@link CurrentVersionViewResult}. The
+ * runtime query is assembled untyped (the chain alternates join shapes), which
+ * is why the return type is asserted rather than inferred: letting `.as()` infer
+ * the selection through `.from(current)` collapses every column to `never`.
+ *
+ * Currency is resolved from `rootVersion` (fail-closed): a `MAX(version)`
+ * sub-select drives the FROM, and the leaf / intermediate version tables INNER
+ * JOIN at that current `(id, version)`. One row per node (the sub-select groups
+ * by id) landing on unique `(id, version)` PKs, so no `DISTINCT ON` / `ORDER BY`
+ * is needed. A leaf missing at the current version drops out of the INNER JOIN —
+ * the view yields no row.
+ */
+export declare const makeCurrentVersionView: <TRoot extends PgTable & VersionTable, TMerge extends ViewColumns>({ rootVersion, identity, merge }: CurrentVersionViewDeps<TRoot, TMerge>) => <TColumns extends ViewColumns>(schema: PgSchema, name: string, { leaf, through, optional, on, columns }: CurrentVersionViewConfig<TColumns>) => CurrentVersionViewResult<TColumns, TMerge>;
+/**
+ * The actions a version-chain row records by default: a chain appends a
+ * `(version, action, timestamp)` row per edit rather than rewriting in place,
+ * and a delete is a tombstone version.
+ */
+export type VersionAction = "create" | "update" | "delete";
+/**
+ * One entry in a node's append-only version chain — what a version-history
+ * listing returns per row. `Action` is the chain's own action vocabulary
+ * (default {@link VersionAction}).
+ */
+export interface VersionChainEntry<Action extends string = VersionAction> {
+  /** The version number (0 is the create). */
+  readonly version: bigint;
+  /** The edit action this version recorded. */
+  readonly action: Action;
+  /** When the version was written. */
+  readonly timestamp: Date;
+}
+/**
+ * One version's reconstructed state — what a browse / compare surface shows,
+ * and what a restore re-applies as a new version. Every leaf-chain domain
+ * column at `(id, version)`, keyed by column name (leaf-most level wins on a
+ * shared name), plus the root chain's `action` / `timestamp`. Generated
+ * columns (a search vector) are opaque and belong outside `columns`.
+ *
+ * `Extra` carries the branch-level facts a hierarchy adds to a snapshot (a
+ * content branch's visibility and draft flag, say); the library knows none of
+ * them.
+ */
+export type VersionSnapshot<Action extends string = VersionAction, Extra extends object = Record<never, never>> = VersionChainEntry<Action> & Extra & {
+  /** Every leaf-chain domain column at this version, keyed by column name. */
+  readonly columns: Readonly<Record<string, unknown>>;
+};
+/** The `createdAt` / `updatedAt` pair {@link versionTimestamps} returns. */
+export interface VersionTimestamps {
+  /** The birth row's timestamp, or `updatedAt` when the view merges none in. */
+  readonly createdAt: Date;
+  /** The current version's `timestamp`. */
+  readonly updatedAt: Date;
+}
+/**
+ * The `createdAt` / `updatedAt` pair of a current-version row: `updatedAt` is
+ * the current version's `timestamp`; `createdAt` is the birth row's own
+ * timestamp where the view merges one in (a function `merge` of
+ * {@link makeCurrentVersionView}), and falls back to `updatedAt` for a view
+ * that carries none (website #1223).
+ */
+export declare const versionTimestamps: (row: {
+  readonly timestamp: Date;
+  readonly createdAt?: Date | null | undefined;
+}) => VersionTimestamps;
+/** A builder map a table's `columns` takes. */
+type ColumnMap = Record<string, ColumnBuilderBase>;
+/** `T` as a {@link ColumnMap}, so a mapped column type satisfies the table constraint. */
+type AsColumns<T> = T extends ColumnMap ? T : never;
+/** The metadata map member `P` of level `K` in tree metadata `M`; `{}` when absent. */
+type MetaOf<M, K, P extends "level" | "leaf"> = K extends keyof M ? M[K] extends { readonly [Q in P]: infer X; } ? X : Record<never, never> : Record<never, never>;
+/** The hand-authored columns the hooks `H` give level `K`; `{}` when none. */
+type HookColumnsOf<H, K> = K extends keyof H ? H[K] extends {
+  readonly columns?: infer C;
+} ? Exclude<C, undefined> extends ColumnMap ? Exclude<C, undefined> : Record<never, never> : Record<never, never> : Record<never, never>;
+/** Whether an entry declares the `"fact-scoped"` level kind. */
+type IsFactScoped<E> = E extends {
+  readonly kind?: infer Kind;
+} ? [Exclude<Kind, undefined>] extends ["fact-scoped"] ? true : false : false;
+/** Level `K`'s own derived columns: its level columns, then its leaf's. */
+type OwnColumns<M, K, B extends ColumnBuilders> = DerivedColumns<MetaOf<M, K, "level">, B> & DerivedColumns<MetaOf<M, K, "leaf">, B>;
+/**
+ * The columns level `K`'s version table carries beyond `(id, version)`: its own
+ * derived columns (a fact-scoped level keeps them in fact tables instead), then
+ * the hand-authored hook columns.
+ */
+export type TreeVersionColumns<S, M, B extends ColumnBuilders, H, K extends keyof S> = AsColumns<(IsFactScoped<S[K]> extends true ? Record<never, never> : OwnColumns<M, K, B>) & HookColumnsOf<H, K>>;
+/** A fact table's column builders: the `(id, version)` key plus one fact. */
+type FactColumnBuilders<TColumns extends ColumnMap> = {
+  id: SetNotNull<PgUUIDBuilder>;
+  version: SetNotNull<PgBigInt64Builder>;
+} & TColumns;
+/**
+ * One fact table of a fact-scoped level: `(id, version)` keyed, carrying one
+ * column, foreign-keyed to the level's version spine. Written out for the
+ * declaration printer, as {@link SubtypeTables} is.
+ */
+export type FactTable<TColumns extends ColumnMap> = PgTableWithColumns<{
+  name: string;
+  schema: string;
+  columns: PgBuildColumns<string, FactColumnBuilders<TColumns>>;
+  dialect: "pg";
+  isAlias: false;
+}>;
+/** Every level's `{ stable, version }` pair, keyed by level name. */
+export type TreeLevelTables<S, M, B extends ColumnBuilders, H> = { readonly [K in keyof S & string]: SubtypeTables<TreeVersionColumns<S, M, B, H, K>>; };
+/** Every fact-scoped level's fact tables, keyed by level then field; `{}` for a plain level. */
+export type TreeFactTables<S, M, B extends ColumnBuilders> = { readonly [K in keyof S & string]: IsFactScoped<S[K]> extends true ? { readonly [F in keyof OwnColumns<M, K, B>]: FactTable<AsColumns<Pick<OwnColumns<M, K, B>, F>>>; } : Record<never, never>; };
+/** The root identity table's column builders: `id`, the leaf `type`, then the injected extras. */
+type RootIdentityColumnBuilders<IE extends ColumnMap> = {
+  id: SetIsPrimaryKey<PgUUIDBuilder>;
+  type: SetNotNull<PgTextBuilder<[string, ...string[]]>>;
+} & IE;
+/**
+ * The root version table's column builders: the `(id, version)` key, `action`
+ * (the chain's only currency and tombstone state), `timestamp`, the actor,
+ * then the injected extras.
+ */
+type RootVersionColumnBuilders<VE extends ColumnMap> = {
+  id: SetNotNull<PgUUIDBuilder>;
+  version: SetNotNull<PgBigInt64Builder>;
+  action: SetNotNull<PgTextBuilder<[string, ...string[]]>>;
+  timestamp: SetHasDefault<SetNotNull<PgTimestampBuilder>>;
+  actor: PgTextBuilder<[string, ...string[]]>;
+} & VE;
+/** The root `{ identity, version }` pair. Written out for the declaration printer. */
+export interface TreeRootTables<IE extends ColumnMap, VE extends ColumnMap> {
+  identity: PgTableWithColumns<{
+    name: string;
+    schema: string;
+    columns: PgBuildColumns<string, RootIdentityColumnBuilders<IE>>;
+    dialect: "pg";
+    isAlias: false;
+  }>;
+  version: PgTableWithColumns<{
+    name: string;
+    schema: string;
+    columns: PgBuildColumns<string, RootVersionColumnBuilders<VE>>;
+    dialect: "pg";
+    isAlias: false;
+  }>;
+}
+/** Everything {@link makeTreeTables} derives from a tree. */
+export interface TreeTables<S, M, B extends ColumnBuilders, H, IE extends ColumnMap, VE extends ColumnMap> {
+  /** The root identity and version tables. */
+  readonly root: TreeRootTables<IE, VE>;
+  /** Every level's stable + version pair, keyed by level name. */
+  readonly levels: TreeLevelTables<S, M, B, H>;
+  /** Every fact-scoped level's fact tables, keyed by level then field. */
+  readonly facts: TreeFactTables<S, M, B>;
+}
+/**
+ * Per-level hooks for what a model can't carry. Every member is threaded into
+ * a Drizzle builder call, so each is `?: T | undefined` (see
+ * {@link SubtypeTablesConfig}).
+ */
+export interface TreeLevelHooks {
+  /** Hand-authored version-table columns (an FK backing a relationship, a generated column). */
+  readonly columns?: ColumnMap | undefined;
+  /** Extra version-table constraints and indexes, after the generated key and FK. */
+  readonly extraConstraints?: ((table: Record<string, ExtraConfigColumn>) => PgTableExtraConfigValue[]) | undefined;
+  /**
+   * A refinable branch: the `(id, type)` arc of this level and of every level
+   * below it gets `ON UPDATE CASCADE`, so flipping the root's `type` from a
+   * bare value to a concrete leaf cascades down the existing chain (website's
+   * entity refinement).
+   */
+  readonly refinable?: boolean | undefined;
+}
+/** The root tables' names and injected columns. */
+export interface TreeRootConfig<IE extends ColumnMap, VE extends ColumnMap> {
+  /** The identity table's name; `node` when absent. */
+  readonly identity?: string | undefined;
+  /** The root version table's name; `${identity}_version` when absent. */
+  readonly version?: string | undefined;
+  /** Extra identity columns (website's `slug`). */
+  readonly identityColumns?: IE | undefined;
+  /** Extra root-version columns (pulpit's `proposed_by`). */
+  readonly versionColumns?: VE | undefined;
+  /** The actor column's name; `actor` when absent. */
+  readonly actorColumn?: string | undefined;
+}
+/** The configuration {@link makeTreeTables} takes. */
+export interface TreeTablesConfig<B extends ColumnBuilders, H, IE extends ColumnMap, VE extends ColumnMap> {
+  /** The schema every table is created in. */
+  readonly schema: PgSchema;
+  /** The builder registry the `dbColumn` kinds resolve against. */
+  readonly builders: B;
+  /** Resolves a `references` annotation to its target column (see `./derive`). */
+  readonly resolveReference?: DeriveOptions["resolveReference"];
+  /** The root tables' names and injected columns. */
+  readonly root?: TreeRootConfig<IE, VE> | undefined;
+  /** Per-level hooks, keyed by level name. */
+  readonly levels?: H | undefined;
+}
+/**
+ * Derive every table and constraint of a tree in one call: the root identity
+ * table (`id`, `type`, extras; `UNIQUE (id, type)`) and root version table
+ * (`(id, version)` key, `action` checked to `create` / `update` / `delete`,
+ * `timestamp`, the actor, extras); then per level a stable table (`id` →
+ * parent `id`, cascade delete; `type` NOT NULL with `UNIQUE (id, type)`,
+ * `(id, type)` → parent `(id, type)`, and a CHECK narrowing `type` to the
+ * level's subtree leaves) and a version table (`(id, version)` key and
+ * `(id, version)` → parent version FK) carrying the level's level columns,
+ * its leaf's columns (both derived through `builders`) and its hook columns.
+ * A fact-scoped level's version table is a spine, with one
+ * `${level}_${column}` fact table per own column, keyed and foreign-keyed on
+ * `(id, version)` (cascade delete).
+ *
+ * Constraint names are canonical (`${table}_pkey`, `${table}_${parent}_fk`,
+ * `${level}_id_type_unique` / `_fk` / `_type_valid`); no version table carries
+ * `action`. Column, constraint and CHECK value order follow declaration order,
+ * so the same tree always generates the same migration. Throws
+ * `DerivationError` at module load for a column kind `builders` lacks or an
+ * unresolvable reference.
+ *
+ * Every table is typed from the tree's column phantom. The one type-erasure
+ * seam is inside: the level and fact records are assembled from the runtime
+ * tree, then named by {@link TreeTables}.
+ *
+ * @example
+ * ```ts
+ * import { dbColumn, defineTree } from "@thomasfosterau/effect-drizzle-ext";
+ * import { makeTreeTables } from "@thomasfosterau/effect-drizzle-ext/versioned-chain";
+ * import { getTableConfig, integer, pgSchema, text } from "drizzle-orm/pg-core";
+ * import * as Schema from "effect/Schema";
+ *
+ * const tree = defineTree({
+ *   work: {
+ *     columns: { title: dbColumn(Schema.String, { column: "title", pg: "text", notNull: true }) },
+ *   },
+ *   book: {
+ *     parent: "work",
+ *     leaf: { pages: dbColumn(Schema.Finite, { column: "pages", pg: "integer", notNull: false }) },
+ *   },
+ * });
+ *
+ * const tables = makeTreeTables(tree, {
+ *   schema: pgSchema("catalogue"),
+ *   builders: { text: (c: string) => text(c), integer: (c: string) => integer(c) },
+ * });
+ *
+ * console.log(getTableConfig(tables.levels.book.version).columns.map((c) => c.name));
+ * // ["id", "version", "pages"]
+ * ```
+ */
+export declare const makeTreeTables: <S, M, B extends ColumnBuilders, const H extends { readonly [K in keyof S]?: TreeLevelHooks; } = Record<never, never>, IE extends ColumnMap = Record<never, never>, VE extends ColumnMap = Record<never, never>>(tree: Tree<S, M>, config: TreeTablesConfig<B, H, IE, VE>) => TreeTables<S, M, B, H, IE, VE>;
+export {};
+//# sourceMappingURL=versioned-chain.d.ts.map

package/dist/versioned-chain.d.ts.map

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