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

package/src/jsonapi/derive.ts

@@ -0,0 +1,74 @@
+/**
+ * @copyright Thomas Foster
+ *
+ * **The JSON:API resource projection of the derivation entry (Drizzle).**
+ *
+ * `./jsonapi` reads a `Resource.make` definition's `dbColumn` annotations;
+ * `./derive` turns db-column metadata into Drizzle column builders. This entry
+ * is the join: the resource-shaped signatures the consuming applications'
+ * table factories call, implemented by handing `resourceColumns` /
+ * `resourceColumnBounds` to the generic interpreter. No semantics of its own —
+ * failure modes, CHECK naming and the `resolveReference` seam are all
+ * `./derive`'s, and its {@link DerivationError} is what a misdeclared resource
+ * throws at module load.
+ *
+ * @module jsonapi/derive
+ */
+
+import type { ExtraConfigColumn, PgTableExtraConfigValue } from "drizzle-orm/pg-core";
+import {
+  deriveCheckConstraintsFrom,
+  // oxlint-disable-next-line effect/no-service-constructor-imports -- `makeDeriveColumns` is a plain factory over a builder registry, not an Effect service constructor; the rule keys on the `make*` name.
+  makeDeriveColumns,
+  type ColumnBuilders,
+  type DerivedColumns,
+  type DeriveOptions,
+} from "../derive.ts";
+import {
+  resourceColumnBounds,
+  resourceColumns,
+  type AnyResource,
+  type ResourceColumnsMetaOf,
+} from "./index.ts";
+
+/**
+ * The Drizzle column builders a `Resource.make` definition's annotated
+ * attributes produce against registry `B`, keyed and typed per attribute.
+ */
+export type DerivedResourceColumns<
+  R extends AnyResource,
+  B extends ColumnBuilders,
+> = DerivedColumns<ResourceColumnsMetaOf<R>, B>;
+
+/**
+ * Build a `deriveResourceColumns` bound to a specific builder registry. The
+ * returned function interprets a `Resource.make` definition's per-attribute
+ * `dbColumn` annotations into the Drizzle column builders a table factory's
+ * `columns` expects.
+ */
+export const makeDeriveResourceColumns = <B extends ColumnBuilders>(
+  builders: B,
+  options: DeriveOptions = {},
+): (<R extends AnyResource>(resource: R) => DerivedResourceColumns<R, B>) => {
+  const derive = makeDeriveColumns(builders, options);
+  return <R extends AnyResource>(resource: R): DerivedResourceColumns<R, B> =>
+    // SAFETY: `resourceColumns` projects exactly the annotated attributes
+    // `ResourceColumnsMetaOf` keys, so the derived map is the one it describes.
+    derive.fromMeta(resourceColumns(resource)) as DerivedResourceColumns<R, B>;
+};
+
+/**
+ * Derive the SQL `CHECK` constraints a resource definition's numeric-bound
+ * checks imply, named `${tableName}_${column}_${suffix}` unless the annotation
+ * pins a `checkName`, and guarded with `col IS NULL OR …` for a nullable
+ * column. Returns a callback shaped for a table factory's `extraConstraints`
+ * seam; a bounded attribute whose column is absent from the table throws
+ * {@link DerivationError}.
+ *
+ * The projection is deferred to the returned callback, so this composes inside
+ * a `pgTable(...)` call whose columns are still being assembled.
+ */
+export const deriveCheckConstraints =
+  (resource: AnyResource, tableName: string) =>
+  (table: Record<string, ExtraConfigColumn>): PgTableExtraConfigValue[] =>
+    deriveCheckConstraintsFrom(resourceColumnBounds(resource), tableName)(table);

package/src/jsonapi/index.ts

@@ -0,0 +1,355 @@
+/**
+ * @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
+ */
+
+import { Resource } from "@thomasfosterau/effect-jsonapi";
+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 {
+  dbTable as coreDbTable,
+  readDbTable as coreReadDbTable,
+  numericBounds,
+  DB_COLUMN_KEY,
+  type ColumnBounds,
+  type DbColumn,
+  type TableAnnotated as CoreTableAnnotated,
+  type DbTableOf as CoreDbTableOf,
+  type DbTable,
+  type TableMeta,
+  type UnwrapColumn,
+  type FieldColumnsMetaOf,
+  fieldColumns,
+} from "../index.ts";
+import { buildTree, treeError, type LevelSpec, type Tree } from "../tree.ts";
+
+export type { DbTable, TableMeta };
+
+/**
+ * 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 const resourceColumns = (resource: AnyResource): Record<string, DbColumn> =>
+  // `Resource.attributeAnnotations` (an optional peer, outside this workspace)
+  // reports an attribute with no annotations as a literal `undefined` entry;
+  // the foreign `undefined` becomes an `Option` on the same expression.
+  R.getSomes(
+    R.map(Resource.attributeAnnotations(resource), (annotations) =>
+      Option.map(
+        Option.fromUndefinedOr(annotations?.[DB_COLUMN_KEY]),
+        // SAFETY: DB_COLUMN_KEY is namespaced to this package and only
+        // `dbColumn` / `dbColumnFor` write it, always with a `DbColumn` value.
+        (meta) => meta as 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 const resourceColumnBounds = (resource: AnyResource): Record<string, ColumnBounds> => {
+  // SAFETY: `Resource.attributes` returns the resource object's
+  // `Schema.Struct.Fields`; every value is a schema.
+  const fields = Resource.attributes(resource) as Record<string, Schema.Constraint>;
+  return R.getSomes(
+    R.map(resourceColumns(resource), (column, name) =>
+      Option.map(numericBounds(fields[name]), (bounds): ColumnBounds => ({ column, ...bounds })),
+    ),
+  );
+};
+
+// ── Resource projection shapes ────────────────────────────────────────
+
+/**
+ * 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>;
+}
+
+/** 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: Schema.Top, input: Schema.Json): Option.Option<unknown> =>
+  // SAFETY: an attribute schema's decoding needs no services (a resource's
+  // attributes are plain codecs), which `Schema.Top` cannot express.
+  Schema.decodeOption(Schema.toCodecJson(schema as Schema.Codec<unknown>))(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}'.
+ */
+export const resourceAttributeProjections = (
+  resource: AnyResource,
+): ReadonlyArray<ResourceAttributeProjection> => {
+  // SAFETY: `Resource.attributes` returns the resource object's
+  // `Schema.Struct.Fields`; every value is a schema.
+  const fields = Resource.attributes(resource) as Record<string, Schema.Top>;
+  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),
+  }));
+};
+
+// ── Table-level annotation, narrowed to resources ─────────────────────
+
+/**
+ * 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> = CoreTableAnnotated<R, M>;
+
+/** Recovers the db-table metadata phantom from a resource, or `never`. */
+export type DbTableOf<R> = CoreDbTableOf<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 const dbTable = <R extends AnyResource, const M extends TableMeta>(
+  resource: R,
+  meta: M,
+): TableAnnotated<R, M> => coreDbTable(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.
+ */
+export const dbTableFor =
+  <Level extends string>() =>
+  <R extends AnyResource, const M extends DbTable<Level>>(
+    resource: R,
+    meta: M,
+  ): TableAnnotated<R, M> =>
+    coreDbTable(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.
+ */
+export const readDbTable = (resource: AnyResource): Option.Option<TableMeta> =>
+  coreReadDbTable(resource);
+
+// ── Tree ──────────────────────────────────────────────────────────────
+
+/** 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 const defineResourceTreeFor =
+  <Ext extends object>() =>
+  <const S extends CheckedResourceTreeSpec<S, Ext>>(spec: S): Tree<S, ResourceTreeMeta<S>> =>
+    buildTree<S, AnyResource, ResourceTreeMeta<S>>(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"]
+ * ```
+ */
+export const defineResourceTree: <const S extends CheckedResourceTreeSpec<S, Record<never, never>>>(
+  spec: S,
+) => Tree<S, ResourceTreeMeta<S>> = defineResourceTreeFor<Record<never, never>>();

package/src/query.ts

@@ -0,0 +1,183 @@
+/**
+ * @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
+ */
+import { and, sql } from "drizzle-orm";
+import type { SQL, SQLWrapper } from "drizzle-orm";
+import type { EffectDrizzleQueryError } from "drizzle-orm/effect-core";
+import * as Effect from "effect/Effect";
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+
+/**
+ * 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 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 const totalCountColumn = {
+  [TOTAL_COUNT_ALIAS]: sql<number>`(count(*) over ())::int`,
+} as const;
+
+/** 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;
+}
+
+/**
+ * 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: readonly unknown[]): number => {
+  const first = rows[0];
+  return Predicate.isObjectOrArray(first) && TOTAL_COUNT_ALIAS in first
+    ? Number(first[TOTAL_COUNT_ALIAS])
+    : 0;
+};
+
+/**
+ * Build a {@link Page} from rows selected with {@link totalCountColumn},
+ * mapping each row to its resource.
+ */
+export const pageOf = <TRow, TResource>(
+  rows: readonly TRow[],
+  toResource: (row: TRow) => TResource,
+): Page<TResource> => ({
+  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.
+ */
+export const pageWithTotal = <TResource>(
+  items: readonly TResource[],
+  rows: readonly unknown[],
+): Page<TResource> => ({
+  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`.
+ */
+/* oxlint-disable effect/prefer-option-over-null -- Drizzle-facing: mirrors drizzle-orm's own `and()` signature, which callers pass straight into `.where(...)` */
+export const combineFilters = (...filters: ReadonlyArray<SQL | undefined>): SQL | undefined =>
+  and(...filters);
+/* oxlint-enable effect/prefer-option-over-null */
+
+/**
+ * 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 const boundedPagination = (options: {
+  readonly maxLimit: number;
+  readonly defaultLimit: number;
+}) => {
+  const { maxLimit, defaultLimit } = options;
+  const Limit = Schema.Int.pipe(
+    Schema.check(Schema.isBetween({ minimum: 0, maximum: maxLimit, exclusiveMinimum: true })),
+  );
+  const Offset = Schema.Natural;
+  const Input = Schema.Struct({
+    limit: Limit.pipe(Schema.withDecodingDefaultKey(Effect.succeed(defaultLimit))),
+    offset: Offset.pipe(Schema.withDecodingDefaultKey(Effect.succeed(0))),
+  });
+  return { Limit, Offset, Input };
+};
+
+/** 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 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> =>
+  Effect.map(db.execute(query), (result) =>
+    // SAFETY: `T` is the row type the caller asserts its query selects (the
+    // driver hands rows back untyped); a non-array result is the driver's
+    // result object, whose `rows` holds those rows when present.
+    Array.isArray(result)
+      ? (result as readonly T[])
+      : ((result as { rows?: readonly T[] }).rows ?? []),
+  );