@atscript/db-client 0.1.147 → 0.1.148

package/dist/index.cjs

@@ -166,6 +166,17 @@ var ActionUnsupportedError = class extends Error {
 * const all = await users.query()
 * const page = await users.pages({ filter: { active: true } }, 1, 20)
 * ```
+*
+* `D` (since 0.1.148) types the display-only fields the controller declares
+* with `@DbDecorations`: `$select` of the read methods accepts their keys and
+* rows carry them as optional properties. Filter and sort stay over `T`'s own
+* fields — a decoration is never filterable or sortable.
+*
+* ```typescript
+* const tickets = new Client<typeof Ticket, TicketDecorations>('/api/tickets')
+* const rows = await tickets.query({ controls: { $select: ['title', 'ownerName'] } })
+* rows[0].ownerName // string | undefined
+* ```
 */
 var Client = class {
 	_path;
@@ -212,6 +223,12 @@ var Client = class {
 	* 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).
+	*
+	* Arithmetic (since 0.1.148): `{ $fn: 'sum', $expr, $as }` aggregates a per-row
+	* expression over numeric fields; `{ $expr, $as }` computes over aliases of other
+	* numeric entries or numeric `$groupBy` fields (`number | null`). `first` / `last`
+	* read a representative row ordered by `$rowOrder`. The URL forms are `expr(a/b):x`,
+	* `sum(a*b):x`, `first(f):x` and `$rowOrder=f,-id`.
 	*/
 	async aggregate(query) {
 		return this._get("query", query);
@@ -274,8 +291,9 @@ var Client = class {
 		const controlStr = query?.controls ? (0, _uniqu_url_builder.buildUrl)({ controls: query.controls }) : "";
 		return this._getOrNull(this._idUrl("one", id, controlStr));
 	}
-	async insert(data) {
-		return this._request("POST", "", await this._prepareWrite(data, "insert"));
+	async insert(data, opts) {
+		const query = opts?.onConflict === "ignore" ? "?$onConflict=ignore" : "";
+		return this._request("POST", query, await this._prepareWrite(data, "insert"));
 	}
 	/**
 	* `PATCH /` — partial update one or many records by primary key.

package/dist/index.d.cts

@@ -1,13 +1,15 @@
-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 { 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 { 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, 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, TDbInsertIgnoreResult as TDbInsertIgnoreResult$1, TDbInsertManyIgnoreResult as TDbInsertManyIgnoreResult$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>;
 type Nav<T> = NavOf<T>;
 type Id<T> = IdOf<T>;
 type Response<T, Q> = ClientResponse<T, Q>;
+/** A read row: the response over the own fields plus the declared decorations `D`, each optional. */
+type DecoratedRow<T, Q, D> = Response<T, Q> & Partial<D>;
 /**
  * HTTP client for moost-db REST endpoints.
  *
@@ -28,8 +30,19 @@ type Response<T, Q> = ClientResponse<T, Q>;
  * const all = await users.query()
  * const page = await users.pages({ filter: { active: true } }, 1, 20)
  * ```
+ *
+ * `D` (since 0.1.148) types the display-only fields the controller declares
+ * with `@DbDecorations`: `$select` of the read methods accepts their keys and
+ * rows carry them as optional properties. Filter and sort stay over `T`'s own
+ * fields — a decoration is never filterable or sortable.
+ *
+ * ```typescript
+ * const tickets = new Client<typeof Ticket, TicketDecorations>('/api/tickets')
+ * const rows = await tickets.query({ controls: { $select: ['title', 'ownerName'] } })
+ * rows[0].ownerName // string | undefined
+ * ```
  */
-declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
+declare class Client<T extends AtscriptClientShape = AtscriptClientShape, D extends object = Record<never, never>> {
   private readonly _path;
   private readonly _baseUrl;
   private readonly _fetch;
@@ -47,7 +60,7 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    * The response type narrows by the literal `$with` array in `query` —
    * relations not listed in `$with` are stripped from the row type.
    */
-  query<Q extends Uniquery$1<Own<T>, Nav<T>> = Uniquery$1<Own<T>, Nav<T>>>(query?: Q): Promise<Response<T, Q>[]>;
+  query<Q extends DecoratedQuery<T, D> = DecoratedQuery<T, D>>(query?: Q): Promise<DecoratedRow<T, Q, D>[]>;
   /**
    * `GET /query` with `$count: true` — returns record count.
    */
@@ -62,15 +75,21 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    * 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).
+   *
+   * Arithmetic (since 0.1.148): `{ $fn: 'sum', $expr, $as }` aggregates a per-row
+   * expression over numeric fields; `{ $expr, $as }` computes over aliases of other
+   * numeric entries or numeric `$groupBy` fields (`number | null`). `first` / `last`
+   * read a representative row ordered by `$rowOrder`. The URL forms are `expr(a/b):x`,
+   * `sum(a*b):x`, `first(f):x` and `$rowOrder=f,-id`.
    */
-  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>[]>;
+  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 | AggregateOfExpr | SelectArithExpr)[] ? AggregateResult$1<Own<T>, Q["controls"]["$select"]>[] : Record<string, unknown>[]>;
   /**
    * `GET /pages` — paginated query with typed filter and relations.
    *
    * Response rows narrow by the literal `$with` array — same algebra as
    * {@link query}.
    */
-  pages<Q extends Uniquery$1<Own<T>, Nav<T>> = Uniquery$1<Own<T>, Nav<T>>>(query?: Q, page?: number, size?: number): Promise<PageResult<Response<T, Q>>>;
+  pages<Q extends DecoratedQuery<T, D> = DecoratedQuery<T, D>>(query?: Q, page?: number, size?: number): Promise<PageResult<DecoratedRow<T, Q, D>>>;
   /**
    * `GET /geo` — distance-ranked geospatial search (tables with `@db.index.geo`).
    *
@@ -80,13 +99,13 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    * in `query.controls`; filter / `$select` / `$with` / `$skip` / `$limit`
    * compose as usual.
    */
-  geoSearch<Q extends Uniquery$1<Own<T>, Nav<T>> = Uniquery$1<Own<T>, Nav<T>>>(point: [number, number], query?: Q): Promise<Array<Response<T, Q> & {
+  geoSearch<Q extends DecoratedQuery<T, D> = DecoratedQuery<T, D>>(point: [number, number], query?: Q): Promise<Array<DecoratedRow<T, Q, D> & {
     $distance: number;
   }>>;
   /**
    * `GET /geo` with `$page` / `$size` — paginated distance-ranked search.
    */
-  geoPages<Q extends Uniquery$1<Own<T>, Nav<T>> = Uniquery$1<Own<T>, Nav<T>>>(point: [number, number], query?: Q, page?: number, size?: number): Promise<PageResult<Response<T, Q> & {
+  geoPages<Q extends DecoratedQuery<T, D> = DecoratedQuery<T, D>>(point: [number, number], query?: Q, page?: number, size?: number): Promise<PageResult<DecoratedRow<T, Q, D> & {
     $distance: number;
   }>>;
   /**
@@ -96,10 +115,10 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    * `query.controls` — same algebra as {@link query}.
    */
   one<Q extends {
-    controls?: UniqueryControls$1<Own<T>, Nav<T>>;
+    controls?: DecoratedControls<T, D>;
   } = {
-    controls?: UniqueryControls$1<Own<T>, Nav<T>>;
-  }>(id: Id<T>, query?: Q): Promise<Response<T, Q> | null>;
+    controls?: DecoratedControls<T, D>;
+  }>(id: Id<T>, query?: Q): Promise<DecoratedRow<T, Q, D> | null>;
   /**
    * `POST /` — insert one record. The version column (if any) is optional —
    * the server initialises it; `$cas` is rejected (no meaning on insert).
@@ -109,6 +128,20 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    * `POST /` — insert many records.
    */
   insert(data: PatchOf<T>[]): Promise<TDbInsertManyResult$1>;
+  /**
+   * `POST /?$onConflict=ignore` — insert one record, skipping it when it
+   * collides on the primary key or a unique index (since 0.1.148).
+   */
+  insert(data: PatchOf<T>, opts: {
+    onConflict: "ignore";
+  }): Promise<TDbInsertIgnoreResult$1>;
+  /**
+   * `POST /?$onConflict=ignore` — insert many records, skipping the ones that
+   * collide; the result reports inserted and skipped input indices (since 0.1.148).
+   */
+  insert(data: PatchOf<T>[], opts: {
+    onConflict: "ignore";
+  }): Promise<TDbInsertManyIgnoreResult$1>;
   /**
    * `PATCH /` — partial update one or many records by primary key.
    *
@@ -464,4 +497,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 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, 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 };

package/dist/index.d.mts

@@ -1,13 +1,15 @@
-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 { 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 { TAtscriptAnnotatedType, TSerializedAnnotatedType } from "@atscript/typescript/utils";
-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";
+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";
 
 //#region src/client.d.ts
 type Own<T> = OwnOf<T>;
 type Nav<T> = NavOf<T>;
 type Id<T> = IdOf<T>;
 type Response<T, Q> = ClientResponse<T, Q>;
+/** A read row: the response over the own fields plus the declared decorations `D`, each optional. */
+type DecoratedRow<T, Q, D> = Response<T, Q> & Partial<D>;
 /**
  * HTTP client for moost-db REST endpoints.
  *
@@ -28,8 +30,19 @@ type Response<T, Q> = ClientResponse<T, Q>;
  * const all = await users.query()
  * const page = await users.pages({ filter: { active: true } }, 1, 20)
  * ```
+ *
+ * `D` (since 0.1.148) types the display-only fields the controller declares
+ * with `@DbDecorations`: `$select` of the read methods accepts their keys and
+ * rows carry them as optional properties. Filter and sort stay over `T`'s own
+ * fields — a decoration is never filterable or sortable.
+ *
+ * ```typescript
+ * const tickets = new Client<typeof Ticket, TicketDecorations>('/api/tickets')
+ * const rows = await tickets.query({ controls: { $select: ['title', 'ownerName'] } })
+ * rows[0].ownerName // string | undefined
+ * ```
  */
-declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
+declare class Client<T extends AtscriptClientShape = AtscriptClientShape, D extends object = Record<never, never>> {
   private readonly _path;
   private readonly _baseUrl;
   private readonly _fetch;
@@ -47,7 +60,7 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    * The response type narrows by the literal `$with` array in `query` —
    * relations not listed in `$with` are stripped from the row type.
    */
-  query<Q extends Uniquery$1<Own<T>, Nav<T>> = Uniquery$1<Own<T>, Nav<T>>>(query?: Q): Promise<Response<T, Q>[]>;
+  query<Q extends DecoratedQuery<T, D> = DecoratedQuery<T, D>>(query?: Q): Promise<DecoratedRow<T, Q, D>[]>;
   /**
    * `GET /query` with `$count: true` — returns record count.
    */
@@ -62,15 +75,21 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    * 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).
+   *
+   * Arithmetic (since 0.1.148): `{ $fn: 'sum', $expr, $as }` aggregates a per-row
+   * expression over numeric fields; `{ $expr, $as }` computes over aliases of other
+   * numeric entries or numeric `$groupBy` fields (`number | null`). `first` / `last`
+   * read a representative row ordered by `$rowOrder`. The URL forms are `expr(a/b):x`,
+   * `sum(a*b):x`, `first(f):x` and `$rowOrder=f,-id`.
    */
-  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>[]>;
+  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 | AggregateOfExpr | SelectArithExpr)[] ? AggregateResult$1<Own<T>, Q["controls"]["$select"]>[] : Record<string, unknown>[]>;
   /**
    * `GET /pages` — paginated query with typed filter and relations.
    *
    * Response rows narrow by the literal `$with` array — same algebra as
    * {@link query}.
    */
-  pages<Q extends Uniquery$1<Own<T>, Nav<T>> = Uniquery$1<Own<T>, Nav<T>>>(query?: Q, page?: number, size?: number): Promise<PageResult<Response<T, Q>>>;
+  pages<Q extends DecoratedQuery<T, D> = DecoratedQuery<T, D>>(query?: Q, page?: number, size?: number): Promise<PageResult<DecoratedRow<T, Q, D>>>;
   /**
    * `GET /geo` — distance-ranked geospatial search (tables with `@db.index.geo`).
    *
@@ -80,13 +99,13 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    * in `query.controls`; filter / `$select` / `$with` / `$skip` / `$limit`
    * compose as usual.
    */
-  geoSearch<Q extends Uniquery$1<Own<T>, Nav<T>> = Uniquery$1<Own<T>, Nav<T>>>(point: [number, number], query?: Q): Promise<Array<Response<T, Q> & {
+  geoSearch<Q extends DecoratedQuery<T, D> = DecoratedQuery<T, D>>(point: [number, number], query?: Q): Promise<Array<DecoratedRow<T, Q, D> & {
     $distance: number;
   }>>;
   /**
    * `GET /geo` with `$page` / `$size` — paginated distance-ranked search.
    */
-  geoPages<Q extends Uniquery$1<Own<T>, Nav<T>> = Uniquery$1<Own<T>, Nav<T>>>(point: [number, number], query?: Q, page?: number, size?: number): Promise<PageResult<Response<T, Q> & {
+  geoPages<Q extends DecoratedQuery<T, D> = DecoratedQuery<T, D>>(point: [number, number], query?: Q, page?: number, size?: number): Promise<PageResult<DecoratedRow<T, Q, D> & {
     $distance: number;
   }>>;
   /**
@@ -96,10 +115,10 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    * `query.controls` — same algebra as {@link query}.
    */
   one<Q extends {
-    controls?: UniqueryControls$1<Own<T>, Nav<T>>;
+    controls?: DecoratedControls<T, D>;
   } = {
-    controls?: UniqueryControls$1<Own<T>, Nav<T>>;
-  }>(id: Id<T>, query?: Q): Promise<Response<T, Q> | null>;
+    controls?: DecoratedControls<T, D>;
+  }>(id: Id<T>, query?: Q): Promise<DecoratedRow<T, Q, D> | null>;
   /**
    * `POST /` — insert one record. The version column (if any) is optional —
    * the server initialises it; `$cas` is rejected (no meaning on insert).
@@ -109,6 +128,20 @@ declare class Client<T extends AtscriptClientShape = AtscriptClientShape> {
    * `POST /` — insert many records.
    */
   insert(data: PatchOf<T>[]): Promise<TDbInsertManyResult$1>;
+  /**
+   * `POST /?$onConflict=ignore` — insert one record, skipping it when it
+   * collides on the primary key or a unique index (since 0.1.148).
+   */
+  insert(data: PatchOf<T>, opts: {
+    onConflict: "ignore";
+  }): Promise<TDbInsertIgnoreResult$1>;
+  /**
+   * `POST /?$onConflict=ignore` — insert many records, skipping the ones that
+   * collide; the result reports inserted and skipped input indices (since 0.1.148).
+   */
+  insert(data: PatchOf<T>[], opts: {
+    onConflict: "ignore";
+  }): Promise<TDbInsertManyIgnoreResult$1>;
   /**
    * `PATCH /` — partial update one or many records by primary key.
    *
@@ -464,4 +497,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 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, 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 };

package/dist/index.mjs

@@ -165,6 +165,17 @@ var ActionUnsupportedError = class extends Error {
 * const all = await users.query()
 * const page = await users.pages({ filter: { active: true } }, 1, 20)
 * ```
+*
+* `D` (since 0.1.148) types the display-only fields the controller declares
+* with `@DbDecorations`: `$select` of the read methods accepts their keys and
+* rows carry them as optional properties. Filter and sort stay over `T`'s own
+* fields — a decoration is never filterable or sortable.
+*
+* ```typescript
+* const tickets = new Client<typeof Ticket, TicketDecorations>('/api/tickets')
+* const rows = await tickets.query({ controls: { $select: ['title', 'ownerName'] } })
+* rows[0].ownerName // string | undefined
+* ```
 */
 var Client = class {
 	_path;
@@ -211,6 +222,12 @@ var Client = class {
 	* 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).
+	*
+	* Arithmetic (since 0.1.148): `{ $fn: 'sum', $expr, $as }` aggregates a per-row
+	* expression over numeric fields; `{ $expr, $as }` computes over aliases of other
+	* numeric entries or numeric `$groupBy` fields (`number | null`). `first` / `last`
+	* read a representative row ordered by `$rowOrder`. The URL forms are `expr(a/b):x`,
+	* `sum(a*b):x`, `first(f):x` and `$rowOrder=f,-id`.
 	*/
 	async aggregate(query) {
 		return this._get("query", query);
@@ -273,8 +290,9 @@ var Client = class {
 		const controlStr = query?.controls ? buildUrl({ controls: query.controls }) : "";
 		return this._getOrNull(this._idUrl("one", id, controlStr));
 	}
-	async insert(data) {
-		return this._request("POST", "", await this._prepareWrite(data, "insert"));
+	async insert(data, opts) {
+		const query = opts?.onConflict === "ignore" ? "?$onConflict=ignore" : "";
+		return this._request("POST", query, await this._prepareWrite(data, "insert"));
 	}
 	/**
 	* `PATCH /` — partial update one or many records by primary key.

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

@@ -1,7 +1,7 @@
-import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, BucketExpr as BucketExpr$1, BucketUnit, CalendarBucketLabel, FilterExpr, TypedWithRelation, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1, ValidGroupBy as ValidGroupBy$1, WeekStart } from "@uniqu/core";
 import { TAtscriptAnnotatedType, TAtscriptTypeObject } from "@atscript/typescript/utils";
-import { DbPatch, DbResponse, DbRow, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1, TFieldMeta, TMetaResponse, TRelationInfo, TSearchIndexInfo } from "@atscript/db";
+import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, BucketExpr as BucketExpr$1, BucketUnit, CalendarBucketLabel, FilterExpr, SelectExpr, TypedWithRelation, Uniquery as Uniquery$1, UniqueryControls, ValidGroupBy as ValidGroupBy$1, WeekStart } from "@uniqu/core";
 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/types.d.ts
 /**
@@ -96,6 +96,18 @@ type DataOf<T> = T extends {
     __dataType?: infer D;
   };
 } ? unknown extends D ? T extends (new (...a: any[]) => infer I) ? I : Record<string, unknown> : D & Record<string, unknown> : Record<string, unknown>;
+/**
+ * `$select` controls of a read over `T` whose controller declares the display-only
+ * fields `D` (`@DbDecorations`): `$select` also accepts `keyof D`; filter, sort
+ * and every other control stay over the own fields. Since 0.1.148.
+ */
+type DecoratedControls<T, D> = Omit<UniqueryControls<OwnOf<T>, NavOf<T>>, "$select"> & {
+  $select?: SelectExpr<OwnOf<T> & D>;
+};
+/** A read query over `T` — {@link DecoratedControls} for the controls. Since 0.1.148. */
+type DecoratedQuery<T, D> = Omit<Uniquery$1<OwnOf<T>, NavOf<T>>, "controls"> & {
+  controls?: DecoratedControls<T, D>;
+};
 /** Extract own (non-nav) properties from an Atscript annotated type. */
 type OwnOf<T> = T extends {
   __ownProps: infer O;
@@ -236,4 +248,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, 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 };
+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 };

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

@@ -1,7 +1,7 @@
+import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, BucketExpr as BucketExpr$1, BucketUnit, CalendarBucketLabel, FilterExpr, SelectExpr, TypedWithRelation, Uniquery as Uniquery$1, UniqueryControls, ValidGroupBy as ValidGroupBy$1, WeekStart } from "@uniqu/core";
 import { TAtscriptAnnotatedType, TAtscriptTypeObject } from "@atscript/typescript/utils";
-import { AggregateQuery as AggregateQuery$1, AggregateResult as AggregateResult$1, BucketExpr as BucketExpr$1, BucketUnit, CalendarBucketLabel, FilterExpr, TypedWithRelation, Uniquery as Uniquery$1, UniqueryControls as UniqueryControls$1, ValidGroupBy as ValidGroupBy$1, WeekStart } from "@uniqu/core";
+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";
-import { DbPatch, DbResponse, DbRow, TDbDeleteResult as TDbDeleteResult$1, TDbInsertManyResult as TDbInsertManyResult$1, TDbInsertResult as TDbInsertResult$1, TDbUpdateResult as TDbUpdateResult$1, TFieldMeta, TMetaResponse, TRelationInfo, TSearchIndexInfo } from "@atscript/db";
 
 //#region src/types.d.ts
 /**
@@ -96,6 +96,18 @@ type DataOf<T> = T extends {
     __dataType?: infer D;
   };
 } ? unknown extends D ? T extends (new (...a: any[]) => infer I) ? I : Record<string, unknown> : D & Record<string, unknown> : Record<string, unknown>;
+/**
+ * `$select` controls of a read over `T` whose controller declares the display-only
+ * fields `D` (`@DbDecorations`): `$select` also accepts `keyof D`; filter, sort
+ * and every other control stay over the own fields. Since 0.1.148.
+ */
+type DecoratedControls<T, D> = Omit<UniqueryControls<OwnOf<T>, NavOf<T>>, "$select"> & {
+  $select?: SelectExpr<OwnOf<T> & D>;
+};
+/** A read query over `T` — {@link DecoratedControls} for the controls. Since 0.1.148. */
+type DecoratedQuery<T, D> = Omit<Uniquery$1<OwnOf<T>, NavOf<T>>, "controls"> & {
+  controls?: DecoratedControls<T, D>;
+};
 /** Extract own (non-nav) properties from an Atscript annotated type. */
 type OwnOf<T> = T extends {
   __ownProps: infer O;
@@ -236,4 +248,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, 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 };
+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 };

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

package/package.json

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