@quadrokit/client 0.3.15 → 0.3.16

package/README.md

@@ -58,6 +58,8 @@ Environment variables (often via `.env` in the project root): `VITE_4D_ORIGIN`,
 | **`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`. Config supports optional **`events`** (see [Request lifecycle events](#request-lifecycle-events)). |
+| **`_quadroFns.gen.ts`** | Shared helpers: **`ResolveOverride`**, **`QuadroDataClassFn`**, **`QuadroEntityFn`**, **`QuadroEntityCollectionFn`**, **`QuadroDatastoreFn`** (used by **`*.gen.ts`** and optional override files). |
+| **`entities/<Class>.overrides.ts`**, **`datastore.overrides.ts`** | Optional stubs you edit to **narrow method signatures** (see [Narrowing function signatures](#narrowing-function-signatures-override-files)). Created if missing; preserved across regenerate when possible. |
 | **`meta.json`** | `__NAME`, `sessionCookieName` hint for 4D session cookies. |
 
 Point your app imports at the generated folder, for example:
@@ -257,6 +259,69 @@ If the catalog does not list a method, it will not appear on the client — rege
 
 ---
 
+## Narrowing function signatures (override files)
+
+Generated ORDA **dataClass**, **entity**, and **entityCollection** methods, plus **datastore** methods, default to **loose** generics (`unknown` / `readonly unknown[]` for results and argument tuples). To type **return values** and **parameters** in TypeScript, add entries to the optional **override** modules beside the codegen output. The generator wires each method type as **`ResolveOverride<YourOverrides, "methodName", DefaultFn>`** in **`*.gen.ts`**: if your interface defines that **exact property name** (same spelling as the catalog / JS API), your signature wins; otherwise the default **`Quadro*Fn`** stands.
+
+### Where the files live
+
+**Split typings (default):** for each exposed dataclass, **`entities/<ClassName>.overrides.ts`** declares up to three interfaces:
+
+| Interface | Catalog `applyTo` | Example call site |
+|-----------|-------------------|-------------------|
+| **`<ClassName>DataclassOverrides`** | dataClass | `quadro.Car.findACar(...)` |
+| **`<ClassName>EntityOverrides`** | entity | `(await quadro.Car.get(id)).isAvailable(...)` |
+| **`<ClassName>EntityCollectionOverrides`** | entityCollection | On **`all()`** / **`query()`** handles and related **`list`** APIs |
+
+**`datastore.overrides.ts`** (next to **`types.gen.ts`**) maps **top-level** datastore methods on **`quadro`** by **catalog method name**.
+
+**Single `types.gen.ts` (**`--no-split-type-files`**):** same idea, with **`./<ClassName>.overrides.ts`** and **`./datastore.overrides.ts`** next to **`types.gen.ts`**.
+
+Stub files may **re-export** **`QuadroDataClassFn`**, **`QuadroEntityFn`**, **`QuadroEntityCollectionFn`**, **`QuadroDatastoreFn`** from **`_quadroFns.gen.ts`**; you can **`import type`** those helpers from **`_quadroFns.gen.js`** (or `.ts`) when you add properties.
+
+### Fn type parameters (from `_quadroFns.gen.ts`)
+
+- **`QuadroDataClassFn<R, A>`** — **`R`**: resolved **`Promise`** result type; **`A`**: **tuple** of positional arguments (sent as the JSON array body to 4D).
+- **`QuadroEntityFn<R, A>`** — same shape for **per-entity** calls.
+- **`QuadroEntityCollectionFn<R, A>`** — same **`R`** / **`A`**; real calls also accept **`init`** with **`EntityCollectionMethodOptions`** (`selection`, `entitySet`, …).
+- **`QuadroDatastoreFn<B, R>`** — **`B`**: body type; **`R`**: result type for **`quadro.<datastoreMethod>(body?)`**.
+
+### Examples
+
+**Per-class overrides** (`entities/Car.overrides.ts` in the split layout):
+
+```ts
+import type { QuadroDataClassFn, QuadroEntityFn } from '../_quadroFns.gen.js'
+import type { Car } from './Car.gen.js'
+
+export interface CarDataclassOverrides {
+  /** Catalog method name must match exactly (e.g. findACar). */
+  findACar: QuadroDataClassFn<Car[], [string, string]>
+}
+
+export interface CarEntityOverrides {
+  isAvailable: QuadroEntityFn<boolean, readonly []>
+}
+
+export interface CarEntityCollectionOverrides {}
+```
+
+**Datastore overrides** (`datastore.overrides.ts`):
+
+```ts
+import type { QuadroDatastoreFn } from './_quadroFns.gen.js'
+
+export interface DatastoreOverrides {
+  testFn: QuadroDatastoreFn<{ foo: string }, { ok: true }>
+}
+```
+
+### Regenerate behavior
+
+Run **`quadrokit-client generate`** after catalog changes. The tool **rewrites** **`*.gen.ts`** (and related generated files) but **keeps** your existing **`*.overrides.ts`** content when refreshing **`entities/`** (and only creates stub override files if missing). Do not rely on editing **`*.gen.ts`** — put signature narrowing in override modules only.
+
+---
+
 ## Low-level runtime (advanced)
 
 Import from **`@quadrokit/client/runtime`** when you need primitives without codegen:

package/dist/generate/codegen.mjs

@@ -155,7 +155,7 @@ 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[]>).
+ * Add entries under the interfaces (e.g. findACar: QuadroDataClassFn<Car[], [string, string]> — R then A).
  * Import fn types from \`'${quadroFnRelativeToStub}'\` when you add entries (or reference re-exports below).
  */
 export type {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quadrokit/client",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "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.15",
+    "@quadrokit/shared": "^0.3.16",
     "undici": "^6.21.0"
   },
   "peerDependencies": {