@atscript/typescript 0.1.29 → 0.1.31

package/dist/cli.cjs

@@ -289,8 +289,9 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 			if (isGrp) this.write(")");
 			return this.write("[]");
 		}
+		if ((0, __atscript_core.isPrimitive)(def)) return this.write(renderPrimitiveTypeDef(def.config.type));
 	}
-	renderStructure(struct, asClass) {
+	renderStructure(struct, asClass, interfaceNode) {
 		this.blockln("{}");
 		const patterns = [];
 		const propsDefs = new Set();
@@ -336,6 +337,7 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 			this.writeln("static toJsonSchema: () => any");
 			if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
 			this.writeln("static toExampleData?: () => any");
+			if (interfaceNode && this.hasDbTable(interfaceNode)) this.renderFlat(interfaceNode);
 		}
 		this.pop();
 	}
@@ -344,12 +346,63 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 		const exported = node.token("export")?.text === "export";
 		this.renderJsDoc(node);
 		this.write(exported ? "export declare " : "declare ");
-		this.write(`class ${node.id} `);
-		const struct = node.getDefinition();
-		if (struct?.entity === "structure") this.renderStructure(struct, node.id);
+		if (node.hasExtends) {
+			const firstParent = node.extendsTokens[0].text;
+			this.write(`class ${node.id} extends ${firstParent} `);
+			const resolved = this.doc.resolveInterfaceExtends(node);
+			if (resolved?.entity === "structure") {
+				const firstParentUnwound = this.doc.unwindType(firstParent);
+				let firstParentProps;
+				if (firstParentUnwound?.def) {
+					let fpDef = firstParentUnwound.def;
+					if ((0, __atscript_core.isInterface)(fpDef)) {
+						if (fpDef.hasExtends) {
+							const fpResolved = firstParentUnwound.doc.resolveInterfaceExtends(fpDef);
+							if (fpResolved && (0, __atscript_core.isStructure)(fpResolved)) firstParentProps = fpResolved.props;
+						}
+						if (!firstParentProps) fpDef = fpDef.getDefinition() || fpDef;
+					}
+					if (!firstParentProps && (0, __atscript_core.isStructure)(fpDef)) firstParentProps = fpDef.props;
+				}
+				this.renderStructureFiltered(resolved, node.id, firstParentProps, node);
+			} else this.writeln("{}");
+		} else {
+			this.write(`class ${node.id} `);
+			const struct = node.getDefinition();
+			if (struct?.entity === "structure") this.renderStructure(struct, node.id, node);
 else this.writeln("{}");
+		}
 		this.writeln();
 	}
+	/**
+	* Renders a structure block, optionally filtering out props that exist in a parent.
+	*/ renderStructureFiltered(struct, asClass, filterProps, interfaceNode) {
+		if (!filterProps) return this.renderStructure(struct, asClass, interfaceNode);
+		this.blockln("{}");
+		for (const prop of Array.from(struct.props.values())) {
+			if (filterProps.has(prop.id)) continue;
+			if (prop.token("identifier")?.pattern) continue;
+			const phantomType = this.phantomPropType(prop.getDefinition());
+			if (phantomType) {
+				this.writeln(`// ${prop.id}: ${phantomType}`);
+				continue;
+			}
+			const optional = !!prop.token("optional");
+			this.write(wrapProp(prop.id), optional ? "?" : "", ": ");
+			const renderedDef = this.renderTypeDefString(prop.getDefinition());
+			renderedDef.split("\n").forEach((l) => this.writeln(l));
+		}
+		this.writeln("static __is_atscript_annotated_type: true");
+		this.writeln(`static type: TAtscriptTypeObject<keyof ${asClass}, ${asClass}>`);
+		this.writeln(`static metadata: TMetadataMap<AtscriptMetadata>`);
+		this.writeln(`static validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof ${asClass}>`);
+		if (resolveJsonSchemaMode(this.opts) === false) this.writeln("/** @deprecated JSON Schema support is disabled. Calling this method will throw a runtime error. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add `@emit.jsonSchema` annotation to individual interfaces. */");
+		this.writeln("static toJsonSchema: () => any");
+		if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
+		this.writeln("static toExampleData?: () => any");
+		if (interfaceNode && this.hasDbTable(interfaceNode)) this.renderFlat(interfaceNode);
+		this.pop();
+	}
 	renderType(node) {
 		this.writeln();
 		const exported = node.token("export")?.text === "export";
@@ -403,6 +456,50 @@ else if ((0, __atscript_core.isPrimitive)(realDef)) typeDef = `TAtscriptTypeFina
 		this.writeln("const toExampleData: (() => any) | undefined");
 		this.popln();
 	}
+	/**
+	* Checks whether an interface has the `@db.table` annotation.
+	*
+	* NOTE: Only `@db.table` interfaces get the `__flat` static property.
+	* This is intentionally hardcoded — `__flat` exists solely to improve
+	* type-safety for filter expressions and `$select`/`$sort` operations
+	* in the DB layer. Non-DB interfaces have no use for dot-notation path types.
+	*/ hasDbTable(node) {
+		return !!node.annotations?.some((a) => a.name === "db.table");
+	}
+	/**
+	* Renders the `static __flat` property — a map of all dot-notation paths
+	* to their TypeScript value types.
+	*
+	* This enables type-safe autocomplete for filter keys and `$select`/`$sort`
+	* paths when using `AtscriptDbTable`. The `FlatOf<T>` utility type extracts
+	* this map at the type level.
+	*
+	* Special rendering rules:
+	* - **Intermediate paths** (structures, arrays of structures) → `never`
+	*   (prevents `$eq` comparisons, but allows `$select` and `$exists`)
+	* - **`@db.json` fields** → `string` (stored as serialized JSON in DB,
+	*   not individually queryable)
+	* - **Leaf fields** → their original TypeScript type
+	*/ renderFlat(node) {
+		const flatMap = (0, __atscript_core.flattenInterfaceNode)(this.doc, node);
+		if (flatMap.size === 0) return;
+		this.write("static __flat: ");
+		this.blockln("{}");
+		for (const [path$3, descriptor] of flatMap) {
+			this.write(`"${escapeQuotes(path$3)}"`);
+			if (descriptor.optional) this.write("?");
+			this.write(": ");
+			if (descriptor.intermediate) this.writeln("never");
+else if (descriptor.dbJson) this.writeln("string");
+else {
+				const originalDef = descriptor.propNode?.getDefinition();
+				const defToRender = originalDef && !((0, __atscript_core.isGroup)(descriptor.def) && descriptor.def !== originalDef) ? originalDef : descriptor.def;
+				const renderedDef = this.renderTypeDefString(defToRender);
+				renderedDef.split("\n").forEach((l) => this.writeln(l));
+			}
+		}
+		this.pop();
+	}
 	phantomPropType(def) {
 		if (!def) return undefined;
 		if ((0, __atscript_core.isPrimitive)(def) && def.config.type === "phantom") return def.id;
@@ -1214,7 +1311,11 @@ else {
 				const unwound = this.doc.unwindType(annotateNode.targetName);
 				if (unwound?.def) {
 					let def = this.doc.mergeIntersection(unwound.def);
-					if ((0, __atscript_core.isInterface)(def)) def = def.getDefinition() || def;
+					if ((0, __atscript_core.isInterface)(def)) if (def.hasExtends) {
+						const resolved = unwound.doc.resolveInterfaceExtends(def);
+						if (resolved) def = resolved;
+else def = def.getDefinition() || def;
+					} else def = def.getDefinition() || def;
 					this._adHocAnnotations = this.buildAdHocMap([annotateNode]);
 					this.annotateType(def, node.id);
 					this._adHocAnnotations = null;
@@ -1225,7 +1326,12 @@ else {
 				}
 			}
 		} else {
-			this.annotateType(node.getDefinition(), node.id);
+			let def = node.getDefinition();
+			if ((0, __atscript_core.isInterface)(node) && node.hasExtends) {
+				const resolved = this.doc.resolveInterfaceExtends(node);
+				if (resolved) def = resolved;
+			}
+			this.annotateType(def, node.id);
 			this.indent().defineMetadata(node).unindent();
 			this.writeln();
 		}
@@ -1314,7 +1420,11 @@ else {
 		switch (node.entity) {
 			case "interface":
 			case "type": {
-				const def = node.getDefinition();
+				let def = node.getDefinition();
+				if ((0, __atscript_core.isInterface)(node) && node.hasExtends) {
+					const resolved = this.doc.resolveInterfaceExtends(node);
+					if (resolved) def = resolved;
+				}
 				const handle = this.toAnnotatedHandle(def, true);
 				const typeId = this.typeIds.get(node) ?? (node.__typeId !== null && node.__typeId !== undefined ? node.id : undefined);
 				if (typeId) handle.id(typeId);

package/dist/index.cjs

@@ -287,8 +287,9 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 			if (isGrp) this.write(")");
 			return this.write("[]");
 		}
+		if ((0, __atscript_core.isPrimitive)(def)) return this.write(renderPrimitiveTypeDef(def.config.type));
 	}
-	renderStructure(struct, asClass) {
+	renderStructure(struct, asClass, interfaceNode) {
 		this.blockln("{}");
 		const patterns = [];
 		const propsDefs = new Set();
@@ -334,6 +335,7 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 			this.writeln("static toJsonSchema: () => any");
 			if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
 			this.writeln("static toExampleData?: () => any");
+			if (interfaceNode && this.hasDbTable(interfaceNode)) this.renderFlat(interfaceNode);
 		}
 		this.pop();
 	}
@@ -342,12 +344,63 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 		const exported = node.token("export")?.text === "export";
 		this.renderJsDoc(node);
 		this.write(exported ? "export declare " : "declare ");
-		this.write(`class ${node.id} `);
-		const struct = node.getDefinition();
-		if (struct?.entity === "structure") this.renderStructure(struct, node.id);
+		if (node.hasExtends) {
+			const firstParent = node.extendsTokens[0].text;
+			this.write(`class ${node.id} extends ${firstParent} `);
+			const resolved = this.doc.resolveInterfaceExtends(node);
+			if (resolved?.entity === "structure") {
+				const firstParentUnwound = this.doc.unwindType(firstParent);
+				let firstParentProps;
+				if (firstParentUnwound?.def) {
+					let fpDef = firstParentUnwound.def;
+					if ((0, __atscript_core.isInterface)(fpDef)) {
+						if (fpDef.hasExtends) {
+							const fpResolved = firstParentUnwound.doc.resolveInterfaceExtends(fpDef);
+							if (fpResolved && (0, __atscript_core.isStructure)(fpResolved)) firstParentProps = fpResolved.props;
+						}
+						if (!firstParentProps) fpDef = fpDef.getDefinition() || fpDef;
+					}
+					if (!firstParentProps && (0, __atscript_core.isStructure)(fpDef)) firstParentProps = fpDef.props;
+				}
+				this.renderStructureFiltered(resolved, node.id, firstParentProps, node);
+			} else this.writeln("{}");
+		} else {
+			this.write(`class ${node.id} `);
+			const struct = node.getDefinition();
+			if (struct?.entity === "structure") this.renderStructure(struct, node.id, node);
 else this.writeln("{}");
+		}
 		this.writeln();
 	}
+	/**
+	* Renders a structure block, optionally filtering out props that exist in a parent.
+	*/ renderStructureFiltered(struct, asClass, filterProps, interfaceNode) {
+		if (!filterProps) return this.renderStructure(struct, asClass, interfaceNode);
+		this.blockln("{}");
+		for (const prop of Array.from(struct.props.values())) {
+			if (filterProps.has(prop.id)) continue;
+			if (prop.token("identifier")?.pattern) continue;
+			const phantomType = this.phantomPropType(prop.getDefinition());
+			if (phantomType) {
+				this.writeln(`// ${prop.id}: ${phantomType}`);
+				continue;
+			}
+			const optional = !!prop.token("optional");
+			this.write(wrapProp(prop.id), optional ? "?" : "", ": ");
+			const renderedDef = this.renderTypeDefString(prop.getDefinition());
+			renderedDef.split("\n").forEach((l) => this.writeln(l));
+		}
+		this.writeln("static __is_atscript_annotated_type: true");
+		this.writeln(`static type: TAtscriptTypeObject<keyof ${asClass}, ${asClass}>`);
+		this.writeln(`static metadata: TMetadataMap<AtscriptMetadata>`);
+		this.writeln(`static validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof ${asClass}>`);
+		if (resolveJsonSchemaMode(this.opts) === false) this.writeln("/** @deprecated JSON Schema support is disabled. Calling this method will throw a runtime error. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add `@emit.jsonSchema` annotation to individual interfaces. */");
+		this.writeln("static toJsonSchema: () => any");
+		if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
+		this.writeln("static toExampleData?: () => any");
+		if (interfaceNode && this.hasDbTable(interfaceNode)) this.renderFlat(interfaceNode);
+		this.pop();
+	}
 	renderType(node) {
 		this.writeln();
 		const exported = node.token("export")?.text === "export";
@@ -401,6 +454,50 @@ else if ((0, __atscript_core.isPrimitive)(realDef)) typeDef = `TAtscriptTypeFina
 		this.writeln("const toExampleData: (() => any) | undefined");
 		this.popln();
 	}
+	/**
+	* Checks whether an interface has the `@db.table` annotation.
+	*
+	* NOTE: Only `@db.table` interfaces get the `__flat` static property.
+	* This is intentionally hardcoded — `__flat` exists solely to improve
+	* type-safety for filter expressions and `$select`/`$sort` operations
+	* in the DB layer. Non-DB interfaces have no use for dot-notation path types.
+	*/ hasDbTable(node) {
+		return !!node.annotations?.some((a) => a.name === "db.table");
+	}
+	/**
+	* Renders the `static __flat` property — a map of all dot-notation paths
+	* to their TypeScript value types.
+	*
+	* This enables type-safe autocomplete for filter keys and `$select`/`$sort`
+	* paths when using `AtscriptDbTable`. The `FlatOf<T>` utility type extracts
+	* this map at the type level.
+	*
+	* Special rendering rules:
+	* - **Intermediate paths** (structures, arrays of structures) → `never`
+	*   (prevents `$eq` comparisons, but allows `$select` and `$exists`)
+	* - **`@db.json` fields** → `string` (stored as serialized JSON in DB,
+	*   not individually queryable)
+	* - **Leaf fields** → their original TypeScript type
+	*/ renderFlat(node) {
+		const flatMap = (0, __atscript_core.flattenInterfaceNode)(this.doc, node);
+		if (flatMap.size === 0) return;
+		this.write("static __flat: ");
+		this.blockln("{}");
+		for (const [path$2, descriptor] of flatMap) {
+			this.write(`"${escapeQuotes(path$2)}"`);
+			if (descriptor.optional) this.write("?");
+			this.write(": ");
+			if (descriptor.intermediate) this.writeln("never");
+else if (descriptor.dbJson) this.writeln("string");
+else {
+				const originalDef = descriptor.propNode?.getDefinition();
+				const defToRender = originalDef && !((0, __atscript_core.isGroup)(descriptor.def) && descriptor.def !== originalDef) ? originalDef : descriptor.def;
+				const renderedDef = this.renderTypeDefString(defToRender);
+				renderedDef.split("\n").forEach((l) => this.writeln(l));
+			}
+		}
+		this.pop();
+	}
 	phantomPropType(def) {
 		if (!def) return undefined;
 		if ((0, __atscript_core.isPrimitive)(def) && def.config.type === "phantom") return def.id;
@@ -1212,7 +1309,11 @@ else {
 				const unwound = this.doc.unwindType(annotateNode.targetName);
 				if (unwound?.def) {
 					let def = this.doc.mergeIntersection(unwound.def);
-					if ((0, __atscript_core.isInterface)(def)) def = def.getDefinition() || def;
+					if ((0, __atscript_core.isInterface)(def)) if (def.hasExtends) {
+						const resolved = unwound.doc.resolveInterfaceExtends(def);
+						if (resolved) def = resolved;
+else def = def.getDefinition() || def;
+					} else def = def.getDefinition() || def;
 					this._adHocAnnotations = this.buildAdHocMap([annotateNode]);
 					this.annotateType(def, node.id);
 					this._adHocAnnotations = null;
@@ -1223,7 +1324,12 @@ else {
 				}
 			}
 		} else {
-			this.annotateType(node.getDefinition(), node.id);
+			let def = node.getDefinition();
+			if ((0, __atscript_core.isInterface)(node) && node.hasExtends) {
+				const resolved = this.doc.resolveInterfaceExtends(node);
+				if (resolved) def = resolved;
+			}
+			this.annotateType(def, node.id);
 			this.indent().defineMetadata(node).unindent();
 			this.writeln();
 		}
@@ -1312,7 +1418,11 @@ else {
 		switch (node.entity) {
 			case "interface":
 			case "type": {
-				const def = node.getDefinition();
+				let def = node.getDefinition();
+				if ((0, __atscript_core.isInterface)(node) && node.hasExtends) {
+					const resolved = this.doc.resolveInterfaceExtends(node);
+					if (resolved) def = resolved;
+				}
 				const handle = this.toAnnotatedHandle(def, true);
 				const typeId = this.typeIds.get(node) ?? (node.__typeId !== null && node.__typeId !== undefined ? node.id : undefined);
 				if (typeId) handle.id(typeId);

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import path from "path";
-import { DEFAULT_FORMAT, isArray, isConst, isGroup, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
+import { DEFAULT_FORMAT, flattenInterfaceNode, isArray, isConst, isGroup, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
 
 //#region packages/typescript/src/codegen/code-printer.ts
 function _define_property$4(obj, key, value) {
@@ -262,8 +262,9 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 			if (isGrp) this.write(")");
 			return this.write("[]");
 		}
+		if (isPrimitive(def)) return this.write(renderPrimitiveTypeDef(def.config.type));
 	}
-	renderStructure(struct, asClass) {
+	renderStructure(struct, asClass, interfaceNode) {
 		this.blockln("{}");
 		const patterns = [];
 		const propsDefs = new Set();
@@ -309,6 +310,7 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 			this.writeln("static toJsonSchema: () => any");
 			if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
 			this.writeln("static toExampleData?: () => any");
+			if (interfaceNode && this.hasDbTable(interfaceNode)) this.renderFlat(interfaceNode);
 		}
 		this.pop();
 	}
@@ -317,12 +319,63 @@ var TypeRenderer = class TypeRenderer extends BaseRenderer {
 		const exported = node.token("export")?.text === "export";
 		this.renderJsDoc(node);
 		this.write(exported ? "export declare " : "declare ");
-		this.write(`class ${node.id} `);
-		const struct = node.getDefinition();
-		if (struct?.entity === "structure") this.renderStructure(struct, node.id);
+		if (node.hasExtends) {
+			const firstParent = node.extendsTokens[0].text;
+			this.write(`class ${node.id} extends ${firstParent} `);
+			const resolved = this.doc.resolveInterfaceExtends(node);
+			if (resolved?.entity === "structure") {
+				const firstParentUnwound = this.doc.unwindType(firstParent);
+				let firstParentProps;
+				if (firstParentUnwound?.def) {
+					let fpDef = firstParentUnwound.def;
+					if (isInterface(fpDef)) {
+						if (fpDef.hasExtends) {
+							const fpResolved = firstParentUnwound.doc.resolveInterfaceExtends(fpDef);
+							if (fpResolved && isStructure(fpResolved)) firstParentProps = fpResolved.props;
+						}
+						if (!firstParentProps) fpDef = fpDef.getDefinition() || fpDef;
+					}
+					if (!firstParentProps && isStructure(fpDef)) firstParentProps = fpDef.props;
+				}
+				this.renderStructureFiltered(resolved, node.id, firstParentProps, node);
+			} else this.writeln("{}");
+		} else {
+			this.write(`class ${node.id} `);
+			const struct = node.getDefinition();
+			if (struct?.entity === "structure") this.renderStructure(struct, node.id, node);
 else this.writeln("{}");
+		}
 		this.writeln();
 	}
+	/**
+	* Renders a structure block, optionally filtering out props that exist in a parent.
+	*/ renderStructureFiltered(struct, asClass, filterProps, interfaceNode) {
+		if (!filterProps) return this.renderStructure(struct, asClass, interfaceNode);
+		this.blockln("{}");
+		for (const prop of Array.from(struct.props.values())) {
+			if (filterProps.has(prop.id)) continue;
+			if (prop.token("identifier")?.pattern) continue;
+			const phantomType = this.phantomPropType(prop.getDefinition());
+			if (phantomType) {
+				this.writeln(`// ${prop.id}: ${phantomType}`);
+				continue;
+			}
+			const optional = !!prop.token("optional");
+			this.write(wrapProp(prop.id), optional ? "?" : "", ": ");
+			const renderedDef = this.renderTypeDefString(prop.getDefinition());
+			renderedDef.split("\n").forEach((l) => this.writeln(l));
+		}
+		this.writeln("static __is_atscript_annotated_type: true");
+		this.writeln(`static type: TAtscriptTypeObject<keyof ${asClass}, ${asClass}>`);
+		this.writeln(`static metadata: TMetadataMap<AtscriptMetadata>`);
+		this.writeln(`static validator: (opts?: Partial<TValidatorOptions>) => Validator<typeof ${asClass}>`);
+		if (resolveJsonSchemaMode(this.opts) === false) this.writeln("/** @deprecated JSON Schema support is disabled. Calling this method will throw a runtime error. To enable, set `jsonSchema: 'lazy'` or `jsonSchema: 'bundle'` in tsPlugin options, or add `@emit.jsonSchema` annotation to individual interfaces. */");
+		this.writeln("static toJsonSchema: () => any");
+		if (!this.opts?.exampleData) this.writeln("/** @deprecated Example Data support is disabled. To enable, set `exampleData: true` in tsPlugin options. */");
+		this.writeln("static toExampleData?: () => any");
+		if (interfaceNode && this.hasDbTable(interfaceNode)) this.renderFlat(interfaceNode);
+		this.pop();
+	}
 	renderType(node) {
 		this.writeln();
 		const exported = node.token("export")?.text === "export";
@@ -376,6 +429,50 @@ else if (isPrimitive(realDef)) typeDef = `TAtscriptTypeFinal<${name}>`;
 		this.writeln("const toExampleData: (() => any) | undefined");
 		this.popln();
 	}
+	/**
+	* Checks whether an interface has the `@db.table` annotation.
+	*
+	* NOTE: Only `@db.table` interfaces get the `__flat` static property.
+	* This is intentionally hardcoded — `__flat` exists solely to improve
+	* type-safety for filter expressions and `$select`/`$sort` operations
+	* in the DB layer. Non-DB interfaces have no use for dot-notation path types.
+	*/ hasDbTable(node) {
+		return !!node.annotations?.some((a) => a.name === "db.table");
+	}
+	/**
+	* Renders the `static __flat` property — a map of all dot-notation paths
+	* to their TypeScript value types.
+	*
+	* This enables type-safe autocomplete for filter keys and `$select`/`$sort`
+	* paths when using `AtscriptDbTable`. The `FlatOf<T>` utility type extracts
+	* this map at the type level.
+	*
+	* Special rendering rules:
+	* - **Intermediate paths** (structures, arrays of structures) → `never`
+	*   (prevents `$eq` comparisons, but allows `$select` and `$exists`)
+	* - **`@db.json` fields** → `string` (stored as serialized JSON in DB,
+	*   not individually queryable)
+	* - **Leaf fields** → their original TypeScript type
+	*/ renderFlat(node) {
+		const flatMap = flattenInterfaceNode(this.doc, node);
+		if (flatMap.size === 0) return;
+		this.write("static __flat: ");
+		this.blockln("{}");
+		for (const [path$1, descriptor] of flatMap) {
+			this.write(`"${escapeQuotes(path$1)}"`);
+			if (descriptor.optional) this.write("?");
+			this.write(": ");
+			if (descriptor.intermediate) this.writeln("never");
+else if (descriptor.dbJson) this.writeln("string");
+else {
+				const originalDef = descriptor.propNode?.getDefinition();
+				const defToRender = originalDef && !(isGroup(descriptor.def) && descriptor.def !== originalDef) ? originalDef : descriptor.def;
+				const renderedDef = this.renderTypeDefString(defToRender);
+				renderedDef.split("\n").forEach((l) => this.writeln(l));
+			}
+		}
+		this.pop();
+	}
 	phantomPropType(def) {
 		if (!def) return undefined;
 		if (isPrimitive(def) && def.config.type === "phantom") return def.id;
@@ -1187,7 +1284,11 @@ else {
 				const unwound = this.doc.unwindType(annotateNode.targetName);
 				if (unwound?.def) {
 					let def = this.doc.mergeIntersection(unwound.def);
-					if (isInterface(def)) def = def.getDefinition() || def;
+					if (isInterface(def)) if (def.hasExtends) {
+						const resolved = unwound.doc.resolveInterfaceExtends(def);
+						if (resolved) def = resolved;
+else def = def.getDefinition() || def;
+					} else def = def.getDefinition() || def;
 					this._adHocAnnotations = this.buildAdHocMap([annotateNode]);
 					this.annotateType(def, node.id);
 					this._adHocAnnotations = null;
@@ -1198,7 +1299,12 @@ else {
 				}
 			}
 		} else {
-			this.annotateType(node.getDefinition(), node.id);
+			let def = node.getDefinition();
+			if (isInterface(node) && node.hasExtends) {
+				const resolved = this.doc.resolveInterfaceExtends(node);
+				if (resolved) def = resolved;
+			}
+			this.annotateType(def, node.id);
 			this.indent().defineMetadata(node).unindent();
 			this.writeln();
 		}
@@ -1287,7 +1393,11 @@ else {
 		switch (node.entity) {
 			case "interface":
 			case "type": {
-				const def = node.getDefinition();
+				let def = node.getDefinition();
+				if (isInterface(node) && node.hasExtends) {
+					const resolved = this.doc.resolveInterfaceExtends(node);
+					if (resolved) def = resolved;
+				}
 				const handle = this.toAnnotatedHandle(def, true);
 				const typeId = this.typeIds.get(node) ?? (node.__typeId !== null && node.__typeId !== undefined ? node.id : undefined);
 				if (typeId) handle.id(typeId);

package/dist/utils.d.ts

@@ -48,7 +48,7 @@ interface TValidatorPluginContext {
  * @typeParam T - The annotated type definition.
  * @typeParam DataType - The TypeScript type that `validate` narrows to (auto-inferred).
  */
-declare class Validator<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>> {
+declare class Validator<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType$1<T>> {
     protected readonly def: T;
     protected opts: TValidatorOptions;
     constructor(def: T, opts?: Partial<TValidatorOptions>);
@@ -159,7 +159,7 @@ type InferDataType<T> = T extends {
  * type Data = TAtscriptDataType<typeof MyInterface>
  * ```
  */
-type TAtscriptDataType<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType> = T extends {
+type TAtscriptDataType$1<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType> = T extends {
     type: {
         __dataType?: infer D;
     };
@@ -535,5 +535,16 @@ 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 : TAtscriptDataType<T>;
+
 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, TAnnotatedTypeHandle, TAtscriptAnnotatedType, TAtscriptAnnotatedTypeConstructor, TAtscriptDataType$1 as TAtscriptDataType, TAtscriptTypeArray, TAtscriptTypeComplex, TAtscriptTypeDef, TAtscriptTypeFinal, TAtscriptTypeObject, TCreateDataOptions, TFlattenOptions, TJsonSchema, TMetadataMap, TProcessAnnotationContext, TSerializeOptions, TSerializedAnnotatedType, TSerializedAnnotatedTypeInner, TSerializedTypeArray, TSerializedTypeComplex, TSerializedTypeDef, TSerializedTypeFinal, TSerializedTypeObject, TValidatorOptions, TValidatorPlugin, TValidatorPluginContext, TValueResolver };

package/package.json

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