@atscript/db-client 0.1.127 → 0.1.129

package/dist/index.cjs

@@ -56,6 +56,24 @@ var VersionMismatchError = class extends ClientError {
 		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;
@@ -212,22 +230,26 @@ var Client = class {
 		return this._getOrNull(`one/${encodeURIComponent(String(id))}${controlStr ? `?${controlStr}` : ""}`);
 	}
 	async insert(data) {
-		await this._validateData(data, "insert");
-		return this._request("POST", "", data);
+		return this._request("POST", "", await this._prepareWrite(data, "insert"));
 	}
 	/**
 	* `PATCH /` — partial update one or many records by primary key.
+	*
+	* Accepts both OCC shapes (since 0.1.128): a bare `version: N` (the wire
+	* contract) or the SDK `$cas: { version: N }`, which is lifted to `version`
+	* before preflight and sending. A stale version surfaces as
+	* {@link VersionMismatchError}; a PK-only body with a version is a real
+	* write (the server bumps the version).
 	*/
 	async update(data) {
-		await this._validateData(data, "patch");
-		return this._request("PATCH", "", data);
+		return this._request("PATCH", "", await this._prepareWrite(data, "patch"));
 	}
 	/**
-	* `PUT /` — full replace one or many records by primary key.
+	* `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) {
-		await this._validateData(data, "replace");
-		return this._request("PUT", "", data);
+		return this._request("PUT", "", await this._prepareWrite(data, "replace"));
 	}
 	/**
 	* `DELETE /:id` or `DELETE /?k1=v1&k2=v2` — remove a record by primary key.
@@ -329,8 +351,12 @@ var Client = class {
 	getValidator() {
 		return this._getValidator();
 	}
-	async _validateData(data, mode) {
-		(await this._getValidator()).validate(data, mode);
+	/** Lifts `$cas` to the wire shape, then runs the preflight validator on the result. */
+	async _prepareWrite(data, mode) {
+		const validator = await this._getValidator();
+		const normalized = validator.liftCas(data, mode);
+		validator.validate(normalized, mode);
+		return normalized;
 	}
 	_getValidator() {
 		if (!this._validatorPromise) this._validatorPromise = Promise.all([this.meta(), Promise.resolve().then(() => require("./validator.cjs"))]).then(([m, { createClientValidator }]) => createClientValidator(m, { lenientWrites: this._lenientWrites })).catch((err) => {
@@ -422,14 +448,20 @@ var Client = class {
 		return init;
 	}
 	async _send(url, init, allowEmpty) {
-		const res = await this._fetch(url, init);
+		const method = init.method ?? "GET";
+		let res;
+		try {
+			res = await this._fetch(url, init);
+		} catch (cause) {
+			throw new TransportError(method, url, describeCause(cause), cause);
+		}
 		if (!res.ok) {
 			let errorBody;
 			try {
 				errorBody = await res.json();
 			} catch {
 				errorBody = {
-					message: res.statusText,
+					message: res.statusText || `HTTP ${res.status}`,
 					statusCode: res.status
 				};
 			}
@@ -437,7 +469,11 @@ var Client = class {
 			if (errorBody.kind === "version_mismatch") throw new VersionMismatchError(res.status, errorBody);
 			throw new ClientError(res.status, errorBody);
 		}
-		if (!allowEmpty) return res.json();
+		if (!allowEmpty) try {
+			return await res.json();
+		} catch (cause) {
+			throw new 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 {
 			return await res.json();
@@ -446,6 +482,11 @@ var Client = class {
 		}
 	}
 };
+/** One-line rendering of a thrown value for a `TransportError` message. */
+function describeCause(cause) {
+	if (cause instanceof Error) return cause.message || cause.name;
+	return String(cause);
+}
 /**
 * Render a single identifier field for substitution into a navigate-URL
 * template or human-readable string. `null` / `undefined` collapse to `""`
@@ -487,6 +528,7 @@ exports.ActionNotFoundError = ActionNotFoundError;
 exports.ActionUnsupportedError = ActionUnsupportedError;
 exports.Client = Client;
 exports.ClientError = ClientError;
+exports.TransportError = TransportError;
 exports.VersionMismatchError = VersionMismatchError;
 exports.encodeNavigateId = encodeNavigateId;
 exports.formatIdentifier = formatIdentifier;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { C as TDbDeleteResult, D as TypedWithRelation, E as TDbUpdateResult, O as Uniquery, S as ServerError, T as TDbInsertResult, _ as NavOf, a as ValidatorMode, b as RelationInfo, c as AggregateResult, d as ClientResponse, f as DataOf, g as MetaResponse, h as IdOf, k as UniqueryControls, l as AtscriptClientShape, m as FilterExpr, n as ClientValidator, p as FieldMeta, r as ClientValidatorOptions, s as AggregateQuery, t as ClientValidationError, u as ClientOptions, v as OwnOf, w as TDbInsertManyResult, x as SearchIndexInfo, y as PageResult } from "./validator-3I12BVi4.cjs";
+import { A as TDbUpdateResult, C as RelationInfo, D as TDbDeleteResult, E as ServerError, M as Uniquery, N as UniqueryControls, O as TDbInsertManyResult, S as PatchOf, T as SearchIndexInfo, _ as IdOf, a as ValidatorMode, b as OwnOf, c as AggregateResult, d as ClientResponse, f as DataOf, g as FilterExpr, h as FieldMeta, j as TypedWithRelation, k as TDbInsertResult, l as AtscriptClientShape, m as DbRow, n as ClientValidator, p as DbPatch, r as ClientValidatorOptions, s as AggregateQuery, t as ClientValidationError, u as ClientOptions, v as MetaResponse, w as RowOf, x as PageResult, y as NavOf } from "./validator-C3uaaZkU.cjs";
 import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1 } from "@uniqu/core";
 import { TAtscriptAnnotatedType, TSerializedAnnotatedType } from "@atscript/typescript/utils";
 import { TCrudOp, TCrudPermissions, TDbActionInfo, TDbActionIntent, TDbActionLevel, TDbActionProcessor, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1 } from "@atscript/db";
@@ -6,7 +6,6 @@ import { TCrudOp, TCrudPermissions, TDbActionInfo, TDbActionIntent, TDbActionLev
 //#region src/client.d.ts
 type Own<T> = OwnOf<T>;
 type Nav<T> = NavOf<T>;
-type Data<T> = DataOf<T>;
 type Id<T> = IdOf<T>;
 type Response<T, Q> = ClientResponse<T, Q>;
 /**
@@ -99,21 +98,29 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
     controls?: UniqueryControls$1<Own<T>, Nav<T>>;
   }>(id: Id<T>, query?: Q): Promise<Response<T, Q> | null>;
   /**
-   * `POST /` — insert one record.
+   * `POST /` — insert one record. The version column (if any) is optional —
+   * the server initialises it; `$cas` is rejected (no meaning on insert).
    */
-  insert(data: Partial<Data<T>>): Promise<TDbInsertResult$1>;
+  insert(data: PatchOf<T>): Promise<TDbInsertResult$1>;
   /**
    * `POST /` — insert many records.
    */
-  insert(data: Partial<Data<T>>[]): Promise<TDbInsertManyResult$1>;
+  insert(data: PatchOf<T>[]): Promise<TDbInsertManyResult$1>;
   /**
    * `PATCH /` — partial update one or many records by primary key.
+   *
+   * Accepts both OCC shapes (since 0.1.128): a bare `version: N` (the wire
+   * contract) or the SDK `$cas: { version: N }`, which is lifted to `version`
+   * before preflight and sending. A stale version surfaces as
+   * {@link VersionMismatchError}; a PK-only body with a version is a real
+   * write (the server bumps the version).
    */
-  update(data: Partial<Data<T>> | Partial<Data<T>>[]): Promise<TDbUpdateResult$1>;
+  update(data: PatchOf<T> | PatchOf<T>[]): Promise<TDbUpdateResult$1>;
   /**
-   * `PUT /` — full replace one or many records by primary key.
+   * `PUT /` — full replace one or many records by primary key. Same OCC
+   * shapes as {@link update}; the version column itself is optional.
    */
-  replace(data: Data<T> | Data<T>[]): Promise<TDbUpdateResult$1>;
+  replace(data: RowOf<T> | RowOf<T>[]): Promise<TDbUpdateResult$1>;
   /**
    * `DELETE /:id` or `DELETE /?k1=v1&k2=v2` — remove a record by primary key.
    */
@@ -177,7 +184,8 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    * Useful for accessing `flatMap` and `navFields` (e.g. for form generation).
    */
   getValidator(): Promise<ClientValidator>;
-  private _validateData;
+  /** Lifts `$cas` to the wire shape, then runs the preflight validator on the result. */
+  private _prepareWrite;
   private _getValidator;
   private _buildActionBody;
   private _interpolateNavigateUrl;
@@ -287,6 +295,28 @@ declare class VersionMismatchError extends ClientError {
   /** 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);
+}
 /** Thrown by `Client.action()` when the action name is not present in `/meta`. */
 declare class ActionNotFoundError extends Error {
   readonly action: string;
@@ -306,4 +336,4 @@ declare class ActionUnsupportedError extends Error {
   constructor(action: string, processor: string, message: string);
 }
 //#endregion
-export { ActionDisabledError, type ActionDisabledErrorBody, ActionNotFoundError, ActionUnsupportedError, type AggregateQuery, type AggregateResult, type AtscriptClientShape, Client, ClientError, type ClientOptions, type ClientResponse, type ClientValidationError, type ClientValidator, type ClientValidatorOptions, type DataOf, type FieldMeta, type FilterExpr, type IdOf, type MetaResponse, type NavOf, type OwnOf, type PageResult, type RelationInfo, type SearchIndexInfo, type ServerError, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbDeleteResult, type TDbInsertManyResult, type TDbInsertResult, type TDbUpdateResult, type TSerializedAnnotatedType, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidatorMode, VersionMismatchError, type VersionMismatchErrorBody, encodeNavigateId, formatIdentifier, formatIdentifierField };
+export { ActionDisabledError, type ActionDisabledErrorBody, ActionNotFoundError, ActionUnsupportedError, type AggregateQuery, type AggregateResult, type AtscriptClientShape, Client, ClientError, type ClientOptions, type ClientResponse, type ClientValidationError, type ClientValidator, type ClientValidatorOptions, type DataOf, type DbPatch, type DbRow, type FieldMeta, type FilterExpr, type IdOf, type MetaResponse, type NavOf, type OwnOf, type PageResult, type PatchOf, type RelationInfo, type RowOf, type SearchIndexInfo, type ServerError, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbDeleteResult, type TDbInsertManyResult, type TDbInsertResult, type TDbUpdateResult, type TSerializedAnnotatedType, TransportError, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidatorMode, VersionMismatchError, type VersionMismatchErrorBody, encodeNavigateId, formatIdentifier, formatIdentifierField };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { C as TDbDeleteResult, D as TypedWithRelation, E as TDbUpdateResult, O as Uniquery, S as ServerError, T as TDbInsertResult, _ as NavOf, a as ValidatorMode, b as RelationInfo, c as AggregateResult, d as ClientResponse, f as DataOf, g as MetaResponse, h as IdOf, k as UniqueryControls, l as AtscriptClientShape, m as FilterExpr, n as ClientValidator, p as FieldMeta, r as ClientValidatorOptions, s as AggregateQuery, t as ClientValidationError, u as ClientOptions, v as OwnOf, w as TDbInsertManyResult, x as SearchIndexInfo, y as PageResult } from "./validator-DBEmk_s8.mjs";
+import { A as TDbUpdateResult, C as RelationInfo, D as TDbDeleteResult, E as ServerError, M as Uniquery, N as UniqueryControls, O as TDbInsertManyResult, S as PatchOf, T as SearchIndexInfo, _ as IdOf, a as ValidatorMode, b as OwnOf, c as AggregateResult, d as ClientResponse, f as DataOf, g as FilterExpr, h as FieldMeta, j as TypedWithRelation, k as TDbInsertResult, l as AtscriptClientShape, m as DbRow, n as ClientValidator, p as DbPatch, r as ClientValidatorOptions, s as AggregateQuery, t as ClientValidationError, u as ClientOptions, v as MetaResponse, w as RowOf, x as PageResult, y as NavOf } from "./validator-CfPFKDL_.mjs";
 import { TAtscriptAnnotatedType, TSerializedAnnotatedType } from "@atscript/typescript/utils";
 import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1 } from "@uniqu/core";
 import { TCrudOp, TCrudPermissions, TDbActionInfo, TDbActionIntent, TDbActionLevel, TDbActionProcessor, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1 } from "@atscript/db";
@@ -6,7 +6,6 @@ import { TCrudOp, TCrudPermissions, TDbActionInfo, TDbActionIntent, TDbActionLev
 //#region src/client.d.ts
 type Own<T> = OwnOf<T>;
 type Nav<T> = NavOf<T>;
-type Data<T> = DataOf<T>;
 type Id<T> = IdOf<T>;
 type Response<T, Q> = ClientResponse<T, Q>;
 /**
@@ -99,21 +98,29 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
     controls?: UniqueryControls$1<Own<T>, Nav<T>>;
   }>(id: Id<T>, query?: Q): Promise<Response<T, Q> | null>;
   /**
-   * `POST /` — insert one record.
+   * `POST /` — insert one record. The version column (if any) is optional —
+   * the server initialises it; `$cas` is rejected (no meaning on insert).
    */
-  insert(data: Partial<Data<T>>): Promise<TDbInsertResult$1>;
+  insert(data: PatchOf<T>): Promise<TDbInsertResult$1>;
   /**
    * `POST /` — insert many records.
    */
-  insert(data: Partial<Data<T>>[]): Promise<TDbInsertManyResult$1>;
+  insert(data: PatchOf<T>[]): Promise<TDbInsertManyResult$1>;
   /**
    * `PATCH /` — partial update one or many records by primary key.
+   *
+   * Accepts both OCC shapes (since 0.1.128): a bare `version: N` (the wire
+   * contract) or the SDK `$cas: { version: N }`, which is lifted to `version`
+   * before preflight and sending. A stale version surfaces as
+   * {@link VersionMismatchError}; a PK-only body with a version is a real
+   * write (the server bumps the version).
    */
-  update(data: Partial<Data<T>> | Partial<Data<T>>[]): Promise<TDbUpdateResult$1>;
+  update(data: PatchOf<T> | PatchOf<T>[]): Promise<TDbUpdateResult$1>;
   /**
-   * `PUT /` — full replace one or many records by primary key.
+   * `PUT /` — full replace one or many records by primary key. Same OCC
+   * shapes as {@link update}; the version column itself is optional.
    */
-  replace(data: Data<T> | Data<T>[]): Promise<TDbUpdateResult$1>;
+  replace(data: RowOf<T> | RowOf<T>[]): Promise<TDbUpdateResult$1>;
   /**
    * `DELETE /:id` or `DELETE /?k1=v1&k2=v2` — remove a record by primary key.
    */
@@ -177,7 +184,8 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    * Useful for accessing `flatMap` and `navFields` (e.g. for form generation).
    */
   getValidator(): Promise<ClientValidator>;
-  private _validateData;
+  /** Lifts `$cas` to the wire shape, then runs the preflight validator on the result. */
+  private _prepareWrite;
   private _getValidator;
   private _buildActionBody;
   private _interpolateNavigateUrl;
@@ -287,6 +295,28 @@ declare class VersionMismatchError extends ClientError {
   /** 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);
+}
 /** Thrown by `Client.action()` when the action name is not present in `/meta`. */
 declare class ActionNotFoundError extends Error {
   readonly action: string;
@@ -306,4 +336,4 @@ declare class ActionUnsupportedError extends Error {
   constructor(action: string, processor: string, message: string);
 }
 //#endregion
-export { ActionDisabledError, type ActionDisabledErrorBody, ActionNotFoundError, ActionUnsupportedError, type AggregateQuery, type AggregateResult, type AtscriptClientShape, Client, ClientError, type ClientOptions, type ClientResponse, type ClientValidationError, type ClientValidator, type ClientValidatorOptions, type DataOf, type FieldMeta, type FilterExpr, type IdOf, type MetaResponse, type NavOf, type OwnOf, type PageResult, type RelationInfo, type SearchIndexInfo, type ServerError, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbDeleteResult, type TDbInsertManyResult, type TDbInsertResult, type TDbUpdateResult, type TSerializedAnnotatedType, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidatorMode, VersionMismatchError, type VersionMismatchErrorBody, encodeNavigateId, formatIdentifier, formatIdentifierField };
+export { ActionDisabledError, type ActionDisabledErrorBody, ActionNotFoundError, ActionUnsupportedError, type AggregateQuery, type AggregateResult, type AtscriptClientShape, Client, ClientError, type ClientOptions, type ClientResponse, type ClientValidationError, type ClientValidator, type ClientValidatorOptions, type DataOf, type DbPatch, type DbRow, type FieldMeta, type FilterExpr, type IdOf, type MetaResponse, type NavOf, type OwnOf, type PageResult, type PatchOf, type RelationInfo, type RowOf, type SearchIndexInfo, type ServerError, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbDeleteResult, type TDbInsertManyResult, type TDbInsertResult, type TDbUpdateResult, type TSerializedAnnotatedType, TransportError, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidatorMode, VersionMismatchError, type VersionMismatchErrorBody, encodeNavigateId, formatIdentifier, formatIdentifierField };

package/dist/index.mjs

@@ -55,6 +55,24 @@ var VersionMismatchError = class extends ClientError {
 		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;
@@ -211,22 +229,26 @@ var Client = class {
 		return this._getOrNull(`one/${encodeURIComponent(String(id))}${controlStr ? `?${controlStr}` : ""}`);
 	}
 	async insert(data) {
-		await this._validateData(data, "insert");
-		return this._request("POST", "", data);
+		return this._request("POST", "", await this._prepareWrite(data, "insert"));
 	}
 	/**
 	* `PATCH /` — partial update one or many records by primary key.
+	*
+	* Accepts both OCC shapes (since 0.1.128): a bare `version: N` (the wire
+	* contract) or the SDK `$cas: { version: N }`, which is lifted to `version`
+	* before preflight and sending. A stale version surfaces as
+	* {@link VersionMismatchError}; a PK-only body with a version is a real
+	* write (the server bumps the version).
 	*/
 	async update(data) {
-		await this._validateData(data, "patch");
-		return this._request("PATCH", "", data);
+		return this._request("PATCH", "", await this._prepareWrite(data, "patch"));
 	}
 	/**
-	* `PUT /` — full replace one or many records by primary key.
+	* `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) {
-		await this._validateData(data, "replace");
-		return this._request("PUT", "", data);
+		return this._request("PUT", "", await this._prepareWrite(data, "replace"));
 	}
 	/**
 	* `DELETE /:id` or `DELETE /?k1=v1&k2=v2` — remove a record by primary key.
@@ -328,8 +350,12 @@ var Client = class {
 	getValidator() {
 		return this._getValidator();
 	}
-	async _validateData(data, mode) {
-		(await this._getValidator()).validate(data, mode);
+	/** Lifts `$cas` to the wire shape, then runs the preflight validator on the result. */
+	async _prepareWrite(data, mode) {
+		const validator = await this._getValidator();
+		const normalized = validator.liftCas(data, mode);
+		validator.validate(normalized, mode);
+		return normalized;
 	}
 	_getValidator() {
 		if (!this._validatorPromise) this._validatorPromise = Promise.all([this.meta(), import("./validator.mjs")]).then(([m, { createClientValidator }]) => createClientValidator(m, { lenientWrites: this._lenientWrites })).catch((err) => {
@@ -421,14 +447,20 @@ var Client = class {
 		return init;
 	}
 	async _send(url, init, allowEmpty) {
-		const res = await this._fetch(url, init);
+		const method = init.method ?? "GET";
+		let res;
+		try {
+			res = await this._fetch(url, init);
+		} catch (cause) {
+			throw new TransportError(method, url, describeCause(cause), cause);
+		}
 		if (!res.ok) {
 			let errorBody;
 			try {
 				errorBody = await res.json();
 			} catch {
 				errorBody = {
-					message: res.statusText,
+					message: res.statusText || `HTTP ${res.status}`,
 					statusCode: res.status
 				};
 			}
@@ -436,7 +468,11 @@ var Client = class {
 			if (errorBody.kind === "version_mismatch") throw new VersionMismatchError(res.status, errorBody);
 			throw new ClientError(res.status, errorBody);
 		}
-		if (!allowEmpty) return res.json();
+		if (!allowEmpty) try {
+			return await res.json();
+		} catch (cause) {
+			throw new 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 {
 			return await res.json();
@@ -445,6 +481,11 @@ var Client = class {
 		}
 	}
 };
+/** One-line rendering of a thrown value for a `TransportError` message. */
+function describeCause(cause) {
+	if (cause instanceof Error) return cause.message || cause.name;
+	return String(cause);
+}
 /**
 * Render a single identifier field for substitution into a navigate-URL
 * template or human-readable string. `null` / `undefined` collapse to `""`
@@ -481,4 +522,4 @@ function describeShape(value) {
 	return typeof value;
 }
 //#endregion
-export { ActionDisabledError, ActionNotFoundError, ActionUnsupportedError, Client, ClientError, VersionMismatchError, encodeNavigateId, formatIdentifier, formatIdentifierField };
+export { ActionDisabledError, ActionNotFoundError, ActionUnsupportedError, Client, ClientError, TransportError, VersionMismatchError, encodeNavigateId, formatIdentifier, formatIdentifierField };

package/dist/{validator-3I12BVi4.d.cts → validator-C3uaaZkU.d.cts}

@@ -1,9 +1,17 @@
 import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, FilterExpr, TypedWithRelation, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1 } from "@uniqu/core";
 import { TAtscriptAnnotatedType, TAtscriptTypeObject } from "@atscript/typescript/utils";
-import { DbResponse, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1, TFieldMeta, TMetaResponse, TRelationInfo, TSearchIndexInfo } from "@atscript/db";
+import { DbPatch, DbResponse, DbRow, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1, TFieldMeta, TMetaResponse, TRelationInfo, TSearchIndexInfo } from "@atscript/db";
 import { DbValidationContext, ValidatorMode, ValidatorMode as ValidatorMode$1 } from "@atscript/db/validator";
 
 //#region src/types.d.ts
+/**
+ * Write payload for `insert()` / `update()`: every key optional, optional
+ * columns additionally accept `null` (explicit NULL). `$cas` is accepted on
+ * `update()` / `replace()` through the open index signature.
+ */
+type PatchOf<T> = DbPatch<DataOf<T>>;
+/** Write payload for `replace()`: full row; optional columns additionally accept `null`. */
+type RowOf<T> = DbRow<DataOf<T>>;
 /** Options for creating a Client instance. */
 interface ClientOptions {
   /**
@@ -120,6 +128,12 @@ type ClientResponse<T, Q> = DbResponse<DataOf<T>, NavOf<T>, Q> & {
 //#region src/validator.d.ts
 /** Options for {@link ClientValidator} / {@link createClientValidator}. */
 interface ClientValidatorOptions {
+  /**
+   * The table's `@db.column.version` column (from `/meta`'s `versionColumn`).
+   * Enables the `$cas` lift in {@link ClientValidator.liftCas}; without it a
+   * `$cas` payload is rejected (the table is not versioned).
+   */
+  versionColumn?: string;
   /**
    * Tolerate unknown properties in write payloads. Enable when the served
    * `/meta` type is a PROJECTION of the full server-side type (e.g. an ARBAC
@@ -144,7 +158,21 @@ declare class ClientValidator {
   readonly flatMap: Map<string, TAtscriptAnnotatedType>;
   /** Set of field paths that are navigation relations (TO/FROM/VIA). */
   readonly navFields: ReadonlySet<string>;
+  /** The table's version column when it opts into OCC (from `/meta`). */
+  readonly versionColumn?: string;
   constructor(type: TAtscriptAnnotatedType<TAtscriptTypeObject>, opts?: ClientValidatorOptions);
+  /**
+   * Normalises the SDK `$cas` shape to the wire shape (since 0.1.128):
+   * `{ id, $cas: { version: 4 } }` → `{ id, version: 4 }` (the server lifts
+   * `version` back to `$cas`). Returns a shallow clone per item; items
+   * without `$cas` (a `$cas: undefined` counts as absent) are returned
+   * as-is. Throws `ClientValidationError` when the table is not versioned,
+   * the `$cas` shape is invalid, or `version` and `$cas` disagree — the same
+   * messages the server produces, from the shared `reconcileCas` — or when
+   * `$cas` appears on an insert.
+   */
+  liftCas(data: unknown, mode: ValidatorMode): unknown;
+  private _liftCasItem;
   /**
    * Validate data for a given write mode.
    * Throws `ClientValidationError` if validation fails.
@@ -178,4 +206,4 @@ declare class ClientValidationError extends Error {
  */
 declare function createClientValidator(meta: MetaResponse, opts?: ClientValidatorOptions): ClientValidator;
 //#endregion
-export { TDbDeleteResult$1 as C, TypedWithRelation as D, TDbUpdateResult$1 as E, Uniquery$1 as O, ServerError as S, TDbInsertResult$1 as T, NavOf as _, ValidatorMode$1 as a, RelationInfo as b, AggregateResult$1 as c, ClientResponse as d, DataOf as f, MetaResponse as g, IdOf as h, DbValidationContext as i, UniqueryControls$1 as k, AtscriptClientShape as l, FilterExpr as m, ClientValidator as n, createClientValidator as o, FieldMeta as p, ClientValidatorOptions as r, AggregateQuery$1 as s, ClientValidationError as t, ClientOptions as u, OwnOf as v, TDbInsertManyResult$1 as w, SearchIndexInfo as x, PageResult as y };
+export { TDbUpdateResult$1 as A, RelationInfo as C, TDbDeleteResult$1 as D, ServerError as E, Uniquery$1 as M, UniqueryControls$1 as N, TDbInsertManyResult$1 as O, PatchOf as S, SearchIndexInfo as T, IdOf as _, ValidatorMode$1 as a, OwnOf as b, AggregateResult$1 as c, ClientResponse as d, DataOf as f, FilterExpr as g, FieldMeta as h, DbValidationContext as i, TypedWithRelation as j, TDbInsertResult$1 as k, AtscriptClientShape as l, DbRow as m, ClientValidator as n, createClientValidator as o, DbPatch as p, ClientValidatorOptions as r, AggregateQuery$1 as s, ClientValidationError as t, ClientOptions as u, MetaResponse as v, RowOf as w, PageResult as x, NavOf as y };

package/dist/{validator-DBEmk_s8.d.mts → validator-CfPFKDL_.d.mts}

@@ -1,9 +1,17 @@
 import { TAtscriptAnnotatedType, TAtscriptTypeObject } from "@atscript/typescript/utils";
 import { DbValidationContext, ValidatorMode, ValidatorMode as ValidatorMode$1 } from "@atscript/db/validator";
 import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, FilterExpr, TypedWithRelation, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1 } from "@uniqu/core";
-import { DbResponse, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1, TFieldMeta, TMetaResponse, TRelationInfo, TSearchIndexInfo } from "@atscript/db";
+import { DbPatch, DbResponse, DbRow, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1, TFieldMeta, TMetaResponse, TRelationInfo, TSearchIndexInfo } from "@atscript/db";
 
 //#region src/types.d.ts
+/**
+ * Write payload for `insert()` / `update()`: every key optional, optional
+ * columns additionally accept `null` (explicit NULL). `$cas` is accepted on
+ * `update()` / `replace()` through the open index signature.
+ */
+type PatchOf<T> = DbPatch<DataOf<T>>;
+/** Write payload for `replace()`: full row; optional columns additionally accept `null`. */
+type RowOf<T> = DbRow<DataOf<T>>;
 /** Options for creating a Client instance. */
 interface ClientOptions {
   /**
@@ -120,6 +128,12 @@ type ClientResponse<T, Q> = DbResponse<DataOf<T>, NavOf<T>, Q> & {
 //#region src/validator.d.ts
 /** Options for {@link ClientValidator} / {@link createClientValidator}. */
 interface ClientValidatorOptions {
+  /**
+   * The table's `@db.column.version` column (from `/meta`'s `versionColumn`).
+   * Enables the `$cas` lift in {@link ClientValidator.liftCas}; without it a
+   * `$cas` payload is rejected (the table is not versioned).
+   */
+  versionColumn?: string;
   /**
    * Tolerate unknown properties in write payloads. Enable when the served
    * `/meta` type is a PROJECTION of the full server-side type (e.g. an ARBAC
@@ -144,7 +158,21 @@ declare class ClientValidator {
   readonly flatMap: Map<string, TAtscriptAnnotatedType>;
   /** Set of field paths that are navigation relations (TO/FROM/VIA). */
   readonly navFields: ReadonlySet<string>;
+  /** The table's version column when it opts into OCC (from `/meta`). */
+  readonly versionColumn?: string;
   constructor(type: TAtscriptAnnotatedType<TAtscriptTypeObject>, opts?: ClientValidatorOptions);
+  /**
+   * Normalises the SDK `$cas` shape to the wire shape (since 0.1.128):
+   * `{ id, $cas: { version: 4 } }` → `{ id, version: 4 }` (the server lifts
+   * `version` back to `$cas`). Returns a shallow clone per item; items
+   * without `$cas` (a `$cas: undefined` counts as absent) are returned
+   * as-is. Throws `ClientValidationError` when the table is not versioned,
+   * the `$cas` shape is invalid, or `version` and `$cas` disagree — the same
+   * messages the server produces, from the shared `reconcileCas` — or when
+   * `$cas` appears on an insert.
+   */
+  liftCas(data: unknown, mode: ValidatorMode): unknown;
+  private _liftCasItem;
   /**
    * Validate data for a given write mode.
    * Throws `ClientValidationError` if validation fails.
@@ -178,4 +206,4 @@ declare class ClientValidationError extends Error {
  */
 declare function createClientValidator(meta: MetaResponse, opts?: ClientValidatorOptions): ClientValidator;
 //#endregion
-export { TDbDeleteResult$1 as C, TypedWithRelation as D, TDbUpdateResult$1 as E, Uniquery$1 as O, ServerError as S, TDbInsertResult$1 as T, NavOf as _, ValidatorMode$1 as a, RelationInfo as b, AggregateResult$1 as c, ClientResponse as d, DataOf as f, MetaResponse as g, IdOf as h, DbValidationContext as i, UniqueryControls$1 as k, AtscriptClientShape as l, FilterExpr as m, ClientValidator as n, createClientValidator as o, FieldMeta as p, ClientValidatorOptions as r, AggregateQuery$1 as s, ClientValidationError as t, ClientOptions as u, OwnOf as v, TDbInsertManyResult$1 as w, SearchIndexInfo as x, PageResult as y };
+export { TDbUpdateResult$1 as A, RelationInfo as C, TDbDeleteResult$1 as D, ServerError as E, Uniquery$1 as M, UniqueryControls$1 as N, TDbInsertManyResult$1 as O, PatchOf as S, SearchIndexInfo as T, IdOf as _, ValidatorMode$1 as a, OwnOf as b, AggregateResult$1 as c, ClientResponse as d, DataOf as f, FilterExpr as g, FieldMeta as h, DbValidationContext as i, TypedWithRelation as j, TDbInsertResult$1 as k, AtscriptClientShape as l, DbRow as m, ClientValidator as n, createClientValidator as o, DbPatch as p, ClientValidatorOptions as r, AggregateQuery$1 as s, ClientValidationError as t, ClientOptions as u, MetaResponse as v, RowOf as w, PageResult as x, NavOf as y };

package/dist/validator.cjs

@@ -15,14 +15,51 @@ var ClientValidator = class {
 	flatMap;
 	/** Set of field paths that are navigation relations (TO/FROM/VIA). */
 	navFields;
+	/** The table's version column when it opts into OCC (from `/meta`). */
+	versionColumn;
 	constructor(type, opts) {
 		this._type = type;
 		this._lenientWrites = opts?.lenientWrites === true;
+		this.versionColumn = opts?.versionColumn;
 		const ctx = (0, _atscript_db_validator.buildValidationContext)(type);
 		this.flatMap = ctx.flatMap;
 		this.navFields = ctx.navFields;
 	}
 	/**
+	* Normalises the SDK `$cas` shape to the wire shape (since 0.1.128):
+	* `{ id, $cas: { version: 4 } }` → `{ id, version: 4 }` (the server lifts
+	* `version` back to `$cas`). Returns a shallow clone per item; items
+	* without `$cas` (a `$cas: undefined` counts as absent) are returned
+	* as-is. Throws `ClientValidationError` when the table is not versioned,
+	* the `$cas` shape is invalid, or `version` and `$cas` disagree — the same
+	* messages the server produces, from the shared `reconcileCas` — or when
+	* `$cas` appears on an insert.
+	*/
+	liftCas(data, mode) {
+		if (Array.isArray(data)) return data.map((item, i) => this._liftCasItem(item, mode, `[${i}].`));
+		return this._liftCasItem(data, mode, "");
+	}
+	_liftCasItem(item, mode, prefix) {
+		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([{
+			path,
+			message: "$cas is not allowed on insert"
+		}]);
+		const clone = { ...item };
+		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) => ({
+				path: `${prefix}${err.path}`,
+				message: err.message
+			})));
+			throw e;
+		}
+		return clone;
+	}
+	/**
 	* Validate data for a given write mode.
 	* Throws `ClientValidationError` if validation fails.
 	*/
@@ -76,7 +113,10 @@ var ClientValidationError = class extends Error {
 * ```
 */
 function createClientValidator(meta, opts) {
-	return new ClientValidator((0, _atscript_typescript_utils.deserializeAnnotatedType)(meta.type), opts);
+	return new ClientValidator((0, _atscript_typescript_utils.deserializeAnnotatedType)(meta.type), {
+		versionColumn: meta.versionColumn,
+		...opts
+	});
 }
 //#endregion
 exports.ClientValidationError = ClientValidationError;

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-3I12BVi4.cjs";
+import { a as ValidatorMode, i as DbValidationContext, n as ClientValidator, o as createClientValidator, r as ClientValidatorOptions, t as ClientValidationError } from "./validator-C3uaaZkU.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-DBEmk_s8.mjs";
+import { a as ValidatorMode, i as DbValidationContext, n as ClientValidator, o as createClientValidator, r as ClientValidatorOptions, t as ClientValidationError } from "./validator-CfPFKDL_.mjs";
 export { ClientValidationError, ClientValidator, ClientValidatorOptions, type DbValidationContext, type ValidatorMode, createClientValidator };

package/dist/validator.mjs

@@ -1,5 +1,5 @@
 import { deserializeAnnotatedType } from "@atscript/typescript/utils";
-import { buildDbValidator, buildValidationContext } from "@atscript/db/validator";
+import { DbError, buildDbValidator, buildValidationContext, reconcileCas } from "@atscript/db/validator";
 //#region src/validator.ts
 /**
 * Client-side validator backed by an Atscript type from the `/meta` endpoint.
@@ -14,14 +14,51 @@ var ClientValidator = class {
 	flatMap;
 	/** Set of field paths that are navigation relations (TO/FROM/VIA). */
 	navFields;
+	/** The table's version column when it opts into OCC (from `/meta`). */
+	versionColumn;
 	constructor(type, opts) {
 		this._type = type;
 		this._lenientWrites = opts?.lenientWrites === true;
+		this.versionColumn = opts?.versionColumn;
 		const ctx = buildValidationContext(type);
 		this.flatMap = ctx.flatMap;
 		this.navFields = ctx.navFields;
 	}
 	/**
+	* Normalises the SDK `$cas` shape to the wire shape (since 0.1.128):
+	* `{ id, $cas: { version: 4 } }` → `{ id, version: 4 }` (the server lifts
+	* `version` back to `$cas`). Returns a shallow clone per item; items
+	* without `$cas` (a `$cas: undefined` counts as absent) are returned
+	* as-is. Throws `ClientValidationError` when the table is not versioned,
+	* the `$cas` shape is invalid, or `version` and `$cas` disagree — the same
+	* messages the server produces, from the shared `reconcileCas` — or when
+	* `$cas` appears on an insert.
+	*/
+	liftCas(data, mode) {
+		if (Array.isArray(data)) return data.map((item, i) => this._liftCasItem(item, mode, `[${i}].`));
+		return this._liftCasItem(data, mode, "");
+	}
+	_liftCasItem(item, mode, prefix) {
+		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([{
+			path,
+			message: "$cas is not allowed on insert"
+		}]);
+		const clone = { ...item };
+		try {
+			reconcileCas(clone, this.versionColumn, "version");
+		} catch (e) {
+			if (e instanceof DbError) throw new ClientValidationError(e.errors.map((err) => ({
+				path: `${prefix}${err.path}`,
+				message: err.message
+			})));
+			throw e;
+		}
+		return clone;
+	}
+	/**
 	* Validate data for a given write mode.
 	* Throws `ClientValidationError` if validation fails.
 	*/
@@ -75,7 +112,10 @@ var ClientValidationError = class extends Error {
 * ```
 */
 function createClientValidator(meta, opts) {
-	return new ClientValidator(deserializeAnnotatedType(meta.type), opts);
+	return new ClientValidator(deserializeAnnotatedType(meta.type), {
+		versionColumn: meta.versionColumn,
+		...opts
+	});
 }
 //#endregion
 export { ClientValidationError, ClientValidator, createClientValidator };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-client",
-  "version": "0.1.127",
+  "version": "0.1.129",
   "description": "Browser-compatible HTTP client for @atscript/moost-db REST endpoints.",
   "keywords": [
     "atscript",
@@ -43,18 +43,18 @@
     "access": "public"
   },
   "dependencies": {
-    "@uniqu/url": "^0.1.7"
+    "@uniqu/url": "^0.1.8"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.89",
-    "@atscript/typescript": "^0.1.89",
-    "@uniqu/core": "^0.1.7",
-    "unplugin-atscript": "^0.1.89",
-    "@atscript/db": "0.1.127"
+    "@atscript/core": "^0.1.92",
+    "@atscript/typescript": "^0.1.92",
+    "@uniqu/core": "^0.1.8",
+    "unplugin-atscript": "^0.1.92",
+    "@atscript/db": "0.1.129"
   },
   "peerDependencies": {
     "@atscript/db": "^0.1.44",
-    "@atscript/typescript": "^0.1.89"
+    "@atscript/typescript": "^0.1.92"
   },
   "scripts": {
     "postinstall": "asc -f dts",