@thomasfosterau/effect-drizzle-ext 0.0.0 → 0.1.0

package/dist/jsonapi/index.d.ts

@@ -0,0 +1,189 @@
+import { F as Tree, N as LevelSpec, c as DbTableOf$1, h as UnwrapColumn, i as DbColumn, l as FieldColumnsMetaOf, m as TableMeta, n as ColumnBounds, p as TableAnnotated$1, s as DbTable } from "../index-CFhgcF4N.js";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { Resource } from "@thomasfosterau/effect-jsonapi";
+/**
+ * Any `Resource.make` resource definition. Re-exported so a derivation layer
+ * can name the constraint of {@link ResourceColumnsMetaOf} without importing
+ * `@thomasfosterau/effect-jsonapi` directly.
+ */
+export type AnyResource = Resource.Any;
+/**
+ * The underlying schema of an attribute field. A `Resource.attribute`
+ * descriptor carries the schema `S` in its config (recoverable through the
+ * `Resource.Attribute` type), peeling the `resource: "optional"` `optionalKey`
+ * wrapper that would otherwise bury the `dbColumn` phantom; a plain annotated
+ * attribute (e.g. `dbColumn(schema, …)` passed directly) is its own schema.
+ */
+type UnderlyingSchema<A> = A extends Resource.Attribute<infer S, infer _R, infer _C, infer _U, infer _Cl> ? S : A;
+/**
+ * The db-column metadata map a resource definition projects to, keyed by the
+ * attributes that declare a `dbColumn` (others drop out of the map entirely).
+ * Recovers each attribute's underlying schema (peeling the descriptor + any
+ * `optionalKey` resource wrapper) and reads its phantom via
+ * {@link UnwrapColumn}. The resource-shaped counterpart of
+ * `FieldColumnsMetaOf`.
+ */
+export type ResourceColumnsMetaOf<R extends AnyResource> = { readonly [K in keyof Resource.AttributesOf<R> as [UnwrapColumn<UnderlyingSchema<Resource.AttributesOf<R>[K]>>] extends [never] ? never : K]: UnwrapColumn<UnderlyingSchema<Resource.AttributesOf<R>[K]>>; };
+/**
+ * Project a resource definition's per-attribute {@link DbColumn} metadata into
+ * plain data the derivation consumes, dropping attributes that declare no
+ * column. Reads the annotation via `Resource.attributeAnnotations`, which
+ * resolves each attribute schema's annotations — including through the
+ * `optionalKey` wrapper a `resource: "optional"` attribute carries, whose AST
+ * is the inner schema's. The type-level counterpart is
+ * {@link ResourceColumnsMetaOf}.
+ */
+export declare const resourceColumns: (resource: AnyResource) => Record<string, DbColumn>;
+/**
+ * Project a resource definition's per-attribute numeric bounds into plain data
+ * a `CHECK`-constraint derivation consumes: for each `dbColumn`-annotated
+ * attribute whose schema carries numeric-bound checks, the bounds paired with
+ * the column metadata. Attributes without a column, or without bounds, drop.
+ * The Drizzle-emitting counterpart is the `./jsonapi/derive` entry's
+ * `deriveCheckConstraints`.
+ */
+export declare const resourceColumnBounds: (resource: AnyResource) => Record<string, ColumnBounds>;
+/**
+ * The resource-projection shape of one `Resource.make` attribute, as plain
+ * data — what an operation factory needs to derive a row → resource mapper
+ * and a version-table column map from the model alone:
+ *
+ * - `date` (a `createdAt` / `updatedAt` / `deletedAt`-style `Date`) → a
+ *   timestamp axis the mapper reads from the chain rather than a column,
+ * - `array` (a materialised-list attribute a flat view does not carry) → a
+ *   placeholder the mapper fills from a join,
+ * - `optional` (an `optionalKey` resource projection) → the value drops when
+ *   the column is absent rather than surfacing as a present `undefined`,
+ * - everything else (including a `NullOr` column read straight off a view) →
+ *   passthrough.
+ *
+ * `column` is the column the attribute's `dbColumn` annotation names, `none`
+ * for an attribute that declares none.
+ */
+export interface ResourceAttributeProjection {
+  readonly key: string;
+  /** The resource projection is an `optionalKey` (drops when absent). */
+  readonly optional: boolean;
+  /** The attribute schema accepts `null` (a `Schema.NullOr`). */
+  readonly nullable: boolean;
+  /** The attribute schema is an array (a materialised-list attribute). */
+  readonly array: boolean;
+  /** The attribute schema decodes an ISO string to a `Date` (a timestamp axis). */
+  readonly date: boolean;
+  /** The column the attribute backs, if it declares one. */
+  readonly column: Option.Option<string>;
+}
+/**
+ * Project a `Resource.make` definition's resource-object attributes into
+ * ordered plain-data {@link ResourceAttributeProjection}s (declaration
+ * order). Optionality is read off each field's AST (`optionalKey` marks the
+ * property optional); nullability, array-ness and date-ness are recovered by
+ * behavioural decode probes through each schema's JSON codec (the wire
+ * reading), so the read stays robust across schema-AST shapes (a `NullOr` of
+ * a transformation, a branded array, …).
+ *
+ * Input-only attributes (`resource: false`) are not on the resource object,
+ * and so not here. The `column` read is {@link resourceColumns}'.
+ */
+export declare const resourceAttributeProjections: (resource: AnyResource) => ReadonlyArray<ResourceAttributeProjection>;
+/**
+ * A resource definition carrying db-table metadata `M` in a type-level phantom
+ * — `TableAnnotated` from the annotation entry with its target narrowed to a
+ * resource.
+ */
+export type TableAnnotated<R extends AnyResource, M extends TableMeta> = TableAnnotated$1<R, M>;
+/** Recovers the db-table metadata phantom from a resource, or `never`. */
+export type DbTableOf<R> = DbTableOf$1<R>;
+/**
+ * Annotate a resource definition with the database table it backs. The
+ * annotation entry's `dbTable`, narrowed to `R extends AnyResource`: it
+ * attaches the metadata as a non-enumerable symbol property and returns the
+ * **same** resource object, so `Resource.make`'s assigned properties (`type`,
+ * `Id`, `identifier`, …) and the referential identity a registry compares by
+ * both survive.
+ */
+export declare const dbTable: <R extends AnyResource, const M extends TableMeta>(resource: R, meta: M) => TableAnnotated<R, M>;
+/**
+ * A {@link dbTable} constrained to a specific level union `Level`, requiring
+ * the full {@link DbTable} metadata. A consumer pins its own levels once —
+ * `const dbTable = dbTableFor<LeafLevel>()` — so an annotation naming a level
+ * the derivation has no parent binding for is a type error at the annotation
+ * site.
+ */
+export declare const dbTableFor: <Level extends string>() => <R extends AnyResource, const M extends DbTable<Level>>(resource: R, meta: M) => TableAnnotated<R, M>;
+/**
+ * Read the db-table metadata off a resource at runtime. `Option.none()` when
+ * the resource carries none. Typed to the {@link TableMeta} floor; a consumer
+ * that annotated with a {@link DbTable} recovers its `level` through the
+ * {@link DbTableOf} phantom.
+ */
+export declare const readDbTable: (resource: AnyResource) => Option.Option<TableMeta>;
+/** The resource an entry's `leaf` holds, when it holds one. */
+type EntryResource<E> = E extends {
+  readonly leaf?: infer L;
+} ? Exclude<L, undefined> extends AnyResource ? Exclude<L, undefined> : never : never;
+/** The fields an entry's `columns` declares; `{}` when absent. */
+type EntryLevelFields<E> = E extends {
+  readonly columns?: infer F;
+} ? Exclude<F, undefined> extends Schema.Struct.Fields ? Exclude<F, undefined> : Record<never, never> : Record<never, never>;
+/**
+ * The typed column metadata of a {@link defineResourceTree} declaration `S`:
+ * per level, its level columns' `DbColumn` map and its leaf resource's
+ * attribute columns. The phantom the table derivation reads.
+ */
+export type ResourceTreeMeta<S> = { readonly [K in keyof S]: {
+  readonly level: FieldColumnsMetaOf<EntryLevelFields<S[K]>>;
+  readonly leaf: [EntryResource<S[K]>] extends [never] ? Record<never, never> : ResourceColumnsMetaOf<EntryResource<S[K]>>;
+}; };
+/**
+ * The constraint a resource tree declaration `S` is checked against: the
+ * core `CheckedTreeSpec`, with each leaf a `Resource.make` definition whose
+ * wire `type` is the level's own name. A leaf filed under another name, or a
+ * parent naming no level (or the level itself), is a type error.
+ */
+export type CheckedResourceTreeSpec<S, Ext> = { readonly [K in keyof S]: LevelSpec<Exclude<keyof S & string, K>, AnyResource & {
+  readonly type: K;
+}> & Ext; };
+/**
+ * A {@link defineResourceTree} whose every entry also carries the consumer's
+ * extension record `Ext`, which the library never reads (pulpit's
+ * `RegistryEntry` flags). Pin it once — `const defineTree =
+ * defineResourceTreeFor<RegistryFlags>()`. Throws `DerivationError` at module
+ * load as `defineResourceTree` does.
+ */
+export declare const defineResourceTreeFor: <Ext extends object>() => <const S extends CheckedResourceTreeSpec<S, Ext>>(spec: S) => Tree<S, ResourceTreeMeta<S>>;
+/**
+ * The core entry's `defineTree` over `Resource.make` definitions: each leaf's
+ * `leaf` is the resource whose wire `type` is the level's name (the
+ * discriminator value), and its domain columns are the resource's
+ * `dbColumn`-annotated attributes. Every other check is the core one. Throws
+ * `DerivationError` at module load for a leaf whose resource `type` isn't its
+ * name, and for every structural fault `defineTree` names.
+ *
+ * @example
+ * ```ts
+ * import { dbColumn } from "@thomasfosterau/effect-drizzle-ext";
+ * import { defineResourceTree } from "@thomasfosterau/effect-drizzle-ext/jsonapi";
+ * import { Resource } from "@thomasfosterau/effect-jsonapi";
+ * import * as Schema from "effect/Schema";
+ *
+ * const Book = Resource.make("book", {
+ *   attributes: {
+ *     pages: dbColumn(Schema.Finite, { column: "pages", pg: "integer", notNull: false }),
+ *   },
+ * });
+ *
+ * const tree = defineResourceTree({
+ *   work: {
+ *     columns: { title: dbColumn(Schema.String, { column: "title", pg: "text", notNull: true }) },
+ *   },
+ *   book: { parent: "work", leaf: Book },
+ * });
+ *
+ * console.log(tree.leaves); // ["book"]
+ * ```
+ */
+export declare const defineResourceTree: <const S extends CheckedResourceTreeSpec<S, Record<never, never>>>(spec: S) => Tree<S, ResourceTreeMeta<S>>;
+export type { DbTable, TableMeta };
+//# sourceMappingURL=index.d.ts.map

package/dist/jsonapi/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":["CoreTableAnnotated","CoreDbTableOf"],"sources":["../../src/jsonapi/index.ts"],"mappings":";;;;;;;;;YA2DY,cAAc,SAAS;;;;;;;;KAS9B,iBAAiB,KACpB,UAAU,SAAS,gBAAgB,SAAS,UAAU,UAAU,UAAU,OAAO,IAAI;;;;;;;;;YAU3E,sBAAsB,UAAU,2BAExC,WAAW,SAAS,aAAa,OAC/B,aAAa,iBAAiB,SAAS,aAAa,GAAG,gCAGrD,IACH,aAAa,iBAAiB,SAAS,aAAa,GAAG;;;;;;;;;;qBAY/C,kBAAe,UAAc,gBAAc,eAAe;;;;;;;;;qBAuB1D,uBAAoB,UAAc,gBAAc,eAAe;;;;;;;;;;;;;;;;;;iBA8B3D;WACN;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA,QAAQ,OAAO;;;;;;;;;;;;;;qBA6Bb,+BAA4B,UAC7B,gBACT,cAAc;;;;;;YAsBL,eAAe,UAAU,aAAa,UAAU,aAAaA,iBAAmB,GAAG;;YAGnF,UAAU,KAAKC,YAAc;;;;;;;;;qBAU5B,UAAW,UAAU,mBAAmB,UAAU,WAAS,UAC5D,GAAC,MACL,MACL,eAAe,GAAG;;;;;;;;qBASR,aACV,4BACA,UAAU,mBAAmB,UAAU,QAAQ,QAAM,UAC1C,GAAC,MACL,MACL,eAAe,GAAG;;;;;;;qBASV,cAAW,UAAc,gBAAc,OAAO,OAAO;;KAM7D,cAAc,KAAK;WAAqB,aAAa;IACtD,QAAQ,sBAAsB,cAC5B,QAAQ;;KAKT,iBAAiB,KAAK;WAAqB,gBAAgB;IAC5D,QAAQ,sBAAsB,OAAO,OAAO,SAC1C,QAAQ,gBACR,uBACF;;;;;;YAOQ,iBAAiB,iBACjB,WAAW;WACV,OAAO,mBAAmB,iBAAiB,EAAE;WAC7C,OAAO,cAAc,EAAE,uBAC5B,uBACA,sBAAsB,cAAc,EAAE;;;;;;;;YAUlC,wBAAwB,GAAG,mBAC3B,WAAW,IAAI,UACvB,cAAc,YAAY,IAC1B;WAAyB,MAAM;KAE/B;;;;;;;;qBAUS,wBACV,gCACM,UAAU,wBAAwB,GAAG,MAAI,MAAQ,MAAI,KAAK,GAAG,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA0C1E,2BAA2B,UAAU,wBAAwB,GAAG,uBAC3E,MAAM,MACH,KAAK,GAAG,iBAAiB"}

package/dist/jsonapi/index.js

@@ -0,0 +1,164 @@
+import { f as readDbTable$1, i as dbTable$1, l as fieldColumns, m as treeError, p as buildTree, t as DB_COLUMN_KEY, u as numericBounds } from "../src-CBeuhy5b.js";
+import * as Arr from "effect/Array";
+import * as Option from "effect/Option";
+import * as Predicate from "effect/Predicate";
+import * as R from "effect/Record";
+import * as Schema from "effect/Schema";
+import * as SchemaAST from "effect/SchemaAST";
+import { Resource } from "@thomasfosterau/effect-jsonapi";
+// src/jsonapi/index.ts
+/**
+* @copyright Thomas Foster
+*
+* **The JSON:API resource projection of the annotation entry (no Drizzle).**
+*
+* The {@link ../index.ts} entry reads `dbColumn` annotations off a
+* `Schema.Struct`'s fields. A consumer whose models are
+* `@thomasfosterau/effect-jsonapi` `Resource.make` definitions declares the
+* same annotations on its **attributes**, which sit behind an extra layer:
+* `Resource.attribute` descriptors, and the `optionalKey` wrapper a
+* `resource: "optional"` attribute takes. This entry is the reader for that
+* shape — the resource-shaped counterpart of `fieldColumns` /
+* `fieldColumnBounds`.
+*
+* **No Drizzle, and an optional peer.** `@thomasfosterau/effect-jsonapi` is an
+* *optional* peer dependency: only this subpath and `./derive` import it, so a
+* consumer with plain `Schema.Struct` models never installs it. The
+* Drizzle-emitting half is `./jsonapi/derive`.
+*
+* The table-level annotation helpers are re-exported here with an
+* `R extends AnyResource` bound. They are the same functions — the narrower
+* bound exists so a consumer's resource-facing `db-annotation.ts` can import
+* every name it needs from one place, and so a non-resource object cannot be
+* annotated through the resource-shaped API by accident.
+*
+* @module jsonapi
+*/
+/**
+* Project a resource definition's per-attribute {@link DbColumn} metadata into
+* plain data the derivation consumes, dropping attributes that declare no
+* column. Reads the annotation via `Resource.attributeAnnotations`, which
+* resolves each attribute schema's annotations — including through the
+* `optionalKey` wrapper a `resource: "optional"` attribute carries, whose AST
+* is the inner schema's. The type-level counterpart is
+* {@link ResourceColumnsMetaOf}.
+*/
+const resourceColumns = (resource) => R.getSomes(R.map(Resource.attributeAnnotations(resource), (annotations) => Option.map(Option.fromUndefinedOr(annotations?.[DB_COLUMN_KEY]), (meta) => meta)));
+/**
+* Project a resource definition's per-attribute numeric bounds into plain data
+* a `CHECK`-constraint derivation consumes: for each `dbColumn`-annotated
+* attribute whose schema carries numeric-bound checks, the bounds paired with
+* the column metadata. Attributes without a column, or without bounds, drop.
+* The Drizzle-emitting counterpart is the `./jsonapi/derive` entry's
+* `deriveCheckConstraints`.
+*/
+const resourceColumnBounds = (resource) => {
+	const fields = Resource.attributes(resource);
+	return R.getSomes(R.map(resourceColumns(resource), (column, name) => Option.map(numericBounds(fields[name]), (bounds) => ({
+		column,
+		...bounds
+	}))));
+};
+/** An ISO timestamp a `Date`-decoding attribute schema accepts. */
+const ISO_PROBE = "2024-01-02T03:04:05.000Z";
+/**
+* What a schema's **JSON codec** decodes `input` to — the wire reading, so an
+* ISO string decodes to a `Date` for `Schema.Date` (whose own decoder accepts
+* only a `Date` instance). A decoder is built per call: this is start-up
+* introspection over a model, not a hot path.
+*/
+const decodesFromJson = (schema, input) => Schema.decodeOption(Schema.toCodecJson(schema))(input);
+/**
+* Project a `Resource.make` definition's resource-object attributes into
+* ordered plain-data {@link ResourceAttributeProjection}s (declaration
+* order). Optionality is read off each field's AST (`optionalKey` marks the
+* property optional); nullability, array-ness and date-ness are recovered by
+* behavioural decode probes through each schema's JSON codec (the wire
+* reading), so the read stays robust across schema-AST shapes (a `NullOr` of
+* a transformation, a branded array, …).
+*
+* Input-only attributes (`resource: false`) are not on the resource object,
+* and so not here. The `column` read is {@link resourceColumns}'.
+*/
+const resourceAttributeProjections = (resource) => {
+	const fields = Resource.attributes(resource);
+	const columns = resourceColumns(resource);
+	return Arr.map(R.toEntries(fields), ([key, schema]) => ({
+		key,
+		optional: SchemaAST.isOptional(schema.ast),
+		nullable: Option.isSome(decodesFromJson(schema, null)),
+		array: Option.isSome(decodesFromJson(schema, [])),
+		date: Option.exists(decodesFromJson(schema, ISO_PROBE), Predicate.isDate),
+		column: Option.fromNullishOr(columns[key]?.column)
+	}));
+};
+/**
+* Annotate a resource definition with the database table it backs. The
+* annotation entry's `dbTable`, narrowed to `R extends AnyResource`: it
+* attaches the metadata as a non-enumerable symbol property and returns the
+* **same** resource object, so `Resource.make`'s assigned properties (`type`,
+* `Id`, `identifier`, …) and the referential identity a registry compares by
+* both survive.
+*/
+const dbTable = (resource, meta) => dbTable$1(resource, meta);
+/**
+* A {@link dbTable} constrained to a specific level union `Level`, requiring
+* the full {@link DbTable} metadata. A consumer pins its own levels once —
+* `const dbTable = dbTableFor<LeafLevel>()` — so an annotation naming a level
+* the derivation has no parent binding for is a type error at the annotation
+* site.
+*/
+const dbTableFor = () => (resource, meta) => dbTable$1(resource, meta);
+/**
+* Read the db-table metadata off a resource at runtime. `Option.none()` when
+* the resource carries none. Typed to the {@link TableMeta} floor; a consumer
+* that annotated with a {@link DbTable} recovers its `level` through the
+* {@link DbTableOf} phantom.
+*/
+const readDbTable = (resource) => readDbTable$1(resource);
+/**
+* A {@link defineResourceTree} whose every entry also carries the consumer's
+* extension record `Ext`, which the library never reads (pulpit's
+* `RegistryEntry` flags). Pin it once — `const defineTree =
+* defineResourceTreeFor<RegistryFlags>()`. Throws `DerivationError` at module
+* load as `defineResourceTree` does.
+*/
+const defineResourceTreeFor = () => (spec) => buildTree(spec, {
+	levelColumns: fieldColumns,
+	leafColumns: (resource, name) => resource.type === name ? resourceColumns(resource) : treeError(`leaf "${name}" carries resource "${resource.type}"; a leaf's name is its resource's type`)
+});
+/**
+* The core entry's `defineTree` over `Resource.make` definitions: each leaf's
+* `leaf` is the resource whose wire `type` is the level's name (the
+* discriminator value), and its domain columns are the resource's
+* `dbColumn`-annotated attributes. Every other check is the core one. Throws
+* `DerivationError` at module load for a leaf whose resource `type` isn't its
+* name, and for every structural fault `defineTree` names.
+*
+* @example
+* ```ts
+* import { dbColumn } from "@thomasfosterau/effect-drizzle-ext";
+* import { defineResourceTree } from "@thomasfosterau/effect-drizzle-ext/jsonapi";
+* import { Resource } from "@thomasfosterau/effect-jsonapi";
+* import * as Schema from "effect/Schema";
+*
+* const Book = Resource.make("book", {
+*   attributes: {
+*     pages: dbColumn(Schema.Finite, { column: "pages", pg: "integer", notNull: false }),
+*   },
+* });
+*
+* const tree = defineResourceTree({
+*   work: {
+*     columns: { title: dbColumn(Schema.String, { column: "title", pg: "text", notNull: true }) },
+*   },
+*   book: { parent: "work", leaf: Book },
+* });
+*
+* console.log(tree.leaves); // ["book"]
+* ```
+*/
+const defineResourceTree = defineResourceTreeFor();
+export { dbTable, dbTableFor, defineResourceTree, defineResourceTreeFor, readDbTable, resourceAttributeProjections, resourceColumnBounds, resourceColumns };
+
+//# sourceMappingURL=index.js.map

package/dist/jsonapi/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["coreDbTable","coreReadDbTable"],"sources":["../../src/jsonapi/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkGA,MAAa,mBAAmB,aAI9B,EAAE,SACA,EAAE,IAAI,SAAS,qBAAqB,QAAQ,IAAI,gBAC9C,OAAO,IACL,OAAO,gBAAgB,cAAc,cAAc,IAGlD,SAAS,IACZ,CACF,CACF;;;;;;;;;AAUF,MAAa,wBAAwB,aAAwD;CAG3F,MAAM,SAAS,SAAS,WAAW,QAAQ;CAC3C,OAAO,EAAE,SACP,EAAE,IAAI,gBAAgB,QAAQ,IAAI,QAAQ,SACxC,OAAO,IAAI,cAAc,OAAO,KAAK,IAAI,YAA0B;EAAE;EAAQ,GAAG;CAAO,EAAE,CAC3F,CACF;AACF;;AAoCA,MAAM,YAAY;;;;;;;AAQlB,MAAM,mBAAmB,QAAoB,UAG3C,OAAO,aAAa,OAAO,YAAY,MAA+B,CAAC,CAAC,CAAC,KAAK;;;;;;;;;;;;;AAchF,MAAa,gCACX,aAC+C;CAG/C,MAAM,SAAS,SAAS,WAAW,QAAQ;CAC3C,MAAM,UAAU,gBAAgB,QAAQ;CACxC,OAAO,IAAI,IAAI,EAAE,UAAU,MAAM,IAAI,CAAC,KAAK,aAAa;EACtD;EACA,UAAU,UAAU,WAAW,OAAO,GAAG;EACzC,UAAU,OAAO,OAAO,gBAAgB,QAAQ,IAAI,CAAC;EACrD,OAAO,OAAO,OAAO,gBAAgB,QAAQ,CAAC,CAAC,CAAC;EAChD,MAAM,OAAO,OAAO,gBAAgB,QAAQ,SAAS,GAAG,UAAU,MAAM;EACxE,QAAQ,OAAO,cAAc,QAAQ,IAAI,EAAE,MAAM;CACnD,EAAE;AACJ;;;;;;;;;AAsBA,MAAa,WACX,UACA,SACyBA,UAAY,UAAU,IAAI;;;;;;;;AASrD,MAAa,oBAGT,UACA,SAEAA,UAAY,UAAU,IAAI;;;;;;;AAQ9B,MAAa,eAAe,aAC1BC,cAAgB,QAAQ;;;;;;;;AAqD1B,MAAa,+BAEuC,SAChD,UAA+C,MAAM;CACnD,cAAc;CACd,cAAc,UAAU,SACtB,SAAS,SAAS,OACd,gBAAgB,QAAQ,IACxB,UACE,SAAS,KAAK,sBAAsB,SAAS,KAAK,wCACpD;AACR,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCL,MAAa,qBAEuB,sBAA4C"}

package/dist/query.d.ts

@@ -0,0 +1,111 @@
+import * as Schema from "effect/Schema";
+import { SQL, SQLWrapper } from "drizzle-orm";
+import * as Effect from "effect/Effect";
+import { EffectDrizzleQueryError } from "drizzle-orm/effect-core";
+/**
+ * The alias the unpaged total rides back on. Prefixed so it cannot collide
+ * with a projected column, and so a clash surfaces as a visible key rather
+ * than silently overwriting an attribute.
+ */
+export declare const TOTAL_COUNT_ALIAS = "__totalCount";
+/**
+ * The selection entry adding the unpaged total to a list query. Spread into
+ * a `.select({ … })` map alongside the columns the read already projects.
+ *
+ * `COUNT(*) OVER ()` is evaluated after `WHERE` and before `LIMIT`/`OFFSET`,
+ * so it rides back on every row of the page the query was already
+ * fetching — one round trip instead of a separate sequential `count(*)`
+ * query for data the first one can already carry.
+ *
+ * @example
+ * ```ts
+ * import { totalCountColumn } from "@thomasfosterau/effect-drizzle-ext/query";
+ * import { eq } from "drizzle-orm";
+ * import { integer, pgTable, QueryBuilder, text } from "drizzle-orm/pg-core";
+ *
+ * const article = pgTable("article", { id: integer().primaryKey(), title: text().notNull() });
+ *
+ * const page = new QueryBuilder()
+ *   .select({ id: article.id, title: article.title, ...totalCountColumn })
+ *   .from(article)
+ *   .where(eq(article.title, "Hello"))
+ *   .limit(20);
+ *
+ * console.log(page.toSQL().sql);
+ * // select "id", "title", (count(*) over ())::int from "article" where … limit $2
+ * ```
+ */
+export declare const totalCountColumn: {
+  readonly __totalCount: SQL<number>;
+};
+/** One page of a list read: the window's rows plus the unpaged total. */
+export interface Page<TResource> {
+  readonly items: readonly TResource[];
+  readonly totalCount: number;
+}
+/**
+ * Build a {@link Page} from rows selected with {@link totalCountColumn},
+ * mapping each row to its resource.
+ */
+export declare const pageOf: <TRow, TResource>(rows: readonly TRow[], toResource: (row: TRow) => TResource) => Page<TResource>;
+/**
+ * A {@link Page} over resources already mapped — for a list whose rows go
+ * through several transformation steps before becoming resources, where
+ * {@link pageOf}'s single mapper doesn't fit.
+ */
+export declare const pageWithTotal: <TResource>(items: readonly TResource[], rows: readonly unknown[]) => Page<TResource>;
+/**
+ * Combines a set of optional SQL filters into one `AND`-joined condition.
+ * Filters an operation didn't build (an optional query parameter left
+ * unset) are `undefined`; `and()` drops them, so passing every filter
+ * unconditionally is safe. With no defined filter at all, the result is
+ * `undefined` — the caller omits `.where(...)` entirely rather than
+ * applying a vacuous `WHERE true`.
+ */
+export declare const combineFilters: (...filters: ReadonlyArray<SQL | undefined>) => SQL | undefined;
+/**
+ * Builds a `limit` / `offset` input schema bounded by `options`, plus the
+ * two field schemas standalone (for a caller that validates them outside a
+ * struct, e.g. against a query-string parameter one at a time).
+ *
+ * `limit` accepts an integer in `(0, maxLimit]`; `offset` accepts an
+ * integer `>= 0`. Both keys are optional on input and decode to
+ * `defaultLimit` / `0` respectively when absent, via
+ * {@link Schema.withDecodingDefaultKey} — so `Input`'s decoded `Type` always
+ * carries both fields, while its `Encoded` (request) side may omit either.
+ */
+export declare const boundedPagination: (options: {
+  readonly maxLimit: number;
+  readonly defaultLimit: number;
+}) => {
+  Limit: Schema.Int;
+  Offset: Schema.Natural;
+  Input: Schema.Struct<{
+    readonly limit: Schema.withDecodingDefaultKey<Schema.Int, never>;
+    readonly offset: Schema.withDecodingDefaultKey<Schema.Natural, never>;
+  }>;
+};
+/** The shape {@link boundedPagination} returns. */
+export type BoundedPagination = ReturnType<typeof boundedPagination>;
+/**
+ * Rows-normalising wrapper for raw-SQL reads (`db.execute<T>`).
+ *
+ * drizzle-orm's effect-postgres driver types `db.execute<T>` as
+ * `readonly T[]`, but depending on the SQL client bound underneath, the
+ * query can resolve in "raw" mode with no row mapper, handing back the
+ * full driver result object (`{ rows, rowCount, … }`) instead of a bare
+ * array — so `.map` on the yielded value throws `rows.map is not a
+ * function`. Every raw-SQL read should go through this helper instead of
+ * `db.execute` directly: it accepts both shapes — array in → array out —
+ * so which shape the underlying driver actually returns changes nothing
+ * for call sites. Write-only executes (INSERT/DDL) that never read rows
+ * may keep calling `db.execute` directly.
+ *
+ * `db` is typed to the narrowest shape this needs (`execute` alone),
+ * widened so both a real Effect-Drizzle database and a stub client in a
+ * test satisfy it without a cast.
+ */
+export declare const executeRows: <T extends Record<string, unknown>>(db: {
+  readonly execute: (query: SQLWrapper | string) => Effect.Effect<unknown, EffectDrizzleQueryError>;
+}, query: SQLWrapper | string) => Effect.Effect<readonly T[], EffectDrizzleQueryError>;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","names":[],"sources":["../src/query.ts"],"mappings":";;;;;;;;;qBAuBa;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA6BA;;;;iBAKI,KAAK;WACX,gBAAgB;WAChB;;;;;;qBA0BE,SAAU,MAAM,WAAS,eACrB,QAAM,aACR,KAAK,SAAS,cAC1B,KAAK;;;;;;qBAUK,gBAAiB,WAAS,gBACrB,aAAW,6BAE1B,KAAK;;;;;;;;;qBAcK,oBAAc,SAAgB,cAAc,qBAAmB;;;;;;;;;;;;qBAe/D,oBAAiB;WACnB;WACA;;;;;;;;;;YAeC,oBAAoB,kBAAkB;;;;;;;;;;;;;;;;;;;qBAoBrC,cAAe,UAAU,yBAAuB;WAEhD,UACP,OAAO,wBACJ,OAAO,gBAAgB;GAC7B,OACM,wBACN,OAAO,gBAAgB,KAAK"}

package/dist/query.js

@@ -0,0 +1,142 @@
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+import { and, sql } from "drizzle-orm";
+import * as Effect from "effect/Effect";
+// src/query.ts
+/**
+* @copyright Thomas Foster
+*
+* List-read helpers: the unpaged-total window column and the {@link Page}
+* shape every list read returns, a variadic AND filter combinator, a bounded
+* limit/offset input schema, and the rows-normalising wrapper over a raw-SQL
+* `execute` that papers over a driver mismatch between typed and runtime
+* `db.execute` shapes.
+*
+* @module query
+*/
+/**
+* The alias the unpaged total rides back on. Prefixed so it cannot collide
+* with a projected column, and so a clash surfaces as a visible key rather
+* than silently overwriting an attribute.
+*/
+const TOTAL_COUNT_ALIAS = "__totalCount";
+/**
+* The selection entry adding the unpaged total to a list query. Spread into
+* a `.select({ … })` map alongside the columns the read already projects.
+*
+* `COUNT(*) OVER ()` is evaluated after `WHERE` and before `LIMIT`/`OFFSET`,
+* so it rides back on every row of the page the query was already
+* fetching — one round trip instead of a separate sequential `count(*)`
+* query for data the first one can already carry.
+*
+* @example
+* ```ts
+* import { totalCountColumn } from "@thomasfosterau/effect-drizzle-ext/query";
+* import { eq } from "drizzle-orm";
+* import { integer, pgTable, QueryBuilder, text } from "drizzle-orm/pg-core";
+*
+* const article = pgTable("article", { id: integer().primaryKey(), title: text().notNull() });
+*
+* const page = new QueryBuilder()
+*   .select({ id: article.id, title: article.title, ...totalCountColumn })
+*   .from(article)
+*   .where(eq(article.title, "Hello"))
+*   .limit(20);
+*
+* console.log(page.toSQL().sql);
+* // select "id", "title", (count(*) over ())::int from "article" where … limit $2
+* ```
+*/
+const totalCountColumn = { [TOTAL_COUNT_ALIAS]: sql`(count(*) over ())::int` };
+/**
+* Reads the total off the first row — every row carries the same value,
+* since the window is evaluated over the whole matching set. Falls back to
+* `0` for an empty page: a window function over zero rows returns nothing,
+* so **an empty page reports `totalCount: 0`** — exact when nothing
+* matches, and wrong only when a caller paged past the end of a non-empty
+* collection. That case is self-describing (`items: []` says it) and
+* self-correcting (paging back gives the true total); the alternative is a
+* second query on every list read. The alias is added by
+* {@link totalCountColumn} outside the row's declared type, so it is
+* recovered by an `in` narrowing rather than a cast.
+*/
+const totalFrom = (rows) => {
+	const first = rows[0];
+	return Predicate.isObjectOrArray(first) && "__totalCount" in first ? Number(first[TOTAL_COUNT_ALIAS]) : 0;
+};
+/**
+* Build a {@link Page} from rows selected with {@link totalCountColumn},
+* mapping each row to its resource.
+*/
+const pageOf = (rows, toResource) => ({
+	items: rows.map(toResource),
+	totalCount: totalFrom(rows)
+});
+/**
+* A {@link Page} over resources already mapped — for a list whose rows go
+* through several transformation steps before becoming resources, where
+* {@link pageOf}'s single mapper doesn't fit.
+*/
+const pageWithTotal = (items, rows) => ({
+	items,
+	totalCount: totalFrom(rows)
+});
+/**
+* Combines a set of optional SQL filters into one `AND`-joined condition.
+* Filters an operation didn't build (an optional query parameter left
+* unset) are `undefined`; `and()` drops them, so passing every filter
+* unconditionally is safe. With no defined filter at all, the result is
+* `undefined` — the caller omits `.where(...)` entirely rather than
+* applying a vacuous `WHERE true`.
+*/
+const combineFilters = (...filters) => and(...filters);
+/**
+* Builds a `limit` / `offset` input schema bounded by `options`, plus the
+* two field schemas standalone (for a caller that validates them outside a
+* struct, e.g. against a query-string parameter one at a time).
+*
+* `limit` accepts an integer in `(0, maxLimit]`; `offset` accepts an
+* integer `>= 0`. Both keys are optional on input and decode to
+* `defaultLimit` / `0` respectively when absent, via
+* {@link Schema.withDecodingDefaultKey} — so `Input`'s decoded `Type` always
+* carries both fields, while its `Encoded` (request) side may omit either.
+*/
+const boundedPagination = (options) => {
+	const { maxLimit, defaultLimit } = options;
+	const Limit = Schema.Int.pipe(Schema.check(Schema.isBetween({
+		minimum: 0,
+		maximum: maxLimit,
+		exclusiveMinimum: true
+	})));
+	const Offset = Schema.Natural;
+	return {
+		Limit,
+		Offset,
+		Input: Schema.Struct({
+			limit: Limit.pipe(Schema.withDecodingDefaultKey(Effect.succeed(defaultLimit))),
+			offset: Offset.pipe(Schema.withDecodingDefaultKey(Effect.succeed(0)))
+		})
+	};
+};
+/**
+* Rows-normalising wrapper for raw-SQL reads (`db.execute<T>`).
+*
+* drizzle-orm's effect-postgres driver types `db.execute<T>` as
+* `readonly T[]`, but depending on the SQL client bound underneath, the
+* query can resolve in "raw" mode with no row mapper, handing back the
+* full driver result object (`{ rows, rowCount, … }`) instead of a bare
+* array — so `.map` on the yielded value throws `rows.map is not a
+* function`. Every raw-SQL read should go through this helper instead of
+* `db.execute` directly: it accepts both shapes — array in → array out —
+* so which shape the underlying driver actually returns changes nothing
+* for call sites. Write-only executes (INSERT/DDL) that never read rows
+* may keep calling `db.execute` directly.
+*
+* `db` is typed to the narrowest shape this needs (`execute` alone),
+* widened so both a real Effect-Drizzle database and a stub client in a
+* test satisfy it without a cast.
+*/
+const executeRows = (db, query) => Effect.map(db.execute(query), (result) => Array.isArray(result) ? result : result.rows ?? []);
+export { TOTAL_COUNT_ALIAS, boundedPagination, combineFilters, executeRows, pageOf, pageWithTotal, totalCountColumn };
+
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","names":[],"sources":["../src/query.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAuBA,MAAa,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BjC,MAAa,mBAAmB,GAC7B,oBAAoB,GAAW,0BAClC;;;;;;;;;;;;;AAoBA,MAAM,aAAa,SAAqC;CACtD,MAAM,QAAQ,KAAK;CACnB,OAAO,UAAU,gBAAgB,KAAK,KAAA,kBAA0B,QAC5D,OAAO,MAAM,kBAAkB,IAC/B;AACN;;;;;AAMA,MAAa,UACX,MACA,gBACqB;CACrB,OAAO,KAAK,IAAI,UAAU;CAC1B,YAAY,UAAU,IAAI;AAC5B;;;;;;AAOA,MAAa,iBACX,OACA,UACqB;CACrB;CACA,YAAY,UAAU,IAAI;AAC5B;;;;;;;;;AAWA,MAAa,kBAAkB,GAAG,YAChC,IAAI,GAAG,OAAO;;;;;;;;;;;;AAchB,MAAa,qBAAqB,YAG5B;CACJ,MAAM,EAAE,UAAU,iBAAiB;CACnC,MAAM,QAAQ,OAAO,IAAI,KACvB,OAAO,MAAM,OAAO,UAAU;EAAE,SAAS;EAAG,SAAS;EAAU,kBAAkB;CAAK,CAAC,CAAC,CAC1F;CACA,MAAM,SAAS,OAAO;CAKtB,OAAO;EAAE;EAAO;EAAQ,OAJV,OAAO,OAAO;GAC1B,OAAO,MAAM,KAAK,OAAO,uBAAuB,OAAO,QAAQ,YAAY,CAAC,CAAC;GAC7E,QAAQ,OAAO,KAAK,OAAO,uBAAuB,OAAO,QAAQ,CAAC,CAAC,CAAC;EACtE,CAC4B;CAAE;AAChC;;;;;;;;;;;;;;;;;;;AAuBA,MAAa,eACX,IAKA,UAEA,OAAO,IAAI,GAAG,QAAQ,KAAK,IAAI,WAI7B,MAAM,QAAQ,MAAM,IACf,SACC,OAAmC,QAAQ,CAAC,CACpD"}

package/dist/references.d.ts

@@ -0,0 +1,38 @@
+import { o as DbColumnReference } from "./index-CFhgcF4N.js";
+import { AnyPgColumn, PgTable } from "drizzle-orm/pg-core";
+/**
+ * A name-keyed registry of FK-reference targets, plus the lazy resolver the
+ * derivation's `resolveReference` hook expects.
+ *
+ * The invariant is the laziness: `resolve` never touches the registry, so a
+ * reference may be resolved before its target table module has loaded;
+ * **forcing** the returned thunk is what reads the registry, and that happens
+ * only when Drizzle materialises the foreign key.
+ */
+export interface ReferenceRegistry {
+  /**
+   * Register a table as a possible FK-reference target, keyed by its SQL table
+   * name (matching a `references.table` annotation). Idempotent; call it once,
+   * right after the target table is defined, in the table module that owns it.
+   */
+  readonly register: (table: PgTable) => void;
+  /**
+   * Resolve a `dbColumn` `references` annotation to the target Drizzle column,
+   * as the lazy thunk `.references()` consumes. Wire it into the derivation's
+   * {@link DeriveOptions.resolveReference}; it is invoked only when a derived
+   * column declares a reference, so leaves with no FK annotations never touch
+   * the registry.
+   *
+   * Forcing the thunk against an unregistered table, or against a table with
+   * no such column, throws {@link DerivationError} — a schema-definition
+   * programmer error surfaced the first time Drizzle forces the thunk, not a
+   * runtime condition.
+   */
+  readonly resolve: (reference: DbColumnReference) => () => AnyPgColumn;
+}
+/**
+ * Build a fresh {@link ReferenceRegistry}. Each call owns its own name → table
+ * map, so independent schemas never resolve into each other.
+ */
+export declare const makeReferenceRegistry: () => ReferenceRegistry;
+//# sourceMappingURL=references.d.ts.map

package/dist/references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"references.d.ts","names":[],"sources":["../src/references.ts"],"mappings":";;;;;;;;;;;iBAgDiB;;;;;;WAMN,WAAW,OAAO;;;;;;;;;;;;;WAalB,UAAU,WAAW,4BAA4B;;;;;;qBAO/C,6BAA4B"}