@quadrokit/client 0.2.13 → 0.3.0

package/README.md

@@ -1,47 +1,219 @@
 # `@quadrokit/client`
 
-Typed **4D REST** helper: small runtime (`fetch` with `credentials: 'include'`, paging, [`$attributes`](https://developer.4d.com/docs/REST/attributes)) plus a **code generator** that turns a catalog JSON into `.quadrokit/generated`.
+Typed [**4D REST**](https://developer.4d.com/docs/REST/REST_requests) client: a small runtime (`fetch` with `credentials: 'include'`, lists, entity sets, [`$attributes`](https://developer.4d.com/docs/REST/attributes)) and a **code generator** that turns a catalog JSON into a typed `createClient` and entity types.
+
+---
 
 ## Install
 
 ```bash
+npm add @quadrokit/client
+# or
 bun add @quadrokit/client
 ```
 
-## CLI: `quadrokit-client`
+The package exposes:
+
+- **`@quadrokit/client`** — runtime + types (and anything your generated code needs).
+- **`@quadrokit/client/runtime`** — low-level helpers if you build custom integrations.
+
+---
+
+## Generate the client from your 4D catalog
 
-After install, the binary name is **`quadrokit-client`** (not the scoped package name):
+Install adds the **`quadrokit-client`** binary (alias: **`quadrokit`**).
 
 ```bash
 bunx quadrokit-client generate \
   --url 'http://localhost:7080/rest/$catalog/$all' \
-  --token YOUR_TOKEN \
   --out .quadrokit/generated
 ```
 
-- **`--url`**: HTTP(S) catalog URL or `file:///absolute/path/to/catalog.json`. Use **`/rest/$catalog/$all`** so the JSON includes dataclass **attributes**; plain `/rest/$catalog` only lists names (empty types). Defaults to `${VITE_4D_ORIGIN}/rest/$catalog/$all`.
-- **`--token`**: optional `Authorization: Bearer …` for protected catalog endpoints
-- **`--out`**: output directory (default `.quadrokit/generated`)
+### Why `$catalog/$all`?
+
+Use a URL that returns the **full** catalog (dataclasses **with attributes**). Plain [`/rest/$catalog`](https://developer.4d.com/docs/REST/catalog) often lists tables only; without attribute metadata, generated `select` paths and typings are incomplete. The generator warns if attributes are missing.
+
+### CLI options
+
+| Option | Description |
+|--------|-------------|
+| **`--url`** | Catalog URL, or `file:///absolute/path/to/catalog.json`. If omitted: `${VITE_4D_ORIGIN}/rest/$catalog/$all` (from env / `.env`), else `http://127.0.0.1:7080/rest/$catalog/$all`. |
+| **`--out`** | Output directory (default: `.quadrokit/generated`). |
+| **`--token`** | `Authorization: Bearer …` for protected catalog endpoints (generator HTTP only). |
+| **`--access-key`** | Multipart `accessKey` to 4D’s login API; generator obtains `4DAdminSID` and uses it for the catalog request. Requires an `http(s)` `--url` unless you pass **`--login-url`**. |
+| **`--login-url`** | Full login URL (default: `{catalog origin}/api/login`). |
+| **`-v` / `--verbose`** | Step-by-step logs on stderr. |
+| **`--insecure-tls`** | Skip TLS verification (dev / self-signed HTTPS only). |
+
+Environment variables (often via `.env` in the project root): `VITE_4D_ORIGIN`, `QUADROKIT_ACCESS_KEY`, `QUADROKIT_LOGIN_URL`, `QUADROKIT_CATALOG_TOKEN`, `QUADROKIT_GENERATE_VERBOSE`, `QUADROKIT_INSECURE_TLS`.
+
+### Generated files
+
+| File | Purpose |
+|------|---------|
+| **`types.gen.ts`** | Entity interfaces and `*Path` unions for typed `select`. |
+| **`client.gen.ts`** | `createClient(config)` — dataclass APIs, optional `authentify`, `rpc`, `quadrokitCatalogMeta`. |
+| **`meta.json`** | `__NAME`, `sessionCookieName` hint for 4D session cookies. |
+
+Point your app imports at the generated folder, for example:
+
+```ts
+import { createClient } from './.quadrokit/generated/client.gen.js'
+import type { Agency } from './.quadrokit/generated/types.gen.js'
+```
+
+---
+
+## Creating the client
+
+```ts
+import { createClient } from './.quadrokit/generated/client.gen.js'
+
+const quadro = createClient({
+  /** Base URL of the REST root, e.g. `https://host:port/rest` or `/rest` behind a dev proxy */
+  baseURL: import.meta.env.VITE_4D_REST_URL ?? '/rest',
+  /** Optional: swap `fetch` (e.g. tests, Node with undici) */
+  fetchImpl: globalThis.fetch,
+  /** Optional: default headers on every request */
+  defaultHeaders: { Authorization: `Bearer ${token}` },
+})
+```
+
+At runtime, requests use **`credentials: 'include'`** so session cookies (e.g. `4DSID_<datastore>`) are sent when your app and 4D share the same site or proxy. See `meta.json` → `sessionCookieName` after generate.
+
+---
+
+## Dataclass API (generated)
+
+For each exposed dataclass, the client exposes a namespace such as `quadro.Agency`, `quadro.Reservation`, etc.
+
+### `all(options?)` — full class as an async iterable “collection”
+
+Walk entities with optional **`select`**, **`filter`**, **`orderby`**, paging, and 4D **entity sets** (`$method=entityset`) for efficient paging.
+
+```ts
+const col = quadro.Agency.all({
+  select: ['ID', 'name', 'department.name'] as const,
+  filter: 'name = "Paris"',
+  page: 1,
+  pageSize: 50,
+  signal: ac.signal,
+})
+
+for await (const agency of col) {
+  console.log(agency.name)
+}
+
+await col.release() // release server entity set when done (see 4D $method=release)
+```
+
+Important options (see `CollectionOptions` in `@quadrokit/client/runtime`):
 
-## Generated output
+| Option | Role |
+|--------|------|
+| **`select`** | [`$attributes`](https://developer.4d.com/docs/REST/attributes): scalar or relation paths (`'manager.name'`). |
+| **`filter` / `orderby`** | OData-style list constraints. |
+| **`page` / `pageSize`** | Client-side paging over the list / entity set. |
+| **`maxItems`** | Stop iteration after N rows. |
+| **`signal`** | `AbortController` — abort in-flight requests when unmounting or changing filters. |
+| **`reuseEntitySet` / `onEntitySetReady`** | Reuse a cached entity-set URI across requests (see your app’s paging hooks). |
 
-- `types.gen.ts` — entity interfaces and `*Path` unions for `select`
-- `client.gen.ts` — `createClient({ baseURL })` with dataclasses, `authentify.login` when present in catalog, and `rpc()` escape hatch
-- `meta.json` — catalog `__NAME`, `sessionCookieName` hint
+### `query(filter, options?)`
 
-## Runtime imports
+Same shape as `all`, but with a **`filter`** string as the first argument (and optional `params` for `:1`, `:2`, … placeholders in the filter).
 
-Apps and generated code import low-level pieces from:
+### `get(id, options?)`
+
+Load one entity by primary key; optional **`select`** for `$attributes`.
+
+### `delete(id)`
+
+`DELETE` the entity.
+
+### Related entities on a row
+
+Mapped rows get non-enumerable properties for **related collections** (e.g. `agency.todayBookings`) with a **`.list(options)`** that returns another collection handle for the child dataclass.
+
+---
+
+## ORDA class functions (generated from catalog)
+
+If your 4D project exposes methods in the REST catalog, the generator wires them by `applyTo` (see [Calling class functions](https://developer.4d.com/docs/REST/classFunctions.html)):
+
+| Catalog `applyTo` | Where it appears in JS | REST shape (simplified) |
+|-------------------|-------------------------|-------------------------|
+| **`dataClass`** | `quadro.Agency.agencyStats<R>(args, init?)` | `POST /rest/{Class}/{function}` with JSON array body |
+| **`entityCollection`** | On **`all()` / `query()`** handles and on related `{ list, … }` APIs | `POST /rest/{Class}/{function}` + optional `selection`, `entitySet` |
+| **`entity`** | On each **mapped entity** row | `POST /rest/{Class}({key})/{function}` |
+
+- **`args`**: `readonly unknown[]` — 4D receives a **JSON array** of parameters (scalars, entities, entity selections per 4D rules).
+- **`init`**: optional `{ method: 'GET' \| 'POST', unwrapResult?, signal?, … }` — GET uses `?$params=…` for [HTTP GET functions](https://developer.4d.com/docs/ORDA/ordaClasses#onhttpget-keyword).
+- **`unwrapResult`**: when `true` (default), `{ "result": x }` responses are unwrapped to `x`.
+
+Entity-selection methods accept **`EntityCollectionMethodOptions`**:
+
+- **`selection`**: `{ filter?, orderby?, select?, page?, pageSize? }` → `$filter`, `$orderby`, `$attributes`, `$skip`, `$top`.
+- **`entitySet`**: UUID or path segment so the URL includes `…/$entityset/{uuid}`.
+
+Example:
 
 ```ts
-import { QuadroHttp, type SelectedEntity } from '@quadrokit/client/runtime';
+const stats = await quadro.Agency.agencyStats<MyStatsRow>([from, to])
+
+const col = quadro.Reservation.all({ pageSize: 20 })
+// After the handle exists, e.g. from a hook or manual create:
+await col.getFirst?.([], { selection: { filter: 'ID > 0', pageSize: 1 } })
+
+await reservation.cancel<{ ok: boolean }>([], { signal: ac.signal })
 ```
 
-The main entry re-exports the runtime barrel.
+If the catalog does not list a method, it will not appear on the client — regenerate after changing 4D exposure.
+
+---
 
-## Dev in this monorepo
+## Low-level runtime (advanced)
+
+Import from **`@quadrokit/client/runtime`** when you need primitives without codegen:
+
+| Export | Use |
+|--------|-----|
+| **`QuadroHttp`** | Thin wrapper: `json()`, `void()`, `request()` with base URL + default headers. |
+| **`createCollection`** | Build a `CollectionHandle` from a `CollectionContext` + options + row mapper. |
+| **`callDataClassFunction`**, **`callEntityFunction`**, **`callEntityCollectionFunction`** | Call ORDA functions by name and path (same REST rules as above). |
+| **`callDatastorePath`**, **`createClient`’s `rpc`** | Arbitrary segments under the REST root, e.g. datastore or singleton paths. |
+| **`buildListSearchParams`**, **`buildMethodSelectionQuery`**, … | Query-string helpers aligned with 4D. |
+| **`QuadroHttpError`** | Thrown on non-OK HTTP with status and body text. |
+
+The generated `createClient` is the recommended surface; these are for tooling, tests, or custom wrappers.
+
+---
+
+## Errors
+
+Failed HTTP responses throw **`QuadroHttpError`** (status + response body). Handle network errors separately (`fetch` failures).
+
+---
+
+## Monorepo development
+
+From `packages/client`:
 
 ```bash
 bun run typecheck
-bun run src/cli.ts generate --url file://../../assets/catalog.json --out ../../.quadrokit/generated
+bun run build
+```
+
+Example generate from the fixture catalog (adjust `file://` to an absolute path on your machine):
+
+```bash
+bun run src/cli.ts generate --url file:///ABS/path/to/assets/catalog.json --out ../../.quadrokit/generated-demo
 ```
+
+---
+
+## Further reading
+
+- [4D REST requests](https://developer.4d.com/docs/REST/REST_requests)
+- [REST `$attributes`](https://developer.4d.com/docs/REST/attributes)
+- [REST `$method` (entity set, release, …)](https://developer.4d.com/docs/REST/method)
+- [Calling class functions (ORDA)](https://developer.4d.com/docs/REST/classFunctions.html)

package/dist/generate/codegen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/generate/codegen.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAsC,WAAW,EAAE,MAAM,mBAAmB,CAAA;AA0UxF,uIAAuI;AACvI,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAYvE;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBxF"}
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/generate/codegen.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAsC,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAmXxF,uIAAuI;AACvI,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAYvE;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBxF"}

package/dist/generate/codegen.mjs

@@ -108,6 +108,13 @@ function emitInterface(dc, _byName) {
 function exposedDataClasses(catalog) {
     return catalog.dataClasses?.filter((d) => d.exposed !== false) ?? [];
 }
+/** ORDA catalog methods by `applyTo` (4D: dataClass, entityCollection, entity). */
+function methodsForApply(dc, applyTo) {
+    if (!dc) {
+        return [];
+    }
+    return (dc.methods ?? []).filter((m) => m.applyTo === applyTo && m.exposed !== false);
+}
 function emitTypes(catalog) {
     const classes = exposedDataClasses(catalog);
     const byName = new Map(classes.map((c) => [c.name, c]));
@@ -130,16 +137,18 @@ function emitTypes(catalog) {
 }
 function emitClient(catalog) {
     const classes = exposedDataClasses(catalog);
+    const byName = new Map(classes.map((c) => [c.name, c]));
     const dbName = catalog.__NAME ?? 'default';
     const hasAuthentify = catalog.methods?.some((m) => m.name === 'authentify' && m.applyTo === 'dataStore');
     const keyNamesRecord = Object.fromEntries(classes.map((x) => [x.name, keyNames(x)]));
     const imports = classes.length > 0
-        ? `/* eslint-disable */\n/* Auto-generated by @quadrokit/client — do not edit */\n\nimport {\n  QuadroHttp,\n  makeDataClassApi,\n  attachRelatedApis,\n  callDatastorePath,\n  type CollectionHandle,\n  type CollectionOptions,\n  type SelectedEntity,\n} from '@quadrokit/client/runtime';\n`
+        ? `/* eslint-disable */\n/* Auto-generated by @quadrokit/client — do not edit */\n\nimport {\n  QuadroHttp,\n  makeDataClassApi,\n  attachRelatedApis,\n  attachEntityClassMethods,\n  bindEntityCollectionMethods,\n  callDataClassFunction,\n  callDatastorePath,\n  type ClassFunctionHttpOptions,\n  type CollectionHandle,\n  type CollectionOptions,\n  type SelectedEntity,\n} from '@quadrokit/client/runtime';\n`
         : `/* eslint-disable */\n/* Auto-generated by @quadrokit/client — do not edit */\n\nimport { QuadroHttp, callDatastorePath } from '@quadrokit/client/runtime';\n`;
     const typeImports = classes.map((c) => c.name).join(', ');
     const pathImports = classes.map((c) => `${c.name}Path`).join(', ');
     const typeImportLine = typeImports || pathImports
-        ? `\nimport type { ${[typeImports, pathImports].filter(Boolean).join(', ')} } from './types.gen.mjs';\n\n`
+        ? // Split so `rename-dist-js-to-mjs` does not rewrite this *emitted* import to `.mjs`.
+            `\nimport type { ${[typeImports, pathImports].filter(Boolean).join(', ')} } from './types.gen';\n\n`
         : '\n';
     const header = `${imports}${typeImportLine}`;
     const metaExport = `
@@ -159,9 +168,26 @@ export interface QuadroClientConfig {
         .map((c) => {
         const nav = navigableRelations(c);
         const relMap = JSON.stringify(relationTargets(c));
+        const kn = JSON.stringify(keyNames(c));
+        const ecNav = nav.map((n) => ({
+            attr: n.attr,
+            targetClass: n.targetClass,
+            entityCollectionMethodNames: methodsForApply(byName.get(n.targetClass), 'entityCollection').map((m) => m.name),
+        }));
+        const entityMethodNames = methodsForApply(c, 'entity').map((m) => m.name);
         return `  function map${c.name}Row(http: QuadroHttp, raw: unknown): ${c.name} {
     const row = raw as ${c.name};
     const pk = (row as { ID?: number }).ID ?? (row as { id?: number }).id;
+    attachEntityClassMethods(
+      raw,
+      {
+        http,
+        className: '${c.name}',
+        relationMap: ${relMap},
+        keyNames: ${kn},
+      },
+      ${JSON.stringify(entityMethodNames)},
+    );
     attachRelatedApis(
       raw,
       {
@@ -171,7 +197,7 @@ export interface QuadroClientConfig {
         relationMap: ${relMap},
         keyNames: ${JSON.stringify(keyNamesRecord)},
       },
-      ${JSON.stringify(nav)},
+      ${JSON.stringify(ecNav)},
     );
     return row;
   }`;
@@ -182,6 +208,12 @@ export interface QuadroClientConfig {
         const relMap = JSON.stringify(relationTargets(c));
         const kn = JSON.stringify(keyNames(c));
         const pathsType = `${c.name}Path`;
+        const ecNames = JSON.stringify(methodsForApply(c, 'entityCollection').map((m) => m.name));
+        const dcBlock = methodsForApply(c, 'dataClass')
+            .map((m) => `        ${m.name}: async <R = unknown>(args: readonly unknown[] = [], init?: ClassFunctionHttpOptions & { unwrapResult?: boolean }) =>
+          callDataClassFunction<R>(http, '${c.name}', '${m.name}', args, init),`)
+            .join('\n');
+        const dcPrefix = dcBlock ? `${dcBlock}\n` : '';
         return `    ${c.name}: (() => {
       const cfg = {
         http,
@@ -191,10 +223,11 @@ export interface QuadroClientConfig {
       } as const;
       const api = makeDataClassApi<${c.name}>(cfg);
       return {
-        all<S extends readonly ${pathsType}[] = readonly []>(
+${dcPrefix}        all<S extends readonly ${pathsType}[] = readonly []>(
           options?: CollectionOptions & { select?: S },
         ): CollectionHandle<S['length'] extends 0 ? ${c.name} : SelectedEntity<${c.name}, S>> {
           const inner = api.all(options as CollectionOptions);
+          bindEntityCollectionMethods(inner, { http, className: '${c.name}', relationMap: ${relMap} }, ${ecNames});
           return {
             ...inner,
             delete: inner.delete.bind(inner),
@@ -238,6 +271,7 @@ export interface QuadroClientConfig {
           options?: CollectionOptions & { params?: unknown[]; select?: S },
         ): CollectionHandle<S['length'] extends 0 ? ${c.name} : SelectedEntity<${c.name}, S>> {
           const inner = api.query(filter, options as CollectionOptions);
+          bindEntityCollectionMethods(inner, { http, className: '${c.name}', relationMap: ${relMap} }, ${ecNames});
           return {
             ...inner,
             delete: inner.delete.bind(inner),

package/dist/runtime/class-function.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ORDA class functions over REST ([4D docs](https://developer.4d.com/docs/REST/classFunctions.html)):
+ * dataclass, entity selection (entityCollection), and entity methods.
+ */
+import type { QuadroHttp } from './http.js';
+import { type MethodSelectionQuery } from './query.js';
+export type ClassFunctionHttpOptions = {
+    /** POST (default) or GET when the function is declared with `onHTTPGet`. */
+    method?: 'GET' | 'POST';
+    signal?: AbortSignal;
+};
+/** Unwrap `{ "result": ... }` when present; otherwise return the body as-is (e.g. entity payloads). */
+export declare function unwrapClassFunctionResult<T>(body: unknown): T;
+/**
+ * Dataclass class function: `POST /rest/{dataClass}/{function}` with a JSON array body.
+ * GET: `?$params=[...]` ([docs](https://developer.4d.com/docs/REST/classFunctions.html)).
+ */
+export declare function callDataClassFunction<T>(http: QuadroHttp, dataClass: string, functionName: string, args: readonly unknown[], options?: ClassFunctionHttpOptions & {
+    unwrapResult?: boolean;
+}): Promise<T>;
+/**
+ * Entity class function: `POST /rest/{dataClass}({key})/{function}`.
+ */
+export declare function callEntityFunction<T>(http: QuadroHttp, dataClass: string, entityKey: string | number, functionName: string, args: readonly unknown[], options?: ClassFunctionHttpOptions & {
+    unwrapResult?: boolean;
+}): Promise<T>;
+export type EntityCollectionMethodOptions = ClassFunctionHttpOptions & {
+    unwrapResult?: boolean;
+    /**
+     * Restrict the entity selection (`$filter`, `$orderby`, `$attributes`, `$skip` / `$top`).
+     * ([docs](https://developer.4d.com/docs/REST/classFunctions.html)).
+     */
+    selection?: MethodSelectionQuery;
+    /**
+     * Existing server entity set: UUID or `.../$entityset/{uuid}` suffix.
+     */
+    entitySet?: string;
+};
+/**
+ * Entity selection class function: `POST /rest/{dataClass}/{function}` with optional
+ * `/$entityset/{uuid}` and list query (`$filter`, `$orderby`, …).
+ */
+export declare function callEntityCollectionFunction<T>(http: QuadroHttp, dataClass: string, relationMap: Record<string, string>, functionName: string, args: readonly unknown[], options?: EntityCollectionMethodOptions): Promise<T>;
+//# sourceMappingURL=class-function.d.ts.map

package/dist/runtime/class-function.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"class-function.d.ts","sourceRoot":"","sources":["../../src/runtime/class-function.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,EAA6B,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAEjF,MAAM,MAAM,wBAAwB,GAAG;IACrC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;IACvB,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,CAAA;AAED,uGAAuG;AACvG,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,GAAG,CAAC,CAK7D;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,SAAS,OAAO,EAAE,EACxB,OAAO,CAAC,EAAE,wBAAwB,GAAG;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9D,OAAO,CAAC,CAAC,CAAC,CAoBZ;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAAG,MAAM,EAC1B,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,SAAS,OAAO,EAAE,EACxB,OAAO,CAAC,EAAE,wBAAwB,GAAG;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9D,OAAO,CAAC,CAAC,CAAC,CAqBZ;AAED,MAAM,MAAM,6BAA6B,GAAG,wBAAwB,GAAG;IACrE,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,oBAAoB,CAAA;IAChC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;GAGG;AACH,wBAAsB,4BAA4B,CAAC,CAAC,EAClD,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,SAAS,OAAO,EAAE,EACxB,OAAO,CAAC,EAAE,6BAA6B,GACtC,OAAO,CAAC,CAAC,CAAC,CA2BZ"}

package/dist/runtime/class-function.mjs

@@ -0,0 +1,93 @@
+import { buildMethodSelectionQuery } from './query.mjs';
+/** Unwrap `{ "result": ... }` when present; otherwise return the body as-is (e.g. entity payloads). */
+export function unwrapClassFunctionResult(body) {
+    if (body !== null && typeof body === 'object' && 'result' in body) {
+        return body.result;
+    }
+    return body;
+}
+/**
+ * Dataclass class function: `POST /rest/{dataClass}/{function}` with a JSON array body.
+ * GET: `?$params=[...]` ([docs](https://developer.4d.com/docs/REST/classFunctions.html)).
+ */
+export async function callDataClassFunction(http, dataClass, functionName, args, options) {
+    const method = options?.method ?? 'POST';
+    const unwrap = options?.unwrapResult !== false;
+    const base = `/${dataClass}/${functionName}`;
+    let body;
+    if (method === 'GET') {
+        const params = new URLSearchParams();
+        params.set('$params', JSON.stringify([...args]));
+        body = await http.json(`${base}?${params.toString()}`, {
+            method: 'GET',
+            signal: options?.signal,
+        });
+    }
+    else {
+        body = await http.json(base, {
+            method: 'POST',
+            body: JSON.stringify([...args]),
+            signal: options?.signal,
+        });
+    }
+    return (unwrap ? unwrapClassFunctionResult(body) : body);
+}
+/**
+ * Entity class function: `POST /rest/{dataClass}({key})/{function}`.
+ */
+export async function callEntityFunction(http, dataClass, entityKey, functionName, args, options) {
+    const method = options?.method ?? 'POST';
+    const unwrap = options?.unwrapResult !== false;
+    const key = encodeURIComponent(String(entityKey));
+    const base = `/${dataClass}(${key})/${functionName}`;
+    let body;
+    if (method === 'GET') {
+        const params = new URLSearchParams();
+        params.set('$params', JSON.stringify([...args]));
+        body = await http.json(`${base}?${params.toString()}`, {
+            method: 'GET',
+            signal: options?.signal,
+        });
+    }
+    else {
+        body = await http.json(base, {
+            method: 'POST',
+            body: JSON.stringify([...args]),
+            signal: options?.signal,
+        });
+    }
+    return (unwrap ? unwrapClassFunctionResult(body) : body);
+}
+/**
+ * Entity selection class function: `POST /rest/{dataClass}/{function}` with optional
+ * `/$entityset/{uuid}` and list query (`$filter`, `$orderby`, …).
+ */
+export async function callEntityCollectionFunction(http, dataClass, relationMap, functionName, args, options) {
+    const method = options?.method ?? 'POST';
+    const unwrap = options?.unwrapResult !== false;
+    let path = `/${dataClass}/${functionName}`;
+    if (options?.entitySet) {
+        const raw = options.entitySet.trim().replace(/^\//, '');
+        const id = raw.startsWith('$entityset') ? raw.replace(/^\$entityset\/?/, '') : raw;
+        path += `/$entityset/${encodeURIComponent(id)}`;
+    }
+    path += buildMethodSelectionQuery(dataClass, relationMap, options?.selection);
+    let body;
+    if (method === 'GET') {
+        const params = new URLSearchParams();
+        params.set('$params', JSON.stringify([...args]));
+        const join = path.includes('?') ? '&' : '?';
+        body = await http.json(`${path}${join}${params.toString()}`, {
+            method: 'GET',
+            signal: options?.signal,
+        });
+    }
+    else {
+        body = await http.json(path, {
+            method: 'POST',
+            body: JSON.stringify([...args]),
+            signal: options?.signal,
+        });
+    }
+    return (unwrap ? unwrapClassFunctionResult(body) : body);
+}

package/dist/runtime/collection.d.ts

@@ -1,4 +1,4 @@
-import type { QuadroHttp } from './http.js';
+import { type QuadroHttp } from './http.js';
 import { type ListQueryParams } from './query.js';
 export interface CollectionContext {
     http: QuadroHttp;
@@ -18,6 +18,13 @@ export interface CollectionOptions extends ListQueryParams {
     maxItems?: number;
     /** When aborted (e.g. React effect cleanup), list fetches stop and iteration ends. */
     signal?: AbortSignal;
+    /**
+     * Skip `$top=0` entity-set creation and use this URI (e.g. from `__ENTITYSET` or
+     * {@link onEntitySetReady}). Path form must match what the client uses after {@link parseEntitySetUri}.
+     */
+    reuseEntitySet?: string;
+    /** Fired once when a new entity set is created (not when {@link reuseEntitySet} is used). */
+    onEntitySetReady?: (entitySetPath: string) => void;
 }
 export type MapRow<R> = (raw: unknown) => R;
 /**

package/dist/runtime/collection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../../src/runtime/collection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAC3C,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAA;AAGxE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,UAAU,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC,gEAAgE;IAChE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,sFAAsF;IACtF,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,CAAA;AAe3C;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,GAAG,EAAE,iBAAiB,EACtB,cAAc,EAAE,iBAAiB,EACjC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAChB,gBAAgB,CAAC,CAAC,CAAC,CA+FrB;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,GAAG;IACnD,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACvB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,CAAA"}
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../../src/runtime/collection.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0C,KAAK,UAAU,EAAE,MAAM,WAAW,CAAA;AACnF,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,YAAY,CAAA;AAGnB,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,UAAU,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC,gEAAgE;IAChE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,sFAAsF;IACtF,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,6FAA6F;IAC7F,gBAAgB,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,IAAI,CAAA;CACnD;AAED,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,CAAA;AAsE3C;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,GAAG,EAAE,iBAAiB,EACtB,cAAc,EAAE,iBAAiB,EACjC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAChB,gBAAgB,CAAC,CAAC,CAAC,CAmKrB;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,GAAG;IACnD,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACvB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,CAAA"}

package/dist/runtime/collection.mjs

@@ -1,5 +1,56 @@
-import { buildListSearchParams } from './query.mjs';
+import { mountPathFromBaseURL, normalizeBaseURL } from './http.mjs';
+import { buildEntitySetCreationParams, buildEntitySetPageParams, buildListSearchParams, } from './query.mjs';
 import { unwrapEntityList } from './unwrap.mjs';
+/**
+ * If `path` still starts with the same pathname as `baseURL` (e.g. `/rest`), strip it.
+ * Avoids `baseURL` + path → `.../rest/rest/Agency/...` when `__ENTITYSET` already included `/rest`.
+ */
+function stripDuplicateMountPrefix(pathOrUrl, baseURL) {
+    const qIdx = pathOrUrl.indexOf('?');
+    const pathOnly = qIdx >= 0 ? pathOrUrl.slice(0, qIdx) : pathOrUrl;
+    const query = qIdx >= 0 ? pathOrUrl.slice(qIdx) : '';
+    const mount = mountPathFromBaseURL(baseURL);
+    if (!mount) {
+        return pathOrUrl;
+    }
+    let p = pathOnly;
+    while (p.startsWith(`${mount}/`) || p === mount) {
+        if (p === mount) {
+            p = '/';
+            break;
+        }
+        p = p.slice(mount.length);
+        if (!p.startsWith('/')) {
+            p = `/${p}`;
+        }
+    }
+    return p + query;
+}
+/** Turn `__ENTITYSET` / `Content-Location` into a path or absolute URL `QuadroHttp.request` accepts. */
+function parseEntitySetUri(raw, baseURL) {
+    const base = normalizeBaseURL(baseURL);
+    if (raw.startsWith('http://') || raw.startsWith('https://')) {
+        if (raw.startsWith(base)) {
+            const rest = raw.slice(base.length);
+            const path = rest.startsWith('/') ? rest : `/${rest}`;
+            return stripDuplicateMountPrefix(path, baseURL);
+        }
+        return raw;
+    }
+    let path = raw.startsWith('/') ? raw : `/${raw}`;
+    const basePath = mountPathFromBaseURL(baseURL);
+    if (basePath && path.startsWith(`${basePath}/`)) {
+        path = path.slice(basePath.length);
+        if (!path.startsWith('/')) {
+            path = `/${path}`;
+        }
+    }
+    return stripDuplicateMountPrefix(path, baseURL);
+}
+function appendReleaseQuery(pathOrUrl) {
+    const sep = pathOrUrl.includes('?') ? '&' : '?';
+    return `${pathOrUrl}${sep}$method=release`;
+}
 function primaryKeyFromRow(row, keyNames) {
     if (!row || typeof row !== 'object') {
         return undefined;
@@ -17,22 +68,80 @@ function primaryKeyFromRow(row, keyNames) {
  */
 export function createCollection(ctx, initialOptions, mapRow) {
     const seenIds = new Set();
-    let entitySetUrl = ctx.entitySetUrl;
+    let entitySetUrl = ctx.entitySetUrl ??
+        (initialOptions.reuseEntitySet
+            ? parseEntitySetUri(initialOptions.reuseEntitySet, ctx.http.baseURL)
+            : undefined);
+    const useEntitySet = initialOptions.entitySet !== false;
     async function fetchPage(page) {
-        const qs = buildListSearchParams(ctx.className, { ...initialOptions, page }, ctx.relationMap);
-        const res = await ctx.http.request(`${ctx.path}${qs}`, {
+        const pageSize = initialOptions.pageSize ?? 50;
+        const skip = (page - 1) * pageSize;
+        async function parseEntitySetFromResponse(json, res) {
+            let fromBody;
+            if (json && typeof json === 'object' && '__ENTITYSET' in json) {
+                const u = json.__ENTITYSET;
+                if (typeof u === 'string') {
+                    fromBody = u;
+                }
+            }
+            const loc = res.headers.get('Content-Location') ?? res.headers.get('Location');
+            const raw = fromBody ?? loc ?? undefined;
+            if (raw) {
+                entitySetUrl = parseEntitySetUri(raw, ctx.http.baseURL);
+                if (!initialOptions.reuseEntitySet) {
+                    initialOptions.onEntitySetReady?.(entitySetUrl);
+                }
+            }
+        }
+        if (useEntitySet && !entitySetUrl) {
+            const qsCreate = buildEntitySetCreationParams(initialOptions);
+            const createPath = `${ctx.path}${qsCreate}`;
+            const resCreate = await ctx.http.request(createPath, {
+                signal: initialOptions.signal,
+            });
+            const textCreate = await resCreate.text();
+            if (!resCreate.ok) {
+                throw new Error(`Entity set creation failed ${resCreate.status}: ${textCreate.slice(0, 200)}`);
+            }
+            const jsonCreate = textCreate ? JSON.parse(textCreate) : [];
+            await parseEntitySetFromResponse(jsonCreate, resCreate);
+            if (!entitySetUrl) {
+                return unwrapEntityList(ctx.className, jsonCreate);
+            }
+            const qsPage = buildEntitySetPageParams(skip, pageSize, initialOptions.select);
+            const base = entitySetUrl;
+            const pagePath = qsPage
+                ? base.includes('?')
+                    ? `${base}&${qsPage.slice(1)}`
+                    : `${base}${qsPage}`
+                : base;
+            const res = await ctx.http.request(pagePath, {
+                signal: initialOptions.signal,
+            });
+            const text = await res.text();
+            if (!res.ok) {
+                throw new Error(`List failed ${res.status}: ${text.slice(0, 200)}`);
+            }
+            const json = text ? JSON.parse(text) : [];
+            return unwrapEntityList(ctx.className, json);
+        }
+        let requestPath;
+        if (entitySetUrl && useEntitySet) {
+            const qs = buildEntitySetPageParams(skip, pageSize, initialOptions.select);
+            const base = entitySetUrl;
+            requestPath = qs ? (base.includes('?') ? `${base}&${qs.slice(1)}` : `${base}${qs}`) : base;
+        }
+        else {
+            const qs = buildListSearchParams(ctx.className, { ...initialOptions, page }, ctx.relationMap);
+            requestPath = `${ctx.path}${qs}`;
+        }
+        const res = await ctx.http.request(requestPath, {
             signal: initialOptions.signal,
         });
         const text = await res.text();
         if (!res.ok) {
             throw new Error(`List failed ${res.status}: ${text.slice(0, 200)}`);
         }
-        const loc = res.headers.get('Content-Location') ?? res.headers.get('Location');
-        if (loc) {
-            entitySetUrl = loc.startsWith('http')
-                ? loc
-                : `${ctx.http.baseURL}${loc.startsWith('/') ? '' : '/'}${loc}`;
-        }
         const json = text ? JSON.parse(text) : [];
         return unwrapEntityList(ctx.className, json);
     }
@@ -85,16 +194,18 @@ export function createCollection(ctx, initialOptions, mapRow) {
             seenIds.clear();
         },
         async release() {
-            if (entitySetUrl) {
-                try {
-                    await ctx.http.void(entitySetUrl.replace(ctx.http.baseURL, '') || entitySetUrl, {
-                        method: 'DELETE',
-                    });
-                }
-                catch {
-                    // Some servers ignore release; swallow
-                }
-                entitySetUrl = undefined;
+            if (!entitySetUrl) {
+                return;
+            }
+            const toRelease = entitySetUrl;
+            entitySetUrl = undefined;
+            try {
+                const path = appendReleaseQuery(toRelease);
+                const res = await ctx.http.request(path, { method: 'GET' });
+                await res.text();
+            }
+            catch {
+                // 4D may return an error if already expired; ignore
             }
         },
         get length() {

package/dist/runtime/data-class.d.ts

@@ -28,15 +28,22 @@ export interface EntityNavigationConfig {
     relationMap: Record<string, string>;
     keyNames: Record<string, readonly string[]>;
 }
+export interface RelatedNavigationSpec {
+    attr: string;
+    targetClass: string;
+    /** Entity-selection class methods for `targetClass` (4D `entityCollection`). */
+    entityCollectionMethodNames?: readonly string[];
+}
+/** Bind entity-selection class methods onto a collection handle or `{ list }` API object. */
+export declare function bindEntityCollectionMethods<H extends object>(target: H, cfg: Pick<DataClassRuntimeConfig, 'http' | 'className' | 'relationMap'>, methodNames: readonly string[]): H;
+/** Attach entity class methods (4D `entity`) on a mapped row. */
+export declare function attachEntityClassMethods(row: unknown, cfg: Pick<DataClassRuntimeConfig, 'http' | 'className' | 'relationMap' | 'keyNames'>, methodNames: readonly string[]): void;
 /** Nested collection under an entity, e.g. `Agency(1)/todayBookings`. */
-export declare function makeRelatedCollectionApi(cfg: EntityNavigationConfig, attributeName: string, targetClassName: string): {
+export declare function makeRelatedCollectionApi(cfg: EntityNavigationConfig, attributeName: string, targetClassName: string, entityCollectionMethodNames?: readonly string[]): {
     list<S extends readonly string[] = readonly []>(options?: CollectionOptions & {
         select?: S;
     }): CollectionHandle<unknown>;
 };
-export declare function attachRelatedApis(row: unknown, cfg: EntityNavigationConfig, relations: readonly {
-    attr: string;
-    targetClass: string;
-}[]): void;
+export declare function attachRelatedApis(row: unknown, cfg: EntityNavigationConfig, relations: readonly RelatedNavigationSpec[]): void;
 export { unwrapEntityList };
 //# sourceMappingURL=data-class.d.ts.map

package/dist/runtime/data-class.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-class.d.ts","sourceRoot":"","sources":["../../src/runtime/data-class.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,iBAAiB,EAAoB,MAAM,iBAAiB,CAAA;AACjG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE3C,OAAO,EAAgB,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAE5D,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,UAAU,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,wGAAwG;IACxG,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAC5B;AAED,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,sBAAsB;QAIjE,CAAC,SAAS,SAAS,MAAM,EAAE,0BACnB,iBAAiB,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE,GAC3C,gBAAgB,CAAC,CAAC,SAAS,SAAS,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;QAc7C,CAAC,SAAS,SAAS,MAAM,EAAE,oBAC/B,MAAM,GAAG,MAAM,YACT;QAAE,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE,GACvB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;eASH,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;UAU7C,CAAC,SAAS,SAAS,MAAM,EAAE,wBACvB,MAAM,YACJ,iBAAiB,GAAG;QAAE,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE,GAC/D,gBAAgB,CAAC,CAAC,SAAS,SAAS,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;EAe1D;AA6BD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,UAAU,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;IACzB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAA;CAC5C;AAED,yEAAyE;AACzE,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,sBAAsB,EAC3B,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM;SAKhB,CAAC,SAAS,SAAS,MAAM,EAAE,0BACpB,iBAAiB,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE,GAC3C,gBAAgB,CAAC,OAAO,CAAC;EAc/B;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,sBAAsB,EAC3B,SAAS,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EAAE,GAC1D,IAAI,CAYN;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAA"}
+{"version":3,"file":"data-class.d.ts","sourceRoot":"","sources":["../../src/runtime/data-class.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,iBAAiB,EAAoB,MAAM,iBAAiB,CAAA;AACjG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE3C,OAAO,EAAgB,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAE5D,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,UAAU,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,wGAAwG;IACxG,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAC5B;AAED,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,sBAAsB;QAIjE,CAAC,SAAS,SAAS,MAAM,EAAE,0BACnB,iBAAiB,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE,GAC3C,gBAAgB,CAAC,CAAC,SAAS,SAAS,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;QAc7C,CAAC,SAAS,SAAS,MAAM,EAAE,oBAC/B,MAAM,GAAG,MAAM,YACT;QAAE,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE,GACvB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;eASH,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;UAU7C,CAAC,SAAS,SAAS,MAAM,EAAE,wBACvB,MAAM,YACJ,iBAAiB,GAAG;QAAE,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE,GAC/D,gBAAgB,CAAC,CAAC,SAAS,SAAS,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;EAe1D;AA6BD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,UAAU,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;IACzB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAA;CAC5C;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,gFAAgF;IAChF,2BAA2B,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAChD;AAED,6FAA6F;AAC7F,wBAAgB,2BAA2B,CAAC,CAAC,SAAS,MAAM,EAC1D,MAAM,EAAE,CAAC,EACT,GAAG,EAAE,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,WAAW,GAAG,aAAa,CAAC,EACvE,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,CAAC,CAiBH;AAgBD,iEAAiE;AACjE,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC,EACpF,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,IAAI,CAmBN;AAED,yEAAyE;AACzE,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,sBAAsB,EAC3B,aAAa,EAAE,MAAM,EACrB,eAAe,EAAE,MAAM,EACvB,2BAA2B,CAAC,EAAE,SAAS,MAAM,EAAE;SAKxC,CAAC,SAAS,SAAS,MAAM,EAAE,0BACpB,iBAAiB,GAAG;QAAE,MAAM,CAAC,EAAE,CAAC,CAAA;KAAE,GAC3C,gBAAgB,CAAC,OAAO,CAAC;EAmB/B;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,sBAAsB,EAC3B,SAAS,EAAE,SAAS,qBAAqB,EAAE,GAC1C,IAAI,CAYN;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAA"}

package/dist/runtime/data-class.mjs

@@ -1,3 +1,4 @@
+import { callEntityCollectionFunction, callEntityFunction, } from './class-function.mjs';
 import { createCollection } from './collection.mjs';
 import { buildEntityParams } from './query.mjs';
 import { unwrapEntity, unwrapEntityList } from './unwrap.mjs';
@@ -68,10 +69,52 @@ function formatFilterLiteral(p) {
     const s = String(p).replace(/'/g, "''");
     return `'${s}'`;
 }
+/** Bind entity-selection class methods onto a collection handle or `{ list }` API object. */
+export function bindEntityCollectionMethods(target, cfg, methodNames) {
+    if (!methodNames.length) {
+        return target;
+    }
+    const o = target;
+    for (const name of methodNames) {
+        o[name] = (args = [], init) => callEntityCollectionFunction(cfg.http, cfg.className, cfg.relationMap, name, args, init);
+    }
+    return target;
+}
+function primaryKeyFromRow(row, keyNames) {
+    if (!row || typeof row !== 'object') {
+        return undefined;
+    }
+    const o = row;
+    for (const k of keyNames) {
+        const v = o[k];
+        if (v !== undefined && v !== null) {
+            return v;
+        }
+    }
+    return undefined;
+}
+/** Attach entity class methods (4D `entity`) on a mapped row. */
+export function attachEntityClassMethods(row, cfg, methodNames) {
+    if (!row || typeof row !== 'object' || !methodNames.length) {
+        return;
+    }
+    const pk = primaryKeyFromRow(row, cfg.keyNames);
+    if (pk === undefined) {
+        return;
+    }
+    const obj = row;
+    for (const name of methodNames) {
+        Object.defineProperty(obj, name, {
+            enumerable: false,
+            configurable: true,
+            value: (args = [], init) => callEntityFunction(cfg.http, cfg.className, pk, name, args, init),
+        });
+    }
+}
 /** Nested collection under an entity, e.g. `Agency(1)/todayBookings`. */
-export function makeRelatedCollectionApi(cfg, attributeName, targetClassName) {
+export function makeRelatedCollectionApi(cfg, attributeName, targetClassName, entityCollectionMethodNames) {
     const basePath = `/${cfg.parentClass}(${encodeURIComponent(String(cfg.parentId))})/${attributeName}`;
-    return {
+    const api = {
         list(options) {
             return createCollection({
                 http: cfg.http,
@@ -82,17 +125,18 @@ export function makeRelatedCollectionApi(cfg, attributeName, targetClassName) {
             }, options ?? {}, (raw) => raw);
         },
     };
+    return bindEntityCollectionMethods(api, { http: cfg.http, className: targetClassName, relationMap: cfg.relationMap }, entityCollectionMethodNames ?? []);
 }
 export function attachRelatedApis(row, cfg, relations) {
     if (!row || typeof row !== 'object') {
         return;
     }
     const obj = row;
-    for (const { attr, targetClass } of relations) {
+    for (const { attr, targetClass, entityCollectionMethodNames } of relations) {
         Object.defineProperty(obj, attr, {
             enumerable: false,
             configurable: true,
-            value: makeRelatedCollectionApi(cfg, attr, targetClass),
+            value: makeRelatedCollectionApi(cfg, attr, targetClass, entityCollectionMethodNames),
         });
     }
 }

package/dist/runtime/http.d.ts

@@ -5,6 +5,11 @@ export interface QuadroFetchOptions {
     defaultHeaders?: Record<string, string>;
 }
 export declare function normalizeBaseURL(baseURL: string): string;
+/**
+ * REST mount pathname (e.g. `/rest`) for joining paths and stripping duplicates.
+ * Supports relative bases like `/rest` — `new URL('/rest')` is invalid, so callers must not use that alone.
+ */
+export declare function mountPathFromBaseURL(baseURL: string): string;
 export declare class QuadroHttp {
     private readonly opts;
     constructor(opts: QuadroFetchOptions);

package/dist/runtime/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/runtime/http.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACxC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,kBAAkB;IAErD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAEK,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAwBhE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;IAYzD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAOhE"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/runtime/http.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACxC;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAa5D;AAED,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,kBAAkB;IAErD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAEK,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAwBhE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,CAAC,CAAC;IAYzD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAOhE"}

package/dist/runtime/http.mjs

@@ -2,6 +2,25 @@ import { QuadroHttpError } from './errors.mjs';
 export function normalizeBaseURL(baseURL) {
     return baseURL.replace(/\/$/, '');
 }
+/**
+ * REST mount pathname (e.g. `/rest`) for joining paths and stripping duplicates.
+ * Supports relative bases like `/rest` — `new URL('/rest')` is invalid, so callers must not use that alone.
+ */
+export function mountPathFromBaseURL(baseURL) {
+    const b = normalizeBaseURL(baseURL);
+    if (b.startsWith('http://') || b.startsWith('https://')) {
+        try {
+            return new URL(b).pathname.replace(/\/$/, '') || '';
+        }
+        catch {
+            return '';
+        }
+    }
+    if (b.startsWith('/')) {
+        return b.replace(/\/$/, '') || '';
+    }
+    return '';
+}
 export class QuadroHttp {
     opts;
     constructor(opts) {

package/dist/runtime/index.d.ts

@@ -1,9 +1,10 @@
+export { type ClassFunctionHttpOptions, callDataClassFunction, callEntityCollectionFunction, callEntityFunction, type EntityCollectionMethodOptions, unwrapClassFunctionResult, } from './class-function.js';
 export { type CollectionContext, type CollectionHandle, type CollectionOptions, createCollection, } from './collection.js';
-export { attachRelatedApis, type DataClassRuntimeConfig, type EntityNavigationConfig, makeDataClassApi, makeRelatedCollectionApi, } from './data-class.js';
+export { attachEntityClassMethods, attachRelatedApis, bindEntityCollectionMethods, type DataClassRuntimeConfig, type EntityNavigationConfig, makeDataClassApi, makeRelatedCollectionApi, type RelatedNavigationSpec, } from './data-class.js';
 export { callDatastorePath, createDatastoreNamespace } from './datastore.js';
 export { QuadroHttpError } from './errors.js';
-export { normalizeBaseURL, type QuadroFetchOptions, QuadroHttp, } from './http.js';
+export { mountPathFromBaseURL, normalizeBaseURL, type QuadroFetchOptions, QuadroHttp, } from './http.js';
 export type { Paths1, SelectedEntity } from './paths.js';
-export { buildListSearchParams, type ListQueryParams } from './query.js';
+export { buildEntitySetCreationParams, buildEntitySetPageParams, buildListSearchParams, buildMethodSelectionQuery, type ListQueryParams, type MethodSelectionQuery, } from './query.js';
 export { unwrapEntity, unwrapEntityList } from './unwrap.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,gBAAgB,GACjB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,iBAAiB,EACjB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EACL,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,UAAU,GACX,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AACxD,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAA;AACxE,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,wBAAwB,EAC7B,qBAAqB,EACrB,4BAA4B,EAC5B,kBAAkB,EAClB,KAAK,6BAA6B,EAClC,yBAAyB,GAC1B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,gBAAgB,GACjB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,2BAA2B,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,gBAAgB,EAChB,wBAAwB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAA;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,UAAU,GACX,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AACxD,OAAO,EACL,4BAA4B,EAC5B,wBAAwB,EACxB,qBAAqB,EACrB,yBAAyB,EACzB,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA"}

package/dist/runtime/index.mjs

@@ -1,7 +1,8 @@
+export { callDataClassFunction, callEntityCollectionFunction, callEntityFunction, unwrapClassFunctionResult, } from './class-function.mjs';
 export { createCollection, } from './collection.mjs';
-export { attachRelatedApis, makeDataClassApi, makeRelatedCollectionApi, } from './data-class.mjs';
+export { attachEntityClassMethods, attachRelatedApis, bindEntityCollectionMethods, makeDataClassApi, makeRelatedCollectionApi, } from './data-class.mjs';
 export { callDatastorePath, createDatastoreNamespace } from './datastore.mjs';
 export { QuadroHttpError } from './errors.mjs';
-export { normalizeBaseURL, QuadroHttp, } from './http.mjs';
-export { buildListSearchParams } from './query.mjs';
+export { mountPathFromBaseURL, normalizeBaseURL, QuadroHttp, } from './http.mjs';
+export { buildEntitySetCreationParams, buildEntitySetPageParams, buildListSearchParams, buildMethodSelectionQuery, } from './query.mjs';
 export { unwrapEntity, unwrapEntityList } from './unwrap.mjs';

package/dist/runtime/query.d.ts

@@ -10,8 +10,40 @@ export interface ListQueryParams {
     /** OData-style filter string (4D REST). */
     filter?: string;
     orderby?: string;
+    /**
+     * When true (default for list collections), append `$method=entityset` so 4D creates a cached
+     * entity set ([docs](https://developer.4d.com/docs/REST/method#methodentityset)). Call
+     * `release()` on the collection handle with `$method=release` when finished
+     * ([docs](https://developer.4d.com/docs/REST/method#methodrelease)). Set `false` if the server
+     * does not support entity sets.
+     */
+    entitySet?: boolean;
 }
 export declare function buildListSearchParams(_className: string, opts: ListQueryParams, _relationMap: Record<string, string>): string;
+/**
+ * First request to create an entity set: [`$method=entityset`](https://developer.4d.com/docs/REST/method#methodentityset)
+ * with `$top=0` so the set is created without returning a full page; follow with
+ * {@link buildEntitySetPageParams} on `__ENTITYSET` for real paging.
+ */
+export declare function buildEntitySetCreationParams(opts: ListQueryParams): string;
+/**
+ * Query string for paging an existing entity set (`$skip`, `$top`, `$attributes`).
+ * Used after the first [`$method=entityset`](https://developer.4d.com/docs/REST/method#methodentityset) response.
+ */
+export declare function buildEntitySetPageParams(skip: number, pageSize: number, select?: readonly string[]): string;
 /** Query string for a single entity (`$attributes` / no paging). */
 export declare function buildEntityParams(_className: string, select: readonly string[] | undefined, _relationMap: Record<string, string>): string;
+/** Optional list constraints for entity-selection class functions (not the same as `$method=entityset` cache). */
+export type MethodSelectionQuery = {
+    page?: number;
+    pageSize?: number;
+    select?: readonly string[];
+    filter?: string;
+    orderby?: string;
+};
+/**
+ * Query string for entity-selection class functions: `$filter`, `$orderby`, `$attributes`,
+ * `$skip`, `$top` ([4D class functions](https://developer.4d.com/docs/REST/classFunctions.html)).
+ */
+export declare function buildMethodSelectionQuery(_className: string, _relationMap: Record<string, string>, selection?: MethodSelectionQuery): string;
 //# sourceMappingURL=query.d.ts.map

package/dist/runtime/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/runtime/query.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AASD,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,eAAe,EACrB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,MAAM,CAqBR;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACrC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,MAAM,CAQR"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/runtime/query.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAEhF,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AASD,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,eAAe,EACrB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,MAAM,CAwBR;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAgB1E;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,GACzB,MAAM,CAYR;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACrC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,MAAM,CAQR;AAED,kHAAkH;AAClH,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,SAAS,CAAC,EAAE,oBAAoB,GAC/B,MAAM,CAyBR"}

package/dist/runtime/query.mjs

@@ -24,6 +24,48 @@ export function buildListSearchParams(_className, opts, _relationMap) {
     if (attrs) {
         params.set('$attributes', attrs);
     }
+    if (opts.entitySet) {
+        params.set('$method', 'entityset');
+    }
+    const q = params.toString();
+    return q ? `?${q}` : '';
+}
+/**
+ * First request to create an entity set: [`$method=entityset`](https://developer.4d.com/docs/REST/method#methodentityset)
+ * with `$top=0` so the set is created without returning a full page; follow with
+ * {@link buildEntitySetPageParams} on `__ENTITYSET` for real paging.
+ */
+export function buildEntitySetCreationParams(opts) {
+    const params = new URLSearchParams();
+    params.set('$top', '0');
+    if (opts.filter) {
+        params.set('$filter', opts.filter);
+    }
+    if (opts.orderby) {
+        params.set('$orderby', opts.orderby);
+    }
+    const attrs = attributesParam(opts.select ?? []);
+    if (attrs) {
+        params.set('$attributes', attrs);
+    }
+    params.set('$method', 'entityset');
+    const q = params.toString();
+    return q ? `?${q}` : '';
+}
+/**
+ * Query string for paging an existing entity set (`$skip`, `$top`, `$attributes`).
+ * Used after the first [`$method=entityset`](https://developer.4d.com/docs/REST/method#methodentityset) response.
+ */
+export function buildEntitySetPageParams(skip, pageSize, select) {
+    const params = new URLSearchParams();
+    if (skip > 0) {
+        params.set('$skip', String(skip));
+    }
+    params.set('$top', String(pageSize));
+    const attrs = attributesParam(select ?? []);
+    if (attrs) {
+        params.set('$attributes', attrs);
+    }
     const q = params.toString();
     return q ? `?${q}` : '';
 }
@@ -37,3 +79,34 @@ export function buildEntityParams(_className, select, _relationMap) {
     const q = params.toString();
     return q ? `?${q}` : '';
 }
+/**
+ * Query string for entity-selection class functions: `$filter`, `$orderby`, `$attributes`,
+ * `$skip`, `$top` ([4D class functions](https://developer.4d.com/docs/REST/classFunctions.html)).
+ */
+export function buildMethodSelectionQuery(_className, _relationMap, selection) {
+    if (!selection) {
+        return '';
+    }
+    const params = new URLSearchParams();
+    if (selection.page != null && selection.pageSize != null) {
+        const skip = (selection.page - 1) * selection.pageSize;
+        if (skip > 0) {
+            params.set('$skip', String(skip));
+        }
+        params.set('$top', String(selection.pageSize));
+    }
+    else if (selection.pageSize != null) {
+        params.set('$top', String(selection.pageSize));
+    }
+    if (selection.filter) {
+        params.set('$filter', selection.filter);
+    }
+    if (selection.orderby) {
+        params.set('$orderby', selection.orderby);
+    }
+    if (selection.select?.length) {
+        params.set('$attributes', selection.select.join(','));
+    }
+    const q = params.toString();
+    return q ? `?${q}` : '';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quadrokit/client",
-  "version": "0.2.13",
+  "version": "0.3.0",
   "description": "Typed 4D REST client and catalog code generator for QuadroKit",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -29,7 +29,7 @@
     "generate:fixture": "bun run src/cli.ts generate --url file://../../assets/catalog.json --out ../../.quadrokit/generated-demo"
   },
   "dependencies": {
-    "@quadrokit/shared": "^0.2.13",
+    "@quadrokit/shared": "^0.3.0",
     "undici": "^6.21.0"
   },
   "peerDependencies": {