@atscript/db-client 0.1.164 → 0.1.165

package/dist/index.cjs

@@ -1,150 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_client_error = require("./client-error-C9Q5xCuW.cjs");
 let _uniqu_url_builder = require("@uniqu/url/builder");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let _uniqu_core = require("@uniqu/core");
-//#region src/client-error.ts
-/**
-* Error thrown by `Client` when the server responds with a non-2xx status code.
-* Captures the HTTP status and the structured error body from moost-db.
-*/
-var ClientError = class extends Error {
-	status;
-	body;
-	name = "ClientError";
-	constructor(status, body) {
-		super(body.message || `HTTP ${status}`);
-		this.status = status;
-		this.body = body;
-	}
-	/** Shortcut to structured validation/DB errors from the server. */
-	get errors() {
-		return this.body.errors ?? [];
-	}
-};
-/**
-* Typed marker thrown by `Client._send` when the server response body's
-* `name === 'ActionDisabledError'`. The transport / status / base body are
-* identical to a generic `ClientError`; this subclass adds typed accessors
-* so consumers can write `catch (e) { if (e instanceof ActionDisabledError) … }`
-* to access `action` / `id` / `ids` / `reason` / `reasons` without indexing
-* into `body`.
-*/
-var ActionDisabledError = class extends ClientError {
-	name = "ActionDisabledError";
-	/** The `@DbAction` name that rejected the request. */
-	get action() {
-		return this.body.action;
-	}
-	/** Present only for `'row'`-level rejections. */
-	get id() {
-		return this.body.id;
-	}
-	/** Present only for `'rows'`-level rejections (full list of failing IDs). */
-	get ids() {
-		return this.body.ids;
-	}
-	/**
-	* Human-readable reason shared by every rejected row — present only when
-	* the server's `disabled` predicate returned one. `message` already
-	* carries it.
-	*
-	* @since 0.1.141
-	*/
-	get reason() {
-		return this.body.reason;
-	}
-	/**
-	* `'rows'`-level only: per-row reasons index-aligned with {@link ids}
-	* (`null` where that row has none). Present only when at least one
-	* rejected row carries a reason.
-	*
-	* @since 0.1.141
-	*/
-	get reasons() {
-		return this.body.reasons;
-	}
-};
-/**
-* Typed marker thrown by `Client` when a query-targeted action request is
-* refused (body `name === 'ActionTargetError'`): `TARGET_INVALID` (400),
-* `TARGET_TOO_LARGE` (400, `cap`) or `TARGET_CHANGED` (409, `matched` — the
-* rows the query matches now; re-confirm and retry with that count).
-*
-* @since 0.1.147
-*/
-var ActionTargetError = class extends ClientError {
-	name = "ActionTargetError";
-	get code() {
-		return this.body.code;
-	}
-	get action() {
-		return this.body.action;
-	}
-	get matched() {
-		return this.body.matched;
-	}
-	get cap() {
-		return this.body.cap;
-	}
-};
-/**
-* Typed marker thrown by `Client._send` when the server response body's
-* `kind === 'version_mismatch'`. The transport / status / base body are
-* identical to a generic `ClientError`; this subclass adds a typed
-* `currentVersion` accessor so consumers can write
-* `catch (e) { if (e instanceof VersionMismatchError) … }` without casting.
-*/
-var VersionMismatchError = class extends ClientError {
-	name = "VersionMismatchError";
-	/** Row's current server-side version — clients refresh + retry against it. */
-	get currentVersion() {
-		return this.body.currentVersion;
-	}
-};
-/**
-* Thrown by `Client` when NO server verdict was obtained: `fetch` itself
-* rejected (network down, DNS, CORS, `AbortError`, …) or a 2xx response
-* carried a body that is not JSON. Unlike {@link ClientError} — where the
-* server answered and rejected — the request's outcome is unknown: a write
-* may have committed. Reload before retrying a non-idempotent write.
-* The underlying error is the standard `cause`.
-*/
-var TransportError = class extends Error {
-	method;
-	url;
-	name = "TransportError";
-	constructor(method, url, detail, cause) {
-		super(`${method} ${url}: ${detail}`, { cause });
-		this.method = method;
-		this.url = url;
-	}
-};
-/** Thrown by `Client.action()` when the action name is not present in `/meta`. */
-var ActionNotFoundError = class extends Error {
-	action;
-	name = "ActionNotFoundError";
-	constructor(action) {
-		super(`Action "${action}" is not declared on this controller`);
-		this.action = action;
-	}
-};
-/**
-* Thrown by `Client.action()` for actions that cannot be invoked through
-* the client — currently `processor: 'custom'` (UI-dispatched events,
-* which the application is responsible for handling) and `processor: 'navigate'`
-* when no browser environment and no `navigate` option are configured.
-*/
-var ActionUnsupportedError = class extends Error {
-	action;
-	processor;
-	name = "ActionUnsupportedError";
-	constructor(action, processor, message) {
-		super(message);
-		this.action = action;
-		this.processor = processor;
-	}
-};
-//#endregion
 //#region src/meta-store.ts
 /** ETags remembered per store key (most recent first). */
 const CANDIDATES_PER_KEY = 4;
@@ -336,17 +194,17 @@ var Client = class {
 	* The response type narrows by the literal `$with` array in `query` —
 	* relations not listed in `$with` are stripped from the row type.
 	*/
-	async query(query) {
-		return this._get("query", query);
+	async query(query, opts) {
+		return this._get("query", query, opts?.signal);
 	}
 	/**
 	* `GET /query` with `$count: true` — returns record count.
 	*/
-	async count(query) {
+	async count(query, opts) {
 		return this._get("query", {
 			...query,
 			controls: { $count: true }
-		});
+		}, opts?.signal);
 	}
 	/**
 	* `GET /query` with `$groupBy` — aggregate query with typed dimension/measure fields.
@@ -365,8 +223,8 @@ var Client = class {
 	* read a representative row ordered by `$rowOrder`. The URL forms are `expr(a/b):x`,
 	* `sum(a*b):x`, `first(f):x` and `$rowOrder=f,-id`.
 	*/
-	async aggregate(query) {
-		return this._get("query", query);
+	async aggregate(query, opts) {
+		return this._get("query", query, opts?.signal);
 	}
 	/**
 	* `GET /pages` — paginated query with typed filter and relations.
@@ -374,7 +232,7 @@ var Client = class {
 	* Response rows narrow by the literal `$with` array — same algebra as
 	* {@link query}.
 	*/
-	async pages(query, page = 1, size = 10) {
+	async pages(query, page = 1, size = 10, opts) {
 		return this._get("pages", {
 			...query,
 			controls: {
@@ -382,7 +240,7 @@ var Client = class {
 				$page: page,
 				$size: size
 			}
-		});
+		}, opts?.signal);
 	}
 	/**
 	* `GET /geo` — distance-ranked geospatial search (tables with `@db.index.geo`).
@@ -393,19 +251,19 @@ var Client = class {
 	* in `query.controls`; filter / `$select` / `$with` / `$skip` / `$limit`
 	* compose as usual.
 	*/
-	async geoSearch(point, query) {
+	async geoSearch(point, query, opts) {
 		return this._get("geo", {
 			...query,
 			controls: {
 				...query?.controls,
 				$center: point.join(",")
 			}
-		});
+		}, opts?.signal);
 	}
 	/**
 	* `GET /geo` with `$page` / `$size` — paginated distance-ranked search.
 	*/
-	async geoPages(point, query, page = 1, size = 10) {
+	async geoPages(point, query, page = 1, size = 10, opts) {
 		return this._get("geo", {
 			...query,
 			controls: {
@@ -414,7 +272,7 @@ var Client = class {
 				$page: page,
 				$size: size
 			}
-		});
+		}, opts?.signal);
 	}
 	/**
 	* `GET /one/:id` or `GET /one?k1=v1&k2=v2` — single record by primary key.
@@ -422,13 +280,13 @@ var Client = class {
 	* Returns `null` on 404. Response narrows by the literal `$with` array in
 	* `query.controls` — same algebra as {@link query}.
 	*/
-	async one(id, query) {
+	async one(id, query, opts) {
 		const controlStr = query?.controls ? (0, _uniqu_url_builder.buildUrl)({ controls: query.controls }) : "";
-		return this._getOrNull(this._idUrl("one", id, controlStr));
+		return this._getOrNull(this._idUrl("one", id, controlStr), opts?.signal);
 	}
 	async insert(data, opts) {
 		const query = opts?.onConflict === "ignore" ? "?$onConflict=ignore" : "";
-		return this._request("POST", query, await this._prepareWrite(data, "insert"));
+		return this._request("POST", query, await this._prepareWrite(data, "insert"), opts);
 	}
 	/**
 	* `PATCH /` — partial update one or many records by primary key.
@@ -439,21 +297,21 @@ var Client = class {
 	* {@link VersionMismatchError}; a PK-only body with a version is a real
 	* write (the server bumps the version).
 	*/
-	async update(data) {
-		return this._request("PATCH", "", await this._prepareWrite(data, "patch"));
+	async update(data, opts) {
+		return this._request("PATCH", "", await this._prepareWrite(data, "patch"), opts);
 	}
 	/**
 	* `PUT /` — full replace one or many records by primary key. Same OCC
 	* shapes as {@link update}; the version column itself is optional.
 	*/
-	async replace(data) {
-		return this._request("PUT", "", await this._prepareWrite(data, "replace"));
+	async replace(data, opts) {
+		return this._request("PUT", "", await this._prepareWrite(data, "replace"), opts);
 	}
 	/**
 	* `DELETE /:id` or `DELETE /?k1=v1&k2=v2` — remove a record by primary key.
 	*/
-	async remove(id) {
-		return this._request("DELETE", this._idUrl("", id));
+	async remove(id, opts) {
+		return this._request("DELETE", this._idUrl("", id), void 0, opts);
 	}
 	/**
 	* `GET /meta` — table/view metadata (cached after first call).
@@ -569,8 +427,8 @@ var Client = class {
 	async action(name, id, input) {
 		const meta = await this.meta();
 		const action = meta.actions.find((a) => a.name === name);
-		if (!action) throw new ActionNotFoundError(name);
-		if (action.processor === "custom") throw new ActionUnsupportedError(name, "custom", `Action "${name}" has processor "custom" — applications must dispatch custom actions themselves; the client cannot.`);
+		if (!action) throw new require_client_error.ActionNotFoundError(name);
+		if (action.processor === "custom") throw new require_client_error.ActionUnsupportedError(name, "custom", `Action "${name}" has processor "custom" — applications must dispatch custom actions themselves; the client cannot.`);
 		const mapped = action.idMap ? mapDelegatedIds(action, id) : id;
 		if (action.processor === "navigate") {
 			const order = action.idMap ? Object.keys(action.idMap) : meta.preferredId;
@@ -621,13 +479,13 @@ var Client = class {
 	}
 	async _queryTargetAction(name) {
 		const action = (await this.meta()).actions.find((a) => a.name === name);
-		if (!action) throw new ActionNotFoundError(name);
-		if (!action.queryTarget || action.processor !== "backend") throw new ActionUnsupportedError(name, action.processor, `Action "${name}" does not accept a query target (no \`queryTarget\` in /meta).`);
+		if (!action) throw new require_client_error.ActionNotFoundError(name);
+		if (!action.queryTarget || action.processor !== "backend") throw new require_client_error.ActionUnsupportedError(name, action.processor, `Action "${name}" does not accept a query target (no \`queryTarget\` in /meta).`);
 		return action;
 	}
 	_postQueryTarget(action, body) {
 		const path = action.queryTarget?.url ?? action.value;
-		return this._requestUrl("POST", `${this._baseUrl}${path}`, body, true);
+		return this._requestUrl("POST", `${this._baseUrl}${path}`, body, { allowEmpty: true });
 	}
 	/**
 	* `GET /meta/actions/:id` or `GET /meta/actions?k1=v1&k2=v2` — the
@@ -730,10 +588,10 @@ var Client = class {
 			loc.assign(url);
 			return;
 		}
-		throw new ActionUnsupportedError(action.name, "navigate", `Action "${action.name}" is processor: 'navigate' but no browser is available and no \`navigate\` option was provided to Client.`);
+		throw new require_client_error.ActionUnsupportedError(action.name, "navigate", `Action "${action.name}" is processor: 'navigate' but no browser is available and no \`navigate\` option was provided to Client.`);
 	}
 	_postAction(action, body) {
-		return this._requestUrl("POST", `${this._baseUrl}${action.value}`, body, true);
+		return this._requestUrl("POST", `${this._baseUrl}${action.value}`, body, { allowEmpty: true });
 	}
 	_idToParams(id) {
 		const params = new URLSearchParams();
@@ -755,17 +613,17 @@ var Client = class {
 		const path = `${base ? `${base}/` : ""}${encodeURIComponent(String(id))}`;
 		return query ? `${path}?${query}` : path;
 	}
-	async _getOrNull(endpoint) {
+	async _getOrNull(endpoint, signal) {
 		try {
-			return await this._request("GET", endpoint);
+			return await this._request("GET", endpoint, void 0, { signal });
 		} catch (e) {
-			if (e instanceof ClientError && e.status === 404) return null;
+			if (e instanceof require_client_error.ClientError && e.status === 404) return null;
 			throw e;
 		}
 	}
-	async _get(endpoint, query) {
+	async _get(endpoint, query, signal) {
 		const qs = query ? (0, _uniqu_url_builder.buildUrl)(query) : "";
-		return this._request("GET", `${endpoint}${qs ? `?${qs}` : ""}`);
+		return this._request("GET", `${endpoint}${qs ? `?${qs}` : ""}`, void 0, { signal });
 	}
 	async _resolveHeaders() {
 		if (!this._headers) return {};
@@ -841,7 +699,7 @@ var Client = class {
 			text = await res.text();
 			body = JSON.parse(text);
 		} catch (cause) {
-			throw new TransportError("GET", url, `HTTP ${res.status} body is not JSON (${describeCause(cause)})`, cause);
+			throw new require_client_error.TransportError("GET", url, `HTTP ${res.status} body is not JSON (${describeCause(cause)})`, cause);
 		}
 		store._put(key, etag, text);
 		return {
@@ -849,8 +707,8 @@ var Client = class {
 			etag
 		};
 	}
-	_request(method, endpoint, body) {
-		return this._requestUrl(method, this._endpointUrl(endpoint), body);
+	_request(method, endpoint, body, opts) {
+		return this._requestUrl(method, this._endpointUrl(endpoint), body, opts);
 	}
 	/** `baseUrl + path` joined with an endpoint relative to this controller (`""`, `meta`, `?q`…). */
 	_endpointUrl(endpoint) {
@@ -858,17 +716,18 @@ var Client = class {
 		return `${this._baseUrl}${this._path}${sep}${endpoint}`;
 	}
 	/** Sends one request to an absolute URL with the client's headers and a JSON body. */
-	async _requestUrl(method, url, body, allowEmpty = false) {
+	async _requestUrl(method, url, body, opts) {
 		const headers = { ...await this._resolveHeaders() };
 		const init = {
 			method,
 			headers
 		};
+		if (opts?.signal) init.signal = opts.signal;
 		if (body !== void 0) {
 			headers["Content-Type"] = "application/json";
 			init.body = JSON.stringify(body);
 		}
-		return this._send(url, init, allowEmpty);
+		return this._send(url, init, opts?.allowEmpty === true);
 	}
 	async _send(url, init, allowEmpty) {
 		const res = await this._fetchUrl(url, init);
@@ -879,7 +738,7 @@ var Client = class {
 		try {
 			return await this._fetch(url, init);
 		} catch (cause) {
-			throw new TransportError(init.method ?? "GET", url, describeCause(cause), cause);
+			throw new require_client_error.TransportError(init.method ?? "GET", url, describeCause(cause), cause);
 		}
 	}
 	/** A response's JSON body, or the matching error for a non-2xx status. */
@@ -894,15 +753,15 @@ var Client = class {
 					statusCode: res.status
 				};
 			}
-			if (errorBody.name === "ActionDisabledError") throw new ActionDisabledError(res.status, errorBody);
-			if (errorBody.name === "ActionTargetError") throw new ActionTargetError(res.status, errorBody);
-			if (errorBody.kind === "version_mismatch") throw new VersionMismatchError(res.status, errorBody);
-			throw new ClientError(res.status, errorBody);
+			if (errorBody.name === "ActionDisabledError") throw new require_client_error.ActionDisabledError(res.status, errorBody);
+			if (errorBody.name === "ActionTargetError") throw new require_client_error.ActionTargetError(res.status, errorBody);
+			if (errorBody.kind === "version_mismatch") throw new require_client_error.VersionMismatchError(res.status, errorBody);
+			throw new require_client_error.ClientError(res.status, errorBody);
 		}
 		if (!allowEmpty) try {
 			return await res.json();
 		} catch (cause) {
-			throw new TransportError(method, url, `HTTP ${res.status} body is not JSON (${describeCause(cause)})`, cause);
+			throw new require_client_error.TransportError(method, url, `HTTP ${res.status} body is not JSON (${describeCause(cause)})`, cause);
 		}
 		if (res.status === 204 || res.headers.get("content-length") === "0") return void 0;
 		try {
@@ -1014,15 +873,16 @@ function describeShape(value) {
 	return typeof value;
 }
 //#endregion
-exports.ActionDisabledError = ActionDisabledError;
-exports.ActionNotFoundError = ActionNotFoundError;
-exports.ActionTargetError = ActionTargetError;
-exports.ActionUnsupportedError = ActionUnsupportedError;
+exports.ActionDisabledError = require_client_error.ActionDisabledError;
+exports.ActionNotFoundError = require_client_error.ActionNotFoundError;
+exports.ActionTargetError = require_client_error.ActionTargetError;
+exports.ActionUnsupportedError = require_client_error.ActionUnsupportedError;
 exports.Client = Client;
-exports.ClientError = ClientError;
+exports.ClientError = require_client_error.ClientError;
+exports.ClientValidationError = require_client_error.ClientValidationError;
 exports.MetaStore = MetaStore;
-exports.TransportError = TransportError;
-exports.VersionMismatchError = VersionMismatchError;
+exports.TransportError = require_client_error.TransportError;
+exports.VersionMismatchError = require_client_error.VersionMismatchError;
 exports.actionIdentifier = actionIdentifier;
 Object.defineProperty(exports, "bucketSeries", {
 	enumerable: true,