@atscript/typescript 0.1.88 → 0.1.89

package/dist/utils.mjs

@@ -1,24 +1,52 @@
-import { Validator, ValidatorError, annotate, buildJsonSchema, cloneRefProp, createAnnotatedTypeNode, defineAnnotatedType, detectDiscriminator, forAnnotatedType, fromJsonSchema, isAnnotatedType, isAnnotatedTypeOfPrimitive, isPhantomType, mergeJsonSchemas } from "./json-schema-B64qclVa.mjs";
+import { a as forAnnotatedType, c as createAnnotatedTypeNode, d as isAnnotatedTypeOfPrimitive, f as isPhantomType, i as mergeJsonSchemas, l as defineAnnotatedType, m as ValidatorError, n as detectDiscriminator, o as annotate, p as Validator, r as fromJsonSchema, s as cloneRefProp, t as buildJsonSchema, u as isAnnotatedType } from "./json-schema-DycaD0Rm.mjs";
 
 //#region packages/typescript/src/runtime/coerce.ts
 /**
 * Internal sentinel returned when a value cannot be coerced to a type node.
 * Drives union branch selection without allocating per-node result objects.
 */ const NO_MATCH = Symbol("atscript.coerce.no-match");
-function coerceForType(def, value) {
+/**
+* Coerces string-transport input (route params, query strings) toward the
+* scalar shapes an annotated type expects.
+*
+* Pure and non-throwing: when a value can't be coerced it is returned
+* untouched, leaving the {@link Validator} to report the proper error.
+* Coercion converts representation only — constraint checks (`@expect.int`,
+* `@expect.min`, patterns) remain the validator's job.
+*
+* Rules:
+* - Strings targeting `number` are trimmed and parsed via `Number()`; only
+*   finite results are accepted.
+* - Strings targeting `boolean` accept `"true"/"1"` and `"false"/"0"`.
+* - Unions try each branch in declared order; the first successful parse wins.
+* - Objects recurse into props when the input is a plain object (covers
+*   `@Query()` DTOs where every field arrives as a string).
+* - Arrays and tuples coerce items; intersections apply each member in order.
+* - `string` / `decimal` targets never change string input.
+*
+* @example
+* ```ts
+* coerceForType(KafkaOffset, '42') // → 42
+* coerceForType(KafkaOffset, 'abc') // → 'abc' (validator reports the error)
+* ```
+*/ function coerceForType(def, value) {
 	const result = coerce(def, value);
 	return result === NO_MATCH ? value : result;
 }
-function coerceScalar(designType, value) {
+/**
+* Coerces a single scalar value toward a design type, using the same rules
+* as {@link coerceForType}. Returns the input untouched when it can't coerce.
+* Useful when only a design type is known (e.g. `design:paramtypes` fallbacks).
+*/ function coerceScalar(designType, value) {
 	const result = scalar(designType, value);
 	return result === NO_MATCH ? value : result;
 }
 /** Returns the coerced value, or NO_MATCH when the value can't fit this node. */ function coerce(def, value) {
-	if (value === undefined || value === null) return def.optional === true ? value : NO_MATCH;
+	if (value === void 0 || value === null) return def.optional === true ? value : NO_MATCH;
 	return forAnnotatedType(def, {
 		final: (d) => {
 			const result = scalar(d.type.designType, value);
-			if (result !== NO_MATCH && d.type.value !== undefined && result !== d.type.value) return NO_MATCH;
+			if (result !== NO_MATCH && d.type.value !== void 0 && result !== d.type.value) return NO_MATCH;
 			return result;
 		},
 		phantom: () => value,
@@ -27,7 +55,7 @@ function coerceScalar(designType, value) {
 			return coerceProps(d, value);
 		},
 		array: (d) => Array.isArray(value) ? coerceItems(value, d.type.of) : NO_MATCH,
-		tuple: (d) => Array.isArray(value) && value.length === d.type.items.length ? coerceItems(value, undefined, d.type.items) : NO_MATCH,
+		tuple: (d) => Array.isArray(value) && value.length === d.type.items.length ? coerceItems(value, void 0, d.type.items) : NO_MATCH,
 		union: (d) => {
 			for (const item of d.type.items) {
 				const result = coerce(item, value);
@@ -50,7 +78,7 @@ function scalar(designType, value) {
 	switch (designType) {
 		case "string":
 		case "decimal": return typeof value === "string" ? value : NO_MATCH;
-		case "number": {
+		case "number":
 			if (typeof value === "number") return value;
 			if (typeof value === "string") {
 				const trimmed = value.trim();
@@ -60,13 +88,11 @@ function scalar(designType, value) {
 				}
 			}
 			return NO_MATCH;
-		}
-		case "boolean": {
+		case "boolean":
 			if (typeof value === "boolean") return value;
 			if (value === "true" || value === "1") return true;
 			if (value === "false" || value === "0") return false;
 			return NO_MATCH;
-		}
 		case "object": return typeof value === "object" ? value : NO_MATCH;
 		case "any":
 		case "phantom": return value;
@@ -95,7 +121,7 @@ function scalar(designType, value) {
 			if (result !== NO_MATCH) coerced = result;
 		}
 		if (out) out[key] = coerced;
-else if (coerced !== input) {
+		else if (coerced !== input) {
 			out = {};
 			for (let j = 0; j < i; j++) out[keys[j]] = value[keys[j]];
 			out[key] = coerced;
@@ -113,7 +139,7 @@ else if (coerced !== input) {
 		const result = coerce(of ?? items[i], input);
 		const coerced = result === NO_MATCH ? input : result;
 		if (out) out.push(coerced);
-else if (coerced !== input) {
+		else if (coerced !== input) {
 			out = value.slice(0, i);
 			out.push(coerced);
 		}
@@ -132,33 +158,32 @@ function isPlainObject(value) {
 * Attempts to resolve a value from the mode for the given annotated type.
 * Returns `undefined` when no value is available (or parse/validation fails).
 */ function resolveValue(prop, path, mode) {
-	if (!mode || mode === "empty") return undefined;
+	if (!mode || mode === "empty") return;
 	let raw;
 	if (typeof mode === "function") {
 		raw = mode(prop, path);
-		if (raw === undefined) return undefined;
+		if (raw === void 0) return;
 		if (prop.validator({ unknownProps: "ignore" }).validate(raw, true)) return { value: raw };
-		return undefined;
+		return;
 	}
 	if (mode === "db") {
 		const dbValue = prop.metadata.get("db.default");
-		if (dbValue !== undefined) {
-			const parsed$1 = parseRawValue(dbValue, prop);
-			if (parsed$1 !== undefined && prop.validator({ unknownProps: "ignore" }).validate(parsed$1, true)) return { value: parsed$1 };
-			return undefined;
+		if (dbValue !== void 0) {
+			const parsed = parseRawValue(dbValue, prop);
+			if (parsed !== void 0 && prop.validator({ unknownProps: "ignore" }).validate(parsed, true)) return { value: parsed };
+			return;
 		}
 		if (prop.metadata.has("db.default.increment")) return { value: "increment" };
 		if (prop.metadata.has("db.default.uuid")) return { value: "uuid" };
 		if (prop.metadata.has("db.default.now")) return { value: "now" };
-		return undefined;
+		return;
 	}
 	const metaKey = mode === "default" ? "meta.default" : "meta.example";
 	const rawStr = prop.metadata.get(metaKey);
-	if (rawStr === undefined) return undefined;
+	if (rawStr === void 0) return;
 	const parsed = parseRawValue(rawStr, prop);
-	if (parsed === undefined) return undefined;
+	if (parsed === void 0) return;
 	if (prop.validator({ unknownProps: "ignore" }).validate(parsed, true)) return { value: parsed };
-	return undefined;
 }
 /**
 * Parses a raw annotation string into a JS value.
@@ -168,28 +193,45 @@ function isPlainObject(value) {
 	try {
 		return JSON.parse(raw);
 	} catch {
-		return undefined;
+		return;
 	}
 }
 /** Returns the structural default for a final (primitive/literal) type. */ function finalDefault(def) {
-	if (def.type.value !== undefined) return def.type.value;
+	if (def.type.value !== void 0) return def.type.value;
 	switch (def.type.designType) {
 		case "string": return "";
 		case "number": return 0;
 		case "boolean": return false;
-		case "undefined": return undefined;
+		case "undefined": return;
 		case "null": return null;
-		default: return undefined;
+		default: return;
 	}
 }
-function createDataFromAnnotatedType(type, opts) {
+/**
+* Creates a data object from an ATScript annotated type definition.
+*
+* Supports five modes:
+* - `'empty'` — structural defaults only; optional props omitted
+* - `'default'` — uses `@meta.default` annotations; optional props omitted unless annotated
+* - `'example'` — uses `@meta.example` annotations; optional props always included; arrays get one sample item
+* - `'db'` — uses `@db.default` (parsed) or `@db.default.increment/uuid/now` (fn name string); optional props omitted unless annotated
+* - `function` — custom resolver; optional props omitted unless resolver returns a value
+*
+* When a `@meta.default` / `@meta.example` value is set on a complex type (object, array)
+* and passes full validation, the entire subtree is replaced — no recursion into inner props.
+* If validation fails, the annotation is ignored and structural defaults are built from inner props.
+*
+* @param type - The ATScript annotated type to create data from.
+* @param opts - Options controlling value resolution mode.
+* @returns A value conforming to the type's shape.
+*/ function createDataFromAnnotatedType(type, opts) {
 	return build(type, "", opts?.mode);
 }
 function build(def, path, mode) {
 	const resolved = resolveValue(def, path, mode);
-	if (resolved !== undefined) return resolved.value;
+	if (resolved !== void 0) return resolved.value;
 	return forAnnotatedType(def, {
-		phantom: () => undefined,
+		phantom: () => void 0,
 		final: (d) => finalDefault(d),
 		object: (d) => {
 			const data = {};
@@ -198,9 +240,9 @@ function build(def, path, mode) {
 				const childPath = path ? `${path}.${key}` : key;
 				if (prop.optional) {
 					if (mode === "example") data[key] = build(prop, childPath, mode);
-else {
+					else {
 						const childResolved = resolveValue(prop, childPath, mode);
-						if (childResolved !== undefined) data[key] = childResolved.value;
+						if (childResolved !== void 0) data[key] = childResolved.value;
 					}
 					continue;
 				}
@@ -211,25 +253,28 @@ else {
 		array: (d) => {
 			if (mode === "example") {
 				const item = build(d.type.of, `${path}.0`, mode);
-				return item !== undefined ? [item] : [];
+				return item !== void 0 ? [item] : [];
 			}
 			return [];
 		},
 		tuple: (d) => d.type.items.map((item, i) => build(item, `${path}.${i}`, mode)),
 		union: (d) => {
 			const first = d.type.items[0];
-			return first ? build(first, path, mode) : undefined;
+			return first ? build(first, path, mode) : void 0;
 		},
 		intersection: (d) => {
 			const first = d.type.items[0];
-			return first ? build(first, path, mode) : undefined;
+			return first ? build(first, path, mode) : void 0;
 		}
 	});
 }
 
 //#endregion
 //#region packages/typescript/src/runtime/throw-disabled.ts
-function throwFeatureDisabled(feature, option, annotation) {
+/**
+* Throws a runtime error indicating that a feature is disabled.
+* Used by generated JS files to avoid duplicating the error message string.
+*/ function throwFeatureDisabled(feature, option, annotation) {
 	throw new Error(`${feature} support is disabled. To enable, set \`${option}: 'lazy'\` or \`${option}: 'bundle'\` in tsPlugin options, or add @${annotation} annotation to individual interfaces.`);
 }
 
@@ -251,7 +296,7 @@ function throwFeatureDisabled(feature, option, annotation) {
 * @param type - The root annotated type (must be an object type).
 * @param options - Optional hooks for domain-specific processing.
 * @returns A map of dot-separated field paths to their annotated types.
-*/ const EMPTY_ANCESTORS = new Set();
+*/ const EMPTY_ANCESTORS = /* @__PURE__ */ new Set();
 function extendAncestors(ancestors, id) {
 	if (!id || ancestors.has(id)) return ancestors;
 	const next = new Set(ancestors);
@@ -259,14 +304,14 @@ function extendAncestors(ancestors, id) {
 	return next;
 }
 function flattenAnnotatedType(type, options) {
-	const flatMap = new Map();
+	const flatMap = /* @__PURE__ */ new Map();
 	const skipPhantom = !!options?.excludePhantomTypes;
 	function addFieldToFlatMap(name, def) {
 		const existing = flatMap.get(name);
 		if (existing) {
 			const flatUnion = defineAnnotatedType("union").copyMetadata(existing.metadata).copyMetadata(def.metadata);
 			if (existing.__flat_union) existing.type.items.forEach((item) => flatUnion.item(item));
-else flatUnion.item(existing);
+			else flatUnion.item(existing);
 			flatUnion.item(def);
 			const unionType = flatUnion.$type;
 			unionType.__flat_union = true;
@@ -292,14 +337,12 @@ else flatUnion.item(existing);
 			}
 			case "union":
 			case "intersection":
-			case "tuple": {
+			case "tuple":
 				for (const item of def.type.items) flattenArray(item, name, childAncestors);
 				break;
-			}
-			case "array": {
+			case "array":
 				flattenArray(def.type.of, name, childAncestors);
 				break;
-			}
 			default:
 		}
 	}
@@ -322,14 +365,13 @@ else flatUnion.item(existing);
 			childAncestors = extendAncestors(ancestors, typeId);
 		}
 		switch (kind) {
-			case "object": {
+			case "object":
 				addFieldToFlatMap(prefix || "", def);
 				for (const [key, value] of def.type.props.entries()) {
 					if (skipPhantom && isPhantomType(value)) continue;
 					flattenType(value, prefix ? `${prefix}.${key}` : key, inComplexTypeOrArray, childAncestors);
 				}
 				break;
-			}
 			case "array": {
 				let typeArray = def;
 				if (!inComplexTypeOrArray) {
@@ -343,7 +385,7 @@ else flatUnion.item(existing);
 			}
 			case "intersection":
 			case "tuple":
-			case "union": {
+			case "union":
 				for (const item of def.type.items) flattenType(item, prefix, true, childAncestors);
 				addFieldToFlatMap(prefix || "", def);
 				if (def.optional) {
@@ -351,11 +393,9 @@ else flatUnion.item(existing);
 					if (entry) entry.optional = def.optional;
 				}
 				break;
-			}
-			default: {
+			default:
 				addFieldToFlatMap(prefix || "", def);
 				break;
-			}
 		}
 		if (prefix) options?.onField?.(prefix, def, def.metadata);
 	}
@@ -365,10 +405,26 @@ else flatUnion.item(existing);
 
 //#endregion
 //#region packages/typescript/src/runtime/serialize.ts
-const SERIALIZE_VERSION = 2;
-function serializeAnnotatedType(type, options) {
-	const visited = new Set();
-	const result = serializeNode(type, [], options, visited);
+/** Current serialization format version. Bumped on breaking changes to the serialized shape. */ const SERIALIZE_VERSION = 2;
+/**
+* Converts a runtime {@link TAtscriptAnnotatedType} into a plain JSON-safe object.
+*
+* The result can be stored, transmitted over the network, and later
+* restored with {@link deserializeAnnotatedType}.
+*
+* @example
+* ```ts
+* import { serializeAnnotatedType } from '@atscript/typescript'
+*
+* const json = serializeAnnotatedType(MyInterface)
+* // json is a plain object safe for JSON.stringify
+* ```
+*
+* @param type - The annotated type to serialize.
+* @param options - Optional filtering/transformation for annotations.
+* @returns A versioned, JSON-safe representation of the type.
+*/ function serializeAnnotatedType(type, options) {
+	const result = serializeNode(type, [], options, /* @__PURE__ */ new Set());
 	result.$v = SERIALIZE_VERSION;
 	return result;
 }
@@ -423,23 +479,22 @@ function serializeTypeDef(def, path, options, visited) {
 				designType: d.type.designType,
 				tags: Array.from(d.type.tags)
 			};
-			if (d.type.value !== undefined) result.value = d.type.value;
+			if (d.type.value !== void 0) result.value = d.type.value;
 			return result;
 		},
 		object(d) {
 			const props = {};
 			for (const [key, val] of d.type.props.entries()) props[key] = serializeNode(val, [...path, key], options, visited);
-			const propsPatterns = d.type.propsPatterns.map((pp) => ({
-				pattern: {
-					source: pp.pattern.source,
-					flags: pp.pattern.flags
-				},
-				def: serializeNode(pp.def, path, options, visited)
-			}));
 			return {
 				kind: "object",
 				props,
-				propsPatterns,
+				propsPatterns: d.type.propsPatterns.map((pp) => ({
+					pattern: {
+						source: pp.pattern.source,
+						flags: pp.pattern.flags
+					},
+					def: serializeNode(pp.def, path, options, visited)
+				})),
 				tags: Array.from(d.type.tags)
 			};
 		},
@@ -475,7 +530,7 @@ function serializeTypeDef(def, path, options, visited) {
 }
 function serializeMetadata(metadata, path, kind, options) {
 	const result = {};
-	const ignoreSet = options?.ignoreAnnotations ? new Set(options.ignoreAnnotations) : undefined;
+	const ignoreSet = options?.ignoreAnnotations ? new Set(options.ignoreAnnotations) : void 0;
 	for (const [key, value] of metadata.entries()) {
 		if (ignoreSet?.has(key)) continue;
 		if (options?.processAnnotation) {
@@ -485,7 +540,7 @@ function serializeMetadata(metadata, path, kind, options) {
 				path,
 				kind
 			});
-			if (processed === undefined || processed === null) continue;
+			if (processed === void 0 || processed === null) continue;
 			result[processed.key] = processed.value;
 			continue;
 		}
@@ -493,17 +548,33 @@ function serializeMetadata(metadata, path, kind, options) {
 	}
 	return result;
 }
-function deserializeAnnotatedType(data) {
+/**
+* Restores a runtime {@link TAtscriptAnnotatedType} from its serialized form.
+*
+* The returned object is fully functional — it has a working `.validator()` method
+* and can be used with {@link buildJsonSchema} or the {@link Validator} directly.
+*
+* @example
+* ```ts
+* import { deserializeAnnotatedType } from '@atscript/typescript'
+*
+* const type = deserializeAnnotatedType(json)
+* type.validator().validate(someValue) // works
+* ```
+*
+* @param data - A serialized type produced by {@link serializeAnnotatedType}.
+* @returns A live annotated type with validator support.
+* @throws If the serialized version doesn't match {@link SERIALIZE_VERSION}.
+*/ function deserializeAnnotatedType(data) {
 	if (data.$v !== SERIALIZE_VERSION) throw new Error(`Unsupported serialized type version: ${data.$v} (expected ${SERIALIZE_VERSION})`);
-	const resolved = new Map();
-	return deserializeNode(data, resolved);
+	return deserializeNode(data, /* @__PURE__ */ new Map());
 }
 function emptyObjectTypeDef() {
 	return {
 		kind: "object",
-		props: new Map(),
+		props: /* @__PURE__ */ new Map(),
 		propsPatterns: [],
-		tags: new Set()
+		tags: /* @__PURE__ */ new Set()
 	};
 }
 function toMetadataMap(record) {
@@ -512,7 +583,7 @@ function toMetadataMap(record) {
 function deserializeNode(data, resolved) {
 	if (data.type.kind === "$ref") {
 		const refId = data.type.id;
-		return resolved.get(refId) || createAnnotatedTypeNode(emptyObjectTypeDef(), new Map(), { id: refId });
+		return resolved.get(refId) || createAnnotatedTypeNode(emptyObjectTypeDef(), /* @__PURE__ */ new Map(), { id: refId });
 	}
 	const metadata = toMetadataMap(data.metadata);
 	let result;
@@ -520,7 +591,7 @@ function deserializeNode(data, resolved) {
 		const existing = resolved.get(data.id);
 		if (existing) return existing;
 		result = createAnnotatedTypeNode(emptyObjectTypeDef(), metadata, {
-			optional: data.optional || undefined,
+			optional: data.optional || void 0,
 			id: data.id
 		});
 		resolved.set(data.id, result);
@@ -536,7 +607,7 @@ function deserializeNode(data, resolved) {
 				field: data.ref.field
 			};
 		} else {
-			const sentinel = createAnnotatedTypeNode(emptyObjectTypeDef(), toMetadataMap(refTargetData.metadata), { id: refTargetData.id || undefined });
+			const sentinel = createAnnotatedTypeNode(emptyObjectTypeDef(), toMetadataMap(refTargetData.metadata), { id: refTargetData.id || void 0 });
 			ref = {
 				type: () => sentinel,
 				field: data.ref.field
@@ -549,13 +620,13 @@ function deserializeNode(data, resolved) {
 		return result;
 	}
 	return createAnnotatedTypeNode(type, metadata, {
-		optional: data.optional || undefined,
-		id: data.id || undefined,
+		optional: data.optional || void 0,
+		id: data.id || void 0,
 		ref
 	});
 }
 function deserializeTypeDef(t, resolved) {
-	const tags = "tags" in t ? new Set(t.tags) : new Set();
+	const tags = "tags" in t ? new Set(t.tags) : /* @__PURE__ */ new Set();
 	switch (t.kind) {
 		case "": {
 			const result = {
@@ -563,20 +634,19 @@ function deserializeTypeDef(t, resolved) {
 				designType: t.designType,
 				tags
 			};
-			if (t.value !== undefined) result.value = t.value;
+			if (t.value !== void 0) result.value = t.value;
 			return result;
 		}
 		case "object": {
-			const props = new Map();
+			const props = /* @__PURE__ */ new Map();
 			for (const [key, val] of Object.entries(t.props)) props.set(key, deserializeNode(val, resolved));
-			const propsPatterns = t.propsPatterns.map((pp) => ({
-				pattern: new RegExp(pp.pattern.source, pp.pattern.flags),
-				def: deserializeNode(pp.def, resolved)
-			}));
 			return {
 				kind: "object",
 				props,
-				propsPatterns,
+				propsPatterns: t.propsPatterns.map((pp) => ({
+					pattern: new RegExp(pp.pattern.source, pp.pattern.flags),
+					def: deserializeNode(pp.def, resolved)
+				})),
 				tags
 			};
 		}
@@ -597,7 +667,7 @@ function deserializeTypeDef(t, resolved) {
 			if (existing) return existing.type;
 			return {
 				kind: "object",
-				props: new Map(),
+				props: /* @__PURE__ */ new Map(),
 				propsPatterns: [],
 				tags
 			};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/typescript",
-  "version": "0.1.88",
+  "version": "0.1.89",
   "description": "Atscript: typescript-gen support.",
   "keywords": [
     "annotations",
@@ -73,7 +73,7 @@
   },
   "peerDependencies": {
     "@atscript/db": "^0.1.97",
-    "@atscript/core": "^0.1.88"
+    "@atscript/core": "^0.1.89"
   },
   "peerDependenciesMeta": {
     "@atscript/db": {