@atscript/db-client 0.1.145 → 0.1.147

package/dist/index.cjs

@@ -65,6 +65,29 @@ var ActionDisabledError = class extends ClientError {
 	}
 };
 /**
+* Typed marker thrown by `Client` when a query-targeted action request is
+* refused (body `name === 'ActionTargetError'`): `TARGET_INVALID` (400),
+* `TARGET_TOO_LARGE` (400, `cap`) or `TARGET_CHANGED` (409, `matched` — the
+* rows the query matches now; re-confirm and retry with that count).
+*
+* @since 0.1.147
+*/
+var ActionTargetError = class extends ClientError {
+	name = "ActionTargetError";
+	get code() {
+		return this.body.code;
+	}
+	get action() {
+		return this.body.action;
+	}
+	get matched() {
+		return this.body.matched;
+	}
+	get cap() {
+		return this.body.cap;
+	}
+};
+/**
 * Typed marker thrown by `Client._send` when the server response body's
 * `kind === 'version_mismatch'`. The transport / status / base body are
 * identical to a generic `ClientError`; this subclass adds a typed
@@ -186,7 +209,8 @@ var Client = class {
 	*
 	* `$select` may carry calendar buckets (`{ $bucket, $field, $tz?, $weekStart?, $as? }`);
 	* a `$groupBy` entry must be a dimension or a bucket alias (`ValidGroupBy`), and a
-	* bucket's value is typed as its `YYYY-MM-DD` label (`| null` for an optional source).
+	* bucket's value is typed as its `YYYY-MM-DD` (hour: `YYYY-MM-DDTHH:00`) label
+	* (`| null` for an optional source).
 	* Gap-fill between labels with `nextBucketLabel` (re-exported here).
 	*/
 	async aggregate(query) {
@@ -323,6 +347,13 @@ var Client = class {
 	* `{ ids?, input? }` — `ids` carries `id` (object or array per level),
 	* `input` carries the form payload.
 	*
+	* **Delegated actions** (since 0.1.147). An action another controller owns
+	* (`owner`, e.g. a view listing its source table's actions) may carry
+	* `idMap`: each `id` is then a row (or identifier) of THIS controller and
+	* is mapped to the owner's identification — `{ [ownerField]:
+	* row[path] }` — before it is sent to `value` (the owner's route). A
+	* missing path throws `TypeError`. See {@link actionIdentifier}.
+	*
 	* @typeParam R Caller-asserted return shape from the action handler. The
 	*              server returns whatever the handler emits (commonly
 	*              `{ message?: string, ... }`); the client cannot validate.
@@ -332,15 +363,65 @@ var Client = class {
 		const action = meta.actions.find((a) => a.name === name);
 		if (!action) throw new ActionNotFoundError(name);
 		if (action.processor === "custom") throw new ActionUnsupportedError(name, "custom", `Action "${name}" has processor "custom" — applications must dispatch custom actions themselves; the client cannot.`);
+		const mapped = action.idMap ? mapDelegatedIds(action, id) : id;
 		if (action.processor === "navigate") {
-			const url = this._interpolateNavigateUrl(action, id, meta.preferredId);
+			const order = action.idMap ? Object.keys(action.idMap) : meta.preferredId;
+			const url = this._interpolateNavigateUrl(action, mapped, order);
 			await this._dispatchNavigate(action, url);
 			return;
 		}
-		const body = this._buildActionBody(action, id, input);
+		const body = this._buildActionBody(action, mapped, input);
 		return this._postAction(action, body);
 	}
 	/**
+	* Runs a `'rows'` action on every row matching a query (since 0.1.147) —
+	* the action's `/meta` entry must carry `queryTarget`. POSTs
+	* `{ query: { q, exclude?, expectCount?, maxRows? }, input? }` to
+	* `queryTarget.url` (a delegated action: the view resolves the rows and
+	* runs the owner's action in batches) or `value`. `q` is the `/query`
+	* string of `target.filter` / `search` / `index`.
+	*
+	* The server answers what the handler returns — for a delegated action
+	* (and a handler returning `target.summary()`) a
+	* {@link TDbActionTargetSummary}. Refusals arrive as
+	* {@link ActionTargetError}: `TARGET_TOO_LARGE` (`cap`), `TARGET_CHANGED`
+	* (`matched` differs from `expectCount`), `TARGET_INVALID`. Throws
+	* {@link ActionUnsupportedError} when the action takes no query target.
+	*
+	* @since 0.1.147
+	*/
+	async actionOnQuery(name, target, input) {
+		const action = await this._queryTargetAction(name);
+		const body = { query: queryTargetBody(target) };
+		if (input !== void 0) body.input = input;
+		return this._postQueryTarget(action, body);
+	}
+	/**
+	* How many rows {@link actionOnQuery} would target right now (a dry run:
+	* the handler does not run) — pass the answer as `expectCount` to make the
+	* real run fail with `TARGET_CHANGED` if the set changed in between.
+	*
+	* @since 0.1.147
+	*/
+	async countActionTarget(name, target) {
+		const action = await this._queryTargetAction(name);
+		const query = {
+			...queryTargetBody(target),
+			dryRun: true
+		};
+		return this._postQueryTarget(action, { query });
+	}
+	async _queryTargetAction(name) {
+		const action = (await this.meta()).actions.find((a) => a.name === name);
+		if (!action) throw new ActionNotFoundError(name);
+		if (!action.queryTarget || action.processor !== "backend") throw new ActionUnsupportedError(name, action.processor, `Action "${name}" does not accept a query target (no \`queryTarget\` in /meta).`);
+		return action;
+	}
+	_postQueryTarget(action, body) {
+		const path = action.queryTarget?.url ?? action.value;
+		return this._requestUrl("POST", `${this._baseUrl}${path}`, body, true);
+	}
+	/**
 	* `GET /meta/actions/:id` or `GET /meta/actions?k1=v1&k2=v2` — the
 	* row-level actions the caller may run on one row right now, and the
 	* reasons of those disabled with one: `{ actions, disabledReasons? }`.
@@ -519,6 +600,7 @@ var Client = class {
 				};
 			}
 			if (errorBody.name === "ActionDisabledError") throw new ActionDisabledError(res.status, errorBody);
+			if (errorBody.name === "ActionTargetError") throw new ActionTargetError(res.status, errorBody);
 			if (errorBody.kind === "version_mismatch") throw new VersionMismatchError(res.status, errorBody);
 			throw new ClientError(res.status, errorBody);
 		}
@@ -540,6 +622,60 @@ function describeCause(cause) {
 	if (cause instanceof Error) return cause.message || cause.name;
 	return String(cause);
 }
+/** The value at a dot `path` of `row`. */
+function valueAt(row, path) {
+	if (!path.includes(".") || Object.hasOwn(row, path)) return row[path];
+	let v = row;
+	for (const part of path.split(".")) v = v?.[part];
+	return v;
+}
+/**
+* The identifier `action` takes for one row (or identifier) of the
+* controller whose `/meta` listed it (since 0.1.147):
+*
+* - a delegated action with `idMap` → the owner's identification,
+*   `{ [ownerField]: rowOrId[path] }` (dot paths allowed); a missing value
+*   throws `TypeError` naming the action and the path;
+* - any other action → `rowOrId`'s `preferredId` fields when it carries them
+*   all, else `rowOrId` itself (already an identifier).
+*
+* UIs build `ids` from loaded rows with it; `Client.action()` applies the
+* `idMap` mapping itself.
+*
+* @since 0.1.147
+*/
+function actionIdentifier(action, rowOrId, preferredId) {
+	if (action.idMap) {
+		const out = {};
+		for (const [field, path] of Object.entries(action.idMap)) {
+			const value = valueAt(rowOrId, path);
+			if (value === void 0 || value === null) throw new TypeError(`client.action("${action.name}"): the identifier has no "${path}" — needed for the owner's "${field}".`);
+			out[field] = value;
+		}
+		return out;
+	}
+	if (preferredId.length > 0 && preferredId.every((f) => rowOrId[f] !== void 0)) return Object.fromEntries(preferredId.map((f) => [f, rowOrId[f]]));
+	return rowOrId;
+}
+/** `action()`'s `id` argument through a delegated action's `idMap` (shape errors are left to the body builder). */
+function mapDelegatedIds(action, id) {
+	const map = (one) => one !== null && typeof one === "object" && !Array.isArray(one) ? actionIdentifier(action, one, []) : one;
+	return Array.isArray(id) ? id.map(map) : map(id);
+}
+/** The wire `query` of a {@link TDbQueryTarget}. */
+function queryTargetBody(target) {
+	const controls = {};
+	if (target.search !== void 0) controls.$search = target.search;
+	if (target.index !== void 0) controls.$index = target.index;
+	const out = { q: (0, _uniqu_url_builder.buildUrl)({
+		filter: target.filter ?? {},
+		controls
+	}) };
+	if (target.exclude?.length) out.exclude = target.exclude;
+	if (target.expectCount !== void 0) out.expectCount = target.expectCount;
+	if (target.maxRows !== void 0) out.maxRows = target.maxRows;
+	return out;
+}
 /**
 * Render a single identifier field for substitution into a navigate-URL
 * template or human-readable string. `null` / `undefined` collapse to `""`
@@ -578,11 +714,19 @@ function describeShape(value) {
 //#endregion
 exports.ActionDisabledError = ActionDisabledError;
 exports.ActionNotFoundError = ActionNotFoundError;
+exports.ActionTargetError = ActionTargetError;
 exports.ActionUnsupportedError = ActionUnsupportedError;
 exports.Client = Client;
 exports.ClientError = ClientError;
 exports.TransportError = TransportError;
 exports.VersionMismatchError = VersionMismatchError;
+exports.actionIdentifier = actionIdentifier;
+Object.defineProperty(exports, "bucketSeries", {
+	enumerable: true,
+	get: function() {
+		return _uniqu_core.bucketSeries;
+	}
+});
 Object.defineProperty(exports, "bucketStartInstant", {
 	enumerable: true,
 	get: function() {

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { A as TDbDeleteResult, C as OwnOf, D as RowOf, E as RelationInfo, F as Uniquery, I as UniqueryControls, L as ValidGroupBy, M as TDbInsertResult, N as TDbUpdateResult, O as SearchIndexInfo, P as TypedWithRelation, R as WeekStart, S as NavOf, T as PatchOf, _ as DbRow, a as ValidatorMode, b as IdOf, c as AggregateResult, d as BucketUnit, f as CalendarBucketLabel, g as DbPatch, h as DataOf, j as TDbInsertManyResult, k as ServerError, 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 FieldMeta, w as PageResult, x as MetaResponse, y as FilterExpr } from "./validator-810-rhnQ.cjs";
-import { AggregateExpr, AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, BucketExpr as BucketExpr$1, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1, ValidGroupBy as ValidGroupBy$1, bucketStartInstant, nextBucketLabel } from "@uniqu/core";
+import { A as TDbDeleteResult, C as OwnOf, D as RowOf, E as RelationInfo, F as TypedWithRelation, I as Uniquery, L as UniqueryControls, M as TDbInsertResult, N as TDbQueryTarget, O as SearchIndexInfo, P as TDbUpdateResult, R as ValidGroupBy, S as NavOf, T as PatchOf, _ as DbRow, a as ValidatorMode, b as IdOf, c as AggregateResult, d as BucketUnit, f as CalendarBucketLabel, g as DbPatch, h as DataOf, j as TDbInsertManyResult, k as ServerError, 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 FieldMeta, w as PageResult, x as MetaResponse, y as FilterExpr, z as WeekStart } from "./validator-DVha6LOQ.cjs";
+import { AggregateExpr, AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, BucketExpr as BucketExpr$1, BucketSeriesOptions, NextBucketOptions, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1, ValidGroupBy as ValidGroupBy$1, bucketSeries, bucketStartInstant, nextBucketLabel } from "@uniqu/core";
 import { TAtscriptAnnotatedType, TSerializedAnnotatedType } from "@atscript/typescript/utils";
-import { TCrudOp, TCrudPermissions, TDbActionInfo, TDbActionIntent, TDbActionLevel, TDbActionProcessor, TDbAvailableActions, TDbAvailableActions as TDbAvailableActions$1, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1 } from "@atscript/db";
+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, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1 } from "@atscript/db";
 
 //#region src/client.d.ts
 type Own<T> = OwnOf<T>;
@@ -59,7 +59,8 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    *
    * `$select` may carry calendar buckets (`{ $bucket, $field, $tz?, $weekStart?, $as? }`);
    * a `$groupBy` entry must be a dimension or a bucket alias (`ValidGroupBy`), and a
-   * bucket's value is typed as its `YYYY-MM-DD` label (`| null` for an optional source).
+   * bucket's value is typed as its `YYYY-MM-DD` (hour: `YYYY-MM-DDTHH:00`) label
+   * (`| null` for an optional source).
    * Gap-fill between labels with `nextBucketLabel` (re-exported here).
    */
   aggregate<const Q extends AggregateQuery$1<Own<T>>>(query: Q & ValidGroupBy$1<Own<T>, Q>): Promise<Q["controls"]["$select"] extends readonly (string | AggregateExpr | BucketExpr$1)[] ? AggregateResult$1<Own<T>, Q["controls"]["$select"]>[] : Record<string, unknown>[]>;
@@ -166,11 +167,48 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    * `{ ids?, input? }` — `ids` carries `id` (object or array per level),
    * `input` carries the form payload.
    *
+   * **Delegated actions** (since 0.1.147). An action another controller owns
+   * (`owner`, e.g. a view listing its source table's actions) may carry
+   * `idMap`: each `id` is then a row (or identifier) of THIS controller and
+   * is mapped to the owner's identification — `{ [ownerField]:
+   * row[path] }` — before it is sent to `value` (the owner's route). A
+   * missing path throws `TypeError`. See {@link actionIdentifier}.
+   *
    * @typeParam R Caller-asserted return shape from the action handler. The
    *              server returns whatever the handler emits (commonly
    *              `{ message?: string, ... }`); the client cannot validate.
    */
   action<R = unknown>(name: string, id?: Partial<Own<T>> | Partial<Own<T>>[], input?: unknown): Promise<R>;
+  /**
+   * Runs a `'rows'` action on every row matching a query (since 0.1.147) —
+   * the action's `/meta` entry must carry `queryTarget`. POSTs
+   * `{ query: { q, exclude?, expectCount?, maxRows? }, input? }` to
+   * `queryTarget.url` (a delegated action: the view resolves the rows and
+   * runs the owner's action in batches) or `value`. `q` is the `/query`
+   * string of `target.filter` / `search` / `index`.
+   *
+   * The server answers what the handler returns — for a delegated action
+   * (and a handler returning `target.summary()`) a
+   * {@link TDbActionTargetSummary}. Refusals arrive as
+   * {@link ActionTargetError}: `TARGET_TOO_LARGE` (`cap`), `TARGET_CHANGED`
+   * (`matched` differs from `expectCount`), `TARGET_INVALID`. Throws
+   * {@link ActionUnsupportedError} when the action takes no query target.
+   *
+   * @since 0.1.147
+   */
+  actionOnQuery<R = TDbActionTargetSummary$1>(name: string, target: TDbQueryTarget<T>, input?: unknown): Promise<R>;
+  /**
+   * How many rows {@link actionOnQuery} would target right now (a dry run:
+   * the handler does not run) — pass the answer as `expectCount` to make the
+   * real run fail with `TARGET_CHANGED` if the set changed in between.
+   *
+   * @since 0.1.147
+   */
+  countActionTarget(name: string, target: TDbQueryTarget<T>): Promise<{
+    matched: number;
+  }>;
+  private _queryTargetAction;
+  private _postQueryTarget;
   /**
    * `GET /meta/actions/:id` or `GET /meta/actions?k1=v1&k2=v2` — the
    * row-level actions the caller may run on one row right now, and the
@@ -224,6 +262,22 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
   private _requestUrl;
   private _send;
 }
+/**
+ * The identifier `action` takes for one row (or identifier) of the
+ * controller whose `/meta` listed it (since 0.1.147):
+ *
+ * - a delegated action with `idMap` → the owner's identification,
+ *   `{ [ownerField]: rowOrId[path] }` (dot paths allowed); a missing value
+ *   throws `TypeError` naming the action and the path;
+ * - any other action → `rowOrId`'s `preferredId` fields when it carries them
+ *   all, else `rowOrId` itself (already an identifier).
+ *
+ * UIs build `ids` from loaded rows with it; `Client.action()` applies the
+ * `idMap` mapping itself.
+ *
+ * @since 0.1.147
+ */
+declare function actionIdentifier(action: Pick<TDbActionInfo$1, "name" | "idMap">, rowOrId: Record<string, unknown>, preferredId: readonly string[]): Record<string, unknown>;
 /**
  * Render a single identifier field for substitution into a navigate-URL
  * template or human-readable string. `null` / `undefined` collapse to `""`
@@ -318,6 +372,34 @@ declare class ActionDisabledError extends ClientError {
    */
   get reasons(): (string | null)[] | undefined;
 }
+/**
+ * Wire-body shape for `ActionTargetError` responses (since 0.1.147): a
+ * query target the server refused — `code` says why.
+ */
+interface ActionTargetErrorBody extends ServerError {
+  name: "ActionTargetError";
+  code: "TARGET_INVALID" | "TARGET_TOO_LARGE" | "TARGET_CHANGED";
+  action: string;
+  /** `TARGET_CHANGED`: the current match count. */
+  matched?: number;
+  /** `TARGET_TOO_LARGE`: the most rows one request may target. */
+  cap?: number;
+}
+/**
+ * Typed marker thrown by `Client` when a query-targeted action request is
+ * refused (body `name === 'ActionTargetError'`): `TARGET_INVALID` (400),
+ * `TARGET_TOO_LARGE` (400, `cap`) or `TARGET_CHANGED` (409, `matched` — the
+ * rows the query matches now; re-confirm and retry with that count).
+ *
+ * @since 0.1.147
+ */
+declare class ActionTargetError extends ClientError {
+  name: string;
+  get code(): ActionTargetErrorBody["code"];
+  get action(): string;
+  get matched(): number | undefined;
+  get cap(): number | undefined;
+}
 /**
  * Wire-body shape for 409 OCC `version_mismatch` responses. Extends the base
  * `ServerError` envelope with a `kind` discriminator and the row's current
@@ -382,4 +464,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, type BucketExpr, 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 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 TDbAvailableActions, type TDbDeleteResult, type TDbInsertManyResult, type TDbInsertResult, type TDbUpdateResult, type TSerializedAnnotatedType, TransportError, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidGroupBy, type ValidatorMode, VersionMismatchError, type VersionMismatchErrorBody, type WeekStart, 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, 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 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 };

package/dist/index.d.mts

@@ -1,7 +1,7 @@
-import { A as TDbDeleteResult, C as OwnOf, D as RowOf, E as RelationInfo, F as Uniquery, I as UniqueryControls, L as ValidGroupBy, M as TDbInsertResult, N as TDbUpdateResult, O as SearchIndexInfo, P as TypedWithRelation, R as WeekStart, S as NavOf, T as PatchOf, _ as DbRow, a as ValidatorMode, b as IdOf, c as AggregateResult, d as BucketUnit, f as CalendarBucketLabel, g as DbPatch, h as DataOf, j as TDbInsertManyResult, k as ServerError, 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 FieldMeta, w as PageResult, x as MetaResponse, y as FilterExpr } from "./validator-CIm1ZCS5.mjs";
+import { A as TDbDeleteResult, C as OwnOf, D as RowOf, E as RelationInfo, F as TypedWithRelation, I as Uniquery, L as UniqueryControls, M as TDbInsertResult, N as TDbQueryTarget, O as SearchIndexInfo, P as TDbUpdateResult, R as ValidGroupBy, S as NavOf, T as PatchOf, _ as DbRow, a as ValidatorMode, b as IdOf, c as AggregateResult, d as BucketUnit, f as CalendarBucketLabel, g as DbPatch, h as DataOf, j as TDbInsertManyResult, k as ServerError, 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 FieldMeta, w as PageResult, x as MetaResponse, y as FilterExpr, z as WeekStart } from "./validator-xkEq4h0X.mjs";
 import { TAtscriptAnnotatedType, TSerializedAnnotatedType } from "@atscript/typescript/utils";
-import { AggregateExpr, AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, BucketExpr as BucketExpr$1, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1, ValidGroupBy as ValidGroupBy$1, bucketStartInstant, nextBucketLabel } from "@uniqu/core";
-import { TCrudOp, TCrudPermissions, TDbActionInfo, TDbActionIntent, TDbActionLevel, TDbActionProcessor, TDbAvailableActions, TDbAvailableActions as TDbAvailableActions$1, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1 } from "@atscript/db";
+import { AggregateExpr, AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, BucketExpr as BucketExpr$1, BucketSeriesOptions, NextBucketOptions, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$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, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1 } from "@atscript/db";
 
 //#region src/client.d.ts
 type Own<T> = OwnOf<T>;
@@ -59,7 +59,8 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    *
    * `$select` may carry calendar buckets (`{ $bucket, $field, $tz?, $weekStart?, $as? }`);
    * a `$groupBy` entry must be a dimension or a bucket alias (`ValidGroupBy`), and a
-   * bucket's value is typed as its `YYYY-MM-DD` label (`| null` for an optional source).
+   * bucket's value is typed as its `YYYY-MM-DD` (hour: `YYYY-MM-DDTHH:00`) label
+   * (`| null` for an optional source).
    * Gap-fill between labels with `nextBucketLabel` (re-exported here).
    */
   aggregate<const Q extends AggregateQuery$1<Own<T>>>(query: Q & ValidGroupBy$1<Own<T>, Q>): Promise<Q["controls"]["$select"] extends readonly (string | AggregateExpr | BucketExpr$1)[] ? AggregateResult$1<Own<T>, Q["controls"]["$select"]>[] : Record<string, unknown>[]>;
@@ -166,11 +167,48 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    * `{ ids?, input? }` — `ids` carries `id` (object or array per level),
    * `input` carries the form payload.
    *
+   * **Delegated actions** (since 0.1.147). An action another controller owns
+   * (`owner`, e.g. a view listing its source table's actions) may carry
+   * `idMap`: each `id` is then a row (or identifier) of THIS controller and
+   * is mapped to the owner's identification — `{ [ownerField]:
+   * row[path] }` — before it is sent to `value` (the owner's route). A
+   * missing path throws `TypeError`. See {@link actionIdentifier}.
+   *
    * @typeParam R Caller-asserted return shape from the action handler. The
    *              server returns whatever the handler emits (commonly
    *              `{ message?: string, ... }`); the client cannot validate.
    */
   action<R = unknown>(name: string, id?: Partial<Own<T>> | Partial<Own<T>>[], input?: unknown): Promise<R>;
+  /**
+   * Runs a `'rows'` action on every row matching a query (since 0.1.147) —
+   * the action's `/meta` entry must carry `queryTarget`. POSTs
+   * `{ query: { q, exclude?, expectCount?, maxRows? }, input? }` to
+   * `queryTarget.url` (a delegated action: the view resolves the rows and
+   * runs the owner's action in batches) or `value`. `q` is the `/query`
+   * string of `target.filter` / `search` / `index`.
+   *
+   * The server answers what the handler returns — for a delegated action
+   * (and a handler returning `target.summary()`) a
+   * {@link TDbActionTargetSummary}. Refusals arrive as
+   * {@link ActionTargetError}: `TARGET_TOO_LARGE` (`cap`), `TARGET_CHANGED`
+   * (`matched` differs from `expectCount`), `TARGET_INVALID`. Throws
+   * {@link ActionUnsupportedError} when the action takes no query target.
+   *
+   * @since 0.1.147
+   */
+  actionOnQuery<R = TDbActionTargetSummary$1>(name: string, target: TDbQueryTarget<T>, input?: unknown): Promise<R>;
+  /**
+   * How many rows {@link actionOnQuery} would target right now (a dry run:
+   * the handler does not run) — pass the answer as `expectCount` to make the
+   * real run fail with `TARGET_CHANGED` if the set changed in between.
+   *
+   * @since 0.1.147
+   */
+  countActionTarget(name: string, target: TDbQueryTarget<T>): Promise<{
+    matched: number;
+  }>;
+  private _queryTargetAction;
+  private _postQueryTarget;
   /**
    * `GET /meta/actions/:id` or `GET /meta/actions?k1=v1&k2=v2` — the
    * row-level actions the caller may run on one row right now, and the
@@ -224,6 +262,22 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
   private _requestUrl;
   private _send;
 }
+/**
+ * The identifier `action` takes for one row (or identifier) of the
+ * controller whose `/meta` listed it (since 0.1.147):
+ *
+ * - a delegated action with `idMap` → the owner's identification,
+ *   `{ [ownerField]: rowOrId[path] }` (dot paths allowed); a missing value
+ *   throws `TypeError` naming the action and the path;
+ * - any other action → `rowOrId`'s `preferredId` fields when it carries them
+ *   all, else `rowOrId` itself (already an identifier).
+ *
+ * UIs build `ids` from loaded rows with it; `Client.action()` applies the
+ * `idMap` mapping itself.
+ *
+ * @since 0.1.147
+ */
+declare function actionIdentifier(action: Pick<TDbActionInfo$1, "name" | "idMap">, rowOrId: Record<string, unknown>, preferredId: readonly string[]): Record<string, unknown>;
 /**
  * Render a single identifier field for substitution into a navigate-URL
  * template or human-readable string. `null` / `undefined` collapse to `""`
@@ -318,6 +372,34 @@ declare class ActionDisabledError extends ClientError {
    */
   get reasons(): (string | null)[] | undefined;
 }
+/**
+ * Wire-body shape for `ActionTargetError` responses (since 0.1.147): a
+ * query target the server refused — `code` says why.
+ */
+interface ActionTargetErrorBody extends ServerError {
+  name: "ActionTargetError";
+  code: "TARGET_INVALID" | "TARGET_TOO_LARGE" | "TARGET_CHANGED";
+  action: string;
+  /** `TARGET_CHANGED`: the current match count. */
+  matched?: number;
+  /** `TARGET_TOO_LARGE`: the most rows one request may target. */
+  cap?: number;
+}
+/**
+ * Typed marker thrown by `Client` when a query-targeted action request is
+ * refused (body `name === 'ActionTargetError'`): `TARGET_INVALID` (400),
+ * `TARGET_TOO_LARGE` (400, `cap`) or `TARGET_CHANGED` (409, `matched` — the
+ * rows the query matches now; re-confirm and retry with that count).
+ *
+ * @since 0.1.147
+ */
+declare class ActionTargetError extends ClientError {
+  name: string;
+  get code(): ActionTargetErrorBody["code"];
+  get action(): string;
+  get matched(): number | undefined;
+  get cap(): number | undefined;
+}
 /**
  * Wire-body shape for 409 OCC `version_mismatch` responses. Extends the base
  * `ServerError` envelope with a `kind` discriminator and the row's current
@@ -382,4 +464,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, type BucketExpr, 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 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 TDbAvailableActions, type TDbDeleteResult, type TDbInsertManyResult, type TDbInsertResult, type TDbUpdateResult, type TSerializedAnnotatedType, TransportError, type TypedWithRelation, type Uniquery, type UniqueryControls, type ValidGroupBy, type ValidatorMode, VersionMismatchError, type VersionMismatchErrorBody, type WeekStart, 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, 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 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 };

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { buildUrl } from "@uniqu/url/builder";
 import { deserializeAnnotatedType } from "@atscript/typescript/utils";
-import { bucketStartInstant, nextBucketLabel } from "@uniqu/core";
+import { bucketSeries, bucketStartInstant, nextBucketLabel } from "@uniqu/core";
 //#region src/client-error.ts
 /**
 * Error thrown by `Client` when the server responds with a non-2xx status code.
@@ -64,6 +64,29 @@ var ActionDisabledError = class extends ClientError {
 	}
 };
 /**
+* Typed marker thrown by `Client` when a query-targeted action request is
+* refused (body `name === 'ActionTargetError'`): `TARGET_INVALID` (400),
+* `TARGET_TOO_LARGE` (400, `cap`) or `TARGET_CHANGED` (409, `matched` — the
+* rows the query matches now; re-confirm and retry with that count).
+*
+* @since 0.1.147
+*/
+var ActionTargetError = class extends ClientError {
+	name = "ActionTargetError";
+	get code() {
+		return this.body.code;
+	}
+	get action() {
+		return this.body.action;
+	}
+	get matched() {
+		return this.body.matched;
+	}
+	get cap() {
+		return this.body.cap;
+	}
+};
+/**
 * Typed marker thrown by `Client._send` when the server response body's
 * `kind === 'version_mismatch'`. The transport / status / base body are
 * identical to a generic `ClientError`; this subclass adds a typed
@@ -185,7 +208,8 @@ var Client = class {
 	*
 	* `$select` may carry calendar buckets (`{ $bucket, $field, $tz?, $weekStart?, $as? }`);
 	* a `$groupBy` entry must be a dimension or a bucket alias (`ValidGroupBy`), and a
-	* bucket's value is typed as its `YYYY-MM-DD` label (`| null` for an optional source).
+	* bucket's value is typed as its `YYYY-MM-DD` (hour: `YYYY-MM-DDTHH:00`) label
+	* (`| null` for an optional source).
 	* Gap-fill between labels with `nextBucketLabel` (re-exported here).
 	*/
 	async aggregate(query) {
@@ -322,6 +346,13 @@ var Client = class {
 	* `{ ids?, input? }` — `ids` carries `id` (object or array per level),
 	* `input` carries the form payload.
 	*
+	* **Delegated actions** (since 0.1.147). An action another controller owns
+	* (`owner`, e.g. a view listing its source table's actions) may carry
+	* `idMap`: each `id` is then a row (or identifier) of THIS controller and
+	* is mapped to the owner's identification — `{ [ownerField]:
+	* row[path] }` — before it is sent to `value` (the owner's route). A
+	* missing path throws `TypeError`. See {@link actionIdentifier}.
+	*
 	* @typeParam R Caller-asserted return shape from the action handler. The
 	*              server returns whatever the handler emits (commonly
 	*              `{ message?: string, ... }`); the client cannot validate.
@@ -331,15 +362,65 @@ var Client = class {
 		const action = meta.actions.find((a) => a.name === name);
 		if (!action) throw new ActionNotFoundError(name);
 		if (action.processor === "custom") throw new ActionUnsupportedError(name, "custom", `Action "${name}" has processor "custom" — applications must dispatch custom actions themselves; the client cannot.`);
+		const mapped = action.idMap ? mapDelegatedIds(action, id) : id;
 		if (action.processor === "navigate") {
-			const url = this._interpolateNavigateUrl(action, id, meta.preferredId);
+			const order = action.idMap ? Object.keys(action.idMap) : meta.preferredId;
+			const url = this._interpolateNavigateUrl(action, mapped, order);
 			await this._dispatchNavigate(action, url);
 			return;
 		}
-		const body = this._buildActionBody(action, id, input);
+		const body = this._buildActionBody(action, mapped, input);
 		return this._postAction(action, body);
 	}
 	/**
+	* Runs a `'rows'` action on every row matching a query (since 0.1.147) —
+	* the action's `/meta` entry must carry `queryTarget`. POSTs
+	* `{ query: { q, exclude?, expectCount?, maxRows? }, input? }` to
+	* `queryTarget.url` (a delegated action: the view resolves the rows and
+	* runs the owner's action in batches) or `value`. `q` is the `/query`
+	* string of `target.filter` / `search` / `index`.
+	*
+	* The server answers what the handler returns — for a delegated action
+	* (and a handler returning `target.summary()`) a
+	* {@link TDbActionTargetSummary}. Refusals arrive as
+	* {@link ActionTargetError}: `TARGET_TOO_LARGE` (`cap`), `TARGET_CHANGED`
+	* (`matched` differs from `expectCount`), `TARGET_INVALID`. Throws
+	* {@link ActionUnsupportedError} when the action takes no query target.
+	*
+	* @since 0.1.147
+	*/
+	async actionOnQuery(name, target, input) {
+		const action = await this._queryTargetAction(name);
+		const body = { query: queryTargetBody(target) };
+		if (input !== void 0) body.input = input;
+		return this._postQueryTarget(action, body);
+	}
+	/**
+	* How many rows {@link actionOnQuery} would target right now (a dry run:
+	* the handler does not run) — pass the answer as `expectCount` to make the
+	* real run fail with `TARGET_CHANGED` if the set changed in between.
+	*
+	* @since 0.1.147
+	*/
+	async countActionTarget(name, target) {
+		const action = await this._queryTargetAction(name);
+		const query = {
+			...queryTargetBody(target),
+			dryRun: true
+		};
+		return this._postQueryTarget(action, { query });
+	}
+	async _queryTargetAction(name) {
+		const action = (await this.meta()).actions.find((a) => a.name === name);
+		if (!action) throw new ActionNotFoundError(name);
+		if (!action.queryTarget || action.processor !== "backend") throw new ActionUnsupportedError(name, action.processor, `Action "${name}" does not accept a query target (no \`queryTarget\` in /meta).`);
+		return action;
+	}
+	_postQueryTarget(action, body) {
+		const path = action.queryTarget?.url ?? action.value;
+		return this._requestUrl("POST", `${this._baseUrl}${path}`, body, true);
+	}
+	/**
 	* `GET /meta/actions/:id` or `GET /meta/actions?k1=v1&k2=v2` — the
 	* row-level actions the caller may run on one row right now, and the
 	* reasons of those disabled with one: `{ actions, disabledReasons? }`.
@@ -518,6 +599,7 @@ var Client = class {
 				};
 			}
 			if (errorBody.name === "ActionDisabledError") throw new ActionDisabledError(res.status, errorBody);
+			if (errorBody.name === "ActionTargetError") throw new ActionTargetError(res.status, errorBody);
 			if (errorBody.kind === "version_mismatch") throw new VersionMismatchError(res.status, errorBody);
 			throw new ClientError(res.status, errorBody);
 		}
@@ -539,6 +621,60 @@ function describeCause(cause) {
 	if (cause instanceof Error) return cause.message || cause.name;
 	return String(cause);
 }
+/** The value at a dot `path` of `row`. */
+function valueAt(row, path) {
+	if (!path.includes(".") || Object.hasOwn(row, path)) return row[path];
+	let v = row;
+	for (const part of path.split(".")) v = v?.[part];
+	return v;
+}
+/**
+* The identifier `action` takes for one row (or identifier) of the
+* controller whose `/meta` listed it (since 0.1.147):
+*
+* - a delegated action with `idMap` → the owner's identification,
+*   `{ [ownerField]: rowOrId[path] }` (dot paths allowed); a missing value
+*   throws `TypeError` naming the action and the path;
+* - any other action → `rowOrId`'s `preferredId` fields when it carries them
+*   all, else `rowOrId` itself (already an identifier).
+*
+* UIs build `ids` from loaded rows with it; `Client.action()` applies the
+* `idMap` mapping itself.
+*
+* @since 0.1.147
+*/
+function actionIdentifier(action, rowOrId, preferredId) {
+	if (action.idMap) {
+		const out = {};
+		for (const [field, path] of Object.entries(action.idMap)) {
+			const value = valueAt(rowOrId, path);
+			if (value === void 0 || value === null) throw new TypeError(`client.action("${action.name}"): the identifier has no "${path}" — needed for the owner's "${field}".`);
+			out[field] = value;
+		}
+		return out;
+	}
+	if (preferredId.length > 0 && preferredId.every((f) => rowOrId[f] !== void 0)) return Object.fromEntries(preferredId.map((f) => [f, rowOrId[f]]));
+	return rowOrId;
+}
+/** `action()`'s `id` argument through a delegated action's `idMap` (shape errors are left to the body builder). */
+function mapDelegatedIds(action, id) {
+	const map = (one) => one !== null && typeof one === "object" && !Array.isArray(one) ? actionIdentifier(action, one, []) : one;
+	return Array.isArray(id) ? id.map(map) : map(id);
+}
+/** The wire `query` of a {@link TDbQueryTarget}. */
+function queryTargetBody(target) {
+	const controls = {};
+	if (target.search !== void 0) controls.$search = target.search;
+	if (target.index !== void 0) controls.$index = target.index;
+	const out = { q: buildUrl({
+		filter: target.filter ?? {},
+		controls
+	}) };
+	if (target.exclude?.length) out.exclude = target.exclude;
+	if (target.expectCount !== void 0) out.expectCount = target.expectCount;
+	if (target.maxRows !== void 0) out.maxRows = target.maxRows;
+	return out;
+}
 /**
 * Render a single identifier field for substitution into a navigate-URL
 * template or human-readable string. `null` / `undefined` collapse to `""`
@@ -575,4 +711,4 @@ function describeShape(value) {
 	return typeof value;
 }
 //#endregion
-export { ActionDisabledError, ActionNotFoundError, ActionUnsupportedError, Client, ClientError, TransportError, VersionMismatchError, bucketStartInstant, encodeNavigateId, formatIdentifier, formatIdentifierField, nextBucketLabel };
+export { ActionDisabledError, ActionNotFoundError, ActionTargetError, ActionUnsupportedError, Client, ClientError, TransportError, VersionMismatchError, actionIdentifier, bucketSeries, bucketStartInstant, encodeNavigateId, formatIdentifier, formatIdentifierField, nextBucketLabel };

package/dist/{validator-810-rhnQ.d.cts → validator-DVha6LOQ.d.cts}

@@ -132,6 +132,28 @@ type ClientResponse<T, Q> = DbResponse<DataOf<T>, NavOf<T>, Q> & {
    */
   $disabledReasons?: Record<string, string>;
 };
+/**
+ * "Every row matching this query" — the target of
+ * `Client.actionOnQuery()` / `countActionTarget()`, for a `'rows'` action
+ * whose `/meta` entry carries `queryTarget`. The same filter / search /
+ * index the user's `/query` used; the server resolves it under the caller's
+ * read scope and the action's own gate.
+ *
+ * @since 0.1.147
+ */
+interface TDbQueryTarget<T = AtscriptClientShape> {
+  filter?: Uniquery$1<OwnOf<T>, NavOf<T>>["filter"];
+  /** `$search` term. */
+  search?: string;
+  /** `$index` — the search index `search` uses. */
+  index?: string;
+  /** Identifiers to leave out (any identification of the controller the request goes to). */
+  exclude?: Record<string, unknown>[];
+  /** Fail with 409 `TARGET_CHANGED` when the target no longer matches exactly this many rows. */
+  expectCount?: number;
+  /** Client-side cap (never above the action's `queryTarget.maxRows`). */
+  maxRows?: number;
+}
 //#endregion
 //#region src/validator.d.ts
 /** Options for {@link ClientValidator} / {@link createClientValidator}. */
@@ -214,4 +236,4 @@ declare class ClientValidationError extends Error {
  */
 declare function createClientValidator(meta: MetaResponse, opts?: ClientValidatorOptions): ClientValidator;
 //#endregion
-export { TDbDeleteResult$1 as A, OwnOf as C, RowOf as D, RelationInfo as E, Uniquery$1 as F, UniqueryControls$1 as I, ValidGroupBy$1 as L, TDbInsertResult$1 as M, TDbUpdateResult$1 as N, SearchIndexInfo as O, TypedWithRelation as P, WeekStart as R, NavOf as S, PatchOf as T, DbRow as _, ValidatorMode$1 as a, IdOf as b, AggregateResult$1 as c, BucketUnit as d, CalendarBucketLabel as f, DbPatch as g, DataOf as h, DbValidationContext as i, TDbInsertManyResult$1 as j, ServerError 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, FieldMeta as v, PageResult as w, MetaResponse as x, FilterExpr as y };
+export { TDbDeleteResult$1 as A, OwnOf as C, RowOf as D, RelationInfo as E, TypedWithRelation as F, Uniquery$1 as I, UniqueryControls$1 as L, TDbInsertResult$1 as M, TDbQueryTarget as N, SearchIndexInfo as O, TDbUpdateResult$1 as P, ValidGroupBy$1 as R, NavOf as S, PatchOf as T, DbRow as _, ValidatorMode$1 as a, IdOf as b, AggregateResult$1 as c, BucketUnit as d, CalendarBucketLabel as f, DbPatch as g, DataOf as h, DbValidationContext as i, TDbInsertManyResult$1 as j, ServerError 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, FieldMeta as v, PageResult as w, MetaResponse as x, FilterExpr as y, WeekStart as z };

package/dist/{validator-CIm1ZCS5.d.mts → validator-xkEq4h0X.d.mts}

@@ -132,6 +132,28 @@ type ClientResponse<T, Q> = DbResponse<DataOf<T>, NavOf<T>, Q> & {
    */
   $disabledReasons?: Record<string, string>;
 };
+/**
+ * "Every row matching this query" — the target of
+ * `Client.actionOnQuery()` / `countActionTarget()`, for a `'rows'` action
+ * whose `/meta` entry carries `queryTarget`. The same filter / search /
+ * index the user's `/query` used; the server resolves it under the caller's
+ * read scope and the action's own gate.
+ *
+ * @since 0.1.147
+ */
+interface TDbQueryTarget<T = AtscriptClientShape> {
+  filter?: Uniquery$1<OwnOf<T>, NavOf<T>>["filter"];
+  /** `$search` term. */
+  search?: string;
+  /** `$index` — the search index `search` uses. */
+  index?: string;
+  /** Identifiers to leave out (any identification of the controller the request goes to). */
+  exclude?: Record<string, unknown>[];
+  /** Fail with 409 `TARGET_CHANGED` when the target no longer matches exactly this many rows. */
+  expectCount?: number;
+  /** Client-side cap (never above the action's `queryTarget.maxRows`). */
+  maxRows?: number;
+}
 //#endregion
 //#region src/validator.d.ts
 /** Options for {@link ClientValidator} / {@link createClientValidator}. */
@@ -214,4 +236,4 @@ declare class ClientValidationError extends Error {
  */
 declare function createClientValidator(meta: MetaResponse, opts?: ClientValidatorOptions): ClientValidator;
 //#endregion
-export { TDbDeleteResult$1 as A, OwnOf as C, RowOf as D, RelationInfo as E, Uniquery$1 as F, UniqueryControls$1 as I, ValidGroupBy$1 as L, TDbInsertResult$1 as M, TDbUpdateResult$1 as N, SearchIndexInfo as O, TypedWithRelation as P, WeekStart as R, NavOf as S, PatchOf as T, DbRow as _, ValidatorMode$1 as a, IdOf as b, AggregateResult$1 as c, BucketUnit as d, CalendarBucketLabel as f, DbPatch as g, DataOf as h, DbValidationContext as i, TDbInsertManyResult$1 as j, ServerError 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, FieldMeta as v, PageResult as w, MetaResponse as x, FilterExpr as y };
+export { TDbDeleteResult$1 as A, OwnOf as C, RowOf as D, RelationInfo as E, TypedWithRelation as F, Uniquery$1 as I, UniqueryControls$1 as L, TDbInsertResult$1 as M, TDbQueryTarget as N, SearchIndexInfo as O, TDbUpdateResult$1 as P, ValidGroupBy$1 as R, NavOf as S, PatchOf as T, DbRow as _, ValidatorMode$1 as a, IdOf as b, AggregateResult$1 as c, BucketUnit as d, CalendarBucketLabel as f, DbPatch as g, DataOf as h, DbValidationContext as i, TDbInsertManyResult$1 as j, ServerError 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, FieldMeta as v, PageResult as w, MetaResponse as x, FilterExpr as y, WeekStart 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-810-rhnQ.cjs";
+import { a as ValidatorMode, i as DbValidationContext, n as ClientValidator, o as createClientValidator, r as ClientValidatorOptions, t as ClientValidationError } from "./validator-DVha6LOQ.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-CIm1ZCS5.mjs";
+import { a as ValidatorMode, i as DbValidationContext, n as ClientValidator, o as createClientValidator, r as ClientValidatorOptions, t as ClientValidationError } from "./validator-xkEq4h0X.mjs";
 export { ClientValidationError, ClientValidator, ClientValidatorOptions, type DbValidationContext, type ValidatorMode, createClientValidator };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/db-client",
-  "version": "0.1.145",
+  "version": "0.1.147",
   "description": "Browser-compatible HTTP client for @atscript/moost-db REST endpoints.",
   "keywords": [
     "atscript",
@@ -43,18 +43,18 @@
     "access": "public"
   },
   "dependencies": {
-    "@uniqu/core": "^0.1.11",
-    "@uniqu/url": "^0.1.11"
+    "@uniqu/core": "^0.1.12",
+    "@uniqu/url": "^0.1.12"
   },
   "devDependencies": {
-    "@atscript/core": "^0.1.97",
-    "@atscript/typescript": "^0.1.97",
-    "unplugin-atscript": "^0.1.97",
-    "@atscript/db": "0.1.145"
+    "@atscript/core": "^0.1.99",
+    "@atscript/typescript": "^0.1.99",
+    "unplugin-atscript": "^0.1.99",
+    "@atscript/db": "0.1.147"
   },
   "peerDependencies": {
     "@atscript/db": "^0.1.44",
-    "@atscript/typescript": "^0.1.97"
+    "@atscript/typescript": "^0.1.99"
   },
   "scripts": {
     "postinstall": "asc -f dts",