@atscript/db 0.1.152 → 0.1.153

package/dist/plugin.cjs

@@ -33,7 +33,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_aggregate_fns = require("./aggregate-fns-C-UJRobm.cjs");
+const require_aggregate_fns = require("./aggregate-fns-DFtKAv7Q.cjs");
 const require_search_fields = require("./search-fields-DwrsJUC1.cjs");
 require("./consts-BzRfCcH2.cjs");
 const require_validation_utils = require("./validation-utils-debIYpq0.cjs");
@@ -1695,6 +1695,52 @@ const dbSearchAnnotations = { search: {
 	})
 } };
 //#endregion
+//#region src/plugin/annotations/sort.ts
+/**
+* `@db.sort.nulls` (since 0.1.153) — a field's default NULL placement when a
+* read sorts by it without a `$nulls` entry for it.
+*/
+const dbSortAnnotations = { sort: { nulls: new _atscript_core.AnnotationSpec({
+	description: "Default **NULL placement** when a read sorts by this field and the request names none (`$nulls` control, URL suffix `$sort=-closedAt:last`).\n\n- **`'first'`** — rows where the field is NULL (or missing) come before every value, in both sort directions\n- **`'last'`** — they come after every value, in both directions\n\nWithout it (and without `$nulls`) NULL placement is the database's own: first in ascending order on SQLite, MySQL, MongoDB and the in-memory adapter, last on PostgreSQL. Applies to `$sort` and to the `$rowOrder` of `first()` / `last()`. Only optional fields can be NULL — on a required table field it has no effect. On PostgreSQL, MySQL and MongoDB a placement the engine does not produce natively costs the index its ORDER BY (a sort step instead).\n\n**Example:**\n```atscript\n@db.sort.nulls 'last'\nclosedAt?: number.timestamp\n```\n",
+	nodeType: ["prop"],
+	passedWhenReferred: false,
+	multiple: false,
+	argument: {
+		name: "placement",
+		type: "string",
+		values: ["first", "last"],
+		description: "Where NULL goes: 'first' (before every value) or 'last' (after every value), whatever the sort direction."
+	},
+	validate(token, _args, doc) {
+		const errors = [];
+		const field = token.parentNode;
+		const fail = (message, severity = 1) => errors.push({
+			message,
+			severity,
+			range: token.range
+		});
+		if (field.countAnnotations("db.json") > 0) {
+			fail("@db.sort.nulls on a @db.json field — JSON-stored fields are not sortable");
+			return errors;
+		}
+		if (field.countAnnotations("db.encrypted") > 0) {
+			fail("@db.sort.nulls on a @db.encrypted field — encrypted fields are not sortable");
+			return errors;
+		}
+		const def = field.getDefinition();
+		let leaf = def;
+		if (def && (0, _atscript_core.isRef)(def)) leaf = doc.unwindType(def.id, def.chain)?.def;
+		const base = require_validation_utils.primitiveBaseType(leaf);
+		if (def && ((0, _atscript_core.isArray)(def) || (0, _atscript_core.isStructure)(def)) || leaf && ((0, _atscript_core.isArray)(leaf) || (0, _atscript_core.isStructure)(leaf) || (0, _atscript_core.isInterface)(leaf)) || leaf && (0, _atscript_core.isPrimitive)(leaf) && (base === "array" || base === "object")) {
+			fail("@db.sort.nulls needs a sortable scalar field — not an object or an array");
+			return errors;
+		}
+		const owner = require_validation_utils.getDbTableOwner(token);
+		if (!field.has("optional") && owner && owner.countAnnotations("db.table") > 0 && field.ownerNode?.ownerNode === owner) fail("@db.sort.nulls on a required field has no effect — the field is never NULL; make it optional (field?: …) or remove the annotation", 2);
+		return errors;
+	}
+}) } };
+//#endregion
 //#region src/plugin/annotations/table.ts
 const dbTableAnnotations = {
 	table: {
@@ -2286,6 +2332,7 @@ const dbPlugin = (options) => ({
 				agg: dbAggAnnotations.agg,
 				compute: dbComputeAnnotations.compute,
 				search: dbSearchAnnotations.search,
+				sort: dbSortAnnotations.sort,
 				amount: dbAmountAnnotations.amount,
 				unit: dbUnitAnnotations.unit
 			} },

package/dist/plugin.mjs

@@ -1,4 +1,4 @@
-import { i as NULL_WHEN_EMPTY_AGGREGATE_FNS, o as SUPPORTED_AGGREGATE_FNS, t as AGG_ANNOTATIONS } from "./aggregate-fns-CyaZyb9I.mjs";
+import { i as NULL_WHEN_EMPTY_AGGREGATE_FNS, o as SUPPORTED_AGGREGATE_FNS, t as AGG_ANNOTATIONS } from "./aggregate-fns-B_sgl4mB.mjs";
 import { a as DERIVED_INCOMPATIBLE, i as DB_ENTITY_ANNOTATIONS, o as JSON_LEAF_TYPES, r as numericTypeProblem } from "./search-fields-DBIZKwyb.mjs";
 import "./consts-C_-5_pFq.mjs";
 import { C as validateFieldBaseType, S as validateExclusiveWith, _ as getParentTypeName, a as hasAnyViewAnnotation, b as refActionAnnotation, d as viewJoins, f as viewScopeTypes, g as getParentStruct, h as getNavTargetTypeName, i as forEachFieldRef, l as validateQueryScope, m as getDbTableOwner, n as findFKFieldsPointingTo, o as isAliasDecl, p as getAnnotationAlias, r as findViewCycle, s as isDbSourceDecl, t as earlierJoinTargets, u as validateRefArgument, v as integerMemberIndexProblem, w as validateSiblingStringField, x as searchFieldVerdict, y as primitiveBaseType } from "./validation-utils-DqZAH6aT.mjs";
@@ -1659,6 +1659,52 @@ const dbSearchAnnotations = { search: {
 	})
 } };
 //#endregion
+//#region src/plugin/annotations/sort.ts
+/**
+* `@db.sort.nulls` (since 0.1.153) — a field's default NULL placement when a
+* read sorts by it without a `$nulls` entry for it.
+*/
+const dbSortAnnotations = { sort: { nulls: new AnnotationSpec({
+	description: "Default **NULL placement** when a read sorts by this field and the request names none (`$nulls` control, URL suffix `$sort=-closedAt:last`).\n\n- **`'first'`** — rows where the field is NULL (or missing) come before every value, in both sort directions\n- **`'last'`** — they come after every value, in both directions\n\nWithout it (and without `$nulls`) NULL placement is the database's own: first in ascending order on SQLite, MySQL, MongoDB and the in-memory adapter, last on PostgreSQL. Applies to `$sort` and to the `$rowOrder` of `first()` / `last()`. Only optional fields can be NULL — on a required table field it has no effect. On PostgreSQL, MySQL and MongoDB a placement the engine does not produce natively costs the index its ORDER BY (a sort step instead).\n\n**Example:**\n```atscript\n@db.sort.nulls 'last'\nclosedAt?: number.timestamp\n```\n",
+	nodeType: ["prop"],
+	passedWhenReferred: false,
+	multiple: false,
+	argument: {
+		name: "placement",
+		type: "string",
+		values: ["first", "last"],
+		description: "Where NULL goes: 'first' (before every value) or 'last' (after every value), whatever the sort direction."
+	},
+	validate(token, _args, doc) {
+		const errors = [];
+		const field = token.parentNode;
+		const fail = (message, severity = 1) => errors.push({
+			message,
+			severity,
+			range: token.range
+		});
+		if (field.countAnnotations("db.json") > 0) {
+			fail("@db.sort.nulls on a @db.json field — JSON-stored fields are not sortable");
+			return errors;
+		}
+		if (field.countAnnotations("db.encrypted") > 0) {
+			fail("@db.sort.nulls on a @db.encrypted field — encrypted fields are not sortable");
+			return errors;
+		}
+		const def = field.getDefinition();
+		let leaf = def;
+		if (def && isRef(def)) leaf = doc.unwindType(def.id, def.chain)?.def;
+		const base = primitiveBaseType(leaf);
+		if (def && (isArray(def) || isStructure(def)) || leaf && (isArray(leaf) || isStructure(leaf) || isInterface(leaf)) || leaf && isPrimitive(leaf) && (base === "array" || base === "object")) {
+			fail("@db.sort.nulls needs a sortable scalar field — not an object or an array");
+			return errors;
+		}
+		const owner = getDbTableOwner(token);
+		if (!field.has("optional") && owner && owner.countAnnotations("db.table") > 0 && field.ownerNode?.ownerNode === owner) fail("@db.sort.nulls on a required field has no effect — the field is never NULL; make it optional (field?: …) or remove the annotation", 2);
+		return errors;
+	}
+}) } };
+//#endregion
 //#region src/plugin/annotations/table.ts
 const dbTableAnnotations = {
 	table: {
@@ -2250,6 +2296,7 @@ const dbPlugin = (options) => ({
 				agg: dbAggAnnotations.agg,
 				compute: dbComputeAnnotations.compute,
 				search: dbSearchAnnotations.search,
+				sort: dbSortAnnotations.sort,
 				amount: dbAmountAnnotations.amount,
 				unit: dbUnitAnnotations.unit
 			} },

package/dist/rel.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_nested_writer = require("./nested-writer-BzbOPSUp.cjs");
-const require_relation_loader = require("./relation-loader-fNjHgBMs.cjs");
+const require_nested_writer = require("./nested-writer-Bl1SZS7x.cjs");
+const require_relation_loader = require("./relation-loader-DeulLrAw.cjs");
 exports.applyPatchNestedTo = require_nested_writer.applyPatchNestedTo;
 exports.batchInsertNestedFrom = require_nested_writer.batchInsertNestedFrom;
 exports.batchInsertNestedTo = require_nested_writer.batchInsertNestedTo;

package/dist/rel.d.cts

@@ -1,6 +1,6 @@
-import { Hn as TGenericLogger, Pt as TTableResolver, U as TDbForeignKey, Wt as TableMetadata, Yt as BaseDbAdapter, et as TDbRelation, h as AtscriptDbWritable, m as AtscriptDbTableLike, zt as TWriteTableResolver } from "./buckets-tzd8iIM2.cjs";
+import { Gn as TGenericLogger, It as TTableResolver, Kt as TableMetadata, Vt as TWriteTableResolver, W as TDbForeignKey, Zt as BaseDbAdapter, h as AtscriptDbWritable, m as AtscriptDbTableLike, nt as TDbRelation } from "./buckets-jy8BfswO.cjs";
 import { t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.cjs";
-import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-DxIZKvnJ.cjs";
+import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-D_8bydc2.cjs";
 import { FilterExpr, WithRelation } from "@uniqu/core";
 import { Validator } from "@atscript/typescript/utils";
 

package/dist/rel.d.mts

@@ -1,6 +1,6 @@
-import { Hn as TGenericLogger, Pt as TTableResolver, U as TDbForeignKey, Wt as TableMetadata, Yt as BaseDbAdapter, et as TDbRelation, h as AtscriptDbWritable, m as AtscriptDbTableLike, zt as TWriteTableResolver } from "./buckets-Cb0zmhDc.mjs";
+import { Gn as TGenericLogger, It as TTableResolver, Kt as TableMetadata, Vt as TWriteTableResolver, W as TDbForeignKey, Zt as BaseDbAdapter, h as AtscriptDbWritable, m as AtscriptDbTableLike, nt as TDbRelation } from "./buckets-CBKL_ZWE.mjs";
 import { t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.mjs";
-import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-Bdo4NHPC.mjs";
+import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-BUsxNNGU.mjs";
 import { Validator } from "@atscript/typescript/utils";
 import { FilterExpr, WithRelation } from "@uniqu/core";
 

package/dist/rel.mjs

@@ -1,3 +1,3 @@
-import { t as loadRelationsImpl } from "./relation-loader-DYab07lw.mjs";
-import { B as resolveRelationTargetTable, R as findFKForRelation, a as batchPatchNestedFrom, c as batchReplaceNestedFrom, d as checkDepthOverflow, f as planNestedFromVia, h as validateBatch, i as batchInsertNestedVia, l as batchReplaceNestedTo, m as preValidateNestedFrom, n as batchInsertNestedFrom, o as batchPatchNestedTo, p as planPatchNestedTo, r as batchInsertNestedTo, s as batchPatchNestedVia, t as applyPatchNestedTo, u as batchReplaceNestedVia, z as findRemoteFK } from "./nested-writer-cvbVAkNo.mjs";
+import { t as loadRelationsImpl } from "./relation-loader-CNBMPfRr.mjs";
+import { B as resolveRelationTargetTable, R as findFKForRelation, a as batchPatchNestedFrom, c as batchReplaceNestedFrom, d as checkDepthOverflow, f as planNestedFromVia, h as validateBatch, i as batchInsertNestedVia, l as batchReplaceNestedTo, m as preValidateNestedFrom, n as batchInsertNestedFrom, o as batchPatchNestedTo, p as planPatchNestedTo, r as batchInsertNestedTo, s as batchPatchNestedVia, t as applyPatchNestedTo, u as batchReplaceNestedVia, z as findRemoteFK } from "./nested-writer-BOj_c_lI.mjs";
 export { applyPatchNestedTo, batchInsertNestedFrom, batchInsertNestedTo, batchInsertNestedVia, batchPatchNestedFrom, batchPatchNestedTo, batchPatchNestedVia, batchReplaceNestedFrom, batchReplaceNestedTo, batchReplaceNestedVia, checkDepthOverflow, findFKForRelation, findRemoteFK, loadRelationsImpl, planNestedFromVia, planPatchNestedTo, preValidateNestedFrom, resolveRelationTargetTable, validateBatch };

package/dist/{relation-helpers-Bdo4NHPC.d.mts → relation-helpers-BUsxNNGU.d.mts}

@@ -1,4 +1,4 @@
-import { U as TDbForeignKey, et as TDbRelation } from "./buckets-Cb0zmhDc.mjs";
+import { W as TDbForeignKey, nt as TDbRelation } from "./buckets-CBKL_ZWE.mjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/rel/relation-helpers.d.ts

package/dist/{relation-helpers-DxIZKvnJ.d.cts → relation-helpers-D_8bydc2.d.cts}

@@ -1,4 +1,4 @@
-import { U as TDbForeignKey, et as TDbRelation } from "./buckets-tzd8iIM2.cjs";
+import { W as TDbForeignKey, nt as TDbRelation } from "./buckets-jy8BfswO.cjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/rel/relation-helpers.d.ts

package/dist/{relation-loader-DYab07lw.mjs → relation-loader-CNBMPfRr.mjs}

@@ -1,4 +1,4 @@
-import { B as resolveRelationTargetTable, E as andFilters, I as compositeKey, P as relationStaticFilter, R as findFKForRelation, V as slicePerGroup, z as findRemoteFK } from "./nested-writer-cvbVAkNo.mjs";
+import { B as resolveRelationTargetTable, E as andFilters, I as compositeKey, P as relationStaticFilter, R as findFKForRelation, V as slicePerGroup, z as findRemoteFK } from "./nested-writer-BOj_c_lI.mjs";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
@@ -42,6 +42,7 @@ async function loadRelationsImpl(rows, withRelations, host) {
 		const flatRel = withRel;
 		const controls = { ...withRel.controls || {} };
 		if (flatRel.$sort && !controls.$sort) controls.$sort = flatRel.$sort;
+		if (flatRel.$nulls && !controls.$nulls) controls.$nulls = flatRel.$nulls;
 		if (flatRel.$limit !== null && flatRel.$limit !== void 0 && (controls.$limit === null || controls.$limit === void 0)) controls.$limit = flatRel.$limit;
 		if (flatRel.$skip !== null && flatRel.$skip !== void 0 && (controls.$skip === null || controls.$skip === void 0)) controls.$skip = flatRel.$skip;
 		if (flatRel.$select && !controls.$select) controls.$select = flatRel.$select;

package/dist/{relation-loader-fNjHgBMs.cjs → relation-loader-DeulLrAw.cjs}

@@ -1,4 +1,4 @@
-const require_nested_writer = require("./nested-writer-BzbOPSUp.cjs");
+const require_nested_writer = require("./nested-writer-Bl1SZS7x.cjs");
 //#region src/rel/relation-loader.ts
 var relation_loader_exports = /* @__PURE__ */ require("./plugin.cjs").__exportAll({
 	ensureSelectIncludesFields: () => ensureSelectIncludesFields,
@@ -30,6 +30,7 @@ async function loadRelationsImpl(rows, withRelations, host) {
 		const flatRel = withRel;
 		const controls = { ...withRel.controls || {} };
 		if (flatRel.$sort && !controls.$sort) controls.$sort = flatRel.$sort;
+		if (flatRel.$nulls && !controls.$nulls) controls.$nulls = flatRel.$nulls;
 		if (flatRel.$limit !== null && flatRel.$limit !== void 0 && (controls.$limit === null || controls.$limit === void 0)) controls.$limit = flatRel.$limit;
 		if (flatRel.$skip !== null && flatRel.$skip !== void 0 && (controls.$skip === null || controls.$skip === void 0)) controls.$skip = flatRel.$skip;
 		if (flatRel.$select && !controls.$select) controls.$select = flatRel.$select;

package/dist/sync.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_db_error = require("./db-error-DRQH4sLY.cjs");
-const require_column_diff = require("./column-diff-CU7KHj9-.cjs");
+const require_db_error = require("./db-error-JcfJqqpk.cjs");
+const require_column_diff = require("./column-diff-CbdWi_uZ.cjs");
 //#region src/schema/table-option-diff.ts
 /**
 * Computes the difference between desired and existing table options.

package/dist/sync.d.cts

@@ -1,5 +1,5 @@
-import { Dt as TPrimaryKeyChange, H as TDbFieldMeta, Hn as TGenericLogger, Nt as TTableOptionDiff, Ot as TReferencingForeignKey, Q as TDbObjectKind, Zt as DbSpace, _t as TExistingTableOption, ft as TDerivedChangeReason, gt as TExistingForeignKey, mt as TEnsureTableOptions } from "./buckets-tzd8iIM2.cjs";
-import { _ as computeTableSnapshot, a as hasForeignKeyChanges, b as snapshotToExistingTableOptions, c as TFieldSnapshot, d as TViewColumnSnapshot, f as TViewJoinSnapshot, g as computeTableHash, h as computeSchemaHash, i as fkKey, l as TForeignKeySnapshot, m as canonicalizeQueryNode, n as computeForeignKeyDiff, o as computeColumnDiff, p as TViewSnapshot, t as TForeignKeyDiff, u as TTableSnapshot, v as computeViewSnapshot, y as snapshotToExistingColumns } from "./fk-diff-Bw26lwSc.cjs";
+import { $t as DbSpace, At as TReferencingForeignKey, Ft as TTableOptionDiff, Gn as TGenericLogger, U as TDbFieldMeta, et as TDbObjectKind, gt as TEnsureTableOptions, kt as TPrimaryKeyChange, mt as TDerivedChangeReason, vt as TExistingForeignKey, yt as TExistingTableOption } from "./buckets-jy8BfswO.cjs";
+import { _ as computeTableSnapshot, a as hasForeignKeyChanges, b as snapshotToExistingTableOptions, c as TFieldSnapshot, d as TViewColumnSnapshot, f as TViewJoinSnapshot, g as computeTableHash, h as computeSchemaHash, i as fkKey, l as TForeignKeySnapshot, m as canonicalizeQueryNode, n as computeForeignKeyDiff, o as computeColumnDiff, p as TViewSnapshot, t as TForeignKeyDiff, u as TTableSnapshot, v as computeViewSnapshot, y as snapshotToExistingColumns } from "./fk-diff-D1mrLMjU.cjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/schema/sync-entry.d.ts

package/dist/sync.d.mts

@@ -1,5 +1,5 @@
-import { Dt as TPrimaryKeyChange, H as TDbFieldMeta, Hn as TGenericLogger, Nt as TTableOptionDiff, Ot as TReferencingForeignKey, Q as TDbObjectKind, Zt as DbSpace, _t as TExistingTableOption, ft as TDerivedChangeReason, gt as TExistingForeignKey, mt as TEnsureTableOptions } from "./buckets-Cb0zmhDc.mjs";
-import { _ as computeTableSnapshot, a as hasForeignKeyChanges, b as snapshotToExistingTableOptions, c as TFieldSnapshot, d as TViewColumnSnapshot, f as TViewJoinSnapshot, g as computeTableHash, h as computeSchemaHash, i as fkKey, l as TForeignKeySnapshot, m as canonicalizeQueryNode, n as computeForeignKeyDiff, o as computeColumnDiff, p as TViewSnapshot, t as TForeignKeyDiff, u as TTableSnapshot, v as computeViewSnapshot, y as snapshotToExistingColumns } from "./fk-diff-lcAnwvm9.mjs";
+import { $t as DbSpace, At as TReferencingForeignKey, Ft as TTableOptionDiff, Gn as TGenericLogger, U as TDbFieldMeta, et as TDbObjectKind, gt as TEnsureTableOptions, kt as TPrimaryKeyChange, mt as TDerivedChangeReason, vt as TExistingForeignKey, yt as TExistingTableOption } from "./buckets-CBKL_ZWE.mjs";
+import { _ as computeTableSnapshot, a as hasForeignKeyChanges, b as snapshotToExistingTableOptions, c as TFieldSnapshot, d as TViewColumnSnapshot, f as TViewJoinSnapshot, g as computeTableHash, h as computeSchemaHash, i as fkKey, l as TForeignKeySnapshot, m as canonicalizeQueryNode, n as computeForeignKeyDiff, o as computeColumnDiff, p as TViewSnapshot, t as TForeignKeyDiff, u as TTableSnapshot, v as computeViewSnapshot, y as snapshotToExistingColumns } from "./fk-diff-BIJ8l_hF.mjs";
 import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
 
 //#region src/schema/sync-entry.d.ts

package/dist/sync.mjs

@@ -1,5 +1,5 @@
-import { r as DbError } from "./db-error-Az85UhTX.mjs";
-import { _t as NoopLogger, a as computeTableHash, c as snapshotToExistingColumns, d as computeForeignKeyDiff, dt as aliasTargetOf, f as fkColumns, i as computeSchemaHash, l as snapshotToExistingTableOptions, m as hasForeignKeyChanges, o as computeTableSnapshot, p as fkKey, r as canonicalizeQueryNode, s as computeViewSnapshot, t as computeColumnDiff, u as viewSnapshotSources } from "./column-diff-CnyLjbQ8.mjs";
+import { r as DbError } from "./db-error-eSsQX7rt.mjs";
+import { _t as NoopLogger, a as computeTableHash, c as snapshotToExistingColumns, d as computeForeignKeyDiff, dt as aliasTargetOf, f as fkColumns, i as computeSchemaHash, l as snapshotToExistingTableOptions, m as hasForeignKeyChanges, o as computeTableSnapshot, p as fkKey, r as canonicalizeQueryNode, s as computeViewSnapshot, t as computeColumnDiff, u as viewSnapshotSources } from "./column-diff-DrE4ho_m.mjs";
 //#region src/schema/table-option-diff.ts
 /**
 * Computes the difference between desired and existing table options.

package/dist/{validator-tBNvM1qc.d.cts → validator-B3xlbrWf.d.cts}

@@ -14,7 +14,28 @@ type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" |
  * table lives on a different adapter, or the table was built without a
  * `DbSpace` (moost-db: 400). @since 0.1.147
  */
-| "REL_FILTER_NOT_SUPPORTED" /** The `DbSpace` was closed; the table/view handle can no longer be used (moost-db: 503). @since 0.1.148 */ | "SPACE_CLOSED" /** The adapter does not implement `insertManyIgnore` (moost-db: 400). @since 0.1.148 */ | "ON_CONFLICT_NOT_SUPPORTED" | "TX_WAIT_TIMEOUT";
+| "REL_FILTER_NOT_SUPPORTED" /** The `DbSpace` was closed; the table/view handle can no longer be used (moost-db: 503). @since 0.1.148 */ | "SPACE_CLOSED" /** The adapter does not implement `insertManyIgnore` (moost-db: 400). @since 0.1.148 */ | "ON_CONFLICT_NOT_SUPPORTED" | "TX_WAIT_TIMEOUT"
+/**
+ * The engine chose this transaction as a deadlock victim (MySQL errno 1213,
+ * PostgreSQL 40P01) and rolled it back. Retry the WHOLE transaction.
+ * `retryable` is `true`. @since 0.1.153
+ */
+| "DEADLOCK"
+/**
+ * A row lock was not granted in time (MySQL errno 1205
+ * `innodb_lock_wait_timeout`, PostgreSQL 55P03 `lock_timeout` / `NOWAIT`).
+ * The statement failed; MySQL keeps the transaction open unless
+ * `innodb_rollback_on_timeout` is set, PostgreSQL aborts it — retry the
+ * whole transaction. `retryable` is `true`. @since 0.1.153
+ */
+| "LOCK_TIMEOUT"
+/**
+ * PostgreSQL could not serialize the transaction (`40001`: under
+ * `REPEATABLE READ` / `SERIALIZABLE`, e.g. a row locked or updated after it
+ * changed since the snapshot). The transaction is aborted — retry it whole.
+ * `retryable` is `true`. @since 0.1.153
+ */
+| "SERIALIZATION_FAILURE";
 declare class DbError extends Error {
   readonly code: DbErrorCode;
   readonly errors: Array<{
@@ -26,7 +47,20 @@ declare class DbError extends Error {
     path: string;
     message: string;
   }>, message?: string);
+  /**
+   * `true` when retrying the whole transaction may succeed — a transient
+   * concurrency condition (`DEADLOCK`, `LOCK_TIMEOUT`,
+   * `SERIALIZATION_FAILURE`), not a fault of the
+   * request. @since 0.1.153
+   */
+  get retryable(): boolean;
 }
+/**
+ * Whether `error` is a retryable `DbError` (`DEADLOCK` / `LOCK_TIMEOUT` /
+ * `SERIALIZATION_FAILURE`):
+ * re-running the whole transaction may succeed. @since 0.1.153
+ */
+declare function isRetryableDbError(error: unknown): error is DbError;
 /** Whether `error` is a `DbError` with code `CONFLICT` (unique / primary-key violation). */
 declare function isConflict(error: unknown): error is DbError;
 /**
@@ -162,4 +196,4 @@ interface ValidationContext {
  */
 declare function buildValidationContext(type: TAtscriptAnnotatedType<TAtscriptTypeObject>): ValidationContext;
 //#endregion
-export { aggregateFailure as _, buildValidationContext as a, isNavRelation as c, getKeyProps as d, CasExhaustedError as f, aggregateExpressionsNotSupported as g, DbErrorCode as h, buildPatchPartial as i, TArrayPatch as l, DbError as m, ValidatorMode as n, dbPlugin as o, CasMismatchError as p, buildDbValidator as r, forceNavNonOptional as s, ValidationContext as t, TDbPatch as u, bucketTimeZoneUnavailable as v, isConflict as y };
+export { aggregateFailure as _, buildValidationContext as a, isRetryableDbError as b, isNavRelation as c, getKeyProps as d, CasExhaustedError as f, aggregateExpressionsNotSupported as g, DbErrorCode as h, buildPatchPartial as i, TArrayPatch as l, DbError as m, ValidatorMode as n, dbPlugin as o, CasMismatchError as p, buildDbValidator as r, forceNavNonOptional as s, ValidationContext as t, TDbPatch as u, bucketTimeZoneUnavailable as v, isConflict as y };

package/dist/{validator-tBNvM1qc.d.mts → validator-B3xlbrWf.d.mts}

@@ -14,7 +14,28 @@ type DbErrorCode = "CONFLICT" | "FK_VIOLATION" | "NOT_FOUND" | "CASCADE_CYCLE" |
  * table lives on a different adapter, or the table was built without a
  * `DbSpace` (moost-db: 400). @since 0.1.147
  */
-| "REL_FILTER_NOT_SUPPORTED" /** The `DbSpace` was closed; the table/view handle can no longer be used (moost-db: 503). @since 0.1.148 */ | "SPACE_CLOSED" /** The adapter does not implement `insertManyIgnore` (moost-db: 400). @since 0.1.148 */ | "ON_CONFLICT_NOT_SUPPORTED" | "TX_WAIT_TIMEOUT";
+| "REL_FILTER_NOT_SUPPORTED" /** The `DbSpace` was closed; the table/view handle can no longer be used (moost-db: 503). @since 0.1.148 */ | "SPACE_CLOSED" /** The adapter does not implement `insertManyIgnore` (moost-db: 400). @since 0.1.148 */ | "ON_CONFLICT_NOT_SUPPORTED" | "TX_WAIT_TIMEOUT"
+/**
+ * The engine chose this transaction as a deadlock victim (MySQL errno 1213,
+ * PostgreSQL 40P01) and rolled it back. Retry the WHOLE transaction.
+ * `retryable` is `true`. @since 0.1.153
+ */
+| "DEADLOCK"
+/**
+ * A row lock was not granted in time (MySQL errno 1205
+ * `innodb_lock_wait_timeout`, PostgreSQL 55P03 `lock_timeout` / `NOWAIT`).
+ * The statement failed; MySQL keeps the transaction open unless
+ * `innodb_rollback_on_timeout` is set, PostgreSQL aborts it — retry the
+ * whole transaction. `retryable` is `true`. @since 0.1.153
+ */
+| "LOCK_TIMEOUT"
+/**
+ * PostgreSQL could not serialize the transaction (`40001`: under
+ * `REPEATABLE READ` / `SERIALIZABLE`, e.g. a row locked or updated after it
+ * changed since the snapshot). The transaction is aborted — retry it whole.
+ * `retryable` is `true`. @since 0.1.153
+ */
+| "SERIALIZATION_FAILURE";
 declare class DbError extends Error {
   readonly code: DbErrorCode;
   readonly errors: Array<{
@@ -26,7 +47,20 @@ declare class DbError extends Error {
     path: string;
     message: string;
   }>, message?: string);
+  /**
+   * `true` when retrying the whole transaction may succeed — a transient
+   * concurrency condition (`DEADLOCK`, `LOCK_TIMEOUT`,
+   * `SERIALIZATION_FAILURE`), not a fault of the
+   * request. @since 0.1.153
+   */
+  get retryable(): boolean;
 }
+/**
+ * Whether `error` is a retryable `DbError` (`DEADLOCK` / `LOCK_TIMEOUT` /
+ * `SERIALIZATION_FAILURE`):
+ * re-running the whole transaction may succeed. @since 0.1.153
+ */
+declare function isRetryableDbError(error: unknown): error is DbError;
 /** Whether `error` is a `DbError` with code `CONFLICT` (unique / primary-key violation). */
 declare function isConflict(error: unknown): error is DbError;
 /**
@@ -162,4 +196,4 @@ interface ValidationContext {
  */
 declare function buildValidationContext(type: TAtscriptAnnotatedType<TAtscriptTypeObject>): ValidationContext;
 //#endregion
-export { aggregateFailure as _, buildValidationContext as a, isNavRelation as c, getKeyProps as d, CasExhaustedError as f, aggregateExpressionsNotSupported as g, DbErrorCode as h, buildPatchPartial as i, TArrayPatch as l, DbError as m, ValidatorMode as n, dbPlugin as o, CasMismatchError as p, buildDbValidator as r, forceNavNonOptional as s, ValidationContext as t, TDbPatch as u, bucketTimeZoneUnavailable as v, isConflict as y };
+export { aggregateFailure as _, buildValidationContext as a, isRetryableDbError as b, isNavRelation as c, getKeyProps as d, CasExhaustedError as f, aggregateExpressionsNotSupported as g, DbErrorCode as h, buildPatchPartial as i, TArrayPatch as l, DbError as m, ValidatorMode as n, dbPlugin as o, CasMismatchError as p, buildDbValidator as r, forceNavNonOptional as s, ValidationContext as t, TDbPatch as u, bucketTimeZoneUnavailable as v, isConflict as y };

package/dist/{validator-BTiIOTKP.mjs → validator-BACewoRj.mjs}

@@ -1,6 +1,6 @@
-import { i as DepthLimitExceededError } from "./db-error-Az85UhTX.mjs";
+import { i as DepthLimitExceededError } from "./db-error-eSsQX7rt.mjs";
 import { getDbFieldOp } from "./ops.mjs";
-import { flattenAnnotatedType } from "@atscript/typescript/utils";
+import { createAnnotatedTypeNode, flattenAnnotatedType } from "@atscript/typescript/utils";
 //#region src/patch/patch-types.ts
 /**
 * Extracts `@expect.array.key` properties from an array-of-objects type.
@@ -40,6 +40,16 @@ function isPatchOperatorObject(value) {
 	return keys.every((k) => PATCH_OPS.has(k));
 }
 /**
+* Items of union / tuple / intersection types the plugin has visited. The
+* validator visits a complex type before its items, so an item is known here
+* by the time it is validated.
+*/
+const complexItems = /* @__PURE__ */ new WeakSet();
+function markComplexItems(def) {
+	const kind = def.type.kind;
+	if (kind === "union" || kind === "tuple" || kind === "intersection") for (const item of def.type.items) complexItems.add(item);
+}
+/**
 * Validator plugin for database operations.
 *
 * Handles navigation field constraints and delegates to the standard validator
@@ -54,6 +64,7 @@ function createDbValidatorPlugin() {
 	return (ctx, def, value) => {
 		const dbCtx = ctx.context;
 		if (!dbCtx) return;
+		markComplexItems(def);
 		if (def.type.tags?.has("geoPoint") && value !== void 0 && value !== null) {
 			if (!Array.isArray(value) || value.length !== 2 || typeof value[0] !== "number" || typeof value[1] !== "number" || !Number.isFinite(value[0]) || !Number.isFinite(value[1])) {
 				ctx.error("Expected a [lng, lat] tuple of two finite numbers (GeoJSON order)");
@@ -73,7 +84,7 @@ function createDbValidatorPlugin() {
 		const isFrom = def.metadata.has("db.rel.from");
 		const isVia = def.metadata.has("db.rel.via");
 		if (isTo || isFrom || isVia) return handleNavField(ctx, def, value, dbCtx, isTo, isFrom, isVia);
-		if (value === void 0 && (dbCtx.mode === "insert" || dbCtx.mode === "replace")) {
+		if (value === void 0 && (dbCtx.mode === "insert" || dbCtx.mode === "replace") && !complexItems.has(def)) {
 			const meta = def.metadata;
 			const serverManaged = meta.has("db.default") || meta.has("db.default.increment") || meta.has("db.default.uuid") || meta.has("db.default.now") || meta.has("db.column.version") || meta.has("db.column.derived");
 			const hasFK = meta.has("db.rel.FK");
@@ -90,7 +101,7 @@ function createDbValidatorPlugin() {
 					return false;
 				}
 				if (dbCtx.flatMap && !isFieldOpAllowed(ctx.path, dbCtx.flatMap, dbCtx.navFields)) {
-					ctx.error("Field operations ($inc/$dec/$mul) are not supported inside @db.json fields or nested objects without @db.patch.strategy \"merge\"");
+					ctx.error("Field operations ($inc/$dec/$mul) are not supported inside @db.json fields, array items, or nested objects without @db.patch.strategy \"merge\"");
 					return false;
 				}
 				if (!(def.type.kind === "" && def.type.designType === "number")) {
@@ -118,6 +129,8 @@ function createDbValidatorPlugin() {
 * - The field itself is `@db.json` (ops on opaque blobs are meaningless).
 * - Any ancestor is `@db.json`.
 * - Any ancestor is a nested object without `@db.patch.strategy "merge"`.
+* - Any ancestor is an embedded array (arrays are written whole, so an op
+*   inside an item would be stored verbatim).
 *
 * Accepts immediately when an ancestor is a navigation field (TO/FROM/VIA) —
 * the nested data is extracted and validated against its own table separately.
@@ -131,6 +144,7 @@ function isFieldOpAllowed(path, flatMap, navFields) {
 		const entry = flatMap.get(ancestor);
 		if (!entry) continue;
 		if (entry.metadata.has("db.json")) return false;
+		if (entry.type.kind === "array") return false;
 		if (entry.type.kind === "object" && entry.metadata.get("db.patch.strategy") !== "merge") return false;
 	}
 	return true;
@@ -233,7 +247,10 @@ function validatePartialItems(ctx, arrayDef, items, op, isMerge) {
 		return false;
 	}
 	const elementDef = arrayDef.type.of;
-	if (elementDef.type.kind !== "object") return ctx.validateAnnotatedType(arrayDef, items);
+	if (elementDef.type.kind !== "object") {
+		for (let i = 0; i < items.length; i++) if (!validateAt(ctx, `${op}[${i}]`, elementDef, items[i])) return false;
+		return true;
+	}
 	const keyProps = getKeyProps(arrayDef);
 	for (let i = 0; i < items.length; i++) {
 		const item = items[i];
@@ -249,12 +266,24 @@ function validatePartialItems(ctx, arrayDef, items, op, isMerge) {
 			}
 		}
 		const objType = elementDef.type;
-		for (const [key, val] of Object.entries(rec)) {
+		let provided;
+		let providedValue;
+		for (const key of Object.keys(rec)) {
 			const propDef = objType.props.get(key);
 			if (propDef) {
-				if (!ctx.validateAnnotatedType(propDef, val)) return false;
+				(provided ??= /* @__PURE__ */ new Map()).set(key, propDef);
+				(providedValue ??= {})[key] = rec[key];
 			}
 		}
+		if (provided) {
+			const itemDef = createAnnotatedTypeNode({
+				kind: "object",
+				props: provided,
+				propsPatterns: [],
+				tags: objType.tags
+			}, elementDef.metadata);
+			if (!validateAt(ctx, `${op}[${i}]`, itemDef, providedValue)) return false;
+		}
 		if (op === "$update" && isMerge !== true) {
 			for (const [propName, propDef] of objType.props) if (!propDef.optional && !keyProps.has(propName) && rec[propName] === void 0) {
 				ctx.error(`${op}[${i}]: field '${propName}' is required (replace strategy)`);
@@ -265,6 +294,21 @@ function validatePartialItems(ctx, arrayDef, items, op, isMerge) {
 	return true;
 }
 /**
+* Validates `value` against `def` as if it sat under `segment` of the current
+* path (`<path>.<segment>`), through the validator's full `validateSafe` walk
+* (optional/null shortcut, `replace`, plugins). The plugin context has no
+* public path push, so the value is wrapped in a single-prop object.
+*/
+function validateAt(ctx, segment, def, value) {
+	const wrapper = createAnnotatedTypeNode({
+		kind: "object",
+		props: new Map([[segment, def]]),
+		propsPatterns: [],
+		tags: /* @__PURE__ */ new Set()
+	}, /* @__PURE__ */ new Map());
+	return ctx.validateAnnotatedType(wrapper, { [segment]: value });
+}
+/**
 * Returns `true` when every char in `[start, end)` is an ASCII digit.
 * Matches segments that represent array indices in dot-notation paths.
 */

package/dist/{validator-UcuJxHNT.cjs → validator-BxWwh3wf.cjs}

@@ -1,4 +1,4 @@
-const require_db_error = require("./db-error-DRQH4sLY.cjs");
+const require_db_error = require("./db-error-JcfJqqpk.cjs");
 const require_ops = require("./ops.cjs");
 let _atscript_typescript_utils = require("@atscript/typescript/utils");
 //#region src/patch/patch-types.ts
@@ -40,6 +40,16 @@ function isPatchOperatorObject(value) {
 	return keys.every((k) => PATCH_OPS.has(k));
 }
 /**
+* Items of union / tuple / intersection types the plugin has visited. The
+* validator visits a complex type before its items, so an item is known here
+* by the time it is validated.
+*/
+const complexItems = /* @__PURE__ */ new WeakSet();
+function markComplexItems(def) {
+	const kind = def.type.kind;
+	if (kind === "union" || kind === "tuple" || kind === "intersection") for (const item of def.type.items) complexItems.add(item);
+}
+/**
 * Validator plugin for database operations.
 *
 * Handles navigation field constraints and delegates to the standard validator
@@ -54,6 +64,7 @@ function createDbValidatorPlugin() {
 	return (ctx, def, value) => {
 		const dbCtx = ctx.context;
 		if (!dbCtx) return;
+		markComplexItems(def);
 		if (def.type.tags?.has("geoPoint") && value !== void 0 && value !== null) {
 			if (!Array.isArray(value) || value.length !== 2 || typeof value[0] !== "number" || typeof value[1] !== "number" || !Number.isFinite(value[0]) || !Number.isFinite(value[1])) {
 				ctx.error("Expected a [lng, lat] tuple of two finite numbers (GeoJSON order)");
@@ -73,7 +84,7 @@ function createDbValidatorPlugin() {
 		const isFrom = def.metadata.has("db.rel.from");
 		const isVia = def.metadata.has("db.rel.via");
 		if (isTo || isFrom || isVia) return handleNavField(ctx, def, value, dbCtx, isTo, isFrom, isVia);
-		if (value === void 0 && (dbCtx.mode === "insert" || dbCtx.mode === "replace")) {
+		if (value === void 0 && (dbCtx.mode === "insert" || dbCtx.mode === "replace") && !complexItems.has(def)) {
 			const meta = def.metadata;
 			const serverManaged = meta.has("db.default") || meta.has("db.default.increment") || meta.has("db.default.uuid") || meta.has("db.default.now") || meta.has("db.column.version") || meta.has("db.column.derived");
 			const hasFK = meta.has("db.rel.FK");
@@ -90,7 +101,7 @@ function createDbValidatorPlugin() {
 					return false;
 				}
 				if (dbCtx.flatMap && !isFieldOpAllowed(ctx.path, dbCtx.flatMap, dbCtx.navFields)) {
-					ctx.error("Field operations ($inc/$dec/$mul) are not supported inside @db.json fields or nested objects without @db.patch.strategy \"merge\"");
+					ctx.error("Field operations ($inc/$dec/$mul) are not supported inside @db.json fields, array items, or nested objects without @db.patch.strategy \"merge\"");
 					return false;
 				}
 				if (!(def.type.kind === "" && def.type.designType === "number")) {
@@ -118,6 +129,8 @@ function createDbValidatorPlugin() {
 * - The field itself is `@db.json` (ops on opaque blobs are meaningless).
 * - Any ancestor is `@db.json`.
 * - Any ancestor is a nested object without `@db.patch.strategy "merge"`.
+* - Any ancestor is an embedded array (arrays are written whole, so an op
+*   inside an item would be stored verbatim).
 *
 * Accepts immediately when an ancestor is a navigation field (TO/FROM/VIA) —
 * the nested data is extracted and validated against its own table separately.
@@ -131,6 +144,7 @@ function isFieldOpAllowed(path, flatMap, navFields) {
 		const entry = flatMap.get(ancestor);
 		if (!entry) continue;
 		if (entry.metadata.has("db.json")) return false;
+		if (entry.type.kind === "array") return false;
 		if (entry.type.kind === "object" && entry.metadata.get("db.patch.strategy") !== "merge") return false;
 	}
 	return true;
@@ -233,7 +247,10 @@ function validatePartialItems(ctx, arrayDef, items, op, isMerge) {
 		return false;
 	}
 	const elementDef = arrayDef.type.of;
-	if (elementDef.type.kind !== "object") return ctx.validateAnnotatedType(arrayDef, items);
+	if (elementDef.type.kind !== "object") {
+		for (let i = 0; i < items.length; i++) if (!validateAt(ctx, `${op}[${i}]`, elementDef, items[i])) return false;
+		return true;
+	}
 	const keyProps = getKeyProps(arrayDef);
 	for (let i = 0; i < items.length; i++) {
 		const item = items[i];
@@ -249,12 +266,24 @@ function validatePartialItems(ctx, arrayDef, items, op, isMerge) {
 			}
 		}
 		const objType = elementDef.type;
-		for (const [key, val] of Object.entries(rec)) {
+		let provided;
+		let providedValue;
+		for (const key of Object.keys(rec)) {
 			const propDef = objType.props.get(key);
 			if (propDef) {
-				if (!ctx.validateAnnotatedType(propDef, val)) return false;
+				(provided ??= /* @__PURE__ */ new Map()).set(key, propDef);
+				(providedValue ??= {})[key] = rec[key];
 			}
 		}
+		if (provided) {
+			const itemDef = (0, _atscript_typescript_utils.createAnnotatedTypeNode)({
+				kind: "object",
+				props: provided,
+				propsPatterns: [],
+				tags: objType.tags
+			}, elementDef.metadata);
+			if (!validateAt(ctx, `${op}[${i}]`, itemDef, providedValue)) return false;
+		}
 		if (op === "$update" && isMerge !== true) {
 			for (const [propName, propDef] of objType.props) if (!propDef.optional && !keyProps.has(propName) && rec[propName] === void 0) {
 				ctx.error(`${op}[${i}]: field '${propName}' is required (replace strategy)`);
@@ -265,6 +294,21 @@ function validatePartialItems(ctx, arrayDef, items, op, isMerge) {
 	return true;
 }
 /**
+* Validates `value` against `def` as if it sat under `segment` of the current
+* path (`<path>.<segment>`), through the validator's full `validateSafe` walk
+* (optional/null shortcut, `replace`, plugins). The plugin context has no
+* public path push, so the value is wrapped in a single-prop object.
+*/
+function validateAt(ctx, segment, def, value) {
+	const wrapper = (0, _atscript_typescript_utils.createAnnotatedTypeNode)({
+		kind: "object",
+		props: new Map([[segment, def]]),
+		propsPatterns: [],
+		tags: /* @__PURE__ */ new Set()
+	}, /* @__PURE__ */ new Map());
+	return ctx.validateAnnotatedType(wrapper, { [segment]: value });
+}
+/**
 * Returns `true` when every char in `[start, end)` is an ASCII digit.
 * Matches segments that represent array indices in dot-notation paths.
 */