@orthacms/utils-server 0.0.0-reserve.0

package/dist/lib/filters/table-helpers.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.columnOf = columnOf;
+exports.rebind = rebind;
+exports.primaryKey = primaryKey;
+const drizzle_orm_1 = require("drizzle-orm");
+const filter_exceptions_1 = require("./filter-exceptions");
+/* eslint-enable @typescript-eslint/no-explicit-any */
+/**
+ * Resolve a column on a table by name, or throw if absent.
+ *
+ * The lookup is `Object.hasOwn`-guarded: drizzle's column map is a plain
+ * object, so `cols['constructor']` would otherwise return `Object` itself and
+ * this function would hand a `Function` to drizzle as a `Column`. The parser's
+ * whitelist is the primary guard, but this is the site where an escaped name
+ * turns into malformed SQL rather than an error, so it guards itself too.
+ */
+function columnOf(table, name) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const cols = (0, drizzle_orm_1.getTableColumns)(table);
+    const col = Object.hasOwn(cols, name) ? cols[name] : undefined;
+    if (!col)
+        throw new filter_exceptions_1.FilterSchemaException(`column "${name}" not on table`);
+    return col;
+}
+/**
+ * Re-resolve a prebuilt column against the table the translator is actually
+ * querying.
+ *
+ * A `RelationSchema`'s parent-side columns (`fk` on a `many-to-one` /
+ * `self-referential`, and every `parentKey`) are built once, against the
+ * **physical** parent table. That is wrong the moment the parent is an
+ * *alias* — which happens for every relation nested under a
+ * `self-referential` hop, whose subquery is `FROM t AS qb_x`. An unaliased
+ * `t.col` inside that subquery is still resolvable from the OUTERMOST
+ * query's `FROM t`, so Postgres silently binds the correlation to the root
+ * row instead of the aliased one: `parent.author.name` would filter on the
+ * ROOT row's author, and `parent.parent.name` would collapse to
+ * `parent.name`. Valid SQL, wrong rows, no error.
+ *
+ * Rebinding by the column's own DB name against the queried table fixes the
+ * correlation. It is a no-op when the parent is the physical table (the
+ * lookup finds the identical column), so unaliased paths are unaffected.
+ * Only ever call this for columns that live on the parent **by
+ * construction** — never for a target-side `fk` (`one-to-many`), where the
+ * name could collide with an unrelated parent column.
+ */
+function rebind(column, table) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const cols = (0, drizzle_orm_1.getTableColumns)(table);
+    for (const candidate of Object.values(cols)) {
+        if (candidate.name === column.name)
+            return candidate;
+    }
+    return column;
+}
+/**
+ * Resolve a table's primary key (defaults to an `id` column).
+ * Callers can override with an explicit `parentKey`/`targetKey` in the
+ * relation schema when the table's primary key is named differently.
+ */
+function primaryKey(table) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const cols = (0, drizzle_orm_1.getTableColumns)(table);
+    if (Object.hasOwn(cols, 'id'))
+        return cols['id'];
+    throw new filter_exceptions_1.FilterSchemaException('table has no `id` column — declare parentKey/targetKey explicitly');
+}

package/dist/lib/filters/tree-to-drizzle.d.ts

@@ -0,0 +1,35 @@
+import { type SQL } from 'drizzle-orm';
+import { type DbLike, type TableLike } from './table-helpers';
+import type { FilterSchema, ParsedNode, ParsedRule } from './types';
+export type { DbLike, TableLike } from './table-helpers';
+/**
+ * Hook a host can supply to handle filter rules whose field is in
+ * {@link FilterSchema.extensionFields}. Returns a Drizzle SQL fragment
+ * that gets spliced into the WHERE tree at the leaf's position, so
+ * extension rules compose with native ones inside AND/OR groups.
+ *
+ * The translator awaits each call sequentially during the walk; if
+ * an extension performs a DB roundtrip its latency adds linearly per
+ * leaf — extensions that need expensive lookups should prepare data
+ * once per request and capture it in the closure.
+ */
+export type FilterExtensionResolver = (rule: ParsedRule) => Promise<SQL>;
+/** Optional translator hooks — currently just the extension resolver. */
+export interface ApplyFilterTreeOptions {
+    /** Called for any leaf whose `path[0]` is in `schema.extensionFields`. */
+    resolveExtension?: FilterExtensionResolver;
+}
+/**
+ * Translate a parsed filter tree into a single Drizzle SQL fragment.
+ * Returns `undefined` when the tree is empty (or every group collapses
+ * to nothing) so callers can skip the WHERE clause without a special
+ * case. Group nodes emit `and(...)` / `or(...)`; rule nodes share the
+ * same scalar / relation translation.
+ *
+ * Async because extension resolvers may be async (e.g. a role filter
+ * runs a tiny `SELECT slug FROM roles` to validate enum membership).
+ * Non-extension trees stay synchronous in spirit — every native branch
+ * resolves immediately, no awaits hit the wire.
+ */
+export declare function applyFilterTree(tree: ParsedNode | null | undefined, schema: FilterSchema, rootTable: TableLike, db: DbLike, options?: ApplyFilterTreeOptions): Promise<SQL | undefined>;
+//# sourceMappingURL=tree-to-drizzle.d.ts.map

package/dist/lib/filters/tree-to-drizzle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-to-drizzle.d.ts","sourceRoot":"","sources":["../../../src/lib/filters/tree-to-drizzle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,GAAG,EAAE,MAAM,aAAa,CAAC;AAMrD,OAAO,EAAY,KAAK,MAAM,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEpE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAEzE,yEAAyE;AACzE,MAAM,WAAW,sBAAsB;IACnC,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;CAC9C;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACjC,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EACnC,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,SAAS,EACpB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,sBAA2B,GACrC,OAAO,CAAC,GAAG,GAAG,SAAS,CAAC,CAG1B"}

package/dist/lib/filters/tree-to-drizzle.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyFilterTree = applyFilterTree;
+const drizzle_orm_1 = require("drizzle-orm");
+const filter_exceptions_1 = require("./filter-exceptions");
+const negation_1 = require("./negation");
+const own_property_1 = require("./own-property");
+const relation_exists_1 = require("./relation-exists");
+const scalar_op_1 = require("./scalar-op");
+const table_helpers_1 = require("./table-helpers");
+/**
+ * Translate a parsed filter tree into a single Drizzle SQL fragment.
+ * Returns `undefined` when the tree is empty (or every group collapses
+ * to nothing) so callers can skip the WHERE clause without a special
+ * case. Group nodes emit `and(...)` / `or(...)`; rule nodes share the
+ * same scalar / relation translation.
+ *
+ * Async because extension resolvers may be async (e.g. a role filter
+ * runs a tiny `SELECT slug FROM roles` to validate enum membership).
+ * Non-extension trees stay synchronous in spirit — every native branch
+ * resolves immediately, no awaits hit the wire.
+ */
+async function applyFilterTree(tree, schema, rootTable, db, options = {}) {
+    if (!tree)
+        return undefined;
+    return walk(tree, schema, rootTable, db, options);
+}
+async function walk(node, schema, parent, db, options) {
+    if (node.kind === 'rule') {
+        return translateRule(node, schema, parent, db, options);
+    }
+    const parts = [];
+    for (const child of node.children) {
+        const piece = await walk(child, schema, parent, db, options);
+        if (piece !== undefined)
+            parts.push(piece);
+    }
+    if (parts.length === 0)
+        return undefined;
+    if (parts.length === 1)
+        return parts[0];
+    return node.combinator === 'or' ? (0, drizzle_orm_1.or)(...parts) : (0, drizzle_orm_1.and)(...parts);
+}
+async function translateRule(rule, schema, parent, db, options) {
+    const head = rule.path[0];
+    if (schema.extensionFields?.has(head)) {
+        if (!options.resolveExtension) {
+            throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.InvalidNode, `extension field "${head}" referenced but no resolver provided`, { field: head });
+        }
+        return options.resolveExtension(rule);
+    }
+    if (rule.path.length === 1) {
+        return (0, scalar_op_1.scalar)((0, table_helpers_1.columnOf)(parent, rule.path[0]), rule.op, rule.value);
+    }
+    const key = rule.path[0];
+    // `Object.hasOwn`-guarded: `relations['valueOf']` on a plain object map
+    // returns `Object.prototype.valueOf`, which passes this truthiness check
+    // and then falls out of `relationExists`'s `switch (rel.kind)` as
+    // `undefined` — the predicate the user asked for is silently dropped and
+    // the endpoint answers 200 unfiltered.
+    const rel = (0, own_property_1.own)(schema.relations, key);
+    if (!rel) {
+        throw new filter_exceptions_1.FilterException(filter_exceptions_1.FilterErrorCode.UnknownRelation, `unknown relation "${key}"`, { relation: key });
+    }
+    const leaf = { path: rule.path.slice(1), op: rule.op, value: rule.value };
+    // A negating rule on a relation path asks for the ABSENCE of a matching
+    // related row, which is `NOT EXISTS(… positive …)` — NOT the naive
+    // `EXISTS(… negated …)`, which on a to-many relation asserts the
+    // opposite of what the user wrote. The negation wraps the OUTERMOST
+    // hop, so a multi-hop path negates the whole chain ("no (author,
+    // company) pair matches") rather than just its last segment.
+    if ((0, negation_1.isNegatingLeaf)(rule.op, rule.value)) {
+        return (0, drizzle_orm_1.not)((0, relation_exists_1.relationExists)(rel, parent, (0, negation_1.positiveLeaf)(leaf), db));
+    }
+    return (0, relation_exists_1.relationExists)(rel, parent, leaf, db);
+}

package/dist/lib/filters/types.d.ts

@@ -0,0 +1,217 @@
+import type { AnyColumn, SQL, Table } from 'drizzle-orm';
+import type { TableLike } from './table-helpers';
+/**
+ * Builds a relation's `scope` predicate — the workspace + soft-delete
+ * guard ANDed inside its EXISTS subquery. It is a function, not a
+ * prebuilt `SQL`, because the table it must reference is not always the
+ * physical target: a `self-referential` relation aliases the target, and
+ * the predicate has to bind to that alias, not the outer table of the
+ * same name. The translator passes whichever table it actually queries
+ * (aliased or not), so the host resolves columns from that — e.g. via
+ * `getTableColumns(target)`. Return `undefined` to add nothing.
+ */
+export type RelationScope = (target: TableLike) => SQL | undefined;
+/** Named constants for `FilterOperator` — use in switches and comparisons. */
+export declare const FilterOperator: {
+    readonly Eq: "eq";
+    readonly Ne: "ne";
+    readonly Gt: "gt";
+    readonly Gte: "gte";
+    readonly Lt: "lt";
+    readonly Lte: "lte";
+    readonly In: "in";
+    readonly Nin: "nin";
+    readonly Like: "like";
+    readonly Ilike: "ilike";
+    readonly Nilike: "nilike";
+    readonly Null: "null";
+};
+/** Standard REST operator names. Translator maps each to a Drizzle helper. */
+export type FilterOperator = (typeof FilterOperator)[keyof typeof FilterOperator];
+/** Named constants for `ScalarFieldType` — use in switches. */
+export declare const ScalarFieldType: {
+    readonly String: "string";
+    readonly Number: "number";
+    readonly Boolean: "boolean";
+    readonly Uuid: "uuid";
+    readonly Date: "date";
+    readonly Enum: "enum";
+};
+/** How the parser coerces raw URL string values. */
+export type ScalarFieldType = (typeof ScalarFieldType)[keyof typeof ScalarFieldType];
+/** Named constants for `RelationSchema['kind']` — use in switches. */
+export declare const RelationKind: {
+    readonly OneToOne: "one-to-one";
+    readonly OneToMany: "one-to-many";
+    readonly ManyToOne: "many-to-one";
+    readonly ManyToMany: "many-to-many";
+    readonly SelfReferential: "self-referential";
+};
+/** Relation cardinality discriminants. */
+export type RelationKind = (typeof RelationKind)[keyof typeof RelationKind];
+/**
+ * Coercion rules for one column.
+ *
+ * The declared `type` decides two things, not one: how an incoming string is
+ * coerced, and **which operators the field may be asked** (`operator-support.ts`
+ * holds the table). A field does not accept every operator — the pattern family
+ * (`like`/`ilike`/`nilike`) is text-only, because Postgres defines `~~` for text
+ * and nothing else.
+ */
+export interface ScalarFieldSchema {
+    /** How incoming strings are coerced before hitting Drizzle. */
+    type: ScalarFieldType;
+    /** Required when `type === 'enum'`. */
+    enumValues?: readonly string[];
+}
+/** Columns exposed on one table. */
+export type FieldSchema = Record<string, ScalarFieldSchema>;
+/**
+ * Relation descriptor. `kind` discriminates the SQL shape the translator
+ * emits (EXISTS, EXISTS + INNER JOIN, aliased self-join).
+ */
+export type RelationSchema = {
+    /** Target FK references parent — one row (1:1) or many (1:N). */
+    kind: 'one-to-one' | 'one-to-many';
+    /** Target table containing the FK. */
+    table: Table;
+    /** Column on `table` referencing parent's primary key. */
+    fk: AnyColumn;
+    /** Parent primary key — defaults to `parent.id`. */
+    parentKey?: AnyColumn;
+    /**
+     * Extra predicate ANDed inside the EXISTS subquery, over the
+     * target table's own columns — e.g. a workspace boundary and a
+     * soft-delete guard. Without it a relation filter traverses rows
+     * the root query itself excludes (a soft-deleted or foreign
+     * target still matches `relation.field`). See {@link RelationScope}.
+     */
+    scope?: RelationScope;
+    fields?: FieldSchema;
+    relations?: Record<string, RelationSchema>;
+} | {
+    /** Parent FK references target. */
+    kind: 'many-to-one';
+    /** Target table. */
+    table: Table;
+    /** Column on the parent table referencing target's primary key. */
+    fk: AnyColumn;
+    /** Target primary key — defaults to `target.id`. */
+    targetKey?: AnyColumn;
+    /** Workspace + soft-delete guard. See {@link RelationScope}. */
+    scope?: RelationScope;
+    fields?: FieldSchema;
+    relations?: Record<string, RelationSchema>;
+} | {
+    /** Many rows link parent to target through a junction table. */
+    kind: 'many-to-many';
+    /** Junction (through) table. */
+    through: Table;
+    /** Junction column referencing parent's primary key. */
+    fk: AnyColumn;
+    /** Junction column referencing target's primary key. */
+    targetFk: AnyColumn;
+    /** Target table — required when filtering on target fields. */
+    table?: Table;
+    parentKey?: AnyColumn;
+    targetKey?: AnyColumn;
+    /**
+     * Workspace + soft-delete guard. Because a scope lives on the
+     * target table, it can only be applied through the join to
+     * `table` — so when it is present the junction-only fast path
+     * (filtering on the target FK alone) must yield to the full join.
+     * See {@link RelationScope}.
+     */
+    scope?: RelationScope;
+    fields?: FieldSchema;
+    relations?: Record<string, RelationSchema>;
+} | {
+    /** Parent references another row in the same table. */
+    kind: 'self-referential';
+    /** Same physical table as the parent. */
+    table: Table;
+    /** Column on the parent referencing its own primary key. */
+    fk: AnyColumn;
+    /**
+     * Alias used for the self-joined table inside the subquery. Must
+     * be unique per occurrence in the filter tree, not per relation:
+     * two rules on the same self-relation would otherwise share a
+     * correlation name and collide.
+     */
+    alias: string;
+    /**
+     * Workspace + soft-delete guard, applied against the aliased
+     * self-join (the translator passes the alias). See
+     * {@link RelationScope}.
+     */
+    scope?: RelationScope;
+    fields?: FieldSchema;
+    relations?: Record<string, RelationSchema>;
+};
+/** Public filter surface for one endpoint. */
+export interface FilterSchema {
+    /** Scalar columns on the root table. */
+    fields?: FieldSchema;
+    /** Relations traversable from the root table. */
+    relations?: Record<string, RelationSchema>;
+    /**
+     * Field names that should be routed through a host-supplied
+     * `resolveExtension` hook instead of the standard scalar / relation
+     * translator. Lets a downstream plugin contribute a "virtual"
+     * field — e.g. `role` on the user filter — that resolves to a
+     * subquery the host stitches into the WHERE tree.
+     *
+     * Each entry MUST also have a corresponding declaration under
+     * {@link fields} so the parser can validate the leaf's value
+     * against a {@link ScalarFieldSchema}. The set is consulted only
+     * by the translator, not by `parseFilterTree`.
+     */
+    extensionFields?: ReadonlySet<string>;
+    /** Maximum dotted-path depth. Defaults to 3. */
+    maxDepth?: number;
+    /**
+     * Maximum total number of rules + groups in a tree-shaped filter.
+     * Defaults to 50. Guards against pathological JSON payloads that
+     * would otherwise translate into very large SQL trees.
+     */
+    maxNodes?: number;
+    /**
+     * Maximum nesting depth of `and`/`or` groups in a tree-shaped filter.
+     * Defaults to 5. Independent of {@link maxDepth} (which limits
+     * dotted-path depth on a single rule).
+     */
+    maxGroupDepth?: number;
+    /**
+     * Maximum number of elements in a single `in`/`nin` value list.
+     * Defaults to 100. Bounds the size of the generated `IN (...)` clause
+     * independently of {@link maxNodes} (which counts whole rules, not the
+     * elements inside one rule's value list).
+     */
+    maxInListLength?: number;
+}
+/** Parser output, one node per URL filter entry. */
+export interface ParsedFilter {
+    /** Dotted path split into segments, e.g. `['workspaces','name']`. */
+    path: string[];
+    /** Requested operator. */
+    op: FilterOperator;
+    /** Coerced to the declared type; array for `in`/`nin`, boolean for `null`. */
+    value: unknown;
+}
+/** Tree-shaped parser output — leaf rule, type-tagged for the union. */
+export interface ParsedRule extends ParsedFilter {
+    kind: 'rule';
+}
+/** Tree-shaped parser output — group node combining children with AND or OR. */
+export interface ParsedGroup {
+    kind: 'group';
+    combinator: 'and' | 'or';
+    children: ParsedNode[];
+}
+/**
+ * Tree-shaped parser output. `parseFilterTree` returns a `ParsedGroup`
+ * root (or null when the input is empty); the translator walks this
+ * tree directly into Drizzle SQL.
+ */
+export type ParsedNode = ParsedRule | ParsedGroup;
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/filters/types.d.ts.map

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

package/dist/lib/filters/types.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RelationKind = exports.ScalarFieldType = exports.FilterOperator = void 0;
+/** Named constants for `FilterOperator` — use in switches and comparisons. */
+exports.FilterOperator = {
+    Eq: 'eq',
+    Ne: 'ne',
+    Gt: 'gt',
+    Gte: 'gte',
+    Lt: 'lt',
+    Lte: 'lte',
+    In: 'in',
+    Nin: 'nin',
+    Like: 'like',
+    Ilike: 'ilike',
+    Nilike: 'nilike',
+    Null: 'null'
+};
+/** Named constants for `ScalarFieldType` — use in switches. */
+exports.ScalarFieldType = {
+    String: 'string',
+    Number: 'number',
+    Boolean: 'boolean',
+    Uuid: 'uuid',
+    Date: 'date',
+    Enum: 'enum'
+};
+/** Named constants for `RelationSchema['kind']` — use in switches. */
+exports.RelationKind = {
+    OneToOne: 'one-to-one',
+    OneToMany: 'one-to-many',
+    ManyToOne: 'many-to-one',
+    ManyToMany: 'many-to-many',
+    SelfReferential: 'self-referential'
+};

package/dist/lib/pg-errors.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Postgres error introspection shared by services that map constraint
+ * violations to clean HTTP errors (e.g. a unique-index race settled by the
+ * constraint → 409) instead of leaking a 500.
+ */
+/**
+ * Whether an error (or its `cause`, where a driver/ORM wraps it) is a
+ * Postgres unique violation (`23505`). Drivers surface the SQLSTATE on a
+ * `code` property; the walk is defensive because Drizzle has wrapped driver
+ * errors differently across versions.
+ */
+export declare function isUniqueViolation(error: unknown): boolean;
+/**
+ * The **name of the index/constraint** a unique violation (`23505`) tripped, or
+ * `undefined` when the error is not one.
+ *
+ * A table can carry several unique indexes, and "which one" is the difference
+ * between two entirely different messages to the caller — a localized content
+ * table has both a `(locale_group_id, locale)` pair and a per-locale one-to-one
+ * relation index, and reporting either as the other tells the user to fix
+ * something that is not wrong. Postgres names the offender on `constraint`;
+ * the same defensive `cause` walk as {@link isUniqueViolation} finds it through
+ * whatever the driver/ORM wrapped it in.
+ *
+ * Returns `''` for a violation whose constraint the driver did not name, so a
+ * caller can still distinguish "a unique violation, unattributed" from "not a
+ * unique violation" without a second call.
+ */
+export declare function violatedConstraint(error: unknown): string | undefined;
+/**
+ * Whether an error (or its `cause`, where a driver/ORM wraps it) is a Postgres
+ * **foreign-key** violation (`23503`).
+ *
+ * The counterpart of {@link isUniqueViolation} for the other constraint a write
+ * can lose to. A row that something else still references under
+ * `ON DELETE RESTRICT` is a legitimate refusal the caller can act on ("detach
+ * the referring records first") — leaking it as a 500 tells them the server
+ * broke instead. Deliberately a boolean and not a constraint name: unlike the
+ * several unique indexes on one localized content table, the answer here does
+ * not vary by which FK tripped.
+ */
+export declare function isForeignKeyViolation(error: unknown): boolean;
+//# sourceMappingURL=pg-errors.d.ts.map

package/dist/lib/pg-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-errors.d.ts","sourceRoot":"","sources":["../../src/lib/pg-errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAiBrE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAgB7D"}

package/dist/lib/pg-errors.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * Postgres error introspection shared by services that map constraint
+ * violations to clean HTTP errors (e.g. a unique-index race settled by the
+ * constraint → 409) instead of leaking a 500.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isUniqueViolation = isUniqueViolation;
+exports.violatedConstraint = violatedConstraint;
+exports.isForeignKeyViolation = isForeignKeyViolation;
+/** Postgres error code for a unique constraint/index violation. */
+const UNIQUE_VIOLATION = '23505';
+/** Postgres error code for a foreign-key constraint violation. */
+const FOREIGN_KEY_VIOLATION = '23503';
+/**
+ * Whether an error (or its `cause`, where a driver/ORM wraps it) is a
+ * Postgres unique violation (`23505`). Drivers surface the SQLSTATE on a
+ * `code` property; the walk is defensive because Drizzle has wrapped driver
+ * errors differently across versions.
+ */
+function isUniqueViolation(error) {
+    return violatedConstraint(error) !== undefined;
+}
+/**
+ * The **name of the index/constraint** a unique violation (`23505`) tripped, or
+ * `undefined` when the error is not one.
+ *
+ * A table can carry several unique indexes, and "which one" is the difference
+ * between two entirely different messages to the caller — a localized content
+ * table has both a `(locale_group_id, locale)` pair and a per-locale one-to-one
+ * relation index, and reporting either as the other tells the user to fix
+ * something that is not wrong. Postgres names the offender on `constraint`;
+ * the same defensive `cause` walk as {@link isUniqueViolation} finds it through
+ * whatever the driver/ORM wrapped it in.
+ *
+ * Returns `''` for a violation whose constraint the driver did not name, so a
+ * caller can still distinguish "a unique violation, unattributed" from "not a
+ * unique violation" without a second call.
+ */
+function violatedConstraint(error) {
+    let current = error;
+    for (let depth = 0; current && depth < 5; depth += 1) {
+        if (typeof current === 'object' &&
+            'code' in current &&
+            current.code === UNIQUE_VIOLATION) {
+            const name = current.constraint;
+            return typeof name === 'string' ? name : '';
+        }
+        current =
+            typeof current === 'object' && 'cause' in current
+                ? current.cause
+                : undefined;
+    }
+    return undefined;
+}
+/**
+ * Whether an error (or its `cause`, where a driver/ORM wraps it) is a Postgres
+ * **foreign-key** violation (`23503`).
+ *
+ * The counterpart of {@link isUniqueViolation} for the other constraint a write
+ * can lose to. A row that something else still references under
+ * `ON DELETE RESTRICT` is a legitimate refusal the caller can act on ("detach
+ * the referring records first") — leaking it as a 500 tells them the server
+ * broke instead. Deliberately a boolean and not a constraint name: unlike the
+ * several unique indexes on one localized content table, the answer here does
+ * not vary by which FK tripped.
+ */
+function isForeignKeyViolation(error) {
+    let current = error;
+    for (let depth = 0; current && depth < 5; depth += 1) {
+        if (typeof current === 'object' &&
+            'code' in current &&
+            current.code === FOREIGN_KEY_VIOLATION) {
+            return true;
+        }
+        current =
+            typeof current === 'object' && 'cause' in current
+                ? current.cause
+                : undefined;
+    }
+    return false;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "@orthacms/utils-server",
+    "version": "0.0.0-reserve.0",
+    "description": "@orthacms/utils-server — part of Ortha CMS.",
+    "license": "MIT",
+    "homepage": "https://github.com/ortha-source/ortha-cms/tree/main/packages/utils/server",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ortha-source/ortha-cms.git",
+        "directory": "packages/utils/server"
+    },
+    "bugs": {
+        "url": "https://github.com/ortha-source/ortha-cms/issues"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist"
+    ],
+    "dependencies": {
+        "@nestjs/common": "^11.0.0",
+        "drizzle-orm": "^0.45.0",
+        "tslib": "^2.3.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}