@atscript/db 0.1.43 → 0.1.45

package/dist/validator-0iGuvGOD.cjs

@@ -0,0 +1,337 @@
+const require_ops = require("./ops.cjs");
+let _atscript_typescript_utils = require("@atscript/typescript/utils");
+//#region src/patch/patch-types.ts
+/**
+* Extracts `@expect.array.key` properties from an array-of-objects type.
+* These keys uniquely identify an element inside the array and are used
+* for `$update`, `$remove`, and `$upsert` operations.
+*
+* @param def - Atscript array type definition.
+* @returns Set of property names marked as keys; empty set if none.
+*/
+function getKeyProps(def) {
+	if (def.type.of.type.kind === "object") {
+		const objType = def.type.of.type;
+		const keyProps = /* @__PURE__ */ new Set();
+		for (const [key, val] of objType.props.entries()) if (val.metadata.get("expect.array.key")) keyProps.add(key);
+		return keyProps;
+	}
+	return /* @__PURE__ */ new Set();
+}
+//#endregion
+//#region src/db-validator-plugin.ts
+/** Set of recognised array‑patch operator keys. */
+const PATCH_OPS = new Set([
+	"$replace",
+	"$insert",
+	"$upsert",
+	"$update",
+	"$remove"
+]);
+/**
+* Returns `true` when `value` looks like a patch‑operator object
+* (at least one key is a recognised operator and no unknown keys).
+*/
+function isPatchOperatorObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const keys = Object.keys(value);
+	if (keys.length === 0) return false;
+	return keys.every((k) => PATCH_OPS.has(k));
+}
+/**
+* Validator plugin for database operations.
+*
+* Handles navigation field constraints and delegates to the standard validator
+* for type checking. The annotated type tree already includes nav fields with
+* their full target types — this plugin controls WHEN recursion is allowed
+* based on the operation mode (insert/replace/patch).
+*
+* Replaces the old `navFieldsValidatorPlugin` (which blindly skipped all nav
+* fields) and `_checkNavProps()` (which validated constraints separately).
+*/
+function createDbValidatorPlugin() {
+	return (ctx, def, value) => {
+		const dbCtx = ctx.context;
+		if (!dbCtx) return;
+		const isTo = def.metadata.has("db.rel.to");
+		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")) {
+			const meta = def.metadata;
+			const hasDefault = meta.has("db.default") || meta.has("db.default.increment") || meta.has("db.default.uuid") || meta.has("db.default.now");
+			const hasFK = meta.has("db.rel.FK");
+			if (hasDefault || hasFK) {
+				if (dbCtx.mode === "replace" && meta.has("meta.id") && !isInsideNavField(ctx.path, dbCtx.navFields)) return;
+				return true;
+			}
+		}
+		if (dbCtx.mode === "patch") {
+			if (require_ops.isDbFieldOp(value)) {
+				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\"");
+					return false;
+				}
+				if (!(def.type.kind === "" && def.type.designType === "number")) {
+					ctx.error("Field operations ($inc/$dec/$mul) can only be applied to numeric fields");
+					return false;
+				}
+				return true;
+			}
+			if (def.type.kind === "array" && dbCtx.flatMap) {
+				const flatEntry = dbCtx.flatMap.get(ctx.path);
+				if (flatEntry?.metadata?.has("db.__topLevelArray") && !flatEntry.metadata.has("db.json")) return handleArrayPatch(ctx, def, value);
+			}
+		}
+	};
+}
+/**
+* Checks whether a field op is valid at `path`.
+*
+* Rejects when:
+* - 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"`.
+*
+* Accepts immediately when an ancestor is a navigation field (TO/FROM/VIA) —
+* the nested data is extracted and validated against its own table separately.
+*/
+function isFieldOpAllowed(path, flatMap, navFields) {
+	if (flatMap.get(path)?.metadata.has("db.json")) return false;
+	let pos = path.length;
+	while ((pos = path.lastIndexOf(".", pos - 1)) !== -1) {
+		const ancestor = path.slice(0, pos);
+		if (navFields?.has(ancestor)) return true;
+		const entry = flatMap.get(ancestor);
+		if (!entry) continue;
+		if (entry.metadata.has("db.json")) return false;
+		if (entry.type.kind === "object" && entry.metadata.get("db.patch.strategy") !== "merge") return false;
+	}
+	return true;
+}
+/** Returns true if the given path is nested inside a navigation field. */
+function isInsideNavField(path, navFields) {
+	if (!navFields) return false;
+	let pos = path.length;
+	while ((pos = path.lastIndexOf(".", pos - 1)) !== -1) if (navFields.has(path.slice(0, pos))) return true;
+	return false;
+}
+function handleNavField(ctx, def, value, dbCtx, isTo, isFrom, isVia) {
+	const dotIdx = ctx.path.lastIndexOf(".");
+	const fieldName = dotIdx === -1 ? ctx.path : ctx.path.slice(dotIdx + 1);
+	if (value === null) {
+		ctx.error(`Cannot process null navigation property '${fieldName}'`);
+		return false;
+	}
+	if (value === void 0) return true;
+	if (dbCtx.mode === "patch") {
+		if (isFrom || isVia) {
+			if (isPatchOperatorObject(value)) return validateNavPatchOps(ctx, def, value, fieldName);
+			const relType = isFrom ? "1:N" : "M:N";
+			ctx.error(`Cannot patch ${relType} relation '${fieldName}' with a plain value — use patch operators ({ $insert, $remove, $replace, $update, $upsert })`);
+			return false;
+		}
+	}
+	if (isVia) return true;
+}
+/**
+* Validates patch operator values against the nav field's target array type.
+* Each operator's items are validated against the element type.
+*/
+function validateNavPatchOps(ctx, def, ops, fieldName) {
+	if (def.type.kind !== "array") {
+		ctx.error(`Cannot use patch operators on non-array relation '${fieldName}'`);
+		return false;
+	}
+	const arrayDef = def;
+	for (const op of [
+		"$replace",
+		"$insert",
+		"$upsert"
+	]) if (ops[op] !== void 0) {
+		if (!ctx.validateAnnotatedType(arrayDef, ops[op])) return false;
+	}
+	for (const op of ["$update", "$remove"]) if (ops[op] !== void 0) {
+		if (!validatePartialItems(ctx, arrayDef, ops[op], op, true)) return false;
+	}
+	return true;
+}
+/**
+* Handles patch‑mode validation for top‑level embedded arrays.
+*
+* When the incoming value is:
+* - A plain array → falls through to default array validation ($replace semantics)
+* - A patch operator object → validates each operator's payload individually
+*/
+function handleArrayPatch(ctx, def, value) {
+	if (Array.isArray(value)) return;
+	if (typeof value !== "object" || value === null) return;
+	const ops = value;
+	const keys = Object.keys(ops);
+	if (keys.length === 0 || !keys.every((k) => PATCH_OPS.has(k))) {
+		if (keys.some((k) => PATCH_OPS.has(k))) {
+			const unknown = keys.filter((k) => !PATCH_OPS.has(k));
+			ctx.error(`Unknown patch operator(s): ${unknown.join(", ")}. Allowed: $replace, $insert, $upsert, $update, $remove`);
+			return false;
+		}
+		return;
+	}
+	for (const op of [
+		"$replace",
+		"$insert",
+		"$upsert"
+	]) if (ops[op] !== void 0) {
+		if (!ctx.validateAnnotatedType(def, ops[op])) return false;
+	}
+	const isMerge = def.metadata.get("db.patch.strategy") === "merge";
+	for (const op of ["$update", "$remove"]) if (ops[op] !== void 0) {
+		if (!validatePartialItems(ctx, def, ops[op], op, isMerge)) return false;
+	}
+	return true;
+}
+/**
+* Validates `$update` / `$remove` items.
+*
+* Each item must be an object. For object arrays with `@expect.array.key` fields,
+* key properties are required and non‑key properties are validated but optional.
+* For primitive arrays, items are validated directly against the element type.
+*/
+function validatePartialItems(ctx, arrayDef, items, op, isMerge) {
+	if (!Array.isArray(items)) {
+		ctx.error(`${op} must be an array`);
+		return false;
+	}
+	const elementDef = arrayDef.type.of;
+	if (elementDef.type.kind !== "object") return ctx.validateAnnotatedType(arrayDef, items);
+	const keyProps = getKeyProps(arrayDef);
+	for (let i = 0; i < items.length; i++) {
+		const item = items[i];
+		if (typeof item !== "object" || item === null || Array.isArray(item)) {
+			ctx.error(`${op}[${i}]: expected object`);
+			return false;
+		}
+		const rec = item;
+		if (keyProps.size > 0) {
+			for (const kp of keyProps) if (rec[kp] === void 0 || rec[kp] === null) {
+				ctx.error(`${op}[${i}]: key field '${kp}' is required`);
+				return false;
+			}
+		}
+		const objType = elementDef.type;
+		for (const [key, val] of Object.entries(rec)) {
+			const propDef = objType.props.get(key);
+			if (propDef) {
+				if (!ctx.validateAnnotatedType(propDef, val)) 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)`);
+				return false;
+			}
+		}
+	}
+	return true;
+}
+//#endregion
+//#region src/validator.ts
+/** Singleton db validator plugin — stateless, safe to share across all validators. */
+const dbPlugin = createDbValidatorPlugin();
+/**
+* Builds a validator for a given write mode.
+*
+* Shared between server-side (`AtscriptDbTable`) and client-side (`ClientValidator`).
+* Both use the same plugin, same `replace`, same `partial` logic.
+*
+* @param type - The annotated type to validate against.
+* @param mode - The write operation mode.
+* @param extraPlugins - Additional adapter-specific plugins (prepended before the db plugin).
+*/
+function buildDbValidator(type, mode, extraPlugins) {
+	const plugins = extraPlugins ? [...extraPlugins, dbPlugin] : [dbPlugin];
+	return type.validator({
+		plugins,
+		partial: mode === "patch",
+		replace: forceNavNonOptional
+	});
+}
+/** Returns true if the annotated type is a navigation relation (TO/FROM/VIA). */
+function isNavRelation(type) {
+	return !!type.metadata && (type.metadata.has("db.rel.to") || type.metadata.has("db.rel.from") || type.metadata.has("db.rel.via"));
+}
+/**
+* Forces nav fields non-optional so the plugin handles null/undefined checks.
+* The Validator caches replace results internally, so this allocates at most once per type node.
+*/
+function forceNavNonOptional(type) {
+	if (!type.optional) return type;
+	if (isNavRelation(type)) return {
+		...type,
+		optional: false
+	};
+	return type;
+}
+/**
+* Builds a lightweight validation context from a deserialized Atscript type.
+*
+* This is the client-side equivalent of the server's `TableMetadata.build()`,
+* without any adapter-specific processing (physical columns, index resolution, etc.).
+*
+* @param type - A deserialized annotated type (from `deserializeAnnotatedType(meta.type)`).
+* @returns `flatMap` and `navFields` suitable for passing to `createDbValidatorPlugin` via `DbValidationContext`.
+*/
+function buildValidationContext(type) {
+	const navFields = /* @__PURE__ */ new Set();
+	return {
+		flatMap: (0, _atscript_typescript_utils.flattenAnnotatedType)(type, {
+			topLevelArrayTag: "db.__topLevelArray",
+			onField: (path, _type, metadata) => {
+				if (metadata.has("db.rel.to") || metadata.has("db.rel.from") || metadata.has("db.rel.via")) navFields.add(path);
+			}
+		}),
+		navFields
+	};
+}
+//#endregion
+Object.defineProperty(exports, "buildDbValidator", {
+	enumerable: true,
+	get: function() {
+		return buildDbValidator;
+	}
+});
+Object.defineProperty(exports, "buildValidationContext", {
+	enumerable: true,
+	get: function() {
+		return buildValidationContext;
+	}
+});
+Object.defineProperty(exports, "createDbValidatorPlugin", {
+	enumerable: true,
+	get: function() {
+		return createDbValidatorPlugin;
+	}
+});
+Object.defineProperty(exports, "dbPlugin", {
+	enumerable: true,
+	get: function() {
+		return dbPlugin;
+	}
+});
+Object.defineProperty(exports, "forceNavNonOptional", {
+	enumerable: true,
+	get: function() {
+		return forceNavNonOptional;
+	}
+});
+Object.defineProperty(exports, "getKeyProps", {
+	enumerable: true,
+	get: function() {
+		return getKeyProps;
+	}
+});
+Object.defineProperty(exports, "isNavRelation", {
+	enumerable: true,
+	get: function() {
+		return isNavRelation;
+	}
+});

package/dist/validator-BeXlQISk.d.mts

@@ -0,0 +1,69 @@
+import { TAtscriptAnnotatedType, TAtscriptTypeArray, TAtscriptTypeObject, TValidatorPlugin, Validator } from "@atscript/typescript/utils";
+
+//#region src/patch/patch-types.d.ts
+interface TArrayPatch<A extends readonly unknown[]> {
+  $replace?: A;
+  $insert?: A;
+  $upsert?: A;
+  $update?: Array<Partial<TArrayElement<A>>>;
+  $remove?: Array<Partial<TArrayElement<A>>>;
+}
+type TArrayElement<ArrayType extends readonly unknown[]> = ArrayType extends ReadonlyArray<infer ElementType> ? ElementType : never;
+/**
+ * Maps each property of T into a patch payload:
+ * - Array properties become `TArrayPatch<T[K]>`
+ * - Non-array properties become `Partial<T[K]>`
+ */
+type TDbPatch<T> = { [K in keyof T]?: T[K] extends Array<infer _> ? TArrayPatch<T[K]> : Partial<T[K]> };
+/**
+ * Extracts `@expect.array.key` properties from an array-of-objects type.
+ * These keys uniquely identify an element inside the array and are used
+ * for `$update`, `$remove`, and `$upsert` operations.
+ *
+ * @param def - Atscript array type definition.
+ * @returns Set of property names marked as keys; empty set if none.
+ */
+declare function getKeyProps(def: TAtscriptAnnotatedType<TAtscriptTypeArray>): Set<string>;
+//#endregion
+//#region src/validator.d.ts
+/** Write operation mode for validator configuration. */
+type ValidatorMode = "insert" | "patch" | "replace";
+/** Singleton db validator plugin — stateless, safe to share across all validators. */
+declare const dbPlugin: TValidatorPlugin;
+/**
+ * Builds a validator for a given write mode.
+ *
+ * Shared between server-side (`AtscriptDbTable`) and client-side (`ClientValidator`).
+ * Both use the same plugin, same `replace`, same `partial` logic.
+ *
+ * @param type - The annotated type to validate against.
+ * @param mode - The write operation mode.
+ * @param extraPlugins - Additional adapter-specific plugins (prepended before the db plugin).
+ */
+declare function buildDbValidator(type: TAtscriptAnnotatedType, mode: ValidatorMode, extraPlugins?: TValidatorPlugin[]): Validator<any>;
+/** Returns true if the annotated type is a navigation relation (TO/FROM/VIA). */
+declare function isNavRelation(type: TAtscriptAnnotatedType): boolean;
+/**
+ * Forces nav fields non-optional so the plugin handles null/undefined checks.
+ * The Validator caches replace results internally, so this allocates at most once per type node.
+ */
+declare function forceNavNonOptional(type: TAtscriptAnnotatedType): TAtscriptAnnotatedType;
+/** Result of {@link buildValidationContext}. */
+interface ValidationContext {
+  /** Flat map of dotted field paths → annotated types (same shape the server builds). */
+  flatMap: Map<string, TAtscriptAnnotatedType>;
+  /** Set of field paths that are navigation relations (TO/FROM/VIA). */
+  navFields: ReadonlySet<string>;
+}
+/**
+ * Builds a lightweight validation context from a deserialized Atscript type.
+ *
+ * This is the client-side equivalent of the server's `TableMetadata.build()`,
+ * without any adapter-specific processing (physical columns, index resolution, etc.).
+ *
+ * @param type - A deserialized annotated type (from `deserializeAnnotatedType(meta.type)`).
+ * @returns `flatMap` and `navFields` suitable for passing to `createDbValidatorPlugin` via `DbValidationContext`.
+ */
+declare function buildValidationContext(type: TAtscriptAnnotatedType<TAtscriptTypeObject>): ValidationContext;
+//#endregion
+export { dbPlugin as a, TArrayPatch as c, buildValidationContext as i, TDbPatch as l, ValidatorMode as n, forceNavNonOptional as o, buildDbValidator as r, isNavRelation as s, ValidationContext as t, getKeyProps as u };