@atscript/db-client 0.1.151 → 0.1.153

package/dist/index.cjs

@@ -145,6 +145,131 @@ var ActionUnsupportedError = class extends Error {
 	}
 };
 //#endregion
+//#region src/meta-store.ts
+/** ETags remembered per store key (most recent first). */
+const CANDIDATES_PER_KEY = 4;
+/**
+* Content-addressed cache of `GET /meta` responses, keyed by the server's
+* `ETag`, used by {@link Client.meta} to revalidate instead of downloading.
+*
+* For each store key (the meta URL, or `ClientOptions.metaKey`) the store
+* remembers the ETags it has seen. `meta()` sends them as `If-None-Match`;
+* when the server answers `304 Not Modified` the client reuses the body
+* stored under the returned `ETag`. Several keys that serve the same bytes
+* — e.g. one parametric controller mounted at `/api/tenant/:id/todos` —
+* therefore share one stored body, and the first visit to a new key costs a
+* `304` instead of the full `/meta`.
+*
+* It is a pure cache: the server decides on every request whether the body
+* is still valid. Failures are never stored.
+*
+* @since 0.1.153
+*/
+var MetaStore = class {
+	_maxEntries;
+	_unconditionalMs;
+	/** Raw JSON body by opaque ETag (`W/` stripped — `If-None-Match` compares weakly). */
+	_bodies = /* @__PURE__ */ new Map();
+	_keys = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this._maxEntries = Math.max(1, options?.maxEntries ?? 50);
+		this._unconditionalMs = Math.max(0, options?.unconditionalMs ?? 3e5);
+	}
+	/** Number of stored `/meta` bodies. */
+	get size() {
+		return this._bodies.size;
+	}
+	/**
+	* The ETags this store would send as `If-None-Match` for `key` — those seen
+	* for it whose body is still stored, most recent first.
+	*/
+	candidates(key) {
+		const entry = this._keys.get(key);
+		if (!entry) return [];
+		return entry.etags.filter((etag) => this._bodies.has(opaque(etag)));
+	}
+	/** Drops every stored body and remembered ETag. */
+	clear() {
+		this._bodies.clear();
+		this._keys.clear();
+	}
+	/**
+	* Stored body for `etag` (weak comparison), marking it — and `etag` as the
+	* latest candidate for `key` — as recently used.
+	*
+	* @internal used by `Client`
+	*/
+	_reuse(key, etag) {
+		const id = opaque(etag);
+		const text = this._bodies.get(id);
+		if (text === void 0) return void 0;
+		this._bodies.delete(id);
+		this._bodies.set(id, text);
+		this._remember(key, etag);
+		return text;
+	}
+	/**
+	* Stores a `200` body under its ETag and remembers the ETag for `key`.
+	*
+	* @internal used by `Client`
+	*/
+	_put(key, etag, text) {
+		const id = opaque(etag);
+		this._bodies.delete(id);
+		this._bodies.set(id, text);
+		while (this._bodies.size > this._maxEntries) this._bodies.delete(this._bodies.keys().next().value);
+		this._remember(key, etag);
+	}
+	/**
+	* Whether `key` is in its no-`If-None-Match` window; an expired window is
+	* cleared, so the next request is conditional again.
+	*
+	* @internal used by `Client`
+	*/
+	_isUnconditional(key) {
+		const entry = this._keys.get(key);
+		const until = entry?.unconditionalUntil;
+		if (until === void 0) return false;
+		if (Date.now() < until) return true;
+		delete entry.unconditionalUntil;
+		return false;
+	}
+	/** @internal used by `Client` */
+	_markUnconditional(key) {
+		this._touchKey(key).unconditionalUntil = Date.now() + this._unconditionalMs;
+	}
+	_remember(key, etag) {
+		const entry = this._touchKey(key);
+		const id = opaque(etag);
+		entry.etags = [etag, ...entry.etags.filter((e) => opaque(e) !== id)].slice(0, CANDIDATES_PER_KEY);
+	}
+	/** The entry for `key`, created if needed and moved to most recently used. */
+	_touchKey(key) {
+		const entry = this._keys.get(key) ?? { etags: [] };
+		this._keys.delete(key);
+		this._keys.set(key, entry);
+		while (this._keys.size > this._maxEntries * 4) this._keys.delete(this._keys.keys().next().value);
+		return entry;
+	}
+};
+function opaque(etag) {
+	return etag.startsWith("W/") ? etag.slice(2) : etag;
+}
+/**
+* The store every {@link Client} uses unless `ClientOptions.metaStore` says
+* otherwise, so all clients in a page share revalidated `/meta` bodies.
+*/
+const defaultMetaStore = new MetaStore();
+/**
+* Clears the shared default {@link MetaStore}. Call it on sign-out or any
+* identity change (together with `Client.invalidateMeta()` on live clients).
+*
+* @since 0.1.153
+*/
+function clearMetaStore() {
+	defaultMetaStore.clear();
+}
+//#endregion
 //#region src/client.ts
 /**
 * HTTP client for moost-db REST endpoints.
@@ -185,7 +310,11 @@ var Client = class {
 	_headers;
 	_navigate;
 	_lenientWrites;
+	_metaStore;
+	_metaKey;
 	_metaPromise;
+	/** The `ETag` of the `/meta` body {@link _metaPromise} resolved to. */
+	_metaEtag;
 	_validatorPromise;
 	/** Cached deserialized form schemas keyed by resolved URL. */
 	_formCache = /* @__PURE__ */ new Map();
@@ -196,6 +325,8 @@ var Client = class {
 		this._headers = opts?.headers;
 		this._navigate = opts?.navigate;
 		this._lenientWrites = opts?.lenientWrites;
+		this._metaStore = opts?.metaStore === false ? void 0 : opts?.metaStore ?? defaultMetaStore;
+		this._metaKey = opts?.metaKey;
 	}
 	/**
 	* `GET /query` — query records with typed filter, sort, select, and relations.
@@ -322,10 +453,17 @@ var Client = class {
 	}
 	/**
 	* `GET /meta` — table/view metadata (cached after first call).
+	*
+	* The response is revalidated through the client's meta store
+	* (`ClientOptions.metaStore`): ETags seen before for this store key go out
+	* as `If-None-Match`, and a `304 Not Modified` reuses the stored body.
 	*/
 	async meta() {
 		if (!this._metaPromise) {
-			const p = this._request("GET", "meta").catch((err) => {
+			const p = this._loadMeta().then(({ body, etag }) => {
+				if (this._metaPromise === p) this._metaEtag = etag;
+				return body;
+			}, (err) => {
 				if (this._metaPromise === p) this._metaPromise = void 0;
 				throw err;
 			});
@@ -334,6 +472,19 @@ var Client = class {
 		return this._metaPromise;
 	}
 	/**
+	* The `ETag` of the `/meta` body {@link meta} resolved to — `undefined`
+	* before it resolves, after {@link invalidateMeta}, or when the server sent
+	* no readable `ETag` (cross-origin without `Access-Control-Expose-Headers:
+	* ETag`). Equal ETags mean byte-identical `/meta` bodies, so it can key
+	* anything derived from them (deserialized types, validators, column
+	* definitions) across clients and route params.
+	*
+	* @since 0.1.153
+	*/
+	metaEtag() {
+		return this._metaEtag;
+	}
+	/**
 	* Drops everything this client cached from the server's metadata — the
 	* `/meta` response, the validator built from it and the loaded action
 	* forms — so the next call fetches them again. Call it when the viewer's
@@ -341,10 +492,15 @@ var Client = class {
 	* user, and a client reused across identities would otherwise keep serving
 	* the previous user's columns, actions and write rules.
 	*
+	* The next `meta()` still revalidates through the meta store, so an
+	* unchanged `/meta` costs a `304`, not a download. On an identity change
+	* also clear the store (`clearMetaStore()` / `metaStore.clear()`).
+	*
 	* @since 0.1.151
 	*/
 	invalidateMeta() {
 		this._metaPromise = void 0;
+		this._metaEtag = void 0;
 		this._validatorPromise = void 0;
 		this._formCache.clear();
 	}
@@ -600,6 +756,83 @@ var Client = class {
 		if (typeof this._headers === "function") return await this._headers();
 		return this._headers;
 	}
+	/**
+	* `GET /meta` through the meta store: conditional when the store holds
+	* bodies for this key, falling back to a plain request whenever the
+	* conditional one cannot be answered from the store.
+	*/
+	async _loadMeta() {
+		const url = this._endpointUrl("meta");
+		const store = this._metaStore;
+		if (!store) {
+			const res = await this._fetchUrl(url, {
+				method: "GET",
+				headers: await this._resolveHeaders()
+			});
+			return {
+				body: await this._readResponse(res, url, "GET", false),
+				etag: res.ok ? readEtag(res) : void 0
+			};
+		}
+		const key = this._metaKey ?? url;
+		const headers = await this._resolveHeaders();
+		const candidates = store._isUnconditional(key) ? [] : store.candidates(key);
+		if (candidates.length > 0) {
+			const init = {
+				method: "GET",
+				headers: {
+					...headers,
+					"If-None-Match": candidates.join(", ")
+				}
+			};
+			let res;
+			try {
+				res = await this._fetchUrl(url, init);
+			} catch {}
+			if (res && res.status === 304) {
+				const etag = readEtag(res);
+				const text = etag === void 0 ? void 0 : store._reuse(key, etag);
+				if (text !== void 0) return {
+					body: JSON.parse(text),
+					etag
+				};
+			} else if (res) return this._storeMeta(store, key, url, res);
+			else {
+				const fallback = await this._fetchUrl(url, {
+					method: "GET",
+					headers: { ...headers }
+				});
+				store._markUnconditional(key);
+				return this._storeMeta(store, key, url, fallback);
+			}
+		}
+		const res = await this._fetchUrl(url, {
+			method: "GET",
+			headers: { ...headers }
+		});
+		return this._storeMeta(store, key, url, res);
+	}
+	/** Reads a `/meta` response; a `2xx` carrying a readable `ETag` goes into the store. */
+	async _storeMeta(store, key, url, res) {
+		const etag = res.ok ? readEtag(res) : void 0;
+		if (etag === void 0 || typeof res.text !== "function") return {
+			body: await this._readResponse(res, url, "GET", false),
+			etag
+		};
+		let body;
+		let text;
+		try {
+			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);
+		}
+		store._put(key, etag, text);
+		return {
+			body,
+			etag
+		};
+	}
 	_request(method, endpoint, body) {
 		return this._requestUrl(method, this._endpointUrl(endpoint), body);
 	}
@@ -622,13 +855,19 @@ var Client = class {
 		return this._send(url, init, allowEmpty);
 	}
 	async _send(url, init, allowEmpty) {
-		const method = init.method ?? "GET";
-		let res;
+		const res = await this._fetchUrl(url, init);
+		return this._readResponse(res, url, init.method ?? "GET", allowEmpty);
+	}
+	/** `fetch` with a network failure surfaced as {@link TransportError}. */
+	async _fetchUrl(url, init) {
 		try {
-			res = await this._fetch(url, init);
+			return await this._fetch(url, init);
 		} catch (cause) {
-			throw new TransportError(method, url, describeCause(cause), cause);
+			throw new TransportError(init.method ?? "GET", url, describeCause(cause), cause);
 		}
+	}
+	/** A response's JSON body, or the matching error for a non-2xx status. */
+	async _readResponse(res, url, method, allowEmpty) {
 		if (!res.ok) {
 			let errorBody;
 			try {
@@ -657,6 +896,13 @@ var Client = class {
 		}
 	}
 };
+/**
+* The response's `ETag`, when readable — a cross-origin response hides it
+* unless the server sends `Access-Control-Expose-Headers: ETag`.
+*/
+function readEtag(res) {
+	return res.headers?.get?.("etag") || void 0;
+}
 /** One-line rendering of a thrown value for a `TransportError` message. */
 function describeCause(cause) {
 	if (cause instanceof Error) return cause.message || cause.name;
@@ -758,6 +1004,7 @@ exports.ActionTargetError = ActionTargetError;
 exports.ActionUnsupportedError = ActionUnsupportedError;
 exports.Client = Client;
 exports.ClientError = ClientError;
+exports.MetaStore = MetaStore;
 exports.TransportError = TransportError;
 exports.VersionMismatchError = VersionMismatchError;
 exports.actionIdentifier = actionIdentifier;
@@ -773,6 +1020,7 @@ Object.defineProperty(exports, "bucketStartInstant", {
 		return _uniqu_core.bucketStartInstant;
 	}
 });
+exports.clearMetaStore = clearMetaStore;
 exports.encodeNavigateId = encodeNavigateId;
 exports.formatIdentifier = formatIdentifier;
 exports.formatIdentifierField = formatIdentifierField;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { A as SearchIndexInfo, B as Uniquery, C as MetaResponse, D as PatchOf, E as PageResult, F as TDbInsertManyResult, H as ValidGroupBy, I as TDbInsertResult, L as TDbQueryTarget, M as TDbDeleteResult, N as TDbInsertIgnoreResult, O as RelationInfo, P as TDbInsertManyIgnoreResult, R as TDbUpdateResult, S as IdOf, T as OwnOf, U as WeekStart, V as UniqueryControls, _ as DbRow, a as ValidatorMode, b as FieldMeta, c as AggregateResult, d as BucketUnit, f as CalendarBucketLabel, g as DbPatch, h as DataOf, j as ServerError, k as RowOf, l as AtscriptClientShape, m as ClientResponse, n as ClientValidator, p as ClientOptions, r as ClientValidatorOptions, s as AggregateQuery, t as ClientValidationError, u as BucketExpr, v as DecoratedControls, w as NavOf, x as FilterExpr, y as DecoratedQuery, z as TypedWithRelation } from "./validator-CVM7eNP7.cjs";
+import { A as SearchIndexInfo, B as Uniquery, C as MetaResponse, D as PatchOf, E as PageResult, F as TDbInsertManyResult, G as MetaStoreOptions, H as ValidGroupBy, I as TDbInsertResult, K as clearMetaStore, L as TDbQueryTarget, M as TDbDeleteResult, N as TDbInsertIgnoreResult, O as RelationInfo, P as TDbInsertManyIgnoreResult, R as TDbUpdateResult, S as IdOf, T as OwnOf, U as WeekStart, V as UniqueryControls, W as MetaStore, _ as DbRow, a as ValidatorMode, b as FieldMeta, c as AggregateResult, d as BucketUnit, f as CalendarBucketLabel, g as DbPatch, h as DataOf, j as ServerError, k as RowOf, l as AtscriptClientShape, m as ClientResponse, n as ClientValidator, p as ClientOptions, r as ClientValidatorOptions, s as AggregateQuery, t as ClientValidationError, u as BucketExpr, v as DecoratedControls, w as NavOf, x as FilterExpr, y as DecoratedQuery, z as TypedWithRelation } from "./validator-u-SCH8c3.cjs";
 import { AggregateExpr, AggregateOfExpr, AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, BucketExpr as BucketExpr$1, BucketSeriesOptions, NextBucketOptions, SelectArithExpr, Uniquery as Uniquery$1, ValidGroupBy as ValidGroupBy$1, bucketSeries, bucketStartInstant, nextBucketLabel } from "@uniqu/core";
 import { TAtscriptAnnotatedType, TSerializedAnnotatedType } from "@atscript/typescript/utils";
 import { TCrudOp, TCrudPermissions, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionLevel, TDbActionProcessor, TDbActionTargetSummary, TDbActionTargetSummary as TDbActionTargetSummary$1, TDbAvailableActions, TDbAvailableActions as TDbAvailableActions$1, TDbDeleteResult as TDbDeleteResult$1, TDbInsertIgnoreResult as TDbInsertIgnoreResult$1, TDbInsertManyIgnoreResult as TDbInsertManyIgnoreResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1 } from "@atscript/db";
@@ -49,7 +49,11 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape, D exte
   private readonly _headers?;
   private readonly _navigate?;
   private readonly _lenientWrites?;
+  private readonly _metaStore;
+  private readonly _metaKey?;
   private _metaPromise?;
+  /** The `ETag` of the `/meta` body {@link _metaPromise} resolved to. */
+  private _metaEtag?;
   private _validatorPromise?;
   /** Cached deserialized form schemas keyed by resolved URL. */
   private _formCache;
@@ -163,8 +167,23 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape, D exte
   remove(id: Id<T>): Promise<TDbDeleteResult$1>;
   /**
    * `GET /meta` — table/view metadata (cached after first call).
+   *
+   * The response is revalidated through the client's meta store
+   * (`ClientOptions.metaStore`): ETags seen before for this store key go out
+   * as `If-None-Match`, and a `304 Not Modified` reuses the stored body.
    */
   meta(): Promise<MetaResponse>;
+  /**
+   * The `ETag` of the `/meta` body {@link meta} resolved to — `undefined`
+   * before it resolves, after {@link invalidateMeta}, or when the server sent
+   * no readable `ETag` (cross-origin without `Access-Control-Expose-Headers:
+   * ETag`). Equal ETags mean byte-identical `/meta` bodies, so it can key
+   * anything derived from them (deserialized types, validators, column
+   * definitions) across clients and route params.
+   *
+   * @since 0.1.153
+   */
+  metaEtag(): string | undefined;
   /**
    * Drops everything this client cached from the server's metadata — the
    * `/meta` response, the validator built from it and the loaded action
@@ -173,6 +192,10 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape, D exte
    * user, and a client reused across identities would otherwise keep serving
    * the previous user's columns, actions and write rules.
    *
+   * The next `meta()` still revalidates through the meta store, so an
+   * unchanged `/meta` costs a `304`, not a download. On an identity change
+   * also clear the store (`clearMetaStore()` / `metaStore.clear()`).
+   *
    * @since 0.1.151
    */
   invalidateMeta(): void;
@@ -299,12 +322,24 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape, D exte
   private _getOrNull;
   private _get;
   private _resolveHeaders;
+  /**
+   * `GET /meta` through the meta store: conditional when the store holds
+   * bodies for this key, falling back to a plain request whenever the
+   * conditional one cannot be answered from the store.
+   */
+  private _loadMeta;
+  /** Reads a `/meta` response; a `2xx` carrying a readable `ETag` goes into the store. */
+  private _storeMeta;
   private _request;
   /** `baseUrl + path` joined with an endpoint relative to this controller (`""`, `meta`, `?q`…). */
   private _endpointUrl;
   /** Sends one request to an absolute URL with the client's headers and a JSON body. */
   private _requestUrl;
   private _send;
+  /** `fetch` with a network failure surfaced as {@link TransportError}. */
+  private _fetchUrl;
+  /** A response's JSON body, or the matching error for a non-2xx status. */
+  private _readResponse;
 }
 /**
  * The identifier `action` takes for one row (or identifier) of the
@@ -508,4 +543,4 @@ declare class ActionUnsupportedError extends Error {
   constructor(action: string, processor: string, message: string);
 }
 //#endregion
-export { ActionDisabledError, type ActionDisabledErrorBody, ActionNotFoundError, ActionTargetError, type ActionTargetErrorBody, ActionUnsupportedError, type AggregateQuery, type AggregateResult, type AtscriptClientShape, type BucketExpr, type BucketSeriesOptions, type BucketUnit, type CalendarBucketLabel, 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 NextBucketOptions, 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 TDbActionTargetSummary, type TDbAvailableActions, type TDbDeleteResult, type TDbInsertIgnoreResult, type TDbInsertManyIgnoreResult, type TDbInsertManyResult, type TDbInsertResult, type TDbQueryTarget, type TDbUpdateResult, type TSerializedAnnotatedType, TransportError, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidGroupBy, type ValidatorMode, VersionMismatchError, type VersionMismatchErrorBody, type WeekStart, actionIdentifier, bucketSeries, bucketStartInstant, encodeNavigateId, formatIdentifier, formatIdentifierField, nextBucketLabel };
+export { ActionDisabledError, type ActionDisabledErrorBody, ActionNotFoundError, ActionTargetError, type ActionTargetErrorBody, ActionUnsupportedError, type AggregateQuery, type AggregateResult, type AtscriptClientShape, type BucketExpr, type BucketSeriesOptions, type BucketUnit, type CalendarBucketLabel, 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, MetaStore, type MetaStoreOptions, type NavOf, type NextBucketOptions, 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 TDbActionTargetSummary, type TDbAvailableActions, type TDbDeleteResult, type TDbInsertIgnoreResult, type TDbInsertManyIgnoreResult, type TDbInsertManyResult, type TDbInsertResult, type TDbQueryTarget, type TDbUpdateResult, type TSerializedAnnotatedType, TransportError, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidGroupBy, type ValidatorMode, VersionMismatchError, type VersionMismatchErrorBody, type WeekStart, actionIdentifier, bucketSeries, bucketStartInstant, clearMetaStore, encodeNavigateId, formatIdentifier, formatIdentifierField, nextBucketLabel };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { A as SearchIndexInfo, B as Uniquery, C as MetaResponse, D as PatchOf, E as PageResult, F as TDbInsertManyResult, H as ValidGroupBy, I as TDbInsertResult, L as TDbQueryTarget, M as TDbDeleteResult, N as TDbInsertIgnoreResult, O as RelationInfo, P as TDbInsertManyIgnoreResult, R as TDbUpdateResult, S as IdOf, T as OwnOf, U as WeekStart, V as UniqueryControls, _ as DbRow, a as ValidatorMode, b as FieldMeta, c as AggregateResult, d as BucketUnit, f as CalendarBucketLabel, g as DbPatch, h as DataOf, j as ServerError, k as RowOf, l as AtscriptClientShape, m as ClientResponse, n as ClientValidator, p as ClientOptions, r as ClientValidatorOptions, s as AggregateQuery, t as ClientValidationError, u as BucketExpr, v as DecoratedControls, w as NavOf, x as FilterExpr, y as DecoratedQuery, z as TypedWithRelation } from "./validator-CPmmXTAt.mjs";
+import { A as SearchIndexInfo, B as Uniquery, C as MetaResponse, D as PatchOf, E as PageResult, F as TDbInsertManyResult, G as MetaStoreOptions, H as ValidGroupBy, I as TDbInsertResult, K as clearMetaStore, L as TDbQueryTarget, M as TDbDeleteResult, N as TDbInsertIgnoreResult, O as RelationInfo, P as TDbInsertManyIgnoreResult, R as TDbUpdateResult, S as IdOf, T as OwnOf, U as WeekStart, V as UniqueryControls, W as MetaStore, _ as DbRow, a as ValidatorMode, b as FieldMeta, c as AggregateResult, d as BucketUnit, f as CalendarBucketLabel, g as DbPatch, h as DataOf, j as ServerError, k as RowOf, l as AtscriptClientShape, m as ClientResponse, n as ClientValidator, p as ClientOptions, r as ClientValidatorOptions, s as AggregateQuery, t as ClientValidationError, u as BucketExpr, v as DecoratedControls, w as NavOf, x as FilterExpr, y as DecoratedQuery, z as TypedWithRelation } from "./validator-DRW4WDEX.mjs";
 import { TAtscriptAnnotatedType, TSerializedAnnotatedType } from "@atscript/typescript/utils";
 import { AggregateExpr, AggregateOfExpr, AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, BucketExpr as BucketExpr$1, BucketSeriesOptions, NextBucketOptions, SelectArithExpr, Uniquery as Uniquery$1, ValidGroupBy as ValidGroupBy$1, bucketSeries, bucketStartInstant, nextBucketLabel } from "@uniqu/core";
 import { TCrudOp, TCrudPermissions, TDbActionInfo, TDbActionInfo as TDbActionInfo$1, TDbActionIntent, TDbActionLevel, TDbActionProcessor, TDbActionTargetSummary, TDbActionTargetSummary as TDbActionTargetSummary$1, TDbAvailableActions, TDbAvailableActions as TDbAvailableActions$1, TDbDeleteResult as TDbDeleteResult$1, TDbInsertIgnoreResult as TDbInsertIgnoreResult$1, TDbInsertManyIgnoreResult as TDbInsertManyIgnoreResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1 } from "@atscript/db";
@@ -49,7 +49,11 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape, D exte
   private readonly _headers?;
   private readonly _navigate?;
   private readonly _lenientWrites?;
+  private readonly _metaStore;
+  private readonly _metaKey?;
   private _metaPromise?;
+  /** The `ETag` of the `/meta` body {@link _metaPromise} resolved to. */
+  private _metaEtag?;
   private _validatorPromise?;
   /** Cached deserialized form schemas keyed by resolved URL. */
   private _formCache;
@@ -163,8 +167,23 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape, D exte
   remove(id: Id<T>): Promise<TDbDeleteResult$1>;
   /**
    * `GET /meta` — table/view metadata (cached after first call).
+   *
+   * The response is revalidated through the client's meta store
+   * (`ClientOptions.metaStore`): ETags seen before for this store key go out
+   * as `If-None-Match`, and a `304 Not Modified` reuses the stored body.
    */
   meta(): Promise<MetaResponse>;
+  /**
+   * The `ETag` of the `/meta` body {@link meta} resolved to — `undefined`
+   * before it resolves, after {@link invalidateMeta}, or when the server sent
+   * no readable `ETag` (cross-origin without `Access-Control-Expose-Headers:
+   * ETag`). Equal ETags mean byte-identical `/meta` bodies, so it can key
+   * anything derived from them (deserialized types, validators, column
+   * definitions) across clients and route params.
+   *
+   * @since 0.1.153
+   */
+  metaEtag(): string | undefined;
   /**
    * Drops everything this client cached from the server's metadata — the
    * `/meta` response, the validator built from it and the loaded action
@@ -173,6 +192,10 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape, D exte
    * user, and a client reused across identities would otherwise keep serving
    * the previous user's columns, actions and write rules.
    *
+   * The next `meta()` still revalidates through the meta store, so an
+   * unchanged `/meta` costs a `304`, not a download. On an identity change
+   * also clear the store (`clearMetaStore()` / `metaStore.clear()`).
+   *
    * @since 0.1.151
    */
   invalidateMeta(): void;
@@ -299,12 +322,24 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape, D exte
   private _getOrNull;
   private _get;
   private _resolveHeaders;
+  /**
+   * `GET /meta` through the meta store: conditional when the store holds
+   * bodies for this key, falling back to a plain request whenever the
+   * conditional one cannot be answered from the store.
+   */
+  private _loadMeta;
+  /** Reads a `/meta` response; a `2xx` carrying a readable `ETag` goes into the store. */
+  private _storeMeta;
   private _request;
   /** `baseUrl + path` joined with an endpoint relative to this controller (`""`, `meta`, `?q`…). */
   private _endpointUrl;
   /** Sends one request to an absolute URL with the client's headers and a JSON body. */
   private _requestUrl;
   private _send;
+  /** `fetch` with a network failure surfaced as {@link TransportError}. */
+  private _fetchUrl;
+  /** A response's JSON body, or the matching error for a non-2xx status. */
+  private _readResponse;
 }
 /**
  * The identifier `action` takes for one row (or identifier) of the
@@ -508,4 +543,4 @@ declare class ActionUnsupportedError extends Error {
   constructor(action: string, processor: string, message: string);
 }
 //#endregion
-export { ActionDisabledError, type ActionDisabledErrorBody, ActionNotFoundError, ActionTargetError, type ActionTargetErrorBody, ActionUnsupportedError, type AggregateQuery, type AggregateResult, type AtscriptClientShape, type BucketExpr, type BucketSeriesOptions, type BucketUnit, type CalendarBucketLabel, 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 NextBucketOptions, 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 TDbActionTargetSummary, type TDbAvailableActions, type TDbDeleteResult, type TDbInsertIgnoreResult, type TDbInsertManyIgnoreResult, type TDbInsertManyResult, type TDbInsertResult, type TDbQueryTarget, type TDbUpdateResult, type TSerializedAnnotatedType, TransportError, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidGroupBy, type ValidatorMode, VersionMismatchError, type VersionMismatchErrorBody, type WeekStart, actionIdentifier, bucketSeries, bucketStartInstant, encodeNavigateId, formatIdentifier, formatIdentifierField, nextBucketLabel };
+export { ActionDisabledError, type ActionDisabledErrorBody, ActionNotFoundError, ActionTargetError, type ActionTargetErrorBody, ActionUnsupportedError, type AggregateQuery, type AggregateResult, type AtscriptClientShape, type BucketExpr, type BucketSeriesOptions, type BucketUnit, type CalendarBucketLabel, 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, MetaStore, type MetaStoreOptions, type NavOf, type NextBucketOptions, 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 TDbActionTargetSummary, type TDbAvailableActions, type TDbDeleteResult, type TDbInsertIgnoreResult, type TDbInsertManyIgnoreResult, type TDbInsertManyResult, type TDbInsertResult, type TDbQueryTarget, type TDbUpdateResult, type TSerializedAnnotatedType, TransportError, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidGroupBy, type ValidatorMode, VersionMismatchError, type VersionMismatchErrorBody, type WeekStart, actionIdentifier, bucketSeries, bucketStartInstant, clearMetaStore, encodeNavigateId, formatIdentifier, formatIdentifierField, nextBucketLabel };

package/dist/index.mjs

@@ -144,6 +144,131 @@ var ActionUnsupportedError = class extends Error {
 	}
 };
 //#endregion
+//#region src/meta-store.ts
+/** ETags remembered per store key (most recent first). */
+const CANDIDATES_PER_KEY = 4;
+/**
+* Content-addressed cache of `GET /meta` responses, keyed by the server's
+* `ETag`, used by {@link Client.meta} to revalidate instead of downloading.
+*
+* For each store key (the meta URL, or `ClientOptions.metaKey`) the store
+* remembers the ETags it has seen. `meta()` sends them as `If-None-Match`;
+* when the server answers `304 Not Modified` the client reuses the body
+* stored under the returned `ETag`. Several keys that serve the same bytes
+* — e.g. one parametric controller mounted at `/api/tenant/:id/todos` —
+* therefore share one stored body, and the first visit to a new key costs a
+* `304` instead of the full `/meta`.
+*
+* It is a pure cache: the server decides on every request whether the body
+* is still valid. Failures are never stored.
+*
+* @since 0.1.153
+*/
+var MetaStore = class {
+	_maxEntries;
+	_unconditionalMs;
+	/** Raw JSON body by opaque ETag (`W/` stripped — `If-None-Match` compares weakly). */
+	_bodies = /* @__PURE__ */ new Map();
+	_keys = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this._maxEntries = Math.max(1, options?.maxEntries ?? 50);
+		this._unconditionalMs = Math.max(0, options?.unconditionalMs ?? 3e5);
+	}
+	/** Number of stored `/meta` bodies. */
+	get size() {
+		return this._bodies.size;
+	}
+	/**
+	* The ETags this store would send as `If-None-Match` for `key` — those seen
+	* for it whose body is still stored, most recent first.
+	*/
+	candidates(key) {
+		const entry = this._keys.get(key);
+		if (!entry) return [];
+		return entry.etags.filter((etag) => this._bodies.has(opaque(etag)));
+	}
+	/** Drops every stored body and remembered ETag. */
+	clear() {
+		this._bodies.clear();
+		this._keys.clear();
+	}
+	/**
+	* Stored body for `etag` (weak comparison), marking it — and `etag` as the
+	* latest candidate for `key` — as recently used.
+	*
+	* @internal used by `Client`
+	*/
+	_reuse(key, etag) {
+		const id = opaque(etag);
+		const text = this._bodies.get(id);
+		if (text === void 0) return void 0;
+		this._bodies.delete(id);
+		this._bodies.set(id, text);
+		this._remember(key, etag);
+		return text;
+	}
+	/**
+	* Stores a `200` body under its ETag and remembers the ETag for `key`.
+	*
+	* @internal used by `Client`
+	*/
+	_put(key, etag, text) {
+		const id = opaque(etag);
+		this._bodies.delete(id);
+		this._bodies.set(id, text);
+		while (this._bodies.size > this._maxEntries) this._bodies.delete(this._bodies.keys().next().value);
+		this._remember(key, etag);
+	}
+	/**
+	* Whether `key` is in its no-`If-None-Match` window; an expired window is
+	* cleared, so the next request is conditional again.
+	*
+	* @internal used by `Client`
+	*/
+	_isUnconditional(key) {
+		const entry = this._keys.get(key);
+		const until = entry?.unconditionalUntil;
+		if (until === void 0) return false;
+		if (Date.now() < until) return true;
+		delete entry.unconditionalUntil;
+		return false;
+	}
+	/** @internal used by `Client` */
+	_markUnconditional(key) {
+		this._touchKey(key).unconditionalUntil = Date.now() + this._unconditionalMs;
+	}
+	_remember(key, etag) {
+		const entry = this._touchKey(key);
+		const id = opaque(etag);
+		entry.etags = [etag, ...entry.etags.filter((e) => opaque(e) !== id)].slice(0, CANDIDATES_PER_KEY);
+	}
+	/** The entry for `key`, created if needed and moved to most recently used. */
+	_touchKey(key) {
+		const entry = this._keys.get(key) ?? { etags: [] };
+		this._keys.delete(key);
+		this._keys.set(key, entry);
+		while (this._keys.size > this._maxEntries * 4) this._keys.delete(this._keys.keys().next().value);
+		return entry;
+	}
+};
+function opaque(etag) {
+	return etag.startsWith("W/") ? etag.slice(2) : etag;
+}
+/**
+* The store every {@link Client} uses unless `ClientOptions.metaStore` says
+* otherwise, so all clients in a page share revalidated `/meta` bodies.
+*/
+const defaultMetaStore = new MetaStore();
+/**
+* Clears the shared default {@link MetaStore}. Call it on sign-out or any
+* identity change (together with `Client.invalidateMeta()` on live clients).
+*
+* @since 0.1.153
+*/
+function clearMetaStore() {
+	defaultMetaStore.clear();
+}
+//#endregion
 //#region src/client.ts
 /**
 * HTTP client for moost-db REST endpoints.
@@ -184,7 +309,11 @@ var Client = class {
 	_headers;
 	_navigate;
 	_lenientWrites;
+	_metaStore;
+	_metaKey;
 	_metaPromise;
+	/** The `ETag` of the `/meta` body {@link _metaPromise} resolved to. */
+	_metaEtag;
 	_validatorPromise;
 	/** Cached deserialized form schemas keyed by resolved URL. */
 	_formCache = /* @__PURE__ */ new Map();
@@ -195,6 +324,8 @@ var Client = class {
 		this._headers = opts?.headers;
 		this._navigate = opts?.navigate;
 		this._lenientWrites = opts?.lenientWrites;
+		this._metaStore = opts?.metaStore === false ? void 0 : opts?.metaStore ?? defaultMetaStore;
+		this._metaKey = opts?.metaKey;
 	}
 	/**
 	* `GET /query` — query records with typed filter, sort, select, and relations.
@@ -321,10 +452,17 @@ var Client = class {
 	}
 	/**
 	* `GET /meta` — table/view metadata (cached after first call).
+	*
+	* The response is revalidated through the client's meta store
+	* (`ClientOptions.metaStore`): ETags seen before for this store key go out
+	* as `If-None-Match`, and a `304 Not Modified` reuses the stored body.
 	*/
 	async meta() {
 		if (!this._metaPromise) {
-			const p = this._request("GET", "meta").catch((err) => {
+			const p = this._loadMeta().then(({ body, etag }) => {
+				if (this._metaPromise === p) this._metaEtag = etag;
+				return body;
+			}, (err) => {
 				if (this._metaPromise === p) this._metaPromise = void 0;
 				throw err;
 			});
@@ -333,6 +471,19 @@ var Client = class {
 		return this._metaPromise;
 	}
 	/**
+	* The `ETag` of the `/meta` body {@link meta} resolved to — `undefined`
+	* before it resolves, after {@link invalidateMeta}, or when the server sent
+	* no readable `ETag` (cross-origin without `Access-Control-Expose-Headers:
+	* ETag`). Equal ETags mean byte-identical `/meta` bodies, so it can key
+	* anything derived from them (deserialized types, validators, column
+	* definitions) across clients and route params.
+	*
+	* @since 0.1.153
+	*/
+	metaEtag() {
+		return this._metaEtag;
+	}
+	/**
 	* Drops everything this client cached from the server's metadata — the
 	* `/meta` response, the validator built from it and the loaded action
 	* forms — so the next call fetches them again. Call it when the viewer's
@@ -340,10 +491,15 @@ var Client = class {
 	* user, and a client reused across identities would otherwise keep serving
 	* the previous user's columns, actions and write rules.
 	*
+	* The next `meta()` still revalidates through the meta store, so an
+	* unchanged `/meta` costs a `304`, not a download. On an identity change
+	* also clear the store (`clearMetaStore()` / `metaStore.clear()`).
+	*
 	* @since 0.1.151
 	*/
 	invalidateMeta() {
 		this._metaPromise = void 0;
+		this._metaEtag = void 0;
 		this._validatorPromise = void 0;
 		this._formCache.clear();
 	}
@@ -599,6 +755,83 @@ var Client = class {
 		if (typeof this._headers === "function") return await this._headers();
 		return this._headers;
 	}
+	/**
+	* `GET /meta` through the meta store: conditional when the store holds
+	* bodies for this key, falling back to a plain request whenever the
+	* conditional one cannot be answered from the store.
+	*/
+	async _loadMeta() {
+		const url = this._endpointUrl("meta");
+		const store = this._metaStore;
+		if (!store) {
+			const res = await this._fetchUrl(url, {
+				method: "GET",
+				headers: await this._resolveHeaders()
+			});
+			return {
+				body: await this._readResponse(res, url, "GET", false),
+				etag: res.ok ? readEtag(res) : void 0
+			};
+		}
+		const key = this._metaKey ?? url;
+		const headers = await this._resolveHeaders();
+		const candidates = store._isUnconditional(key) ? [] : store.candidates(key);
+		if (candidates.length > 0) {
+			const init = {
+				method: "GET",
+				headers: {
+					...headers,
+					"If-None-Match": candidates.join(", ")
+				}
+			};
+			let res;
+			try {
+				res = await this._fetchUrl(url, init);
+			} catch {}
+			if (res && res.status === 304) {
+				const etag = readEtag(res);
+				const text = etag === void 0 ? void 0 : store._reuse(key, etag);
+				if (text !== void 0) return {
+					body: JSON.parse(text),
+					etag
+				};
+			} else if (res) return this._storeMeta(store, key, url, res);
+			else {
+				const fallback = await this._fetchUrl(url, {
+					method: "GET",
+					headers: { ...headers }
+				});
+				store._markUnconditional(key);
+				return this._storeMeta(store, key, url, fallback);
+			}
+		}
+		const res = await this._fetchUrl(url, {
+			method: "GET",
+			headers: { ...headers }
+		});
+		return this._storeMeta(store, key, url, res);
+	}
+	/** Reads a `/meta` response; a `2xx` carrying a readable `ETag` goes into the store. */
+	async _storeMeta(store, key, url, res) {
+		const etag = res.ok ? readEtag(res) : void 0;
+		if (etag === void 0 || typeof res.text !== "function") return {
+			body: await this._readResponse(res, url, "GET", false),
+			etag
+		};
+		let body;
+		let text;
+		try {
+			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);
+		}
+		store._put(key, etag, text);
+		return {
+			body,
+			etag
+		};
+	}
 	_request(method, endpoint, body) {
 		return this._requestUrl(method, this._endpointUrl(endpoint), body);
 	}
@@ -621,13 +854,19 @@ var Client = class {
 		return this._send(url, init, allowEmpty);
 	}
 	async _send(url, init, allowEmpty) {
-		const method = init.method ?? "GET";
-		let res;
+		const res = await this._fetchUrl(url, init);
+		return this._readResponse(res, url, init.method ?? "GET", allowEmpty);
+	}
+	/** `fetch` with a network failure surfaced as {@link TransportError}. */
+	async _fetchUrl(url, init) {
 		try {
-			res = await this._fetch(url, init);
+			return await this._fetch(url, init);
 		} catch (cause) {
-			throw new TransportError(method, url, describeCause(cause), cause);
+			throw new TransportError(init.method ?? "GET", url, describeCause(cause), cause);
 		}
+	}
+	/** A response's JSON body, or the matching error for a non-2xx status. */
+	async _readResponse(res, url, method, allowEmpty) {
 		if (!res.ok) {
 			let errorBody;
 			try {
@@ -656,6 +895,13 @@ var Client = class {
 		}
 	}
 };
+/**
+* The response's `ETag`, when readable — a cross-origin response hides it
+* unless the server sends `Access-Control-Expose-Headers: ETag`.
+*/
+function readEtag(res) {
+	return res.headers?.get?.("etag") || void 0;
+}
 /** One-line rendering of a thrown value for a `TransportError` message. */
 function describeCause(cause) {
 	if (cause instanceof Error) return cause.message || cause.name;
@@ -751,4 +997,4 @@ function describeShape(value) {
 	return typeof value;
 }
 //#endregion
-export { ActionDisabledError, ActionNotFoundError, ActionTargetError, ActionUnsupportedError, Client, ClientError, TransportError, VersionMismatchError, actionIdentifier, bucketSeries, bucketStartInstant, encodeNavigateId, formatIdentifier, formatIdentifierField, nextBucketLabel };
+export { ActionDisabledError, ActionNotFoundError, ActionTargetError, ActionUnsupportedError, Client, ClientError, MetaStore, TransportError, VersionMismatchError, actionIdentifier, bucketSeries, bucketStartInstant, clearMetaStore, encodeNavigateId, formatIdentifier, formatIdentifierField, nextBucketLabel };

package/dist/{validator-CPmmXTAt.d.mts → validator-DRW4WDEX.d.mts}

@@ -3,6 +3,89 @@ import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$
 import { DbValidationContext, ValidatorMode, ValidatorMode as ValidatorMode$1 } from "@atscript/db/validator";
 import { DbPatch, DbResponse, DbRow, TDbDeleteResult as TDbDeleteResult$1, TDbInsertIgnoreResult as TDbInsertIgnoreResult$1, TDbInsertManyIgnoreResult as TDbInsertManyIgnoreResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1, TFieldMeta, TMetaResponse, TRelationInfo, TSearchIndexInfo } from "@atscript/db";
 
+//#region src/meta-store.d.ts
+/** Options for {@link MetaStore}. */
+interface MetaStoreOptions {
+  /**
+   * How many `/meta` bodies the store keeps (least recently used are dropped
+   * first). Default `50`.
+   */
+  maxEntries?: number;
+  /**
+   * After a conditional `/meta` request fails at the transport level (e.g. a
+   * CORS preflight refusing `If-None-Match`) while the plain retry succeeds,
+   * how long (ms) that store key is loaded without `If-None-Match` before a
+   * conditional request is tried again. Default `300000` (5 minutes).
+   */
+  unconditionalMs?: number;
+}
+/**
+ * Content-addressed cache of `GET /meta` responses, keyed by the server's
+ * `ETag`, used by {@link Client.meta} to revalidate instead of downloading.
+ *
+ * For each store key (the meta URL, or `ClientOptions.metaKey`) the store
+ * remembers the ETags it has seen. `meta()` sends them as `If-None-Match`;
+ * when the server answers `304 Not Modified` the client reuses the body
+ * stored under the returned `ETag`. Several keys that serve the same bytes
+ * — e.g. one parametric controller mounted at `/api/tenant/:id/todos` —
+ * therefore share one stored body, and the first visit to a new key costs a
+ * `304` instead of the full `/meta`.
+ *
+ * It is a pure cache: the server decides on every request whether the body
+ * is still valid. Failures are never stored.
+ *
+ * @since 0.1.153
+ */
+declare class MetaStore {
+  private readonly _maxEntries;
+  private readonly _unconditionalMs;
+  /** Raw JSON body by opaque ETag (`W/` stripped — `If-None-Match` compares weakly). */
+  private readonly _bodies;
+  private readonly _keys;
+  constructor(options?: MetaStoreOptions);
+  /** Number of stored `/meta` bodies. */
+  get size(): number;
+  /**
+   * The ETags this store would send as `If-None-Match` for `key` — those seen
+   * for it whose body is still stored, most recent first.
+   */
+  candidates(key: string): string[];
+  /** Drops every stored body and remembered ETag. */
+  clear(): void;
+  /**
+   * Stored body for `etag` (weak comparison), marking it — and `etag` as the
+   * latest candidate for `key` — as recently used.
+   *
+   * @internal used by `Client`
+   */
+  _reuse(key: string, etag: string): string | undefined;
+  /**
+   * Stores a `200` body under its ETag and remembers the ETag for `key`.
+   *
+   * @internal used by `Client`
+   */
+  _put(key: string, etag: string, text: string): void;
+  /**
+   * Whether `key` is in its no-`If-None-Match` window; an expired window is
+   * cleared, so the next request is conditional again.
+   *
+   * @internal used by `Client`
+   */
+  _isUnconditional(key: string): boolean;
+  /** @internal used by `Client` */
+  _markUnconditional(key: string): void;
+  private _remember;
+  /** The entry for `key`, created if needed and moved to most recently used. */
+  private _touchKey;
+}
+/**
+ * Clears the shared default {@link MetaStore}. Call it on sign-out or any
+ * identity change (together with `Client.invalidateMeta()` on live clients).
+ *
+ * @since 0.1.153
+ */
+declare function clearMetaStore(): void;
+//#endregion
 //#region src/types.d.ts
 /**
  * Write payload for `insert()` / `update()`: every key optional, optional
@@ -48,6 +131,23 @@ interface ClientOptions {
    * preflight catches typos.
    */
   lenientWrites?: boolean;
+  /**
+   * Where `meta()` keeps revalidatable `/meta` bodies (since 0.1.153).
+   * Defaults to one store shared by every client in the page, so clients for
+   * the same controller — or for one parametric controller under different
+   * route params — revalidate with `If-None-Match` and reuse the body on a
+   * `304`. Pass your own `new MetaStore()` to isolate a group of clients, or
+   * `false` to always download `/meta`.
+   */
+  metaStore?: MetaStore | false;
+  /**
+   * Key under which `metaStore` remembers this client's ETags (since
+   * 0.1.153). Defaults to the `/meta` URL. Give clients of a parametric
+   * mount one shared key (e.g. the route template
+   * `"/api/tenant/:tenantId/todos"`) so a new route param revalidates against
+   * the body already loaded for another one.
+   */
+  metaKey?: string;
 }
 /** Search index metadata from the server. */
 type SearchIndexInfo = TSearchIndexInfo;
@@ -248,4 +348,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, ValidGroupBy$1 as H, TDbInsertResult$1 as I, 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, 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, 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 { 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, 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 };

package/dist/{validator-CVM7eNP7.d.cts → validator-u-SCH8c3.d.cts}

@@ -3,6 +3,89 @@ import { TAtscriptAnnotatedType, TAtscriptTypeObject } from "@atscript/typescrip
 import { DbPatch, DbResponse, DbRow, TDbDeleteResult as TDbDeleteResult$1, TDbInsertIgnoreResult as TDbInsertIgnoreResult$1, TDbInsertManyIgnoreResult as TDbInsertManyIgnoreResult$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/meta-store.d.ts
+/** Options for {@link MetaStore}. */
+interface MetaStoreOptions {
+  /**
+   * How many `/meta` bodies the store keeps (least recently used are dropped
+   * first). Default `50`.
+   */
+  maxEntries?: number;
+  /**
+   * After a conditional `/meta` request fails at the transport level (e.g. a
+   * CORS preflight refusing `If-None-Match`) while the plain retry succeeds,
+   * how long (ms) that store key is loaded without `If-None-Match` before a
+   * conditional request is tried again. Default `300000` (5 minutes).
+   */
+  unconditionalMs?: number;
+}
+/**
+ * Content-addressed cache of `GET /meta` responses, keyed by the server's
+ * `ETag`, used by {@link Client.meta} to revalidate instead of downloading.
+ *
+ * For each store key (the meta URL, or `ClientOptions.metaKey`) the store
+ * remembers the ETags it has seen. `meta()` sends them as `If-None-Match`;
+ * when the server answers `304 Not Modified` the client reuses the body
+ * stored under the returned `ETag`. Several keys that serve the same bytes
+ * — e.g. one parametric controller mounted at `/api/tenant/:id/todos` —
+ * therefore share one stored body, and the first visit to a new key costs a
+ * `304` instead of the full `/meta`.
+ *
+ * It is a pure cache: the server decides on every request whether the body
+ * is still valid. Failures are never stored.
+ *
+ * @since 0.1.153
+ */
+declare class MetaStore {
+  private readonly _maxEntries;
+  private readonly _unconditionalMs;
+  /** Raw JSON body by opaque ETag (`W/` stripped — `If-None-Match` compares weakly). */
+  private readonly _bodies;
+  private readonly _keys;
+  constructor(options?: MetaStoreOptions);
+  /** Number of stored `/meta` bodies. */
+  get size(): number;
+  /**
+   * The ETags this store would send as `If-None-Match` for `key` — those seen
+   * for it whose body is still stored, most recent first.
+   */
+  candidates(key: string): string[];
+  /** Drops every stored body and remembered ETag. */
+  clear(): void;
+  /**
+   * Stored body for `etag` (weak comparison), marking it — and `etag` as the
+   * latest candidate for `key` — as recently used.
+   *
+   * @internal used by `Client`
+   */
+  _reuse(key: string, etag: string): string | undefined;
+  /**
+   * Stores a `200` body under its ETag and remembers the ETag for `key`.
+   *
+   * @internal used by `Client`
+   */
+  _put(key: string, etag: string, text: string): void;
+  /**
+   * Whether `key` is in its no-`If-None-Match` window; an expired window is
+   * cleared, so the next request is conditional again.
+   *
+   * @internal used by `Client`
+   */
+  _isUnconditional(key: string): boolean;
+  /** @internal used by `Client` */
+  _markUnconditional(key: string): void;
+  private _remember;
+  /** The entry for `key`, created if needed and moved to most recently used. */
+  private _touchKey;
+}
+/**
+ * Clears the shared default {@link MetaStore}. Call it on sign-out or any
+ * identity change (together with `Client.invalidateMeta()` on live clients).
+ *
+ * @since 0.1.153
+ */
+declare function clearMetaStore(): void;
+//#endregion
 //#region src/types.d.ts
 /**
  * Write payload for `insert()` / `update()`: every key optional, optional
@@ -48,6 +131,23 @@ interface ClientOptions {
    * preflight catches typos.
    */
   lenientWrites?: boolean;
+  /**
+   * Where `meta()` keeps revalidatable `/meta` bodies (since 0.1.153).
+   * Defaults to one store shared by every client in the page, so clients for
+   * the same controller — or for one parametric controller under different
+   * route params — revalidate with `If-None-Match` and reuse the body on a
+   * `304`. Pass your own `new MetaStore()` to isolate a group of clients, or
+   * `false` to always download `/meta`.
+   */
+  metaStore?: MetaStore | false;
+  /**
+   * Key under which `metaStore` remembers this client's ETags (since
+   * 0.1.153). Defaults to the `/meta` URL. Give clients of a parametric
+   * mount one shared key (e.g. the route template
+   * `"/api/tenant/:tenantId/todos"`) so a new route param revalidates against
+   * the body already loaded for another one.
+   */
+  metaKey?: string;
 }
 /** Search index metadata from the server. */
 type SearchIndexInfo = TSearchIndexInfo;
@@ -248,4 +348,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, ValidGroupBy$1 as H, TDbInsertResult$1 as I, 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, 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, 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 { 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, 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 };

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-CVM7eNP7.cjs";
+import { a as ValidatorMode, i as DbValidationContext, n as ClientValidator, o as createClientValidator, r as ClientValidatorOptions, t as ClientValidationError } from "./validator-u-SCH8c3.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-CPmmXTAt.mjs";
+import { a as ValidatorMode, i as DbValidationContext, n as ClientValidator, o as createClientValidator, r as ClientValidatorOptions, t as ClientValidationError } from "./validator-DRW4WDEX.mjs";
 export { ClientValidationError, ClientValidator, ClientValidatorOptions, type DbValidationContext, type ValidatorMode, createClientValidator };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-client",
-  "version": "0.1.151",
+  "version": "0.1.153",
   "description": "Browser-compatible HTTP client for @atscript/moost-db REST endpoints.",
   "keywords": [
     "atscript",
@@ -43,18 +43,18 @@
     "access": "public"
   },
   "dependencies": {
-    "@uniqu/core": "^0.1.14",
-    "@uniqu/url": "^0.1.14"
+    "@uniqu/core": "^0.1.15",
+    "@uniqu/url": "^0.1.15"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.102",
-    "@atscript/typescript": "^0.1.102",
-    "unplugin-atscript": "^0.1.102",
-    "@atscript/db": "0.1.151"
+    "@atscript/core": "^0.1.103",
+    "@atscript/typescript": "^0.1.103",
+    "unplugin-atscript": "^0.1.103",
+    "@atscript/db": "0.1.153"
   },
   "peerDependencies": {
     "@atscript/db": "^0.1.44",
-    "@atscript/typescript": "^0.1.102"
+    "@atscript/typescript": "^0.1.103"
   },
   "scripts": {
     "postinstall": "asc -f dts",