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

package/dist/versioned-chain.js

@@ -0,0 +1,298 @@
+import { m as treeError } from "./src-CBeuhy5b.js";
+import { makeDeriveColumns } from "./derive.js";
+import { enumCheck, makeDiscriminatorConstraints } from "./constraints.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 { and, eq, getTableName, max } from "drizzle-orm";
+import { alias, bigint, foreignKey, primaryKey, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import * as Order from "effect/Order";
+// src/versioned-chain.ts
+/**
+* @copyright Thomas Foster
+*
+* **Effect Schema → Drizzle derivation: the opt-in versioned-chain interpreter
+* (Drizzle).**
+*
+* The generic "tree of levels, each a stable + version table pair, joined up a
+* composite `(id, version)` FK chain to a root, with fail-closed current-version
+* views" structure — the shape a temporal-versioned node hierarchy takes. Two
+* factories, each parameterised over the bits a specific hierarchy pins:
+*
+* - {@link makeSubtypeTables} — the stable + version table-pair builder. Emits
+*   the structural plumbing (stable `id` → parent FK, version `id` / `version`
+*   columns, the `(id, version)` primary key, and the `(id, version)` →
+*   parent-version FK) while the domain columns stay authored per leaf. The
+*   discriminator constraints (a `type` column arced up the tree) are injected,
+*   so a hierarchy without a discriminator, or with different discriminator
+*   semantics, configures its own.
+*
+* - {@link makeCurrentVersionView} — the uniform fail-closed current-version
+*   view. Resolves each node's current version from a **root version table**,
+*   then INNER JOINs the leaf (and any intermediate version tables) at exactly
+*   that `(id, version)`; a node whose root version advanced past its leaf (a
+*   partial-chain tombstone) yields **no row** — the view fails closed rather
+*   than surfacing a stale older leaf row. The root version table and the
+*   always-joined identity row (plus the columns it merges into every view) are
+*   injected.
+*
+* Depends on Drizzle. The annotation layer ({@link .}) stays free of any
+* versioning opinion — this interpreter is opt-in.
+*
+* @module versioned-chain
+*/
+/**
+* Build a `defineSubtypeTables` bound to a discriminator hook. The hook turns a
+* leaf's `discriminator` declaration into the stable-table constraints that
+* enforce it (e.g. a `UNIQUE(id, type)` + composite `(id, type)` → parent FK +
+* per-level CHECK trio); a hierarchy without a discriminator passes a hook that
+* is simply never invoked (its leaves omit `discriminator`).
+*
+* The returned builder emits a regular subtype's `{ stable, version }` table
+* pair with the composite-`(id, version)` FK chain to its parent branch.
+*/
+const makeSubtypeTables = (applyDiscriminator) => (schema, { name, parentId, parentVersion, columns, versionDefault, extraConstraints, discriminator }) => {
+	const stableColumns = {
+		id: uuid("id").primaryKey().references(() => parentId, { onDelete: "cascade" }),
+		type: discriminator ? text("type").notNull() : text("type")
+	};
+	const stable = discriminator ? schema.table(name, stableColumns, (table) => applyDiscriminator(name, {
+		id: table.id,
+		type: table.type
+	}, discriminator)) : schema.table(name, stableColumns);
+	return {
+		stable,
+		version: schema.table(`${name}_version`, {
+			id: uuid("id").notNull().references(() => stable.id, {
+				onUpdate: "cascade",
+				onDelete: "cascade"
+			}),
+			version: versionDefault === void 0 ? bigint("version", { mode: "bigint" }).notNull() : bigint("version", { mode: "bigint" }).notNull().default(versionDefault),
+			...columns
+		}, (table) => {
+			const constraints = [primaryKey({
+				name: `${name}_version_pkey`,
+				columns: [table.id, table.version]
+			}), foreignKey({
+				name: `${name}_version_${getTableName(parentVersion)}_fk`,
+				columns: [table.id, table.version],
+				foreignColumns: [parentVersion.id, parentVersion.version]
+			})];
+			return extraConstraints ? [...constraints, ...extraConstraints(table)] : constraints;
+		})
+	};
+};
+/** Whether a `merge` is the function form, which receives the birth-row alias. */
+const isMergeFunction = (merge) => Predicate.isFunction(merge);
+/**
+* Build a `currentVersionView` bound to a root version table + identity row.
+* `schema.view(name).as(...)` with the uniform join chain generated from
+* {@link CurrentVersionViewConfig}.
+*
+* The joins only widen the `FROM` clause; they never change the explicit
+* `columns` selection, so the view's `$inferSelect` is derived directly from
+* `columns` + the injected `merge` via {@link CurrentVersionViewResult}. The
+* runtime query is assembled untyped (the chain alternates join shapes), which
+* is why the return type is asserted rather than inferred: letting `.as()` infer
+* the selection through `.from(current)` collapses every column to `never`.
+*
+* Currency is resolved from `rootVersion` (fail-closed): a `MAX(version)`
+* sub-select drives the FROM, and the leaf / intermediate version tables INNER
+* JOIN at that current `(id, version)`. One row per node (the sub-select groups
+* by id) landing on unique `(id, version)` PKs, so no `DISTINCT ON` / `ORDER BY`
+* is needed. A leaf missing at the current version drops out of the INNER JOIN —
+* the view yields no row.
+*/
+const makeCurrentVersionView = ({ rootVersion, identity, merge }) => (schema, name, { leaf, through = [], optional = [], on = [], columns }) => {
+	const rootTable = rootVersion;
+	return schema.view(name).as((qb) => {
+		const current = qb.select({
+			id: rootVersion.id,
+			version: max(rootVersion.version).as("current_version")
+		}).from(rootTable).groupBy(rootVersion.id).as("current_version");
+		const versionZero = isMergeFunction(merge) ? alias(rootVersion, "version_zero") : void 0;
+		const mergeColumns = isMergeFunction(merge) ? merge(versionZero) : merge;
+		let q = qb.select({
+			...columns,
+			...mergeColumns
+		}).from(current);
+		q = q.innerJoin(leaf, and(eq(current.id, leaf.id), eq(current.version, leaf.version)));
+		q = Arr.reduce(through, q, (acc, t) => acc.innerJoin(t, and(eq(current.id, t.id), eq(current.version, t.version))));
+		q = Arr.reduce(optional, q, (acc, t) => acc.leftJoin(t, and(eq(current.id, t.id), eq(current.version, t.version))));
+		q = Arr.reduce(on, q, (acc, t) => acc.innerJoin(t, eq(current.id, t.id)));
+		q = q.innerJoin(identity, eq(current.id, identity.id));
+		q = q.innerJoin(rootVersion, and(eq(current.id, rootVersion.id), eq(current.version, rootVersion.version)));
+		if (versionZero) q = q.innerJoin(versionZero, and(eq(current.id, versionZero.id), eq(versionZero.version, 0n)));
+		return q;
+	});
+};
+/**
+* The `createdAt` / `updatedAt` pair of a current-version row: `updatedAt` is
+* the current version's `timestamp`; `createdAt` is the birth row's own
+* timestamp where the view merges one in (a function `merge` of
+* {@link makeCurrentVersionView}), and falls back to `updatedAt` for a view
+* that carries none (website #1223).
+*/
+const versionTimestamps = (row) => ({
+	createdAt: row.createdAt ?? row.timestamp,
+	updatedAt: row.timestamp
+});
+/**
+* An injected extras map, or `{}` when the member is absent.
+*
+* SAFETY: `T` is inferred from this very member, so it is a real map when the
+* member is present and defaults to `{}` (the `IE` / `VE` defaults of
+* {@link makeTreeTables}) exactly when it is absent.
+*/
+const columnsOrEmpty = (columns) => columns ?? {};
+/** The `action` values the root version table admits. */
+const VERSION_ACTIONS = [
+	"create",
+	"update",
+	"delete"
+];
+/**
+* Derive every table and constraint of a tree in one call: the root identity
+* table (`id`, `type`, extras; `UNIQUE (id, type)`) and root version table
+* (`(id, version)` key, `action` checked to `create` / `update` / `delete`,
+* `timestamp`, the actor, extras); then per level a stable table (`id` →
+* parent `id`, cascade delete; `type` NOT NULL with `UNIQUE (id, type)`,
+* `(id, type)` → parent `(id, type)`, and a CHECK narrowing `type` to the
+* level's subtree leaves) and a version table (`(id, version)` key and
+* `(id, version)` → parent version FK) carrying the level's level columns,
+* its leaf's columns (both derived through `builders`) and its hook columns.
+* A fact-scoped level's version table is a spine, with one
+* `${level}_${column}` fact table per own column, keyed and foreign-keyed on
+* `(id, version)` (cascade delete).
+*
+* Constraint names are canonical (`${table}_pkey`, `${table}_${parent}_fk`,
+* `${level}_id_type_unique` / `_fk` / `_type_valid`); no version table carries
+* `action`. Column, constraint and CHECK value order follow declaration order,
+* so the same tree always generates the same migration. Throws
+* `DerivationError` at module load for a column kind `builders` lacks or an
+* unresolvable reference.
+*
+* Every table is typed from the tree's column phantom. The one type-erasure
+* seam is inside: the level and fact records are assembled from the runtime
+* tree, then named by {@link TreeTables}.
+*
+* @example
+* ```ts
+* import { dbColumn, defineTree } from "@thomasfosterau/effect-drizzle-ext";
+* import { makeTreeTables } from "@thomasfosterau/effect-drizzle-ext/versioned-chain";
+* import { getTableConfig, integer, pgSchema, text } from "drizzle-orm/pg-core";
+* import * as Schema from "effect/Schema";
+*
+* const tree = defineTree({
+*   work: {
+*     columns: { title: dbColumn(Schema.String, { column: "title", pg: "text", notNull: true }) },
+*   },
+*   book: {
+*     parent: "work",
+*     leaf: { pages: dbColumn(Schema.Finite, { column: "pages", pg: "integer", notNull: false }) },
+*   },
+* });
+*
+* const tables = makeTreeTables(tree, {
+*   schema: pgSchema("catalogue"),
+*   builders: { text: (c: string) => text(c), integer: (c: string) => integer(c) },
+* });
+*
+* console.log(getTableConfig(tables.levels.book.version).columns.map((c) => c.name));
+* // ["id", "version", "pages"]
+* ```
+*/
+const makeTreeTables = (tree, config) => {
+	const { schema } = config;
+	const derive = makeDeriveColumns(config.builders, { resolveReference: config.resolveReference });
+	const identityName = config.root?.identity ?? "node";
+	const versionName = config.root?.version ?? `${identityName}_version`;
+	const toolkit = makeDiscriminatorConstraints({ leaves: (level) => Option.getOrElse(Option.map(Arr.findFirst(tree.levels, (candidate) => candidate.name === level), (found) => found.subtreeLeaves), () => []) });
+	const identity = schema.table(identityName, {
+		id: uuid("id").primaryKey(),
+		type: text("type").notNull(),
+		...columnsOrEmpty(config.root?.identityColumns)
+	}, (table) => [toolkit.typeUnique(identityName, {
+		id: table.id,
+		type: table.type
+	})]);
+	const version = schema.table(versionName, {
+		id: uuid("id").notNull().references(() => identity.id, { onDelete: "cascade" }),
+		version: bigint("version", { mode: "bigint" }).notNull(),
+		action: text("action").notNull(),
+		timestamp: timestamp("timestamp", { withTimezone: true }).notNull().defaultNow(),
+		actor: text(config.root?.actorColumn ?? "actor"),
+		...columnsOrEmpty(config.root?.versionColumns)
+	}, (table) => [primaryKey({
+		name: `${versionName}_pkey`,
+		columns: [table.id, table.version]
+	}), enumCheck(`${versionName}_action_valid`, table.action, VERSION_ACTIONS)]);
+	const hooksOf = (name) => config.levels?.[name] ?? {};
+	const subtype = makeSubtypeTables((level, stable, parent) => toolkit.typeConstraints(level, stable, parent.stable, { refinable: parent.refinable }));
+	const builtLevel = (built, name) => Option.getOrElse(R.get(built, name), () => treeError(`level "${name}" was read before it was built`));
+	const buildLevel = (built, level) => {
+		const parent = Option.match(level.parent, {
+			onNone: () => ({
+				stable: identity,
+				version
+			}),
+			onSome: (name) => builtLevel(built, name).tables
+		});
+		const hooks = hooksOf(level.name);
+		const metas = {
+			...level.levelColumns,
+			...level.leafColumns
+		};
+		const own = derive.fromMeta(metas);
+		const factScoped = level.kind === "fact-scoped";
+		const tables = subtype(schema, {
+			name: level.name,
+			parentId: parent.stable.id,
+			parentVersion: parent.version,
+			columns: factScoped ? { ...hooks.columns } : {
+				...own,
+				...hooks.columns
+			},
+			extraConstraints: hooks.extraConstraints,
+			discriminator: {
+				stable: parent.stable,
+				refinable: Arr.some([...level.ancestors, level.name], (name) => hooksOf(name).refinable === true)
+			}
+		});
+		const factOf = ([key, meta], builder) => {
+			const name = `${level.name}_${meta.column}`;
+			return [key, schema.table(name, {
+				id: uuid("id").notNull(),
+				version: bigint("version", { mode: "bigint" }).notNull(),
+				[key]: builder
+			}, (table) => [primaryKey({
+				name: `${name}_pkey`,
+				columns: [table.id, table.version]
+			}), foreignKey({
+				name: `${name}_${getTableName(tables.version)}_fk`,
+				columns: [table.id, table.version],
+				foreignColumns: [tables.version.id, tables.version.version]
+			}).onDelete("cascade")])];
+		};
+		return {
+			tables,
+			facts: factScoped ? R.fromEntries(Arr.map(Arr.zip(R.toEntries(metas), R.values(own)), ([entry, builder]) => factOf(entry, builder))) : {}
+		};
+	};
+	const built = Arr.reduce(Arr.sort(tree.levels, Order.mapInput(Order.Number, (level) => level.ancestors.length)), R.empty(), (acc, level) => ({
+		...acc,
+		[level.name]: buildLevel(acc, level)
+	}));
+	return {
+		root: {
+			identity,
+			version
+		},
+		levels: R.fromEntries(Arr.map(tree.names, (name) => [name, builtLevel(built, name).tables])),
+		facts: R.fromEntries(Arr.map(tree.names, (name) => [name, builtLevel(built, name).facts]))
+	};
+};
+export { makeCurrentVersionView, makeSubtypeTables, makeTreeTables, versionTimestamps };
+
+//# sourceMappingURL=versioned-chain.js.map

package/dist/versioned-chain.js.map

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

package/package.json

@@ -1,6 +1,112 @@
 {
   "name": "@thomasfosterau/effect-drizzle-ext",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The Effect ↔ Drizzle bridge: Effect Schema → Drizzle column derivation with an extensible column-kind system, a versioned-chain interpreter, typed Postgres error classification, pagination and transaction combinators.",
+  "keywords": [
+    "drizzle",
+    "drizzle-orm",
+    "effect",
+    "effect-schema",
+    "postgres",
+    "typescript"
+  ],
+  "homepage": "https://github.com/thomasfosterau/effect-drizzle-ext#readme",
+  "bugs": {
+    "url": "https://github.com/thomasfosterau/effect-drizzle-ext/issues"
+  },
+  "license": "MIT",
+  "author": "Thomas Foster <me@thomasfoster.au>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thomasfosterau/effect-drizzle-ext.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./derive": {
+      "types": "./dist/derive.d.ts",
+      "default": "./dist/derive.js"
+    },
+    "./references": {
+      "types": "./dist/references.d.ts",
+      "default": "./dist/references.js"
+    },
+    "./constraints": {
+      "types": "./dist/constraints.d.ts",
+      "default": "./dist/constraints.js"
+    },
+    "./columns": {
+      "types": "./dist/columns.d.ts",
+      "default": "./dist/columns.js"
+    },
+    "./query": {
+      "types": "./dist/query.d.ts",
+      "default": "./dist/query.js"
+    },
+    "./sort": {
+      "types": "./dist/sort.d.ts",
+      "default": "./dist/sort.js"
+    },
+    "./update": {
+      "types": "./dist/update.d.ts",
+      "default": "./dist/update.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "default": "./dist/errors.js"
+    },
+    "./database": {
+      "types": "./dist/database.d.ts",
+      "default": "./dist/database.js"
+    },
+    "./versioned-chain": {
+      "types": "./dist/versioned-chain.d.ts",
+      "default": "./dist/versioned-chain.js"
+    },
+    "./jsonapi": {
+      "types": "./dist/jsonapi/index.d.ts",
+      "default": "./dist/jsonapi/index.js"
+    },
+    "./jsonapi/derive": {
+      "types": "./dist/jsonapi/derive.d.ts",
+      "default": "./dist/jsonapi/derive.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@effect/language-service": "^0.87.5",
+    "@thomasfosterau/effect-jsonapi": "^0.20.0",
+    "@types/node": "^26.6.6",
+    "@vitest/coverage-istanbul": "5.0.5",
+    "drizzle-orm": "1.0.0-rc.5",
+    "effect": "4.1.2",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "@thomasfosterau/effect-jsonapi": ">=0.16.0",
+    "drizzle-orm": ">=1.0.0-rc.5",
+    "effect": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@thomasfosterau/effect-jsonapi": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  }
 }

package/src/columns.ts

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