@quadrokit/client 0.3.13 → 0.3.15

package/README.md

@@ -16,6 +16,7 @@ The package exposes:
 
 - **`@quadrokit/client`** — runtime + types (and anything your generated code needs).
 - **`@quadrokit/client/runtime`** — low-level helpers if you build custom integrations.
+- **`@quadrokit/client/rx`** — optional RxJS bridge for `QuadroEventBus` (install **`rxjs`** in your app).
 
 ---
 
@@ -44,6 +45,7 @@ Use a URL that returns the **full** catalog (dataclasses **with attributes**). P
 | **`--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). |
+| **`--no-split-type-files`** | Emit a single **`types.gen.ts`** (legacy). **Default:** split typings — **`entities/<Class>.gen.ts`**, optional **`datastore.gen.ts`**, and **`types.gen.ts`** as the barrel. |
 
 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`.
 
@@ -51,9 +53,11 @@ Environment variables (often via `.env` in the project root): `VITE_4D_ORIGIN`,
 
 | File | Purpose |
 |------|---------|
-| **`types.gen.ts`** | Entity interfaces; **`*Path`** aliases use **`QuadroAttributePaths<T>`** (recursive dot paths, depth-limited for circular relations); **`QuadroClient`** typing. |
+| **`types.gen.ts`** | Barrel: **`QuadroClient`** typing; re-exports entity types and **`*Path`** aliases. |
+| **`entities/<ClassName>.gen.ts`** | One file per exposed dataclass (default layout): **`export interface`** + **`export type`** **`<ClassName>Path`** (`QuadroAttributePaths<…>`). Omit with **`--no-split-type-files`** (single `types.gen.ts`). |
+| **`datastore.gen.ts`** | When the catalog lists datastore REST methods (e.g. `testFn`): **`QuadroDatastoreMethodFn`**. Omitted when there are no such exposed methods. **`authentify`** is not special-cased here — it is typed under **`QuadroClient`** only when the catalog exposes it (see **`hasAuthentify`** in **`catalog.gen.json`**). |
 | **`catalog.gen.json`** | Catalog runtime spec (dataclass layouts, methods, relations) consumed by `@quadrokit/client/runtime` — keeps **`client.gen.ts`** tiny. |
-| **`client.gen.ts`** | Thin `createClient(config)` that wires `QuadroHttp` + `buildQuadroClientFromCatalogSpec` + `catalog.gen.json`. |
+| **`client.gen.ts`** | Thin `createClient(config)` that wires `QuadroHttp` + `buildQuadroClientFromCatalogSpec` + `catalog.gen.json`. Config supports optional **`events`** (see [Request lifecycle events](#request-lifecycle-events)). |
 | **`meta.json`** | `__NAME`, `sessionCookieName` hint for 4D session cookies. |
 
 Point your app imports at the generated folder, for example:
@@ -80,10 +84,90 @@ const quadro = createClient({
 })
 ```
 
+Optional **`events: new QuadroEventBus()`** (from **`@quadrokit/client/runtime`**) enables [request lifecycle events](#request-lifecycle-events) on every call through the client.
+
 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.
 
 ---
 
+## Request lifecycle events
+
+Pass a **`QuadroEventBus`** from **`@quadrokit/client/runtime`** into **`createClient({ …, events })`**. The runtime emits a **loading → success** or **loading → error** sequence per logical operation (lists, `get`, `delete`, class functions, datastore paths, login, etc.).
+
+```ts
+import { createClient } from './.quadrokit/generated/client.gen.js'
+import { QuadroEventBus } from '@quadrokit/client/runtime'
+
+const events = new QuadroEventBus()
+
+const quadro = createClient({
+  baseURL: '/rest',
+  events,
+})
+
+const unsub = events.subscribe((e) => {
+  if (e.type === 'loading') {
+    console.debug(e.context.operation, e.path, e.method)
+  }
+  if (e.type === 'success') {
+    console.debug(e.durationMs, e.body)
+  }
+  if (e.type === 'error') {
+    console.warn(e.status, e.message, e.error)
+  }
+})
+
+// later: unsub()
+```
+
+You can also subscribe on the HTTP instance: **`quadro._http.subscribe(listener)`** returns an unsubscribe function.
+
+### Event shapes (`QuadroClientEvent`)
+
+| Field | `loading` | `success` | `error` |
+|-------|-----------|-----------|---------|
+| **`type`** | `'loading'` | `'success'` | `'error'` |
+| **`operationId`** | Correlates one start → one outcome | same | same |
+| **`context`** | **`QuadroRequestContext`**: **`operation`** (**`QuadroOperation`** string), optional **`className`**, **`methodName`**, **`entityKey`**, **`attributes`** | same | same |
+| **`path`** | Request path | same | same |
+| **`method`** | HTTP method | — | — |
+| **`startedAt`** | Timestamp | — | — |
+| **`durationMs`** | — | Elapsed | Elapsed |
+| **`status`** | — | If HTTP response is raw `Response` | If thrown value has HTTP **`status`** (e.g. **`QuadroHttpError`**) |
+| **`body`** | — | Result: parsed JSON, rows, `void`, or a small summary for raw **`Response`** | — |
+| **`message` / `error`** | — | — | User-facing message + original error |
+
+### Operations (`QuadroOperation`)
+
+Examples include: **`http.json`**, **`http.void`**, **`http.request`**, **`collection.list`**, **`collection.release`**, **`dataclass.get`**, **`dataclass.delete`**, **`function.dataclass`**, **`function.entity`**, **`function.entityCollection`**, **`datastore`**, **`auth.login`**.
+
+### `QuadroHttp` helpers (advanced)
+
+When **`events`** is set, **`json`**, **`void`**, and **`request`** accept an optional trailing **`QuadroRequestContext`** so emissions can be tagged. **`QuadroHttp`** also exposes:
+
+- **`rawRequest(path, init)`** — fetch without emitting (used inside multi-step flows).
+- **`runWithEvents(context, path, method, fn)`** — run an async function with the same loading/success/error envelope as the built-in methods.
+- **`events`** getter — the bus instance, if any.
+
+---
+
+## RxJS (`@quadrokit/client/rx`)
+
+Install **`rxjs`** in your app, then bridge the bus to an observable:
+
+```ts
+import { quadroEventsObservable } from '@quadrokit/client/rx'
+import { filter } from 'rxjs/operators'
+
+const sub = quadroEventsObservable(events)
+  .pipe(filter((e) => e.type === 'error'))
+  .subscribe((e) => console.warn(e.message))
+```
+
+**`rxjs`** is an **optional peer dependency** of `@quadrokit/client`; you only need it if you import `@quadrokit/client/rx`.
+
+---
+
 ## Dataclass API (generated)
 
 For each exposed dataclass, the client exposes a namespace such as `quadro.Agency`, `quadro.Reservation`, etc.
@@ -143,11 +227,11 @@ If your 4D project exposes methods in the REST catalog, the generator wires them
 
 | 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 |
+| **`dataClass`** | `quadro.Agency.agencyStats<R, A>(args, init?)` — **`R`** = result, **`A`** = args tuple (defaults: `unknown`, `readonly unknown[]`) | `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).
+- **`args`**: tuple type **`A`** (second generic on dataclass functions; default `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`.
 
@@ -159,7 +243,8 @@ Entity-selection methods accept **`EntityCollectionMethodOptions`**:
 Example:
 
 ```ts
-const stats = await quadro.Agency.agencyStats<MyStatsRow>([from, to])
+const stats = await quadro.Agency.agencyStats<MyStatsRow, [string, string]>([from, to])
+// or: agencyStats<MyStatsRow>([from, to]) when you only need to fix the result type
 
 const col = quadro.Reservation.all({ pageSize: 20 })
 // After the handle exists, e.g. from a hook or manual create:
@@ -178,7 +263,8 @@ Import from **`@quadrokit/client/runtime`** when you need primitives without cod
 
 | Export | Use |
 |--------|-----|
-| **`QuadroHttp`** | Thin wrapper: `json()`, `void()`, `request()` with base URL + default headers. |
+| **`QuadroHttp`** | Thin wrapper: **`json()`**, **`void()`**, **`request()`** with base URL + default headers; optional **`events`**; **`rawRequest`**, **`runWithEvents`**, **`subscribe`**. |
+| **`QuadroEventBus`**, **`QuadroClientEvent`**, **`QuadroLoadingEvent`**, **`QuadroSuccessEvent`**, **`QuadroErrorEvent`**, **`QuadroRequestContext`**, **`QuadroOperation`** | Lifecycle event types and bus (see [Request lifecycle events](#request-lifecycle-events)). |
 | **`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. |
@@ -191,7 +277,7 @@ The generated `createClient` is the recommended surface; these are for tooling,
 
 ## Errors
 
-Failed HTTP responses throw **`QuadroHttpError`** (status + response body). Handle network errors separately (`fetch` failures).
+Failed HTTP responses throw **`QuadroHttpError`** (status + response body). Handle network errors separately (`fetch` failures). When **`events`** is configured, failures also emit a **`QuadroErrorEvent`** with **`message`**, **`error`**, and optional **`status`** before the error propagates.
 
 ---
 

package/dist/cli.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { readFile } from 'node:fs/promises';
+import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { catalogFetchInit, defaultLoginUrlFromCatalogUrl, fetch4DAdminSessionCookie, vLog, wrapFetchError, } from './generate/catalog-session.mjs';
 import { warnIfCatalogLacksAttributes, writeGenerated } from './generate/codegen.mjs';
@@ -13,6 +14,7 @@ function parseArgs(argv) {
     let out = '.quadrokit/generated';
     let verbose = false;
     let insecureTls = false;
+    let splitTypeFiles = true;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === '--url' && argv[i + 1]) {
@@ -36,11 +38,14 @@ function parseArgs(argv) {
         else if (a === '--insecure-tls') {
             insecureTls = true;
         }
+        else if (a === '--no-split-type-files') {
+            splitTypeFiles = false;
+        }
         else if (!a.startsWith('-') && !command) {
             command = a;
         }
     }
-    return { command, url, token, accessKey, loginUrl, out, verbose, insecureTls };
+    return { command, url, token, accessKey, loginUrl, out, verbose, insecureTls, splitTypeFiles };
 }
 /** 4D sometimes returns `dataClass` (summary) vs `dataClasses` (detail); align to `dataClasses`. */
 function normalizeCatalogJson(raw) {
@@ -64,7 +69,15 @@ async function loadCatalog(url, auth, debug) {
     vLog(debug, '🦙', 'QuadroKit catalog generate', 'Loading catalog…');
     vLog(debug, '📍', 'Catalog URL', url);
     if (url.startsWith('file:')) {
-        const p = fileURLToPath(url);
+        let p;
+        try {
+            p = fileURLToPath(new URL(url));
+        }
+        catch {
+            // e.g. `file://../../assets/catalog.json` (invalid file URL host on some platforms)
+            const rest = url.replace(/^file:/i, '').replace(/^\/+/, '');
+            p = path.resolve(process.cwd(), rest);
+        }
         vLog(debug, '📂', 'Local file', p);
         const text = await readFile(p, 'utf8');
         vLog(debug, '✅', 'Catalog JSON', `Read ${text.length} bytes from disk`);
@@ -128,6 +141,10 @@ Debug / TLS:
   -v, --verbose        Friendly step-by-step logs (emojis) on stderr
   --insecure-tls       Skip TLS certificate verification (dev/self-signed HTTPS only)
 
+Output layout (default: split entity + datastore typings):
+  --no-split-type-files   Emit a single types.gen.ts (legacy); default is split files:
+                          entities/<Class>.gen.ts, optional datastore.gen.ts, types.gen.ts barrel.
+
 Env / .env: VITE_4D_ORIGIN, QUADROKIT_ACCESS_KEY, QUADROKIT_LOGIN_URL, QUADROKIT_CATALOG_TOKEN,
             QUADROKIT_GENERATE_VERBOSE, QUADROKIT_INSECURE_TLS (set to 1 / true / yes)
 
@@ -157,7 +174,7 @@ Examples:
         token: accessKey ? undefined : bearer,
     }, debug);
     warnIfCatalogLacksAttributes(catalog);
-    await writeGenerated(out, catalog);
+    await writeGenerated(out, catalog, { splitTypeFiles: parsed.splitTypeFiles });
     if (debug.verbose) {
         vLog(debug, '🎉', 'All set', `Generated client → ${out}`);
     }

package/dist/generate/codegen.d.ts

@@ -16,8 +16,19 @@ export declare function buildCatalogRuntimeSpec(catalog: CatalogJson): {
     }[];
     keyNamesByClass: Record<string, string[]>;
     hasAuthentify: boolean;
+    datastoreMethodNames: string[];
 };
 /** Warn when the catalog lists dataclasses but omits attributes (e.g. plain `GET /rest/$catalog` instead of `/rest/$catalog/$all`). */
 export declare function warnIfCatalogLacksAttributes(catalog: CatalogJson): void;
-export declare function writeGenerated(outDir: string, catalog: CatalogJson): Promise<void>;
+export interface WriteGeneratedOptions {
+    /**
+     * When `true` (default), emit each exposed dataclass as `entities/<Name>.gen.ts`, optional
+     * `datastore.gen.ts` (per-method `Datastore_*` aliases + `QuadroDatastoreMethodFn`), and a barrel `types.gen.ts`.
+     * When `false`, emit a single `types.gen.ts` (legacy layout).
+     * `entities/<Name>.overrides.ts` and `datastore.overrides.ts` are created only if missing; existing
+     * entity override files are preserved when the `entities/` folder is regenerated.
+     */
+    splitTypeFiles?: boolean;
+}
+export declare function writeGenerated(outDir: string, catalog: CatalogJson, options?: WriteGeneratedOptions): Promise<void>;
 //# sourceMappingURL=codegen.d.ts.map

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;AA4GxF,yFAAyF;AACzF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,WAAW,GAAG;IAC7D,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAA;QACZ,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QACnC,QAAQ,EAAE,MAAM,EAAE,CAAA;QAClB,iBAAiB,EAAE,MAAM,EAAE,CAAA;QAC3B,2BAA2B,EAAE,MAAM,EAAE,CAAA;QACrC,oBAAoB,EAAE,MAAM,EAAE,CAAA;QAC9B,SAAS,EAAE;YACT,IAAI,EAAE,MAAM,CAAA;YACZ,WAAW,EAAE,MAAM,CAAA;YACnB,2BAA2B,EAAE,MAAM,EAAE,CAAA;SACtC,EAAE,CAAA;KACJ,EAAE,CAAA;IACH,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;IACzC,aAAa,EAAE,OAAO,CAAA;CACvB,CAuBA;AA6GD,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,CAsBxF"}
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/generate/codegen.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAGV,WAAW,EAEZ,MAAM,mBAAmB,CAAA;AAmd1B,yFAAyF;AACzF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,WAAW,GAAG;IAC7D,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAA;QACZ,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QACnC,QAAQ,EAAE,MAAM,EAAE,CAAA;QAClB,iBAAiB,EAAE,MAAM,EAAE,CAAA;QAC3B,2BAA2B,EAAE,MAAM,EAAE,CAAA;QACrC,oBAAoB,EAAE,MAAM,EAAE,CAAA;QAC9B,SAAS,EAAE;YACT,IAAI,EAAE,MAAM,CAAA;YACZ,WAAW,EAAE,MAAM,CAAA;YACnB,2BAA2B,EAAE,MAAM,EAAE,CAAA;SACtC,EAAE,CAAA;KACJ,EAAE,CAAA;IACH,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;IACzC,aAAa,EAAE,OAAO,CAAA;IACtB,oBAAoB,EAAE,MAAM,EAAE,CAAA;CAC/B,CAwBA;AAoOD,uIAAuI;AACvI,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAYvE;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAqCD,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,WAAW,EACpB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CA2Ff"}

package/dist/generate/codegen.mjs

@@ -1,6 +1,11 @@
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { sessionCookieName } from '@quadrokit/shared';
+/**
+ * Suffix for import specifiers in generated `.ts` (`./Foo.gen.js`).
+ * Build with template + this const so `rename-dist-js-to-mjs` does not rewrite emitted paths in `dist/` to `.mjs`.
+ */
+const EMITTED_TS_IMPORT_SUFFIX = '.js';
 function map4dType(attr) {
     const t = attr.type ?? 'unknown';
     switch (t) {
@@ -83,19 +88,315 @@ function emitInterface(dc) {
     lines.push('}');
     return lines.join('\n');
 }
+/** Class names referenced as `relatedEntity` types (for per-entity file imports). Excludes self-references. */
+function referencedEntityTypes(dc) {
+    const names = new Set();
+    for (const a of dc.attributes ?? []) {
+        if (a.kind === 'relatedEntity' && a.type && a.type !== dc.name) {
+            names.add(a.type);
+        }
+    }
+    return [...names].sort((x, y) => x.localeCompare(y));
+}
+function entityGenNamespaceImportName(className) {
+    return `Gen${className}`;
+}
+function emitQuadroFnTypesFile() {
+    return `/* eslint-disable */
+/* Auto-generated by @quadrokit/client — do not edit */
+
+import type { ClassFunctionHttpOptions, EntityCollectionMethodOptions } from '@quadrokit/client/runtime';
+
+/** When the matching \`*Overrides\` interface defines a key, that signature wins; otherwise \`D\`. */
+export type ResolveOverride<O extends object, K extends string, D> = K extends keyof O
+  ? O[Extract<K, keyof O>] extends infer V
+    ? [V] extends [never]
+      ? D
+      : V extends undefined
+        ? D
+        : V
+    : D
+  : D;
+
+export type QuadroDataClassFn = <
+  R = unknown,
+  A extends readonly unknown[] = readonly unknown[],
+>(
+  args?: A,
+  init?: ClassFunctionHttpOptions & { unwrapResult?: boolean },
+) => Promise<R>;
+
+export type QuadroEntityFn = <
+  R = unknown,
+  A extends readonly unknown[] = readonly unknown[],
+>(
+  args?: A,
+  init?: ClassFunctionHttpOptions & { unwrapResult?: boolean },
+) => Promise<R>;
+
+export type QuadroEntityCollectionFn = <
+  R = unknown,
+  A extends readonly unknown[] = readonly unknown[],
+>(
+  args?: A,
+  init?: EntityCollectionMethodOptions,
+) => Promise<R>;
+
+export type QuadroDatastoreFn = <
+  B = unknown,
+  R = unknown,
+>(
+  body?: B,
+  init?: { method?: 'GET' | 'POST' },
+) => Promise<R>;
+`;
+}
+function emitOverridesStubFile(className, quadroFnRelativeToStub) {
+    return `/* eslint-disable */
+/**
+ * Optional: narrow REST method typings for ${className}.
+ * Add entries under the interfaces (e.g. findACar: QuadroDataClassFn<[string, string], Car[]>).
+ * Import fn types from \`'${quadroFnRelativeToStub}'\` when you add entries (or reference re-exports below).
+ */
+export type {
+  QuadroDataClassFn,
+  QuadroEntityFn,
+  QuadroEntityCollectionFn,
+} from '${quadroFnRelativeToStub}';
+
+export interface ${className}DataclassOverrides {}
+
+export interface ${className}EntityOverrides {}
+
+export interface ${className}EntityCollectionOverrides {}
+`;
+}
+function emitDatastoreOverridesStub(quadroFnsRelativeToStub) {
+    return `/* eslint-disable */
+/**
+ * Optional: narrow top-level datastore REST methods on the generated client (e.g. \`testFn\`).
+ * Add one property per catalog method name on \`DatastoreOverrides\`.
+ * Import \`QuadroDatastoreFn\` from \`'${quadroFnsRelativeToStub}'\` when you add entries.
+ */
+export type { QuadroDatastoreFn } from '${quadroFnsRelativeToStub}';
+
+export interface DatastoreOverrides {}
+`;
+}
+/** Import names from \`_quadroFns.gen\` required for this class’s emitted method aliases (avoids unused imports under \`noUnusedLocals\`). */
+function quadroFnTypeNamesForClass(dc) {
+    const dcMs = methodsForApply(dc, 'dataClass');
+    const emMs = methodsForApply(dc, 'entity');
+    const ecMs = methodsForApply(dc, 'entityCollection');
+    const out = [];
+    if (dcMs.length > 0 || emMs.length > 0 || ecMs.length > 0) {
+        out.push('ResolveOverride');
+    }
+    if (dcMs.length > 0) {
+        out.push('QuadroDataClassFn');
+    }
+    if (emMs.length > 0) {
+        out.push('QuadroEntityFn');
+    }
+    if (ecMs.length > 0) {
+        out.push('QuadroEntityCollectionFn');
+    }
+    return out;
+}
+function quadroFnTypeNamesForCatalog(classes, dsNames) {
+    const set = new Set();
+    for (const c of classes) {
+        for (const n of quadroFnTypeNamesForClass(c)) {
+            set.add(n);
+        }
+    }
+    if (dsNames.length > 0) {
+        set.add('ResolveOverride');
+        set.add('QuadroDatastoreFn');
+    }
+    const order = [
+        'ResolveOverride',
+        'QuadroDataClassFn',
+        'QuadroEntityFn',
+        'QuadroEntityCollectionFn',
+        'QuadroDatastoreFn',
+    ];
+    return order.filter((n) => set.has(n));
+}
+function overrideTypeNamesForClass(c) {
+    const parts = [];
+    if (methodsForApply(c, 'dataClass').length > 0) {
+        parts.push(`${c.name}DataclassOverrides`);
+    }
+    if (methodsForApply(c, 'entity').length > 0) {
+        parts.push(`${c.name}EntityOverrides`);
+    }
+    if (methodsForApply(c, 'entityCollection').length > 0) {
+        parts.push(`${c.name}EntityCollectionOverrides`);
+    }
+    return parts;
+}
+function methodNameLiteralForKey(name) {
+    return JSON.stringify(name);
+}
+function buildMethodAliasLines(dc) {
+    const dcMs = methodsForApply(dc, 'dataClass');
+    const emMs = methodsForApply(dc, 'entity');
+    const ecMs = methodsForApply(dc, 'entityCollection');
+    const dataclassLines = dcMs.map((m) => {
+        const id = sanitizeMethodId(m.name);
+        const key = methodNameLiteralForKey(m.name);
+        return `export type ${dc.name}_dataclass_${id} = ResolveOverride<${dc.name}DataclassOverrides, ${key}, QuadroDataClassFn>`;
+    });
+    const entityLines = emMs.map((m) => {
+        const id = sanitizeMethodId(m.name);
+        const key = methodNameLiteralForKey(m.name);
+        return `export type ${dc.name}_entity_${id} = ResolveOverride<${dc.name}EntityOverrides, ${key}, QuadroEntityFn>`;
+    });
+    const ecLines = ecMs.map((m) => {
+        const id = sanitizeMethodId(m.name);
+        const key = methodNameLiteralForKey(m.name);
+        return `export type ${dc.name}_entityCollection_${id} = ResolveOverride<${dc.name}EntityCollectionOverrides, ${key}, QuadroEntityCollectionFn>`;
+    });
+    const entityMap = emMs.length > 0
+        ? `export type ${dc.name}EntityMethodMap = {
+${emMs
+            .map((m) => `  ${objectPropertyKey(m.name)}: ${dc.name}_entity_${sanitizeMethodId(m.name)};`)
+            .join('\n')}
+};
+
+export type ${dc.name}WithEntityMethods = ${dc.name} & Partial<${dc.name}EntityMethodMap>;
+`
+        : '';
+    const ecMap = ecMs.length > 0
+        ? `export type ${dc.name}EntityCollectionMethodMap = {
+${ecMs
+            .map((m) => `  ${objectPropertyKey(m.name)}: ${dc.name}_entityCollection_${sanitizeMethodId(m.name)};`)
+            .join('\n')}
+};
+`
+        : '';
+    const methodBlock = [...dataclassLines, ...entityLines, ...ecLines].join('\n');
+    const tail = [entityMap, ecMap].filter(Boolean).join('\n');
+    return [methodBlock, tail].filter(Boolean).join('\n\n');
+}
+function emitEntityTypeBody(dc, opts) {
+    const refs = referencedEntityTypes(dc);
+    const fnNames = quadroFnTypeNamesForClass(dc);
+    const fnImport = fnNames.length > 0
+        ? `import type {\n  ${fnNames.join(',\n  ')},\n} from '${opts.quadroFnImport}';\n`
+        : '';
+    const ovNames = overrideTypeNamesForClass(dc);
+    const ovImport = ovNames.length > 0
+        ? `import type {\n  ${ovNames.join(',\n  ')},\n} from '${opts.overridesImport}';\n`
+        : '';
+    const runtimeImport = `import type { QuadroAttributePaths } from '@quadrokit/client/runtime';
+`;
+    const refImports = refs.length > 0
+        ? `${refs
+            .map((r) => `import type { ${r} } from './${r}.gen${EMITTED_TS_IMPORT_SUFFIX}';`)
+            .join('\n')}\n`
+        : '';
+    const iface = emitInterface(dc);
+    const pathType = `export type ${dc.name}Path = QuadroAttributePaths<${dc.name}>;
+`;
+    const methodAliases = buildMethodAliasLines(dc);
+    const blocks = [fnImport, ovImport, runtimeImport, refImports, iface, '', pathType, methodAliases]
+        .filter((x) => x !== '')
+        .join('\n');
+    return blocks;
+}
+function emitEntityTypeFile(dc) {
+    const header = `/* eslint-disable */\n/* Auto-generated by @quadrokit/client — do not edit */\n`;
+    const quadroPath = `../_quadroFns.gen${EMITTED_TS_IMPORT_SUFFIX}`;
+    const body = emitEntityTypeBody(dc, {
+        quadroFnImport: quadroPath,
+        overridesImport: `./${dc.name}.overrides${EMITTED_TS_IMPORT_SUFFIX}`,
+    });
+    return `${header}${body}\n`;
+}
+function buildDatastoreMethodAliasLines(catalog) {
+    const dsNames = datastoreMethodsExcludingAuthentify(catalog);
+    if (dsNames.length === 0) {
+        return '';
+    }
+    return dsNames
+        .map((n) => {
+        const id = sanitizeMethodId(n);
+        const key = methodNameLiteralForKey(n);
+        return `export type Datastore_${id} = ResolveOverride<DatastoreOverrides, ${key}, QuadroDatastoreFn>`;
+    })
+        .join('\n');
+}
+function emitDatastoreTypesFile(catalog) {
+    const dsNames = datastoreMethodsExcludingAuthentify(catalog);
+    const header = `/* eslint-disable */\n/* Auto-generated by @quadrokit/client — do not edit */\n\n`;
+    const imports = `import type {
+  ResolveOverride,
+  QuadroDatastoreFn,
+} from './_quadroFns.gen${EMITTED_TS_IMPORT_SUFFIX}';
+
+import type { DatastoreOverrides } from './datastore.overrides${EMITTED_TS_IMPORT_SUFFIX}';
+
+`;
+    const base = `/** Default datastore method shape; per-method aliases below respect \`DatastoreOverrides\`. */
+export type QuadroDatastoreMethodFn = QuadroDatastoreFn;
+
+`;
+    const aliases = dsNames.length > 0 ? `${buildDatastoreMethodAliasLines(catalog)}\n` : '';
+    return `${header}${imports}${base}${aliases}`;
+}
 /** Include dataclasses unless explicitly not exposed (`exposed === false`). Omitted `exposed` is treated as true. */
 function exposedDataClasses(catalog) {
     return catalog.dataClasses?.filter((d) => d.exposed !== false) ?? [];
 }
+/** Normalized `applyTo` for catalog method rows (4D: `dataClass`, `entity`, `entityCollection`). */
+const APPLY_TO_KIND = {
+    dataClass: 'dataclass',
+    entity: 'entity',
+    entityCollection: 'entitycollection',
+};
+function normalizeCatalogMethodApplyTo(applyTo) {
+    return applyTo?.trim().toLowerCase().replace(/\s+/g, '') ?? '';
+}
 /** ORDA catalog methods by `applyTo` (4D: dataClass, entityCollection, entity). */
-function methodsForApply(dc, applyTo) {
+function methodsForApply(dc, kind) {
     if (!dc) {
         return [];
     }
-    return (dc.methods ?? []).filter((m) => m.applyTo === applyTo && m.exposed !== false);
+    const want = APPLY_TO_KIND[kind];
+    return (dc.methods ?? []).filter((m) => normalizeCatalogMethodApplyTo(m.applyTo) === want && m.exposed !== false);
+}
+function sanitizeMethodId(name) {
+    return name.replace(/[^\w$]/g, '_').replace(/_+/g, '_');
+}
+/** Top-level ORDA `catalog.methods` entry targeting the datastore (4D: `dataStore`; compare case-insensitively). */
+function catalogMethodApplyToIsDatastore(applyTo) {
+    return applyTo?.trim().toLowerCase() === 'datastore';
 }
+/**
+ * True when the catalog lists an exposed `authentify` datastore method (same rules as other datastore methods).
+ * Not emitted in types/runtime when absent or `exposed: false`.
+ */
 function catalogHasAuthentify(catalog) {
-    return Boolean(catalog.methods?.some((m) => m.name === 'authentify' && m.applyTo === 'dataStore'));
+    return Boolean(catalog.methods?.some((m) => m.name?.toLowerCase() === 'authentify' &&
+        catalogMethodApplyToIsDatastore(m.applyTo) &&
+        m.exposed !== false));
+}
+/** Top-level ORDA `methods` with datastore `applyTo`, excluding `authentify` (typed as `authentify.login` when present). */
+function datastoreMethodsExcludingAuthentify(catalog) {
+    return (catalog.methods ?? [])
+        .filter((m) => Boolean(m.name) &&
+        catalogMethodApplyToIsDatastore(m.applyTo) &&
+        m.exposed !== false &&
+        m.name.toLowerCase() !== 'authentify')
+        .map((m) => m.name);
+}
+function isValidJsIdentifier(name) {
+    return /^[A-Za-z_$][\w$]*$/.test(name);
+}
+function objectPropertyKey(name) {
+    return isValidJsIdentifier(name) ? name : JSON.stringify(name);
 }
 /** Serializable spec consumed by {@link buildQuadroClientFromCatalogSpec} at runtime. */
 export function buildCatalogRuntimeSpec(catalog) {
@@ -103,6 +404,7 @@ export function buildCatalogRuntimeSpec(catalog) {
     const byName = new Map(classes.map((c) => [c.name, c]));
     return {
         hasAuthentify: catalogHasAuthentify(catalog),
+        datastoreMethodNames: datastoreMethodsExcludingAuthentify(catalog),
         keyNamesByClass: Object.fromEntries(classes.map((x) => [x.name, [...keyNames(x)]])),
         classes: classes.map((c) => ({
             name: c.name,
@@ -119,62 +421,148 @@ export function buildCatalogRuntimeSpec(catalog) {
         })),
     };
 }
-function emitQuadroClientTypeBlock(catalog, withEntities) {
+function emitQuadroClientTypeBlock(catalog, withEntities, datastoreFnStyle = 'inline', 
+/** When true, method types are referenced as `GenCar.Car_dataclass_*` from per-entity files. */
+splitLayout = false) {
     const classes = exposedDataClasses(catalog);
     const hasAuthentify = catalogHasAuthentify(catalog);
+    const dsNames = datastoreMethodsExcludingAuthentify(catalog);
     const authLine = hasAuthentify
         ? `  authentify: { login: (body: { email: string; password: string }) => Promise<unknown> };\n`
         : '';
+    const dsProps = dsNames.length > 0
+        ? `${dsNames
+            .map((n) => {
+            const id = sanitizeMethodId(n);
+            const ref = datastoreFnStyle === 'imported' ? `GenDatastore.Datastore_${id}` : `Datastore_${id}`;
+            return `  ${objectPropertyKey(n)}: ${ref};`;
+        })
+            .join('\n')}\n`
+        : '';
     const tail = `  rpc: (segments: string[], init?: { method?: 'GET' | 'POST'; body?: unknown }) => Promise<unknown>;
   sessionCookieName: string;
   _http: QuadroHttp;
 };`;
     if (!withEntities || classes.length === 0) {
         return `export type QuadroClient = {
-${authLine}${tail}
+${authLine}${dsProps}${tail}
 `;
     }
-    const dcFn = `type QuadroDataClassFn = <R = unknown>(args?: readonly unknown[], init?: ClassFunctionHttpOptions & { unwrapResult?: boolean }) => Promise<R>;
-
-`;
     const branches = classes
         .map((c) => {
-        const keys = methodsForApply(c, 'dataClass')
-            .map((m) => `'${m.name}'`)
-            .join(' | ');
-        const rhs = keys
-            ? `BaseDataClassApi<${c.name}, ${c.name}Path> & { [K in ${keys}]: QuadroDataClassFn }`
-            : `BaseDataClassApi<${c.name}, ${c.name}Path>`;
-        return `  ${c.name}: ${rhs};`;
+        const dcMs = methodsForApply(c, 'dataClass');
+        if (dcMs.length === 0) {
+            return `  ${c.name}: BaseDataClassApi<${c.name}, ${c.name}Path>;`;
+        }
+        const ns = splitLayout ? entityGenNamespaceImportName(c.name) : null;
+        const props = dcMs
+            .map((m) => {
+            const id = sanitizeMethodId(m.name);
+            const ref = ns ? `${ns}.${c.name}_dataclass_${id}` : `${c.name}_dataclass_${id}`;
+            return `    ${objectPropertyKey(m.name)}: ${ref};`;
+        })
+            .join('\n');
+        return `  ${c.name}: BaseDataClassApi<${c.name}, ${c.name}Path> & {
+${props}
+  };`;
     })
         .join('\n');
-    return `${dcFn}export type QuadroClient = {
-${authLine}${branches}
+    return `export type QuadroClient = {
+${authLine}${dsProps}${branches}
 ${tail}
 `;
 }
-function emitTypes(catalog) {
+function emitTypesMonolithic(catalog) {
     const classes = exposedDataClasses(catalog);
+    const dsNames = datastoreMethodsExcludingAuthentify(catalog);
+    const quadroFnNames = quadroFnTypeNamesForCatalog(classes, dsNames);
+    const needsQuadroFns = quadroFnNames.length > 0;
     const interfaces = classes.map((c) => emitInterface(c));
     const pathTypes = classes.map((c) => {
         const name = `${c.name}Path`;
         return `export type ${name} = QuadroAttributePaths<${c.name}>;`;
     });
+    const methodAliasBlocks = classes.map((c) => buildMethodAliasLines(c)).join('\n\n');
+    const datastoreAliasBlock = dsNames.length > 0 ? `${buildDatastoreMethodAliasLines(catalog)}\n\n` : '';
     const header = `/* eslint-disable */\n/* Auto-generated by @quadrokit/client — do not edit */\n`;
     const pathNote = classes.length > 0
-        ? `/**\n * *Path types use {@link QuadroAttributePaths} (recursive relation paths, depth-limited for circular graphs).\n * Override depth: \`type DeepEmployeePath = QuadroAttributePaths<Employee, 12>\`.\n */\n`
+        ? `/**\n * *Path types use {@link QuadroAttributePaths} (recursive relation paths, depth-limited for circular graphs).\n * Override depth: \`type DeepEmployeePath = QuadroAttributePaths<Employee, 12>\`.\n * Per-class REST method typings: \`*_dataclass_*\`, \`*_entity_*\`, \`*_entityCollection_*\`; narrow in \`./*.overrides.ts\`.\n * Datastore methods: \`Datastore_*\` aliases; narrow in \`./datastore.overrides.ts\`.\n */\n`
+        : dsNames.length > 0
+            ? `/**\n * Datastore REST methods: \`Datastore_*\` type aliases; narrow signatures in \`./datastore.overrides.ts\`.\n */\n`
+            : '';
+    const fnImport = needsQuadroFns
+        ? `import type {\n  ${quadroFnNames.join(',\n  ')},\n} from './_quadroFns.gen${EMITTED_TS_IMPORT_SUFFIX}';\n\n`
         : '';
+    const datastoreOverrideImport = dsNames.length > 0
+        ? `import type { DatastoreOverrides } from './datastore.overrides${EMITTED_TS_IMPORT_SUFFIX}';
+
+`
+        : '';
+    const overrideImportLines = classes
+        .map((c) => {
+        const parts = overrideTypeNamesForClass(c);
+        if (parts.length === 0) {
+            return null;
+        }
+        return `import type { ${parts.join(', ')} } from './${c.name}.overrides${EMITTED_TS_IMPORT_SUFFIX}';`;
+    })
+        .filter(Boolean);
+    const overrideImports = overrideImportLines.length > 0 ? `${overrideImportLines.join('\n')}\n\n` : '';
     const runtimeImport = classes.length > 0
-        ? `import type { BaseDataClassApi, ClassFunctionHttpOptions, QuadroAttributePaths, QuadroHttp } from '@quadrokit/client/runtime';\n\n`
+        ? `import type { BaseDataClassApi, QuadroAttributePaths, QuadroHttp } from '@quadrokit/client/runtime';\n\n`
         : `import type { QuadroHttp } from '@quadrokit/client/runtime';\n\n`;
+    if (classes.length === 0) {
+        const raw = catalog.dataClasses?.length ?? 0;
+        const note = raw > 0
+            ? `\n/**\n * No entity types: all ${raw} data class(es) in the catalog have exposed: false.\n * Enable REST exposure for tables in 4D, then run quadrokit-client generate again.\n */\n`
+            : dsNames.length > 0
+                ? ''
+                : `\n/**\n * No entity types: the catalog has no dataClasses (or an empty list).\n */\n`;
+        return `${header}${runtimeImport}${fnImport}${datastoreOverrideImport}${note}${pathNote}${datastoreAliasBlock}${emitQuadroClientTypeBlock(catalog, false, 'inline', false)}`;
+    }
+    return `${header}${runtimeImport}${fnImport}${overrideImports}${datastoreOverrideImport}${interfaces.join('\n\n')}\n\n${pathNote}${pathTypes.join('\n\n')}\n\n${datastoreAliasBlock}${methodAliasBlocks}\n\n${emitQuadroClientTypeBlock(catalog, true, 'inline', false)}`;
+}
+function emitTypesSplitMain(catalog) {
+    const classes = exposedDataClasses(catalog);
+    const dsNames = datastoreMethodsExcludingAuthentify(catalog);
+    const header = `/* eslint-disable */\n/* Auto-generated by @quadrokit/client — do not edit */\n`;
+    const pathNote = classes.length > 0
+        ? `/**\n * *Path types use {@link QuadroAttributePaths} (recursive relation paths, depth-limited for circular graphs).\n * Override depth: \`type DeepEmployeePath = QuadroAttributePaths<Employee, 12>\`.\n * Entity interfaces and REST method aliases live under \`./entities/*.gen.ts\`; optional signature overrides in \`./entities/*.overrides.ts\`.\n * Datastore: \`./datastore.gen.ts\` and \`./datastore.overrides.ts\` when present.\n */\n`
+        : dsNames.length > 0
+            ? `/**\n * Datastore method typings: \`./datastore.gen.ts\`; narrow signatures in \`./datastore.overrides.ts\`.\n */\n`
+            : '';
+    const datastoreImport = dsNames.length > 0
+        ? `import type * as GenDatastore from './datastore.gen${EMITTED_TS_IMPORT_SUFFIX}';\n\n`
+        : '';
+    const runtimeImport = classes.length > 0
+        ? `import type { BaseDataClassApi, QuadroHttp } from '@quadrokit/client/runtime';\n\n`
+        : `import type { QuadroHttp } from '@quadrokit/client/runtime';\n\n`;
+    const entityImports = classes.length > 0
+        ? `${classes
+            .map((c) => `import type { ${c.name}, ${c.name}Path } from './entities/${c.name}.gen${EMITTED_TS_IMPORT_SUFFIX}';`)
+            .join('\n')}\n\n`
+        : '';
+    const genNamespaceImports = classes.length > 0
+        ? `${classes
+            .filter((c) => methodsForApply(c, 'dataClass').length > 0)
+            .map((c) => `import type * as ${entityGenNamespaceImportName(c.name)} from './entities/${c.name}.gen${EMITTED_TS_IMPORT_SUFFIX}';`)
+            .join('\n')}${classes.some((c) => methodsForApply(c, 'dataClass').length > 0) ? '\n\n' : ''}`
+        : '';
+    const entityStarExports = classes.length > 0
+        ? `${classes
+            .map((c) => `export * from './entities/${c.name}.gen${EMITTED_TS_IMPORT_SUFFIX}';`)
+            .join('\n')}\n\n`
+        : '';
+    const datastoreStarExport = dsNames.length > 0 ? `export * from './datastore.gen${EMITTED_TS_IMPORT_SUFFIX}';\n\n` : '';
+    const datastoreStyle = dsNames.length > 0 ? 'imported' : 'inline';
     if (classes.length === 0) {
         const raw = catalog.dataClasses?.length ?? 0;
         const note = raw > 0
             ? `\n/**\n * No entity types: all ${raw} data class(es) in the catalog have exposed: false.\n * Enable REST exposure for tables in 4D, then run quadrokit-client generate again.\n */\n`
             : `\n/**\n * No entity types: the catalog has no dataClasses (or an empty list).\n */\n`;
-        return `${header}${runtimeImport}${note}\n${emitQuadroClientTypeBlock(catalog, false)}`;
+        return `${header}${runtimeImport}${datastoreImport}${note}${pathNote}\n${datastoreStarExport}${emitQuadroClientTypeBlock(catalog, false, datastoreStyle, false)}`;
     }
-    return `${header}${runtimeImport}${interfaces.join('\n\n')}\n\n${pathNote}${pathTypes.join('\n\n')}\n\n${emitQuadroClientTypeBlock(catalog, true)}`;
+    return `${header}${runtimeImport}${datastoreImport}${entityImports}${genNamespaceImports}${pathNote}${entityStarExports}${datastoreStarExport}\n${emitQuadroClientTypeBlock(catalog, true, datastoreStyle, true)}`;
 }
 function emitClient(catalog) {
     const dbName = catalog.__NAME ?? 'default';
@@ -226,10 +614,104 @@ export function warnIfCatalogLacksAttributes(catalog) {
     }
     console.error('quadrokit: catalog has dataclass names but no attribute details. Fetch the full catalog: GET /rest/$catalog/$all (plain /rest/$catalog omits attributes). See 4D REST docs: $catalog/$all.');
 }
-export async function writeGenerated(outDir, catalog) {
+/** Writes `contents` only when `filePath` does not exist (used for `*.overrides.ts` stubs). */
+async function writeStubIfMissing(filePath, contents) {
+    try {
+        await stat(filePath);
+    }
+    catch {
+        await writeFile(filePath, contents, 'utf8');
+    }
+}
+/** Reads existing `entities/*.overrides.ts` before the entities dir is recreated so user edits are kept. */
+async function readExistingEntityOverrides(entitiesDir) {
+    const map = new Map();
+    try {
+        const st = await stat(entitiesDir);
+        if (!st.isDirectory()) {
+            return map;
+        }
+        const names = await readdir(entitiesDir);
+        for (const name of names) {
+            if (!name.endsWith('.overrides.ts')) {
+                continue;
+            }
+            const p = path.join(entitiesDir, name);
+            const s = await stat(p);
+            if (!s.isFile()) {
+                continue;
+            }
+            map.set(name, await readFile(p, 'utf8'));
+        }
+    }
+    catch {
+        // entities dir missing or unreadable
+    }
+    return map;
+}
+export async function writeGenerated(outDir, catalog, options = {}) {
+    const splitTypeFiles = options.splitTypeFiles !== false;
     await mkdir(outDir, { recursive: true });
+    const entitiesDir = path.join(outDir, 'entities');
+    const datastorePath = path.join(outDir, 'datastore.gen.ts');
+    const quadroFnsPath = path.join(outDir, '_quadroFns.gen.ts');
+    const classes = exposedDataClasses(catalog);
+    const dsNames = datastoreMethodsExcludingAuthentify(catalog);
+    if (splitTypeFiles) {
+        const preservedEntityOverrides = await readExistingEntityOverrides(entitiesDir);
+        await rm(entitiesDir, { recursive: true, force: true });
+        const needsQuadroFns = classes.length > 0 || dsNames.length > 0;
+        if (needsQuadroFns) {
+            await writeFile(quadroFnsPath, emitQuadroFnTypesFile(), 'utf8');
+        }
+        else {
+            await rm(quadroFnsPath, { force: true }).catch(() => { });
+        }
+        if (classes.length > 0) {
+            await mkdir(entitiesDir, { recursive: true });
+            for (const c of classes) {
+                await writeFile(path.join(entitiesDir, `${c.name}.gen.ts`), emitEntityTypeFile(c), 'utf8');
+                const overrideName = `${c.name}.overrides.ts`;
+                const overridePath = path.join(entitiesDir, overrideName);
+                const previous = preservedEntityOverrides.get(overrideName);
+                if (previous !== undefined) {
+                    await writeFile(overridePath, previous, 'utf8');
+                }
+                else {
+                    await writeStubIfMissing(overridePath, emitOverridesStubFile(c.name, `../_quadroFns.gen${EMITTED_TS_IMPORT_SUFFIX}`));
+                }
+            }
+        }
+        if (dsNames.length > 0) {
+            await writeFile(datastorePath, emitDatastoreTypesFile(catalog), 'utf8');
+            await writeStubIfMissing(path.join(outDir, 'datastore.overrides.ts'), emitDatastoreOverridesStub(`./_quadroFns.gen${EMITTED_TS_IMPORT_SUFFIX}`));
+        }
+        else {
+            await rm(datastorePath, { force: true }).catch(() => { });
+        }
+        await writeFile(path.join(outDir, 'types.gen.ts'), emitTypesSplitMain(catalog), 'utf8');
+    }
+    else {
+        await rm(entitiesDir, { recursive: true, force: true });
+        await rm(datastorePath, { force: true }).catch(() => { });
+        const needsQuadroFns = classes.length > 0 || dsNames.length > 0;
+        if (needsQuadroFns) {
+            await writeFile(quadroFnsPath, emitQuadroFnTypesFile(), 'utf8');
+        }
+        else {
+            await rm(quadroFnsPath, { force: true }).catch(() => { });
+        }
+        if (classes.length > 0) {
+            for (const c of classes) {
+                await writeStubIfMissing(path.join(outDir, `${c.name}.overrides.ts`), emitOverridesStubFile(c.name, `./_quadroFns.gen${EMITTED_TS_IMPORT_SUFFIX}`));
+            }
+        }
+        if (dsNames.length > 0) {
+            await writeStubIfMissing(path.join(outDir, 'datastore.overrides.ts'), emitDatastoreOverridesStub(`./_quadroFns.gen${EMITTED_TS_IMPORT_SUFFIX}`));
+        }
+        await writeFile(path.join(outDir, 'types.gen.ts'), emitTypesMonolithic(catalog), 'utf8');
+    }
     await writeFile(path.join(outDir, 'catalog.gen.json'), `${JSON.stringify(buildCatalogRuntimeSpec(catalog), null, 2)}\n`, 'utf8');
-    await writeFile(path.join(outDir, 'types.gen.ts'), emitTypes(catalog), 'utf8');
     await writeFile(path.join(outDir, 'client.gen.ts'), emitClient(catalog), 'utf8');
     await writeFile(path.join(outDir, 'meta.json'), JSON.stringify({
         __NAME: catalog.__NAME,

package/dist/runtime/catalog-builder.d.ts

@@ -13,7 +13,10 @@ export interface CatalogClassRuntimeSpec {
 export interface CatalogRuntimeSpec {
     classes: readonly CatalogClassRuntimeSpec[];
     keyNamesByClass: Readonly<Record<string, readonly string[]>>;
-    hasAuthentify: boolean;
+    /** Set from the catalog at generate time; omit or `false` when `authentify` is not an exposed datastore method. */
+    hasAuthentify?: boolean;
+    /** Top-level datastore REST methods from `catalog.methods` (`applyTo: dataStore`), excluding `authentify`. */
+    datastoreMethodNames: readonly string[];
 }
 /**
  * Builds the object returned by generated `createClient()` from `catalog.gen.json`.

package/dist/runtime/catalog-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-builder.d.ts","sourceRoot":"","sources":["../../src/runtime/catalog-builder.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAA;AAExB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE3C,kEAAkE;AAClE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,2BAA2B,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAA;IACvC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAA;CAC5C;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAA;IAC3C,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;IAC5D,aAAa,EAAE,OAAO,CAAA;CACvB;AAqHD;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,kBAAkB,EACxB,IAAI,EAAE;IAAE,iBAAiB,EAAE,MAAM,CAAA;CAAE,GAClC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBzB"}
+{"version":3,"file":"catalog-builder.d.ts","sourceRoot":"","sources":["../../src/runtime/catalog-builder.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,qBAAqB,EAC3B,MAAM,iBAAiB,CAAA;AAExB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE3C,kEAAkE;AAClE,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3B,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,2BAA2B,EAAE,SAAS,MAAM,EAAE,CAAA;IAC9C,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAA;IACvC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAA;CAC5C;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAA;IAC3C,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;IAC5D,mHAAmH;IACnH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,8GAA8G;IAC9G,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAA;CACxC;AAqHD;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,kBAAkB,EACxB,IAAI,EAAE;IAAE,iBAAiB,EAAE,MAAM,CAAA;CAAE,GAClC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA8BzB"}

package/dist/runtime/catalog-builder.mjs

@@ -84,11 +84,14 @@ function makeDataClassNamespace(http, c, keyNamesRecord) {
 export function buildQuadroClientFromCatalogSpec(http, spec, meta) {
     const keyNamesRecord = spec.keyNamesByClass;
     const out = {};
-    if (spec.hasAuthentify) {
+    if (spec.hasAuthentify === true) {
         out.authentify = {
             login: (body) => callDatastorePath(http, ['authentify', 'login'], { body }, { operation: 'auth.login' }),
         };
     }
+    for (const name of spec.datastoreMethodNames ?? []) {
+        out[name] = (body, init) => callDatastorePath(http, [name], { body, method: init?.method }, { operation: 'datastore', methodName: name });
+    }
     for (const c of spec.classes) {
         out[c.name] = makeDataClassNamespace(http, c, keyNamesRecord);
     }

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,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,CA+LrB;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":"AACA,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,CA6LrB;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,3 +1,4 @@
+import { QuadroHttpError } from './errors.mjs';
 import { mountPathFromBaseURL, normalizeBaseURL } from './http.mjs';
 import { buildEntitySetCreationParams, buildEntitySetPageParams, buildListSearchParams, } from './query.mjs';
 import { unwrapEntityList } from './unwrap.mjs';
@@ -111,7 +112,7 @@ export function createCollection(ctx, initialOptions, mapRow) {
                 });
                 const textCreate = await resCreate.text();
                 if (!resCreate.ok) {
-                    throw new Error(`Entity set creation failed ${resCreate.status}: ${textCreate.slice(0, 200)}`);
+                    throw new QuadroHttpError(resCreate.status, textCreate);
                 }
                 const jsonCreate = textCreate ? JSON.parse(textCreate) : [];
                 await parseEntitySetFromResponse(jsonCreate, resCreate);
@@ -130,7 +131,7 @@ export function createCollection(ctx, initialOptions, mapRow) {
                 });
                 const text = await res.text();
                 if (!res.ok) {
-                    throw new Error(`List failed ${res.status}: ${text.slice(0, 200)}`);
+                    throw new QuadroHttpError(res.status, text);
                 }
                 const json = text ? JSON.parse(text) : [];
                 return unwrapEntityList(ctx.className, json);
@@ -150,7 +151,7 @@ export function createCollection(ctx, initialOptions, mapRow) {
             });
             const text = await res.text();
             if (!res.ok) {
-                throw new Error(`List failed ${res.status}: ${text.slice(0, 200)}`);
+                throw new QuadroHttpError(res.status, text);
             }
             const json = text ? JSON.parse(text) : [];
             return unwrapEntityList(ctx.className, json);

package/package.json

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