@atscript/typescript 0.1.23 → 0.1.25

package/dist/cli.cjs

@@ -991,6 +991,46 @@ function isPhantomType(def) {
 
 //#endregion
 //#region packages/typescript/src/json-schema.ts
+/**
+* Detects a discriminator property across union items.
+*
+* Scans all items for object-typed members that share a common property
+* with distinct const/literal values. If exactly one such property exists,
+* it is returned as the discriminator.
+*/ function detectDiscriminator(items) {
+	if (items.length < 2) return null;
+	for (const item of items) if (item.type.kind !== "object") return null;
+	const firstObj = items[0].type;
+	const candidates = [];
+	for (const [propName, propType] of firstObj.props.entries()) if (propType.type.kind === "" && propType.type.value !== undefined) candidates.push(propName);
+	const validCandidates = [];
+	for (const candidate of candidates) {
+		const values = new Set();
+		const mapping = {};
+		let valid = true;
+		for (let i = 0; i < items.length; i++) {
+			const obj = items[i].type;
+			const prop = obj.props.get(candidate);
+			if (!prop || prop.type.kind !== "" || prop.type.value === undefined) {
+				valid = false;
+				break;
+			}
+			const val = prop.type.value;
+			if (values.has(val)) {
+				valid = false;
+				break;
+			}
+			values.add(val);
+			mapping[String(val)] = `#/oneOf/${i}`;
+		}
+		if (valid) validCandidates.push({
+			propertyName: candidate,
+			mapping
+		});
+	}
+	if (validCandidates.length === 1) return validCandidates[0];
+	return null;
+}
 function buildJsonSchema(type) {
 	const build$1 = (def) => {
 		const meta = def.metadata;
@@ -1025,6 +1065,14 @@ function buildJsonSchema(type) {
 				return schema;
 			},
 			union(d) {
+				const disc = detectDiscriminator(d.type.items);
+				if (disc) return {
+					oneOf: d.type.items.map(build$1),
+					discriminator: {
+						propertyName: disc.propertyName,
+						mapping: disc.mapping
+					}
+				};
 				return { anyOf: d.type.items.map(build$1) };
 			},
 			intersection(d) {

package/dist/index.cjs

@@ -988,6 +988,46 @@ function isPhantomType(def) {
 
 //#endregion
 //#region packages/typescript/src/json-schema.ts
+/**
+* Detects a discriminator property across union items.
+*
+* Scans all items for object-typed members that share a common property
+* with distinct const/literal values. If exactly one such property exists,
+* it is returned as the discriminator.
+*/ function detectDiscriminator(items) {
+	if (items.length < 2) return null;
+	for (const item of items) if (item.type.kind !== "object") return null;
+	const firstObj = items[0].type;
+	const candidates = [];
+	for (const [propName, propType] of firstObj.props.entries()) if (propType.type.kind === "" && propType.type.value !== undefined) candidates.push(propName);
+	const validCandidates = [];
+	for (const candidate of candidates) {
+		const values = new Set();
+		const mapping = {};
+		let valid = true;
+		for (let i = 0; i < items.length; i++) {
+			const obj = items[i].type;
+			const prop = obj.props.get(candidate);
+			if (!prop || prop.type.kind !== "" || prop.type.value === undefined) {
+				valid = false;
+				break;
+			}
+			const val = prop.type.value;
+			if (values.has(val)) {
+				valid = false;
+				break;
+			}
+			values.add(val);
+			mapping[String(val)] = `#/oneOf/${i}`;
+		}
+		if (valid) validCandidates.push({
+			propertyName: candidate,
+			mapping
+		});
+	}
+	if (validCandidates.length === 1) return validCandidates[0];
+	return null;
+}
 function buildJsonSchema(type) {
 	const build = (def) => {
 		const meta = def.metadata;
@@ -1022,6 +1062,14 @@ function buildJsonSchema(type) {
 				return schema;
 			},
 			union(d) {
+				const disc = detectDiscriminator(d.type.items);
+				if (disc) return {
+					oneOf: d.type.items.map(build),
+					discriminator: {
+						propertyName: disc.propertyName,
+						mapping: disc.mapping
+					}
+				};
 				return { anyOf: d.type.items.map(build) };
 			},
 			intersection(d) {

package/dist/index.mjs

@@ -964,6 +964,46 @@ function isPhantomType(def) {
 
 //#endregion
 //#region packages/typescript/src/json-schema.ts
+/**
+* Detects a discriminator property across union items.
+*
+* Scans all items for object-typed members that share a common property
+* with distinct const/literal values. If exactly one such property exists,
+* it is returned as the discriminator.
+*/ function detectDiscriminator(items) {
+	if (items.length < 2) return null;
+	for (const item of items) if (item.type.kind !== "object") return null;
+	const firstObj = items[0].type;
+	const candidates = [];
+	for (const [propName, propType] of firstObj.props.entries()) if (propType.type.kind === "" && propType.type.value !== undefined) candidates.push(propName);
+	const validCandidates = [];
+	for (const candidate of candidates) {
+		const values = new Set();
+		const mapping = {};
+		let valid = true;
+		for (let i = 0; i < items.length; i++) {
+			const obj = items[i].type;
+			const prop = obj.props.get(candidate);
+			if (!prop || prop.type.kind !== "" || prop.type.value === undefined) {
+				valid = false;
+				break;
+			}
+			const val = prop.type.value;
+			if (values.has(val)) {
+				valid = false;
+				break;
+			}
+			values.add(val);
+			mapping[String(val)] = `#/oneOf/${i}`;
+		}
+		if (valid) validCandidates.push({
+			propertyName: candidate,
+			mapping
+		});
+	}
+	if (validCandidates.length === 1) return validCandidates[0];
+	return null;
+}
 function buildJsonSchema(type) {
 	const build = (def) => {
 		const meta = def.metadata;
@@ -998,6 +1038,14 @@ function buildJsonSchema(type) {
 				return schema;
 			},
 			union(d) {
+				const disc = detectDiscriminator(d.type.items);
+				if (disc) return {
+					oneOf: d.type.items.map(build),
+					discriminator: {
+						propertyName: disc.propertyName,
+						mapping: disc.mapping
+					}
+				};
 				return { anyOf: d.type.items.map(build) };
 			},
 			intersection(d) {

package/dist/utils.cjs

@@ -552,6 +552,46 @@ function isAnnotatedTypeOfPrimitive(t) {
 
 //#endregion
 //#region packages/typescript/src/json-schema.ts
+/**
+* Detects a discriminator property across union items.
+*
+* Scans all items for object-typed members that share a common property
+* with distinct const/literal values. If exactly one such property exists,
+* it is returned as the discriminator.
+*/ function detectDiscriminator(items) {
+	if (items.length < 2) return null;
+	for (const item of items) if (item.type.kind !== "object") return null;
+	const firstObj = items[0].type;
+	const candidates = [];
+	for (const [propName, propType] of firstObj.props.entries()) if (propType.type.kind === "" && propType.type.value !== undefined) candidates.push(propName);
+	const validCandidates = [];
+	for (const candidate of candidates) {
+		const values = new Set();
+		const mapping = {};
+		let valid = true;
+		for (let i = 0; i < items.length; i++) {
+			const obj = items[i].type;
+			const prop = obj.props.get(candidate);
+			if (!prop || prop.type.kind !== "" || prop.type.value === undefined) {
+				valid = false;
+				break;
+			}
+			const val = prop.type.value;
+			if (values.has(val)) {
+				valid = false;
+				break;
+			}
+			values.add(val);
+			mapping[String(val)] = `#/oneOf/${i}`;
+		}
+		if (valid) validCandidates.push({
+			propertyName: candidate,
+			mapping
+		});
+	}
+	if (validCandidates.length === 1) return validCandidates[0];
+	return null;
+}
 function buildJsonSchema(type) {
 	const build$1 = (def) => {
 		const meta = def.metadata;
@@ -586,6 +626,14 @@ function buildJsonSchema(type) {
 				return schema;
 			},
 			union(d) {
+				const disc = detectDiscriminator(d.type.items);
+				if (disc) return {
+					oneOf: d.type.items.map(build$1),
+					discriminator: {
+						propertyName: disc.propertyName,
+						mapping: disc.mapping
+					}
+				};
 				return { anyOf: d.type.items.map(build$1) };
 			},
 			intersection(d) {
@@ -778,15 +826,24 @@ function build(def, path, mode) {
 				if (isPhantomType(prop)) continue;
 				const childPath = path ? `${path}.${key}` : key;
 				if (prop.optional) {
-					const childResolved = resolveValue(prop, childPath, mode);
-					if (childResolved !== undefined) data[key] = childResolved.value;
+					if (mode === "example") data[key] = build(prop, childPath, mode);
+else {
+						const childResolved = resolveValue(prop, childPath, mode);
+						if (childResolved !== undefined) data[key] = childResolved.value;
+					}
 					continue;
 				}
 				data[key] = build(prop, childPath, mode);
 			}
 			return data;
 		},
-		array: () => [],
+		array: (d) => {
+			if (mode === "example") {
+				const item = build(d.type.of, `${path}.0`, mode);
+				return item !== undefined ? [item] : [];
+			}
+			return [];
+		},
 		tuple: (d) => d.type.items.map((item, i) => build(item, `${path}.${i}`, mode)),
 		union: (d) => {
 			const first = d.type.items[0];

package/dist/utils.d.ts

@@ -332,7 +332,7 @@ interface TCreateDataOptions {
      * How to resolve values:
      * - `'empty'` — structural defaults only (`''`, `0`, `false`, `[]`, `{}`); optional props skipped
      * - `'default'` — use `@meta.default` annotations; optional props skipped unless annotated
-     * - `'example'` — use `@meta.example` annotations; optional props skipped unless annotated
+     * - `'example'` — use `@meta.example` annotations; optional props always included; arrays get one sample item
      * - `function` — custom resolver per field; optional props skipped unless resolver returns a value
      *
      * @default 'empty'
@@ -345,7 +345,7 @@ interface TCreateDataOptions {
  * Supports four 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 omitted unless annotated
+ * - `'example'` — uses `@meta.example` annotations; optional props always included; arrays get one sample item
  * - `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)

package/dist/utils.mjs

@@ -551,6 +551,46 @@ function isAnnotatedTypeOfPrimitive(t) {
 
 //#endregion
 //#region packages/typescript/src/json-schema.ts
+/**
+* Detects a discriminator property across union items.
+*
+* Scans all items for object-typed members that share a common property
+* with distinct const/literal values. If exactly one such property exists,
+* it is returned as the discriminator.
+*/ function detectDiscriminator(items) {
+	if (items.length < 2) return null;
+	for (const item of items) if (item.type.kind !== "object") return null;
+	const firstObj = items[0].type;
+	const candidates = [];
+	for (const [propName, propType] of firstObj.props.entries()) if (propType.type.kind === "" && propType.type.value !== undefined) candidates.push(propName);
+	const validCandidates = [];
+	for (const candidate of candidates) {
+		const values = new Set();
+		const mapping = {};
+		let valid = true;
+		for (let i = 0; i < items.length; i++) {
+			const obj = items[i].type;
+			const prop = obj.props.get(candidate);
+			if (!prop || prop.type.kind !== "" || prop.type.value === undefined) {
+				valid = false;
+				break;
+			}
+			const val = prop.type.value;
+			if (values.has(val)) {
+				valid = false;
+				break;
+			}
+			values.add(val);
+			mapping[String(val)] = `#/oneOf/${i}`;
+		}
+		if (valid) validCandidates.push({
+			propertyName: candidate,
+			mapping
+		});
+	}
+	if (validCandidates.length === 1) return validCandidates[0];
+	return null;
+}
 function buildJsonSchema(type) {
 	const build$1 = (def) => {
 		const meta = def.metadata;
@@ -585,6 +625,14 @@ function buildJsonSchema(type) {
 				return schema;
 			},
 			union(d) {
+				const disc = detectDiscriminator(d.type.items);
+				if (disc) return {
+					oneOf: d.type.items.map(build$1),
+					discriminator: {
+						propertyName: disc.propertyName,
+						mapping: disc.mapping
+					}
+				};
 				return { anyOf: d.type.items.map(build$1) };
 			},
 			intersection(d) {
@@ -777,15 +825,24 @@ function build(def, path, mode) {
 				if (isPhantomType(prop)) continue;
 				const childPath = path ? `${path}.${key}` : key;
 				if (prop.optional) {
-					const childResolved = resolveValue(prop, childPath, mode);
-					if (childResolved !== undefined) data[key] = childResolved.value;
+					if (mode === "example") data[key] = build(prop, childPath, mode);
+else {
+						const childResolved = resolveValue(prop, childPath, mode);
+						if (childResolved !== undefined) data[key] = childResolved.value;
+					}
 					continue;
 				}
 				data[key] = build(prop, childPath, mode);
 			}
 			return data;
 		},
-		array: () => [],
+		array: (d) => {
+			if (mode === "example") {
+				const item = build(d.type.of, `${path}.0`, mode);
+				return item !== undefined ? [item] : [];
+			}
+			return [];
+		},
 		tuple: (d) => d.type.items.map((item, i) => build(item, `${path}.${i}`, mode)),
 		union: (d) => {
 			const first = d.type.items[0];

package/package.json

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

package/skills/atscript-typescript/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: atscript-typescript
-description: Atscript TypeScript language extension — .as file syntax, code generation, runtime type system, validation, and utilities for the Atscript metadata description language.
+description: Use when working with Atscript (.as files) in TypeScript projects — writing or editing .as interfaces/types/annotations, configuring atscript.config.ts or tsPlugin, understanding generated .d.ts/.js output, using runtime APIs (TAtscriptAnnotatedType, metadata, validators), generating JSON Schema or example data from types, serializing/deserializing annotated types, or running the asc CLI.
 ---
 
 # @atscript/typescript

package/skills/atscript-typescript/utilities.md

@@ -88,11 +88,15 @@ const schema = buildJsonSchema(User)
 | `@expect.pattern` (multiple) | `allOf: [{ pattern }, ...]` |
 | `@meta.required` on string | `minLength: 1` |
 | optional property | not in `required` array |
-| union | `anyOf` |
+| union | `anyOf` (or `oneOf` + `discriminator` for discriminated unions) |
 | intersection | `allOf` |
 | tuple | `items` as array |
 | phantom | empty object `{}` (excluded) |
 
+### Discriminated Unions
+
+When all union items are objects sharing exactly one property with distinct const/literal values, `buildJsonSchema` auto-detects it and emits `oneOf` with a `discriminator` object (including `propertyName` and `mapping`) instead of `anyOf`. No annotations needed — detection is automatic.
+
 ## `fromJsonSchema(schema)` — JSON Schema → Annotated Type
 
 The inverse of `buildJsonSchema`. Creates a fully functional annotated type from a JSON Schema:
@@ -257,12 +261,13 @@ const custom = createDataFromAnnotatedType(User, {
 |------|----------|
 | `'empty'` (default) | Structural defaults: `''`, `0`, `false`, `[]`, `{}`. Optional props omitted |
 | `'default'` | Uses `@meta.default` annotations. Optional props only included if annotated |
-| `'example'` | Uses `@meta.example` annotations. Optional props only included if annotated |
+| `'example'` | Uses `@meta.example` annotations. Optional props always included. Arrays get one sample item |
 | `function` | Custom resolver per field. Return `undefined` to fall through |
 
 ### Behavior Notes
 
-- **Optional properties** are omitted unless the mode provides a value for them
+- **Optional properties** are omitted unless the mode provides a value for them (exception: `'example'` mode always includes all optional props)
+- **Arrays** in `'example'` mode generate one sample item from the element type instead of an empty array
 - **Complex types** (object, array): if a `@meta.default`/`@meta.example` annotation is set and passes validation, the entire subtree is replaced (no recursion into inner props)
 - **Annotation values**: strings are used as-is for string types; everything else is parsed via `JSON.parse`
 - **Unions/Intersections**: defaults to first item's value