@atscript/db-client 0.1.164 → 0.1.165

package/dist/{validator-zwjB-484.d.mts → validator-tvR4Sl3l.d.mts}

@@ -172,15 +172,38 @@ interface PageResult<T> {
   pages: number;
   count: number;
 }
-/** Server error response shape (matches moost-db error transform). */
+/**
+ * Per-call options of the `Client` read / write methods (since 0.1.165).
+ */
+interface TClientCallOptions {
+  /**
+   * Cancels the request. An aborted request rejects with a `TransportError`
+   * whose `aborted` is `true` (the `AbortError` is its `cause`).
+   */
+  signal?: AbortSignal;
+}
+/** One entry of a server error's `errors` list. */
+interface ServerErrorEntry {
+  path: string;
+  message: string;
+  /** Machine-readable reason (`UNIQUE`, `FK_MISSING`, `FK_RESTRICT`, …). @since 0.1.165 */
+  code?: string;
+  /** Values the message names, for translating it. @since 0.1.165 */
+  params?: Record<string, unknown>;
+  details?: unknown[];
+}
+/**
+ * Server error response shape (matches moost-db error transform). Open to
+ * extra fields (since 0.1.165): a handler's own error body (`quota`, `tier`,
+ * …) reads without a cast — type it with `ClientError<B>`.
+ */
 interface ServerError {
   message: string;
   statusCode: number;
-  errors?: Array<{
-    path: string;
-    message: string;
-    details?: unknown[];
-  }>;
+  /** The `DbError` code (`CONFLICT`, `FK_VIOLATION`, …) or a handler's own. @since 0.1.165 */
+  code?: string;
+  errors?: ServerErrorEntry[];
+  [key: string]: unknown;
 }
 /**
  * Minimal brand shape every `Client<T>` generic must satisfy. All fields are
@@ -203,6 +226,16 @@ type DataOf<T> = T extends {
     __dataType?: infer D;
   };
 } ? unknown extends D ? T extends (new (...a: any[]) => infer I) ? I : Record<string, unknown> : D & Record<string, unknown> : Record<string, unknown>;
+/**
+ * The row type a read answers with: {@link DataOf} without its
+ * `Record<string, unknown>` widening, which would make `DbResponse`'s
+ * `Omit` collapse every field to `unknown` (since 0.1.165).
+ */
+type ResponseDataOf<T> = T extends {
+  type: {
+    __dataType?: infer D;
+  };
+} ? unknown extends D ? T extends (new (...a: any[]) => infer I) ? I : Record<string, unknown> : D : Record<string, unknown>;
 /**
  * `$select` controls of a read over `T` whose controller declares the display-only
  * fields `D` (`@DbDecorations`): `$select` also accepts `keyof D`; filter, sort
@@ -235,7 +268,7 @@ type IdOf<T> = T extends {
  * short-circuits to the data type. `$actions` / `$disabledReasons` are always
  * optional — the server emits them only when the request set `?$actions=true`.
  */
-type ClientResponse<T, Q> = DbResponse<DataOf<T>, NavOf<T>, Q> & {
+type ClientResponse<T, Q> = DbResponse<ResponseDataOf<T>, NavOf<T>, Q> & {
   /**
    * Server-evaluated per-row availability for `'row'` and `'rows'`-level
    * actions. Each entry is the `name` of an action that is NOT disabled for
@@ -274,6 +307,200 @@ interface TDbQueryTarget<T = AtscriptClientShape> {
   maxRows?: number;
 }
 //#endregion
+//#region src/client-error.d.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.
+ */
+declare class ClientError<B extends ServerError = ServerError> extends Error {
+  /** HTTP status code (e.g. 400, 404, 409, 500). */
+  readonly status: number;
+  /**
+   * Structured error response from the server. `B` (since 0.1.165) types a
+   * body that carries fields of its own: `new ClientError<QuotaBody>(…)`,
+   * `(e as ClientError<QuotaBody>).body.quota`.
+   */
+  readonly body: B;
+  name: string;
+  constructor(/** HTTP status code (e.g. 400, 404, 409, 500). */
+
+  status: number,
+  /**
+   * Structured error response from the server. `B` (since 0.1.165) types a
+   * body that carries fields of its own: `new ClientError<QuotaBody>(…)`,
+   * `(e as ClientError<QuotaBody>).body.quota`.
+   */
+
+  body: B);
+  /** Shortcut to structured validation/DB errors from the server. */
+  get errors(): ServerErrorEntry[];
+}
+/**
+ * Thrown before the request is sent when the client-side preflight
+ * (`validator` option, `ClientValidator`) rejects a write. A
+ * {@link ClientError} since 0.1.165 — status `400`, `body` shaped like the
+ * server's validation envelope (`{ message, statusCode: 400, errors }`) — so
+ * one `instanceof ClientError` branch handles a preflight failure and the
+ * server's 400 alike; `preflight` (`true`) tells them apart. The same class
+ * is exported from `@atscript/db-client` and `@atscript/db-client/validator`.
+ */
+declare class ClientValidationError extends ClientError {
+  name: string;
+  /** `true`: the request never left the client. */
+  readonly preflight: true;
+  constructor(errors: Array<{
+    path: string;
+    message: string;
+  }>);
+}
+/**
+ * Wire-body shape for `ActionDisabledError` responses (HTTP 409). Extends
+ * the base `ServerError` envelope with a `name` discriminator, the action
+ * name, and the offending identifier(s). The bridge between `@atscript/moost-db`'s
+ * server-side error and this typed client-side subclass is the wire JSON
+ * body — neither package depends on the other.
+ */
+interface ActionDisabledErrorBody extends ServerError {
+  name: "ActionDisabledError";
+  action: string;
+  id?: Record<string, unknown>;
+  ids?: Record<string, unknown>[];
+  /** Reason shared by every rejected row, when the server's predicate gave one. @since 0.1.141 */
+  reason?: string;
+  /** `'rows'` level: index-aligned with `ids`, `null` = no reason for that row. @since 0.1.141 */
+  reasons?: (string | null)[];
+}
+/**
+ * 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`.
+ */
+declare class ActionDisabledError extends ClientError {
+  name: string;
+  /** The `@DbAction` name that rejected the request. */
+  get action(): string;
+  /** Present only for `'row'`-level rejections. */
+  get id(): Record<string, unknown> | undefined;
+  /** Present only for `'rows'`-level rejections (full list of failing IDs). */
+  get ids(): Record<string, unknown>[] | undefined;
+  /**
+   * 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(): string | undefined;
+  /**
+   * `'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(): (string | null)[] | undefined;
+}
+/**
+ * Wire-body shape for `ActionTargetError` responses (since 0.1.147): a
+ * query target the server refused — `code` says why.
+ */
+interface ActionTargetErrorBody extends ServerError {
+  name: "ActionTargetError";
+  code: "TARGET_INVALID" | "TARGET_TOO_LARGE" | "TARGET_CHANGED";
+  action: string;
+  /** `TARGET_CHANGED`: the current match count. */
+  matched?: number;
+  /** `TARGET_TOO_LARGE`: the most rows one request may target. */
+  cap?: number;
+}
+/**
+ * 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
+ */
+declare class ActionTargetError extends ClientError {
+  name: string;
+  get code(): ActionTargetErrorBody["code"];
+  get action(): string;
+  get matched(): number | undefined;
+  get cap(): number | undefined;
+}
+/**
+ * Wire-body shape for 409 OCC `version_mismatch` responses. Extends the base
+ * `ServerError` envelope with a `kind` discriminator and the row's current
+ * server-side version. The bridge between `@atscript/moost-db`'s server-side
+ * `_disambiguateMismatch` and this typed client-side subclass is the wire
+ * JSON body — neither package depends on the other.
+ */
+interface VersionMismatchErrorBody extends ServerError {
+  kind: "version_mismatch";
+  currentVersion: number;
+}
+/**
+ * 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.
+ */
+declare class VersionMismatchError extends ClientError {
+  name: string;
+  /** Row's current server-side version — clients refresh + retry against it. */
+  get currentVersion(): number;
+}
+/**
+ * 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`.
+ */
+declare class TransportError extends Error {
+  /** HTTP method of the failed request. */
+  readonly method: string;
+  /** Full request URL. */
+  readonly url: string;
+  name: string;
+  constructor(/** HTTP method of the failed request. */
+
+  method: string, /** Full request URL. */
+
+  url: string, /** What went wrong; the message is `<method> <url>: <detail>`. */
+
+  detail: string, cause?: unknown);
+  /**
+   * `true` when the request was cancelled — its `cause` is an `AbortError`
+   * (an aborted `signal`) or a `TimeoutError` (`AbortSignal.timeout`) —
+   * rather than a network failure. @since 0.1.165
+   */
+  get aborted(): boolean;
+}
+/** Thrown by `Client.action()` when the action name is not present in `/meta`. */
+declare class ActionNotFoundError extends Error {
+  readonly action: string;
+  name: string;
+  constructor(action: string);
+}
+/**
+ * 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.
+ */
+declare class ActionUnsupportedError extends Error {
+  readonly action: string;
+  readonly processor: string;
+  name: string;
+  constructor(action: string, processor: string, message: string);
+}
+//#endregion
 //#region src/validator.d.ts
 /** Options for {@link ClientValidator} / {@link createClientValidator}. */
 interface ClientValidatorOptions {
@@ -329,20 +556,6 @@ declare class ClientValidator {
   validate(data: unknown, mode: ValidatorMode): void;
   private _getValidator;
 }
-/**
- * Structured validation error thrown before HTTP requests when client-side
- * validation fails.
- */
-declare class ClientValidationError extends Error {
-  readonly errors: Array<{
-    path: string;
-    message: string;
-  }>;
-  constructor(errors: Array<{
-    path: string;
-    message: string;
-  }>);
-}
 /**
  * Create a {@link ClientValidator} from a meta response (or promise).
  *
@@ -355,4 +568,4 @@ declare class ClientValidationError extends Error {
  */
 declare function createClientValidator(meta: MetaResponse, opts?: ClientValidatorOptions): ClientValidator;
 //#endregion
-export { SearchIndexInfo as A, Uniquery$1 as B, MetaResponse as C, PatchOf as D, PageResult as E, TDbInsertManyResult$1 as F, MetaStoreOptions as G, ValidGroupBy$1 as H, TDbInsertResult$1 as I, clearMetaStore as K, TDbQueryTarget as L, TDbDeleteResult$1 as M, TDbInsertIgnoreResult$1 as N, RelationInfo as O, TDbInsertManyIgnoreResult$1 as P, TDbUpdateResult$1 as R, IdOf as S, OwnOf as T, WeekStart as U, UniqueryControls as V, MetaStore as W, DbRow as _, ValidatorMode$1 as a, FieldMeta as b, AggregateResult$1 as c, BucketUnit as d, CalendarBucketLabel as f, DbPatch as g, DataOf as h, DbValidationContext as i, ServerError as j, RowOf as k, AtscriptClientShape as l, ClientResponse as m, ClientValidator as n, createClientValidator as o, ClientOptions as p, defaultMetaStore as q, ClientValidatorOptions as r, AggregateQuery$1 as s, ClientValidationError as t, BucketExpr$1 as u, DecoratedControls as v, NavOf as w, FilterExpr as x, DecoratedQuery as y, TypedWithRelation as z };
+export { UniqueryControls as $, FieldMeta as A, RowOf as B, ClientOptions as C, DbRow as D, DbPatch as E, OwnOf as F, TDbInsertIgnoreResult$1 as G, ServerError as H, PageResult as I, TDbInsertResult$1 as J, TDbInsertManyIgnoreResult$1 as K, PatchOf as L, IdOf as M, MetaResponse as N, DecoratedControls as O, NavOf as P, Uniquery$1 as Q, RelationInfo as R, CalendarBucketLabel as S, DataOf as T, TClientCallOptions as U, SearchIndexInfo as V, TDbDeleteResult$1 as W, TDbUpdateResult$1 as X, TDbQueryTarget as Y, TypedWithRelation as Z, AggregateQuery$1 as _, createClientValidator as a, defaultMetaStore as at, BucketExpr$1 as b, ActionNotFoundError as c, ActionUnsupportedError as d, ValidGroupBy$1 as et, ClientError as f, VersionMismatchErrorBody as g, VersionMismatchError as h, ValidatorMode$1 as i, clearMetaStore as it, FilterExpr as j, DecoratedQuery as k, ActionTargetError as l, TransportError as m, ClientValidatorOptions as n, MetaStore as nt, ActionDisabledError as o, ClientValidationError as p, TDbInsertManyResult$1 as q, DbValidationContext as r, MetaStoreOptions as rt, ActionDisabledErrorBody as s, ClientValidator as t, WeekStart as tt, ActionTargetErrorBody as u, AggregateResult$1 as v, ClientResponse as w, BucketUnit as x, AtscriptClientShape as y, ResponseDataOf as z };

package/dist/validator.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_client_error = require("./client-error-C9Q5xCuW.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let _atscript_db_validator = require("@atscript/db/validator");
 //#region src/validator.ts
@@ -43,7 +44,7 @@ var ClientValidator = class {
 		if (item === null || typeof item !== "object" || Array.isArray(item)) return item;
 		if (item.$cas === void 0) return item;
 		const path = `${prefix}$cas`;
-		if (mode === "insert") throw new ClientValidationError([{
+		if (mode === "insert") throw new require_client_error.ClientValidationError([{
 			path,
 			message: "$cas is not allowed on insert"
 		}]);
@@ -51,7 +52,7 @@ var ClientValidator = class {
 		try {
 			(0, _atscript_db_validator.reconcileCas)(clone, this.versionColumn, "version");
 		} catch (e) {
-			if (e instanceof _atscript_db_validator.DbError) throw new ClientValidationError(e.errors.map((err) => ({
+			if (e instanceof _atscript_db_validator.DbError) throw new require_client_error.ClientValidationError(e.errors.map((err) => ({
 				path: `${prefix}${err.path}`,
 				message: err.message
 			})));
@@ -74,7 +75,7 @@ var ClientValidator = class {
 		};
 		for (let i = 0; i < items.length; i++) if (!validator.validate(items[i], true, ctx)) {
 			const prefix = isArray ? `[${i}]` : "";
-			throw new ClientValidationError(validator.errors.map((e) => ({
+			throw new require_client_error.ClientValidationError(validator.errors.map((e) => ({
 				path: prefix ? e.path ? `${prefix}.${e.path}` : prefix : e.path,
 				message: e.message
 			})));
@@ -90,19 +91,6 @@ var ClientValidator = class {
 	}
 };
 /**
-* Structured validation error thrown before HTTP requests when client-side
-* validation fails.
-*/
-var ClientValidationError = class extends Error {
-	errors;
-	constructor(errors) {
-		const msg = errors.length === 1 ? errors[0].message : `Validation failed with ${errors.length} errors`;
-		super(msg);
-		this.name = "ClientValidationError";
-		this.errors = errors;
-	}
-};
-/**
 * Create a {@link ClientValidator} from a meta response (or promise).
 *
 * @example
@@ -119,6 +107,6 @@ function createClientValidator(meta, opts) {
 	});
 }
 //#endregion
-exports.ClientValidationError = ClientValidationError;
+exports.ClientValidationError = require_client_error.ClientValidationError;
 exports.ClientValidator = ClientValidator;
 exports.createClientValidator = createClientValidator;

package/dist/validator.d.cts

@@ -1,2 +1,2 @@
-import { a as ValidatorMode, i as DbValidationContext, n as ClientValidator, o as createClientValidator, r as ClientValidatorOptions, t as ClientValidationError } from "./validator-CI8qxCps.cjs";
+import { a as createClientValidator, i as ValidatorMode, n as ClientValidatorOptions, p as ClientValidationError, r as DbValidationContext, t as ClientValidator } from "./validator-DrJYT-pz.cjs";
 export { ClientValidationError, ClientValidator, ClientValidatorOptions, type DbValidationContext, type ValidatorMode, createClientValidator };

package/dist/validator.d.mts

@@ -1,2 +1,2 @@
-import { a as ValidatorMode, i as DbValidationContext, n as ClientValidator, o as createClientValidator, r as ClientValidatorOptions, t as ClientValidationError } from "./validator-zwjB-484.mjs";
+import { a as createClientValidator, i as ValidatorMode, n as ClientValidatorOptions, p as ClientValidationError, r as DbValidationContext, t as ClientValidator } from "./validator-tvR4Sl3l.mjs";
 export { ClientValidationError, ClientValidator, ClientValidatorOptions, type DbValidationContext, type ValidatorMode, createClientValidator };

package/dist/validator.mjs

@@ -1,3 +1,4 @@
+import { o as ClientValidationError } from "./client-error-Dn4WeNft.mjs";
 import { deserializeAnnotatedType } from "@atscript/typescript/utils";
 import { DbError, buildDbValidator, buildValidationContext, reconcileCas } from "@atscript/db/validator";
 //#region src/validator.ts
@@ -89,19 +90,6 @@ var ClientValidator = class {
 	}
 };
 /**
-* Structured validation error thrown before HTTP requests when client-side
-* validation fails.
-*/
-var ClientValidationError = class extends Error {
-	errors;
-	constructor(errors) {
-		const msg = errors.length === 1 ? errors[0].message : `Validation failed with ${errors.length} errors`;
-		super(msg);
-		this.name = "ClientValidationError";
-		this.errors = errors;
-	}
-};
-/**
 * Create a {@link ClientValidator} from a meta response (or promise).
 *
 * @example

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-client",
-  "version": "0.1.164",
+  "version": "0.1.165",
   "description": "Browser-compatible HTTP client for @atscript/moost-db REST endpoints.",
   "keywords": [
     "atscript",
@@ -47,14 +47,14 @@
     "@uniqu/url": "^0.1.15"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.109",
-    "@atscript/typescript": "^0.1.109",
-    "unplugin-atscript": "^0.1.109",
-    "@atscript/db": "0.1.164"
+    "@atscript/core": "^0.2.1",
+    "@atscript/typescript": "^0.2.1",
+    "unplugin-atscript": "^0.2.1",
+    "@atscript/db": "0.1.165"
   },
   "peerDependencies": {
-    "@atscript/typescript": "^0.1.109",
-    "@atscript/db": "^0.1.164"
+    "@atscript/typescript": "^0.2.1",
+    "@atscript/db": "^0.1.165"
   },
   "scripts": {
     "build": "vp pack",