@quadrokit/client 0.3.13 → 0.3.14

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).
 
 ---
 
@@ -53,7 +54,7 @@ Environment variables (often via `.env` in the project root): `VITE_4D_ORIGIN`,
 |------|---------|
 | **`types.gen.ts`** | Entity interfaces; **`*Path`** aliases use **`QuadroAttributePaths<T>`** (recursive dot paths, depth-limited for circular relations); **`QuadroClient`** typing. |
 | **`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 +81,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.
@@ -178,7 +259,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 +273,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/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.14",
   "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.14",
     "undici": "^6.21.0"
   },
   "peerDependencies": {