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

package/dist/src-CBeuhy5b.js

@@ -0,0 +1,478 @@
+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 Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as SchemaAST from "effect/SchemaAST";
+// src/derivation-error.ts
+/**
+* The construction-time failure every module-load derivation throws. Kept in a
+* module of its own that imports nothing from Drizzle, so the Drizzle-free
+* entry (`.`, which `defineTree` lives in) and `./derive` share one class: a
+* consumer matching on it structurally, or with `instanceof`, sees the same
+* error from either. Not a published subpath.
+*
+* @module derivation-error
+*/
+/**
+* A construction-time derivation failure: a table or a tree could not be built
+* from its declarations (no builder registered for a column kind, a
+* `references` annotation with no resolver, numeric bounds on a column the
+* table has no column for, an unresolvable FK target, a tree level whose
+* parent is missing or forms a cycle).
+*
+* **Thrown, never failed.** Derivation runs at module load, before an Effect
+* runtime exists, so the only way to stop a misdeclared table or tree from
+* reaching production is to make its `import` fail. It is a tagged error all
+* the same, so a consumer that does catch one (a registry loader, a codegen
+* script) can match it structurally.
+*/
+var DerivationError = class extends Schema.TaggedError()("DerivationError", { message: Schema.String }) {};
+// src/tree.ts
+/**
+* The interpreter behind `defineTree` (`.`) and `defineResourceTree`
+* (`./jsonapi`): one Drizzle-free declaration of an ontology's level tree, from
+* which every structural fact the database layer needs is derived at module
+* load. Not a published subpath: the two entries re-export its types and wrap
+* {@link buildTree} with their own leaf reader.
+*
+* **Shape.** A tree is an ordered record of levels. Each level names its
+* `parent` (another level; absent means a child of the root, i.e. a branch
+* root), may carry level `columns` (`dbColumn`-annotated fields contributed to
+* every descendant's view, landing on that level's version table) and a level
+* `kind`, and is either a **marker** (no `leaf`) or a **leaf** (a `leaf`
+* payload: a struct's fields in `.`, a `Resource.make` definition in
+* `./jsonapi`). A leaf's name is its discriminator value.
+*
+* **Order.** Declaration order is preserved wherever it becomes SQL order: the
+* level list, every descendant and subtree-leaf list (the discriminator CHECK
+* value sets), and each level's columns.
+*
+* **Failures.** Every check throws {@link DerivationError} at module load:
+* there is no runtime yet, and a misdeclared tree must stop its `import`.
+*
+* @module tree
+*/
+/**
+* Names no level column or leaf column may take: the chain's own columns, which
+* the derived tables and views project from the root and from every level.
+*/
+const RESERVED_COLUMN_NAMES = [
+	"id",
+	"version",
+	"action",
+	"type"
+];
+/** Throw the tree's {@link DerivationError}. */
+const treeError = (message) => {
+	throw new DerivationError({ message: `defineTree: ${message}` });
+};
+/** Throw for a level whose `parent` names no level of the tree. */
+const unknownParent = (name, parent) => treeError(`level "${name}" names parent "${parent}", which is not a level of this tree`);
+/** A canonical array index, which a JS object would reorder ahead of declaration order. */
+const isArrayIndex = (name) => /^(?:0|[1-9]\d*)$/.test(name);
+/** The first column on a path whose key or column name an earlier one took. */
+const firstClash = (path) => Arr.findFirst(Arr.map(path, (later, i) => Option.map(Arr.findFirst(Arr.take(path, i), (earlier) => earlier.key === later.key || earlier.column === later.column), (earlier) => [earlier, later])), Option.isSome).pipe(Option.flatten);
+/**
+* Check a tree declaration and derive every level's facts. Throws
+* {@link DerivationError} at module load for an empty tree, a level name a JS
+* object would reorder (an array index) or that is empty, a parent naming no
+* level, a parent cycle, a leaf with children, a marker with no leaf below it,
+* a level column without a `dbColumn` annotation, a column taking a reserved
+* name (`id`, `version`, `action`, `type`), or two columns on one root-to-leaf
+* path sharing a field key or a column name. The entries' own payload checks
+* come from `reader`.
+*/
+const buildTree = (spec, reader) => {
+	const names = R.keys(spec);
+	if (!Arr.isReadonlyArrayNonEmpty(names)) treeError("a tree needs at least one level");
+	Arr.forEach(names, (name) => {
+		if (name === "" || isArrayIndex(name)) treeError(`level name "${name}" is not allowed: an empty name or an array index would not keep declaration order`);
+	});
+	const has = (name) => R.has(spec, name);
+	const entryOf = (name) => spec[name];
+	const parentOf = (name) => Option.map(Option.fromUndefinedOr(entryOf(name).parent), (parent) => has(parent) ? parent : unknownParent(name, parent));
+	const leafOf = (name) => Option.fromUndefinedOr(entryOf(name).leaf);
+	const isLeafName = (name) => Option.isSome(leafOf(name));
+	const ancestorsOf = (name, trail) => Option.match(parentOf(name), {
+		onNone: () => [],
+		onSome: (parent) => Arr.contains(trail, parent) ? treeError(`the parents form a cycle: ${[...Arr.dropWhile(trail, (step) => step !== parent), parent].join(" → ")}`) : [...ancestorsOf(parent, [...trail, parent]), parent]
+	});
+	const ancestorsFor = (name) => ancestorsOf(name, [name]);
+	const leaves = Arr.filter(names, isLeafName);
+	const childrenOf = (name) => Arr.filter(names, (candidate) => Option.exists(parentOf(candidate), (parent) => parent === name));
+	const descendantsOf = (name) => Arr.filter(names, (candidate) => Arr.contains(ancestorsFor(candidate), name));
+	const subtreeLeavesOf = (name) => Arr.filter(leaves, (leaf) => leaf === name || Arr.contains(ancestorsFor(leaf), name));
+	Arr.forEach(names, (name) => {
+		if (isLeafName(name) && Arr.isReadonlyArrayNonEmpty(childrenOf(name))) treeError(`leaf "${name}" has children (${childrenOf(name).join(", ")}); only a marker level can be a parent`);
+		if (!isLeafName(name) && !Arr.isReadonlyArrayNonEmpty(subtreeLeavesOf(name))) treeError(`marker level "${name}" has no leaf below it, so its discriminator CHECK would admit nothing`);
+	});
+	const levelColumnsOf = (name) => {
+		const fields = entryOf(name).columns ?? {};
+		const columns = reader.levelColumns(fields);
+		const bare = Arr.filter(R.keys(fields), (key) => !R.has(columns, key));
+		return Arr.isReadonlyArrayNonEmpty(bare) ? treeError(`level "${name}" declares level columns with no dbColumn annotation (${bare.join(", ")}); a level column must back a database column`) : columns;
+	};
+	const leafColumnsOf = (name) => Option.match(leafOf(name), {
+		onNone: () => ({}),
+		onSome: (leaf) => reader.leafColumns(leaf, name)
+	});
+	const ownColumnsFor = (name) => {
+		const levelColumns = levelColumnsOf(name);
+		const leafColumns = leafColumnsOf(name);
+		const path = Arr.map([...R.toEntries(levelColumns), ...R.toEntries(leafColumns)], ([key, meta]) => ({
+			level: name,
+			key,
+			column: meta.column
+		}));
+		Arr.forEach(path, ({ key, column }) => {
+			if (Arr.contains(RESERVED_COLUMN_NAMES, key) || Arr.contains(RESERVED_COLUMN_NAMES, column)) treeError(`level "${name}" declares "${key}" (column "${column}"), but ${RESERVED_COLUMN_NAMES.join(", ")} are reserved for the chain`);
+		});
+		return {
+			levelColumns,
+			leafColumns,
+			path
+		};
+	};
+	const ownColumns = Arr.map(names, (name) => ({
+		name,
+		...ownColumnsFor(name)
+	}));
+	const ownOf = (name) => Option.getOrElse(Arr.findFirst(ownColumns, (own) => own.name === name), () => ({
+		name,
+		levelColumns: {},
+		leafColumns: {},
+		path: []
+	}));
+	Arr.forEach(leaves, (leaf) => {
+		const path = Arr.flatMap([...ancestorsFor(leaf), leaf], (name) => ownOf(name).path);
+		Option.map(firstClash(path), ([earlier, later]) => treeError(`"${later.key}" (column "${later.column}") on level "${later.level}" collides with "${earlier.key}" (column "${earlier.column}") on level "${earlier.level}"; both reach leaf "${leaf}"`));
+	});
+	const levels = Arr.map(names, (name) => ({
+		name,
+		entry: entryOf(name),
+		parent: parentOf(name),
+		kind: entryOf(name).kind ?? "plain",
+		isLeaf: isLeafName(name),
+		ancestors: ancestorsFor(name),
+		children: childrenOf(name),
+		descendants: descendantsOf(name),
+		subtreeLeaves: subtreeLeavesOf(name),
+		branch: Option.getOrElse(Arr.head(ancestorsFor(name)), () => name),
+		levelColumns: ownOf(name).levelColumns,
+		leafColumns: ownOf(name).leafColumns
+	}));
+	return {
+		spec,
+		names,
+		levels,
+		leaves,
+		branchRoots: Arr.filter(names, (name) => Option.isNone(parentOf(name))),
+		level: (name) => Option.getOrElse(Arr.findFirst(levels, (level) => level.name === name), () => treeError(`"${name}" is not a level of this tree`))
+	};
+};
+// src/index.ts
+/**
+* @copyright Thomas Foster
+*
+* **Effect Schema → Drizzle derivation: the annotation entry (no Drizzle).**
+*
+* A model attribute's base schema carries a {@link dbColumn} annotation
+* describing the database column it backs; a downstream derivation (the
+* {@link ./derive.ts} entry) reads that annotation and emits the matching
+* Drizzle column builder. One declaration — the annotated field — is the single
+* source for both the model projection and the column.
+*
+* This entry point has **no Drizzle dependency**: it is the half a client- /
+* model-layer package can import without pulling the ORM into its bundle. The
+* Drizzle-emitting half lives behind the {@link ./derive.ts} and
+* {@link ./versioned-chain.ts} subpaths.
+*
+* **Why a phantom rides alongside the annotation.** Effect Schema annotations
+* are erased from the static type (`schema.annotate(...)` returns the *same*
+* type, and `resolveAnnotations` widens every read to the augmented
+* `Annotations` interface). So a purely-annotation-driven derivation cannot stay
+* type-safe — it can neither tell *which* fields are columns nor recover their
+* precise column type at the type level. {@link dbColumn} therefore does two
+* things: it attaches a real runtime annotation (the source of truth the runtime
+* reads) **and** carries the metadata literally in a type-level phantom (so the
+* column map stays precisely typed, preserving `$inferSelect`). Annotations
+* alone are runtime-only; type safety needs the phantom.
+*
+* **Extensible column kinds.** The `pg` kind is an open `string` at this layer —
+* the package bakes in no fixed set of kinds. A consumer pins its own kind union
+* (e.g. `text | integer | boolean | timestamp | …custom`) via {@link dbColumnFor}
+* and supplies the matching Drizzle builders to the derivation. So a repo can
+* inject bespoke column kinds (a block-document store, a JSON codec, …) without
+* the package knowing about them.
+*
+* **Why the readers take `Schema.Constraint`, not `Schema.Top`.** Every reader
+* here only *reads* a schema (`resolveAnnotations`, `.ast`, the structural
+* wrapper members); none of them calls `annotate` / `check` / `rebuild`. That is
+* exactly effect's `Schema.Constraint` surface, and it is also the element type
+* of `Schema.Struct.Fields` — so the field readers below can hand a struct's own
+* field straight to a reader with no cast. `Schema.Top` is strictly narrower, so
+* this widening accepts everything a `Schema.Top` parameter would.
+*
+* @module index
+*/
+/**
+* The annotation key under which {@link dbColumn} stores its metadata.
+* {@link dbColumn} writes it; {@link readDbColumn} and {@link fieldColumns}
+* read it. Namespaced to the package so a consumer's own annotations never
+* collide.
+*/
+const DB_COLUMN_KEY = "effect-drizzle-ext/dbColumn";
+/**
+* Annotate a base schema with the database column it backs. Attaches a genuine
+* Effect annotation (the runtime reads it via {@link readDbColumn}) and carries
+* the metadata literally in the type (so the column derivation stays precisely
+* typed). Wrap the result in a model helper as usual — the helper's projection
+* carries the annotation through to the table factory.
+*
+* Accepts any `pg` string; pin the kind union with {@link dbColumnFor} to catch
+* unknown-kind typos at the annotation site.
+*/
+const dbColumn = (schema, meta) => schema.annotate({ [DB_COLUMN_KEY]: meta });
+/**
+* A {@link dbColumn} constrained to a specific column-kind union `Kind`. A
+* consumer pins its own kinds once — `const dbColumn = dbColumnFor<PgKind>()` —
+* so an annotation naming a kind the derivation can't build is a type error at
+* the annotation site rather than a runtime surprise.
+*/
+const dbColumnFor = () => (schema, meta) => schema.annotate({ [DB_COLUMN_KEY]: meta });
+/**
+* Read the db-column annotation off a schema at runtime. `Option.none()` when
+* the schema declares none.
+*
+* Reads the schema's **own** annotations only: `Schema.resolveAnnotations` on a
+* `Schema.optional(...)` / `Schema.NullOr(...)` wrapper does not see the inner
+* schema's annotation. Use {@link fieldColumns} for a struct's fields, which
+* peels those wrappers structurally.
+*/
+const readDbColumn = (schema) => Option.fromNullishOr(Schema.resolveAnnotations(schema)?.[DB_COLUMN_KEY]);
+/**
+* The runtime key under which {@link dbTable} attaches its metadata. A symbol
+* **property on the target object**, not an Effect Schema annotation — and that
+* is the reason {@link dbTable} is generic over any `T extends object` rather
+* than over `Schema.Top`.
+*
+* `annotate` does not annotate in place: it **rebuilds** the schema. For a
+* target assembled as `Object.assign(struct, { … })` — the shape a resource /
+* model definition in the consuming applications takes — a rebuild drops every
+* assigned property, and it breaks the referential identity that family
+* membership and registry lockstep checks compare by. A non-enumerable own
+* symbol property annotates in place, preserving both, and works on a plain
+* object just as well as on a schema.
+*/
+const DB_TABLE_KEY = Symbol.for("effect-drizzle-ext/dbTable");
+/**
+* Annotate any object with the database table it backs. Attaches the metadata
+* as a non-enumerable symbol property (see {@link DB_TABLE_KEY} for why not
+* `annotate`) and carries it literally in the type, so a level-bound table
+* factory can constrain its input to leaves anchored at its level. Returns the
+* **same** object.
+*
+* Accepts any {@link TableMeta}; pin a level union with {@link dbTableFor}.
+*/
+const dbTable = (target, meta) => {
+	Object.defineProperty(target, DB_TABLE_KEY, {
+		value: meta,
+		enumerable: false
+	});
+	return target;
+};
+/**
+* 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
+* rather than a runtime surprise.
+*/
+const dbTableFor = () => (target, meta) => dbTable(target, meta);
+/**
+* Read the db-table metadata off a target at runtime. `Option.none()` when the
+* target carries none.
+*
+* Typed to the {@link TableMeta} floor: a consumer that annotated with a
+* {@link DbTable} recovers its `level` through the {@link DbTableOf} phantom,
+* which is where the level is statically known.
+*/
+const readDbTable = (target) => Option.fromNullishOr(target[DB_TABLE_KEY]);
+const BOUND_KEYS = [
+	"minimum",
+	"maximum",
+	"exclusiveMinimum",
+	"exclusiveMaximum"
+];
+/**
+* The neutral `CheckInput` the walker hands a check's `toJsonSchema`: no outer
+* type, no member schemas, which the bound filters ignore.
+*/
+const NEUTRAL_CHECK_INPUT = {
+	type: void 0,
+	schemas: []
+};
+/**
+* Whether a `toJsonSchema` output is a plain fragment. The approximate
+* `[fragment, true]` form is an array, whose bound keys read as absent, so the
+* walker reads no bounds from it.
+*/
+const isFragment = (output) => Predicate.isObject(output);
+/** The JSON-Schema fragment a check's `toJsonSchema` annotation exposes, if any. */
+const checkFragment = (check) => Option.flatMap(Option.fromNullishOr(check.annotations?.toJsonSchema), (toJsonSchema) => Option.filter(Option.flatMap(Result.getSuccess(Result.try(() => toJsonSchema(NEUTRAL_CHECK_INPUT))), Option.fromNullishOr), isFragment));
+/** Merge a fragment's numeric bound keys over `bounds` (the later check wins a key). */
+const mergeBounds = (fragment, bounds) => Arr.reduce(BOUND_KEYS, bounds, (acc, key) => {
+	const value = fragment[key];
+	return Predicate.isNumber(value) ? {
+		...acc,
+		[key]: value
+	} : acc;
+});
+/**
+* Merge the numeric-bound fragments of a check list over `bounds`.
+*
+* `checks` is an `Option` because effect's own AST leaves the field absent; the
+* callers convert that foreign `undefined` at the boundary with
+* `Option.fromNullishOr`.
+*/
+const collectCheckBounds = (checks, bounds) => Arr.reduce(Option.getOrElse(checks, () => []), bounds, (acc, check) => {
+	const nested = Predicate.isTagged(check, "FilterGroup") ? collectCheckBounds(Option.some(check.checks), acc) : acc;
+	return Option.match(checkFragment(check), {
+		onNone: () => nested,
+		onSome: (fragment) => mergeBounds(fragment, nested)
+	});
+});
+/**
+* Recover the {@link NumericBounds} a single attribute schema declares, or
+* `Option.none()` when it declares none. Reads the schema's own checks plus the
+* checks of each union member — the `Schema.NullOr(Schema.Finite.check(...))`
+* shape a nullable numeric attribute takes. Deliberately shallow: bounds
+* buried deeper than one union level are a modelling smell, not a supported
+* shape.
+*
+* Exported because the `./jsonapi` entry's resource-level bounds reader is the
+* same walk over a different field source.
+*/
+const numericBounds = (schema) => {
+	const { ast } = schema;
+	const bounds = Arr.reduce(SchemaAST.isUnion(ast) ? ast.types : [], collectCheckBounds(Option.fromNullishOr(ast.checks), {}), (acc, member) => collectCheckBounds(Option.fromNullishOr(member.checks), acc));
+	return Arr.some(BOUND_KEYS, (key) => bounds[key] !== void 0) ? Option.some(bounds) : Option.none();
+};
+/**
+* One structural peel of a field wrapper: the schema `schema` wraps, or
+* `Option.none()` when it wraps nothing.
+*
+* Structural, not annotation-driven, because `Schema.resolveAnnotations` on a
+* wrapper does not see the inner schema's annotations — the wrapper is a
+* different schema with its own (empty) annotation record. An
+* `optional` / `optionalKey` wrapper exposes its inner schema as `.schema`; a
+* `NullOr` / `UndefinedOr` union exposes its members as `.members`, of which the
+* `null` / `undefined` arms are the ones to skip.
+*/
+const underlyingSchema = (schema) => {
+	const wrapper = schema;
+	if (wrapper.schema !== void 0) return Option.some(wrapper.schema);
+	return Arr.findFirst(wrapper.members ?? [], (member) => {
+		const tag = member.ast._tag;
+		return tag !== "Null" && tag !== "Undefined";
+	});
+};
+/**
+* How many wrappers deep the peel walks before giving up. The deepest shape the
+* projection supports is `optional(NullOr(annotated))`, which is three peels
+* (`optionalKey` → `UndefinedOr` → `NullOr`); the cap is slack above that, and
+* it is what keeps a self-referential schema from recursing forever.
+*/
+const MAX_WRAPPER_DEPTH = 8;
+/**
+* The schema that actually carries the {@link dbColumn} annotation for a struct
+* field: the field itself when it is annotated, otherwise the first annotated
+* schema found by peeling its wrappers. `Option.none()` for a field that backs
+* no column.
+*
+* Returning the *schema* rather than the metadata is what lets
+* {@link fieldColumnBounds} read the bounds off the same node the column was
+* declared on — bounds on `dbColumn(NullOr(Number.check(…)), …)` sit one union
+* level below the annotated node, which is exactly what {@link numericBounds}
+* walks.
+*/
+const columnSchema = (field, depth = 0) => {
+	if (depth > MAX_WRAPPER_DEPTH) return Option.none();
+	if (Option.isSome(readDbColumn(field))) return Option.some(field);
+	return Option.flatMap(underlyingSchema(field), (inner) => columnSchema(inner, depth + 1));
+};
+/**
+* Project a `Schema.Struct`'s fields to the per-field {@link DbColumn} metadata
+* the derivation consumes, dropping fields that declare no column. Peels the
+* `optional` / `NullOr` wrappers a field may apply. The type-level counterpart
+* is {@link FieldColumnsMetaOf}.
+*/
+const fieldColumns = (fields) => R.getSomes(R.map(fields, (field) => Option.flatMap(columnSchema(field), readDbColumn)));
+/**
+* Project a `Schema.Struct`'s per-field numeric bounds into plain data a
+* `CHECK`-constraint derivation consumes: for each {@link dbColumn}-annotated
+* field whose schema carries numeric-bound checks, the bounds paired with the
+* column metadata. Fields without a column, or without bounds, drop. The
+* Drizzle-emitting counterpart is the `./derive` entry's
+* `deriveFieldCheckConstraints`.
+*/
+const fieldColumnBounds = (fields) => R.getSomes(R.map(fields, (field) => Option.flatMap(columnSchema(field), (schema) => Option.zipWith(readDbColumn(schema), numericBounds(schema), (column, bounds) => ({
+	column,
+	...bounds
+})))));
+/**
+* A {@link defineTree} whose every entry also carries the consumer's
+* extension record `Ext` (pulpit's `owned` / `pageable` flags, say); the
+* library reads none of its members and hands each entry back on
+* `tree.level(name).entry`. Pin it once — `const defineTree =
+* defineTreeFor<RegistryFlags>()` — so an entry missing a flag is a type
+* error. Throws {@link DerivationError} at module load as `defineTree` does.
+*/
+const defineTreeFor = () => (spec) => buildTree(spec, {
+	levelColumns: fieldColumns,
+	leafColumns: fieldColumns
+});
+/**
+* Declare an ontology's level tree once, Drizzle-free, so a models package can
+* state it and the database layer derive every table, constraint and view from
+* it. Each entry is a level: a **marker** (no `leaf`) or a **leaf**, whose
+* `leaf` is the struct fields of its domain columns (`dbColumn`-annotated) and
+* whose name is its discriminator value. An entry names its `parent` (absent:
+* a branch root under the tree's root), and may carry level `columns`
+* contributed to every descendant's view and a level `kind`.
+*
+* Returns the checked {@link Tree}: per level, its ancestors, children,
+* descendants, subtree leaves (the discriminator CHECK value set) and branch,
+* all in declaration order. A parent naming no level of the tree, or the level
+* itself, is a type error. Throws {@link DerivationError} at module load for
+* every structural fault the types can't catch: a missing parent or a cycle, a
+* leaf with children, a marker with no leaf below it, an unannotated level
+* column, a reserved column name (`id`, `version`, `action`, `type`), or two
+* columns on one root-to-leaf path sharing a field key or a column name.
+*
+* @example
+* ```ts
+* import { dbColumn, defineTree } from "@thomasfosterau/effect-drizzle-ext";
+* 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 }) },
+*   },
+*   film: { parent: "work", leaf: {} },
+* });
+*
+* console.log(tree.level("work").subtreeLeaves); // ["book", "film"]
+* console.log(tree.level("book").ancestors); // ["work"]
+* ```
+*/
+const defineTree = defineTreeFor();
+export { dbTableFor as a, fieldColumnBounds as c, readDbColumn as d, readDbTable as f, DerivationError as h, dbTable as i, fieldColumns as l, treeError as m, dbColumn as n, defineTree as o, buildTree as p, dbColumnFor as r, defineTreeFor as s, DB_COLUMN_KEY as t, numericBounds as u };
+
+//# sourceMappingURL=src-CBeuhy5b.js.map

package/dist/src-CBeuhy5b.js.map

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

package/dist/update.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @copyright Thomas Foster
+ *
+ * **The update tri-state at a single seam.** {@link updateSetMap} builds an
+ * `UPDATE … SET` map from a decoded update input's **own keys**:
+ *
+ * | input                | meaning        | in the `SET` map        |
+ * | -------------------- | -------------- | ----------------------- |
+ * | `{ col: value }`     | set            | `col: value`            |
+ * | `{ col: null }`      | clear          | `col: null`             |
+ * | key absent / `undefined` | carry forward | not present at all  |
+ *
+ * An update input schema encodes the three states across key presence and
+ * the value — `Schema.optionalKey(Schema.NullOr(X))` for a clearable field,
+ * `Schema.optionalKey(X)` for one that may not be cleared — so decoding has
+ * already refused `null` for a column that must not be cleared. What this
+ * module must never do is fold the first two rows together: `col: input.col
+ * ?? null` turns a carry-forward into a clear, which is silent data loss
+ * (website #1877).
+ *
+ * **Nothing here is `Option`.** The `null` / `undefined` split *is* the
+ * tri-state; collapsing either side to one `Option` erases the difference
+ * between "leave alone" and "clear". The `SET` map is also Drizzle-facing,
+ * where `undefined` means "not supplied" and an `Option` would be written as
+ * a value.
+ *
+ * The preferenceflow application's shape (`apps/api/src/operations/
+ * update-fields.ts`); the website application's carry-forward merge
+ * (`mergeUpdateFields(current, input)`) is the same rule applied to a
+ * pre-read row, and needs no helper once the write is a `SET` map.
+ *
+ * @module update
+ */
+/**
+ * The `SET` (or `VALUES`) map {@link updateSetMap} produces from input `I`
+ * and writable column keys `K`: every writable key of `I`, optional (it is
+ * present only when the input supplied a value), with `undefined` removed
+ * from its value type (a present `null` stays).
+ */
+export type UpdateSet<I, K extends string> = { readonly [P in Extract<keyof I, K>]?: Exclude<I[P], undefined>; };
+/**
+ * The `SET` map for an update: every key of `input` that names a writable
+ * column and carries a **present** value (`null` included), in the input's
+ * own key order. Keys outside `writable` — the routing `id`, a
+ * server-owned column, a relationship the table does not carry, an unknown
+ * key — are dropped; an `undefined`-valued key (an explicit carry-forward)
+ * is dropped too, since the tri-state's first two rows must stay apart.
+ *
+ * `writable` is any iterable of column keys; pass a module-scope `HashSet`
+ * to build it once.
+ */
+export declare const updateSetMap: <I extends Readonly<Record<string, unknown>>, K extends string>(input: I, writable: Iterable<K>) => UpdateSet<I, K>;
+/**
+ * The `VALUES` map for a create: every key of `input` naming a writable
+ * column with a present value. An absent optional is left to the column
+ * default rather than written as `undefined`, and a key the table does not
+ * carry is dropped — the same projection as {@link updateSetMap}, without
+ * the tri-state reading (a create has nothing to carry forward).
+ */
+export declare const insertValues: <I extends Readonly<Record<string, unknown>>, K extends string>(input: I, writable: Iterable<K>) => UpdateSet<I, K>;
+//# sourceMappingURL=update.d.ts.map

package/dist/update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.d.ts","names":[],"sources":["../src/update.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YA4CY,UAAU,GAAG,gCACb,KAAK,cAAc,GAAG,MAAM,QAAQ,EAAE;;;;;;;;;;;;qBAiBrC,eAAgB,UAAU,SAAS,0BAA0B,kBAAgB,OACjF,GAAC,UACE,SAAS,OAClB,UAAU,GAAG;;;;;;;;qBAmBH,eAAgB,UAAU,SAAS,0BAA0B,kBAAgB,OACjF,GAAC,UACE,SAAS,OAClB,UAAU,GAAG"}

package/dist/update.js

@@ -0,0 +1,64 @@
+import * as Array from "effect/Array";
+import * as Record from "effect/Record";
+import * as HashSet from "effect/HashSet";
+// src/update.ts
+/**
+* @copyright Thomas Foster
+*
+* **The update tri-state at a single seam.** {@link updateSetMap} builds an
+* `UPDATE … SET` map from a decoded update input's **own keys**:
+*
+* | input                | meaning        | in the `SET` map        |
+* | -------------------- | -------------- | ----------------------- |
+* | `{ col: value }`     | set            | `col: value`            |
+* | `{ col: null }`      | clear          | `col: null`             |
+* | key absent / `undefined` | carry forward | not present at all  |
+*
+* An update input schema encodes the three states across key presence and
+* the value — `Schema.optionalKey(Schema.NullOr(X))` for a clearable field,
+* `Schema.optionalKey(X)` for one that may not be cleared — so decoding has
+* already refused `null` for a column that must not be cleared. What this
+* module must never do is fold the first two rows together: `col: input.col
+* ?? null` turns a carry-forward into a clear, which is silent data loss
+* (website #1877).
+*
+* **Nothing here is `Option`.** The `null` / `undefined` split *is* the
+* tri-state; collapsing either side to one `Option` erases the difference
+* between "leave alone" and "clear". The `SET` map is also Drizzle-facing,
+* where `undefined` means "not supplied" and an `Option` would be written as
+* a value.
+*
+* The preferenceflow application's shape (`apps/api/src/operations/
+* update-fields.ts`); the website application's carry-forward merge
+* (`mergeUpdateFields(current, input)`) is the same rule applied to a
+* pre-read row, and needs no helper once the write is a `SET` map.
+*
+* @module update
+*/
+const toHashSet = (writable) => HashSet.isHashSet(writable) ? writable : HashSet.fromIterable(writable);
+/**
+* The `SET` map for an update: every key of `input` that names a writable
+* column and carries a **present** value (`null` included), in the input's
+* own key order. Keys outside `writable` — the routing `id`, a
+* server-owned column, a relationship the table does not carry, an unknown
+* key — are dropped; an `undefined`-valued key (an explicit carry-forward)
+* is dropped too, since the tri-state's first two rows must stay apart.
+*
+* `writable` is any iterable of column keys; pass a module-scope `HashSet`
+* to build it once.
+*/
+const updateSetMap = (input, writable) => {
+	const columns = toHashSet(writable);
+	return Record.fromEntries(Array.filter(Record.toEntries(input), ([key, value]) => value !== void 0 && HashSet.has(columns, key)));
+};
+/**
+* The `VALUES` map for a create: every key of `input` naming a writable
+* column with a present value. An absent optional is left to the column
+* default rather than written as `undefined`, and a key the table does not
+* carry is dropped — the same projection as {@link updateSetMap}, without
+* the tri-state reading (a create has nothing to carry forward).
+*/
+const insertValues = (input, writable) => updateSetMap(input, writable);
+export { insertValues, updateSetMap };
+
+//# sourceMappingURL=update.js.map

package/dist/update.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.js","names":[],"sources":["../src/update.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,MAAM,aAA+B,aACnC,QAAQ,UAAU,QAAQ,IAAI,WAAW,QAAQ,aAAa,QAAQ;;;;;;;;;;;;AAaxE,MAAa,gBACX,OACA,aACoB;CACpB,MAAM,UAAmC,UAAU,QAAQ;CAG3D,OAAO,OAAO,YACZ,MAAM,OACJ,OAAO,UAAU,KAAK,IACrB,CAAC,KAAK,WAAW,UAAU,KAAA,KAAa,QAAQ,IAAI,SAAS,GAAG,CACnE,CACF;AACF;;;;;;;;AASA,MAAa,gBACX,OACA,aACoB,aAAa,OAAO,QAAQ"}