@zeroxsolutions/jsonapi 0.13.2 → 0.13.3

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 0.13.3 (2026-10-18)
+
+### 🚀 Features
+
+- **jsonapi:** turn a guarded query into a finder's options ([9f5f895](https://github.com/zeroxsolutions/zeroxsolutions/commit/9f5f895))
+
+### ❤️ Thank You
+
+- Claude Opus 5.5
+- Lương Văn Tú
+
 ## 0.13.2 (2026-10-06)
 
 No code changes. It depends on @zeroxsolutions/response, so its version follows response 0.14.4.
@@ -17,11 +28,11 @@ No code changes. It depends on @zeroxsolutions/response, so its version follows
 
 ### 🩹 Fixes
 
-- ⚠️  **jsonapi:** negotiate by the four json:api server rules alone ([67f4529](https://github.com/zeroxsolutions/zeroxsolutions/commit/67f4529))
+- ⚠️ **jsonapi:** negotiate by the four json:api server rules alone ([67f4529](https://github.com/zeroxsolutions/zeroxsolutions/commit/67f4529))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **jsonapi:** negotiate by the four json:api server rules alone  ([67f4529](https://github.com/zeroxsolutions/zeroxsolutions/commit/67f4529))
+- **jsonapi:** negotiate by the four json:api server rules alone ([67f4529](https://github.com/zeroxsolutions/zeroxsolutions/commit/67f4529))
   negotiateJsonApi returns null for a Content-Type that
   is not the JSON:API media type (or absent), and for an Accept that holds
   no JSON:API instance. A route refuses a body it cannot read through its
@@ -41,12 +52,12 @@ This was a version bump only for @zeroxsolutions/jsonapi to align it with other
 ### 🩹 Fixes
 
 - **jsonapi:** read every content-type parameter, q included ([07f81b9](https://github.com/zeroxsolutions/zeroxsolutions/commit/07f81b9))
-- ⚠️  **jsonapi:** negotiate ext, q, wildcards and content-type per spec ([2e2ffad](https://github.com/zeroxsolutions/zeroxsolutions/commit/2e2ffad))
+- ⚠️ **jsonapi:** negotiate ext, q, wildcards and content-type per spec ([2e2ffad](https://github.com/zeroxsolutions/zeroxsolutions/commit/2e2ffad))
 - **jsonapi:** read q as a weight when parsing a media type ([5403c39](https://github.com/zeroxsolutions/zeroxsolutions/commit/5403c39))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **jsonapi:** negotiate ext, q, wildcards and content-type per spec  ([2e2ffad](https://github.com/zeroxsolutions/zeroxsolutions/commit/2e2ffad))
+- **jsonapi:** negotiate ext, q, wildcards and content-type per spec ([2e2ffad](https://github.com/zeroxsolutions/zeroxsolutions/commit/2e2ffad))
   a Content-Type wildcard or a missing Content-Type is 415; an unsupported ext is 415 or 406; a wildcard no longer hides modified JSON:API Accept members; q=0 refuses a member.
 
 ### ❤️ Thank You
@@ -70,11 +81,11 @@ This was a version bump only for @zeroxsolutions/jsonapi to align it with other
 
 ### 💅 Refactors
 
-- ⚠️  **jsonapi:** list the names each entry publishes ([3746762](https://github.com/zeroxsolutions/zeroxsolutions/commit/3746762))
+- ⚠️ **jsonapi:** list the names each entry publishes ([3746762](https://github.com/zeroxsolutions/zeroxsolutions/commit/3746762))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **jsonapi:** list the names each entry publishes  ([3746762](https://github.com/zeroxsolutions/zeroxsolutions/commit/3746762))
+- **jsonapi:** list the names each entry publishes ([3746762](https://github.com/zeroxsolutions/zeroxsolutions/commit/3746762))
   the root no longer exports `parseMediaType`,
   `isJsonApiWithDisallowedParams` or `ParsedMediaType`; `negotiateJsonApi`
   is the negotiation decision. `./client` publishes the same names as
@@ -107,11 +118,11 @@ Version bump only, to take the repackaged `@zeroxsolutions/response`.
 
 ### 🚀 Features
 
-- ⚠️  **server,jsonapi:** one surface, one error-code vocabulary ([32b4aed](https://github.com/zeroxsolutions/zeroxsolutions/commit/32b4aed))
+- ⚠️ **server,jsonapi:** one surface, one error-code vocabulary ([32b4aed](https://github.com/zeroxsolutions/zeroxsolutions/commit/32b4aed))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **server,jsonapi:** one surface, one error-code vocabulary  ([32b4aed](https://github.com/zeroxsolutions/zeroxsolutions/commit/32b4aed))
+- **server,jsonapi:** one surface, one error-code vocabulary ([32b4aed](https://github.com/zeroxsolutions/zeroxsolutions/commit/32b4aed))
   createErrorHandler, createValidationHook and
   jsonApiContentNegotiation take a required `namespace`; negotiateJsonApi takes it
   as a third argument. Codes these mint are now `<namespace>.<name>`.
@@ -124,11 +135,11 @@ Version bump only, to take the repackaged `@zeroxsolutions/response`.
 
 ### 💅 Refactors
 
-- ⚠️  **query,response,server:** one wire spelling, flat exports ([5c57b3a](https://github.com/zeroxsolutions/zeroxsolutions/commit/5c57b3a))
+- ⚠️ **query,response,server:** one wire spelling, flat exports ([5c57b3a](https://github.com/zeroxsolutions/zeroxsolutions/commit/5c57b3a))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **query,response,server:** one wire spelling, flat exports  ([5c57b3a](https://github.com/zeroxsolutions/zeroxsolutions/commit/5c57b3a))
+- **query,response,server:** one wire spelling, flat exports ([5c57b3a](https://github.com/zeroxsolutions/zeroxsolutions/commit/5c57b3a))
   `@zeroxsolutions/response/http`, `@zeroxsolutions/query/http`
   and `@zeroxsolutions/server/hono/http` are gone, and the surviving `/jsonapi`
   and `/hono` subpaths move to the package root. Every import drops its subpath.
@@ -145,11 +156,11 @@ This was a version bump only for @zeroxsolutions/jsonapi to align it with other
 
 ### 💅 Refactors
 
-- ⚠️  **jsonapi:** widen negotiation, move its middleware out ([d28eb2b](https://github.com/zeroxsolutions/zeroxsolutions/commit/d28eb2b))
+- ⚠️ **jsonapi:** widen negotiation, move its middleware out ([d28eb2b](https://github.com/zeroxsolutions/zeroxsolutions/commit/d28eb2b))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **jsonapi:** widen negotiation, move its middleware out  ([d28eb2b](https://github.com/zeroxsolutions/zeroxsolutions/commit/d28eb2b))
+- **jsonapi:** widen negotiation, move its middleware out ([d28eb2b](https://github.com/zeroxsolutions/zeroxsolutions/commit/d28eb2b))
   jsonApiContentNegotiation is no longer exported here; it is
   @zeroxsolutions/server. negotiateJsonApi answers 415 for any
   Content-Type that is not the JSON:API media type, and 406 for an Accept naming
@@ -197,12 +208,12 @@ This was a version bump only for @zeroxsolutions/jsonapi to align it with other
 
 ### 🩹 Fixes
 
-- ⚠️  **jsonapi:** shape the collection model on the document, not the other spelling ([4ae8d26](https://github.com/zeroxsolutions/zeroxsolutions/commit/4ae8d26))
+- ⚠️ **jsonapi:** shape the collection model on the document, not the other spelling ([4ae8d26](https://github.com/zeroxsolutions/zeroxsolutions/commit/4ae8d26))
 - **jsonapi:** add the reader source the previous commit left untracked ([7399114](https://github.com/zeroxsolutions/zeroxsolutions/commit/7399114))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **jsonapi:** shape the collection model on the document, not the other spelling  ([4ae8d26](https://github.com/zeroxsolutions/zeroxsolutions/commit/4ae8d26))
+- **jsonapi:** shape the collection model on the document, not the other spelling ([4ae8d26](https://github.com/zeroxsolutions/zeroxsolutions/commit/4ae8d26))
   `Collection.items` is `Collection.data`, and `Collection.total`
   is gone - read `meta` for it.
 
@@ -306,12 +317,12 @@ This was a version bump only for @zeroxsolutions/jsonapi to align it with other
 
 ### 🚀 Features
 
-- ⚠️  **jsonapi:** bind the permit-list to a row and an operator vocabulary, and pipe the schema through it ([5f824d0](https://github.com/zeroxsolutions/zeroxsolutions/commit/5f824d0))
+- ⚠️ **jsonapi:** bind the permit-list to a row and an operator vocabulary, and pipe the schema through it ([5f824d0](https://github.com/zeroxsolutions/zeroxsolutions/commit/5f824d0))
 - **jsonapi:** declare a list endpoint's query parameters from its permit-list ([bb3c3c8](https://github.com/zeroxsolutions/zeroxsolutions/commit/bb3c3c8))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **jsonapi:** bind the permit-list to a row and an operator vocabulary, and pipe the schema through it  ([5f824d0](https://github.com/zeroxsolutions/zeroxsolutions/commit/5f824d0))
+- **jsonapi:** bind the permit-list to a row and an operator vocabulary, and pipe the schema through it ([5f824d0](https://github.com/zeroxsolutions/zeroxsolutions/commit/5f824d0))
   `jsonApiQuerySchema` now returns a piped schema whose output is
   `GuardedJsonApiQuery`, not the raw query map. Unreleased, so no consumer is affected.
   The two type-level checks are pinned by `@ts-expect-error` in a spec, watched failing
@@ -339,11 +350,11 @@ This was a version bump only for @zeroxsolutions/jsonapi to align it with other
 
 ### 🚀 Features
 
-- ⚠️  **jsonapi:** shape the document by the query, and close the escape hatch ([79da0f2](https://github.com/zeroxsolutions/zeroxsolutions/commit/79da0f2))
+- ⚠️ **jsonapi:** shape the document by the query, and close the escape hatch ([79da0f2](https://github.com/zeroxsolutions/zeroxsolutions/commit/79da0f2))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **jsonapi:** shape the document by the query, and close the escape hatch  ([79da0f2](https://github.com/zeroxsolutions/zeroxsolutions/commit/79da0f2))
+- **jsonapi:** shape the document by the query, and close the escape hatch ([79da0f2](https://github.com/zeroxsolutions/zeroxsolutions/commit/79da0f2))
   `customFamilies` removed from `JsonApiQuerySpec`, its
   argument removed from `unprocessableQueryParams`, and `isCustomFamilyBase` no
   longer exported. No declaration can accept a parameter outside the families
@@ -358,13 +369,13 @@ This was a version bump only for @zeroxsolutions/jsonapi to align it with other
 
 ### 🚀 Features
 
-- ⚠️  **jsonapi:** bind the list query to a permit-list and parse the filter tree ([2c212b0](https://github.com/zeroxsolutions/zeroxsolutions/commit/2c212b0))
+- ⚠️ **jsonapi:** bind the list query to a permit-list and parse the filter tree ([2c212b0](https://github.com/zeroxsolutions/zeroxsolutions/commit/2c212b0))
 - **jsonapi:** screen query parameters against the standard's grammar ([e7bd26c](https://github.com/zeroxsolutions/zeroxsolutions/commit/e7bd26c))
 - **jsonapi:** refuse a query the endpoint did not permit ([1dd1df6](https://github.com/zeroxsolutions/zeroxsolutions/commit/1dd1df6))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- **jsonapi:** bind the list query to a permit-list and parse the filter tree  ([2c212b0](https://github.com/zeroxsolutions/zeroxsolutions/commit/2c212b0))
+- **jsonapi:** bind the list query to a permit-list and parse the filter tree ([2c212b0](https://github.com/zeroxsolutions/zeroxsolutions/commit/2c212b0))
   `parseJsonApiQuery` and `parseFilter` are removed;
   `filterable` entries are `{ operators, type }` rather than a bare operator
   list; `filter` is a bracketed family, not a JSON-encoded array; queries
@@ -420,11 +431,11 @@ This was a version bump only for @zeroxsolutions/jsonapi to align it with other
 
 ### 🚀 Features
 
-- ⚠️  add JSON:API v1.1 toolkit and routing lib, dissolve common ([53545a6](https://github.com/zeroxsolutions/zeroxsolutions/commit/53545a6))
+- ⚠️ add JSON:API v1.1 toolkit and routing lib, dissolve common ([53545a6](https://github.com/zeroxsolutions/zeroxsolutions/commit/53545a6))
 
-### ⚠️  Breaking Changes
+### ⚠️ Breaking Changes
 
-- add JSON:API v1.1 toolkit and routing lib, dissolve common  ([53545a6](https://github.com/zeroxsolutions/zeroxsolutions/commit/53545a6))
+- add JSON:API v1.1 toolkit and routing lib, dissolve common ([53545a6](https://github.com/zeroxsolutions/zeroxsolutions/commit/53545a6))
   @zeroxsolutions/common is removed. Its error/response
   schemas move to @zeroxsolutions/jsonapi; its path/is-match helpers move to
   @zeroxsolutions/routing.
@@ -432,4 +443,4 @@ This was a version bump only for @zeroxsolutions/jsonapi to align it with other
 ### ❤️ Thank You
 
 - Claude Opus 4.8 (1M context)
-- Lương Văn Tú
+- Lương Văn Tú

package/README.md

@@ -1,7 +1,7 @@
 # @zeroxsolutions/jsonapi
 
 The [JSON:API v1.1](https://jsonapi.org/) halves that are **not** a response body: content negotiation
-on the request, and document deserialization on the client.
+on the request, the finder options a guarded query reads as, and document deserialization on the client.
 
 Everything a server puts _in_ a response - the document schemas, the serializers, the `errors[]`
 document - is `@zeroxsolutions/response`, and the central `onError` that renders it is
@@ -18,16 +18,16 @@ asks for, what the server answers, and what the caller may address.
 pnpm add @zeroxsolutions/jsonapi @zeroxsolutions/response
 ```
 
-No peer dep, and no framework: every export here is a plain function over strings and documents. The
+No peer dep, and no framework: every export here is a plain function over strings, queries and documents. The
 Hono middleware that mounts the negotiation decision is `@zeroxsolutions/server`, which is
 what keeps `hono` out of the package an SPA also loads.
 
 ## Entry points
 
-| Import                           | Use in                  | What it holds                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| -------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@zeroxsolutions/jsonapi`        | services, gateway       | `negotiateJsonApi` - the whole decision, from `Content-Type`, `Accept` and the `ext` URIs this surface supports (`supportedExtensions`), to the `JsonApiError` to reject with or `null`: 415 where `Content-Type` is the JSON:API media type carrying a parameter beyond `ext`/`profile` or an `ext` outside `supportedExtensions`; 406 where `Accept` holds JSON:API instances and every one carries such a parameter or `ext`; nothing else |
-| `@zeroxsolutions/jsonapi/client` | SPA, external consumers | `deserializeDocument` (jsona), `readResource` / `readCollection` over it - the same flattening, typed off the route's own document - `readRelated` for what an `include` resolved, which no document type can name; `toRequestDocument`, the JSON:API request document a write sends, each relationship wrapped in its relationship object; and `ApiError`, the non-2xx a caller throws once a response has come back                         |
+| Import                           | Use in                  | What it holds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| -------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@zeroxsolutions/jsonapi`        | services, gateway       | `negotiateJsonApi` - the whole decision, from `Content-Type`, `Accept` and the `ext` URIs this surface supports (`supportedExtensions`), to the `JsonApiError` to reject with or `null`: 415 where `Content-Type` is the JSON:API media type carrying a parameter beyond `ext`/`profile` or an `ext` outside `supportedExtensions`; 406 where `Accept` holds JSON:API instances and every one carries such a parameter or `ext`; nothing else. `findOptionsOf` - a guarded query to the options `@zeroxsolutions/db`'s finders take |
+| `@zeroxsolutions/jsonapi/client` | SPA, external consumers | `deserializeDocument` (jsona), `readResource` / `readCollection` over it - the same flattening, typed off the route's own document - `readRelated` for what an `include` resolved, which no document type can name; `toRequestDocument`, the JSON:API request document a write sends, each relationship wrapped in its relationship object; and `ApiError`, the non-2xx a caller throws once a response has come back                                                                                                               |
 
 A transport mounts the decision rather than calling it: `jsonApiContentNegotiation` is the Hono adapter
 over it, and it lives with the other framework wiring. `negotiateJsonApi` itself takes the surface's
@@ -74,3 +74,30 @@ The decision is the four server rules of JSON:API v1.1 and nothing more:
   names `Content-Type`, or one fewer usable member in `Accept`, which is a 406 where none is left.
   `supportedExtensions` is `negotiateJsonApi`'s fourth parameter: the extension URIs this surface answers
   `ext` requests for, empty by default, which refuses every `ext`.
+
+## A guarded query as a finder's options
+
+`findOptionsOf(query, permits)` turns the query `@zeroxsolutions/query`'s guard answered into the options a base
+repository's finder takes, so no route writes a converter of its own. It is called from the controller, and the
+finder hands the options to the base unchanged:
+
+```ts
+import { findOptionsOf } from '@zeroxsolutions/jsonapi';
+
+const options = findOptionsOf(c.req.valid('query'), placesQueryPermits); // { read, filter, orderBy, limit, offset }
+const [rows, total] = await placesRepository.findAllAndCountByTenantId(tenantId, options);
+```
+
+A read-one query answers `{ read }` alone. The permits name the `type` the read starts from and the `relationships`
+`relationsOf` answers in `@zeroxsolutions/db/utils`; it throws on permits naming no `type`. The `read` is built so:
+
+| The guarded query holds                      | The read loads                                                                 |
+| -------------------------------------------- | ------------------------------------------------------------------------------ |
+| a column in the type's fieldset              | that column                                                                    |
+| a relationship in the fieldset, not included | the related row's primary key, which is the linkage its relationship publishes |
+| a facet (`facets`) in the fieldset           | that relation under its own type's fieldset, exactly                           |
+| an `include` path                            | every relation on it, each under its type's fieldset and its primary key       |
+| a computed name given a `ComputedRead`       | the columns and relations it names, whatever the fieldset asked                |
+
+The filter, the order and the page window pass through unchanged. The package depends on `@zeroxsolutions/query`
+alone: the read names are strings, and `@zeroxsolutions/db` refuses one its table does not hold with `UnknownReadName`.

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { negotiateJsonApi } from './lib/negotiation/index.js';
+export { findOptionsOf, type CollectionFindOptions, type ReadOf, type ResourceFindOptions, } from './lib/find-options/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EACL,aAAa,EACb,KAAK,qBAAqB,EAC1B,KAAK,MAAM,EACX,KAAK,mBAAmB,GACzB,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -1 +1,2 @@
 export { negotiateJsonApi } from './lib/negotiation/index.js';
+export { findOptionsOf, } from './lib/find-options/index.js';

package/dist/lib/find-options/find-options-of.d.ts

@@ -0,0 +1,41 @@
+import type { FilterTree, PermittedCollectionQuery, PermittedResourceQuery, ResourceQueryPermits, SortField } from '@zeroxsolutions/query';
+/**
+ * What one level of a read loads, in the shape a base finder of `@zeroxsolutions/db` takes: columns absent load every
+ * column, and a relation named under `relations` loads under its own read.
+ */
+export interface ReadOf {
+    columns?: string[];
+    relations?: Record<string, ReadOf>;
+}
+/** The finder options a guarded read-one query asks for. */
+export interface ResourceFindOptions {
+    read: ReadOf;
+}
+/** The finder options a guarded collection query asks for: the read, and its filter, order and page window. */
+export interface CollectionFindOptions<Leaf> extends ResourceFindOptions {
+    filter: FilterTree<Leaf>[];
+    orderBy: SortField[];
+    offset: number;
+    limit: number;
+}
+/**
+ * The finder options a guarded query asks for, built off the permits that guarded it: one function for every entity,
+ * so no context declares a converter of its own.
+ *
+ * | The guarded query holds | The options carry |
+ * | --- | --- |
+ * | `fields[<type>]` naming columns | those columns in `read` |
+ * | a relationship in a fieldset, not included | that relation in `read` with its primary key alone, the linkage it publishes |
+ * | an `include` path | every relation on it in `read`, each under its own type's fieldset and its primary key |
+ * | a facet in a fieldset | that relation in `read` with exactly the columns its own type's fieldset names |
+ * | `filter`, `sort`, `offset`, `limit` | `filter`, `orderBy`, `offset` and `limit`, unchanged |
+ *
+ * Each computed attribute the permits map to a read loads that read on every query, whatever fieldset was sent.
+ *
+ * @param permits - the permits the query was guarded under; its `type` names the root type and its `relationships`
+ *   (from `relationsOf` in `@zeroxsolutions/db/utils`) what each relationship reaches
+ * @throws Error when the permits name no `type`, or an include path a relationship of theirs does not reach
+ */
+export declare function findOptionsOf<Leaf, P extends ResourceQueryPermits>(query: PermittedCollectionQuery<Leaf, P>, permits: P): CollectionFindOptions<Leaf>;
+export declare function findOptionsOf<P extends ResourceQueryPermits>(query: PermittedResourceQuery<P>, permits: P): ResourceFindOptions;
+//# sourceMappingURL=find-options-of.d.ts.map

package/dist/lib/find-options/find-options-of.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-options-of.d.ts","sourceRoot":"","sources":["../../../src/lib/find-options/find-options-of.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,UAAU,EACV,wBAAwB,EACxB,sBAAsB,EAEtB,oBAAoB,EACpB,SAAS,EACV,MAAM,uBAAuB,CAAC;AAE/B;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,+GAA+G;AAC/G,MAAM,WAAW,qBAAqB,CAAC,IAAI,CAAE,SAAQ,mBAAmB;IACtE,MAAM,EAAE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;IAC3B,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AA4FD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,CAAC,SAAS,oBAAoB,EAChE,KAAK,EAAE,wBAAwB,CAAC,IAAI,EAAE,CAAC,CAAC,EACxC,OAAO,EAAE,CAAC,GACT,qBAAqB,CAAC,IAAI,CAAC,CAAC;AAC/B,wBAAgB,aAAa,CAAC,CAAC,SAAS,oBAAoB,EAC1D,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,EAChC,OAAO,EAAE,CAAC,GACT,mBAAmB,CAAC"}

package/dist/lib/find-options/find-options-of.js

@@ -0,0 +1,86 @@
+function includeTreeOf(paths) {
+    const root = {};
+    for (const path of paths ?? []) {
+        let level = root;
+        for (const segment of path.split('.'))
+            level = level[segment] ??= {};
+    }
+    return root;
+}
+/** `a` and `b` joined, each name once, in the order they were first named. */
+const union = (a, b) => [...new Set([...a, ...b])];
+/**
+ * Adds what a computed attribute is computed from to a level. Columns join where both name some; a level that names
+ * none already loads every column, and a computed read naming none adds nothing to a level that names some.
+ */
+function mergeComputed(level, computed) {
+    if (computed.columns !== undefined && level.columns !== undefined)
+        level.columns = union(level.columns, computed.columns);
+    for (const [name, nested] of Object.entries(computed.relations ?? {})) {
+        level.relations ??= {};
+        const existing = level.relations[name];
+        if (existing) {
+            mergeComputed(existing, nested);
+            continue;
+        }
+        const added = nested.columns === undefined ? {} : { columns: [...nested.columns] };
+        level.relations[name] = added;
+        mergeComputed(added, { relations: nested.relations });
+    }
+}
+/**
+ * One level of the read: its fieldset's columns, the linkage of each relationship it names, each facet under its own
+ * table's fieldset, each included relation under its own type's fieldset, and what its computed attributes need.
+ */
+function levelOf(walk, type, relations, include, path) {
+    const level = {};
+    const fieldset = walk.fields[type];
+    const facets = new Set(walk.permits.facets?.[type] ?? []);
+    if (fieldset !== undefined) {
+        level.columns = fieldset.filter((name) => !Object.hasOwn(relations, name));
+        for (const name of fieldset) {
+            const target = Object.hasOwn(relations, name) ? relations[name] : undefined;
+            if (!target)
+                continue;
+            level.relations ??= {};
+            const facetColumns = walk.fields[target.type];
+            level.relations[name] = facets.has(name)
+                ? facetColumns === undefined
+                    ? {}
+                    : { columns: [...facetColumns] }
+                : { columns: [...target.primaryKey] };
+        }
+    }
+    for (const [name, below] of Object.entries(include)) {
+        const target = Object.hasOwn(relations, name) ? relations[name] : undefined;
+        if (!target)
+            throw new Error(`"${path}${name}" names no relationship the permits' relationships declare.`);
+        const included = levelOf(walk, target.type, target.relations, below, `${path}${name}.`);
+        // An included resource publishes its id, which its type's fieldset never names.
+        if (included.columns !== undefined)
+            included.columns = union(target.primaryKey, included.columns);
+        level.relations ??= {};
+        level.relations[name] = included;
+    }
+    const computed = walk.permits.computed?.[type];
+    if (computed !== undefined && !Array.isArray(computed)) {
+        for (const read of Object.values(computed))
+            mergeComputed(level, read);
+    }
+    return level;
+}
+export function findOptionsOf(query, permits) {
+    if (permits.type === undefined)
+        throw new Error('The permits name no `type` for the read to start from.');
+    const walk = { fields: query.fields, permits };
+    const read = levelOf(walk, permits.type, permits.relationships ?? {}, includeTreeOf(query.include), '');
+    if (query.limit === undefined)
+        return { read };
+    return {
+        read,
+        filter: query.filter ?? [],
+        orderBy: query.sort ?? [],
+        offset: query.offset ?? 0,
+        limit: query.limit,
+    };
+}

package/dist/lib/find-options/index.d.ts

@@ -0,0 +1,2 @@
+export * from './find-options-of.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/find-options/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/find-options/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/dist/lib/find-options/index.js

@@ -0,0 +1 @@
+export * from './find-options-of.js';

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zeroxsolutions/jsonapi",
-  "version": "0.13.2",
+  "version": "0.13.3",
   "private": false,
   "type": "module",
   "sideEffects": false,
-  "description": "The JSON:API halves that are not the response body: v1.1 content negotiation (media type, 415/406/400) and the client-side document deserializer. The response document, its serializers and its error document live in @zeroxsolutions/response.",
+  "description": "The JSON:API halves that are not the response body: v1.1 content negotiation (media type, 415/406/400), findOptionsOf from a guarded query to a finder's options, and the client-side document deserializer. The response document, its serializers and its error document live in @zeroxsolutions/response.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -30,6 +30,7 @@
   "dependencies": {
     "jsona": "^1.12.0",
     "tslib": "^2.3.0",
+    "@zeroxsolutions/query": "0.7.4",
     "@zeroxsolutions/response": "0.14.4"
   }
 }