@zeroxsolutions/db 9.0.1 → 9.2.0

package/CHANGELOG.md

@@ -1,3 +1,31 @@
+## 9.2.0 (2026-09-28)
+
+### 🚀 Features
+
+- **db:** resolve a relationship filter against its foreign-key column ([32903ba](https://github.com/zeroxsolutions/zeroxsolutions/commit/32903ba))
+
+### ❤️ Thank You
+
+- Claude Opus 5.5 (1M context)
+- Lương Văn Tú
+
+## 9.1.0 (2026-09-27)
+
+### 🚀 Features
+
+- **db:** order by a path no column holds, and admit resolved names ([bc10882](https://github.com/zeroxsolutions/zeroxsolutions/commit/bc10882))
+- **db:** resolve a filter path no column holds through its own expression ([4627742](https://github.com/zeroxsolutions/zeroxsolutions/commit/4627742))
+
+### 🩹 Fixes
+
+- **db:** parenthesize a resolved condition and read resolvers by own key ([56bb1e4](https://github.com/zeroxsolutions/zeroxsolutions/commit/56bb1e4))
+
+### ❤️ Thank You
+
+- Claude Opus 5.5 (1M context)
+- Claude Sonnet 5
+- Lương Văn Tú
+
 ## 9.0.1 (2026-09-27)
 
 ### 🩹 Fixes

package/README.md

@@ -361,6 +361,32 @@ All 15, as `filterOperatorSchema` declares them:
 
 A `%` or `_` in a text value is escaped, so it matches literally rather than as a wildcard.
 
+#### Relationship Filters
+
+A relationship named in a permit list is no column - its id sits in a foreign-key column instead, which
+`buildFilterConditions` cannot resolve on its own. Declare the permit through `permitsFor`'s own
+`relationship(name, operators)` (`@zeroxsolutions/query`), then hand `columnResolver` the foreign-key
+column under that same name in `resolvers`:
+
+```ts
+import { permitsFor } from '@zeroxsolutions/query';
+import { buildFilterConditions, columnResolver } from '@zeroxsolutions/db/utils';
+
+const placesQueryPermits = permitsFor(placeAttributes, { relationships: places.relationships }).relationship(
+  'region',
+  ['equals', 'in'],
+);
+
+const condition = buildFilterConditions({
+  table: places,
+  filter: query.filter,
+  resolvers: { region: columnResolver(places.regionId) },
+});
+```
+
+`columnResolver` answers `equals` and `in` - the only two operators a relationship filter grants -
+comparing the id against the column it closes over, and throws on any other operator.
+
 ### Order Builder
 
 ```ts

package/dist/utils/assert-queryable-fields.d.ts

@@ -14,8 +14,14 @@ export declare class InvalidQuerySort extends Error {
  * building SQL.
  *
  * @param query - the parsed wire query, read for its `filter` / `sort` (a no-op when `undefined`)
- * @throws {@link InvalidQueryFilter} naming the first filtered field outside `allow.filterable`
- * @throws {@link InvalidQuerySort} naming the first sorted field outside `allow.sortable`
+ * @param resolved - the names a resolver answers, which no row key could list
+ * @throws {@link InvalidQueryFilter} naming the first filtered field outside `allow.filterable` and
+ *   `resolved.filterable`
+ * @throws {@link InvalidQuerySort} naming the first sorted field outside `allow.sortable` and
+ *   `resolved.sortable`
  */
-export declare function assertQueryableFields<TSelect>(query: Partial<Pick<GuardedCollectionQuery<FilterValue>, 'filter' | 'sort'>> | undefined, allow: QueryableFields<TSelect>): void;
+export declare function assertQueryableFields<TSelect>(query: Partial<Pick<GuardedCollectionQuery<FilterValue>, 'filter' | 'sort'>> | undefined, allow: QueryableFields<TSelect>, resolved?: {
+    filterable?: readonly string[];
+    sortable?: readonly string[];
+}): void;
 //# sourceMappingURL=assert-queryable-fields.d.ts.map

package/dist/utils/assert-queryable-fields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assert-queryable-fields.d.ts","sourceRoot":"","sources":["../../src/utils/assert-queryable-fields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,KAAK,EAAc,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG5E,6EAA6E;AAC7E,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,KAAK,EAAE,MAAM;CAG1B;AAED,yEAAyE;AACzE,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,KAAK,EAAE,MAAM;CAG1B;AAaD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAC3C,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,sBAAsB,CAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC,CAAC,GAAG,SAAS,EACxF,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,GAC9B,IAAI,CAUN"}
+{"version":3,"file":"assert-queryable-fields.d.ts","sourceRoot":"","sources":["../../src/utils/assert-queryable-fields.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,KAAK,EAAc,WAAW,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG5E,6EAA6E;AAC7E,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,KAAK,EAAE,MAAM;CAG1B;AAED,yEAAyE;AACzE,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,KAAK,EAAE,MAAM;CAG1B;AAaD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAC3C,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,sBAAsB,CAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC,CAAC,GAAG,SAAS,EACxF,KAAK,EAAE,eAAe,CAAC,OAAO,CAAC,EAC/B,QAAQ,GAAE;IAAE,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GAC9E,IAAI,CAUN"}

package/dist/utils/assert-queryable-fields.js

@@ -28,13 +28,16 @@ function assertFilterNodes(nodes, filterable) {
  * building SQL.
  *
  * @param query - the parsed wire query, read for its `filter` / `sort` (a no-op when `undefined`)
- * @throws {@link InvalidQueryFilter} naming the first filtered field outside `allow.filterable`
- * @throws {@link InvalidQuerySort} naming the first sorted field outside `allow.sortable`
+ * @param resolved - the names a resolver answers, which no row key could list
+ * @throws {@link InvalidQueryFilter} naming the first filtered field outside `allow.filterable` and
+ *   `resolved.filterable`
+ * @throws {@link InvalidQuerySort} naming the first sorted field outside `allow.sortable` and
+ *   `resolved.sortable`
  */
-export function assertQueryableFields(query, allow) {
+export function assertQueryableFields(query, allow, resolved = {}) {
     // Widened to `string`: the membership check runs against client-supplied names, not keys of TSelect.
-    const filterable = allow.filterable;
-    const sortable = allow.sortable;
+    const filterable = [...allow.filterable, ...(resolved.filterable ?? [])];
+    const sortable = [...allow.sortable, ...(resolved.sortable ?? [])];
     assertFilterNodes(query?.filter ?? [], filterable);
     for (const order of query?.sort ?? []) {
         if (!sortable.includes(order.field)) {

package/dist/utils/filter.d.ts

@@ -1,5 +1,5 @@
-import type { SQL } from 'drizzle-orm';
-import type { FilterTree, FilterTreeGroup, SortField } from '@zeroxsolutions/query';
+import type { Column, SQL } from 'drizzle-orm';
+import type { FilterableOf, FilterTree, FilterTreeGroup, SortField } from '@zeroxsolutions/query';
 import type { TableConfig as PgTableConfig } from 'drizzle-orm/pg-core';
 import { PgTable } from 'drizzle-orm/pg-core';
 import type { SQLiteTable, TableConfig as SQLiteTableConfig } from 'drizzle-orm/sqlite-core';
@@ -95,10 +95,27 @@ export type FilterableTable = PgTable<PgTableConfig> | SQLiteTable<SQLiteTableCo
 export declare class UnknownQueryField extends Error {
     constructor(field: string);
 }
-/** What a filter may reach: the table to resolve fields against, and the tree to build. */
+/** An expression for one published path no column holds. `undefined` contributes no condition, like an empty `in`. */
+export type FilterResolver = (leaf: FilterValue) => SQL | undefined;
+/**
+ * One resolver for each filter path the permit list `P` grants that is not a column of the table, and none for any
+ * other name: a path permitted without an expression, or an expression for a path nobody permits, fails to compile.
+ */
+export type FilterResolvers<TTable extends FilterableTable, P> = {
+    readonly [F in Exclude<keyof FilterableOf<P> & string, keyof TTable['_']['columns'] & string>]: FilterResolver;
+};
+/**
+ * The resolver for a relationship filter: the relationship's name is no column, and the id it compares is held in its
+ * foreign-key column. `{ region: columnResolver(places.regionId) }` declares one.
+ *
+ * @throws Error on an operator other than `equals` and `in`, the only two a relationship filter grants
+ */
+export declare function columnResolver(column: Column): FilterResolver;
+/** What a filter may reach: the table to resolve fields against, the tree to build, and the paths no column holds. */
 export interface FilterQuery<TTable extends FilterableTable = FilterableTable> {
     table: TTable;
     filter?: FilterNode[] | undefined;
+    resolvers?: Readonly<Record<string, FilterResolver>> | undefined;
 }
 /**
  * Builds one SQL condition from a filter tree. Nodes at the root join conjunctively; a group joins
@@ -112,16 +129,20 @@ export interface FilterQuery<TTable extends FilterableTable = FilterableTable> {
  * buildFilterConditions({ table: assessments, ...parsedQuery });
  * ```
  */
-export declare function buildFilterConditions<TTable extends FilterableTable>({ table, filter, }: FilterQuery<TTable>): SQL | undefined;
+export declare function buildFilterConditions<TTable extends FilterableTable>({ table, filter, resolvers, }: FilterQuery<TTable>): SQL | undefined;
 /**
  * Builds the `order by` clauses for a parsed sort, in the order the clauses were given.
  *
+ * @param options.resolvers - an expression per sort path no column holds, tried before a column
  * @returns an empty array for an absent or empty `sort`, which orders nothing
- * @throws {@link UnknownQueryField} when a clause names a column the table does not hold
+ * @throws {@link UnknownQueryField} when a clause names a column the table does not hold and no
+ *   resolver answers it
  * @example
  * ```ts
  * const orderClauses = buildOrderBy(users, [{ field: 'createdAt', direction: 'desc' }]);
  * ```
  */
-export declare function buildOrderBy<TTable extends PgTable<PgTableConfig> | SQLiteTable<SQLiteTableConfig>>(table: TTable, sort: SortField[] | undefined): SQL[];
+export declare function buildOrderBy<TTable extends PgTable<PgTableConfig> | SQLiteTable<SQLiteTableConfig>>(table: TTable, sort: SortField[] | undefined, options?: {
+    resolvers?: Readonly<Record<string, () => SQL | Column>>;
+}): SQL[];
 //# sourceMappingURL=filter.d.ts.map

package/dist/utils/filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../src/utils/filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,GAAG,EAAC,MAAM,aAAa,CAAC;AAqB1B,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,KAAK,EAAE,WAAW,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,IAAI,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC7F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,uGAAuG;AACvG,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;EAgB/B,CAAC;AAIH,iHAAiH;AACjH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+BAiC5B,CAAC;AAEH,gGAAgG;AAChG,MAAM,MAAM,WAAW,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;AAEvD,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;AAEjD,eAAO,MAAM,iBAAiB,EAAE,CAAC,CAAC,OAAO,CAAC,WAAW,CAKnD,CAAC;AAEH,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAGjD,CAAC;AAEH,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,IAAI,WAAW,CAEnE;AAED,qEAAqE;AACrE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,uEAAuE;AACvE,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;;GAGG;AACH,MAAM,WAAW,eAAe,CAAC,OAAO;IACtC,UAAU,EAAE,SAAS,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,EAAE,CAAC;IAChD,QAAQ,EAAE,SAAS,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,EAAE,CAAC;CAC/C;AAWD,wDAAwD;AACxD,MAAM,MAAM,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,GAAG,WAAW,CAAC,iBAAiB,CAAC,CAAC;AAEtF;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,KAAK,EAAE,MAAM;CAG1B;AAED,2FAA2F;AAC3F,MAAM,WAAW,WAAW,CAAC,MAAM,SAAS,eAAe,GAAG,eAAe;IAC3E,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,UAAU,EAAE,GAAG,SAAS,CAAC;CACnC;AAmGD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,SAAS,eAAe,EAAE,EACpE,KAAK,EACL,MAAM,GACP,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,GAAG,GAAG,SAAS,CAOvC;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,MAAM,SAAS,OAAO,CAAC,aAAa,CAAC,GAAG,WAAW,CAAC,iBAAiB,CAAC,EACjG,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,EAAE,GAAG,SAAS,GAC5B,GAAG,EAAE,CAgBP"}
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../../src/utils/filter.ts"],"names":[],"mappings":"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"}

package/dist/utils/filter.js

@@ -88,6 +88,21 @@ export class UnknownQueryField extends Error {
         super(`No column resolves the field "${field}".`);
     }
 }
+/**
+ * The resolver for a relationship filter: the relationship's name is no column, and the id it compares is held in its
+ * foreign-key column. `{ region: columnResolver(places.regionId) }` declares one.
+ *
+ * @throws Error on an operator other than `equals` and `in`, the only two a relationship filter grants
+ */
+export function columnResolver(column) {
+    return (leaf) => {
+        if (leaf.operator === 'equals')
+            return eq(column, leaf.value);
+        if (leaf.operator === 'in')
+            return leaf.value.length > 0 ? inArray(column, leaf.value) : undefined;
+        throw new Error(`A relationship filter answers equals and in, not "${leaf.operator}".`);
+    };
+}
 /**
  * The character that makes the next one literal. It is its own escape, so the character class below
  * must list it first: escaping `%` before `\` would re-escape the backslash the first pass added.
@@ -107,7 +122,14 @@ function textMatch(context, column, pattern) {
         : sql `${column} like ${pattern} escape '\\'`;
 }
 function buildCondition(context, filter) {
-    const column = context.columns[filter.field];
+    // Parenthesized because a resolver may return a bare `a or b`, and `and()` joins its operands without
+    // grouping them: beside a sibling or a soft-delete scope it would read `a or (b and deleted_at is null)`.
+    if (Object.hasOwn(context.resolvers, filter.field)) {
+        const expression = context.resolvers[filter.field]?.(filter);
+        return expression === undefined ? undefined : sql `(${expression})`;
+    }
+    // Own keys only: the field is client-written, and `constructor` would otherwise answer from Object.prototype.
+    const column = Object.hasOwn(context.columns, filter.field) ? context.columns[filter.field] : undefined;
     if (!column)
         throw new UnknownQueryField(filter.field);
     switch (filter.operator) {
@@ -179,35 +201,46 @@ function buildGroup(context, group) {
  * buildFilterConditions({ table: assessments, ...parsedQuery });
  * ```
  */
-export function buildFilterConditions({ table, filter, }) {
+export function buildFilterConditions({ table, filter, resolvers, }) {
     if (!filter || filter.length === 0)
         return undefined;
-    const conditions = buildNodes({ columns: getTableColumns(table), caseInsensitiveOperator: is(table, PgTable) }, filter);
+    const conditions = buildNodes({
+        columns: getTableColumns(table),
+        caseInsensitiveOperator: is(table, PgTable),
+        resolvers: resolvers ?? {},
+    }, filter);
     return conditions.length > 0 ? and(...conditions) : undefined;
 }
 /**
  * Builds the `order by` clauses for a parsed sort, in the order the clauses were given.
  *
+ * @param options.resolvers - an expression per sort path no column holds, tried before a column
  * @returns an empty array for an absent or empty `sort`, which orders nothing
- * @throws {@link UnknownQueryField} when a clause names a column the table does not hold
+ * @throws {@link UnknownQueryField} when a clause names a column the table does not hold and no
+ *   resolver answers it
  * @example
  * ```ts
  * const orderClauses = buildOrderBy(users, [{ field: 'createdAt', direction: 'desc' }]);
  * ```
  */
-export function buildOrderBy(table, sort) {
+export function buildOrderBy(table, sort, options = {}) {
     if (!sort || sort.length === 0)
         return [];
     const columns = getTableColumns(table);
     const clauses = [];
     for (const item of sort) {
-        const column = columns[item.field];
-        if (!column)
+        const resolvers = options.resolvers ?? {};
+        const expression = Object.hasOwn(resolvers, item.field)
+            ? resolvers[item.field]?.()
+            : Object.hasOwn(columns, item.field)
+                ? columns[item.field]
+                : undefined;
+        if (!expression)
             throw new UnknownQueryField(item.field);
         if (item.direction === 'desc')
-            clauses.push(desc(column));
+            clauses.push(desc(expression));
         else
-            clauses.push(asc(column));
+            clauses.push(asc(expression));
     }
     return clauses;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/db",
-  "version": "9.0.1",
+  "version": "9.2.0",
   "description": "Generic Drizzle toolkit - the id column and audit timestamps a table takes, a base repository, the unit-of-work and transactional outbox impls, and the filter/sort/pagination query helpers, for PostgreSQL (postgres-js) and Cloudflare D1; ships no domain schema. Shared across ZeroXSolutions services.",
   "private": false,
   "type": "module",
@@ -38,7 +38,7 @@
     "tslib": "^2.3.0",
     "uuid": "^14.0.1",
     "@zeroxsolutions/cosmic": "0.3.4",
-    "@zeroxsolutions/query": "0.5.1"
+    "@zeroxsolutions/query": "0.7.0"
   },
   "peerDependencies": {
     "@testcontainers/postgresql": "^12.1.0",