@atscript/typescript 0.1.30 → 0.1.32

package/dist/utils.cjs

@@ -1,23 +1,5 @@
 "use strict";
 
-//#region packages/typescript/src/traverse.ts
-function forAnnotatedType(def, handlers) {
-	switch (def.type.kind) {
-		case "": {
-			const typed = def;
-			if (handlers.phantom && typed.type.designType === "phantom") return handlers.phantom(typed);
-			return handlers.final(typed);
-		}
-		case "object": return handlers.object(def);
-		case "array": return handlers.array(def);
-		case "union": return handlers.union(def);
-		case "intersection": return handlers.intersection(def);
-		case "tuple": return handlers.tuple(def);
-		default: throw new Error(`Unknown type kind "${def.type.kind}"`);
-	}
-}
-
-//#endregion
 //#region packages/typescript/src/validator.ts
 function _define_property(obj, key, value) {
 	if (key in obj) Object.defineProperty(obj, key, {
@@ -32,28 +14,35 @@ else obj[key] = value;
 const regexCache = new Map();
 var Validator = class {
 	isLimitExceeded() {
-		if (this.stackErrors.length > 0) return this.stackErrors[this.stackErrors.length - 1].length >= this.opts.errorLimit;
+		if (this.stackErrors.length > 0) {
+			const top = this.stackErrors[this.stackErrors.length - 1];
+			return top !== null && top.length >= this.opts.errorLimit;
+		}
 		return this.errors.length >= this.opts.errorLimit;
 	}
 	push(name) {
 		this.stackPath.push(name);
-		this.stackErrors.push([]);
+		this.stackErrors.push(null);
+		this.cachedPath = this.stackPath.length <= 1 ? "" : this.stackPath[1] + (this.stackPath.length > 2 ? "." + this.stackPath.slice(2).join(".") : "");
 	}
 	pop(saveErrors) {
 		this.stackPath.pop();
 		const popped = this.stackErrors.pop();
-		if (saveErrors && popped?.length) popped.forEach((error) => {
-			this.error(error.message, error.path, error.details);
-		});
+		if (saveErrors && popped !== null && popped !== undefined && popped.length > 0) for (const err of popped) this.error(err.message, err.path, err.details);
+		this.cachedPath = this.stackPath.length <= 1 ? "" : this.stackPath[1] + (this.stackPath.length > 2 ? "." + this.stackPath.slice(2).join(".") : "");
 		return popped;
 	}
 	clear() {
-		this.stackErrors[this.stackErrors.length - 1] = [];
+		this.stackErrors[this.stackErrors.length - 1] = null;
 	}
 	error(message, path, details) {
-		const errors = this.stackErrors[this.stackErrors.length - 1] || this.errors;
+		let errors = this.stackErrors[this.stackErrors.length - 1];
+		if (!errors) if (this.stackErrors.length > 0) {
+			errors = [];
+			this.stackErrors[this.stackErrors.length - 1] = errors;
+		} else errors = this.errors;
 		const error = {
-			path: path || this.path,
+			path: path || this.cachedPath,
 			message
 		};
 		if (details?.length) error.details = details;
@@ -73,9 +62,10 @@ var Validator = class {
 	* @returns `true` if the value matches the type definition.
 	* @throws {ValidatorError} When validation fails and `safe` is not `true`.
 	*/ validate(value, safe, context) {
-		this.push("");
 		this.errors = [];
 		this.stackErrors = [];
+		this.stackPath = [""];
+		this.cachedPath = "";
 		this.context = context;
 		const passed = this.validateSafe(this.def, value);
 		this.pop(!passed);
@@ -89,7 +79,7 @@ var Validator = class {
 	validateSafe(def, value) {
 		if (this.isLimitExceeded()) return false;
 		if (!isAnnotatedType(def)) throw new Error("Can not validate not-annotated type");
-		if (typeof this.opts.replace === "function") def = this.opts.replace(def, this.path);
+		if (typeof this.opts.replace === "function") def = this.opts.replace(def, this.cachedPath);
 		if (def.optional && value === undefined) return true;
 		for (const plugin of this.opts.plugins) {
 			const result = plugin(this, def, value);
@@ -98,18 +88,21 @@ var Validator = class {
 		return this.validateAnnotatedType(def, value);
 	}
 	get path() {
-		return this.stackPath.slice(1).join(".");
+		return this.cachedPath;
 	}
 	validateAnnotatedType(def, value) {
-		return forAnnotatedType(def, {
-			final: (d) => this.validatePrimitive(d, value),
-			phantom: () => true,
-			object: (d) => this.validateObject(d, value),
-			array: (d) => this.validateArray(d, value),
-			union: (d) => this.validateUnion(d, value),
-			intersection: (d) => this.validateIntersection(d, value),
-			tuple: (d) => this.validateTuple(d, value)
-		});
+		switch (def.type.kind) {
+			case "": {
+				if (def.type.designType === "phantom") return true;
+				return this.validatePrimitive(def, value);
+			}
+			case "object": return this.validateObject(def, value);
+			case "array": return this.validateArray(def, value);
+			case "union": return this.validateUnion(def, value);
+			case "intersection": return this.validateIntersection(def, value);
+			case "tuple": return this.validateTuple(def, value);
+			default: throw new Error(`Unknown type kind "${def.type.kind}"`);
+		}
 	}
 	validateUnion(def, value) {
 		let i = 0;
@@ -173,6 +166,30 @@ var Validator = class {
 				return false;
 			}
 		}
+		const uniqueItems = def.metadata.get("expect.array.uniqueItems");
+		if (uniqueItems) {
+			const separator = "▼↩";
+			const seen = new Set();
+			const keyProps = new Set();
+			if (def.type.of.type.kind === "object") {
+				for (const [key, val] of def.type.of.type.props.entries()) if (val.metadata.get("expect.array.key")) keyProps.add(key);
+			}
+			for (let idx = 0; idx < value.length; idx++) {
+				const item = value[idx];
+				let key;
+				if (keyProps.size > 0) {
+					key = "";
+					for (const prop of keyProps) key += JSON.stringify(item[prop]) + separator;
+				} else key = JSON.stringify(item);
+				if (seen.has(key)) {
+					this.push(String(idx));
+					this.error(uniqueItems.message || "Duplicate items are not allowed");
+					this.pop(true);
+					return false;
+				}
+				seen.add(key);
+			}
+		}
 		let i = 0;
 		let passed = true;
 		for (const item of value) {
@@ -194,21 +211,20 @@ var Validator = class {
 		let passed = true;
 		const valueKeys = new Set(Object.keys(value));
 		const typeKeys = new Set();
-		const skipList = new Set();
+		let skipList;
 		if (this.opts.skipList) {
-			const path = this.stackPath.length > 1 ? `${this.path}.` : "";
-			this.opts.skipList.forEach((item) => {
-				if (item.startsWith(path)) {
-					const key = item.slice(path.length);
-					skipList.add(key);
-					valueKeys.delete(key);
-				}
-			});
+			const path = this.stackPath.length > 1 ? `${this.cachedPath}.` : "";
+			for (const item of this.opts.skipList) if (item.startsWith(path)) {
+				const key = item.slice(path.length);
+				if (!skipList) skipList = new Set();
+				skipList.add(key);
+				valueKeys.delete(key);
+			}
 		}
 		let partialFunctionMatched = false;
-		if (typeof this.opts.partial === "function") partialFunctionMatched = this.opts.partial(def, this.path);
+		if (typeof this.opts.partial === "function") partialFunctionMatched = this.opts.partial(def, this.cachedPath);
 		for (const [key, item] of def.type.props.entries()) {
-			if (skipList.has(key) || isPhantomType(item)) continue;
+			if (skipList && skipList.has(key) || isPhantomType(item)) continue;
 			typeKeys.add(key);
 			if (value[key] === undefined) {
 				if (partialFunctionMatched || this.opts.partial === "deep" || this.opts.partial === true && this.stackPath.length <= 1) continue;
@@ -229,19 +245,21 @@ else {
 				def: propDef
 			});
 			if (matched.length > 0) {
+				this.push(key);
 				let keyPassed = false;
-				for (const { def: def$1 } of matched) if (this.validateSafe(def$1, value[key])) {
-					this.pop(false);
-					keyPassed = true;
-					break;
+				for (const { def: propDef } of matched) {
+					if (this.validateSafe(propDef, value[key])) {
+						keyPassed = true;
+						break;
+					}
+					this.clear();
 				}
 				if (!keyPassed) {
-					this.push(key);
 					this.validateSafe(matched[0].def, value[key]);
 					this.pop(true);
 					passed = false;
 					if (this.isLimitExceeded()) return false;
-				}
+				} else this.pop(false);
 			} else if (this.opts.unknownProps !== "ignore") {
 				if (this.opts.unknownProps === "error") {
 					this.push(key);
@@ -394,11 +412,13 @@ else {
 		/** Validation errors collected during the last {@link validate} call. */ _define_property(this, "errors", void 0);
 		_define_property(this, "stackErrors", void 0);
 		_define_property(this, "stackPath", void 0);
+		_define_property(this, "cachedPath", void 0);
 		_define_property(this, "context", void 0);
 		this.def = def;
 		this.errors = [];
 		this.stackErrors = [];
 		this.stackPath = [];
+		this.cachedPath = "";
 		this.opts = {
 			partial: false,
 			unknownProps: "error",
@@ -612,6 +632,24 @@ function isAnnotatedTypeOfPrimitive(t) {
 	return false;
 }
 
+//#endregion
+//#region packages/typescript/src/traverse.ts
+function forAnnotatedType(def, handlers) {
+	switch (def.type.kind) {
+		case "": {
+			const typed = def;
+			if (handlers.phantom && typed.type.designType === "phantom") return handlers.phantom(typed);
+			return handlers.final(typed);
+		}
+		case "object": return handlers.object(def);
+		case "array": return handlers.array(def);
+		case "union": return handlers.union(def);
+		case "intersection": return handlers.intersection(def);
+		case "tuple": return handlers.tuple(def);
+		default: throw new Error(`Unknown type kind "${def.type.kind}"`);
+	}
+}
+
 //#endregion
 //#region packages/typescript/src/json-schema.ts
 /**

package/dist/utils.d.ts

@@ -54,12 +54,13 @@ declare class Validator<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedTyp
     constructor(def: T, opts?: Partial<TValidatorOptions>);
     /** Validation errors collected during the last {@link validate} call. */
     errors: TError[];
-    protected stackErrors: TError[][];
+    protected stackErrors: Array<TError[] | null>;
     protected stackPath: string[];
+    protected cachedPath: string;
     protected context: unknown;
     protected isLimitExceeded(): boolean;
     protected push(name: string): void;
-    protected pop(saveErrors: boolean): TError[] | undefined;
+    protected pop(saveErrors: boolean): TError[] | null | undefined;
     protected clear(): void;
     protected error(message: string, path?: string, details?: TError[]): void;
     protected throw(): void;
@@ -535,5 +536,28 @@ declare function serializeAnnotatedType(type: TAtscriptAnnotatedType, options?:
  */
 declare function deserializeAnnotatedType(data: TSerializedAnnotatedType): TAtscriptAnnotatedType;
 
+/**
+ * Extracts the flat dot-notation type map from an Atscript annotated type.
+ * If the type has a `__flat` static property (emitted for `@db.table` interfaces),
+ * returns that flat map. Otherwise falls back to `TAtscriptDataType<T>`.
+ *
+ * Use this for type-safe filters and selects with dot-notation field paths.
+ */
+type FlatOf<T> = T extends {
+    __flat: infer F;
+} ? F : T extends TAtscriptAnnotatedType ? TAtscriptDataType<T> : unknown;
+/**
+ * Extracts the primary key type from an Atscript annotated type.
+ * If the type has a `__pk` static property (emitted for `@db.table` interfaces
+ * with `@meta.id` fields), returns that type. Otherwise falls back to `unknown`.
+ *
+ * - Single `@meta.id` field → scalar type (e.g., `string`, `number`)
+ * - Multiple `@meta.id` fields → object type (e.g., `{ userId: string; orderId: number }`)
+ * - No `@meta.id` fields → `unknown`
+ */
+type PrimaryKeyOf<T> = T extends {
+    __pk: infer PK;
+} ? PK : unknown;
+
 export { SERIALIZE_VERSION, Validator, ValidatorError, annotate, buildJsonSchema, cloneRefProp, createDataFromAnnotatedType, defineAnnotatedType, deserializeAnnotatedType, flattenAnnotatedType, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, mergeJsonSchemas, serializeAnnotatedType, throwFeatureDisabled };
-export type { InferDataType, TAnnotatedTypeHandle, TAtscriptAnnotatedType, TAtscriptAnnotatedTypeConstructor, TAtscriptDataType, TAtscriptTypeArray, TAtscriptTypeComplex, TAtscriptTypeDef, TAtscriptTypeFinal, TAtscriptTypeObject, TCreateDataOptions, TFlattenOptions, TJsonSchema, TMetadataMap, TProcessAnnotationContext, TSerializeOptions, TSerializedAnnotatedType, TSerializedAnnotatedTypeInner, TSerializedTypeArray, TSerializedTypeComplex, TSerializedTypeDef, TSerializedTypeFinal, TSerializedTypeObject, TValidatorOptions, TValidatorPlugin, TValidatorPluginContext, TValueResolver };
+export type { FlatOf, InferDataType, PrimaryKeyOf, TAnnotatedTypeHandle, TAtscriptAnnotatedType, TAtscriptAnnotatedTypeConstructor, TAtscriptDataType, TAtscriptTypeArray, TAtscriptTypeComplex, TAtscriptTypeDef, TAtscriptTypeFinal, TAtscriptTypeObject, TCreateDataOptions, TFlattenOptions, TJsonSchema, TMetadataMap, TProcessAnnotationContext, TSerializeOptions, TSerializedAnnotatedType, TSerializedAnnotatedTypeInner, TSerializedTypeArray, TSerializedTypeComplex, TSerializedTypeDef, TSerializedTypeFinal, TSerializedTypeObject, TValidatorOptions, TValidatorPlugin, TValidatorPluginContext, TValueResolver };

package/dist/utils.mjs

@@ -1,22 +1,4 @@
 
-//#region packages/typescript/src/traverse.ts
-function forAnnotatedType(def, handlers) {
-	switch (def.type.kind) {
-		case "": {
-			const typed = def;
-			if (handlers.phantom && typed.type.designType === "phantom") return handlers.phantom(typed);
-			return handlers.final(typed);
-		}
-		case "object": return handlers.object(def);
-		case "array": return handlers.array(def);
-		case "union": return handlers.union(def);
-		case "intersection": return handlers.intersection(def);
-		case "tuple": return handlers.tuple(def);
-		default: throw new Error(`Unknown type kind "${def.type.kind}"`);
-	}
-}
-
-//#endregion
 //#region packages/typescript/src/validator.ts
 function _define_property(obj, key, value) {
 	if (key in obj) Object.defineProperty(obj, key, {
@@ -31,28 +13,35 @@ else obj[key] = value;
 const regexCache = new Map();
 var Validator = class {
 	isLimitExceeded() {
-		if (this.stackErrors.length > 0) return this.stackErrors[this.stackErrors.length - 1].length >= this.opts.errorLimit;
+		if (this.stackErrors.length > 0) {
+			const top = this.stackErrors[this.stackErrors.length - 1];
+			return top !== null && top.length >= this.opts.errorLimit;
+		}
 		return this.errors.length >= this.opts.errorLimit;
 	}
 	push(name) {
 		this.stackPath.push(name);
-		this.stackErrors.push([]);
+		this.stackErrors.push(null);
+		this.cachedPath = this.stackPath.length <= 1 ? "" : this.stackPath[1] + (this.stackPath.length > 2 ? "." + this.stackPath.slice(2).join(".") : "");
 	}
 	pop(saveErrors) {
 		this.stackPath.pop();
 		const popped = this.stackErrors.pop();
-		if (saveErrors && popped?.length) popped.forEach((error) => {
-			this.error(error.message, error.path, error.details);
-		});
+		if (saveErrors && popped !== null && popped !== undefined && popped.length > 0) for (const err of popped) this.error(err.message, err.path, err.details);
+		this.cachedPath = this.stackPath.length <= 1 ? "" : this.stackPath[1] + (this.stackPath.length > 2 ? "." + this.stackPath.slice(2).join(".") : "");
 		return popped;
 	}
 	clear() {
-		this.stackErrors[this.stackErrors.length - 1] = [];
+		this.stackErrors[this.stackErrors.length - 1] = null;
 	}
 	error(message, path, details) {
-		const errors = this.stackErrors[this.stackErrors.length - 1] || this.errors;
+		let errors = this.stackErrors[this.stackErrors.length - 1];
+		if (!errors) if (this.stackErrors.length > 0) {
+			errors = [];
+			this.stackErrors[this.stackErrors.length - 1] = errors;
+		} else errors = this.errors;
 		const error = {
-			path: path || this.path,
+			path: path || this.cachedPath,
 			message
 		};
 		if (details?.length) error.details = details;
@@ -72,9 +61,10 @@ var Validator = class {
 	* @returns `true` if the value matches the type definition.
 	* @throws {ValidatorError} When validation fails and `safe` is not `true`.
 	*/ validate(value, safe, context) {
-		this.push("");
 		this.errors = [];
 		this.stackErrors = [];
+		this.stackPath = [""];
+		this.cachedPath = "";
 		this.context = context;
 		const passed = this.validateSafe(this.def, value);
 		this.pop(!passed);
@@ -88,7 +78,7 @@ var Validator = class {
 	validateSafe(def, value) {
 		if (this.isLimitExceeded()) return false;
 		if (!isAnnotatedType(def)) throw new Error("Can not validate not-annotated type");
-		if (typeof this.opts.replace === "function") def = this.opts.replace(def, this.path);
+		if (typeof this.opts.replace === "function") def = this.opts.replace(def, this.cachedPath);
 		if (def.optional && value === undefined) return true;
 		for (const plugin of this.opts.plugins) {
 			const result = plugin(this, def, value);
@@ -97,18 +87,21 @@ var Validator = class {
 		return this.validateAnnotatedType(def, value);
 	}
 	get path() {
-		return this.stackPath.slice(1).join(".");
+		return this.cachedPath;
 	}
 	validateAnnotatedType(def, value) {
-		return forAnnotatedType(def, {
-			final: (d) => this.validatePrimitive(d, value),
-			phantom: () => true,
-			object: (d) => this.validateObject(d, value),
-			array: (d) => this.validateArray(d, value),
-			union: (d) => this.validateUnion(d, value),
-			intersection: (d) => this.validateIntersection(d, value),
-			tuple: (d) => this.validateTuple(d, value)
-		});
+		switch (def.type.kind) {
+			case "": {
+				if (def.type.designType === "phantom") return true;
+				return this.validatePrimitive(def, value);
+			}
+			case "object": return this.validateObject(def, value);
+			case "array": return this.validateArray(def, value);
+			case "union": return this.validateUnion(def, value);
+			case "intersection": return this.validateIntersection(def, value);
+			case "tuple": return this.validateTuple(def, value);
+			default: throw new Error(`Unknown type kind "${def.type.kind}"`);
+		}
 	}
 	validateUnion(def, value) {
 		let i = 0;
@@ -172,6 +165,30 @@ var Validator = class {
 				return false;
 			}
 		}
+		const uniqueItems = def.metadata.get("expect.array.uniqueItems");
+		if (uniqueItems) {
+			const separator = "▼↩";
+			const seen = new Set();
+			const keyProps = new Set();
+			if (def.type.of.type.kind === "object") {
+				for (const [key, val] of def.type.of.type.props.entries()) if (val.metadata.get("expect.array.key")) keyProps.add(key);
+			}
+			for (let idx = 0; idx < value.length; idx++) {
+				const item = value[idx];
+				let key;
+				if (keyProps.size > 0) {
+					key = "";
+					for (const prop of keyProps) key += JSON.stringify(item[prop]) + separator;
+				} else key = JSON.stringify(item);
+				if (seen.has(key)) {
+					this.push(String(idx));
+					this.error(uniqueItems.message || "Duplicate items are not allowed");
+					this.pop(true);
+					return false;
+				}
+				seen.add(key);
+			}
+		}
 		let i = 0;
 		let passed = true;
 		for (const item of value) {
@@ -193,21 +210,20 @@ var Validator = class {
 		let passed = true;
 		const valueKeys = new Set(Object.keys(value));
 		const typeKeys = new Set();
-		const skipList = new Set();
+		let skipList;
 		if (this.opts.skipList) {
-			const path = this.stackPath.length > 1 ? `${this.path}.` : "";
-			this.opts.skipList.forEach((item) => {
-				if (item.startsWith(path)) {
-					const key = item.slice(path.length);
-					skipList.add(key);
-					valueKeys.delete(key);
-				}
-			});
+			const path = this.stackPath.length > 1 ? `${this.cachedPath}.` : "";
+			for (const item of this.opts.skipList) if (item.startsWith(path)) {
+				const key = item.slice(path.length);
+				if (!skipList) skipList = new Set();
+				skipList.add(key);
+				valueKeys.delete(key);
+			}
 		}
 		let partialFunctionMatched = false;
-		if (typeof this.opts.partial === "function") partialFunctionMatched = this.opts.partial(def, this.path);
+		if (typeof this.opts.partial === "function") partialFunctionMatched = this.opts.partial(def, this.cachedPath);
 		for (const [key, item] of def.type.props.entries()) {
-			if (skipList.has(key) || isPhantomType(item)) continue;
+			if (skipList && skipList.has(key) || isPhantomType(item)) continue;
 			typeKeys.add(key);
 			if (value[key] === undefined) {
 				if (partialFunctionMatched || this.opts.partial === "deep" || this.opts.partial === true && this.stackPath.length <= 1) continue;
@@ -228,19 +244,21 @@ else {
 				def: propDef
 			});
 			if (matched.length > 0) {
+				this.push(key);
 				let keyPassed = false;
-				for (const { def: def$1 } of matched) if (this.validateSafe(def$1, value[key])) {
-					this.pop(false);
-					keyPassed = true;
-					break;
+				for (const { def: propDef } of matched) {
+					if (this.validateSafe(propDef, value[key])) {
+						keyPassed = true;
+						break;
+					}
+					this.clear();
 				}
 				if (!keyPassed) {
-					this.push(key);
 					this.validateSafe(matched[0].def, value[key]);
 					this.pop(true);
 					passed = false;
 					if (this.isLimitExceeded()) return false;
-				}
+				} else this.pop(false);
 			} else if (this.opts.unknownProps !== "ignore") {
 				if (this.opts.unknownProps === "error") {
 					this.push(key);
@@ -393,11 +411,13 @@ else {
 		/** Validation errors collected during the last {@link validate} call. */ _define_property(this, "errors", void 0);
 		_define_property(this, "stackErrors", void 0);
 		_define_property(this, "stackPath", void 0);
+		_define_property(this, "cachedPath", void 0);
 		_define_property(this, "context", void 0);
 		this.def = def;
 		this.errors = [];
 		this.stackErrors = [];
 		this.stackPath = [];
+		this.cachedPath = "";
 		this.opts = {
 			partial: false,
 			unknownProps: "error",
@@ -611,6 +631,24 @@ function isAnnotatedTypeOfPrimitive(t) {
 	return false;
 }
 
+//#endregion
+//#region packages/typescript/src/traverse.ts
+function forAnnotatedType(def, handlers) {
+	switch (def.type.kind) {
+		case "": {
+			const typed = def;
+			if (handlers.phantom && typed.type.designType === "phantom") return handlers.phantom(typed);
+			return handlers.final(typed);
+		}
+		case "object": return handlers.object(def);
+		case "array": return handlers.array(def);
+		case "union": return handlers.union(def);
+		case "intersection": return handlers.intersection(def);
+		case "tuple": return handlers.tuple(def);
+		default: throw new Error(`Unknown type kind "${def.type.kind}"`);
+	}
+}
+
 //#endregion
 //#region packages/typescript/src/json-schema.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/typescript",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "description": "Atscript: typescript-gen support.",
   "keywords": [
     "annotations",
@@ -64,7 +64,7 @@
     "vitest": "3.2.4"
   },
   "peerDependencies": {
-    "@atscript/core": "^0.1.30"
+    "@atscript/core": "^0.1.32"
   },
   "build": [
     {},

package/skills/atscript-typescript/annotations.md

@@ -17,7 +17,7 @@
 | `@meta.required`      | `message?: string`         | Required field. Strings: non-whitespace. Booleans: must be `true`  |
 | `@meta.default`       | `value: string`            | Default value (strings as-is, others parsed as JSON)               |
 | `@meta.example`       | `value: string`            | Example value (strings as-is, others parsed as JSON)               |
-| `@expect.array.key`   | _(none)_                   | Mark field as key inside array (string/number types only)          |
+| `@expect.array.key`   | `message?: string`         | Mark field as key inside array (string/number only, non-optional). Multiple = composite key |
 
 ### `@expect.*` — Validation Constraints
 
@@ -29,6 +29,7 @@
 | `@expect.max`       | `maxValue: number`, `message?: string`                  | number        | Maximum value                                          |
 | `@expect.int`       | _(none)_                                                | number        | Must be integer                                        |
 | `@expect.pattern`   | `pattern: string`, `flags?: string`, `message?: string` | string        | Regex validation. **Multiple allowed** (all must pass) |
+| `@expect.array.uniqueItems` | `message?: string`                             | array         | No duplicate items (by key fields or deep equality)    |
 
 ### `@ui.*` — UI / Presentation Hints