@atscript/db 0.1.146 → 0.1.147

package/dist/plugin.cjs

@@ -33,10 +33,10 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_aggregate_fns = require("./aggregate-fns-CGBv3E8S.cjs");
+const require_aggregate_fns = require("./aggregate-fns-CtsRbZn9.cjs");
 const require_derived_rules = require("./derived-rules-YstgIxG-.cjs");
 require("./consts-BzRfCcH2.cjs");
-const require_validation_utils = require("./validation-utils-DOsB4e6G.cjs");
+const require_validation_utils = require("./validation-utils-Da2GjobR.cjs");
 let node_path = require("node:path");
 node_path = __toESM(node_path, 1);
 let node_url = require("node:url");
@@ -174,6 +174,27 @@ function viewHavingScope(view) {
 		unqualifiedTarget: view.id
 	} : void 0;
 }
+/**
+* The ordering (4th argument) of a first-row `@db.view.joins`: the join
+* target only — an unqualified key is a field of the target.
+* @since 0.1.147
+*/
+function joinOrderScope(join) {
+	const target = join.args[0]?.text;
+	return target ? {
+		allowedTypes: [target],
+		unqualifiedTarget: target
+	} : void 0;
+}
+/**
+* The expression of a `@db.compute` on a view field: the view's own fields,
+* unqualified — the `@db.view.having` scope.
+* @since 0.1.147
+*/
+function computeScope(propToken) {
+	const view = require_validation_utils.getDbTableOwner(propToken);
+	return view ? viewHavingScope(view) : void 0;
+}
 /** The condition of a `@db.agg.*` on a view field: the scope of the view's `@db.view.filter`. */
 function aggConditionScope(propToken) {
 	const view = require_validation_utils.getDbTableOwner(propToken);
@@ -208,16 +229,25 @@ function relFilterScope(field) {
 		unqualifiedTarget: target
 	};
 }
+/** The `@db.view.joins` annotation one of whose arguments is `arg`. */
+function joinOfArg(joins, arg) {
+	return joins.find((a) => a.args.includes(arg));
+}
 /** The `fieldScope` hooks (argument token → scope) the annotation specs declare. */
 const fieldScopes = {
 	viewFilter: (arg) => arg.parentNode ? viewFilterScope(arg.parentNode) : void 0,
 	viewJoin: (arg) => {
 		const view = arg.parentNode;
 		const joins = view ? require_validation_utils.viewJoins(view) : [];
-		const join = joins.find((a) => a.args.includes(arg));
+		const join = joinOfArg(joins, arg);
 		return view && join ? viewJoinScope(view, join, require_validation_utils.earlierJoinTargets(joins, join)) : void 0;
 	},
+	joinOrder: (arg) => {
+		const join = arg.parentNode ? joinOfArg(require_validation_utils.viewJoins(arg.parentNode), arg) : void 0;
+		return join ? joinOrderScope(join) : void 0;
+	},
 	viewHaving: (arg) => arg.parentNode ? viewHavingScope(arg.parentNode) : void 0,
+	compute: computeScope,
 	aggCondition: aggConditionScope,
 	aggField: aggFieldScope,
 	relFilter: (arg) => arg.parentNode ? relFilterScope(arg.parentNode) : void 0
@@ -868,6 +898,127 @@ function columnCapability(capability, verb) {
 	});
 }
 //#endregion
+//#region src/plugin/annotations/compute.ts
+/** What a `@db.compute` field cannot also carry (VC1). */
+const EXCLUSIVE_WITH = [
+	...require_aggregate_fns.AGG_ANNOTATIONS,
+	"db.json",
+	"db.ignore"
+].map((key) => ({ key }));
+/** Primitive tags of timestamps (MySQL may store them as native `TIMESTAMP`). */
+const TIMESTAMP_TAGS = [
+	"timestamp",
+	"created",
+	"updated"
+];
+/** The `@db.compute` expression token of a prop, if any. */
+function computeArg(prop) {
+	return prop?.annotations?.find((a) => a.name === "db.compute")?.args[0];
+}
+/**
+* Whether a prop is typed exactly `number` (a plain primitive ref — no chain
+* ref, no `number.*` extension).
+*/
+function isPlainNumber(prop, doc) {
+	const def = prop.getDefinition();
+	if (!def || !(0, _atscript_core.isRef)(def) || def.hasChain || def.id !== "number") return false;
+	return (0, _atscript_core.isPrimitive)(doc.unwindType("number")?.def);
+}
+/**
+* Why an operand prop cannot be computed with, or `undefined` when it can:
+* its resolved type must be a `number` primitive — not `decimal`, not a
+* timestamp — and it must have storage (no `@db.ignore`).
+*/
+function operandProblem(prop, doc) {
+	if (prop.countAnnotations("db.ignore") > 0) return "is @db.ignore'd";
+	if (computeArg(prop)) return void 0;
+	const def = prop.getDefinition();
+	const leaf = def && (0, _atscript_core.isRef)(def) ? doc.unwindType(def.id, def.chain)?.def : def;
+	const base = require_validation_utils.primitiveBaseType(leaf);
+	if (base === void 0) return void 0;
+	if (base !== "number") return `is ${base === "decimal" ? "a decimal" : `a ${base}`}`;
+	if ((0, _atscript_core.isPrimitive)(leaf) && TIMESTAMP_TAGS.some((t) => leaf.tags.has(t))) return "is a timestamp";
+}
+/** VC6 — whether an expression may be NULL (`/` by zero, an optional operand). */
+function exprNullable(node, props) {
+	if ("value" in node) return false;
+	if ("left" in node) return node.op === "/" || exprNullable(node.left, props) || exprNullable(node.right, props);
+	if ("operand" in node) return exprNullable(node.operand, props);
+	if ("args" in node) return node.args.every((a) => exprNullable(a, props));
+	return props.get(node.fieldRef.text)?.has("optional") ?? false;
+}
+/**
+* VC4 — the first `@db.compute` cycle through `start`, as field names
+* (`rank → priority → rank`), or `undefined`.
+*/
+function findComputeCycle(start, props) {
+	const path = [];
+	const done = /* @__PURE__ */ new Set();
+	const visit = (name) => {
+		const at = path.indexOf(name);
+		if (at !== -1) return name === start ? [...path.slice(at), name] : void 0;
+		if (done.has(name)) return void 0;
+		const refs = computeArg(props.get(name))?.exprNode?.fieldRefs() ?? [];
+		path.push(name);
+		for (const ref of refs) {
+			if (ref.typeRef) continue;
+			const cycle = visit(ref.fieldRef.text);
+			if (cycle) return cycle;
+		}
+		path.pop();
+		done.add(name);
+	};
+	return visit(start);
+}
+function validateCompute(token, args, doc) {
+	const errors = [];
+	const prop = token.parentNode;
+	const field = prop.id ?? "field";
+	const view = require_validation_utils.getDbTableOwner(token);
+	const error = (message, range = token.range) => errors.push({
+		message,
+		severity: 1,
+		range
+	});
+	if (!view || view.countAnnotations("db.view.for") === 0) {
+		error("@db.compute is only valid on a field of a @db.view.for view");
+		return errors;
+	}
+	errors.push(...require_validation_utils.validateExclusiveWith(token, "@db.compute", EXCLUSIVE_WITH));
+	if (!isPlainNumber(prop, doc)) error(`Field "${field}" has a @db.compute and must be typed \`number\``);
+	const expr = args[0]?.exprNode;
+	if (!expr) return errors;
+	const refs = expr.fieldRefs();
+	const props = viewProps(view) ?? /* @__PURE__ */ new Map();
+	if (refs.length === 0) error("@db.compute needs at least one view field — a constant column is not supported", args[0].range);
+	const scope = viewHavingScope(view);
+	if (scope) errors.push(...require_validation_utils.validateQueryScope(args[0], scope, doc, "@db.compute references the view's own fields — declare it on the view first (`field: Type.field`)"));
+	for (const ref of refs) {
+		if (ref.typeRef) continue;
+		const operand = props.get(ref.fieldRef.text);
+		const why = operand && operandProblem(operand, doc);
+		if (why) error(`@db.compute operand '${ref.fieldRef.text}' ${why} — operands must be number fields`, ref.fieldRef.range);
+	}
+	if (prop.id) {
+		const cycle = findComputeCycle(prop.id, props);
+		if (cycle) error(`@db.compute of "${field}" depends on itself: ${cycle.join(" → ")}`, args[0].range);
+	}
+	if (!prop.has("optional") && exprNullable(expr.expression, props)) error(`Field "${field}" has a @db.compute that may be NULL and must be optional (${field}?: …) — it is NULL when an operand is NULL or a divisor is 0`);
+	return errors;
+}
+const dbComputeAnnotations = { compute: new _atscript_core.AnnotationSpec({
+	description: "Declares a **computed view column** (since 0.1.147): closed arithmetic over the view's own fields — dimensions, aggregates, first-row-join fields and other computed fields — evaluated by the database, so the column sorts, filters and pages like any other.\n\nGrammar: `+ - * /`, unary `-`, parentheses, numeric literals, `coalesce(a, b, …)`. Every value is a double (`7 / 2 = 3.5`); a NULL operand yields NULL; division by zero yields NULL — so an expression with `/` or an optional operand needs an optional field.\n\n**Example:**\n```atscript\n@db.agg.count 'id', `Issue.status = 'open'`\nopenCount: Issue.id\n\n@db.compute `openCount * 10 + coalesce(oldestSeverity, 0)`\nrank: number\n```\n",
+	nodeType: ["prop"],
+	passedWhenReferred: false,
+	argument: {
+		name: "expression",
+		type: "expr",
+		description: "Arithmetic over the view's own fields (unqualified): `+ - * /`, unary `-`, parentheses, numbers, `coalesce(a, b, …)`.",
+		fieldScope: fieldScopes.compute
+	},
+	validate: validateCompute
+}) };
+//#endregion
 //#region src/plugin/annotations/index-ann.ts
 const dbIndexAnnotations = { index: {
 	plain: new _atscript_core.AnnotationSpec({
@@ -1258,8 +1409,23 @@ const dbRelAnnotations = { rel: {
 			return errors;
 		}
 	}),
+	filterable: new _atscript_core.AnnotationSpec({
+		description: "Lets HTTP clients filter the parent rows by this relation's related rows — `ticket=$some(status=open)` / `ticket=$none(...)` in a moost-db query (`{ ticket: { $some: { status: 'open' } } }`). Off by default: a client predicate filters the PARENT set and runs a correlated subquery. Server-side code (`transformFilter`, `actionRowScope`, direct table calls) never needs it. The related table's own field rules (visibility, encryption, write-only) apply inside the predicate.\n\n**Example:**\n```atscript\n@db.rel.to\n@db.rel.filterable\nticket?: Ticket\n```\n",
+		nodeType: ["prop"],
+		passedWhenReferred: false,
+		validate(token) {
+			const errors = [];
+			const field = token.parentNode;
+			if (!(field.countAnnotations("db.rel.to") > 0 || field.countAnnotations("db.rel.from") > 0 || field.countAnnotations("db.rel.via") > 0)) errors.push({
+				message: "@db.rel.filterable is only valid on navigational fields (@db.rel.to, @db.rel.from, or @db.rel.via)",
+				severity: 1,
+				range: token.range
+			});
+			return errors;
+		}
+	}),
 	filter: new _atscript_core.AnnotationSpec({
-		description: "Applies a filter to a navigational property, restricting which related records are loaded.\n\n**Example:**\n```atscript\n@db.rel.from\n@db.rel.filter `Post.published = true`\npublishedPosts: Post[]\n```\n",
+		description: "Applies a filter to a navigational property, restricting which related records are loaded (`$with`) and which count in relational predicates (`$some` / `$none`).\n\n**Example:**\n```atscript\n@db.rel.from\n@db.rel.filter `Post.published = true`\npublishedPosts: Post[]\n```\n",
 		nodeType: ["prop"],
 		passedWhenReferred: false,
 		argument: {
@@ -1285,10 +1451,40 @@ const dbRelAnnotations = { rel: {
 			if (!args[0]?.queryNode) return errors;
 			const scope = relFilterScope(field);
 			if (scope) errors.push(...require_validation_utils.validateQueryScope(args[0], scope, doc));
+			const expression = args[0].queryNode.expression;
+			forEachComparison(expression, (cmp) => {
+				if (cmp.right && "fieldRef" in cmp.right) errors.push({
+					message: "@db.rel.filter compares two fields — only field-to-value conditions are supported",
+					severity: 1,
+					range: cmp.right.fieldRef.range
+				});
+			});
+			const junction = hasVia ? require_validation_utils.getAnnotationAlias(field, "db.rel.via") : void 0;
+			if (junction) {
+				const conjuncts = (0, _atscript_core.isQueryLogical)(expression) && expression.operator === "and" ? expression.operands : [expression];
+				for (const conjunct of conjuncts) {
+					let junctionRef;
+					let targetRef = false;
+					require_validation_utils.forEachFieldRef(conjunct, (ref) => {
+						if (ref.typeRef?.text === junction) junctionRef ??= ref.typeRef.range;
+						else targetRef = true;
+					});
+					if (junctionRef && targetRef) errors.push({
+						message: `@db.rel.filter has a condition reading both the junction '${junction}' and the related type — split it into separate top-level "and" conditions`,
+						severity: 1,
+						range: junctionRef
+					});
+				}
+			}
 			return errors;
 		}
 	})
 } };
+/** Every comparison of a query expression (through and / or / not). */
+function forEachComparison(expr, fn) {
+	if ((0, _atscript_core.isQueryLogical)(expr)) for (const operand of expr.operands) forEachComparison(operand, fn);
+	else if ((0, _atscript_core.isQueryComparison)(expr)) fn(expr);
+}
 //#endregion
 //#region src/plugin/annotations/search.ts
 const dbSearchAnnotations = { search: {
@@ -1638,6 +1834,61 @@ const dbUnitAnnotations = { unit: {
 } };
 //#endregion
 //#region src/plugin/annotations/view.ts
+/**
+* VJ6–VJ8 — the ordering of a first-row join: every key is a scalar field of
+* the join target (no object, array, `@db.json`, `@db.encrypted`, `@db.writeOnly` or
+* navigation field), no key repeats, and the target (through `@db.alias`)
+* declares exactly one `@meta.id` field — the anchor of the join's
+* correlated subquery.
+*/
+function validateJoinOrder(orderToken, scope, doc) {
+	const target = scope.unqualifiedTarget;
+	const errors = require_validation_utils.validateQueryScope(orderToken, scope, doc, `a first-row join orders by fields of its target '${target}'`);
+	const seen = /* @__PURE__ */ new Set();
+	for (const item of orderToken.orderNode.items) {
+		const { ref } = item;
+		if (ref.typeRef && ref.typeRef.text !== target) continue;
+		const path = ref.fieldRef.text;
+		if (seen.has(path)) {
+			errors.push({
+				message: `Order key '${path}' appears more than once`,
+				severity: 1,
+				range: ref.fieldRef.range
+			});
+			continue;
+		}
+		seen.add(path);
+		const why = orderKeyProblem(doc, target, path.split("."));
+		if (why) errors.push({
+			message: `Order key '${path}' ${why} — order by a scalar field of '${target}'`,
+			severity: 1,
+			range: ref.fieldRef.range
+		});
+	}
+	const ids = (0, _atscript_core.getFieldsForType)(doc, target).filter((p) => p.countAnnotations("meta.id") > 0);
+	if (ids.length !== 1) errors.push({
+		message: `A first-row join needs a target with exactly one @meta.id field — '${target}' has ${ids.length === 0 ? "none" : `${ids.length} (a composite key)`}`,
+		severity: 1,
+		range: orderToken.range
+	});
+	return errors;
+}
+/** Why `path` of `target` cannot order a first-row join, or `undefined` when it can. */
+function orderKeyProblem(doc, target, path) {
+	for (let i = 1; i <= path.length; i++) {
+		const step = doc.unwindType(target, path.slice(0, i));
+		if (!step) return void 0;
+		const node = step.node;
+		if (node && (0, _atscript_core.isProp)(node)) {
+			if (node.countAnnotations("db.json") > 0) return "reads a @db.json field";
+			if (node.countAnnotations("db.encrypted") > 0) return "is @db.encrypted";
+			if (node.countAnnotations("db.writeOnly") > 0) return "is @db.writeOnly";
+			if (node.countAnnotations("db.ignore") > 0) return "is @db.ignore'd";
+		}
+		if ((0, _atscript_core.isArray)(step.def)) return "is an array";
+		if (i === path.length && !(0, _atscript_core.isPrimitive)(step.def)) return "is not a scalar";
+	}
+}
 const dbViewAnnotations = { view: {
 	$self: new _atscript_core.AnnotationSpec({
 		description: "Marks an interface as a **database view**. Optionally takes a view name argument.\n\n**Example:**\n```atscript\n@db.view \"active_premium_users\"\n@db.view.for User\nexport interface ActivePremiumUser { ... }\n```\n",
@@ -1689,7 +1940,7 @@ const dbViewAnnotations = { view: {
 		}
 	}),
 	joins: new _atscript_core.AnnotationSpec({
-		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). The target is a `@db.table`, a `@db.view` (since 0.1.141), or a `@db.alias` type — the way to join one table twice or to self-join the entry table: every scope name (entry + joins) must be unique.\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",
+		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). The target is a `@db.table`, a `@db.view` (since 0.1.141), or a `@db.alias` type — the way to join one table twice or to self-join the entry table: every scope name (entry + joins) must be unique.\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\n**First-row join** (since 0.1.147): a 4th argument — an ordering of the target's fields (`` `raisedAt, id` ``, `` `severity desc` ``) — joins only the FIRST matching target row by that ordering (the target's primary key is appended as the final tie-break), so every field read through the join comes from that one row. NULL sorts first in `asc`.\n```atscript\n@db.view.joins OldestOpenIssue, `OldestOpenIssue.ticketId = Ticket.id and OldestOpenIssue.status = 'open'`, 'left', `raisedAt`\n```\n",
 		nodeType: ["interface"],
 		passedWhenReferred: false,
 		multiple: true,
@@ -1713,6 +1964,13 @@ const dbViewAnnotations = { view: {
 				optional: true,
 				description: "`\"inner\"` (default) drops entry rows without a match; `\"left\"` keeps them with NULLs.",
 				values: ["inner", "left"]
+			},
+			{
+				name: "order",
+				type: "order",
+				optional: true,
+				description: "Makes this a first-row join: of the target rows matching the condition only the first by this ordering joins (`` `raisedAt, id` ``, `` `severity desc` ``). Keys are scalar fields of the join target; its primary key is appended as the final tie-break. NULL is the smallest value (first in `asc`, last in `desc`).",
+				fieldScope: fieldScopes.joinOrder
 			}
 		],
 		validate(token, args, doc) {
@@ -1761,6 +2019,8 @@ const dbViewAnnotations = { view: {
 			}
 			const scope = join && viewJoinScope(owner, join, earlier);
 			if (args[1]?.queryNode && scope) errors.push(...require_validation_utils.validateQueryScope(args[1], scope, doc, "a join may reference the entry table and joins declared before it"));
+			const order = join && args[3]?.orderNode ? joinOrderScope(join) : void 0;
+			if (order) errors.push(...validateJoinOrder(args[3], order, doc));
 			return errors;
 		}
 	}),
@@ -1890,6 +2150,7 @@ const dbPlugin = (options) => ({
 				view: dbViewAnnotations.view,
 				alias: dbAliasAnnotations.alias,
 				agg: dbAggAnnotations.agg,
+				compute: dbComputeAnnotations.compute,
 				search: dbSearchAnnotations.search,
 				amount: dbAmountAnnotations.amount,
 				unit: dbUnitAnnotations.unit