@zeroxsolutions/db 9.0.1 → 9.1.0

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,20 @@ 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;
+};
+/** 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 +122,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

@@ -107,7 +107,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 +186,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.1.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.6.0"
   },
   "peerDependencies": {
     "@testcontainers/postgresql": "^12.1.0",