uql-orm 0.9.5 → 0.10.1

package/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to this project will be documented in this file. Please add
 
 date format is [yyyy-mm-dd]
 
+## [0.10.1] - 2026-07-03
+
+### Features
+
+- **`UqlModule` ends the pool on application shutdown** (`onApplicationShutdown`), so Nest testing modules and SIGTERM-driven shutdowns release database connections; call `app.enableShutdownHooks()` to wire signals.
+
+### Bug Fixes
+
+- **`uql-orm@0.10.0` on npm shipped only the browser bundle** (5 files; `dist/index.js` missing, so every server-side import failed). The package build shared the repo root's `tsBuildInfoFile` (introduced 2026-06-29 in an unrelated config cleanup): after `clean` wiped `dist`, `tsc -b` trusted the stale build info and emitted nothing, and the release published the partial `dist`. The build info is now package-local and the errant root-level one has been removed entirely, restoring the isolation each package had before that cleanup. `prepack` no longer checks two hardcoded files (which would have missed this exact failure — neither covered `uql-orm/migrate`); it now verifies every path declared in `main`, `types`, `bin`, and `exports` exists in `dist` before packing, derived straight from `package.json` so the check can't go stale as exports are added. Use 0.10.1 instead of 0.10.0.
+
+## [0.10.0] - 2026-07-02
+
+### Breaking Changes
+
+- **HTTP transport redesigned around a framework-agnostic core (`uql-orm/http`)**: the wire contract (routes, envelopes, query serialization) is defined once and shared by the server adapters and the browser client; `uql-orm/express` is now a thin adapter over it.
+  - **Hooks**: `pre`/`preSave`/`preFilter` receive a single `HookContext` (`{ meta, op, method, query, body, context }`) instead of `(req, meta)`, may be `async`, and abort by throwing (a numeric `status` on the error becomes the HTTP status). Migration is mechanical: `req.query` becomes `ctx.query`, `req.body` becomes `ctx.body`.
+  - **Error responses** are now `{ error: { message, code } }` (was `{ error: string }`).
+  - **`HttpQuerier.saveOne`** issues `PUT /<entity>` (server-side upsert) instead of client-side POST/PATCH branching.
+  - **Removed**: `buildQuerierRouter`, express `parseQuery` (use `parseQueryParams` from `uql-orm/http`), the `express.Request.query` type augmentation, and the browser re-exports of `stringifyQuery` and the envelope types (import them from `uql-orm/http`).
+  - **`uql-orm/browser` no longer loads `reflect-metadata`**: import it (or `uql-orm`) directly if you relied on that side effect.
+
+### Features
+
+- **`uql-orm/http`**: `createFetchHandler` mounts natively on Hono, Next.js route handlers, Bun.serve, Deno.serve, Cloudflare Workers, and SvelteKit; `createRequestHandler` bridges any other framework.
+- **Extended wire protocol**: new routes for `insertMany`, `saveOne` (upsert), `saveMany`, and bulk `updateMany`, with matching `HttpQuerier` methods.
+- **`uql-orm/nestjs`**: `UqlModule.forRoot({ pool })` registers the pool with Nest DI and as UQL's default pool.
+- **HTTP QUERY method (RFC 10008)**: reads can send the JSON query in the request body, avoiding URL-length limits; the client opts in via `new HttpQuerier('/api', { readMethod: 'QUERY' })`.
+- **Better client ergonomics**: per-call and per-instance `headers`, `AbortSignal` support, and non-2xx responses throw `RequestError` carrying the HTTP `status`.
+- **`post` hook**: shape the success envelope before it is sent (strip secrets, derive presentation fields).
+
+### Bug Fixes
+
+- **The published browser bundle was broken** (it contained test helpers instead of the client); it is now a 4 KB bundle with no `reflect-metadata`.
+- **The express middleware falls through** (`next()`) on unknown routes, so it composes with custom routes on the same prefix.
+- Hooks can now enforce `softDelete`; malformed JSON returns `400` instead of `500`; `HEAD` is served as `GET`; query strings are percent-encoded; `GET /<entity>/:id` merges an array `$where` via `$and` instead of overwriting it.
+
 ## [0.9.5] - 2026-07-02
 
 ### Documentation

package/README.md

@@ -13,7 +13,7 @@
 
 ```ts
 await querier.findMany(User, {
-  $select: { id: true, name: true },
+  $select: { id: true, email: true },
   $where: { email: { $endsWith: '@uql-orm.dev' } },
   $limit: 10,
 });
@@ -41,7 +41,8 @@ Full docs: **[uql-orm.dev](https://uql-orm.dev)**
 | Aggregate queries, grouping, HAVING | [Aggregate](https://uql-orm.dev/querying/aggregate) |
 | Semantic search & vector similarity | [Semantic Search](https://uql-orm.dev/ai-semantic-search) |
 | Streaming, transactions, raw SQL | [Querying](https://uql-orm.dev/querying/querier) |
-| NestJS integration & HttpQuerier | [Fullstack](https://uql-orm.dev/comparison) |
+| REST API from your entities (any framework) | [HTTP](https://uql-orm.dev/extensions-http) |
+| Typed browser client, NestJS module | [Browser](https://uql-orm.dev/extensions-browser) · [NestJS](https://uql-orm.dev/nestjs) |
 
 ## Install
 

package/dist/browser/http/bus.d.ts

@@ -0,0 +1,4 @@
+import type { RequestCallback, RequestNotification } from '../type/index.js';
+export declare function notify(notification: RequestNotification): void;
+export declare function on(cb: RequestCallback): () => void;
+//# sourceMappingURL=bus.d.ts.map

package/dist/browser/http/bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.d.ts","sourceRoot":"","sources":["../../../src/browser/http/bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAI7E,wBAAgB,MAAM,CAAC,YAAY,EAAE,mBAAmB,GAAG,IAAI,CAI9D;AAED,wBAAgB,EAAE,CAAC,EAAE,EAAE,eAAe,GAAG,MAAM,IAAI,CAMlD"}

package/dist/browser/http/bus.js

@@ -0,0 +1,14 @@
+const subscriptors = [];
+export function notify(notification) {
+    for (const subscriptor of subscriptors) {
+        subscriptor(notification);
+    }
+}
+export function on(cb) {
+    subscriptors.push(cb);
+    const index = subscriptors.length - 1;
+    return () => {
+        subscriptors.splice(index, 1);
+    };
+}
+//# sourceMappingURL=bus.js.map

package/dist/browser/http/bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.js","sourceRoot":"","sources":["../../../src/browser/http/bus.ts"],"names":[],"mappings":"AAEA,MAAM,YAAY,GAAsB,EAAE,CAAC;AAE3C,MAAM,UAAU,MAAM,CAAC,YAAiC;IACtD,KAAK,MAAM,WAAW,IAAI,YAAY,EAAE,CAAC;QACvC,WAAW,CAAC,YAAY,CAAC,CAAC;IAC5B,CAAC;AACH,CAAC;AAED,MAAM,UAAU,EAAE,CAAC,EAAmB;IACpC,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtB,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC;IACtC,OAAO,GAAS,EAAE;QAChB,YAAY,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAChC,CAAC,CAAC;AACJ,CAAC"}

package/dist/browser/http/http.d.ts

@@ -0,0 +1,22 @@
+import type { RequestSuccessResponse } from '../../http/contract.js';
+import type { RequestOptions } from '../type/index.js';
+/**
+ * Error thrown for non-2xx responses. Carries the HTTP status so callers can key
+ * behavior on it (401 redirects, 402 payment flows, error-boundary routing).
+ */
+export declare class RequestError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+export declare function get<T>(url: string, opts?: RequestOptions): Promise<RequestSuccessResponse<T>>;
+export declare function post<T>(url: string, payload: unknown, opts?: RequestOptions): Promise<RequestSuccessResponse<T>>;
+export declare function patch<T>(url: string, payload: unknown, opts?: RequestOptions): Promise<RequestSuccessResponse<T>>;
+export declare function put<T>(url: string, payload: unknown, opts?: RequestOptions): Promise<RequestSuccessResponse<T>>;
+export declare function remove<T>(url: string, opts?: RequestOptions): Promise<RequestSuccessResponse<T>>;
+/**
+ * HTTP QUERY (RFC 10008): a safe, idempotent read whose JSON query travels in the
+ * request body, avoiding URL-length limits. Method name must stay uppercase
+ * (fetch only normalizes the classic verbs).
+ */
+export declare function query<T>(url: string, payload: unknown, opts?: RequestOptions): Promise<RequestSuccessResponse<T>>;
+//# sourceMappingURL=http.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/browser/http/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAC3F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGvD;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;IAGnC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADvB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM;CAK1B;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,sCAExD;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,cAAc,sCAG3E;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,cAAc,sCAG5E;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,cAAc,sCAG1E;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,sCAE3D;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,cAAc,sCAG5E"}

package/dist/browser/http/http.js

@@ -0,0 +1,70 @@
+import { notify } from './bus.js';
+/**
+ * Error thrown for non-2xx responses. Carries the HTTP status so callers can key
+ * behavior on it (401 redirects, 402 payment flows, error-boundary routing).
+ */
+export class RequestError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'RequestError';
+    }
+}
+export function get(url, opts) {
+    return request(url, { method: 'get' }, opts);
+}
+export function post(url, payload, opts) {
+    const body = JSON.stringify(payload);
+    return request(url, { method: 'post', body }, opts);
+}
+export function patch(url, payload, opts) {
+    const body = JSON.stringify(payload);
+    return request(url, { method: 'patch', body }, opts);
+}
+export function put(url, payload, opts) {
+    const body = JSON.stringify(payload);
+    return request(url, { method: 'put', body }, opts);
+}
+export function remove(url, opts) {
+    return request(url, { method: 'delete' }, opts);
+}
+/**
+ * HTTP QUERY (RFC 10008): a safe, idempotent read whose JSON query travels in the
+ * request body, avoiding URL-length limits. Method name must stay uppercase
+ * (fetch only normalizes the classic verbs).
+ */
+export function query(url, payload, opts) {
+    const body = JSON.stringify(payload);
+    return request(url, { method: 'QUERY', body }, opts);
+}
+function request(url, init, opts) {
+    notify({ phase: 'start', opts });
+    init.headers = {
+        accept: 'application/json',
+        'content-type': 'application/json',
+        ...opts?.headers,
+    };
+    if (opts?.signal) {
+        init.signal = opts.signal;
+    }
+    return fetch(url, init)
+        .then((rawResp) => rawResp.json().then((resp) => {
+        const isSuccess = rawResp.status >= 200 && rawResp.status < 300;
+        if (isSuccess) {
+            notify({ phase: 'success', opts });
+            return resp;
+        }
+        const errorResp = resp;
+        const error = {
+            message: errorResp?.error?.message ?? rawResp.statusText,
+            code: errorResp?.error?.code ?? rawResp.status,
+        };
+        notify({ phase: 'error', error, opts });
+        throw new RequestError(error.message, error.code);
+    }))
+        .finally(() => {
+        notify({ phase: 'complete', opts });
+    });
+}
+//# sourceMappingURL=http.js.map

package/dist/browser/http/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/browser/http/http.ts"],"names":[],"mappings":"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"}

package/dist/browser/http/index.d.ts

@@ -0,0 +1,3 @@
+export * from './bus.js';
+export * from './http.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/browser/http/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/browser/http/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}

package/dist/browser/http/index.js

@@ -0,0 +1,3 @@
+export * from './bus.js';
+export * from './http.js';
+//# sourceMappingURL=index.js.map

package/dist/browser/http/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/browser/http/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC"}

package/dist/browser/index.d.ts

@@ -0,0 +1,5 @@
+export * from './http/index.js';
+export * from './options.js';
+export * from './querier/index.js';
+export * from './type/index.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}

package/dist/browser/index.js

@@ -0,0 +1,5 @@
+export * from './http/index.js';
+export * from './options.js';
+export * from './querier/index.js';
+export * from './type/index.js';
+//# sourceMappingURL=index.js.map

package/dist/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC"}

package/dist/browser/options.d.ts

@@ -0,0 +1,5 @@
+import type { ClientQuerier, ClientQuerierPool } from './type/index.js';
+export declare function setQuerierPool<T extends ClientQuerierPool>(pool: T): void;
+export declare function getQuerierPool(): ClientQuerierPool;
+export declare function getQuerier(): ClientQuerier;
+//# sourceMappingURL=options.d.ts.map

package/dist/browser/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/browser/options.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAMxE,wBAAgB,cAAc,CAAC,CAAC,SAAS,iBAAiB,EAAE,IAAI,EAAE,CAAC,QAElE;AAED,wBAAgB,cAAc,IAAI,iBAAiB,CAElD;AAED,wBAAgB,UAAU,IAAI,aAAa,CAE1C"}

package/dist/browser/options.js

@@ -0,0 +1,14 @@
+import { HttpQuerier } from './querier/httpQuerier.js';
+let defaultPool = {
+    getQuerier: () => new HttpQuerier('/api'),
+};
+export function setQuerierPool(pool) {
+    defaultPool = pool;
+}
+export function getQuerierPool() {
+    return defaultPool;
+}
+export function getQuerier() {
+    return getQuerierPool().getQuerier();
+}
+//# sourceMappingURL=options.js.map

package/dist/browser/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/browser/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAGvD,IAAI,WAAW,GAAsB;IACnC,UAAU,EAAE,GAAG,EAAE,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC;CAC1C,CAAC;AAEF,MAAM,UAAU,cAAc,CAA8B,IAAO;IACjE,WAAW,GAAG,IAAI,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,cAAc,EAAE,CAAC,UAAU,EAAE,CAAC;AACvC,CAAC"}

package/dist/browser/querier/httpQuerier.d.ts

@@ -0,0 +1,38 @@
+import { type HttpMethod, type RequestSuccessResponse } from '../../http/contract.js';
+import type { IdValue, Query, QueryOne, QueryOptions, QuerySearch, Type, UpdatePayload } from '../../type/index.js';
+import type { ClientQuerier, RequestFindOptions, RequestOptions } from '../type/index.js';
+export type HttpQuerierDefaults = {
+    /**
+     * headers sent with every request from this instance, merged under per-call headers.
+     * Create one instance per request (e.g. during SSR) to scope auth headers safely.
+     */
+    readonly headers?: Record<string, string>;
+    /**
+     * transport for read queries (findOne, findMany, count). 'QUERY' (RFC 10008) sends the
+     * JSON query in the request body, avoiding URL-length limits for large queries; requires
+     * infrastructure (proxies, CDNs) that forwards the QUERY method. Defaults to 'GET'.
+     */
+    readonly readMethod?: Extract<HttpMethod, 'GET' | 'QUERY'>;
+};
+export declare class HttpQuerier implements ClientQuerier {
+    readonly basePath: string;
+    readonly defaults: HttpQuerierDefaults;
+    constructor(basePath: string, defaults?: HttpQuerierDefaults);
+    findOneById<E>(entity: Type<E>, id: IdValue<E>, q?: QueryOne<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<E | undefined>>;
+    findOne<E>(entity: Type<E>, q: QueryOne<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<E | undefined>>;
+    findMany<E>(entity: Type<E>, q: Query<E>, opts?: RequestFindOptions): Promise<RequestSuccessResponse<E[]>>;
+    findManyAndCount<E>(entity: Type<E>, q: Query<E>, opts?: RequestFindOptions): Promise<RequestSuccessResponse<E[]>>;
+    count<E>(entity: Type<E>, q: QuerySearch<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<number>>;
+    insertOne<E>(entity: Type<E>, payload: E, opts?: RequestOptions): Promise<RequestSuccessResponse<IdValue<E>>>;
+    insertMany<E>(entity: Type<E>, payload: E[], opts?: RequestOptions): Promise<RequestSuccessResponse<IdValue<E>[]>>;
+    updateOneById<E>(entity: Type<E>, id: IdValue<E>, payload: UpdatePayload<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<number>>;
+    updateMany<E>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<number>>;
+    saveOne<E>(entity: Type<E>, payload: E, opts?: RequestOptions): Promise<RequestSuccessResponse<IdValue<E>>>;
+    saveMany<E>(entity: Type<E>, payload: E[], opts?: RequestOptions): Promise<RequestSuccessResponse<IdValue<E>[]>>;
+    deleteOneById<E>(entity: Type<E>, id: IdValue<E>, opts?: QueryOptions & RequestOptions): Promise<RequestSuccessResponse<number>>;
+    deleteMany<E>(entity: Type<E>, q: QuerySearch<E>, opts?: QueryOptions & RequestOptions): Promise<RequestSuccessResponse<number>>;
+    getBasePath<E>(entity: Type<E>): string;
+    protected read<T>(path: string, q: Record<string, unknown> | undefined, opts?: RequestOptions): Promise<RequestSuccessResponse<T>>;
+    protected buildOptions<O extends RequestOptions>(opts?: O): O | undefined;
+}
+//# sourceMappingURL=httpQuerier.d.ts.map

package/dist/browser/querier/httpQuerier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpQuerier.d.ts","sourceRoot":"","sources":["../../../src/browser/querier/httpQuerier.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,UAAU,EAAE,KAAK,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAE/G,OAAO,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpH,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAE1F,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,EAAE,KAAK,GAAG,OAAO,CAAC,CAAC;CAC5D,CAAC;AAEF,qBAAa,WAAY,YAAW,aAAa;IAE7C,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,QAAQ,EAAE,mBAAmB;gBAD7B,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,mBAAwB;IAG7C,WAAW,CAAC,CAAC,EACX,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EACf,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,EACd,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAAC,sBAAsB,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAMjD,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAIlH,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,kBAAkB;IAQnE,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,kBAAkB;IAI3E,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc;IAIlE,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc;IAK/D,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,cAAc;IAKlE,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc;IAKlG,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc;IAMlG,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,cAAc;IAK7D,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,cAAc;IAKhE,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,GAAE,YAAY,GAAG,cAAmB;IAM1F,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,GAAE,YAAY,GAAG,cAAmB;IAM1F,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;IAI9B,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAAE,IAAI,CAAC,EAAE,cAAc;IAO7F,SAAS,CAAC,YAAY,CAAC,CAAC,SAAS,cAAc,EAAE,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;CAM1E"}

package/dist/browser/querier/httpQuerier.js

@@ -0,0 +1,83 @@
+import { CRUD_ROUTES, entityPath } from '../../http/contract.js';
+import { stringifyQuery } from '../../http/query.js';
+import { get, query as httpQuery, patch, post, put, remove } from '../http/index.js';
+export class HttpQuerier {
+    basePath;
+    defaults;
+    constructor(basePath, defaults = {}) {
+        this.basePath = basePath;
+        this.defaults = defaults;
+    }
+    findOneById(entity, id, q, opts) {
+        const basePath = this.getBasePath(entity);
+        const qs = stringifyQuery(q);
+        return get(`${basePath}/${id}${qs}`, this.buildOptions(opts));
+    }
+    findOne(entity, q, opts) {
+        return this.read(`${this.getBasePath(entity)}${CRUD_ROUTES.findOne.path}`, q, opts);
+    }
+    findMany(entity, q, opts) {
+        const data = { ...q };
+        if (opts?.count) {
+            data.count = true;
+        }
+        return this.read(this.getBasePath(entity), data, opts);
+    }
+    findManyAndCount(entity, q, opts) {
+        return this.findMany(entity, q, { ...opts, count: true });
+    }
+    count(entity, q, opts) {
+        return this.read(`${this.getBasePath(entity)}${CRUD_ROUTES.count.path}`, q, opts);
+    }
+    insertOne(entity, payload, opts) {
+        const basePath = this.getBasePath(entity);
+        return post(basePath, payload, this.buildOptions(opts));
+    }
+    insertMany(entity, payload, opts) {
+        const basePath = this.getBasePath(entity);
+        return post(`${basePath}${CRUD_ROUTES.insertMany.path}`, payload, this.buildOptions(opts));
+    }
+    updateOneById(entity, id, payload, opts) {
+        const basePath = this.getBasePath(entity);
+        return patch(`${basePath}/${id}`, payload, this.buildOptions(opts));
+    }
+    updateMany(entity, q, payload, opts) {
+        const basePath = this.getBasePath(entity);
+        const qs = stringifyQuery(q);
+        return patch(`${basePath}${qs}`, payload, this.buildOptions(opts));
+    }
+    saveOne(entity, payload, opts) {
+        const basePath = this.getBasePath(entity);
+        return put(basePath, payload, this.buildOptions(opts));
+    }
+    saveMany(entity, payload, opts) {
+        const basePath = this.getBasePath(entity);
+        return put(`${basePath}${CRUD_ROUTES.saveMany.path}`, payload, this.buildOptions(opts));
+    }
+    deleteOneById(entity, id, opts = {}) {
+        const basePath = this.getBasePath(entity);
+        const qs = opts.softDelete ? stringifyQuery({ softDelete: opts.softDelete }) : '';
+        return remove(`${basePath}/${id}${qs}`, this.buildOptions(opts));
+    }
+    deleteMany(entity, q, opts = {}) {
+        const basePath = this.getBasePath(entity);
+        const qs = stringifyQuery(opts.softDelete ? { ...q, softDelete: opts.softDelete } : q);
+        return remove(`${basePath}${qs}`, this.buildOptions(opts));
+    }
+    getBasePath(entity) {
+        return `${this.basePath}/${entityPath(entity)}`;
+    }
+    read(path, q, opts) {
+        if (this.defaults.readMethod === 'QUERY') {
+            return httpQuery(path, q ?? {}, this.buildOptions(opts));
+        }
+        return get(`${path}${stringifyQuery(q)}`, this.buildOptions(opts));
+    }
+    buildOptions(opts) {
+        if (!this.defaults.headers && !opts?.headers) {
+            return opts;
+        }
+        return { ...opts, headers: { ...this.defaults.headers, ...opts?.headers } };
+    }
+}
+//# sourceMappingURL=httpQuerier.js.map

package/dist/browser/querier/httpQuerier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpQuerier.js","sourceRoot":"","sources":["../../../src/browser/querier/httpQuerier.ts"],"names":[],"mappings":"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"}

package/dist/browser/querier/index.d.ts

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

package/dist/browser/querier/index.d.ts.map

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

package/dist/browser/querier/index.js

@@ -0,0 +1,2 @@
+export * from './httpQuerier.js';
+//# sourceMappingURL=index.js.map

package/dist/browser/querier/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/browser/querier/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/browser/type/clientQuerier.d.ts

@@ -0,0 +1,28 @@
+import type { RequestSuccessResponse } from '../../http/contract.js';
+import type { IdValue, Query, QueryOne, QueryOptions, QuerySearch, Type, UpdatePayload } from '../../type/index.js';
+import type { RequestOptions } from './request.js';
+/**
+ * Client-side querier — mirrors {@link UniversalQuerier} method names and semantics but with two structural differences:
+ * 1. Every return type is wrapped in `RequestSuccessResponse<T>` (adds `data`/`count` envelope).
+ * 2. Every method accepts an extra `opts?: RequestOptions` parameter.
+ *
+ * These differences prevent clean `extends UniversalQuerier` — TypeScript does not support
+ * higher-kinded type wrappers, so the interfaces are kept in sync by convention.
+ * @see UniversalQuerier for the server-side contract with direct return types.
+ */
+export interface ClientQuerier {
+    findOneById<E>(entity: Type<E>, id: IdValue<E>, q?: QueryOne<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<E | undefined>>;
+    findOne<E>(entity: Type<E>, q: QueryOne<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<E | undefined>>;
+    findMany<E>(entity: Type<E>, q: Query<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<E[]>>;
+    findManyAndCount<E>(entity: Type<E>, q: Query<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<E[]>>;
+    count<E>(entity: Type<E>, q?: QuerySearch<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<number>>;
+    insertOne<E>(entity: Type<E>, payload: E, opts?: RequestOptions): Promise<RequestSuccessResponse<IdValue<E>>>;
+    insertMany<E>(entity: Type<E>, payload: E[], opts?: RequestOptions): Promise<RequestSuccessResponse<IdValue<E>[]>>;
+    updateOneById<E>(entity: Type<E>, id: IdValue<E>, payload: UpdatePayload<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<number>>;
+    updateMany<E>(entity: Type<E>, q: QuerySearch<E>, payload: UpdatePayload<E>, opts?: RequestOptions): Promise<RequestSuccessResponse<number>>;
+    saveOne<E>(entity: Type<E>, payload: E, opts?: RequestOptions): Promise<RequestSuccessResponse<IdValue<E>>>;
+    saveMany<E>(entity: Type<E>, payload: E[], opts?: RequestOptions): Promise<RequestSuccessResponse<IdValue<E>[]>>;
+    deleteOneById<E>(entity: Type<E>, id: IdValue<E>, opts?: QueryOptions & RequestOptions): Promise<RequestSuccessResponse<number>>;
+    deleteMany<E>(entity: Type<E>, qm: QuerySearch<E>, opts?: QueryOptions & RequestOptions): Promise<RequestSuccessResponse<number>>;
+}
+//# sourceMappingURL=clientQuerier.d.ts.map

package/dist/browser/type/clientQuerier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clientQuerier.d.ts","sourceRoot":"","sources":["../../../src/browser/type/clientQuerier.ts"],"names":[],"mappings":"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"}

package/dist/browser/type/clientQuerier.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=clientQuerier.js.map

package/dist/browser/type/clientQuerier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clientQuerier.js","sourceRoot":"","sources":["../../../src/browser/type/clientQuerier.ts"],"names":[],"mappings":""}

package/dist/browser/type/clientQuerierPool.d.ts

@@ -0,0 +1,5 @@
+import type { ClientQuerier } from './clientQuerier.js';
+export type ClientQuerierPool = {
+    getQuerier(): ClientQuerier;
+};
+//# sourceMappingURL=clientQuerierPool.d.ts.map

package/dist/browser/type/clientQuerierPool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clientQuerierPool.d.ts","sourceRoot":"","sources":["../../../src/browser/type/clientQuerierPool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,UAAU,IAAI,aAAa,CAAC;CAC7B,CAAC"}

package/dist/browser/type/clientQuerierPool.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=clientQuerierPool.js.map

package/dist/browser/type/clientQuerierPool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clientQuerierPool.js","sourceRoot":"","sources":["../../../src/browser/type/clientQuerierPool.ts"],"names":[],"mappings":""}

package/dist/browser/type/index.d.ts

@@ -0,0 +1,4 @@
+export * from './clientQuerier.js';
+export * from './clientQuerierPool.js';
+export * from './request.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/browser/type/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/browser/type/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,cAAc,CAAC"}

package/dist/browser/type/index.js

@@ -0,0 +1,4 @@
+export * from './clientQuerier.js';
+export * from './clientQuerierPool.js';
+export * from './request.js';
+//# sourceMappingURL=index.js.map

package/dist/browser/type/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/browser/type/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AAEvC,cAAc,cAAc,CAAC"}

package/dist/browser/type/request.d.ts

@@ -0,0 +1,28 @@
+import type { RequestErrorResponse } from '../../http/contract.js';
+export type RequestOptions = {
+    silent?: boolean;
+    /**
+     * extra headers merged over the defaults (e.g. `{ Authorization: 'Bearer ...' }`).
+     */
+    headers?: Record<string, string>;
+    /**
+     * abort/timeout control, e.g. `AbortSignal.timeout(120_000)` for long-running calls.
+     */
+    signal?: AbortSignal;
+};
+export type RequestFindOptions = RequestOptions & {
+    count?: boolean;
+};
+type RequestBaseNotification = {
+    readonly opts?: RequestOptions;
+};
+type RequestSuccessNotification = {
+    readonly phase: 'start' | 'success' | 'complete';
+} & RequestBaseNotification;
+type RequestErrorNotification = {
+    readonly phase: 'error';
+} & RequestErrorResponse & RequestBaseNotification;
+export type RequestNotification = RequestSuccessNotification | RequestErrorNotification;
+export type RequestCallback = (msg: RequestNotification) => void;
+export {};
+//# sourceMappingURL=request.d.ts.map

package/dist/browser/type/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../../src/browser/type/request.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAEnE,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,cAAc,GAAG;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,KAAK,uBAAuB,GAAG;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,CAAA;CAAE,CAAC;AAClE,KAAK,0BAA0B,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,UAAU,CAAA;CAAE,GAAG,uBAAuB,CAAC;AACjH,KAAK,wBAAwB,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,oBAAoB,GAAG,uBAAuB,CAAC;AAC7G,MAAM,MAAM,mBAAmB,GAAG,0BAA0B,GAAG,wBAAwB,CAAC;AACxF,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,mBAAmB,KAAK,IAAI,CAAC"}

package/dist/browser/type/request.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=request.js.map

package/dist/browser/type/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../../src/browser/type/request.ts"],"names":[],"mappings":""}