@atscript/db 0.1.135 → 0.1.137

package/dist/plugin.mjs

@@ -1,8 +1,9 @@
+import { i as SUPPORTED_AGGREGATE_FNS, r as NULL_WHEN_EMPTY_AGGREGATE_FNS } from "./aggregate-fns-CfsveE1w.mjs";
 import "./consts-C_-5_pFq.mjs";
-import { a as getAnnotationAlias, c as getParentStruct, d as validateExclusiveWith, f as validateFieldBaseType, i as validateRefArgument, l as getParentTypeName, n as hasAnyViewAnnotation, o as getDbTableOwner, p as validateSiblingStringField, r as validateQueryScope, s as getNavTargetTypeName, t as findFKFieldsPointingTo, u as refActionAnnotation } from "./validation-utils-MWOP1Ts4.mjs";
+import { _ as validateSiblingStringField, a as validateRefArgument, c as getAnnotationAlias, d as getParentStruct, f as getParentTypeName, g as validateFieldBaseType, h as validateExclusiveWith, i as validateQueryScope, l as getDbTableOwner, m as refActionAnnotation, n as hasAnyViewAnnotation, o as viewJoins, p as primitiveBaseType, r as joinTargets, s as viewScopeTypes, t as findFKFieldsPointingTo, u as getNavTargetTypeName } from "./validation-utils-B4h-GW4d.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { AnnotationSpec, DEFAULT_FORMAT, isArray, isInterface, isPrimitive, isRef, isStructure } from "@atscript/core";
+import { AnnotationSpec, DEFAULT_FORMAT, isArray, isInterface, isPrimitive, isProp, isRef, isStructure } from "@atscript/core";
 //#region src/plugin/manifest.ts
 const DB_ENTITY_ANNOTATIONS = [
 	"db.table",
@@ -95,67 +96,98 @@ async function generateModelManifest(options, output, format, repo) {
 }
 //#endregion
 //#region src/plugin/annotations/agg.ts
-const dbAggAnnotations = { agg: {
-	sum: new 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 validateFieldBaseType(token, doc, "@db.agg.sum", ["number", "decimal"]);
-		}
-	}),
-	avg: new 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 validateFieldBaseType(token, doc, "@db.agg.avg", ["number", "decimal"]);
-		}
-	}),
-	count: new 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 validateFieldBaseType(token, doc, "@db.agg.count", ["number"]);
-		}
-	}),
-	min: new 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 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" && 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 = getDbTableOwner(token);
+	const entryTypeName = owner ? 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(...validateQueryScope(condition, 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 (!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 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(...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
@@ -245,7 +277,7 @@ const dbColumnAnnotations = {
 	}) },
 	column: {
 		$self: new 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: {
@@ -255,7 +287,7 @@ const dbColumnAnnotations = {
 			}
 		}),
 		renamed: new 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: {
@@ -1261,6 +1293,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 = SUPPORTED_AGGREGATE_FNS.filter((fn) => !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 (isInterface(owner)) return owner.props;
+	const def = owner.getDefinition();
+	return def && 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 && isProp(stepNode) && stepNode.countAnnotations("db.json") > 0 || isArray(step.def)) {
+			throughJson = true;
+			break;
+		}
+	}
+	if (!throughJson) return [];
+	const leaf = doc.unwindType(typeName, chain)?.def;
+	const leafType = 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 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 || !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 AnnotationSpec({
@@ -1292,29 +1404,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(...validateRefArgument(args[0], doc, { requireDbTable: true }));
+			errors.push(...validateViewInterface(owner, doc));
 			return errors;
 		}
 	}),
 	joins: new 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;
@@ -1336,9 +1460,29 @@ const dbViewAnnotations = { view: {
 				});
 				return errors;
 			}
+			const allJoins = viewJoins(owner);
+			const position = allJoins.findIndex((a) => a.token === token);
+			const earlier = 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(...validateQueryScope(args[1], [joinTargetName, entryTypeName], entryTypeName, doc));
+				errors.push(...validateQueryScope(args[1], [
+					joinTargetName,
+					entryTypeName,
+					...earlier
+				], entryTypeName, doc, "a join may reference the entry table and joins declared before it"));
 			}
 			return errors;
 		}
@@ -1372,12 +1516,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(...validateQueryScope(args[0], allowedTypes, entryTypeName, doc));
+			errors.push(...validateQueryScope(args[0], viewScopeTypes(owner), entryTypeName, doc));
 			return errors;
 		}
 	}),

package/dist/rel.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_nested_writer = require("./nested-writer-wk1EFUNY.cjs");
-const require_relation_loader = require("./relation-loader-BD4xANQJ.cjs");
+const require_nested_writer = require("./nested-writer-BZNCuqI6.cjs");
+const require_relation_loader = require("./relation-loader-6ZB_5KFq.cjs");
 exports.batchInsertNestedFrom = require_nested_writer.batchInsertNestedFrom;
 exports.batchInsertNestedTo = require_nested_writer.batchInsertNestedTo;
 exports.batchInsertNestedVia = require_nested_writer.batchInsertNestedVia;

package/dist/rel.d.cts

@@ -1,5 +1,6 @@
-import { Ct as TWriteTableResolver, Ht as TGenericLogger, K as TDbRelation, Nt as BaseDbAdapter, Ot as TableMetadata, R as TDbForeignKey, yt as TTableResolver } from "./buckets-D6PBXKRJ.cjs";
+import { Pt as BaseDbAdapter, bt as TTableResolver, kt as TableMetadata, q as TDbRelation, sn as TGenericLogger, wt as TWriteTableResolver, z as TDbForeignKey } from "./buckets-C-27xmtq.cjs";
 import { t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.cjs";
+import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-DxrvS6ar.cjs";
 import { FilterExpr, WithRelation } from "@uniqu/core";
 import { Validator } from "@atscript/typescript/utils";
 
@@ -20,25 +21,6 @@ interface TRelationLoaderHost {
  */
 declare function loadRelationsImpl(rows: Array<Record<string, unknown>>, withRelations: WithRelation[], host: TRelationLoaderHost): Promise<void>;
 //#endregion
-//#region src/rel/relation-helpers.d.ts
-/**
- * Finds the FK entry that connects a `@db.rel.to` relation to its target.
- */
-declare function findFKForRelation(relation: TDbRelation, foreignKeys: ReadonlyMap<string, TDbForeignKey>): {
-  localFields: string[];
-  targetFields: string[];
-} | undefined;
-/**
- * Finds a FK on a remote table that points back to a given table name.
- */
-declare function findRemoteFK(targetTable: {
-  foreignKeys: ReadonlyMap<string, TDbForeignKey>;
-}, thisTableName: string, alias?: string): TDbForeignKey | undefined;
-/**
- * Resolves the target table name from a relation's target type metadata.
- */
-declare function resolveRelationTargetTable(relation: TDbRelation): string;
-//#endregion
 //#region src/rel/nested-writer.d.ts
 /**
  * Properties the nested writer functions need from the table instance.

package/dist/rel.d.mts

@@ -1,5 +1,6 @@
-import { Ct as TWriteTableResolver, Ht as TGenericLogger, K as TDbRelation, Nt as BaseDbAdapter, Ot as TableMetadata, R as TDbForeignKey, yt as TTableResolver } from "./buckets-GruoVxH5.mjs";
+import { Pt as BaseDbAdapter, bt as TTableResolver, kt as TableMetadata, q as TDbRelation, sn as TGenericLogger, wt as TWriteTableResolver, z as TDbForeignKey } from "./buckets-BFG2RYRW.mjs";
 import { t as DbValidationContext } from "./db-validator-plugin-BWy60OvG.mjs";
+import { n as findRemoteFK, r as resolveRelationTargetTable, t as findFKForRelation } from "./relation-helpers-D3Zu0Mta.mjs";
 import { Validator } from "@atscript/typescript/utils";
 import { FilterExpr, WithRelation } from "@uniqu/core";
 
@@ -20,25 +21,6 @@ interface TRelationLoaderHost {
  */
 declare function loadRelationsImpl(rows: Array<Record<string, unknown>>, withRelations: WithRelation[], host: TRelationLoaderHost): Promise<void>;
 //#endregion
-//#region src/rel/relation-helpers.d.ts
-/**
- * Finds the FK entry that connects a `@db.rel.to` relation to its target.
- */
-declare function findFKForRelation(relation: TDbRelation, foreignKeys: ReadonlyMap<string, TDbForeignKey>): {
-  localFields: string[];
-  targetFields: string[];
-} | undefined;
-/**
- * Finds a FK on a remote table that points back to a given table name.
- */
-declare function findRemoteFK(targetTable: {
-  foreignKeys: ReadonlyMap<string, TDbForeignKey>;
-}, thisTableName: string, alias?: string): TDbForeignKey | undefined;
-/**
- * Resolves the target table name from a relation's target type metadata.
- */
-declare function resolveRelationTargetTable(relation: TDbRelation): string;
-//#endregion
 //#region src/rel/nested-writer.d.ts
 /**
  * Properties the nested writer functions need from the table instance.

package/dist/rel.mjs

@@ -1,3 +1,3 @@
-import { t as loadRelationsImpl } from "./relation-loader-B68R1LET.mjs";
-import { _ as resolveRelationTargetTable, a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, g as findRemoteFK, h as findFKForRelation, i as batchPatchNestedFrom, l as batchReplaceNestedVia, n as batchInsertNestedTo, o as batchPatchNestedVia, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-CqL24ojl.mjs";
+import { t as loadRelationsImpl } from "./relation-loader-CTFaZpVa.mjs";
+import { _ as resolveRelationTargetTable, a as batchPatchNestedTo, c as batchReplaceNestedTo, d as preValidateNestedFrom, f as validateBatch, g as findRemoteFK, h as findFKForRelation, i as batchPatchNestedFrom, l as batchReplaceNestedVia, n as batchInsertNestedTo, o as batchPatchNestedVia, r as batchInsertNestedVia, s as batchReplaceNestedFrom, t as batchInsertNestedFrom, u as checkDepthOverflow } from "./nested-writer-FWD5oOYh.mjs";
 export { batchInsertNestedFrom, batchInsertNestedTo, batchInsertNestedVia, batchPatchNestedFrom, batchPatchNestedTo, batchPatchNestedVia, batchReplaceNestedFrom, batchReplaceNestedTo, batchReplaceNestedVia, checkDepthOverflow, findFKForRelation, findRemoteFK, loadRelationsImpl, preValidateNestedFrom, resolveRelationTargetTable, validateBatch };

package/dist/relation-helpers-D3Zu0Mta.d.mts

@@ -0,0 +1,30 @@
+import { q as TDbRelation, z as TDbForeignKey } from "./buckets-BFG2RYRW.mjs";
+import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
+
+//#region src/rel/relation-helpers.d.ts
+/**
+ * Finds the FK entry that connects a `@db.rel.to` relation to its target.
+ */
+declare function findFKForRelation(relation: TDbRelation, foreignKeys: ReadonlyMap<string, TDbForeignKey>): {
+  localFields: string[];
+  targetFields: string[];
+} | undefined;
+/**
+ * Finds a FK on a remote table that points back to a given table name.
+ */
+declare function findRemoteFK(targetTable: {
+  foreignKeys: ReadonlyMap<string, TDbForeignKey>;
+}, thisTableName: string, alias?: string): TDbForeignKey | undefined;
+/**
+ * Table name of an annotated type — its `@db.table`, else its type id (`""`
+ * when neither is set). The rule relations, foreign keys and view plans use
+ * to name a referenced table.
+ * @since 0.1.136
+ */
+declare function tableNameOf(type: TAtscriptAnnotatedType | undefined): string;
+/**
+ * Resolves the target table name from a relation's target type metadata.
+ */
+declare function resolveRelationTargetTable(relation: TDbRelation): string;
+//#endregion
+export { tableNameOf as i, findRemoteFK as n, resolveRelationTargetTable as r, findFKForRelation as t };

package/dist/relation-helpers-DxrvS6ar.d.cts

@@ -0,0 +1,30 @@
+import { q as TDbRelation, z as TDbForeignKey } from "./buckets-C-27xmtq.cjs";
+import { TAtscriptAnnotatedType } from "@atscript/typescript/utils";
+
+//#region src/rel/relation-helpers.d.ts
+/**
+ * Finds the FK entry that connects a `@db.rel.to` relation to its target.
+ */
+declare function findFKForRelation(relation: TDbRelation, foreignKeys: ReadonlyMap<string, TDbForeignKey>): {
+  localFields: string[];
+  targetFields: string[];
+} | undefined;
+/**
+ * Finds a FK on a remote table that points back to a given table name.
+ */
+declare function findRemoteFK(targetTable: {
+  foreignKeys: ReadonlyMap<string, TDbForeignKey>;
+}, thisTableName: string, alias?: string): TDbForeignKey | undefined;
+/**
+ * Table name of an annotated type — its `@db.table`, else its type id (`""`
+ * when neither is set). The rule relations, foreign keys and view plans use
+ * to name a referenced table.
+ * @since 0.1.136
+ */
+declare function tableNameOf(type: TAtscriptAnnotatedType | undefined): string;
+/**
+ * Resolves the target table name from a relation's target type metadata.
+ */
+declare function resolveRelationTargetTable(relation: TDbRelation): string;
+//#endregion
+export { tableNameOf as i, findRemoteFK as n, resolveRelationTargetTable as r, findFKForRelation as t };

package/dist/{relation-loader-BD4xANQJ.cjs → relation-loader-6ZB_5KFq.cjs}

@@ -1,4 +1,4 @@
-const require_nested_writer = require("./nested-writer-wk1EFUNY.cjs");
+const require_nested_writer = require("./nested-writer-BZNCuqI6.cjs");
 //#region src/rel/relation-loader.ts
 var relation_loader_exports = /* @__PURE__ */ require("./plugin.cjs").__exportAll({
 	ensureSelectIncludesFields: () => ensureSelectIncludesFields,

package/dist/{relation-loader-B68R1LET.mjs → relation-loader-CTFaZpVa.mjs}

@@ -1,4 +1,4 @@
-import { _ as resolveRelationTargetTable, g as findRemoteFK, h as findFKForRelation } from "./nested-writer-CqL24ojl.mjs";
+import { _ as resolveRelationTargetTable, g as findRemoteFK, h as findFKForRelation } from "./nested-writer-FWD5oOYh.mjs";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {

package/dist/shared.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_validation_utils = require("./validation-utils-B7SXPkm7.cjs");
+const require_validation_utils = require("./validation-utils-Dg0hW6dn.cjs");
 exports.findFKFieldsPointingTo = require_validation_utils.findFKFieldsPointingTo;
 exports.getAnnotationAlias = require_validation_utils.getAnnotationAlias;
 exports.getDbTableOwner = require_validation_utils.getDbTableOwner;
@@ -7,9 +7,13 @@ exports.getNavTargetTypeName = require_validation_utils.getNavTargetTypeName;
 exports.getParentStruct = require_validation_utils.getParentStruct;
 exports.getParentTypeName = require_validation_utils.getParentTypeName;
 exports.hasAnyViewAnnotation = require_validation_utils.hasAnyViewAnnotation;
+exports.joinTargets = require_validation_utils.joinTargets;
+exports.primitiveBaseType = require_validation_utils.primitiveBaseType;
 exports.refActionAnnotation = require_validation_utils.refActionAnnotation;
 exports.validateExclusiveWith = require_validation_utils.validateExclusiveWith;
 exports.validateFieldBaseType = require_validation_utils.validateFieldBaseType;
 exports.validateQueryScope = require_validation_utils.validateQueryScope;
 exports.validateRefArgument = require_validation_utils.validateRefArgument;
 exports.validateSiblingStringField = require_validation_utils.validateSiblingStringField;
+exports.viewJoins = require_validation_utils.viewJoins;
+exports.viewScopeTypes = require_validation_utils.viewScopeTypes;

package/dist/shared.d.cts

@@ -1,4 +1,4 @@
-import { AnnotationSpec, AtscriptDoc, SemanticInterfaceNode, SemanticNode, SemanticPropNode, SemanticStructureNode, TMessages, Token } from "@atscript/core";
+import { AnnotationSpec, AtscriptDoc, SemanticInterfaceNode, SemanticNode, SemanticPropNode, SemanticStructureNode, TAnnotationTokens, TMessages, Token } from "@atscript/core";
 
 //#region src/shared/annotation-utils.d.ts
 /** Asserts the field carrying this annotation does not also carry any of `others`. */
@@ -6,6 +6,8 @@ declare function validateExclusiveWith(token: Token, selfName: string, others: A
   key: string;
   displayName?: string;
 }>): TMessages;
+/** Primitive base type (`string`, `number`, `decimal`, …) of a resolved definition, if it is a primitive. */
+declare function primitiveBaseType(def: SemanticNode | undefined): string | undefined;
 /** Asserts `args[0]` names a sibling property whose primitive base type is `string`. */
 declare function validateSiblingStringField(token: Token, args: Token[], doc: AtscriptDoc, selfName: string): TMessages;
 /**
@@ -61,6 +63,16 @@ interface TFKFieldMatch {
  * Resolves `extends` to include inherited fields.
  */
 declare function findFKFieldsPointingTo(doc: AtscriptDoc, iface: SemanticInterfaceNode | SemanticStructureNode, targetTypeName: string, alias?: string): TFKFieldMatch[];
+/** The `@db.view.joins` annotations of a view interface, in declaration order. */
+declare function viewJoins(owner: SemanticNode): TAnnotationTokens[];
+/** The target type names of `@db.view.joins` annotations. */
+declare function joinTargets(joins: readonly TAnnotationTokens[]): string[];
+/**
+ * The type names a view predicate (`@db.view.filter`, a conditional
+ * `@db.agg.*`) may reference: the `@db.view.for` entry table, then every
+ * `@db.view.joins` target.
+ */
+declare function viewScopeTypes(owner: SemanticNode): string[];
 /**
  * Check if a node has any @db.view.* annotation.
  */
@@ -72,7 +84,8 @@ declare function hasAnyViewAnnotation(node: SemanticNode): boolean;
  * @param allowedTypes - Type names allowed as qualified refs
  * @param unqualifiedTarget - Type name for resolving unqualified refs, or null to disallow them
  * @param doc - The document for type lookups
+ * @param scopeHint - Replaces the default "expected 'A' or 'B'" tail of the out-of-scope message
  */
-declare function validateQueryScope(queryToken: Token, allowedTypes: string[], unqualifiedTarget: string | null, doc: AtscriptDoc): TMessages;
+declare function validateQueryScope(queryToken: Token, allowedTypes: string[], unqualifiedTarget: string | null, doc: AtscriptDoc, scopeHint?: string): TMessages;
 //#endregion
-export { TFKFieldMatch, findFKFieldsPointingTo, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, refActionAnnotation, validateExclusiveWith, validateFieldBaseType, validateQueryScope, validateRefArgument, validateSiblingStringField };
+export { TFKFieldMatch, findFKFieldsPointingTo, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, joinTargets, primitiveBaseType, refActionAnnotation, validateExclusiveWith, validateFieldBaseType, validateQueryScope, validateRefArgument, validateSiblingStringField, viewJoins, viewScopeTypes };

package/dist/shared.d.mts

@@ -1,4 +1,4 @@
-import { AnnotationSpec, AtscriptDoc, SemanticInterfaceNode, SemanticNode, SemanticPropNode, SemanticStructureNode, TMessages, Token } from "@atscript/core";
+import { AnnotationSpec, AtscriptDoc, SemanticInterfaceNode, SemanticNode, SemanticPropNode, SemanticStructureNode, TAnnotationTokens, TMessages, Token } from "@atscript/core";
 
 //#region src/shared/annotation-utils.d.ts
 /** Asserts the field carrying this annotation does not also carry any of `others`. */
@@ -6,6 +6,8 @@ declare function validateExclusiveWith(token: Token, selfName: string, others: A
   key: string;
   displayName?: string;
 }>): TMessages;
+/** Primitive base type (`string`, `number`, `decimal`, …) of a resolved definition, if it is a primitive. */
+declare function primitiveBaseType(def: SemanticNode | undefined): string | undefined;
 /** Asserts `args[0]` names a sibling property whose primitive base type is `string`. */
 declare function validateSiblingStringField(token: Token, args: Token[], doc: AtscriptDoc, selfName: string): TMessages;
 /**
@@ -61,6 +63,16 @@ interface TFKFieldMatch {
  * Resolves `extends` to include inherited fields.
  */
 declare function findFKFieldsPointingTo(doc: AtscriptDoc, iface: SemanticInterfaceNode | SemanticStructureNode, targetTypeName: string, alias?: string): TFKFieldMatch[];
+/** The `@db.view.joins` annotations of a view interface, in declaration order. */
+declare function viewJoins(owner: SemanticNode): TAnnotationTokens[];
+/** The target type names of `@db.view.joins` annotations. */
+declare function joinTargets(joins: readonly TAnnotationTokens[]): string[];
+/**
+ * The type names a view predicate (`@db.view.filter`, a conditional
+ * `@db.agg.*`) may reference: the `@db.view.for` entry table, then every
+ * `@db.view.joins` target.
+ */
+declare function viewScopeTypes(owner: SemanticNode): string[];
 /**
  * Check if a node has any @db.view.* annotation.
  */
@@ -72,7 +84,8 @@ declare function hasAnyViewAnnotation(node: SemanticNode): boolean;
  * @param allowedTypes - Type names allowed as qualified refs
  * @param unqualifiedTarget - Type name for resolving unqualified refs, or null to disallow them
  * @param doc - The document for type lookups
+ * @param scopeHint - Replaces the default "expected 'A' or 'B'" tail of the out-of-scope message
  */
-declare function validateQueryScope(queryToken: Token, allowedTypes: string[], unqualifiedTarget: string | null, doc: AtscriptDoc): TMessages;
+declare function validateQueryScope(queryToken: Token, allowedTypes: string[], unqualifiedTarget: string | null, doc: AtscriptDoc, scopeHint?: string): TMessages;
 //#endregion
-export { TFKFieldMatch, findFKFieldsPointingTo, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, refActionAnnotation, validateExclusiveWith, validateFieldBaseType, validateQueryScope, validateRefArgument, validateSiblingStringField };
+export { TFKFieldMatch, findFKFieldsPointingTo, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, joinTargets, primitiveBaseType, refActionAnnotation, validateExclusiveWith, validateFieldBaseType, validateQueryScope, validateRefArgument, validateSiblingStringField, viewJoins, viewScopeTypes };