@thomasfosterau/effect-drizzle-ext 0.0.0 → 0.1.0

package/dist/columns.d.ts

@@ -0,0 +1,113 @@
+import * as Schema from "effect/Schema";
+import { ConvertCustomConfig, PgCustomColumnBuilder, PgTimestampBuilder, SetHasDefault, SetNotNull } from "drizzle-orm/pg-core";
+/**
+ * Builds a typed JSONB Drizzle custom type backed by an Effect Schema.
+ *
+ * Values are stored as PostgreSQL `jsonb`. The schema validates on both
+ * read (`fromDriver`) and write (`toDriver`): writing encodes through the
+ * schema and then through {@link JsonText}; reading decodes unknown driver
+ * output straight through the schema.
+ *
+ * The driver this library ships a Postgres binding for (node-pg, via
+ * `@effect/sql-pg`) already parses `jsonb` columns before `fromDriver` sees
+ * them, so the `typeof value === "string"` branch below is dead under that
+ * driver — it exists for a driver that hands back raw JSON text instead,
+ * and is exercised directly by this module's tests.
+ *
+ * Nullable columns are handled transparently — `null` values pass through
+ * Drizzle without reaching this codec, so `.nullable()` is not required on
+ * `schema`.
+ *
+ * `schema` is bound to `Schema.Codec<unknown, unknown, never, never>` rather
+ * than the wider `Schema.Top`: `toDriver` / `fromDriver` are synchronous
+ * Drizzle hooks with no Effect context to satisfy a requirement from, so a
+ * schema this codec accepts must already need no services to decode or
+ * encode.
+ */
+export declare const jsonbSchema: <S extends Schema.Codec<unknown, unknown, never, never>>(schema: S) => (name: string) => PgCustomColumnBuilder<ConvertCustomConfig<{
+  data: S["Type"];
+  driverData: unknown;
+}>>;
+/**
+ * Custom column type for PostgreSQL `tsvector`.
+ *
+ * Used for generated full-text search columns. The value is opaque to the
+ * consuming application — queries use `sql` template literals for matching.
+ */
+export declare const tsvector: (name: string) => PgCustomColumnBuilder<ConvertCustomConfig<{
+  data: string;
+  driverData: string;
+}>>;
+/**
+ * Custom column type for PostgreSQL `bytea` (binary data).
+ *
+ * Typed `Uint8Array` rather than `Buffer` — see {@link byteaToHex} for why
+ * the Node global is off-limits here. Both directions are honest about the
+ * runtime: `@effect/sql-pg`'s binary `bytea` codec decodes to a `Uint8Array`
+ * and encodes any `Uint8Array` (a Node `Buffer` included, as a subclass) as
+ * raw bytes, so a plain `Uint8Array` binds identically to a `Buffer`.
+ */
+export declare const bytea: (name: string) => PgCustomColumnBuilder<ConvertCustomConfig<{
+  data: Uint8Array;
+  driverData: Uint8Array;
+}>>;
+/**
+ * The `created_at` / `updated_at` builder pair {@link timestamps} returns:
+ * `timestamptz`, `NOT NULL`, defaulting to `now()`.
+ */
+export interface TimestampColumns {
+  /** `created_at timestamptz NOT NULL DEFAULT now()`. */
+  readonly createdAt: SetHasDefault<SetNotNull<PgTimestampBuilder>>;
+  /** `updated_at timestamptz NOT NULL DEFAULT now()`. */
+  readonly updatedAt: SetHasDefault<SetNotNull<PgTimestampBuilder>>;
+}
+/**
+ * A fresh `created_at` / `updated_at` pair: `timestamptz`, `NOT NULL`,
+ * defaulting to `now()`.
+ *
+ * A factory, never a shared object: Drizzle column builders are
+ * **mutable** — `.notNull()` and `.defaultNow()` mutate and return the same
+ * builder instance. A module-level constant reused across tables would
+ * therefore hand every table the same two builders, and whichever table
+ * was declared last would win any later refinement. Calling `timestamps()`
+ * per table mints a fresh pair.
+ *
+ * `updated_at` defaults rather than auto-updates — nothing in Postgres
+ * bumps it, the write path does.
+ *
+ * Spread rather than a base table: Drizzle records a table's columns in
+ * declaration order, and that order is what a consumer's `db:generate`
+ * emits as the `CREATE TABLE` column order. Spreading at the position two
+ * hand-written lines occupied keeps generated SQL byte-identical, so
+ * adopting this helper does not move a baseline migration.
+ */
+export declare const timestamps: () => TimestampColumns;
+/**
+ * Renders a `bytea` value (typically a content hash) as its lowercase hex
+ * string.
+ *
+ * Written against `Uint8Array` rather than `Buffer.prototype.toString("hex")`
+ * on purpose: a runtime that declares the Node `Buffer` global alongside
+ * `@types/node` (Cloudflare Workers' `nodejs_compat` types are one example)
+ * can strip the Node-only methods off the global `Buffer` interface, or
+ * degrade the `Buffer` *value* to `any`, so every `Buffer.*` call goes
+ * unchecked with no signal at all. `Uint8Array` is what a `bytea` row value
+ * structurally is on every runtime, so this encodes identically everywhere
+ * without depending on that global.
+ */
+export declare const byteaToHex: (bytes: Uint8Array) => string;
+/**
+ * Decodes a hex string into the `Uint8Array` a `bytea` column binds — the
+ * inverse of {@link byteaToHex}, replacing `Buffer.from(hex, "hex")`.
+ *
+ * Strict where `Buffer.from` is silent: `Buffer.from` decodes the leading
+ * valid pairs and drops the rest, so a malformed hash quietly becomes a
+ * short-but-plausible key that matches no row. This throws instead — a
+ * caller that takes a hash from outside the trust boundary is expected to
+ * validate its shape before calling this, and gets a loud failure instead
+ * of a silently truncated key when it doesn't.
+ *
+ * @throws TypeError if `hex` is not an even-length run of hex digits.
+ */
+export declare const hexToBytea: (hex: string) => Uint8Array;
+//# sourceMappingURL=columns.d.ts.map

package/dist/columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"columns.d.ts","names":[],"sources":["../src/columns.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;qBAwDa,cACV,UAAU,OAAO,uCAAqC,QAAU,OAAC,iBAG/D,sBAAsB;EAAsB,MAAM;EAAW;;;;;;;;qBA0BrD,WAAQ,iBAElB,sBAAsB;EAAsB;EAAc;;;;;;;;;;;qBAgBhD,QAAK,iBAEf,sBAAsB;EAAsB,MAAM;EAAY,YAAY;;;;;;iBAW5D;;WAEN,WAAW,cAAc,WAAW;;WAEpC,WAAW,cAAc,WAAW;;;;;;;;;;;;;;;;;;;;;;qBAuBlC,kBAAiB;;;;;;;;;;;;;;qBAkBjB,aAAU,OAAW;;;;;;;;;;;;;;qBAgBrB,aAAU,gBAAkB"}

package/dist/columns.js

@@ -0,0 +1,146 @@
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+import { customType, timestamp } from "drizzle-orm/pg-core";
+// src/columns.ts
+/**
+* @copyright Thomas Foster
+*
+* Column helpers for Drizzle table definitions this library owns outright:
+* a generic JSONB codec bridging any Effect Schema to `jsonb`, `tsvector`
+* and `bytea` custom types, the `created_at` / `updated_at` timestamp pair
+* every plain table carries, and the hex codec for rendering / parsing
+* `bytea` values without the Node `Buffer` global.
+*
+* @module columns
+*/
+/**
+* The JSON text boundary, expressed as a schema rather than the `JSON`
+* global: encoding runs `JSON.stringify` and decoding runs a total
+* `JSON.parse` whose `None` covers a malformed string.
+*/
+const JsonText = Schema.fromJsonString(Schema.Unknown);
+const encodeJsonText = Schema.encodeSync(JsonText);
+const decodeJsonText = Schema.decodeUnknownOption(JsonText);
+/**
+* Builds a typed JSONB Drizzle custom type backed by an Effect Schema.
+*
+* Values are stored as PostgreSQL `jsonb`. The schema validates on both
+* read (`fromDriver`) and write (`toDriver`): writing encodes through the
+* schema and then through {@link JsonText}; reading decodes unknown driver
+* output straight through the schema.
+*
+* The driver this library ships a Postgres binding for (node-pg, via
+* `@effect/sql-pg`) already parses `jsonb` columns before `fromDriver` sees
+* them, so the `typeof value === "string"` branch below is dead under that
+* driver — it exists for a driver that hands back raw JSON text instead,
+* and is exercised directly by this module's tests.
+*
+* Nullable columns are handled transparently — `null` values pass through
+* Drizzle without reaching this codec, so `.nullable()` is not required on
+* `schema`.
+*
+* `schema` is bound to `Schema.Codec<unknown, unknown, never, never>` rather
+* than the wider `Schema.Top`: `toDriver` / `fromDriver` are synchronous
+* Drizzle hooks with no Effect context to satisfy a requirement from, so a
+* schema this codec accepts must already need no services to decode or
+* encode.
+*/
+const jsonbSchema = (schema) => (name) => {
+	const encode = Schema.encodeSync(schema);
+	const decode = Schema.decodeUnknownSync(schema);
+	return customType({
+		dataType() {
+			return "jsonb";
+		},
+		toDriver(value) {
+			return encodeJsonText(encode(value));
+		},
+		fromDriver(value) {
+			if (!Predicate.isString(value)) return decode(value);
+			return Option.match(decodeJsonText(value), {
+				onNone: () => decode(value),
+				onSome: (parsed) => decode(parsed)
+			});
+		}
+	})(name);
+};
+/**
+* Custom column type for PostgreSQL `tsvector`.
+*
+* Used for generated full-text search columns. The value is opaque to the
+* consuming application — queries use `sql` template literals for matching.
+*/
+const tsvector = (name) => customType({ dataType() {
+	return "tsvector";
+} })(name);
+/**
+* Custom column type for PostgreSQL `bytea` (binary data).
+*
+* Typed `Uint8Array` rather than `Buffer` — see {@link byteaToHex} for why
+* the Node global is off-limits here. Both directions are honest about the
+* runtime: `@effect/sql-pg`'s binary `bytea` codec decodes to a `Uint8Array`
+* and encodes any `Uint8Array` (a Node `Buffer` included, as a subclass) as
+* raw bytes, so a plain `Uint8Array` binds identically to a `Buffer`.
+*/
+const bytea = (name) => customType({ dataType() {
+	return "bytea";
+} })(name);
+/**
+* A fresh `created_at` / `updated_at` pair: `timestamptz`, `NOT NULL`,
+* defaulting to `now()`.
+*
+* A factory, never a shared object: Drizzle column builders are
+* **mutable** — `.notNull()` and `.defaultNow()` mutate and return the same
+* builder instance. A module-level constant reused across tables would
+* therefore hand every table the same two builders, and whichever table
+* was declared last would win any later refinement. Calling `timestamps()`
+* per table mints a fresh pair.
+*
+* `updated_at` defaults rather than auto-updates — nothing in Postgres
+* bumps it, the write path does.
+*
+* Spread rather than a base table: Drizzle records a table's columns in
+* declaration order, and that order is what a consumer's `db:generate`
+* emits as the `CREATE TABLE` column order. Spreading at the position two
+* hand-written lines occupied keeps generated SQL byte-identical, so
+* adopting this helper does not move a baseline migration.
+*/
+const timestamps = () => ({
+	createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+	updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow()
+});
+/**
+* Renders a `bytea` value (typically a content hash) as its lowercase hex
+* string.
+*
+* Written against `Uint8Array` rather than `Buffer.prototype.toString("hex")`
+* on purpose: a runtime that declares the Node `Buffer` global alongside
+* `@types/node` (Cloudflare Workers' `nodejs_compat` types are one example)
+* can strip the Node-only methods off the global `Buffer` interface, or
+* degrade the `Buffer` *value* to `any`, so every `Buffer.*` call goes
+* unchecked with no signal at all. `Uint8Array` is what a `bytea` row value
+* structurally is on every runtime, so this encodes identically everywhere
+* without depending on that global.
+*/
+const byteaToHex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+/**
+* Decodes a hex string into the `Uint8Array` a `bytea` column binds — the
+* inverse of {@link byteaToHex}, replacing `Buffer.from(hex, "hex")`.
+*
+* Strict where `Buffer.from` is silent: `Buffer.from` decodes the leading
+* valid pairs and drops the rest, so a malformed hash quietly becomes a
+* short-but-plausible key that matches no row. This throws instead — a
+* caller that takes a hash from outside the trust boundary is expected to
+* validate its shape before calling this, and gets a loud failure instead
+* of a silently truncated key when it doesn't.
+*
+* @throws TypeError if `hex` is not an even-length run of hex digits.
+*/
+const hexToBytea = (hex) => {
+	if (hex.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(hex)) throw new TypeError(`Expected an even-length hex string, received ${encodeJsonText(hex)}`);
+	return Uint8Array.from({ length: hex.length / 2 }, (_unused, index) => Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16));
+};
+export { bytea, byteaToHex, hexToBytea, jsonbSchema, timestamps, tsvector };
+
+//# sourceMappingURL=columns.js.map

package/dist/columns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"columns.js","names":[],"sources":["../src/columns.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA4BA,MAAM,WAAW,OAAO,eAAe,OAAO,OAAO;AACrD,MAAM,iBAAiB,OAAO,WAAW,QAAQ;AACjD,MAAM,iBAAiB,OAAO,oBAAoB,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;AA0B1D,MAAa,eAC8C,YAEvD,SACyF;CACzF,MAAM,SAAS,OAAO,WAAW,MAAM;CACvC,MAAM,SAAS,OAAO,kBAAkB,MAAM;CAC9C,OAAO,WAAqD;EAC1D,WAAW;GACT,OAAO;EACT;EACA,SAAS,OAAO;GACd,OAAO,eAAe,OAAO,KAAK,CAAC;EACrC;EACA,WAAW,OAAO;GAChB,IAAI,CAAC,UAAU,SAAS,KAAK,GAAG,OAAO,OAAO,KAAK;GACnD,OAAO,OAAO,MAAM,eAAe,KAAK,GAAG;IACzC,cAAc,OAAO,KAAK;IAC1B,SAAS,WAAW,OAAO,MAAM;GACnC,CAAC;EACH;CACF,CAAC,CAAC,CAAC,IAAI;AACT;;;;;;;AAQF,MAAa,YACX,SAEA,WAAiD,EAC/C,WAAW;CACT,OAAO;AACT,EACF,CAAC,CAAC,CAAC,IAAI;;;;;;;;;;AAWT,MAAa,SACX,SAEA,WAAyD,EACvD,WAAW;CACT,OAAO;AACT,EACF,CAAC,CAAC,CAAC,IAAI;;;;;;;;;;;;;;;;;;;;;AAiCT,MAAa,oBAAsC;CACjD,WAAW,UAAU,cAAc,EAAE,cAAc,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,WAAW;CAChF,WAAW,UAAU,cAAc,EAAE,cAAc,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,WAAW;AAClF;;;;;;;;;;;;;;AAeA,MAAa,cAAc,UACzB,MAAM,KAAK,QAAQ,SAAS,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE;;;;;;;;;;;;;;AAezE,MAAa,cAAc,QAA4B;CACrD,IAAI,IAAI,SAAS,MAAM,KAAK,CAAC,iBAAiB,KAAK,GAAG,GACpD,MAAM,IAAI,UAAU,gDAAgD,eAAe,GAAG,GAAG;CAE3F,OAAO,WAAW,KAAK,EAAE,QAAQ,IAAI,SAAS,EAAE,IAAI,SAAS,UAC3D,OAAO,SAAS,IAAI,MAAM,QAAQ,GAAG,QAAQ,IAAI,CAAC,GAAG,EAAE,CACzD;AACF"}

package/dist/constraints.d.ts

@@ -0,0 +1,117 @@
+import { AnyPgColumn, ExtraConfigColumn, PgTableExtraConfigValue } from "drizzle-orm/pg-core";
+/**
+ * `CHECK (column IN ('a', 'b', …))`, named `name`.
+ *
+ * The models declare each vocabulary once as an exported `as const` array and
+ * validate the wire against `Schema.Literals` over it; the database restates
+ * the same array as an `IN (...)` CHECK so a row written by any path — a
+ * batched ingestion upsert included — cannot carry a value the API would refuse
+ * to serve. There is no Postgres enum type: a `text` column plus a CHECK is
+ * what lets a vocabulary grow with one migration (`ALTER … DROP/ADD
+ * CONSTRAINT`) instead of an `ALTER TYPE … ADD VALUE` that cannot run inside a
+ * transaction.
+ *
+ * A `NULL` in the column **passes** — `NULL IN (...)` is unknown, which CHECK
+ * accepts — so the same constraint serves nullable vocabularies without an
+ * `IS NULL OR` guard. Nullability is the column's own `NOT NULL` to declare.
+ *
+ * The values are rendered as literal SQL text, not bind parameters: a CHECK
+ * expression lives in the migration file, where a `$1` placeholder has nothing
+ * to bind to. They come straight from the models' `as const` arrays, so the two
+ * vocabularies cannot drift — a model change shows up as schema drift in the
+ * consumer's migration-drift check until the migration is regenerated.
+ */
+export declare const enumCheck: (name: string, column: ExtraConfigColumn, values: readonly string[]) => PgTableExtraConfigValue;
+/** A stable table contributes its `id` + `type` columns to the discriminator. */
+export interface TypedStable {
+  readonly id: AnyPgColumn;
+  readonly type: AnyPgColumn;
+}
+/**
+ * Constraint-name templates, overriding the defaults
+ * `${level}_id_type_unique`, `${level}_id_type_fk` and `${level}_type_valid`.
+ * A consumer adopting this helper over hand-written constraints pins whatever
+ * names its existing migrations already carry, so the switch renames nothing.
+ */
+export interface DiscriminatorNames {
+  /** Name of the `UNIQUE(id, type)` constraint. */
+  readonly unique?: ((level: string) => string) | undefined;
+  /** Name of the composite `(id, type)` → parent `(id, type)` foreign key. */
+  readonly parentFk?: ((level: string) => string) | undefined;
+  /** Name of the per-level `type` CHECK. */
+  readonly check?: ((level: string) => string) | undefined;
+}
+/**
+ * The three constraints that enforce a threaded `type` discriminator, bound to
+ * one hierarchy. Generic over the hierarchy's level union `Level`, so a level
+ * the consumer has no leaf set for is a type error at the call site.
+ */
+export interface DiscriminatorToolkit<Level extends string> {
+  /**
+   * `UNIQUE(id, type)` — the target every child's composite `(id, type)` FK
+   * needs. `level` is a plain `string`, not `Level`: a root table sitting
+   * *above* the ontology's levels (and so not itself a level) can carry it too.
+   */
+  readonly typeUnique: (level: string, stable: TypedStable) => PgTableExtraConfigValue;
+  /**
+   * The composite `(id, type)` → parent `(id, type)` foreign key. `onDelete` is
+   * left to the plain single-column `id` FK the table already carries
+   * (cascade); this arc only enforces the discriminator match.
+   *
+   * `onUpdate: "cascade"` (via {@link DiscriminatorToolkit.typeConstraints}'
+   * `refinable` option) makes a bare parent row **refinable**: an operation
+   * that flips the root's `type` from a generic value to a concrete leaf
+   * cascades the new `type` down the pre-existing `(id, type)` chain before the
+   * concrete rows are inserted — so the flip is a plain ordered transaction, no
+   * `DEFERRABLE` constraint needed. Branches that don't refine keep the default
+   * (no referential action on this arc).
+   */
+  readonly typeParentFk: (level: Level, stable: TypedStable, parent: TypedStable, onUpdate?: "cascade") => PgTableExtraConfigValue;
+  /**
+   * The per-level `type` CHECK. A leaf admits only its own type; an
+   * intermediate or branch root admits every concrete leaf in its subtree (the
+   * `leaves` callback the toolkit was built with). The value list is
+   * parameterised, not interpolated.
+   *
+   * A childless marker — an ontology level with no concrete leaf beneath it yet
+   * — has an empty leaf set, so it admits no `type` at all: no leaf names it as
+   * an ancestor, so nothing ever materialises a row there and the table stays
+   * empty until the ontology grows a leaf under it. Emits `CHECK (false)` for
+   * that case — `type IN ()` is a syntax error, and `false` correctly marks the
+   * level uninstantiable rather than admitting an arbitrary value.
+   */
+  readonly typeCheck: (level: Level, stable: TypedStable) => PgTableExtraConfigValue;
+  /**
+   * All three discriminator constraints for a non-root level:
+   * `UNIQUE(id, type)`, the composite `(id, type)` → parent FK, and the
+   * per-level CHECK. A branch root passes the table above it as `parent`; the
+   * root table itself gets only {@link DiscriminatorToolkit.typeUnique} (no
+   * parent, no CHECK — it admits any leaf).
+   *
+   * `refinable: true` gives the composite FK `ON UPDATE CASCADE` — see
+   * {@link DiscriminatorToolkit.typeParentFk}.
+   */
+  readonly typeConstraints: (level: Level, stable: TypedStable, parent: TypedStable, options?: {
+    readonly refinable?: boolean | undefined;
+  }) => PgTableExtraConfigValue[];
+}
+/**
+ * Build a {@link DiscriminatorToolkit} for one hierarchy.
+ *
+ * `leaves(level)` is the seam the ontology plugs into: it answers the concrete
+ * leaf `type` values admissible at `level` (its subtree's leaves — for a leaf
+ * level, itself). The library carries no level ontology of its own, so this
+ * callback, and the optional {@link DiscriminatorNames} templates, are the
+ * whole configuration.
+ *
+ * The constraints it emits are what make a sibling-subtype chimera
+ * unrepresentable: `UNIQUE(id, type)` gives children a composite key to point
+ * at, the composite FK arcs the discriminator up one level (a child can only
+ * exist under a parent carrying the SAME `type`), and the CHECK narrows `type`
+ * to the level's own subtree.
+ */
+export declare const makeDiscriminatorConstraints: <Level extends string>(options: {
+  readonly leaves: (level: Level) => ReadonlyArray<string>;
+  readonly names?: DiscriminatorNames | undefined;
+}) => DiscriminatorToolkit<Level>;
+//# sourceMappingURL=constraints.d.ts.map

package/dist/constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraints.d.ts","names":[],"sources":["../src/constraints.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;qBAsDa,YAAS,cACR,QACJ,mBAAiB,8BAExB;;iBAMc;WACN,IAAI;WACJ,MAAM;;;;;;;;iBAmBA;;WAEN,WAAW;;WAEX,aAAa;;WAEb,UAAU;;;;;;;iBAQJ,qBAAqB;;;;;;WAM3B,aAAa,eAAe,QAAQ,gBAAgB;;;;;;;;;;;;;;WAcpD,eACP,OAAO,OACP,QAAQ,aACR,QAAQ,aACR,yBACG;;;;;;;;;;;;;;WAcI,YAAY,OAAO,OAAO,QAAQ,gBAAgB;;;;;;;;;;;WAWlD,kBACP,OAAO,OACP,QAAQ,aACR,QAAQ,aACR;aAAqB;QAClB;;;;;;;;;;;;;;;;;qBAkBM,+BAAgC,sBAAoB;WACtD,SAAS,OAAO,UAAU;WAC1B,QAAQ;MACf,qBAAqB"}

package/dist/constraints.js

@@ -0,0 +1,93 @@
+import * as Array from "effect/Array";
+import { sql } from "drizzle-orm";
+import { check, foreignKey, unique } from "drizzle-orm/pg-core";
+// src/constraints.ts
+/**
+* @copyright Thomas Foster
+*
+* **Table-level CHECK / UNIQUE / composite-FK helpers.**
+*
+* Two independent families, both emitting values for a table factory's
+* `extraConstraints` seam:
+*
+* - {@link enumCheck} — the `CHECK (col IN (…))` behind an enum-valued `text`
+*   column, so a vocabulary declared once in a model constrains the database
+*   too.
+* - {@link makeDiscriminatorConstraints} — the three constraints that thread a
+*   `type` discriminator up a hierarchy of stable tables, parameterised over
+*   the hierarchy (the library knows no level ontology; the consumer supplies
+*   the leaf set per level).
+*
+* @module constraints
+*/
+/**
+* `CHECK (column IN ('a', 'b', …))`, named `name`.
+*
+* The models declare each vocabulary once as an exported `as const` array and
+* validate the wire against `Schema.Literals` over it; the database restates
+* the same array as an `IN (...)` CHECK so a row written by any path — a
+* batched ingestion upsert included — cannot carry a value the API would refuse
+* to serve. There is no Postgres enum type: a `text` column plus a CHECK is
+* what lets a vocabulary grow with one migration (`ALTER … DROP/ADD
+* CONSTRAINT`) instead of an `ALTER TYPE … ADD VALUE` that cannot run inside a
+* transaction.
+*
+* A `NULL` in the column **passes** — `NULL IN (...)` is unknown, which CHECK
+* accepts — so the same constraint serves nullable vocabularies without an
+* `IS NULL OR` guard. Nullability is the column's own `NOT NULL` to declare.
+*
+* The values are rendered as literal SQL text, not bind parameters: a CHECK
+* expression lives in the migration file, where a `$1` placeholder has nothing
+* to bind to. They come straight from the models' `as const` arrays, so the two
+* vocabularies cannot drift — a model change shows up as schema drift in the
+* consumer's migration-drift check until the migration is regenerated.
+*/
+const enumCheck = (name, column, values) => check(name, sql`${column} IN (${sql.raw(values.map((value) => `'${value}'`).join(", "))})`);
+/**
+* Build a {@link DiscriminatorToolkit} for one hierarchy.
+*
+* `leaves(level)` is the seam the ontology plugs into: it answers the concrete
+* leaf `type` values admissible at `level` (its subtree's leaves — for a leaf
+* level, itself). The library carries no level ontology of its own, so this
+* callback, and the optional {@link DiscriminatorNames} templates, are the
+* whole configuration.
+*
+* The constraints it emits are what make a sibling-subtype chimera
+* unrepresentable: `UNIQUE(id, type)` gives children a composite key to point
+* at, the composite FK arcs the discriminator up one level (a child can only
+* exist under a parent carrying the SAME `type`), and the CHECK narrows `type`
+* to the level's own subtree.
+*/
+const makeDiscriminatorConstraints = (options) => {
+	const uniqueName = options.names?.unique ?? ((level) => `${level}_id_type_unique`);
+	const parentFkName = options.names?.parentFk ?? ((level) => `${level}_id_type_fk`);
+	const checkName = options.names?.check ?? ((level) => `${level}_type_valid`);
+	const typeUnique = (level, stable) => unique(uniqueName(level)).on(stable.id, stable.type);
+	const typeParentFk = (level, stable, parent, onUpdate) => {
+		const fk = foreignKey({
+			name: parentFkName(level),
+			columns: [stable.id, stable.type],
+			foreignColumns: [parent.id, parent.type]
+		});
+		return onUpdate === "cascade" ? fk.onUpdate("cascade") : fk;
+	};
+	const typeCheck = (level, stable) => {
+		const leaves = options.leaves(level);
+		if (Array.isReadonlyArrayEmpty(leaves)) return check(checkName(level), sql`false`);
+		const list = sql.join(leaves.map((leaf) => sql`${leaf}`), sql`, `);
+		return check(checkName(level), sql`${stable.type} IN (${list})`);
+	};
+	return {
+		typeUnique,
+		typeParentFk,
+		typeCheck,
+		typeConstraints: (level, stable, parent, { refinable = false } = {}) => [
+			typeUnique(level, stable),
+			typeParentFk(level, stable, parent, refinable ? "cascade" : void 0),
+			typeCheck(level, stable)
+		]
+	};
+};
+export { enumCheck, makeDiscriminatorConstraints };
+
+//# sourceMappingURL=constraints.js.map

package/dist/constraints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraints.js","names":[],"sources":["../src/constraints.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDA,MAAa,aACX,MACA,QACA,WAEA,MAAM,MAAM,GAAG,GAAG,OAAO,OAAO,IAAI,IAAI,OAAO,KAAK,UAAU,IAAI,MAAM,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,EAAE,EAAE;;;;;;;;;;;;;;;;AAiH5F,MAAa,gCAAsD,YAGhC;CACjC,MAAM,aAAa,QAAQ,OAAO,YAAY,UAAkB,GAAG,MAAM;CACzE,MAAM,eAAe,QAAQ,OAAO,cAAc,UAAkB,GAAG,MAAM;CAC7E,MAAM,YAAY,QAAQ,OAAO,WAAW,UAAkB,GAAG,MAAM;CAEvE,MAAM,cAAc,OAAe,WACjC,OAAO,WAAW,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,OAAO,IAAI;CAErD,MAAM,gBACJ,OACA,QACA,QACA,aAC4B;EAC5B,MAAM,KAAK,WAAW;GACpB,MAAM,aAAa,KAAK;GACxB,SAAS,CAAC,OAAO,IAAI,OAAO,IAAI;GAChC,gBAAgB,CAAC,OAAO,IAAI,OAAO,IAAI;EACzC,CAAC;EACD,OAAO,aAAa,YAAY,GAAG,SAAS,SAAS,IAAI;CAC3D;CAEA,MAAM,aAAa,OAAc,WAAiD;EAChF,MAAM,SAAS,QAAQ,OAAO,KAAK;EACnC,IAAI,MAAM,qBAAqB,MAAM,GAAG,OAAO,MAAM,UAAU,KAAK,GAAG,GAAG,OAAO;EACjF,MAAM,OAAO,IAAI,KACf,OAAO,KAAK,SAAS,GAAG,GAAG,MAAM,GACjC,GAAG,IACL;EACA,OAAO,MAAM,UAAU,KAAK,GAAG,GAAG,GAAG,OAAO,KAAK,OAAO,KAAK,EAAE;CACjE;CAEA,OAAO;EACL;EACA;EACA;EACA,kBACE,OACA,QACA,QACA,EAAE,YAAY,UAAwD,CAAC,MACzC;GAC9B,WAAW,OAAO,MAAM;GACxB,aAAa,OAAO,QAAQ,QAAQ,YAAY,YAAY,KAAA,CAAS;GACrE,UAAU,OAAO,MAAM;EACzB;CACF;AACF"}