@thomasfosterau/effect-drizzle-ext 0.0.0-stage → 0.1.0

package/src/constraints.ts

@@ -0,0 +1,225 @@
+/**
+ * @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
+ */
+
+import { sql } from "drizzle-orm";
+import {
+  check,
+  foreignKey,
+  unique,
+  type AnyPgColumn,
+  type ExtraConfigColumn,
+  type PgTableExtraConfigValue,
+} from "drizzle-orm/pg-core";
+import * as Array from "effect/Array";
+
+// ── Enum-valued text columns ──────────────────────────────────────────
+
+/**
+ * `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 const enumCheck = (
+  name: string,
+  column: ExtraConfigColumn,
+  values: readonly string[],
+): PgTableExtraConfigValue =>
+  check(name, sql`${column} IN (${sql.raw(values.map((value) => `'${value}'`).join(", "))})`);
+
+// ── Threaded `type` discriminator ─────────────────────────────────────
+
+/** A stable table contributes its `id` + `type` columns to the discriminator. */
+export interface TypedStable {
+  readonly id: AnyPgColumn;
+  readonly type: AnyPgColumn;
+}
+
+/*
+ * Every optional member from here to the end of the file — the name templates,
+ * `onUpdate`, the `refinable` option — is `?: T | undefined`, never `Option`,
+ * for the reason stated once in ./derive.ts: they are config a consumer hands
+ * to a Drizzle-emitting factory, and `undefined` is what "not supplied" means
+ * there. `foreignKey(...).onUpdate(Option.none())` would emit `ON UPDATE
+ * [object Object]`.
+ */
+/* oxlint-disable effect/prefer-option-over-null -- config type: `undefined` means "not supplied" (see ./derive.ts) */
+
+/**
+ * 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 const makeDiscriminatorConstraints = <Level extends string>(options: {
+  readonly leaves: (level: Level) => ReadonlyArray<string>;
+  readonly names?: DiscriminatorNames | undefined;
+}): DiscriminatorToolkit<Level> => {
+  const uniqueName = options.names?.unique ?? ((level: string) => `${level}_id_type_unique`);
+  const parentFkName = options.names?.parentFk ?? ((level: string) => `${level}_id_type_fk`);
+  const checkName = options.names?.check ?? ((level: string) => `${level}_type_valid`);
+
+  const typeUnique = (level: string, stable: TypedStable): PgTableExtraConfigValue =>
+    unique(uniqueName(level)).on(stable.id, stable.type);
+
+  const typeParentFk = (
+    level: Level,
+    stable: TypedStable,
+    parent: TypedStable,
+    onUpdate?: "cascade",
+  ): PgTableExtraConfigValue => {
+    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: Level, stable: TypedStable): PgTableExtraConfigValue => {
+    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: Level,
+      stable: TypedStable,
+      parent: TypedStable,
+      { refinable = false }: { readonly refinable?: boolean | undefined } = {},
+    ): PgTableExtraConfigValue[] => [
+      typeUnique(level, stable),
+      typeParentFk(level, stable, parent, refinable ? "cascade" : undefined),
+      typeCheck(level, stable),
+    ],
+  };
+};
+
+/* oxlint-enable effect/prefer-option-over-null */

package/src/database.ts

@@ -0,0 +1,273 @@
+/**
+ * @copyright Thomas Foster
+ *
+ * The Effect-native Drizzle transaction boundary, as a per-application
+ * service factory: the `Database` and `CurrentTransaction` service keys, the
+ * `transact` helper that opens a transaction and discharges its handle into
+ * the context, and the `readHandle` resolver that prefers an ambient
+ * transaction over the client.
+ *
+ * The transaction value is whatever `db.transaction((tx) => Effect.gen(…))`
+ * passes its callback against the Effect-native Drizzle database. Its query
+ * methods (`select`, `insert`, `update`, `delete`, `transaction`) return
+ * Effects instead of Promises, so callers `yield*` them directly inside the
+ * transactional `Effect.gen`.
+ *
+ * Nothing here names a driver. The module is generic over the database and
+ * transaction types, so `drizzle-orm/effect-postgres` (and any other
+ * Effect-native Drizzle driver) binds them from outside;
+ * `@thomasfosterau/effect-drizzle-ext-pg` is the binding this repository
+ * ships. The only Drizzle type that reaches this file is
+ * {@link PgTransactionConfig}, a plain options record.
+ *
+ * Operations that predate the services took the transaction as an explicit
+ * `tx` parameter rather than a `Client | Transaction` union. The pair
+ * {@link DatabaseServices.CurrentTransaction} + {@link
+ * DatabaseServices.transact} replaces that threading (website #1883); the
+ * handle type stays visible because it is still the service's payload and the
+ * driver's callback parameter type.
+ *
+ * @module database
+ */
+
+import type { PgTransactionConfig } from "drizzle-orm/pg-core";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import type { SqlError } from "effect/sql/SqlError";
+
+/**
+ * The five read-side members {@link ReadHandle} narrows a handle to, as a
+ * constraint.
+ *
+ * `Pick<T, K>` requires `K extends keyof T`, which an unconstrained type
+ * parameter cannot satisfy; this interface is what lets {@link ReadHandle}
+ * name the five keys structurally instead. Members are typed `unknown` on
+ * purpose — the constraint asserts only that a handle HAS a read surface,
+ * never what it looks like, so the driver keeps full control of the
+ * signatures a consumer sees.
+ */
+export interface ReadSurface {
+  readonly select: unknown;
+  readonly selectDistinct: unknown;
+  readonly selectDistinctOn: unknown;
+  readonly with: unknown;
+  readonly $count: unknown;
+}
+
+/**
+ * The read surface shared by an Effect-native Drizzle database and its
+ * transaction: every way of starting a SELECT, and nothing that writes.
+ *
+ * A read may run either side of a transaction boundary, so the value
+ * {@link DatabaseServices.readHandle} yields has to be the part both handles
+ * agree on. Narrowing to it is a `Pick`, never a cast: both handles satisfy
+ * it structurally, and the driver's own signatures survive the narrowing.
+ */
+export type ReadHandle<Db extends ReadSurface> = Pick<
+  Db,
+  "select" | "selectDistinct" | "selectDistinctOn" | "with" | "$count"
+>;
+
+/**
+ * The one method {@link DatabaseServices.transact} needs from a handle: open
+ * a transaction, run an Effect against it, commit on success and roll back on
+ * failure.
+ *
+ * Both the database and the transaction satisfy this — a transaction's own
+ * `transaction` opens a SAVEPOINT — which is what makes nesting expressible
+ * without a second type.
+ *
+ * `config` is optional here and absent from a transaction handle's own
+ * signature; a method that ignores it stays assignable, so one interface
+ * covers both.
+ */
+export interface TransactionalDatabase<Tx> {
+  readonly transaction: <A, E, R>(
+    f: (tx: Tx) => Effect.Effect<A, E, R>,
+    config?: PgTransactionConfig,
+  ) => Effect.Effect<A, E | SqlError, R>;
+}
+
+/**
+ * The services one application's database handles are reached through: the
+ * two service keys, the write boundary, and the read-side resolver.
+ *
+ * The identifier of each key is the **key string itself**, deliberately: an
+ * application writes `type Database = typeof services.Database.Identifier`
+ * and gets a requirement it can name in its own signatures, the way a
+ * class-style `Context.Service` gives the class. Two factories called with
+ * different keys therefore produce services that are distinct to the type
+ * checker as well as at runtime.
+ */
+export interface DatabaseServices<Db, Tx extends ReadSurface, Key extends string> {
+  /**
+   * The canonical database service: the Effect-native Drizzle client, keyed
+   * by the string the factory was given. Queries yielded from it are Effects
+   * executed against whatever pool the layer providing it holds open.
+   */
+  readonly Database: Context.Service<Key, Db>;
+
+  /**
+   * The ambient transaction handle for the unit of work in flight.
+   *
+   * Providing it is {@link transact}'s job; an operation that needs the
+   * handle yields this key instead of taking a `tx` parameter, so "must run
+   * inside a transaction" lands in the `R` channel where the compiler checks
+   * it rather than in a parameter a caller can satisfy with the wrong handle.
+   *
+   * The payload is NOT interchangeable with {@link Database}. A transaction
+   * handle is the CONCRETE transaction the driver passed to the callback,
+   * whereas the `Database` payload can be a proxy the consuming application
+   * wrapped around its client (website #593 depends on that difference for
+   * subquery recursion). Read this key as "the open transaction", not as
+   * "permission to write".
+   *
+   * The key string is the `Database` key plus `/CurrentTransaction`, so the
+   * pair is legible in a context dump and two applications composed into one
+   * process never collide.
+   */
+  readonly CurrentTransaction: Context.Service<`${Key}/CurrentTransaction`, Tx>;
+
+  /**
+   * Runs `body` inside a database transaction, providing the handle as
+   * {@link CurrentTransaction}.
+   *
+   * Replaces the hand-rolled `db.transaction((tx) => …)` boundary at every
+   * call site: the handle is yielded here, the driver's callback parameter is
+   * discharged into the context, and `CurrentTransaction` leaves the
+   * requirement channel while everything else in it is preserved.
+   *
+   * **Always-open, never join-if-present.** Calling `transact` while a
+   * transaction is already open deliberately opens a NESTED one (a SAVEPOINT
+   * on the same connection), exactly as the hand-rolled `db.transaction` it
+   * replaces did. A "join the ambient transaction if there is one" variant is
+   * easy to write and is the wrong call here: it would silently delete every
+   * SAVEPOINT the calling code currently takes, changing rollback granularity
+   * without changing a line of that code. If you want to reuse the open
+   * transaction, yield {@link CurrentTransaction} directly and do not open
+   * another. Adjudicated on website #1883 (owner, 2026-09-07, condition 3) —
+   * please do not "improve" this into a join-if-present helper.
+   *
+   * The nested boundary is opened on the ambient handle
+   * (`tx.transaction(…)`), not on the client. Some drivers pin the open
+   * connection to the fiber and would nest either way; a driver that does not
+   * would hand `db.transaction` a SECOND pooled connection, making the
+   * "nested" transaction an independent one that cannot see its parent's
+   * uncommitted writes and does not roll back with it. Going through the
+   * ambient handle is a SAVEPOINT on every driver.
+   */
+  readonly transact: <A, E, R>(
+    body: Effect.Effect<A, E, R>,
+  ) => Effect.Effect<A, E | SqlError, Exclude<R, `${Key}/CurrentTransaction`> | Key>;
+
+  /**
+   * The handle a **read** should use: the ambient {@link CurrentTransaction}
+   * when one is open, the {@link Database} client otherwise.
+   *
+   * Reads sit either side of a boundary. A snapshot reconstruction runs with
+   * no transaction in sight and also runs inside a restore's; a
+   * carry-forward read happens once on a plain GET and again inside the
+   * update. Threading a handle through those is what keeps a
+   * `Pick<Tx, "select">` parameter alive after the services have removed
+   * every other one — functions carrying a parameter purely because they are
+   * honest about being callable from both sides.
+   *
+   * Preferring the transaction is also the safer default, not merely the
+   * convenient one. A read issued against `Database` from inside an open
+   * transaction takes its own pooled connection, so it is not guaranteed to
+   * see that transaction's uncommitted writes — a carry-forward read that
+   * missed the row the same unit of work had just written would be a silent
+   * wrong-answer bug. Reading through the open transaction removes the
+   * question. (A test harness that pins the pool to one connection cannot
+   * demonstrate the difference; the reasoning is about the pooled production
+   * path.)
+   *
+   * This is deliberately **not** what {@link transact} does for writes.
+   * There, joining an ambient transaction would delete a SAVEPOINT and change
+   * rollback granularity, which is why it is always-open (website #1883,
+   * owner, 2026-09-07). A read opens nothing, so there is no boundary to lose
+   * — the asymmetry is the point, not an inconsistency.
+   *
+   * Not for a caller that needs a handle which is concretely NOT the
+   * consuming application's proxy (website #593). This falls back to exactly
+   * that proxy when no transaction is open, so such a caller must keep
+   * opening one of its own.
+   *
+   * The requirement channel says {@link Database} either way:
+   * `Effect.serviceOption` does not surface `CurrentTransaction` in `R`, so
+   * the preference is invisible to the type checker and is pinned by a test
+   * instead.
+   */
+  readonly readHandle: Effect.Effect<ReadHandle<Tx>, never, Key>;
+}
+
+/**
+ * Builds one application's {@link DatabaseServices} around its own database
+ * and transaction types.
+ *
+ * Curried in two stages because TypeScript has no partial type-argument
+ * inference: the first call fixes the driver's handle types (which a consumer
+ * always writes out — they carry its relations graph), the second infers the
+ * key string literal from the argument. Call it once per database, at module
+ * scope, and export what it returns; calling it twice with the same key
+ * produces services that share a runtime slot.
+ *
+ * @example
+ * ```ts
+ * import { makeDatabaseServices } from "@thomasfosterau/effect-drizzle-ext/database";
+ * // Any driver's handle types fit; these are the `@effect/sql-pg` binding's.
+ * import type { PgDatabaseClient, PgTransaction } from "@thomasfosterau/effect-drizzle-ext-pg";
+ *
+ * const relations = {}; // the application's drizzle relations graph
+ * type AppDatabase = PgDatabaseClient<typeof relations>;
+ * type AppTransaction = PgTransaction<typeof relations>;
+ *
+ * const services = makeDatabaseServices<AppDatabase, AppTransaction>()({
+ *   key: "Database",
+ * });
+ * export const { Database, CurrentTransaction, transact, readHandle } = services;
+ * export type Database = typeof services.Database.Identifier; // "Database"
+ *
+ * console.log(Database.key); // "Database"
+ * ```
+ */
+export const makeDatabaseServices =
+  <
+    Db extends TransactionalDatabase<Tx> & ReadHandle<Tx>,
+    Tx extends ReadSurface & TransactionalDatabase<Tx>,
+  >() =>
+  <const Key extends string>(options: { readonly key: Key }): DatabaseServices<Db, Tx, Key> => {
+    const Database = Context.Service<Key, Db>(options.key);
+    const CurrentTransaction = Context.Service<`${Key}/CurrentTransaction`, Tx>(
+      `${options.key}/CurrentTransaction`,
+    );
+
+    /** Widens either handle to the read surface without a cast — both satisfy it structurally. */
+    const asReadHandle = (handle: ReadHandle<Tx>): ReadHandle<Tx> => handle;
+
+    /** Opens the body's boundary on `handle`, discharging the new transaction into the context. */
+    const openOn = <A, E, R>(
+      handle: TransactionalDatabase<Tx>,
+      body: Effect.Effect<A, E, R>,
+    ): Effect.Effect<A, E | SqlError, Exclude<R, `${Key}/CurrentTransaction`>> =>
+      handle.transaction((tx) => Effect.provideService(body, CurrentTransaction, tx));
+
+    return {
+      Database,
+      CurrentTransaction,
+      transact: <A, E, R>(
+        body: Effect.Effect<A, E, R>,
+      ): Effect.Effect<A, E | SqlError, Exclude<R, `${Key}/CurrentTransaction`> | Key> =>
+        Effect.flatMap(Effect.serviceOption(CurrentTransaction), (open) =>
+          Option.isSome(open)
+            ? openOn(open.value, body)
+            : Effect.flatMap(Database, (db) => openOn(db, body)),
+        ),
+      readHandle: Effect.flatMap(Effect.serviceOption(CurrentTransaction), (open) =>
+        Option.isSome(open)
+          ? Effect.succeed(asReadHandle(open.value))
+          : Effect.map(Database, asReadHandle),
+      ),
+    };
+  };

package/src/derivation-error.ts

@@ -0,0 +1,27 @@
+/**
+ * The construction-time failure every module-load derivation throws. Kept in a
+ * module of its own that imports nothing from Drizzle, so the Drizzle-free
+ * entry (`.`, which `defineTree` lives in) and `./derive` share one class: a
+ * consumer matching on it structurally, or with `instanceof`, sees the same
+ * error from either. Not a published subpath.
+ *
+ * @module derivation-error
+ */
+import * as Schema from "effect/Schema";
+
+/**
+ * A construction-time derivation failure: a table or a tree could not be built
+ * from its declarations (no builder registered for a column kind, a
+ * `references` annotation with no resolver, numeric bounds on a column the
+ * table has no column for, an unresolvable FK target, a tree level whose
+ * parent is missing or forms a cycle).
+ *
+ * **Thrown, never failed.** Derivation runs at module load, before an Effect
+ * runtime exists, so the only way to stop a misdeclared table or tree from
+ * reaching production is to make its `import` fail. It is a tagged error all
+ * the same, so a consumer that does catch one (a registry loader, a codegen
+ * script) can match it structurally.
+ */
+export class DerivationError extends Schema.TaggedError<DerivationError>()("DerivationError", {
+  message: Schema.String,
+}) {}