@atscript/typescript 0.1.44 → 0.1.46

package/dist/utils.cjs

@@ -219,7 +219,7 @@ else flatUnion.item(existing);
 
 //#endregion
 //#region packages/typescript/src/runtime/serialize.ts
-const SERIALIZE_VERSION = 1;
+const SERIALIZE_VERSION = 2;
 function serializeAnnotatedType(type, options) {
 	const visited = new Set();
 	const result = serializeNode(type, [], options, visited);
@@ -243,6 +243,17 @@ function serializeNode(def, path, options, visited) {
 	};
 	if (def.optional) result.optional = true;
 	if (def.id) result.id = def.id;
+	const refDepth = options?.refDepth ?? 0;
+	if (refDepth > 0 && def.ref) {
+		const refTarget = def.ref.type();
+		if (refTarget) result.ref = {
+			type: serializeNode(refTarget, [], {
+				...options,
+				refDepth: refDepth - 1
+			}, visited),
+			field: def.ref.field
+		};
+	}
 	return result;
 }
 function serializeTypeDef(def, path, options, visited) {
@@ -332,18 +343,56 @@ function serializeMetadata(metadata, path, kind, options) {
 }
 function deserializeAnnotatedType(data) {
 	if (data.$v !== SERIALIZE_VERSION) throw new Error(`Unsupported serialized type version: ${data.$v} (expected ${SERIALIZE_VERSION})`);
-	return deserializeNode(data);
+	const resolved = new Map();
+	return deserializeNode(data, resolved);
 }
-function deserializeNode(data) {
+function deserializeNode(data, resolved) {
+	if (data.type.kind === "$ref") {
+		const refId = data.type.id;
+		return resolved.get(refId) || require_json_schema.createAnnotatedTypeNode({
+			kind: "object",
+			props: new Map(),
+			propsPatterns: [],
+			tags: new Set()
+		}, new Map(), { id: refId });
+	}
 	const metadata = new Map(Object.entries(data.metadata));
-	const type = deserializeTypeDef(data.type);
-	const result = require_json_schema.createAnnotatedTypeNode(type, metadata, {
+	let result;
+	if (data.id) {
+		const existing = resolved.get(data.id);
+		if (existing) return existing;
+		result = require_json_schema.createAnnotatedTypeNode({
+			kind: "object",
+			props: new Map(),
+			propsPatterns: [],
+			tags: new Set()
+		}, metadata, {
+			optional: data.optional || undefined,
+			id: data.id
+		});
+		resolved.set(data.id, result);
+	}
+	const type = deserializeTypeDef(data.type, resolved);
+	let ref;
+	if (data.ref) {
+		const deserializedRefTarget = deserializeNode(data.ref.type, resolved);
+		ref = {
+			type: () => deserializedRefTarget,
+			field: data.ref.field
+		};
+	}
+	if (result) {
+		result.type = type;
+		if (ref) result.ref = ref;
+		return result;
+	}
+	return require_json_schema.createAnnotatedTypeNode(type, metadata, {
 		optional: data.optional || undefined,
-		id: data.id || undefined
+		id: data.id || undefined,
+		ref
 	});
-	return result;
 }
-function deserializeTypeDef(t) {
+function deserializeTypeDef(t, resolved) {
 	const tags = "tags" in t ? new Set(t.tags) : new Set();
 	switch (t.kind) {
 		case "": {
@@ -357,10 +406,10 @@ function deserializeTypeDef(t) {
 		}
 		case "object": {
 			const props = new Map();
-			for (const [key, val] of Object.entries(t.props)) props.set(key, deserializeNode(val));
+			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)
+				def: deserializeNode(pp.def, resolved)
 			}));
 			return {
 				kind: "object",
@@ -371,22 +420,26 @@ function deserializeTypeDef(t) {
 		}
 		case "array": return {
 			kind: "array",
-			of: deserializeNode(t.of),
+			of: deserializeNode(t.of, resolved),
 			tags
 		};
 		case "union":
 		case "intersection":
 		case "tuple": return {
 			kind: t.kind,
-			items: t.items.map((item) => deserializeNode(item)),
-			tags
-		};
-		case "$ref": return {
-			kind: "object",
-			props: new Map(),
-			propsPatterns: [],
+			items: t.items.map((item) => deserializeNode(item, resolved)),
 			tags
 		};
+		case "$ref": {
+			const existing = resolved.get(t.id);
+			if (existing) return existing.type;
+			return {
+				kind: "object",
+				props: new Map(),
+				propsPatterns: [],
+				tags
+			};
+		}
 		default: throw new Error(`Unknown serialized type kind "${t.kind}"`);
 	}
 }

package/dist/utils.d.ts

@@ -479,7 +479,7 @@ type AtscriptQueryNode = AtscriptQueryComparison | {
 };
 
 /** Current serialization format version. Bumped on breaking changes to the serialized shape. */
-declare const SERIALIZE_VERSION = 1;
+declare const SERIALIZE_VERSION = 2;
 /** Top-level serialized annotated type. JSON-safe representation of a {@link TAtscriptAnnotatedType}. */
 interface TSerializedAnnotatedType extends TSerializedAnnotatedTypeInner {
     /** Format version for forward compatibility */
@@ -491,6 +491,11 @@ interface TSerializedAnnotatedTypeInner {
     metadata: Record<string, unknown>;
     optional?: boolean;
     id?: string;
+    /** FK reference — present when serialized with `refDepth > 0` */
+    ref?: {
+        type: TSerializedAnnotatedTypeInner;
+        field: string;
+    };
 }
 interface TSerializedTypeFinal {
     kind: '';
@@ -549,6 +554,13 @@ interface TSerializeOptions {
         key: string;
         value: unknown;
     } | undefined | void;
+    /**
+     * How many levels of `.ref` (FK references) to expand during serialization.
+     * - `0` (default): refs are stripped (backward-compatible)
+     * - `1`: immediate refs are serialized, but refs inside referenced types are stripped
+     * - `2+`: deeper expansion
+     */
+    refDepth?: number;
 }
 /**
  * Converts a runtime {@link TAtscriptAnnotatedType} into a plain JSON-safe object.

package/dist/utils.mjs

@@ -218,7 +218,7 @@ else flatUnion.item(existing);
 
 //#endregion
 //#region packages/typescript/src/runtime/serialize.ts
-const SERIALIZE_VERSION = 1;
+const SERIALIZE_VERSION = 2;
 function serializeAnnotatedType(type, options) {
 	const visited = new Set();
 	const result = serializeNode(type, [], options, visited);
@@ -242,6 +242,17 @@ function serializeNode(def, path, options, visited) {
 	};
 	if (def.optional) result.optional = true;
 	if (def.id) result.id = def.id;
+	const refDepth = options?.refDepth ?? 0;
+	if (refDepth > 0 && def.ref) {
+		const refTarget = def.ref.type();
+		if (refTarget) result.ref = {
+			type: serializeNode(refTarget, [], {
+				...options,
+				refDepth: refDepth - 1
+			}, visited),
+			field: def.ref.field
+		};
+	}
 	return result;
 }
 function serializeTypeDef(def, path, options, visited) {
@@ -331,18 +342,56 @@ function serializeMetadata(metadata, path, kind, options) {
 }
 function deserializeAnnotatedType(data) {
 	if (data.$v !== SERIALIZE_VERSION) throw new Error(`Unsupported serialized type version: ${data.$v} (expected ${SERIALIZE_VERSION})`);
-	return deserializeNode(data);
+	const resolved = new Map();
+	return deserializeNode(data, resolved);
 }
-function deserializeNode(data) {
+function deserializeNode(data, resolved) {
+	if (data.type.kind === "$ref") {
+		const refId = data.type.id;
+		return resolved.get(refId) || createAnnotatedTypeNode({
+			kind: "object",
+			props: new Map(),
+			propsPatterns: [],
+			tags: new Set()
+		}, new Map(), { id: refId });
+	}
 	const metadata = new Map(Object.entries(data.metadata));
-	const type = deserializeTypeDef(data.type);
-	const result = createAnnotatedTypeNode(type, metadata, {
+	let result;
+	if (data.id) {
+		const existing = resolved.get(data.id);
+		if (existing) return existing;
+		result = createAnnotatedTypeNode({
+			kind: "object",
+			props: new Map(),
+			propsPatterns: [],
+			tags: new Set()
+		}, metadata, {
+			optional: data.optional || undefined,
+			id: data.id
+		});
+		resolved.set(data.id, result);
+	}
+	const type = deserializeTypeDef(data.type, resolved);
+	let ref;
+	if (data.ref) {
+		const deserializedRefTarget = deserializeNode(data.ref.type, resolved);
+		ref = {
+			type: () => deserializedRefTarget,
+			field: data.ref.field
+		};
+	}
+	if (result) {
+		result.type = type;
+		if (ref) result.ref = ref;
+		return result;
+	}
+	return createAnnotatedTypeNode(type, metadata, {
 		optional: data.optional || undefined,
-		id: data.id || undefined
+		id: data.id || undefined,
+		ref
 	});
-	return result;
 }
-function deserializeTypeDef(t) {
+function deserializeTypeDef(t, resolved) {
 	const tags = "tags" in t ? new Set(t.tags) : new Set();
 	switch (t.kind) {
 		case "": {
@@ -356,10 +405,10 @@ function deserializeTypeDef(t) {
 		}
 		case "object": {
 			const props = new Map();
-			for (const [key, val] of Object.entries(t.props)) props.set(key, deserializeNode(val));
+			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)
+				def: deserializeNode(pp.def, resolved)
 			}));
 			return {
 				kind: "object",
@@ -370,22 +419,26 @@ function deserializeTypeDef(t) {
 		}
 		case "array": return {
 			kind: "array",
-			of: deserializeNode(t.of),
+			of: deserializeNode(t.of, resolved),
 			tags
 		};
 		case "union":
 		case "intersection":
 		case "tuple": return {
 			kind: t.kind,
-			items: t.items.map((item) => deserializeNode(item)),
-			tags
-		};
-		case "$ref": return {
-			kind: "object",
-			props: new Map(),
-			propsPatterns: [],
+			items: t.items.map((item) => deserializeNode(item, resolved)),
 			tags
 		};
+		case "$ref": {
+			const existing = resolved.get(t.id);
+			if (existing) return existing.type;
+			return {
+				kind: "object",
+				props: new Map(),
+				propsPatterns: [],
+				tags
+			};
+		}
 		default: throw new Error(`Unknown serialized type kind "${t.kind}"`);
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atscript/typescript",
-  "version": "0.1.44",
+  "version": "0.1.46",
   "description": "Atscript: typescript-gen support.",
   "keywords": [
     "annotations",
@@ -66,7 +66,7 @@
   },
   "peerDependencies": {
     "@atscript/db": "^0.1.41",
-    "@atscript/core": "^0.1.44"
+    "@atscript/core": "^0.1.46"
   },
   "peerDependenciesMeta": {
     "@atscript/db": {

package/skills/atscript-typescript/utilities.md

@@ -213,6 +213,9 @@ serializeAnnotatedType(User, {
     if (ctx.key.startsWith('mongo.')) return undefined
     return { key: ctx.key, value: ctx.value }
   },
+
+  // Include FK references (0 = strip, 1 = immediate refs, 2+ = deeper)
+  refDepth: 1,
 })
 ```
 
@@ -236,7 +239,7 @@ Throws if the serialized version doesn't match `SERIALIZE_VERSION`. The `id` fie
 
 ### `SERIALIZE_VERSION`
 
-Current serialization format version (currently `1`). Used for forward compatibility:
+Current serialization format version (currently `2`). Used for forward compatibility:
 
 ```ts
 import { SERIALIZE_VERSION } from '@atscript/typescript/utils'