@atscript/db 0.1.147 → 0.1.149

package/dist/index.d.mts

@@ -1,13 +1,13 @@
-import { $ as TDbStorageType, $t as AtscriptExprNode, A as TCrudPermissions, An as TDbEncryptionOptions, At as TValueFormatterPair, B as TDbDeleteResult, Bt as isGeoPointType, C as NullableOptional, Cn as andFilters, Ct as TRelationInfo, D as TCascadeTarget, Dn as isResolvedRelationFilter, Dt as TTableOptionDiff, E as TCascadeResolver, En as hasRelationOp, Et as TSyncColumnResult, F as TDbActionTargetSummary, Fn as TGenericLogger, Ft as Uniquery, G as TDbIndexType, Gt as DbSpace, H as TDbForeignKey, Ht as ALL_VIEW_CAPABILITIES, I as TDbAvailableActions, In as UniquSelect, It as UniqueryControls, J as TDbObjectKind, Jt as AtscriptDbView, K as TDbInsertManyResult, Kt as TAdapterFactory, L as TDbCollation, Lt as WithRelation, M as TDbActionIntent, Mn as FieldMappingStrategy, Mt as TWriteOptions, N as TDbActionLevel, Nn as TReadControls, Nt as TWriteTableResolver, O as TColumnDiff, On as relationStaticFilter, Ot as TTableResolver, P as TDbActionProcessor, Pn as NoopLogger, Pt as TypedWithRelation, Q as TDbRemoveGuardContext, Qt as aliasTargetOf, R as TDbDefaultFn, Rt as TableMetadata, S as NavPropsOf, Sn as TRelationStaticFilter, St as TReferencingForeignKey, T as PrimaryKeyOf, Tn as forEachResolvedRelation, Tt as TSearchIndexInfo, U as TDbIndex, Ut as BaseDbAdapter, V as TDbFieldMeta, Vt as ALL_BUCKET_UNITS, W as TDbIndexField, Wt as TViewCapability, X as TDbRelation, Xt as isAtscriptDbView, Y as TDbReferentialAction, Yt as TViewColumnMapping, Z as TDbRemoveGuard, Zt as isViewType, _ as DbQuery, _n as REL_FILTER_MAX_NODES, _t as TIdResolveOptions, a as jsonValueAncestor, an as TViewJoin, at as TDbWriteGuardContext, b as FilterExpr, bn as TRelationFilterJunction, bt as TMetadataOverrides, c as AggregateControls, cn as translateQueryTree, ct as TDerivedColumn, d as AggregateQuery, dn as NativeIntegrity, dt as TExistingForeignKey, en as AtscriptOrderItem, et as TDbUpdateResult, f as AggregateResult, fn as TCascadePin, ft as TExistingTableOption, g as DbPatch, gn as REL_FILTER_MAX_DEPTH, gt as TIdDescriptor, h as DbControls, hn as resolveDesignType, ht as TFkLookupTarget, i as isJsonValueField, in as AtscriptRef, it as TDbWriteGuard, j as TDbActionInfo, jn as DocumentFieldMapper, jt as TViewJsonType, k as TCrudOp, kn as DbEncryption, kt as TTouchManyOptions, l as AggregateExpr, ln as AtscriptDbTable, lt as TEnsureTableOptions, m as AtscriptDbWritable, mn as DbResponse, mt as TFkLookupResolver, n as TResolvedBucket, nn as AtscriptQueryFieldRef, nt as TDbWriteCheck, o as normalizeComputedSelect, on as TViewPlan, ot as TDeleteOptions, pn as AtscriptDbReadable, pt as TFieldMeta, q as TDbInsertResult, qt as TDbSpaceOptions, r as isBucketableField, rn as AtscriptQueryNode, rt as TDbWriteCheckContext, s as resolveCalendarBuckets, sn as isFieldRef, st as TDerivedChangeReason, t as TBucketFieldSource, tn as AtscriptQueryComparison, tt as TDbWriteAction, u as AggregateFn, un as IntegrityStrategy, ut as TExistingColumn, v as DbRow, vn as ResolvedRelationFilter, vt as TIdentification, w as OwnPropsOf, wn as containsRelationFilter, wt as TRowResolveOptions, x as FlatOf, xn as TRelationFilterTable, xt as TPrimaryKeyChange, y as FieldOpsFor, yn as TRelGuardState, yt as TMetaResponse, z as TDbDefaultValue, zt as isGeoIndexableType } from "./buckets-DYopfd2Y.mjs";
+import { $ as TDbReferentialAction, $t as AtscriptDbView, A as TCrudOp, An as containsRelationFilter, At as TSearchIndexInfo, B as TDbDefaultValue, Bn as NoopLogger, Bt as Uniquery, C as NavPropsOf, Cn as REL_FILTER_MAX_NODES, Ct as TInsertOptions, D as TCascadeResolver, Dn as TRelationFilterTable, Dt as TReferencingForeignKey, E as PrimaryKeyOf, En as TRelationFilterJunction, Et as TPrimaryKeyChange, F as TDbActionProcessor, Fn as DbEncryption, Ft as TValueFormatterPair, G as TDbIndexField, Gn as UniquSelect, Gt as isGeoPointType, H as TDbFieldMeta, Hn as TExprAggregate, Ht as WithRelation, I as TDbActionTargetSummary, In as TDbEncryptionOptions, It as TViewJsonType, J as TDbInsertIgnoreSlot, Jt as BaseDbAdapter, K as TDbIndexType, Kt as ALL_BUCKET_UNITS, L as TDbAvailableActions, Ln as DocumentFieldMapper, Lt as TWriteOptions, M as TDbActionInfo, Mn as hasRelationOp, Mt as TTableOptionDiff, N as TDbActionIntent, Nn as isResolvedRelationFilter, Nt as TTableResolver, O as TCascadeTarget, On as TRelationStaticFilter, Ot as TRelationInfo, P as TDbActionLevel, Pn as relationStaticFilter, Pt as TTouchManyOptions, Q as TDbObjectKind, Qt as TDbSpaceOptions, R as TDbCollation, Rn as FieldMappingStrategy, Rt as TWriteTableResolver, S as FlatOf, Sn as REL_FILTER_MAX_DEPTH, St as TIdentification, T as OwnPropsOf, Tn as TRelGuardState, Tt as TMetadataOverrides, U as TDbForeignKey, Un as TFirstLast, Ut as TableMetadata, V as TDbDeleteResult, Vn as TGenericLogger, Vt as UniqueryControls, W as TDbIndex, Wn as TRowOrderKey, Wt as isGeoIndexableType, X as TDbInsertManyResult, Xt as DbSpace, Y as TDbInsertManyIgnoreResult, Yt as TViewCapability, Z as TDbInsertResult, Zt as TAdapterFactory, _ as DbPatch, _n as NativeIntegrity, _t as TFieldMeta, a as isJsonValueField, an as AtscriptOrderItem, at as TDbWriteAction, b as FieldOpsFor, bn as DbResponse, bt as TIdDescriptor, c as resolveCalendarBuckets, cn as AtscriptQueryNode, ct as TDbWriteGuard, d as AggregateFn, dn as TViewPlan, dt as TDerivedChangeReason, en as TViewColumnMapping, et as TDbRelation, f as AggregateQuery, fn as evaluateExpr, ft as TDerivedColumn, g as DbControls, gn as IntegrityStrategy, gt as TExistingTableOption, h as AtscriptDbWritable, hn as AtscriptDbTable, ht as TExistingForeignKey, i as isBucketableField, in as AtscriptExprNode, it as TDbUpdateResult, j as TCrudPermissions, jn as forEachResolvedRelation, jt as TSyncColumnResult, k as TColumnDiff, kn as andFilters, kt as TRowResolveOptions, l as AggregateControls, ln as AtscriptRef, lt as TDbWriteGuardContext, mn as translateQueryTree, mt as TExistingColumn, n as TComputedSelect, nn as isViewType, nt as TDbRemoveGuardContext, o as jsonValueAncestor, on as AtscriptQueryComparison, ot as TDbWriteCheck, p as AggregateResult, pn as isFieldRef, pt as TEnsureTableOptions, q as TDbInsertIgnoreResult, qt as ALL_VIEW_CAPABILITIES, r as TResolvedBucket, rn as aliasTargetOf, rt as TDbStorageType, s as normalizeComputedSelect, sn as AtscriptQueryFieldRef, st as TDbWriteCheckContext, t as TBucketFieldSource, tn as isAtscriptDbView, tt as TDbRemoveGuard, u as AggregateExpr, un as TViewJoin, ut as TDeleteOptions, v as DbQuery, vn as TCascadePin, vt as TFkLookupResolver, w as NullableOptional, wn as ResolvedRelationFilter, wt as TMetaResponse, x as FilterExpr, xn as resolveDesignType, xt as TIdResolveOptions, y as DbRow, yn as AtscriptDbReadable, yt as TFkLookupTarget, z as TDbDefaultFn, zn as TReadControls, zt as TypedWithRelation } from "./buckets-CNdTOnei.mjs";
 import { _ as separateFieldOps, a as $mul, c as $update, d as TDbFieldOp, f as TFieldOps, g as separateCas, h as reconcileCas, i as $insert, l as $upsert, m as isDbFieldOp, n as $dec, o as $remove, p as getDbFieldOp, r as $inc, s as $replace, t as $cas, u as TDbCas } from "./ops-AqhV7s9o.mjs";
 import { a as isPlainObject, i as isEmptyObject, n as findAncestorInSet, o as selfOrAncestor, r as getPath, t as deletePath } from "./object-CtPYTIvy.mjs";
-import { c as CalendarBucketLabel, d as WeekStart, g as ALL_AGGREGATE_FNS, l as ComputedExpr, o as BucketExpr, s as BucketUnit, u as ResolvedBucket } from "./agg-D5DHsAby.mjs";
-import { a as buildValidationContext, c as isNavRelation, d as getKeyProps, f as CasExhaustedError, g as bucketTimeZoneUnavailable, h as DbErrorCode, l as TArrayPatch, m as DbError, n as ValidatorMode, p as CasMismatchError, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as TDbPatch } from "./validator-CMnTI6r7.mjs";
+import { c as CalendarBucketLabel, d as WeekStart, g as ALL_AGGREGATE_FNS, l as ComputedExpr, o as BucketExpr, s as BucketUnit, u as ResolvedBucket } from "./agg-Wo-smrYV.mjs";
+import { _ as aggregateFailure, a as buildValidationContext, c as isNavRelation, d as getKeyProps, f as CasExhaustedError, g as aggregateExpressionsNotSupported, h as DbErrorCode, l as TArrayPatch, m as DbError, n as ValidatorMode, p as CasMismatchError, r as buildDbValidator, s as forceNavNonOptional, t as ValidationContext, u as TDbPatch, v as bucketTimeZoneUnavailable, y as isConflict } from "./validator-tBNvM1qc.mjs";
 import { n as createDbValidatorPlugin, t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.mjs";
-import { r as fkColumns, s as isColumnTypeChanged } from "./fk-diff-BtOmL4OW.mjs";
-import { i as tableNameOf } from "./relation-helpers-C2bLtE-t.mjs";
-import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
-import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, RELATION_OPS, RelationOp, RelationOp as RelationOp$1, ResolvedBucket as ResolvedBucket$1, Uniquery as Uniquery$1, computeInsights, isPrimitive, isRelationOp, walkFilter } from "@uniqu/core";
+import { r as fkColumns, s as isColumnTypeChanged } from "./fk-diff-DsaIijVX.mjs";
+import { i as tableNameOf } from "./relation-helpers-Ba0v49sn.mjs";
+import { AtscriptExprNode as AtscriptExprNode$1, TAtscriptAnnotatedType } from "@atscript/typescript/utils";
+import { AggregateQuery as AggregateQuery$1, FilterExpr as FilterExpr$1, FilterVisitor, RELATION_OPS, RelationOp, RelationOp as RelationOp$1, ResolvedRowOrderKey, ResolvedSelectExpr, Uniquery as Uniquery$1, computeInsights, isPrimitive, isRelationOp, walkFilter } from "@uniqu/core";
 
 //#region src/shared/consts.d.ts
 /**
@@ -149,6 +149,7 @@ interface TGuardedQuery {
     $select?: unknown;
     $groupBy?: unknown;
     $having?: unknown;
+    $rowOrder?: unknown;
   };
 }
 /**
@@ -244,6 +245,28 @@ type TBucketSourceVerdict = {
   code: "encrypted" | "jsonDescendant" | "notTimestamp" | "notFilterable" | "notDimension" | "noBuckets";
   reason: string;
 };
+/** {@link groupSourceVerdict}'s answer — the `reason` clause has no trailing period. */
+type TGroupSourceVerdict = {
+  ok: true;
+} | {
+  ok: false;
+  code: "encrypted" | "notFilterable" | "notDimension";
+  reason: string;
+};
+/**
+ * Whether the stored leaf `fd` may be a `$groupBy` key (since 0.1.148) — the
+ * one rule for the core's strict-table check and moost-db's capability index
+ * (`/meta.fields[P].groupable` and the HTTP gate). First failing rule wins:
+ *
+ * 1. `encrypted` — `@db.encrypted`;
+ * 2. `notFilterable` — the adapter cannot filter (so cannot group) the storage;
+ * 3. `notDimension` — a strict table ({@link isStrictTable}) and the field is
+ *    not a dimension.
+ *
+ * A calendar-bucket alias is not a field: it groups by its source, whose
+ * dimension rule is {@link bucketSourceVerdict}'s (callers skip aliases).
+ */
+declare function groupSourceVerdict(fd: TDbFieldMeta, table: Pick<TBucketSourceTable, "dimensions" | "measures">, adapter: Pick<BaseDbAdapter, "canFilterField">): TGroupSourceVerdict;
 /**
  * Whether the stored leaf `fd` may be the source of a calendar bucket
  * (since 0.1.133) — every schema and adapter rule, once, for the core path
@@ -302,8 +325,9 @@ interface TQueryPathRefs {
  *
  * Aggregate mode is `aggregate` when given, else the presence of `$groupBy`.
  * In aggregate mode `$select` computed entries are collected by kind — an
- * aggregate's `$field` into `aggregate`, a calendar bucket's into `bucket` —
- * and their aliases (`$as`, else uniqu's `resolveAlias`) are exempted from
+ * aggregate's `$field` (a row-level expression's names, a `first` / `last`
+ * field) into `aggregate`, a calendar bucket's into `bucket`, a `$rowOrder`
+ * key into `sort` — and their aliases (`$as`, else uniqu's `resolveAlias`) are exempted from
  * `$sort` / `$having`; a bucket alias is also dropped from `groupBy`, which
  * lists grouped fields only.
  *
@@ -414,10 +438,11 @@ declare function checkHavingKeys(refs: TQueryPathRefs): {
  * ({@link checkHavingKeys} — after the path guard so an unknown key still
  * reads `Unknown field`), then the `$having` values (`guardHavingValues`).
  *
- * `buckets` are the query's resolved calendar buckets when the caller already
- * ran `normalizeComputedSelect` (resolved here otherwise).
+ * `resolved` is the query's normalized computed `$select`
+ * (`resolveComputedSelect`) when the caller already ran it (resolved here
+ * otherwise).
  */
-declare function guardAggregate(meta: TableMetadata, adapter: BaseDbAdapter, query: AggregateQuery$1, resolved?: readonly ResolvedBucket$1[]): void;
+declare function guardAggregate(meta: TableMetadata, adapter: BaseDbAdapter, query: AggregateQuery$1, resolved?: TComputedSelect): void;
 //#endregion
 //#region src/with-optimistic-retry.d.ts
 interface WithOptimisticRetryOptions {
@@ -458,6 +483,14 @@ interface WithOptimisticRetryOptions {
  */
 declare function withOptimisticRetry<TRow extends Record<string, unknown>>(table: AtscriptDbTable, filter: Record<string, unknown>, mutator: (row: TRow) => Promise<Record<string, unknown> | undefined> | Record<string, unknown> | undefined, opts?: WithOptimisticRetryOptions): Promise<TDbUpdateResult>;
 //#endregion
+//#region src/shared/keys.d.ts
+/**
+ * Identity of the key tuple `fields` of `row` for uniqueness checks, or
+ * `undefined` when any component is null / missing (a NULL never collides).
+ * Equal across driver representations (see {@link keyString}).
+ */
+declare function uniqueKeyTuple(row: Record<string, unknown>, fields: readonly string[]): string | undefined;
+//#endregion
 //#region src/shared/index-messages.d.ts
 /**
  * Wording of the "index not found" errors — one source for the core, every
@@ -556,4 +589,16 @@ declare function createFailureCollector(what: string): {
   throwIfAny: () => void;
 };
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptExprNode, type AtscriptOrderItem, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type BucketExpr, type BucketUnit, type CalendarBucketLabel, CasExhaustedError, CasMismatchError, type ComputedExpr, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, type RelationOp, RelationalFieldMapper, type ResolvedBucket, ResolvedRelationFilter, type TAdapterFactory, type TArrayPatch, type TBucketFieldSource, type TBucketSourceTable, type TBucketSourceVerdict, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbActionTargetSummary, type TDbAvailableActions, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TDbWriteAction, type TDbWriteCheck, type TDbWriteCheckContext, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TDerivedChangeReason, type TDerivedColumn, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGuardedQuery, type TIdDescriptor, type TIdResolveOptions, type TIdentification, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReadControls, type TReferencingForeignKey, type TRelationFilterJunction, type TRelationFilterTable, type TRelationInfo, type TRelationStaticFilter, type TResolvedBucket, type TRowResolveOptions, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewCapability, type TViewColumnMapping, type TViewJoin, type TViewJsonType, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, deletePath, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, tableNameOf, translateQueryTree, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };
+//#region src/query/aggregate-expr.d.ts
+/**
+ * Why a field cannot be an arithmetic operand, or `undefined` when it can: it
+ * must be a `number` (not a decimal — those are exact, an expression is IEEE
+ * double — and not a timestamp-tagged number) with plain column storage. The
+ * runtime twin of `@db.compute`'s operand rule, so declared and query-time
+ * arithmetic accept the same fields.
+ *
+ * @since 0.1.148
+ */
+declare function numericOperandProblem(fd: TDbFieldMeta): string | undefined;
+//#endregion
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, type AggregateControls, type AggregateExpr, type AggregateFn, type AggregateQuery, type AggregateResult, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, type AtscriptDbWritable, type AtscriptExprNode, type AtscriptOrderItem, type AtscriptQueryComparison, type AtscriptQueryFieldRef, type AtscriptQueryNode, type AtscriptRef, BaseDbAdapter, type BucketExpr, type BucketUnit, type CalendarBucketLabel, CasExhaustedError, CasMismatchError, type ComputedExpr, DEFAULT_DB_SPACE, type DbControls, DbEncryption, DbError, type DbErrorCode, type DbPatch, type DbQuery, type DbResponse, type DbRow, DbSpace, type DbValidationContext, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, type FieldOpsFor, type FilterExpr, type FilterVisitor, type FlatOf, IntegrityStrategy, NativeIntegrity, type NavPropsOf, NoopLogger, type NullableOptional, type OwnPropsOf, type PrimaryKeyOf, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, type RelationOp, RelationalFieldMapper, type ResolvedBucket, ResolvedRelationFilter, type TAdapterFactory, type TArrayPatch, type TBucketFieldSource, type TBucketSourceTable, type TBucketSourceVerdict, type TCascadeResolver, type TCascadeTarget, type TColumnDiff, type TCrudOp, type TCrudPermissions, type TDbActionInfo, type TDbActionIntent, type TDbActionLevel, type TDbActionProcessor, type TDbActionTargetSummary, type TDbAvailableActions, type TDbCas, type TDbCollation, type TDbDefaultFn, type TDbDefaultValue, type TDbDeleteResult, type TDbEncryptionOptions, type TDbFieldMeta, type TDbFieldOp, type TDbForeignKey, type TDbIndex, type TDbIndexField, type TDbIndexType, type TDbInsertIgnoreResult, type TDbInsertIgnoreSlot, type TDbInsertManyIgnoreResult, type TDbInsertManyResult, type TDbInsertResult, type TDbObjectKind, type TDbPatch, type TDbReferentialAction, type TDbRelation, type TDbRemoveGuard, type TDbRemoveGuardContext, type TDbSpaceOptions, type TDbStorageType, type TDbUpdateResult, type TDbWriteAction, type TDbWriteCheck, type TDbWriteCheckContext, type TDbWriteGuard, type TDbWriteGuardContext, type TDeleteOptions, type TDerivedChangeReason, type TDerivedColumn, type TEnsureTableOptions, type TExistingColumn, type TExistingForeignKey, type TExistingTableOption, type TExprAggregate, type TFieldMeta, type TFieldOps, type TFilterPredicate, type TFilterRef, type TFirstLast, type TFkLookupResolver, type TFkLookupTarget, type TGenericLogger, type TGroupSourceVerdict, type TGuardedQuery, type TIdDescriptor, type TIdResolveOptions, type TIdentification, type TInsertOptions, type TMetaResponse, type TMetadataOverrides, type TPrimaryKeyChange, type TQueryPathKind, type TQueryPathOp, type TQueryPathRefs, type TQueryPathSource, type TReadControls, type TReferencingForeignKey, type TRelationFilterJunction, type TRelationFilterTable, type TRelationInfo, type TRelationStaticFilter, type TResolvedBucket, type TRowOrderKey, type TRowResolveOptions, type TSearchIndexInfo, type TSyncColumnResult, type TTableOptionDiff, type TTableResolver, type TTouchManyOptions, type TValueFormatterPair, type TViewCapability, type TViewColumnMapping, type TViewJoin, type TViewJsonType, type TViewPlan, type TWriteOptions, type TWriteTableResolver, TableMetadata, type TypedWithRelation, UniquSelect, type Uniquery, type UniqueryControls, type ValidationContext, type ValidatorMode, type WeekStart, type WithOptimisticRetryOptions, type WithRelation, acceptedOperatorsHint, aggregateExpressionsNotSupported, aggregateFailure, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, deletePath, evaluateExpr, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, groupSourceVerdict, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isConflict, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, numericOperandProblem, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, tableNameOf, translateQueryTree, uniqueKeyTuple, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };

package/dist/index.mjs

@@ -1,12 +1,12 @@
-import { a as bucketTimeZoneUnavailable, n as CasMismatchError, r as DbError, t as CasExhaustedError } from "./db-error-D5uilS_A.mjs";
-import { $ as UniquSelect, A as geoIndexNotFoundMessage, B as classifyQueryPath, C as ALL_VIEW_CAPABILITIES, D as NativeIntegrity, E as IntegrityStrategy, F as acceptedOperatorsHint, G as guardPaths, H as guardAggregate, I as assertGeoPoint, J as sortFieldNames, K as guardQuery, L as bucketSourceVerdict, M as vectorIndexNotFoundMessage, N as ADAPTER_FILTER_REASON, O as AtscriptDbReadable, P as ENCRYPTED_REASON, Q as FieldMappingStrategy, R as canFilterLeaf, S as ALL_BUCKET_UNITS, T as createFailureCollector, U as guardFilter, V as collectQueryPaths, W as guardPath, X as RelationalFieldMapper, Y as unsupportedOperatorMessage, Z as DocumentFieldMapper, _ as isViewType, at as isJsonValueField, b as decomposePatch, ct as resolveCalendarBuckets, et as TableMetadata, f as fkColumns, g as isAtscriptDbView, h as AtscriptDbView, it as isBucketableField, j as searchIndexNotFoundMessage, k as resolveDesignType, lt as NoopLogger, n as isColumnTypeChanged, nt as isGeoPointType, ot as jsonValueAncestor, q as narrowerFilterOps, rt as aliasTargetOf, st as normalizeComputedSelect, tt as isGeoIndexableType, v as AtscriptDbTable, w as BaseDbAdapter, x as ApplicationIntegrity, y as assertNoVersionWrites, z as checkHavingKeys } from "./column-diff-CO06iQvI.mjs";
-import { n as ALL_AGGREGATE_FNS } from "./aggregate-fns-C0BymEqa.mjs";
-import { B as tableNameOf, C as ResolvedRelationFilter, D as forEachResolvedRelation, M as relationStaticFilter, O as hasRelationOp, S as REL_FILTER_MAX_NODES, T as containsRelationFilter, U as isFieldRef, W as translateQueryTree, k as isResolvedRelationFilter, w as andFilters, x as REL_FILTER_MAX_DEPTH } from "./nested-writer-D35UsDBT.mjs";
+import { a as aggregateExpressionsNotSupported, c as isConflict, l as spaceClosedError, n as CasMismatchError, o as aggregateFailure, r as DbError, s as bucketTimeZoneUnavailable, t as CasExhaustedError } from "./db-error-Az85UhTX.mjs";
+import { $ as FieldMappingStrategy, A as geoIndexNotFoundMessage, B as classifyQueryPath, C as ALL_VIEW_CAPABILITIES, D as NativeIntegrity, E as IntegrityStrategy, F as acceptedOperatorsHint, G as guardPath, H as groupSourceVerdict, I as assertGeoPoint, J as narrowerFilterOps, K as guardPaths, L as bucketSourceVerdict, M as vectorIndexNotFoundMessage, N as ADAPTER_FILTER_REASON, O as AtscriptDbReadable, P as ENCRYPTED_REASON, Q as DocumentFieldMapper, R as canFilterLeaf, S as ALL_BUCKET_UNITS, T as createFailureCollector, U as guardAggregate, V as collectQueryPaths, W as guardFilter, X as unsupportedOperatorMessage, Y as sortFieldNames, Z as RelationalFieldMapper, _ as isViewType, at as aliasTargetOf, b as decomposePatch, ct as jsonValueAncestor, dt as NoopLogger, et as UniquSelect, f as fkColumns, g as isAtscriptDbView, h as AtscriptDbView, it as isGeoPointType, j as searchIndexNotFoundMessage, k as resolveDesignType, lt as normalizeComputedSelect, n as isColumnTypeChanged, nt as TableMetadata, ot as isBucketableField, q as guardQuery, rt as isGeoIndexableType, st as isJsonValueField, tt as numericOperandProblem, ut as resolveCalendarBuckets, v as AtscriptDbTable, w as BaseDbAdapter, x as ApplicationIntegrity, y as assertNoVersionWrites, z as checkHavingKeys } from "./column-diff-Cp6ZoyRE.mjs";
+import { n as ALL_AGGREGATE_FNS } from "./aggregate-fns-CyaZyb9I.mjs";
+import { A as isResolvedRelationFilter, C as REL_FILTER_MAX_NODES, E as containsRelationFilter, G as isFieldRef, K as translateQueryTree, N as relationStaticFilter, O as forEachResolvedRelation, S as REL_FILTER_MAX_DEPTH, T as andFilters, V as tableNameOf, W as evaluateExpr, k as hasRelationOp, w as ResolvedRelationFilter, x as uniqueKeyTuple } from "./nested-writer-CUBoq1ZO.mjs";
 import { t as DB_ENTITY_ANNOTATIONS } from "./derived-rules-0sKn4f5C.mjs";
 import { a as isPlainObject, i as isEmptyObject, n as findAncestorInSet, o as selfOrAncestor, r as getPath, t as deletePath } from "./object-TkiJQ-Dp.mjs";
 import { t as DEFAULT_DB_SPACE } from "./consts-C_-5_pFq.mjs";
 import { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, getDbFieldOp, isDbFieldOp, reconcileCas, separateCas, separateFieldOps } from "./ops.mjs";
-import { a as forceNavNonOptional, c as getKeyProps, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator } from "./validator-Clu2q_7z.mjs";
+import { a as forceNavNonOptional, c as getKeyProps, o as isNavRelation, r as buildValidationContext, s as createDbValidatorPlugin, t as buildDbValidator } from "./validator-BTiIOTKP.mjs";
 import { isAnnotatedType } from "@atscript/typescript/utils";
 import { RELATION_OPS, computeInsights, isPrimitive, isRelationOp, walkFilter } from "@uniqu/core";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
@@ -235,8 +235,14 @@ var DbSpace = class {
 	_readables = /* @__PURE__ */ new WeakMap();
 	/** All tables created in this space — used for reverse FK lookup during cascade. */
 	_allTables = /* @__PURE__ */ new Set();
+	/** Every table / view handle the space created — flagged closed on {@link close}. */
+	_handles = /* @__PURE__ */ new Set();
 	/** Lazily created adapter for administrative ops (drop table/view) that don't need a registered readable. */
 	_adminAdapter;
+	/** Every adapter this space created (tables, views, admin) — disposed on close. */
+	_adapters = /* @__PURE__ */ new Set();
+	_onClose;
+	_closing;
 	logger;
 	/** Encryption service for `@db.encrypted` fields — validated eagerly at construction. */
 	_encryption;
@@ -251,6 +257,7 @@ var DbSpace = class {
 		else {
 			const options = loggerOrOptions ?? {};
 			this.logger = options.logger ?? NoopLogger;
+			this._onClose = options.onClose;
 			if (options.encryption) this._encryption = new DbEncryption(options.encryption);
 		}
 	}
@@ -259,6 +266,7 @@ var DbSpace = class {
 	* appropriate instance. Uses `@db.view` or `@db.view.for` presence to distinguish.
 	*/
 	get(type, logger) {
+		this._assertOpen();
 		if (isViewType(type)) return this.getView(type, logger);
 		return this.getTable(type, logger);
 	}
@@ -267,6 +275,7 @@ var DbSpace = class {
 	* Creates the table + adapter on first access, caches for subsequent calls.
 	*/
 	getTable(type, logger) {
+		this._assertOpen();
 		let readable = this._readables.get(type);
 		if (!readable) {
 			assertNotAlias(type);
@@ -279,6 +288,7 @@ var DbSpace = class {
 			readable.setFkLookupResolver((tableName) => this._getFkLookupTarget(tableName));
 			readable.setEncryption(this._encryption);
 			this._readables.set(type, readable);
+			this._handles.add(readable);
 		}
 		return readable;
 	}
@@ -287,12 +297,14 @@ var DbSpace = class {
 	* Creates the view + adapter on first access, caches for subsequent calls.
 	*/
 	getView(type, logger) {
+		this._assertOpen();
 		let readable = this._readables.get(type);
 		if (!readable) {
 			assertNotAlias(type);
 			readable = new AtscriptDbView(type, this._createAdapter(), logger || this.logger, (t) => this.get(t));
 			readable.setEncryption(this._encryption);
 			this._readables.set(type, readable);
+			this._handles.add(readable);
 		}
 		return readable;
 	}
@@ -301,6 +313,7 @@ var DbSpace = class {
 	* Creates the table/view + adapter on first access if needed.
 	*/
 	getAdapter(type) {
+		this._assertOpen();
 		return this.get(type).dbAdapter;
 	}
 	/**
@@ -308,6 +321,7 @@ var DbSpace = class {
 	* See `BaseDbAdapter.dropTableByName` for an adapter that does not support it.
 	*/
 	async dropTableByName(tableName) {
+		this._assertOpen();
 		await this._getAdminAdapter().dropTableByName(tableName);
 	}
 	/**
@@ -315,6 +329,7 @@ var DbSpace = class {
 	* See `BaseDbAdapter.dropViewByName` for an adapter that does not support it.
 	*/
 	async dropViewByName(viewName) {
+		this._assertOpen();
 		await this._getAdminAdapter().dropViewByName(viewName);
 	}
 	/**
@@ -323,6 +338,7 @@ var DbSpace = class {
 	* @since 0.1.128
 	*/
 	async dropTablesByName(tableNames) {
+		this._assertOpen();
 		await this._getAdminAdapter().dropTablesByName(tableNames);
 	}
 	/**
@@ -332,6 +348,7 @@ var DbSpace = class {
 	* @since 0.1.128
 	*/
 	async getReferencingForeignKeys(tableName) {
+		this._assertOpen();
 		return this._getAdminAdapter().getReferencingForeignKeys?.(tableName);
 	}
 	/**
@@ -350,8 +367,46 @@ var DbSpace = class {
 	_createAdapter() {
 		const adapter = this.adapterFactory();
 		adapter.registerSpace?.(this);
+		this._adapters.add(adapter);
 		return adapter;
 	}
+	/** `true` once {@link close} was called. @since 0.1.148 */
+	get closed() {
+		return this._closing !== void 0;
+	}
+	/** Throws `SPACE_CLOSED` once the space is closed. */
+	_assertOpen() {
+		if (this._closing) throw spaceClosedError();
+	}
+	/**
+	* 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() {
+		return this._closing ??= this._doClose();
+	}
+	async _doClose() {
+		for (const readable of this._handles) readable._spaceClosed = true;
+		const errors = [];
+		for (const adapter of this._adapters) try {
+			await adapter.dispose?.();
+		} catch (error) {
+			errors.push(error);
+		}
+		try {
+			await this._onClose?.();
+		} catch (error) {
+			errors.push(error);
+		}
+		if (errors.length > 0) throw aggregateFailure("DbSpace close failed", errors);
+	}
 	/**
 	* Finds all child tables with FKs pointing to the given parent table name.
 	* Accesses `table.foreignKeys` which triggers `_flatten()` if needed.
@@ -375,6 +430,9 @@ var DbSpace = class {
 		for (const table of this._allTables) if (table.tableName === tableName) return { count: (filter) => table.count({ filter }) };
 	}
 };
+if (typeof Symbol.asyncDispose === "symbol") DbSpace.prototype[Symbol.asyncDispose] = function() {
+	return this.close();
+};
 //#endregion
 //#region src/table/db-entity.ts
 /**
@@ -394,4 +452,4 @@ function isDbEntityType(value) {
 	return DB_ENTITY_ANNOTATIONS.some((name) => value.metadata.has(name));
 }
 //#endregion
-export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, CasMismatchError, DEFAULT_DB_SPACE, DbEncryption, DbError, DbSpace, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, IntegrityStrategy, NativeIntegrity, NoopLogger, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, RelationalFieldMapper, ResolvedRelationFilter, TableMetadata, UniquSelect, acceptedOperatorsHint, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, deletePath, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, tableNameOf, translateQueryTree, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };
+export { $cas, $dec, $inc, $insert, $mul, $remove, $replace, $update, $upsert, ADAPTER_FILTER_REASON, ALL_AGGREGATE_FNS, ALL_BUCKET_UNITS, ALL_VIEW_CAPABILITIES, ApplicationIntegrity, AtscriptDbReadable, AtscriptDbTable, AtscriptDbView, BaseDbAdapter, CasExhaustedError, CasMismatchError, DEFAULT_DB_SPACE, DbEncryption, DbError, DbSpace, DocumentFieldMapper, ENCRYPTED_REASON, FieldMappingStrategy, IntegrityStrategy, NativeIntegrity, NoopLogger, RELATION_OPS, REL_FILTER_MAX_DEPTH, REL_FILTER_MAX_NODES, RelationalFieldMapper, ResolvedRelationFilter, TableMetadata, UniquSelect, acceptedOperatorsHint, aggregateExpressionsNotSupported, aggregateFailure, aliasTargetOf, andFilters, assertGeoPoint, assertNoVersionWrites, bucketSourceVerdict, bucketTimeZoneUnavailable, buildDbValidator, buildValidationContext, canFilterLeaf, checkHavingKeys, classifyQueryPath, collectQueryPaths, computeInsights, containsRelationFilter, createDbValidatorPlugin, createFailureCollector, decomposePatch, deletePath, evaluateExpr, findAncestorInSet, fkColumns, forEachResolvedRelation, forceNavNonOptional, geoIndexNotFoundMessage, getDbFieldOp, getKeyProps, getPath, groupSourceVerdict, guardAggregate, guardFilter, guardPath, guardPaths, guardQuery, hasRelationOp, isAtscriptDbView, isBucketableField, isColumnTypeChanged, isConflict, isDbEntityType, isDbFieldOp, isEmptyObject, isFieldRef, isGeoIndexableType, isGeoPointType, isJsonValueField, isNavRelation, isPlainObject, isPrimitive, isRelationOp, isResolvedRelationFilter, isViewType, jsonValueAncestor, narrowerFilterOps, normalizeComputedSelect, numericOperandProblem, reconcileCas, relationStaticFilter, resolveCalendarBuckets, resolveDesignType, searchIndexNotFoundMessage, selfOrAncestor, separateCas, separateFieldOps, sortFieldNames, tableNameOf, translateQueryTree, uniqueKeyTuple, unsupportedOperatorMessage, vectorIndexNotFoundMessage, walkFilter, withOptimisticRetry };

package/dist/{nested-writer-SqtYJHF0.cjs → nested-writer-BUQvk6QT.cjs}

@@ -1,4 +1,4 @@
-const require_db_error = require("./db-error-DTkkeu5b.cjs");
+const require_db_error = require("./db-error-DRQH4sLY.cjs");
 const require_object = require("./object-Djg28csK.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let _uniqu_core = require("@uniqu/core");
@@ -44,6 +44,40 @@ function walkViewExpr(expr, leaf) {
 	for (const arg of expr.args) walkViewExpr(arg, leaf);
 }
 /**
+* 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
+*/
+function evaluateExpr(expr, leaf) {
+	if (typeof expr === "number") return expr;
+	if ("field" in expr) {
+		const v = leaf(expr.field);
+		if (v === null || v === void 0) return null;
+		const n = Number(v);
+		return Number.isNaN(n) ? null : n;
+	}
+	if (expr.op === "coalesce") {
+		for (const arg of expr.args) {
+			const v = evaluateExpr(arg, leaf);
+			if (v !== null) return v;
+		}
+		return null;
+	}
+	const a = evaluateExpr(expr.args[0], leaf);
+	if (a === null) return null;
+	if (expr.op === "neg") return -a;
+	const b = evaluateExpr(expr.args[1], leaf);
+	if (b === null) return null;
+	switch (expr.op) {
+		case "+": return a + b;
+		case "-": return a - b;
+		case "*": return a * b;
+		default: return b === 0 ? null : a / b;
+	}
+}
+/**
 * Whether a computed-column expression may yield NULL: a `/` (division by
 * zero is NULL), a leaf for which `nullableLeaf` holds, or an operation over
 * a nullable operand — `coalesce` only when every argument is nullable.
@@ -594,8 +628,14 @@ function resolvePredicateMap(key, value, meta, depth) {
 }
 //#endregion
 //#region src/shared/keys.ts
-/** String form of a key value (an ObjectId stringifies to its hex, a bigint to its digits). */
+/**
+* String form of a key value, equal across driver representations: an
+* ObjectId stringifies to its hex, a bigint to its digits, a Date to its ISO
+* instant, a Buffer / Uint8Array to hex.
+*/
 function keyString(value) {
+	if (value instanceof Date) return Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString();
+	if (value instanceof Uint8Array) return Array.from(value, (b) => b.toString(16).padStart(2, "0")).join("");
 	return String(value);
 }
 /** Key equality across driver representations (number vs numeric string, ObjectId vs hex). */
@@ -622,6 +662,20 @@ function rowMatchesKey(row, key) {
 	for (const field in key) if (!sameKey(require_object.getPath(row, field), key[field])) return false;
 	return true;
 }
+/**
+* Identity of the key tuple `fields` of `row` for uniqueness checks, or
+* `undefined` when any component is null / missing (a NULL never collides).
+* Equal across driver representations (see {@link keyString}).
+*/
+function uniqueKeyTuple(row, fields) {
+	const parts = [];
+	for (const field of fields) {
+		const value = require_object.getPath(row, field);
+		if (value === void 0 || value === null) return void 0;
+		parts.push(keyString(value));
+	}
+	return JSON.stringify(parts);
+}
 //#endregion
 //#region src/table/error-utils.ts
 /**
@@ -1543,6 +1597,12 @@ Object.defineProperty(exports, "enrichFkViolation", {
 		return enrichFkViolation;
 	}
 });
+Object.defineProperty(exports, "evaluateExpr", {
+	enumerable: true,
+	get: function() {
+		return evaluateExpr;
+	}
+});
 Object.defineProperty(exports, "findFKEntryForRelation", {
 	enumerable: true,
 	get: function() {
@@ -1675,6 +1735,12 @@ Object.defineProperty(exports, "translateQueryTree", {
 		return translateQueryTree;
 	}
 });
+Object.defineProperty(exports, "uniqueKeyTuple", {
+	enumerable: true,
+	get: function() {
+		return uniqueKeyTuple;
+	}
+});
 Object.defineProperty(exports, "validateBatch", {
 	enumerable: true,
 	get: function() {

package/dist/{nested-writer-D35UsDBT.mjs → nested-writer-CUBoq1ZO.mjs}

@@ -1,4 +1,4 @@
-import { i as DepthLimitExceededError, r as DbError } from "./db-error-D5uilS_A.mjs";
+import { i as DepthLimitExceededError, r as DbError } from "./db-error-Az85UhTX.mjs";
 import { a as isPlainObject, r as getPath } from "./object-TkiJQ-Dp.mjs";
 import { ValidatorError } from "@atscript/typescript/utils";
 import { isRelationOp } from "@uniqu/core";
@@ -44,6 +44,40 @@ function walkViewExpr(expr, leaf) {
 	for (const arg of expr.args) walkViewExpr(arg, leaf);
 }
 /**
+* 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
+*/
+function evaluateExpr(expr, leaf) {
+	if (typeof expr === "number") return expr;
+	if ("field" in expr) {
+		const v = leaf(expr.field);
+		if (v === null || v === void 0) return null;
+		const n = Number(v);
+		return Number.isNaN(n) ? null : n;
+	}
+	if (expr.op === "coalesce") {
+		for (const arg of expr.args) {
+			const v = evaluateExpr(arg, leaf);
+			if (v !== null) return v;
+		}
+		return null;
+	}
+	const a = evaluateExpr(expr.args[0], leaf);
+	if (a === null) return null;
+	if (expr.op === "neg") return -a;
+	const b = evaluateExpr(expr.args[1], leaf);
+	if (b === null) return null;
+	switch (expr.op) {
+		case "+": return a + b;
+		case "-": return a - b;
+		case "*": return a * b;
+		default: return b === 0 ? null : a / b;
+	}
+}
+/**
 * Whether a computed-column expression may yield NULL: a `/` (division by
 * zero is NULL), a leaf for which `nullableLeaf` holds, or an operation over
 * a nullable operand — `coalesce` only when every argument is nullable.
@@ -594,8 +628,14 @@ function resolvePredicateMap(key, value, meta, depth) {
 }
 //#endregion
 //#region src/shared/keys.ts
-/** String form of a key value (an ObjectId stringifies to its hex, a bigint to its digits). */
+/**
+* String form of a key value, equal across driver representations: an
+* ObjectId stringifies to its hex, a bigint to its digits, a Date to its ISO
+* instant, a Buffer / Uint8Array to hex.
+*/
 function keyString(value) {
+	if (value instanceof Date) return Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString();
+	if (value instanceof Uint8Array) return Array.from(value, (b) => b.toString(16).padStart(2, "0")).join("");
 	return String(value);
 }
 /** Key equality across driver representations (number vs numeric string, ObjectId vs hex). */
@@ -622,6 +662,20 @@ function rowMatchesKey(row, key) {
 	for (const field in key) if (!sameKey(getPath(row, field), key[field])) return false;
 	return true;
 }
+/**
+* Identity of the key tuple `fields` of `row` for uniqueness checks, or
+* `undefined` when any component is null / missing (a NULL never collides).
+* Equal across driver representations (see {@link keyString}).
+*/
+function uniqueKeyTuple(row, fields) {
+	const parts = [];
+	for (const field of fields) {
+		const value = getPath(row, field);
+		if (value === void 0 || value === null) return void 0;
+		parts.push(keyString(value));
+	}
+	return JSON.stringify(parts);
+}
 //#endregion
 //#region src/table/error-utils.ts
 /**
@@ -1417,4 +1471,4 @@ async function viaReplace(via, targets, parentPK, maxDepth, depth) {
 	await viaLinkTargets(via, targets, parentPK, maxDepth, depth);
 }
 //#endregion
-export { noteRelationFilter as A, tableNameOf as B, ResolvedRelationFilter as C, forEachResolvedRelation as D, createRelationFilterHost as E, findFKEntryForRelation as F, viewExprNullable as G, computedOperands as H, findFKForRelation as I, walkViewExpr as K, findRemoteFK as L, relationStaticFilter as M, resolveRelationFilterTree as N, hasRelationOp as O, compositeKey as P, resolveRelationTargetTable as R, REL_FILTER_MAX_NODES as S, containsRelationFilter as T, isFieldRef as U, computeOf as V, translateQueryTree as W, remapDeleteFkViolation as _, batchPatchNestedFrom as a, sameKey as b, batchReplaceNestedFrom as c, checkDepthOverflow as d, planNestedFromVia as f, enrichFkViolation as g, validateBatch as h, batchInsertNestedVia as i, relGuardState as j, isResolvedRelationFilter as k, batchReplaceNestedTo as l, preValidateNestedFrom as m, batchInsertNestedFrom as n, batchPatchNestedTo as o, planPatchNestedTo as p, batchInsertNestedTo as r, batchPatchNestedVia as s, applyPatchNestedTo as t, batchReplaceNestedVia as u, pkTupleKey as v, andFilters as w, REL_FILTER_MAX_DEPTH as x, rowMatchesKey as y, slicePerGroup as z };
+export { isResolvedRelationFilter as A, slicePerGroup as B, REL_FILTER_MAX_NODES as C, createRelationFilterHost as D, containsRelationFilter as E, compositeKey as F, isFieldRef as G, computeOf as H, findFKEntryForRelation as I, walkViewExpr as J, translateQueryTree as K, findFKForRelation as L, relGuardState as M, relationStaticFilter as N, forEachResolvedRelation as O, resolveRelationFilterTree as P, findRemoteFK as R, REL_FILTER_MAX_DEPTH as S, andFilters as T, computedOperands as U, tableNameOf as V, evaluateExpr as W, remapDeleteFkViolation as _, batchPatchNestedFrom as a, sameKey as b, batchReplaceNestedFrom as c, checkDepthOverflow as d, planNestedFromVia as f, enrichFkViolation as g, validateBatch as h, batchInsertNestedVia as i, noteRelationFilter as j, hasRelationOp as k, batchReplaceNestedTo as l, preValidateNestedFrom as m, batchInsertNestedFrom as n, batchPatchNestedTo as o, planPatchNestedTo as p, viewExprNullable as q, batchInsertNestedTo as r, batchPatchNestedVia as s, applyPatchNestedTo as t, batchReplaceNestedVia as u, pkTupleKey as v, ResolvedRelationFilter as w, uniqueKeyTuple as x, rowMatchesKey as y, resolveRelationTargetTable as z };

package/dist/numeric-operand-B1jKH7x5.mjs

@@ -0,0 +1,21 @@
+//#region src/shared/numeric-operand.ts
+/** Primitive tags of timestamps (MySQL may store them as native `TIMESTAMP`). */
+const TIMESTAMP_TAGS = [
+	"timestamp",
+	"created",
+	"updated"
+];
+/**
+* Why a field cannot be an arithmetic operand, or `undefined` when it can: it
+* must be a `number` — not a decimal (exact; an expression is IEEE double) and
+* not a timestamp-tagged number. The one rule behind `@db.compute` (declared,
+* from the `.as` source) and query-time arithmetic (from the runtime
+* descriptor), so the two cannot diverge. Storage rules (`@db.ignore`,
+* encrypted, JSON) stay with the callers.
+*/
+function numericTypeProblem({ base, tags }) {
+	if (base !== "number" && base !== "integer") return base === "decimal" ? "is a decimal" : `is a ${base}`;
+	if (tags && TIMESTAMP_TAGS.some((t) => tags.has(t))) return "is a timestamp";
+}
+//#endregion
+export { numericTypeProblem as t };

package/dist/numeric-operand-DKfiRLYp.cjs

@@ -0,0 +1,26 @@
+//#region src/shared/numeric-operand.ts
+/** Primitive tags of timestamps (MySQL may store them as native `TIMESTAMP`). */
+const TIMESTAMP_TAGS = [
+	"timestamp",
+	"created",
+	"updated"
+];
+/**
+* Why a field cannot be an arithmetic operand, or `undefined` when it can: it
+* must be a `number` — not a decimal (exact; an expression is IEEE double) and
+* not a timestamp-tagged number. The one rule behind `@db.compute` (declared,
+* from the `.as` source) and query-time arithmetic (from the runtime
+* descriptor), so the two cannot diverge. Storage rules (`@db.ignore`,
+* encrypted, JSON) stay with the callers.
+*/
+function numericTypeProblem({ base, tags }) {
+	if (base !== "number" && base !== "integer") return base === "decimal" ? "is a decimal" : `is a ${base}`;
+	if (tags && TIMESTAMP_TAGS.some((t) => tags.has(t))) return "is a timestamp";
+}
+//#endregion
+Object.defineProperty(exports, "numericTypeProblem", {
+	enumerable: true,
+	get: function() {
+		return numericTypeProblem;
+	}
+});

package/dist/ops.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_error = require("./db-error-DTkkeu5b.cjs");
+const require_db_error = require("./db-error-DRQH4sLY.cjs");
 //#region src/ops.ts
 /** Increment a numeric field by `value` (default 1). */
 function $inc(value = 1) {

package/dist/ops.mjs

@@ -1,4 +1,4 @@
-import { r as DbError } from "./db-error-D5uilS_A.mjs";
+import { r as DbError } from "./db-error-Az85UhTX.mjs";
 //#region src/ops.ts
 /** Increment a numeric field by `value` (default 1). */
 function $inc(value = 1) {