@zeroxsolutions/db 9.1.0 → 9.3.0

package/CHANGELOG.md

@@ -1,3 +1,42 @@
+## 9.3.0 (2026-09-28)
+
+### 🚀 Features
+
+- **db:** read a table's relationship names off the schema ([2a8045f](https://github.com/zeroxsolutions/zeroxsolutions/commit/2a8045f))
+
+### ❤️ Thank You
+
+- Claude Opus 5.5 (1M context)
+- Lương Văn Tú
+
+## 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,36 @@ 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.
+
+- `relationshipsOf(schema, '<table export>')` - the relations the schema declares on that table, as the map
+  `permitsFor(schema, { relationships })` takes, so a relationship filter names a relation the schema holds.
+  Throws on a key that is no table export (a table's SQL name is not one).
+
 ### Order Builder
 
 ```ts

package/dist/utils/filter.d.ts

@@ -104,6 +104,13 @@ export type FilterResolver = (leaf: FilterValue) => SQL | undefined;
 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;

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

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

package/dist/utils/index.d.ts

@@ -3,5 +3,6 @@ export * from './constants.js';
 export * from './filter.js';
 export * from './include.js';
 export * from './omit.js';
+export * from './relationships.js';
 export * from './table-query.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC"}

package/dist/utils/index.js

@@ -3,4 +3,5 @@ export * from './constants.js';
 export * from './filter.js';
 export * from './include.js';
 export * from './omit.js';
+export * from './relationships.js';
 export * from './table-query.js';

package/dist/utils/relationships.d.ts

@@ -0,0 +1,14 @@
+import { type ExtractTablesWithRelations } from 'drizzle-orm';
+/** The relation names a schema declares on one table, as the map `permitsFor` takes for its relationship filters. */
+export type RelationshipsOf<TSchema extends Record<string, unknown>, K extends keyof ExtractTablesWithRelations<TSchema>> = {
+    readonly [R in keyof ExtractTablesWithRelations<TSchema>[K]['relations'] & string]: Record<never, never>;
+};
+/**
+ * The relations `schema` declares on the table exported as `table`, read the way `drizzle({ schema })` reads them, so a
+ * relation added to the schema is a relationship a permit list can name without a second list to edit.
+ *
+ * @param table - the table's EXPORT name in `schema`, not its SQL name
+ * @throws Error when `table` is no table export of `schema`
+ */
+export declare function relationshipsOf<TSchema extends Record<string, unknown>, K extends keyof ExtractTablesWithRelations<TSchema> & string>(schema: TSchema, table: K): RelationshipsOf<TSchema, K>;
+//# sourceMappingURL=relationships.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/utils/relationships.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8D,KAAK,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAE1H,qHAAqH;AACrH,MAAM,MAAM,eAAe,CACzB,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,CAAC,SAAS,MAAM,0BAA0B,CAAC,OAAO,CAAC,IACjD;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,0BAA0B,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC;CAAE,CAAC;AAEjH;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvC,CAAC,SAAS,MAAM,0BAA0B,CAAC,OAAO,CAAC,GAAG,MAAM,EAC5D,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,GAAG,eAAe,CAAC,OAAO,EAAE,CAAC,CAAC,CAKxD"}

package/dist/utils/relationships.js

@@ -0,0 +1,15 @@
+import { createTableRelationsHelpers, extractTablesRelationalConfig } from 'drizzle-orm';
+/**
+ * The relations `schema` declares on the table exported as `table`, read the way `drizzle({ schema })` reads them, so a
+ * relation added to the schema is a relationship a permit list can name without a second list to edit.
+ *
+ * @param table - the table's EXPORT name in `schema`, not its SQL name
+ * @throws Error when `table` is no table export of `schema`
+ */
+export function relationshipsOf(schema, table) {
+    const { tables } = extractTablesRelationalConfig(schema, createTableRelationsHelpers);
+    const config = Object.hasOwn(tables, table) ? tables[table] : undefined;
+    if (!config)
+        throw new Error(`"${table}" is no table export of the schema.`);
+    return Object.fromEntries(Object.keys(config.relations).map((name) => [name, {}]));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/db",
-  "version": "9.1.0",
+  "version": "9.3.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.6.0"
+    "@zeroxsolutions/query": "0.7.0"
   },
   "peerDependencies": {
     "@testcontainers/postgresql": "^12.1.0",