@zeroxsolutions/db 10.2.0 → 10.3.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 10.3.0 (2026-10-20)
+
+### 🚀 Features
+
+- **db:** take a relation out of a read for a finder to load itself ([f57181e](https://github.com/zeroxsolutions/zeroxsolutions/commit/f57181e))
+
+### ❤️ Thank You
+
+- Lương Văn Tú
+
 ## 10.2.0 (2026-10-20)
 
 ### 🚀 Features

package/README.md

@@ -11,7 +11,8 @@ A shared database library providing base entities, repository patterns, and quer
 - Reads that name what they load: a `read` of columns and nested relations, a `filter` tree, an `orderBy` with the
   primary key appended, and a page window only when one is given
 - `READS` (`defineReads`), declared once per context: each table's order as a relation and its `virtual` filter and
-  order names; `relationsOf` for the relationships a permit list names
+  order names; `relationsOf` for the relationships a permit list names; `withoutRelation` for a relation a finder
+  loads through one of its own
 - The filter vocabulary the wire toolkit is generic over: `filterOperatorSchema` / `FilterOperator` (15 operators),
   `filterValueSchema`, and typed refusals (`UnknownQueryField`, `UnknownReadName`)
 - Transaction support for all operations
@@ -34,13 +35,13 @@ Import from the subpath that matches your driver. **There is no root entry**: `p
 declares `"."`, but no `src/index.ts` exists for the build to emit it from, so
 `from '@zeroxsolutions/db'` does not resolve.
 
-| Export path                     | Description                                                                                                                |
-| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `@zeroxsolutions/db/postgres`   | PostgreSQL entity, repository, view repository, unit of work, outbox, and types                                            |
-| `@zeroxsolutions/db/d1`         | Cloudflare D1 (SQLite) entity, repository, unit of work, outbox, and types                                                 |
-| `@zeroxsolutions/db/utils`      | `defineReads`, `relationsOf`, the read and order types, the filter-value schema + operator enum, the refusals, omit masks  |
-| `@zeroxsolutions/db/testing`    | A throwaway Postgres container carrying your schema, on the engine you name, plus the container timeout and a fake uuid v7 |
-| `@zeroxsolutions/db/containers` | The forced remove that tears down a container you started yourself                                                         |
+| Export path                     | Description                                                                                                                                  |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@zeroxsolutions/db/postgres`   | PostgreSQL entity, repository, view repository, unit of work, outbox, and types                                                              |
+| `@zeroxsolutions/db/d1`         | Cloudflare D1 (SQLite) entity, repository, unit of work, outbox, and types                                                                   |
+| `@zeroxsolutions/db/utils`      | `defineReads`, `relationsOf`, `withoutRelation`, the read and order types, the filter-value schema + operator enum, the refusals, omit masks |
+| `@zeroxsolutions/db/testing`    | A throwaway Postgres container carrying your schema, on the engine you name, plus the container timeout and a fake uuid v7                   |
+| `@zeroxsolutions/db/containers` | The forced remove that tears down a container you started yourself                                                                           |
 
 ---
 
@@ -417,6 +418,20 @@ them. A permit list carries it as `relationships`, `permitsFor` checks a relatio
 `findOptionsOf` in `@zeroxsolutions/jsonapi` finds an included relation's fieldset through it. It throws on a key that
 is no table export (a table's SQL name is not one).
 
+### withoutRelation
+
+`withoutRelation(options, path)` answers the options with the relation at `path` taken out of their read, and every
+relation the read named under it; the options are unchanged where the read names no such relation. A relation load has
+no condition of its own, so a finder that may answer only some of a relation's rows, such as the caller's own, takes
+the relation out and loads it through a finder that carries the condition:
+
+```ts
+findOneVisibleById(id: PostId, memberId: MemberId, options?: FindOneOptions<typeof schema, 'postsTable'>) {
+  // ['review', 'appeals'] leaves the review and takes its appeals out
+  return this.findOne(eq(postsTable.id, id), withoutRelation(options, ['reviews']));
+}
+```
+
 ### Reading the query off a request
 
 This package ships **no** query schema and knows no wire format. Parse the request with

package/dist/utils/index.d.ts

@@ -3,4 +3,5 @@ export * from './omit.js';
 export { UnknownReadName, type ColumnName, type MatchOptions, type OrderEntry, type Read, type RelationRead, } from './read.js';
 export * from './reads.js';
 export * from './relationships.js';
+export * from './without-relation.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,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AACrB,cAAc,WAAW,CAAC;AAC1B,OAAO,EACL,eAAe,EACf,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,YAAY,GAClB,MAAM,WAAW,CAAC;AACnB,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AACrB,cAAc,WAAW,CAAC;AAC1B,OAAO,EACL,eAAe,EACf,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,YAAY,GAClB,MAAM,WAAW,CAAC;AACnB,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC"}

package/dist/utils/index.js

@@ -3,3 +3,4 @@ export * from './omit.js';
 export { UnknownReadName, } from './read.js';
 export * from './reads.js';
 export * from './relationships.js';
+export * from './without-relation.js';

package/dist/utils/without-relation.d.ts

@@ -0,0 +1,11 @@
+import type { Read } from './read.js';
+/**
+ * `options` with the relation at `path` taken out of its read, and with it everything the read named under that
+ * relation; `options` unchanged where its read names no such relation. `['review', 'appeals']` takes the appeals out
+ * of the review and leaves the review. A finder takes a relation out this way where the rows it may answer are a
+ * subset no relation load can scope, and loads that relation through a finder of its own.
+ */
+export declare function withoutRelation<O extends {
+    read?: Read;
+}>(options: O | undefined, path: readonly [string, ...string[]]): O | undefined;
+//# sourceMappingURL=without-relation.d.ts.map

package/dist/utils/without-relation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"without-relation.d.ts","sourceRoot":"","sources":["../../src/utils/without-relation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,IAAI,CAAA;CAAE,EACvD,OAAO,EAAE,CAAC,GAAG,SAAS,EACtB,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,GACnC,CAAC,GAAG,SAAS,CAGf"}

package/dist/utils/without-relation.js

@@ -0,0 +1,23 @@
+/**
+ * `options` with the relation at `path` taken out of its read, and with it everything the read named under that
+ * relation; `options` unchanged where its read names no such relation. `['review', 'appeals']` takes the appeals out
+ * of the review and leaves the review. A finder takes a relation out this way where the rows it may answer are a
+ * subset no relation load can scope, and loads that relation through a finder of its own.
+ */
+export function withoutRelation(options, path) {
+    if (options?.read === undefined)
+        return options;
+    return { ...options, read: readWithout(options.read, path) };
+}
+function readWithout(read, path) {
+    const [name, ...below] = path;
+    const relation = read.relations?.[name];
+    if (relation === undefined)
+        return read;
+    const others = Object.fromEntries(Object.entries(read.relations ?? {}).filter(([key]) => key !== name));
+    const [next, ...rest] = below;
+    return {
+        ...read,
+        relations: next === undefined ? others : { ...others, [name]: readWithout(relation, [next, ...rest]) },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeroxsolutions/db",
-  "version": "10.2.0",
+  "version": "10.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",