@atscript/db 0.1.135 → 0.1.137

package/dist/plugin.cjs

@@ -32,8 +32,10 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	value: mod,
 	enumerable: true
 }) : target, mod));
+//#endregion
+const require_aggregate_fns = require("./aggregate-fns-CGBv3E8S.cjs");
 require("./consts-BzRfCcH2.cjs");
-const require_validation_utils = require("./validation-utils-B7SXPkm7.cjs");
+const require_validation_utils = require("./validation-utils-Dg0hW6dn.cjs");
 let node_path = require("node:path");
 node_path = __toESM(node_path, 1);
 let node_url = require("node:url");
@@ -130,67 +132,98 @@ async function generateModelManifest(options, output, format, repo) {
 }
 //#endregion
 //#region src/plugin/annotations/agg.ts
-const dbAggAnnotations = { agg: {
-	sum: new _atscript_core.AnnotationSpec({
-		description: "Declares a view field as SUM of a source column.",
-		nodeType: ["prop"],
-		passedWhenReferred: false,
-		argument: {
-			name: "field",
-			type: "string",
-			description: "Source column name to sum."
-		},
-		validate(token, _args, doc) {
-			return require_validation_utils.validateFieldBaseType(token, doc, "@db.agg.sum", ["number", "decimal"]);
-		}
-	}),
-	avg: new _atscript_core.AnnotationSpec({
-		description: "Declares a view field as AVG of a source column.",
-		nodeType: ["prop"],
-		passedWhenReferred: false,
-		argument: {
-			name: "field",
-			type: "string",
-			description: "Source column name to average."
-		},
-		validate(token, _args, doc) {
-			return require_validation_utils.validateFieldBaseType(token, doc, "@db.agg.avg", ["number", "decimal"]);
-		}
-	}),
-	count: new _atscript_core.AnnotationSpec({
-		description: "Declares a view field as COUNT. Without argument: COUNT(*). With field name argument: COUNT(field) (non-null count).",
-		nodeType: ["prop"],
-		passedWhenReferred: false,
-		argument: {
-			name: "field",
-			type: "string",
-			optional: true,
-			description: "Source column name to count non-null values. Omit for COUNT(*)."
-		},
-		validate(token, _args, doc) {
-			return require_validation_utils.validateFieldBaseType(token, doc, "@db.agg.count", ["number"]);
-		}
-	}),
-	min: new _atscript_core.AnnotationSpec({
-		description: "Declares a view field as MIN of a source column.",
-		nodeType: ["prop"],
-		passedWhenReferred: false,
-		argument: {
-			name: "field",
-			type: "string",
-			description: "Source column name."
-		}
-	}),
-	max: new _atscript_core.AnnotationSpec({
-		description: "Declares a view field as MAX of a source column.",
+/**
+* A conditional aggregate that is NULL when no row matches (so its field
+* must be optional): every NULL-when-empty function but `sum`, whose
+* conditional form is `COALESCE(…, 0)`.
+*/
+function conditionalIsNullable(name) {
+	return name !== "sum" && require_aggregate_fns.NULL_WHEN_EMPTY_AGGREGATE_FNS.has(name);
+}
+/** The optional 2nd argument every `@db.agg.*` takes. */
+const CONDITION_ARG = {
+	name: "condition",
+	type: "query",
+	optional: true,
+	description: "Row predicate of a conditional aggregate: only rows where it holds are aggregated (SQL `FN(CASE WHEN … THEN field END)`). May reference the entry table and every join; unqualified fields resolve to the entry table."
+};
+/**
+* The rules every `@db.agg.*` shares: `'*'` is `count`'s only, and a
+* condition (2nd argument) must stay within the view's tables (entry + every
+* join, like `@db.view.filter`) and — for the aggregates that are NULL when
+* no row matches (avg / min / max) — sit on an optional field.
+*/
+function validateAggArgs(name, token, args, doc) {
+	const errors = [];
+	const annotation = `@db.agg.${name}`;
+	if (args[0]?.text === "*" && name !== "count") errors.push({
+		message: `${annotation} needs a field — only @db.agg.count accepts '*'`,
+		severity: 1,
+		range: args[0].range
+	});
+	const condition = args[1];
+	if (!condition?.queryNode) return errors;
+	const owner = require_validation_utils.getDbTableOwner(token);
+	const entryTypeName = owner ? require_validation_utils.getAnnotationAlias(owner, "db.view.for") : void 0;
+	if (!owner || !entryTypeName) {
+		errors.push({
+			message: `A conditional ${annotation} requires @db.view.for on the view`,
+			severity: 1,
+			range: condition.range
+		});
+		return errors;
+	}
+	errors.push(...require_validation_utils.validateQueryScope(condition, require_validation_utils.viewScopeTypes(owner), entryTypeName, doc));
+	const prop = token.parentNode;
+	if (conditionalIsNullable(name) && prop && !prop.has("optional")) {
+		const field = prop.id ?? "field";
+		errors.push({
+			message: `Field "${field}" has a conditional ${annotation} and must be optional (${field}?: …) — it is NULL when no row matches`,
+			severity: 1,
+			range: token.range
+		});
+	}
+	return errors;
+}
+const CONDITIONAL = " An optional 2nd argument (a query) makes it conditional: only rows where it holds are aggregated.";
+/** What a conditional `name` yields when no row matches (from `NULL_WHEN_EMPTY_AGGREGATE_FNS`). */
+function conditionalNote(name) {
+	if (!require_aggregate_fns.NULL_WHEN_EMPTY_AGGREGATE_FNS.has(name)) return "";
+	const fn = name.toUpperCase();
+	return conditionalIsNullable(name) ? ` A conditional ${fn} is NULL when no row matches, so its field must be optional.` : ` A conditional ${fn} is 0 (not NULL) when no row matches.`;
+}
+/**
+* One `@db.agg.<name>` spec: `[field, condition?]` (field optional for count
+* only). The description gets the conditional-form sentences appended.
+*/
+function aggSpec(name, description, field, types, extra = "") {
+	return new _atscript_core.AnnotationSpec({
+		description: description + CONDITIONAL + conditionalNote(name) + extra,
 		nodeType: ["prop"],
 		passedWhenReferred: false,
-		argument: {
+		argument: [{
 			name: "field",
 			type: "string",
-			description: "Source column name."
+			optional: field.optional,
+			description: field.description
+		}, CONDITION_ARG],
+		validate(token, args, doc) {
+			const errors = validateAggArgs(name, token, args, doc);
+			if (types) errors.push(...require_validation_utils.validateFieldBaseType(token, doc, `@db.agg.${name}`, types));
+			return errors;
 		}
-	})
+	});
+}
+const dbAggAnnotations = { agg: {
+	sum: aggSpec("sum", "Declares a view field as SUM of a source column.", { description: "Source column name to sum." }, ["number", "decimal"]),
+	avg: aggSpec("avg", "Declares a view field as AVG of a source column.", { description: "Source column name to average." }, ["number", "decimal"]),
+	count: aggSpec("count", "Declares a view field as COUNT. Without argument (or with `'*'`): COUNT(*). With field name argument: COUNT(field) (non-null count).", {
+		optional: true,
+		description: "Source column name to count non-null values. Omit (or `'*'`) for COUNT(*)."
+	}, ["number"], " A conditional COUNT(*) is spelled `@db.agg.count '*', <query>`."),
+	countDistinct: aggSpec("countDistinct", "Declares a view field as COUNT(DISTINCT field): the number of distinct non-null values of a source column.", { description: "Source column name whose distinct non-null values are counted." }, ["number"]),
+	min: aggSpec("min", "Declares a view field as MIN of a source column.", { description: "Source column name." }),
+	max: aggSpec("max", "Declares a view field as MAX of a source column.", { description: "Source column name." })
 } };
 //#endregion
 //#region src/plugin/annotations/amount.ts
@@ -280,7 +313,7 @@ const dbColumnAnnotations = {
 	}) },
 	column: {
 		$self: new _atscript_core.AnnotationSpec({
-			description: "Overrides the physical column name in the database. For nested (flattened) fields, the parent prefix is still prepended automatically.\n\n**Example:**\n```atscript\n@db.column \"first_name\"\nfirstName: string\n// → physical column: first_name\n\n// Nested:\naddress: {\n  @db.column \"zip_code\"\n  zip: string\n}\n// → physical column: address__zip_code\n```\n",
+			description: "Overrides the physical column name in the database. For nested (flattened) fields, the parent prefix is still prepended automatically. Document storage (MongoDB) renames top-level fields only — a nested field keeps its name there.\n\n**Example:**\n```atscript\n@db.column \"first_name\"\nfirstName: string\n// → physical column: first_name\n\n// Nested:\naddress: {\n  @db.column \"zip_code\"\n  zip: string\n}\n// → physical column: address__zip_code\n```\n",
 			nodeType: ["prop"],
 			passedWhenReferred: false,
 			argument: {
@@ -290,7 +323,7 @@ const dbColumnAnnotations = {
 			}
 		}),
 		renamed: new _atscript_core.AnnotationSpec({
-			description: "Specifies the previous local field name for column rename migration. The sync engine generates ALTER TABLE RENAME COLUMN instead of drop+add.\n\n**Example:**\n```atscript\n@db.column.renamed \"zip\"\npostalCode: string\n// Renames address__zip → address__postalCode\n```\n",
+			description: "Specifies the previous local field name for column rename migration. The sync engine generates ALTER TABLE RENAME COLUMN instead of drop+add (on document storage, top-level fields only).\n\n**Example:**\n```atscript\n@db.column.renamed \"zip\"\npostalCode: string\n// Renames address__zip → address__postalCode\n```\n",
 			nodeType: ["prop"],
 			passedWhenReferred: false,
 			argument: {
@@ -1296,6 +1329,86 @@ const dbUnitAnnotations = { unit: {
 	})
 } };
 //#endregion
+//#region src/shared/view-validation.ts
+/** `@db.agg.*` annotations that are never NULL (the counts: 0 over no value). */
+const NULL_SAFE_AGG_ANNOTATIONS = require_aggregate_fns.SUPPORTED_AGGREGATE_FNS.filter((fn) => !require_aggregate_fns.NULL_WHEN_EMPTY_AGGREGATE_FNS.has(fn)).map((fn) => `db.agg.${fn}`);
+/** Primitive leaf types a JSON-stored path may end at. */
+const JSON_LEAF_TYPES = new Set([
+	"string",
+	"number",
+	"boolean"
+]);
+/** Props of a view interface (its own structure; views don't use `extends`). */
+function viewProps(owner) {
+	if ((0, _atscript_core.isInterface)(owner)) return owner.props;
+	const def = owner.getDefinition();
+	return def && (0, _atscript_core.isStructure)(def) ? def.props : void 0;
+}
+/**
+* VW8: a chain ref that passes through a `@db.json` or array node reads a
+* JSON leaf, which views can only extract as a string / number / boolean.
+* Intermediate nodes that `unwindType` can't reach are skipped (sync-time
+* resolution reports them).
+*/
+function validateJsonChain(fieldName, ref, doc, range) {
+	const typeName = ref.id;
+	const chain = ref.chain.map((t) => t.text);
+	if (!typeName || chain.length < 2) return [];
+	let throughJson = false;
+	for (let i = 1; i < chain.length; i++) {
+		const step = doc.unwindType(typeName, chain.slice(0, i));
+		if (!step) return [];
+		const stepNode = step.node;
+		if (stepNode && (0, _atscript_core.isProp)(stepNode) && stepNode.countAnnotations("db.json") > 0 || (0, _atscript_core.isArray)(step.def)) {
+			throughJson = true;
+			break;
+		}
+	}
+	if (!throughJson) return [];
+	const leaf = doc.unwindType(typeName, chain)?.def;
+	const leafType = require_validation_utils.primitiveBaseType(leaf);
+	if (leafType !== void 0 && JSON_LEAF_TYPES.has(leafType)) return [];
+	return [{
+		message: `Field "${fieldName}" reads "${typeName}.${chain.join(".")}" inside a JSON-stored field — it must end at a string, number or boolean leaf`,
+		severity: 1,
+		range
+	}];
+}
+/**
+* Whole-view checks, run once per `@db.view.for` interface:
+*
+* - VW7 — a field reading from a left-joined table must be optional (the
+*   join yields NULL for unmatched rows); `@db.agg.count` / `countDistinct`
+*   fields are exempt (they count 0, never NULL).
+* - VW8 — a chain ref through a `@db.json` or array node must end at a
+*   primitive string / number / boolean leaf.
+* @since 0.1.136
+*/
+function validateViewInterface(owner, doc) {
+	const errors = [];
+	const props = viewProps(owner);
+	if (!props) return errors;
+	const leftJoined = /* @__PURE__ */ new Set();
+	for (const join of require_validation_utils.viewJoins(owner)) {
+		const target = join.args[0]?.text;
+		if (target && join.args[2]?.text === "left") leftJoined.add(target);
+	}
+	for (const [fieldName, prop] of props) {
+		const def = prop.getDefinition();
+		if (!def || !(0, _atscript_core.isRef)(def)) continue;
+		const ref = def;
+		const range = (prop.token("identifier") ?? ref.token("identifier"))?.range;
+		if (!range) continue;
+		if (ref.id && leftJoined.has(ref.id) && !prop.has("optional") && !NULL_SAFE_AGG_ANNOTATIONS.some((name) => prop.countAnnotations(name) > 0)) errors.push({
+			message: `Field "${fieldName}" reads from left-joined "${ref.id}" and must be optional (${fieldName}?: …)`,
+			severity: 1,
+			range
+		});
+		errors.push(...validateJsonChain(fieldName, ref, doc, range));
+	}
+	return errors;
+}
+//#endregion
 //#region src/plugin/annotations/view.ts
 const dbViewAnnotations = { view: {
 	$self: new _atscript_core.AnnotationSpec({
@@ -1327,29 +1440,41 @@ const dbViewAnnotations = { view: {
 		},
 		validate(token, args, doc) {
 			const errors = [];
-			if (token.parentNode.countAnnotations("db.table") > 0) errors.push({
+			const owner = token.parentNode;
+			if (owner.countAnnotations("db.table") > 0) errors.push({
 				message: "An interface cannot be both a @db.table and a @db.view",
 				severity: 1,
 				range: token.range
 			});
 			if (args[0]) errors.push(...require_validation_utils.validateRefArgument(args[0], doc, { requireDbTable: true }));
+			errors.push(...validateViewInterface(owner, doc));
 			return errors;
 		}
 	}),
 	joins: new _atscript_core.AnnotationSpec({
-		description: "Declares an explicit join for a view. Use when no `@db.rel.*` path exists between the entry table and the target.\n\n**Example:**\n```atscript\n@db.view.for Order\n@db.view.joins Warehouse, `Warehouse.regionId = Order.regionId`\nexport interface OrderWarehouse { ... }\n```\n",
+		description: "Declares an explicit join for a view. Joins are INNER by default — pass `'left'` as the third argument to keep entry rows without a match (fields read from a left-joined table must be optional). A join condition may reference the entry table and joins declared before it (chained joins); a table can be joined once (no aliases / self-joins).\n\n**Example:**\n```atscript\n@db.view.for Order\n@db.view.joins Customer, `Customer.id = Order.customerId`\n@db.view.joins Region, `Region.id = Customer.regionId`, 'left'\nexport interface OrderRegion { ... }\n```\n",
 		nodeType: ["interface"],
 		multiple: true,
 		mergeStrategy: "append",
-		argument: [{
-			name: "target",
-			type: "ref",
-			description: "The table type to join (must have @db.table)."
-		}, {
-			name: "condition",
-			type: "query",
-			description: "Join condition expression."
-		}],
+		argument: [
+			{
+				name: "target",
+				type: "ref",
+				description: "The table type to join (must have @db.table)."
+			},
+			{
+				name: "condition",
+				type: "query",
+				description: "Join condition expression."
+			},
+			{
+				name: "kind",
+				type: "string",
+				optional: true,
+				description: "`\"inner\"` (default) drops entry rows without a match; `\"left\"` keeps them with NULLs.",
+				values: ["inner", "left"]
+			}
+		],
 		validate(token, args, doc) {
 			const errors = [];
 			const owner = token.parentNode;
@@ -1371,9 +1496,29 @@ const dbViewAnnotations = { view: {
 				});
 				return errors;
 			}
+			const allJoins = require_validation_utils.viewJoins(owner);
+			const position = allJoins.findIndex((a) => a.token === token);
+			const earlier = require_validation_utils.joinTargets(position === -1 ? [] : allJoins.slice(0, position));
+			if (args[0]) {
+				const target = args[0].text;
+				if (target === entryTypeName) errors.push({
+					message: `@db.view.joins cannot join the entry table '${target}' — no join aliases / self-joins yet`,
+					severity: 1,
+					range: args[0].range
+				});
+				else if (earlier.includes(target)) errors.push({
+					message: `'${target}' is joined more than once — no join aliases / self-joins yet`,
+					severity: 1,
+					range: args[0].range
+				});
+			}
 			if (args[1]?.queryNode && args[0]) {
 				const joinTargetName = args[0].text;
-				errors.push(...require_validation_utils.validateQueryScope(args[1], [joinTargetName, entryTypeName], entryTypeName, doc));
+				errors.push(...require_validation_utils.validateQueryScope(args[1], [
+					joinTargetName,
+					entryTypeName,
+					...earlier
+				], entryTypeName, doc, "a join may reference the entry table and joins declared before it"));
 			}
 			return errors;
 		}
@@ -1407,12 +1552,7 @@ const dbViewAnnotations = { view: {
 				});
 				return errors;
 			}
-			const allowedTypes = [entryTypeName];
-			const joinsAnnotations = owner.annotations?.filter((a) => a.name === "db.view.joins");
-			if (joinsAnnotations) {
-				for (const join of joinsAnnotations) if (join.args[0]) allowedTypes.push(join.args[0].text);
-			}
-			errors.push(...require_validation_utils.validateQueryScope(args[0], allowedTypes, entryTypeName, doc));
+			errors.push(...require_validation_utils.validateQueryScope(args[0], require_validation_utils.viewScopeTypes(owner), entryTypeName, doc));
 			return errors;
 		}
 	}),