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

package/dist/database.d.ts

@@ -0,0 +1,189 @@
+import { PgTransactionConfig } from "drizzle-orm/pg-core";
+import * as Effect from "effect/Effect";
+import * as Context from "effect/Context";
+import { 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 declare 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>;
+//# sourceMappingURL=database.d.ts.map

package/dist/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","names":[],"sources":["../src/database.ts"],"mappings":";;;;;;;;;;;;;;;iBAiDiB;WACN;WACA;WACA;WACA;WACA;;;;;;;;;;;YAYC,WAAW,WAAW,eAAe,KAC/C;;;;;;;;;;;;;;iBAiBe,sBAAsB;WAC5B,cAAc,GAAG,GAAG,GAC3B,IAAI,IAAI,OAAO,OAAO,OAAO,GAAG,GAAG,IACnC,SAAS,wBACN,OAAO,OAAO,GAAG,IAAI,UAAU;;;;;;;;;;;;;iBAcrB,iBAAiB,IAAI,WAAW,aAAa;;;;;;WAMnD,UAAU,QAAQ,QAAQ,KAAK;;;;;;;;;;;;;;;;;;;;WAqB/B,oBAAoB,QAAQ,WAAW,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA8BjE,WAAW,GAAG,GAAG,GACxB,MAAM,OAAO,OAAO,GAAG,GAAG,OACvB,OAAO,OAAO,GAAG,IAAI,UAAU,QAAQ,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAwCrE,YAAY,OAAO,OAAO,WAAW,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAiC/C,uBAET,WAAW,sBAAsB,MAAM,WAAW,KAClD,WAAW,cAAc,sBAAsB,iBAE1C,oBAAkB;WAAsB,KAAK;MAAQ,iBAAiB,IAAI,IAAI"}

package/dist/database.js

@@ -0,0 +1,51 @@
+import * as Option from "effect/Option";
+import * as Effect from "effect/Effect";
+import * as Context from "effect/Context";
+// src/database.ts
+/**
+* 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"
+* ```
+*/
+const makeDatabaseServices = () => (options) => {
+	const Database = Context.Service(options.key);
+	const CurrentTransaction = Context.Service(`${options.key}/CurrentTransaction`);
+	/** Widens either handle to the read surface without a cast — both satisfy it structurally. */
+	const asReadHandle = (handle) => handle;
+	/** Opens the body's boundary on `handle`, discharging the new transaction into the context. */
+	const openOn = (handle, body) => handle.transaction((tx) => Effect.provideService(body, CurrentTransaction, tx));
+	return {
+		Database,
+		CurrentTransaction,
+		transact: (body) => 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))
+	};
+};
+export { makeDatabaseServices };
+
+//# sourceMappingURL=database.js.map

package/dist/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","names":[],"sources":["../src/database.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0OA,MAAa,8BAKgB,YAAkE;CAC3F,MAAM,WAAW,QAAQ,QAAiB,QAAQ,GAAG;CACrD,MAAM,qBAAqB,QAAQ,QACjC,GAAG,QAAQ,IAAI,oBACjB;;CAGA,MAAM,gBAAgB,WAA2C;;CAGjE,MAAM,UACJ,QACA,SAEA,OAAO,aAAa,OAAO,OAAO,eAAe,MAAM,oBAAoB,EAAE,CAAC;CAEhF,OAAO;EACL;EACA;EACA,WACE,SAEA,OAAO,QAAQ,OAAO,cAAc,kBAAkB,IAAI,SACxD,OAAO,OAAO,IAAI,IACd,OAAO,KAAK,OAAO,IAAI,IACvB,OAAO,QAAQ,WAAW,OAAO,OAAO,IAAI,IAAI,CAAC,CACvD;EACF,YAAY,OAAO,QAAQ,OAAO,cAAc,kBAAkB,IAAI,SACpE,OAAO,OAAO,IAAI,IACd,OAAO,QAAQ,aAAa,KAAK,KAAK,CAAC,IACvC,OAAO,IAAI,UAAU,YAAY,CACvC;CACF;AACF"}

package/dist/derive.d.ts

@@ -0,0 +1,97 @@
+import { L as DerivationError, i as DbColumn, l as FieldColumnsMetaOf, n as ColumnBounds, o as DbColumnReference } from "./index-CFhgcF4N.js";
+import * as Schema from "effect/Schema";
+import { ColumnBuilderBase } from "drizzle-orm";
+import { AnyPgColumn, ExtraConfigColumn, PgTableExtraConfigValue } from "drizzle-orm/pg-core";
+/**
+ * A registry mapping column kinds to Drizzle column builders — one builder per
+ * kind, taking the column name and returning a fresh (nullable) builder. The
+ * consumer supplies this; the package provides no fixed set.
+ */
+export type ColumnBuilders<Kind extends string = string> = Record<Kind, (column: string) => ColumnBuilderBase>;
+/** The (nullable) builder a kind produces in registry `B`. */
+type Builder<B extends ColumnBuilders, P extends keyof B> = ReturnType<B[P]>;
+/** The `.notNull()` form of a builder. */
+type NotNull<X> = X extends {
+  notNull(): infer R;
+} ? R : X;
+/**
+ * The Drizzle column builder a single db-column annotation produces against
+ * registry `B`. Total over any `M` (a widened `unknown` metadata falls back to
+ * the base builder type), computing the precise builder type for a concrete
+ * `{ pg, notNull }` metadata.
+ *
+ * Exported so a projection-specific derivation (the `./jsonapi/derive` entry)
+ * can name this type without restating it.
+ */
+export type BuilderFor<M, B extends ColumnBuilders> = M extends {
+  readonly pg: infer P;
+  readonly notNull: infer N;
+} ? P extends keyof B ? N extends true ? NotNull<Builder<B, P>> : Builder<B, P> : ColumnBuilderBase : ColumnBuilderBase;
+/**
+ * The Drizzle column builders a db-column metadata map produces against
+ * registry `B`, keyed and typed per entry — the type-level counterpart of the
+ * builder loop {@link makeDeriveColumns} returns.
+ */
+export type DerivedColumns<Meta, B extends ColumnBuilders> = { readonly [K in keyof Meta]: BuilderFor<Meta[K], B>; };
+/**
+ * Optional hooks for {@link makeDeriveColumns}. `resolveReference` turns a
+ * column's {@link DbColumnReference} name pair into the Drizzle column thunk
+ * `.references()` needs — the seam that lets FK-backed attributes derive their
+ * column instead of being hand-authored. Without it, a `references` annotation
+ * is a configuration error (throws), so a consumer only wires it when it
+ * declares FK columns. The `./references` entry ships one implementation.
+ */
+export interface DeriveOptions {
+  readonly resolveReference?: ((reference: DbColumnReference) => () => AnyPgColumn) | undefined;
+}
+/**
+ * The derivation pair {@link makeDeriveColumns} returns for builder registry
+ * `B`: `fromMeta` over an already-projected metadata map, `fromFields` over a
+ * `Schema.Struct`'s fields. Both throw {@link DerivationError} at module load
+ * on a misdeclared column.
+ */
+export interface DeriveColumns<B extends ColumnBuilders> {
+  /** Derive the builders an already-projected metadata map declares. */
+  readonly fromMeta: <Meta extends Record<string, DbColumn>>(metas: Meta) => DerivedColumns<Meta, B>;
+  /** Derive the builders a `Schema.Struct`'s annotated fields declare. */
+  readonly fromFields: <F extends Schema.Struct.Fields>(fields: F) => DerivedColumns<FieldColumnsMetaOf<F>, B>;
+}
+/**
+ * Build a derivation bound to a specific builder registry. The returned pair
+ * interprets per-column `dbColumn` metadata into the Drizzle column builders a
+ * table factory's `columns` expects:
+ *
+ * - `fromFields` takes a `Schema.Struct`'s fields directly (peeling the
+ *   `optional` / `NullOr` wrappers via {@link fieldColumns});
+ * - `fromMeta` takes an already-projected metadata map, for a projection this
+ *   entry knows nothing about (the `./jsonapi/derive` entry is one).
+ */
+export declare const makeDeriveColumns: <B extends ColumnBuilders>(builders: B, options?: DeriveOptions) => DeriveColumns<B>;
+/**
+ * Derive the SQL `CHECK` constraints an already-projected bounds map implies —
+ * the third leg of annotation-driven columns, after the column itself and the
+ * read-view selection. Emits one Drizzle `check()` per bounded column, named
+ * `${tableName}_${column}_${suffix}` (see {@link boundSuffix} for the canonical
+ * suffixes) unless the column annotation pins a `checkName`. A nullable
+ * column's expression is guarded with `col IS NULL OR …`, matching the
+ * hand-authored precedents.
+ *
+ * Returns a callback shaped for a table factory's `extraConstraints` seam: it
+ * receives the table's columns keyed by **attribute** name (not SQL column
+ * name). A bounded attribute whose column is absent from the table is a
+ * configuration error ({@link DerivationError}) — bounds on a column the table
+ * doesn't carry cannot be enforced.
+ */
+export declare const deriveCheckConstraintsFrom: (bounds: Record<string, ColumnBounds>, tableName: string) => (table: Record<string, ExtraConfigColumn>) => PgTableExtraConfigValue[];
+/**
+ * {@link deriveCheckConstraintsFrom} over a `Schema.Struct`'s fields: the
+ * bounds a model's `Schema.isGreaterThanOrEqualTo` / `isBetween` checks declare
+ * ({@link fieldColumnBounds}) become the table's CHECK constraints. One
+ * declaration drives wire validation and the database constraint.
+ *
+ * The projection is deferred to the returned callback, so this composes inside
+ * a `pgTable(...)` call whose fields are still being assembled.
+ */
+export declare const deriveFieldCheckConstraints: (fields: Schema.Struct.Fields, tableName: string) => (table: Record<string, ExtraConfigColumn>) => PgTableExtraConfigValue[];
+export { DerivationError };
+//# sourceMappingURL=derive.d.ts.map

package/dist/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","names":[],"sources":["../src/derive.ts"],"mappings":";;;;;;;;;YAmEY,eAAe,gCAAgC,OACzD,OACC,mBAAmB;;KAIjB,QAAQ,UAAU,gBAAgB,gBAAgB,KAAK,WAAW,EAAE;;KAGpE,QAAQ,KAAK;EAAY,iBAAiB;IAAM,IAAI;;;;;;;;;;YAW7C,WAAW,GAAG,UAAU,kBAAkB;WAC3C,UAAU;WACV,eAAe;IAEtB,gBAAgB,IACd,iBACE,QAAQ,QAAQ,GAAG,MACnB,QAAQ,GAAG,KACb,oBACF;;;;;;YAOQ,eAAe,MAAM,UAAU,8BAC/B,WAAW,OAAO,WAAW,KAAK,IAAI;;;;;;;;;iBA0BjC;WACN,qBAAqB,WAAW,4BAA4B;;;;;;;;iBA0BtD,cAAc,UAAU;;WAE9B,WAAW,aAAa,eAAe,WAC9C,OAAO,SACJ,eAAe,MAAM;;WAEjB,aAAa,UAAU,OAAO,OAAO,QAC5C,QAAQ,MACL,eAAe,mBAAmB,IAAI;;;;;;;;;;;;qBAahC,oBAAqB,UAAU,gBAAc,UAC9C,GAAC,UACF,kBACR,cAAc;;;;;;;;;;;;;;;;qBAwGJ,6BAA0B,QAC5B,eAAe,eAAa,uBAAmB,OAChD,eAAe,uBAAqB;;;;;;;;;;qBA6BjC,8BAA2B,QAC7B,OAAO,OAAO,QAAM,uBAAmB,OACxC,eAAe,uBAAqB"}

package/dist/derive.js

@@ -0,0 +1,142 @@
+import { c as fieldColumnBounds, h as DerivationError, l as fieldColumns } from "./src-CBeuhy5b.js";
+import * as Arr from "effect/Array";
+import * as R from "effect/Record";
+import "effect/Schema";
+import { sql } from "drizzle-orm";
+import { check } from "drizzle-orm/pg-core";
+// src/derive.ts
+/**
+* @copyright Thomas Foster
+*
+* **Effect Schema → Drizzle derivation: the derivation entry (Drizzle).**
+*
+* Reads the {@link DbColumn} metadata a schema declaration carries (via
+* {@link fieldColumns} from the {@link ./index.ts} annotation entry, or via any
+* other projection that yields a `Record<string, DbColumn>`) and emits the
+* matching Drizzle column builders. Depends on Drizzle, so a model / client
+* layer importing only the annotation entry never pulls the ORM.
+*
+* **Extensible column kinds.** The kind → builder mapping is *injected*, not
+* baked in: a consumer passes a builder registry (a record from its own kind
+* union to a Drizzle column builder) to {@link makeDeriveColumns}, and the
+* derivation preserves each column's precise builder type — so the derived
+* column map keeps `$inferSelect` typed — by reading the type-level phantom
+* `dbColumn` stamps alongside the runtime annotation.
+*
+* **Two entry shapes, one interpreter.** {@link makeDeriveColumns} returns both
+* `fromFields` (a `Schema.Struct`'s fields, the generic source) and `fromMeta`
+* (an already-projected metadata map, the seam the `./jsonapi/derive` entry and
+* any other projection build on). They share one builder loop.
+*
+* **Failures here are THROWN, not Effect failures.** Everything in this module
+* runs at *module load*, while a consumer's table modules are being evaluated —
+* before any Effect runtime exists to run a failure in, and before any query
+* can be issued. A misdeclared table must fail at `import`, not at first
+* insert, so a missing builder / a missing reference hook / bounds on a column
+* the table does not carry throw {@link DerivationError}. Runtime query
+* failures are the opposite and are never thrown: they travel in the Effect
+* error channel as the tagged errors of the `./errors` entry.
+*
+* @module derive
+*/
+/**
+* Build a derivation bound to a specific builder registry. The returned pair
+* interprets per-column `dbColumn` metadata into the Drizzle column builders a
+* table factory's `columns` expects:
+*
+* - `fromFields` takes a `Schema.Struct`'s fields directly (peeling the
+*   `optional` / `NullOr` wrappers via {@link fieldColumns});
+* - `fromMeta` takes an already-projected metadata map, for a projection this
+*   entry knows nothing about (the `./jsonapi/derive` entry is one).
+*/
+const makeDeriveColumns = (builders, options = {}) => {
+	const buildColumn = (meta) => {
+		const build = builders[meta.pg];
+		if (build === void 0) throw new DerivationError({ message: `no builder registered for column kind '${meta.pg}'` });
+		let column = build(meta.column);
+		if (meta.notNull) column = column.notNull();
+		if (meta.default !== void 0) column = column.default(meta.default);
+		if (meta.references !== void 0) {
+			if (options.resolveReference === void 0) throw new DerivationError({ message: `column '${meta.column}' declares a reference but no resolveReference hook was provided` });
+			const target = options.resolveReference(meta.references);
+			column = column.references(target, {
+				onDelete: meta.references.onDelete,
+				onUpdate: meta.references.onUpdate
+			});
+		}
+		return column;
+	};
+	const buildColumns = (metas) => R.fromEntries(Arr.map(R.toEntries(metas), ([name, meta]) => [name, buildColumn(meta)]));
+	return {
+		fromMeta: (metas) => buildColumns(metas),
+		fromFields: (fields) => buildColumns(fieldColumns(fields))
+	};
+};
+/** A number rendered inline into the CHECK expression (never a bind parameter). */
+const literal = (value) => sql.raw(String(value));
+/**
+* The canonical constraint-name suffix a set of bounds earns: `range` when
+* bounded on both sides; `non_negative` for the sole inclusive-minimum-of-`0`
+* case (the established naming for count/duration columns); `min` / `max` for
+* the remaining one-sided bounds.
+*/
+const boundSuffix = (bounds) => {
+	const hasMin = bounds.minimum !== void 0 || bounds.exclusiveMinimum !== void 0;
+	const hasMax = bounds.maximum !== void 0 || bounds.exclusiveMaximum !== void 0;
+	if (hasMin && hasMax) return "range";
+	if (!hasMin) return "max";
+	return bounds.minimum === 0 ? "non_negative" : "min";
+};
+/** The per-side comparisons for a bound set (exclusive bounds win their side). */
+const comparisonParts = (column, bounds) => {
+	const { minimum, maximum, exclusiveMinimum, exclusiveMaximum } = bounds;
+	const parts = [];
+	if (exclusiveMinimum !== void 0) parts.push(sql`${column} > ${literal(exclusiveMinimum)}`);
+	else if (minimum !== void 0) parts.push(sql`${column} >= ${literal(minimum)}`);
+	if (exclusiveMaximum !== void 0) parts.push(sql`${column} < ${literal(exclusiveMaximum)}`);
+	else if (maximum !== void 0) parts.push(sql`${column} <= ${literal(maximum)}`);
+	return parts;
+};
+/**
+* The bound expression for one column (without the nullability guard): a
+* both-sides-inclusive bound renders as `col BETWEEN min AND max` — matching
+* the hand-authored year-range constraints in the consuming applications — and
+* anything else as the {@link comparisonParts} joined with `AND`.
+*/
+const boundExpression = (column, bounds) => bounds.minimum !== void 0 && bounds.maximum !== void 0 ? sql`${column} BETWEEN ${literal(bounds.minimum)} AND ${literal(bounds.maximum)}` : sql.join(comparisonParts(column, bounds), sql` AND `);
+/**
+* Derive the SQL `CHECK` constraints an already-projected bounds map implies —
+* the third leg of annotation-driven columns, after the column itself and the
+* read-view selection. Emits one Drizzle `check()` per bounded column, named
+* `${tableName}_${column}_${suffix}` (see {@link boundSuffix} for the canonical
+* suffixes) unless the column annotation pins a `checkName`. A nullable
+* column's expression is guarded with `col IS NULL OR …`, matching the
+* hand-authored precedents.
+*
+* Returns a callback shaped for a table factory's `extraConstraints` seam: it
+* receives the table's columns keyed by **attribute** name (not SQL column
+* name). A bounded attribute whose column is absent from the table is a
+* configuration error ({@link DerivationError}) — bounds on a column the table
+* doesn't carry cannot be enforced.
+*/
+const deriveCheckConstraintsFrom = (bounds, tableName) => (table) => Arr.map(R.toEntries(bounds), ([attribute, columnBounds]) => {
+	const column = table[attribute];
+	if (column === void 0) throw new DerivationError({ message: `attribute '${attribute}' declares numeric bounds but table '${tableName}' has no column for it` });
+	const expression = boundExpression(column, columnBounds);
+	const guarded = columnBounds.column.notNull ? expression : sql`${column} IS NULL OR ${expression}`;
+	const name = columnBounds.column.checkName ?? `${tableName}_${columnBounds.column.column}_${boundSuffix(columnBounds)}`;
+	return check(name, guarded);
+});
+/**
+* {@link deriveCheckConstraintsFrom} over a `Schema.Struct`'s fields: the
+* bounds a model's `Schema.isGreaterThanOrEqualTo` / `isBetween` checks declare
+* ({@link fieldColumnBounds}) become the table's CHECK constraints. One
+* declaration drives wire validation and the database constraint.
+*
+* The projection is deferred to the returned callback, so this composes inside
+* a `pgTable(...)` call whose fields are still being assembled.
+*/
+const deriveFieldCheckConstraints = (fields, tableName) => (table) => deriveCheckConstraintsFrom(fieldColumnBounds(fields), tableName)(table);
+export { DerivationError, deriveCheckConstraintsFrom, deriveFieldCheckConstraints, makeDeriveColumns };
+
+//# sourceMappingURL=derive.js.map

package/dist/derive.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,157 @@
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as Effect from "effect/Effect";
+/**
+ * The fields of a Postgres error response this library reads, as recovered from
+ * wherever the driver's error sits in an error graph. `code` is the SQLSTATE and
+ * is always present (finding it is what identifies the node); every other
+ * fact is `Option` because Postgres populates it per error class — a `23502`
+ * carries `column` and `table` but no `constraint`, a `23503` carries
+ * `constraint`, `table` and `detail`.
+ */
+export interface PgErrorFacts {
+  /** The five-character SQLSTATE, e.g. `23505`. */
+  readonly code: string;
+  /** The driver's message, or `""` when the node carries none. */
+  readonly message: string;
+  /** The violated constraint's name, for the constraint classes that name one. */
+  readonly constraint: Option.Option<string>;
+  /** The table the statement touched. */
+  readonly table: Option.Option<string>;
+  /** The column at fault, populated for NOT NULL violations. */
+  readonly column: Option.Option<string>;
+  /** Postgres' `DETAIL` line, which names the conflicting key values. */
+  readonly detail: Option.Option<string>;
+  /** The schema the table lives in. */
+  readonly schema: Option.Option<string>;
+}
+/**
+ * The driver's Postgres error facts, recovered from anywhere in `error`'s graph:
+ * a bare Postgres error, a bare `SqlError` (whose `reason` holds the driver
+ * error as its `cause`), or drizzle's `EffectDrizzleQueryError` wrapping an
+ * Effect `Cause` that holds the `SqlError`. `Option.none()` when the graph
+ * holds no node declaring a SQLSTATE, including for a non-object input.
+ *
+ * The walk is bounded (depth 8) and cycle-guarded, so a self-referential or
+ * pathologically deep graph terminates.
+ */
+export declare const findPgError: (error: unknown) => Option.Option<PgErrorFacts>;
+declare const UniqueViolation_base: Schema.Class<UniqueViolation, Schema.TaggedStruct<"UniqueViolation", {
+  readonly constraint: Schema.Option<Schema.String>;
+  readonly table: Schema.Option<Schema.String>;
+  readonly detail: Schema.Option<Schema.String>;
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * SQLSTATE `23505`: a unique or primary key constraint was violated.
+ * `cause` is the value classification started from, so the wrapping graph
+ * (drizzle's query text and params, the `SqlError`) survives the recovery.
+ */
+export declare class UniqueViolation extends UniqueViolation_base {}
+declare const ForeignKeyViolation_base: Schema.Class<ForeignKeyViolation, Schema.TaggedStruct<"ForeignKeyViolation", {
+  readonly constraint: Schema.Option<Schema.String>;
+  readonly table: Schema.Option<Schema.String>;
+  readonly detail: Schema.Option<Schema.String>;
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/** SQLSTATE `23503`: a foreign key constraint was violated. `cause` as in {@link UniqueViolation}. */
+export declare class ForeignKeyViolation extends ForeignKeyViolation_base {}
+declare const NotNullViolation_base: Schema.Class<NotNullViolation, Schema.TaggedStruct<"NotNullViolation", {
+  readonly column: Schema.Option<Schema.String>;
+  readonly table: Schema.Option<Schema.String>;
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/** SQLSTATE `23502`: a NOT NULL constraint was violated. `column` names the offending column. */
+export declare class NotNullViolation extends NotNullViolation_base {}
+declare const CheckViolation_base: Schema.Class<CheckViolation, Schema.TaggedStruct<"CheckViolation", {
+  readonly constraint: Schema.Option<Schema.String>;
+  readonly table: Schema.Option<Schema.String>;
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/** SQLSTATE `23514`: a CHECK constraint was violated — including the bounds checks `./derive` writes. */
+export declare class CheckViolation extends CheckViolation_base {}
+declare const ExclusionViolation_base: Schema.Class<ExclusionViolation, Schema.TaggedStruct<"ExclusionViolation", {
+  readonly constraint: Schema.Option<Schema.String>;
+  readonly table: Schema.Option<Schema.String>;
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/** SQLSTATE `23P01`: an EXCLUDE constraint was violated. */
+export declare class ExclusionViolation extends ExclusionViolation_base {}
+declare const SerializationFailure_base: Schema.Class<SerializationFailure, Schema.TaggedStruct<"SerializationFailure", {
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * SQLSTATE `40001`: the transaction lost a serialization conflict. Retryable:
+ * the same transaction re-run from the top may commit.
+ */
+export declare class SerializationFailure extends SerializationFailure_base {}
+declare const DeadlockDetected_base: Schema.Class<DeadlockDetected, Schema.TaggedStruct<"DeadlockDetected", {
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * SQLSTATE `40P01`: the transaction was chosen as a deadlock victim.
+ * Retryable, like {@link SerializationFailure}.
+ */
+export declare class DeadlockDetected extends DeadlockDetected_base {}
+/**
+ * The integrity-constraint family (`23xxx`): a failure the *statement* caused,
+ * which a caller can map to a domain conflict. Retrying it unchanged fails
+ * again.
+ */
+export type ConstraintViolation = UniqueViolation | ForeignKeyViolation | NotNullViolation | CheckViolation | ExclusionViolation;
+/**
+ * Every failure this module recognises: a {@link ConstraintViolation}, or one
+ * of the two retryable transaction failures.
+ */
+export type ClassifiedError = ConstraintViolation | SerializationFailure | DeadlockDetected;
+/**
+ * Classifies any value into one of the seven tagged errors, by finding the
+ * driver's Postgres error in its graph ({@link findPgError}) and dispatching on the
+ * SQLSTATE. `Option.none()` when the graph holds no driver error, or holds one
+ * whose SQLSTATE is outside the classified families (a syntax error, a
+ * connection failure — `SqlError.reason` already covers those well).
+ */
+export declare const classifyError: (error: unknown) => Option.Option<ClassifiedError>;
+/**
+ * True when `error` is (or wraps) a unique-constraint violation.
+ *
+ * Kept as its own predicate, with its own walk, for adoption parity: this is
+ * the name and the semantics the consuming applications already call, and the
+ * semantics include a fallback the typed classification deliberately does not
+ * have — matching the stable Postgres message fragment when no `code` survived the
+ * wrapping. It also matches a `23505` declared under a `code` that is not
+ * SQLSTATE-shaped, which {@link classifyError} skips.
+ */
+export declare const isUniqueViolation: (error: unknown) => boolean;
+/**
+ * True when `error` is (or wraps) an integrity-constraint violation — one of
+ * the five `23xxx` classes {@link classifyError} recognises.
+ */
+export declare const isConstraintViolation: (error: unknown) => boolean;
+/**
+ * True when `error` is (or wraps) a transaction failure that re-running the
+ * whole transaction may clear: a serialization failure (`40001`) or a deadlock
+ * (`40P01`). Retrying a {@link ConstraintViolation} is pointless; retrying
+ * these is the documented remedy.
+ */
+export declare const isRetryableTransactionFailure: (error: unknown) => boolean;
+/**
+ * Recovers from a constraint violation in the error channel, leaving every
+ * other failure untouched — the failure is re-failed unchanged, with its
+ * original type, so a handler for one Postgres conflict does not swallow the
+ * rest of the channel.
+ *
+ * Data-last only: `self.pipe(catchConstraintViolation(handler))`.
+ */
+export declare const catchConstraintViolation: <A2, E2, R2>(f: (violation: ConstraintViolation) => Effect.Effect<A2, E2, R2>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A | A2, E | E2, R | R2>;
+/**
+ * {@link catchConstraintViolation} narrowed to `23505`: recovers only a unique
+ * violation, passing everything else — including other constraint violations —
+ * through unchanged. This is the duplicate-key conflict a consumer maps to a
+ * domain "already exists".
+ *
+ * Data-last only: `self.pipe(catchUniqueViolation(handler))`.
+ */
+export declare const catchUniqueViolation: <A2, E2, R2>(f: (violation: UniqueViolation) => Effect.Effect<A2, E2, R2>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A | A2, E | E2, R | R2>;
+export {};
+//# sourceMappingURL=errors.d.ts.map