@atscript/db 0.1.147 → 0.1.148

package/dist/{buckets-DYopfd2Y.d.mts → buckets-CNdTOnei.d.mts}

@@ -1,8 +1,41 @@
 import { f as TFieldOps } from "./ops-AqhV7s9o.mjs";
 import { AtscriptExprNode, AtscriptExprNode as AtscriptExprNode$1, AtscriptOrderItem, AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, FlatOf as FlatOf$1, NavPropsOf, NavPropsOf as NavPropsOf$1, OwnPropsOf, OwnPropsOf as OwnPropsOf$1, PrimaryKeyOf, PrimaryKeyOf as PrimaryKeyOf$1, TAtscriptAnnotatedType, TAtscriptDataType, TAtscriptTypeObject, TMetadataMap, TSerializedAnnotatedType, TValidatorOptions, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
-import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, AggregateFn, AggregateFn as AggregateFn$1, AggregateQuery, AggregateQuery as AggregateQuery$1, AggregateResult, BucketUnit, FieldOpsFor, FilterExpr, FilterExpr as FilterExpr$1, RelationOp, ResolvedBucket, TypedWithRelation, Uniquery, Uniquery as Uniquery$1, UniqueryControls, UniqueryControls as UniqueryControls$1, UniqueryInsights, WithRelation, WithRelation as WithRelation$1 } from "@uniqu/core";
+import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, AggregateFn, AggregateFn as AggregateFn$1, AggregateQuery, AggregateQuery as AggregateQuery$1, AggregateResult, BucketUnit, FieldOpsFor, FilterExpr, FilterExpr as FilterExpr$1, RelationOp, ResolvedBucket, ResolvedRowOrderKey, ResolvedSelectExpr, TypedWithRelation, Uniquery, Uniquery as Uniquery$1, UniqueryControls, UniqueryControls as UniqueryControls$1, UniqueryInsights, WithRelation, WithRelation as WithRelation$1 } from "@uniqu/core";
 
 //#region src/query/uniqu-select.d.ts
+/** A row-level expression aggregate: `fn(<expr>)` over each row (physical field leaves). */
+interface TExprAggregate {
+  fn: "sum" | "avg" | "min" | "max";
+  alias: string;
+  expr: AtscriptExprNode;
+  /** The distinct physical columns the expression reads. */
+  names: readonly string[];
+}
+/** A group-level expression: leaves name aliases of other entries or grouped columns. */
+interface TSelectExpr {
+  alias: string;
+  expr: AtscriptExprNode;
+  /** The distinct names the expression reads (aliases of other entries, or grouped columns). */
+  names: readonly string[];
+}
+/** A `first` / `last` entry: the value of PHYSICAL `column` on the group's representative row. */
+interface TFirstLast {
+  fn: "first" | "last";
+  column: string;
+  alias: string;
+}
+/** One key of the representative-row order (PHYSICAL column). */
+interface TRowOrderKey {
+  column: string;
+  desc: boolean;
+}
+/** The arithmetic and representative-row parts of an aggregate `$select`, as the field mapper resolves them. */
+interface TUniquComputed {
+  exprAggregates?: readonly TExprAggregate[];
+  exprs?: readonly TSelectExpr[];
+  rowOrder?: readonly TRowOrderKey[];
+  sources?: ReadonlyMap<string, TDbFieldMeta>;
+}
 /**
  * Wraps a raw `$select` value and provides lazy-cached conversions
  * to the forms different adapters need.
@@ -13,8 +46,9 @@ import { AggregateControls, AggregateExpr, AggregateExpr as AggregateExpr$1, Agg
  * For exclusion → inclusion inversion, pass `allFields` (physical field names).
  *
  * An array `$select` holds plain field names and computed entries —
- * aggregates (`{ $fn, $field }`, {@link aggregates}) and calendar buckets
- * (`{ $bucket, $field }`, {@link buckets}). Entries arrive normalized
+ * aggregates (`{ $fn, $field }`, {@link aggregates}), `first` / `last`
+ * ({@link firstLast}), arithmetic ({@link exprAggregates}, {@link exprs}) and
+ * calendar buckets (`{ $bucket, $field }`, {@link buckets}). Entries arrive normalized
  * (`normalizeComputedSelect` rejects any other shape before translation).
  */
 declare class UniquSelect {
@@ -23,7 +57,6 @@ declare class UniquSelect {
   private _allFields?;
   private _array;
   private _projection;
-  private _aggregates;
   /**
    * The calendar buckets of an aggregate `$select`, normalized (canonical
    * zone, week start, alias) with the PHYSICAL source `field` and its
@@ -32,14 +65,56 @@ declare class UniquSelect {
    * columns). Since 0.1.132.
    */
   readonly buckets: readonly TResolvedBucket[] | undefined;
+  /**
+   * The plain aggregates (`{ $fn, $field }`) of an array-form `$select`;
+   * `undefined` when there are none or the `$select` is object form.
+   * `first` / `last` are listed separately ({@link firstLast}), so an adapter
+   * written before them never meets one here.
+   */
+  readonly aggregates: AggregateExpr[] | undefined;
+  /** The `first` / `last` entries of an array-form `$select` (since 0.1.148); `undefined` when none. */
+  readonly firstLast: readonly TFirstLast[] | undefined;
+  /**
+   * Row-level expression aggregates (`sum(price*qty)`) — leaves are physical
+   * columns; render `fn(<expr>)` per row. `undefined` when there are none.
+   * Only reaches adapters whose `supportsAggregateExpressions()` is true.
+   * Since 0.1.148.
+   */
+  readonly exprAggregates: readonly TExprAggregate[] | undefined;
+  /**
+   * Group-level expressions in dependency order: each leaf names an alias
+   * defined by an aggregate / `first` / `last` / expression entry or a
+   * grouped column; evaluate after grouping. `undefined` when there are none.
+   * Since 0.1.148.
+   */
+  readonly exprs: readonly TSelectExpr[] | undefined;
+  /**
+   * The order of the rows inside each group that `first` / `last` read, as
+   * physical columns, with the primary key appended as the final ascending
+   * tie-break. `undefined` without `first` / `last`. Since 0.1.148.
+   */
+  readonly rowOrder: readonly TRowOrderKey[] | undefined;
+  /**
+   * The descriptors of the PHYSICAL columns a `min` / `max` / `first` / `last`
+   * reads — for an engine that cannot aggregate a type directly (PostgreSQL
+   * has no `MIN(boolean)`). Since 0.1.148.
+   */
+  readonly sources: ReadonlyMap<string, TDbFieldMeta>;
+  /**
+   * The output alias of every computed entry but the calendar buckets, in the
+   * order adapters emit them: {@link aggregates}, {@link exprAggregates},
+   * {@link firstLast}, then {@link exprs} (which read the others). Since 0.1.148.
+   */
+  readonly computedAliases: readonly string[];
   /**
    * @param raw - the `$select` value (field paths already physical).
    * @param allFields - physical field names, for exclusion-form inversion.
    * @param buckets - the resolved calendar buckets of the raw `$select`'s
    *   `{ $bucket }` entries (the field mappers supply them — physical `field`,
    *   source `fd`).
+   * @param computed - the resolved arithmetic and `$rowOrder` parts (physical).
    */
-  constructor(raw: UniqueryControls["$select"], allFields?: string[], buckets?: readonly TResolvedBucket[]);
+  constructor(raw: UniqueryControls["$select"], allFields?: string[], buckets?: readonly TResolvedBucket[], computed?: TUniquComputed);
   /**
    * Resolved inclusion array of plain field names (strings only).
    * Computed entries (aggregates, calendar buckets) are filtered out.
@@ -53,11 +128,6 @@ declare class UniquSelect {
    * AggregateExpr objects in array form are ignored.
    */
   get asProjection(): Record<string, 0 | 1> | undefined;
-  /**
-   * Extracts AggregateExpr entries from array-form $select.
-   * Returns undefined if no aggregates present or if $select is object form.
-   */
-  get aggregates(): AggregateExpr[] | undefined;
   /** Whether the $select contains any AggregateExpr entries. */
   get hasAggregates(): boolean;
   /** The calendar bucket whose alias is `key`, if any — how adapters resolve a `$groupBy` / `$having` key. */
@@ -129,11 +199,28 @@ declare abstract class FieldMappingStrategy {
    * `buckets` are the query's calendar buckets as the core's normalizer
    * resolved them (`normalizeComputedSelect` — `AtscriptDbReadable.aggregate`
    * runs it before the guards); they reach adapters with `field` made
-   * physical and the source descriptor as `fd`.
+   * physical and the source descriptor as `fd`. `exprs` / `rowOrder` are the
+   * arithmetic entries and `$rowOrder` keys of the same normalizer
+   * (`resolveComputedSelect`): they reach adapters as `$select.exprAggregates`
+   * / `.exprs` / `.rowOrder` with physical names (the primary key appended to
+   * the order); `$rowOrder` itself is not forwarded (since 0.1.148).
+   */
+  translateAggregateQuery(query: AggregateQuery, meta: TableMetadata, buckets: readonly ResolvedBucket[], exprs?: readonly ResolvedSelectExpr[], rowOrder?: readonly ResolvedRowOrderKey[]): DbQuery;
+  /**
+   * `$having` with physical keys — except the computed output `aliases`,
+   * which stay as written (an alias equal to a renamed field's name,
+   * `first(raisedAt):raisedAt`, is the alias, exactly as in `$sort`).
    */
-  translateAggregateQuery(query: AggregateQuery, meta: TableMetadata, buckets: readonly ResolvedBucket[]): DbQuery;
-  /** Output aliases of the computed `$select` entries (aggregates and calendar buckets). */
+  private translateHaving;
+  /** Output aliases of the computed `$select` entries (aggregates, expressions and calendar buckets). */
   private computedAliasSet;
+  /**
+   * The arithmetic and `$rowOrder` parts of a grouped query with PHYSICAL
+   * names: a row-level operand is a column; a group-level operand stays an
+   * alias, or becomes the physical name of a `$groupBy` field. The primary
+   * key is appended to the order as the final ascending tie-break.
+   */
+  private physicalComputed;
   /**
    * `$select` with its field paths made physical: array-form names and
    * computed `$field`s (`'*'` kept), or the keys of the object
@@ -535,6 +622,8 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * configured with an `encryption` options block.
    */
   setEncryption(encryption: DbEncryption | undefined): void;
+  /** @internal Set by the owning `DbSpace` when it closes. */
+  _spaceClosed: boolean;
   /** Ensures metadata is built. Called before any metadata access. */
   protected _ensureBuilt(): void;
   /**
@@ -612,6 +701,12 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
   get indexes(): Map<string, TDbIndex>;
   /** Primary key field names from `@meta.id`. */
   get primaryKeys(): readonly string[];
+  /**
+   * Physical column lists that must be unique: the primary key (when declared)
+   * followed by every unique index and every adapter-contributed unique field. Used by conflict-ignoring inserts.
+   * @since 0.1.148
+   */
+  get uniqueKeySets(): string[][];
   /** Preferred row identifier field names. Defaults to primary keys. */
   get preferredId(): readonly string[];
   /** Legitimate row-identifier shapes (primary key + every unique index). */
@@ -850,12 +945,20 @@ declare class AtscriptDbReadable<T extends TAtscriptAnnotatedType = TAtscriptAnn
    * then reverse-maps and applies fromStorage formatters on results.
    */
   aggregate(query: AggregateQuery): Promise<Array<Record<string, unknown>>>;
+  /**
+   * The computed aliases of one source field that is a boolean or a decimal —
+   * `min` / `max` / `first` / `last` — with that field's descriptor: the
+   * aggregate row's value is coerced like the column's own on read.
+   */
+  private _aliasFields;
   /** Whether the underlying adapter supports text search. */
   isSearchable(): boolean;
   /** Whether the adapter can filter on a given field (proxies adapter capability). */
   canFilterField(fd: TDbFieldMeta): boolean;
   /** Calendar-bucket units the adapter can group by (proxies adapter capability; empty = none). */
   calendarBucketUnits(): ReadonlySet<BucketUnit>;
+  /** Whether the adapter renders aggregate arithmetic (proxies adapter capability). @since 0.1.148 */
+  supportsAggregateExpressions(): boolean;
   /** Aggregate functions the adapter renders (proxies adapter capability). @since 0.1.136 */
   aggregateFns(): ReadonlySet<AggregateFn>;
   /** Whether the adapter can sort by a given field (proxies adapter capability). */
@@ -1132,7 +1235,10 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * Inserts a single record. Delegates to {@link insertMany} for unified
    * nested creation support.
    */
-  insertOne(payload: DbPatch<DataType>, opts?: TWriteOptions<DataType>): Promise<TDbInsertResult>;
+  insertOne(payload: DbPatch<DataType>, opts: TInsertOptions<DataType> & {
+    onConflict: "ignore";
+  }): Promise<TDbInsertIgnoreResult>;
+  insertOne(payload: DbPatch<DataType>, opts?: TInsertOptions<DataType>): Promise<TDbInsertResult>;
   /**
    * Inserts multiple records with batch-optimized nested creation.
    *
@@ -1149,7 +1255,11 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
    * 0.1.143) runs once after every phase with the inserted rows' primary-key
    * filters — see {@link TWriteOptions}.
    */
-  insertMany(payloads: Array<DbPatch<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbInsertManyResult>;
+  insertMany(payloads: Array<DbPatch<DataType>>, opts: TInsertOptions<DataType> & {
+    onConflict: "ignore";
+  }): Promise<TDbInsertManyIgnoreResult>;
+  insertMany(payloads: Array<DbPatch<DataType>>, opts?: TInsertOptions<DataType>): Promise<TDbInsertManyResult>;
+  private _insertMany;
   /**
    * Replaces a single record identified by primary key(s).
    * Delegates to {@link bulkReplace} for unified nested relation support.
@@ -1303,6 +1413,24 @@ declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnota
   private _writtenPkFilters;
   /** Invokes a {@link TWriteOptions.check} with de-duplicated PK filters (inside the transaction). */
   private _runWriteCheck;
+  /**
+   * Ignore mode never writes a related parent — it would be orphaned when the
+   * row is skipped. A TO object that names only the target's key fields
+   * (`{ org: { id: 9 } }`) creates nothing: it is a reference to an existing
+   * parent, so it becomes the row's foreign key (the existence check follows
+   * with the other FK validation). Runs before validation (which would demand
+   * the parent's required fields); any other TO object is left for
+   * {@link _rejectNestedToInIgnoreMode}.
+   */
+  private _linkToByKeyInIgnoreMode;
+  /** Ignore mode: whatever TO object is left would create a related parent (see {@link _linkToByKeyInIgnoreMode}). */
+  private _rejectNestedToInIgnoreMode;
+  /**
+   * Conflict-ignoring main insert: marks rows repeating an earlier row's
+   * primary / unique key tuple (NULL components never collide), sends the rest
+   * to the adapter and assembles one slot per input row.
+   */
+  private _insertIgnoring;
   /**
    * The exact primary-key filter of each inserted row: the logical key from
    * the row (SDK defaults applied), else the stored key the adapter wrote into
@@ -1451,6 +1579,14 @@ interface TViewPlan {
  * via the provided resolver function.
  */
 declare function translateQueryTree(node: AtscriptQueryNode, resolveField: (ref: AtscriptQueryFieldRef) => string): FilterExpr;
+/**
+ * Evaluates a computed expression in process (the memory adapter, a test, a
+ * third-party adapter) with the semantics every adapter shares: IEEE double,
+ * a leaf is `Number()`-ed, NULL / undefined propagates as `null`, `/` by zero
+ * is `null`, `coalesce` returns its first non-null value.
+ * @since 0.1.148
+ */
+declare function evaluateExpr(expr: AtscriptExprNode, leaf: (field: string) => unknown): number | null;
 //#endregion
 //#region src/table/view-source.d.ts
 /**
@@ -1680,6 +1816,14 @@ interface TDbSpaceOptions {
   logger?: TGenericLogger;
   /** Field-level encryption configuration for `@db.encrypted` fields. */
   encryption?: TDbEncryptionOptions;
+  /**
+   * Runs once from {@link DbSpace.close}, after every adapter was disposed.
+   * Pass the resource the space does not own by itself, e.g.
+   * `() => driver.close()`. The `createAdapter` helpers of the adapter
+   * packages set it to close the driver they built.
+   * @since 0.1.148
+   */
+  onClose?: () => void | Promise<void>;
 }
 /**
  * A database space — a registry of tables and views sharing the same adapter type and driver.
@@ -1699,13 +1843,21 @@ interface TDbSpaceOptions {
  * const activeUsers = db.getView(ActiveUsersType)
  * ```
  */
-declare class DbSpace {
+declare class DbSpace implements AsyncDisposable {
   protected readonly adapterFactory: TAdapterFactory;
+  /** `await using` support — an alias for {@link close}, installed below where the runtime has the symbol. */
+  [Symbol.asyncDispose]: () => Promise<void>;
   private _readables;
   /** All tables created in this space — used for reverse FK lookup during cascade. */
   private _allTables;
+  /** Every table / view handle the space created — flagged closed on {@link close}. */
+  private _handles;
   /** Lazily created adapter for administrative ops (drop table/view) that don't need a registered readable. */
   private _adminAdapter?;
+  /** Every adapter this space created (tables, views, admin) — disposed on close. */
+  private _adapters;
+  private _onClose?;
+  private _closing?;
   protected readonly logger: TGenericLogger;
   /** Encryption service for `@db.encrypted` fields — validated eagerly at construction. */
   protected readonly _encryption?: DbEncryption;
@@ -1770,6 +1922,23 @@ declare class DbSpace {
    * Optional call: an adapter built against an older `@atscript/db` copy lacks it.
    */
   private _createAdapter;
+  /** `true` once {@link close} was called. @since 0.1.148 */
+  get closed(): boolean;
+  /** Throws `SPACE_CLOSED` once the space is closed. */
+  private _assertOpen;
+  /**
+   * Closes the space: marks it closed, disposes every adapter it created, then
+   * runs the `onClose` hook (the `createAdapter` helpers close their driver
+   * there). Idempotent — every call returns the first call's promise. Every
+   * step is attempted; failures are collected into an `AggregateError`.
+   *
+   * It does not cancel or drain in-flight queries: call it after the server
+   * stopped accepting requests. After close, `get*` and operations on existing
+   * table/view handles throw `DbError("SPACE_CLOSED")`.
+   * @since 0.1.148
+   */
+  close(): Promise<void>;
+  private _doClose;
   /**
    * Finds all child tables with FKs pointing to the given parent table name.
    * Accesses `table.foreignKeys` which triggers `_flatten()` if needed.
@@ -1863,6 +2032,13 @@ declare abstract class BaseDbAdapter {
    * @since 0.1.137
    */
   registerSpace(_space: DbSpace): void;
+  /**
+   * Releases timers, caches or change streams the adapter holds. Called once
+   * by {@link DbSpace.close}; the driver itself is closed by the space's
+   * `onClose` hook, never here. No-op by default.
+   * @since 0.1.148
+   */
+  dispose?(): void | Promise<void>;
   /**
    * Enables or disables verbose (debug-level) logging for this adapter.
    * When disabled, no log strings are constructed — zero overhead.
@@ -2003,6 +2179,20 @@ declare abstract class BaseDbAdapter {
    * @since 0.1.136
    */
   aggregateFns(): ReadonlySet<AggregateFn>;
+  /**
+   * Whether this adapter renders arithmetic in an aggregate `$select`
+   * (`{ $expr }`, `{ $fn, $expr }`) — IEEE double, NULL propagating, `/` by
+   * zero NULL, the same semantics as `@db.compute`. Default `false`
+   * (fail-closed): the core rejects such a query with `AGG_EXPR_NOT_SUPPORTED`
+   * before dispatch. An adapter returning `true` also receives
+   * `controls.$select.exprAggregates` / `.exprs` (see `UniquSelect`), and
+   * `first` / `last` (`aggregateFns()`) with `.firstLast` and `.rowOrder`;
+   * the shared `evaluateExpr` evaluates an expression tree in process.
+   * moost-db advertises it as `/meta.aggregateExpressions`.
+   *
+   * @since 0.1.148
+   */
+  supportsAggregateExpressions(): boolean;
   /**
    * Revision of how this adapter renders a managed view (its SQL / pipeline)
    * from an unchanged view definition. Stored in each managed view's sync
@@ -2357,6 +2547,21 @@ declare abstract class BaseDbAdapter {
   aggregate(_query: DbQuery): Promise<Array<Record<string, unknown>>>;
   abstract insertOne(data: Record<string, unknown>): Promise<TDbInsertResult>;
   abstract insertMany(data: Array<Record<string, unknown>>): Promise<TDbInsertManyResult>;
+  /**
+   * Conflict-ignoring batch insert (`insertMany(rows, { onConflict: 'ignore' })`).
+   * Returns ONE SLOT PER INPUT ROW, in order: `{ insertedId }` for an inserted
+   * row, `null` for a row skipped because it collided with a STORED row on the
+   * primary key or a unique index. (The core already removed duplicates inside
+   * the batch.) Only uniqueness collisions are skipped — NOT NULL, FK, check
+   * and every other error must throw — and a skipped row must never abort the
+   * surrounding transaction. Fail-closed by default: throws
+   * `DbError("ON_CONFLICT_NOT_SUPPORTED")`; also override
+   * {@link supportsInsertIgnore}.
+   * @since 0.1.148
+   */
+  insertManyIgnore(_data: Array<Record<string, unknown>>): Promise<TDbInsertIgnoreSlot[]>;
+  /** Whether {@link insertManyIgnore} is implemented (drives `crud.insert: ["onConflict"]` in `/meta`). @since 0.1.148 */
+  supportsInsertIgnore(): boolean;
   abstract replaceOne(filter: FilterExpr, data: Record<string, unknown>, expectedVersion?: number): Promise<TDbUpdateResult>;
   abstract updateOne(filter: FilterExpr, data: Record<string, unknown>, ops?: TFieldOps, expectedVersion?: number): Promise<TDbUpdateResult>;
   abstract deleteOne(filter: FilterExpr): Promise<TDbDeleteResult>;
@@ -2855,7 +3060,7 @@ declare class TableMetadata {
 //#endregion
 //#region src/types.d.ts
 /** Controls with resolved projection. Used in the adapter interface. */
-interface DbControls extends Omit<UniqueryControls, "$select"> {
+interface DbControls extends Omit<UniqueryControls, "$select" | "$rowOrder"> {
   $select?: UniquSelect;
 }
 /** Query object with resolved projection. Passed to adapter methods. */
@@ -2933,6 +3138,13 @@ interface TFieldMeta {
    * (`bucketUnits`). Since 0.1.132.
    */
   bucketable?: true;
+  /**
+   * Present (true) exactly when the field may be an operand of query-time
+   * arithmetic (`sum(price*qty)`, `expr(a/b)`) — a plain `number` (not a
+   * decimal or timestamp) that is visible and physically aggregatable — on an
+   * adapter with `aggregateExpressions`. Since 0.1.148.
+   */
+  numeric?: true;
   /**
    * Present (true) when the field is a `@db.column.derived` column: its value
    * is computed from a `@db.json` field of the same row and is never written
@@ -2947,6 +3159,20 @@ interface TFieldMeta {
    * Since 0.1.147.
    */
   computed?: true;
+  /**
+   * Present (true) exactly when `$groupBy` on this field passes the gate:
+   * physically filterable (adapter, not write-only, not encrypted) and, on a
+   * table declaring dimensions or measures, a dimension. Since 0.1.148.
+   */
+  groupable?: true;
+  /**
+   * Present (true) for a declared display-only decoration (`@DbDecorations`):
+   * a value the controller computes (`decorateRows`) and attaches to rows. Name
+   * it in `$select` to receive it; it is never filterable, sortable or
+   * groupable, and its column definition is in {@link TMetaResponse.decorations}
+   * (not in `type`). Since 0.1.148.
+   */
+  decoration?: true;
 }
 /** Built-in CRUD operation names; map 1:1 to public method names. */
 type TCrudOp = "query" | "pages" | "one" | "geo" | "insert" | "update" | "replace" | "remove";
@@ -2969,6 +3195,14 @@ interface TMetaResponse {
   relations: TRelationInfo[];
   fields: Record<string, TFieldMeta>;
   type: TSerializedAnnotatedType;
+  /**
+   * The declared display-only fields (`@DbDecorations`): an object type whose
+   * props are the decorations (with their `@meta.*`, `@expect.*` and `@ui.*`
+   * annotations), each also listed in {@link fields} with `decoration: true`.
+   * Absent when none is declared (or none is visible to the caller). Not part
+   * of {@link type}, so forms and write validation never see it. Since 0.1.148.
+   */
+  decorations?: TSerializedAnnotatedType;
   actions: TDbActionInfo[];
   crud: TCrudPermissions;
   /**
@@ -2993,6 +3227,15 @@ interface TMetaResponse {
    * @since 0.1.136
    */
   aggregateFns?: AggregateFn[];
+  /**
+   * Whether the adapter renders arithmetic in an aggregate `$select`
+   * (`{ $expr }`, URL `expr(a/b):alias`, `sum(price*qty):alias`) — see
+   * `BaseDbAdapter.supportsAggregateExpressions()`. Fields that may be
+   * operands are flagged `fields[P].numeric`.
+   *
+   * @since 0.1.148
+   */
+  aggregateExpressions?: boolean;
 }
 /** Where the action applies on the UI. */
 type TDbActionLevel = "table" | "row" | "rows";
@@ -3170,6 +3413,35 @@ interface TDbInsertManyResult {
   insertedCount: number;
   insertedIds: unknown[];
 }
+/**
+ * `insertOne` result in conflict-ignoring mode (`onConflict: 'ignore'`).
+ * @since 0.1.148
+ */
+interface TDbInsertIgnoreResult {
+  /** Id of the inserted row; absent when the row was skipped. */
+  insertedId?: unknown;
+  /** `true` when the row collided on the primary key or a unique index and was skipped. */
+  conflict: boolean;
+}
+/**
+ * `insertMany` result in conflict-ignoring mode (`onConflict: 'ignore'`):
+ * `insertedCount` / `insertedIds` cover the INSERTED rows only (dense, input
+ * order); `inserted` and `conflicts` map back to input indices.
+ * @since 0.1.148
+ */
+interface TDbInsertManyIgnoreResult extends TDbInsertManyResult {
+  /** Input index of each `insertedIds` entry. */
+  inserted: number[];
+  /** Input indices skipped because of a unique / primary-key conflict, ascending. */
+  conflicts: number[];
+}
+/**
+ * One slot per input row of `BaseDbAdapter.insertManyIgnore`: the inserted id,
+ * or `null` for a skipped (conflicting) row.
+ */
+type TDbInsertIgnoreSlot = {
+  insertedId: unknown;
+} | null;
 interface TDbUpdateResult {
   matchedCount: number;
   modifiedCount: number;
@@ -3800,6 +4072,21 @@ interface TWriteOptions<Row = Record<string, unknown>> extends TIdResolveOptions
    */
   check?: TDbWriteCheck;
 }
+/**
+ * Options of `insertOne` / `insertMany`.
+ * @since 0.1.148
+ */
+interface TInsertOptions<Row = Record<string, unknown>> extends TWriteOptions<Row> {
+  /**
+   * `'error'` (default): a unique / primary-key violation throws `CONFLICT`.
+   * `'ignore'`: rows that collide on the primary key or any unique index —
+   * with a stored row or an earlier row of the same batch — are skipped and
+   * reported by input index. Everything else (validation, NOT NULL, FK, check,
+   * guard) still throws and rolls the call back. A row that creates a related
+   * parent (`@db.rel.to` nested object) is rejected in this mode.
+   */
+  onConflict?: "error" | "ignore";
+}
 /**
  * Context handed to a write {@link TWriteOptions.check} (since 0.1.143) — and
  * through it to `AsDbController.checkWrite()`. Lets a permission layer verify
@@ -3938,7 +4225,14 @@ interface TBucketFieldSource {
 declare function normalizeComputedSelect(controls: {
   $select?: unknown;
   $groupBy?: unknown;
+  $rowOrder?: unknown;
 } | undefined, fields: TBucketFieldSource, aggregate?: boolean): ResolvedBucket[];
+/** The normalized computed `$select` entries of a grouped query — see {@link resolveComputedSelect}. */
+interface TComputedSelect {
+  buckets: ResolvedBucket[];
+  exprs: ResolvedSelectExpr[];
+  rowOrder?: ResolvedRowOrderKey[];
+}
 /**
  * @deprecated since 0.1.136 — renamed {@link normalizeComputedSelect} (it
  * normalizes every computed `$select` entry, aggregates included).
@@ -3969,4 +4263,4 @@ declare function isJsonValueField(fd: TDbFieldMeta): boolean;
  */
 declare function jsonValueAncestor(path: string, jsonValueParents: ReadonlySet<string>): string | undefined;
 //#endregion
-export { TDbStorageType as $, AtscriptExprNode$1 as $t, TCrudPermissions as A, TDbEncryptionOptions as An, TValueFormatterPair as At, TDbDeleteResult as B, isGeoPointType as Bt, NullableOptional as C, andFilters as Cn, TRelationInfo as Ct, TCascadeTarget as D, isResolvedRelationFilter as Dn, TTableOptionDiff as Dt, TCascadeResolver as E, hasRelationOp as En, TSyncColumnResult as Et, TDbActionTargetSummary as F, TGenericLogger as Fn, Uniquery$1 as Ft, TDbIndexType as G, DbSpace as Gt, TDbForeignKey as H, ALL_VIEW_CAPABILITIES as Ht, TDbAvailableActions as I, UniquSelect as In, UniqueryControls$1 as It, TDbObjectKind as J, AtscriptDbView as Jt, TDbInsertManyResult as K, TAdapterFactory as Kt, TDbCollation as L, WithRelation$1 as Lt, TDbActionIntent as M, FieldMappingStrategy as Mn, TWriteOptions as Mt, TDbActionLevel as N, TReadControls as Nn, TWriteTableResolver as Nt, TColumnDiff as O, relationStaticFilter as On, TTableResolver as Ot, TDbActionProcessor as P, NoopLogger as Pn, TypedWithRelation as Pt, TDbRemoveGuardContext as Q, aliasTargetOf as Qt, TDbDefaultFn as R, TableMetadata as Rt, NavPropsOf$1 as S, TRelationStaticFilter as Sn, TReferencingForeignKey as St, PrimaryKeyOf$1 as T, forEachResolvedRelation as Tn, TSearchIndexInfo as Tt, TDbIndex as U, BaseDbAdapter as Ut, TDbFieldMeta as V, ALL_BUCKET_UNITS as Vt, TDbIndexField as W, TViewCapability as Wt, TDbRelation as X, isAtscriptDbView as Xt, TDbReferentialAction as Y, TViewColumnMapping as Yt, TDbRemoveGuard as Z, isViewType as Zt, DbQuery as _, REL_FILTER_MAX_NODES as _n, TIdResolveOptions as _t, jsonValueAncestor as a, TViewJoin as an, TDbWriteGuardContext as at, FilterExpr$1 as b, TRelationFilterJunction as bn, TMetadataOverrides as bt, AggregateControls as c, translateQueryTree as cn, TDerivedColumn as ct, AggregateQuery$1 as d, NativeIntegrity as dn, TExistingForeignKey as dt, AtscriptOrderItem as en, TDbUpdateResult as et, AggregateResult as f, TCascadePin as fn, TExistingTableOption as ft, DbPatch as g, REL_FILTER_MAX_DEPTH as gn, TIdDescriptor as gt, DbControls as h, resolveDesignType as hn, TFkLookupTarget as ht, isJsonValueField as i, AtscriptRef as in, TDbWriteGuard as it, TDbActionInfo as j, DocumentFieldMapper as jn, TViewJsonType as jt, TCrudOp as k, DbEncryption as kn, TTouchManyOptions as kt, AggregateExpr$1 as l, AtscriptDbTable as ln, TEnsureTableOptions as lt, AtscriptDbWritable as m, DbResponse as mn, TFkLookupResolver as mt, TResolvedBucket as n, AtscriptQueryFieldRef$1 as nn, TDbWriteCheck as nt, normalizeComputedSelect as o, TViewPlan as on, TDeleteOptions as ot, AtscriptDbTableLike as p, AtscriptDbReadable as pn, TFieldMeta as pt, TDbInsertResult as q, TDbSpaceOptions as qt, isBucketableField as r, AtscriptQueryNode$1 as rn, TDbWriteCheckContext as rt, resolveCalendarBuckets as s, isFieldRef as sn, TDerivedChangeReason as st, TBucketFieldSource as t, AtscriptQueryComparison as tn, TDbWriteAction as tt, AggregateFn$1 as u, IntegrityStrategy as un, TExistingColumn as ut, DbRow as v, ResolvedRelationFilter as vn, TIdentification as vt, OwnPropsOf$1 as w, containsRelationFilter as wn, TRowResolveOptions as wt, FlatOf$1 as x, TRelationFilterTable as xn, TPrimaryKeyChange as xt, FieldOpsFor as y, TRelGuardState as yn, TMetaResponse as yt, TDbDefaultValue as z, isGeoIndexableType as zt };
+export { TDbReferentialAction as $, AtscriptDbView as $t, TCrudOp as A, containsRelationFilter as An, TSearchIndexInfo as At, TDbDefaultValue as B, NoopLogger as Bn, Uniquery$1 as Bt, NavPropsOf$1 as C, REL_FILTER_MAX_NODES as Cn, TInsertOptions as Ct, TCascadeResolver as D, TRelationFilterTable as Dn, TReferencingForeignKey as Dt, PrimaryKeyOf$1 as E, TRelationFilterJunction as En, TPrimaryKeyChange as Et, TDbActionProcessor as F, DbEncryption as Fn, TValueFormatterPair as Ft, TDbIndexField as G, UniquSelect as Gn, isGeoPointType as Gt, TDbFieldMeta as H, TExprAggregate as Hn, WithRelation$1 as Ht, TDbActionTargetSummary as I, TDbEncryptionOptions as In, TViewJsonType as It, TDbInsertIgnoreSlot as J, BaseDbAdapter as Jt, TDbIndexType as K, ALL_BUCKET_UNITS as Kt, TDbAvailableActions as L, DocumentFieldMapper as Ln, TWriteOptions as Lt, TDbActionInfo as M, hasRelationOp as Mn, TTableOptionDiff as Mt, TDbActionIntent as N, isResolvedRelationFilter as Nn, TTableResolver as Nt, TCascadeTarget as O, TRelationStaticFilter as On, TRelationInfo as Ot, TDbActionLevel as P, relationStaticFilter as Pn, TTouchManyOptions as Pt, TDbObjectKind as Q, TDbSpaceOptions as Qt, TDbCollation as R, FieldMappingStrategy as Rn, TWriteTableResolver as Rt, FlatOf$1 as S, REL_FILTER_MAX_DEPTH as Sn, TIdentification as St, OwnPropsOf$1 as T, TRelGuardState as Tn, TMetadataOverrides as Tt, TDbForeignKey as U, TFirstLast as Un, TableMetadata as Ut, TDbDeleteResult as V, TGenericLogger as Vn, UniqueryControls$1 as Vt, TDbIndex as W, TRowOrderKey as Wn, isGeoIndexableType as Wt, TDbInsertManyResult as X, DbSpace as Xt, TDbInsertManyIgnoreResult as Y, TViewCapability as Yt, TDbInsertResult as Z, TAdapterFactory as Zt, DbPatch as _, NativeIntegrity as _n, TFieldMeta as _t, isJsonValueField as a, AtscriptOrderItem as an, TDbWriteAction as at, FieldOpsFor as b, DbResponse as bn, TIdDescriptor as bt, resolveCalendarBuckets as c, AtscriptQueryNode$1 as cn, TDbWriteGuard as ct, AggregateFn$1 as d, TViewPlan as dn, TDerivedChangeReason as dt, TViewColumnMapping as en, TDbRelation as et, AggregateQuery$1 as f, evaluateExpr as fn, TDerivedColumn as ft, DbControls as g, IntegrityStrategy as gn, TExistingTableOption as gt, AtscriptDbWritable as h, AtscriptDbTable as hn, TExistingForeignKey as ht, isBucketableField as i, AtscriptExprNode$1 as in, TDbUpdateResult as it, TCrudPermissions as j, forEachResolvedRelation as jn, TSyncColumnResult as jt, TColumnDiff as k, andFilters as kn, TRowResolveOptions as kt, AggregateControls as l, AtscriptRef as ln, TDbWriteGuardContext as lt, AtscriptDbTableLike as m, translateQueryTree as mn, TExistingColumn as mt, TComputedSelect as n, isViewType as nn, TDbRemoveGuardContext as nt, jsonValueAncestor as o, AtscriptQueryComparison as on, TDbWriteCheck as ot, AggregateResult as p, isFieldRef as pn, TEnsureTableOptions as pt, TDbInsertIgnoreResult as q, ALL_VIEW_CAPABILITIES as qt, TResolvedBucket as r, aliasTargetOf as rn, TDbStorageType as rt, normalizeComputedSelect as s, AtscriptQueryFieldRef$1 as sn, TDbWriteCheckContext as st, TBucketFieldSource as t, isAtscriptDbView as tn, TDbRemoveGuard as tt, AggregateExpr$1 as u, TViewJoin as un, TDeleteOptions as ut, DbQuery as v, TCascadePin as vn, TFkLookupResolver as vt, NullableOptional as w, ResolvedRelationFilter as wn, TMetaResponse as wt, FilterExpr$1 as x, resolveDesignType as xn, TIdResolveOptions as xt, DbRow as y, AtscriptDbReadable as yn, TFkLookupTarget as yt, TDbDefaultFn as z, TReadControls as zn, TypedWithRelation as zt };