@atscript/db 0.1.38

package/dist/relation-loader-Dv7qXYq7.mjs

@@ -0,0 +1,409 @@
+import { findFKForRelation, findRemoteFK, resolveRelationTargetTable } from "./relation-helpers-DyBIlQnB.mjs";
+
+//#region packages/db/src/rel/relation-loader.ts
+async function loadRelationsImpl(rows, withRelations, host) {
+	if (rows.length === 0 || withRelations.length === 0) return;
+	if (host.adapter.supportsNativeRelations()) return host.adapter.loadRelations(rows, withRelations, host._meta.relations, host._meta.foreignKeys, host._tableResolver);
+	if (!host._tableResolver) return;
+	const tasks = [];
+	for (const withRel of withRelations) {
+		const relName = withRel.name;
+		if (relName.includes(".")) continue;
+		const relation = host._meta.relations.get(relName);
+		if (!relation) throw new Error(`Unknown relation "${relName}" in $with. Available relations: ${[...host._meta.relations.keys()].join(", ") || "(none)"}`);
+		const targetType = relation.targetType();
+		if (!targetType) continue;
+		const targetTable = host._tableResolver(targetType);
+		if (!targetTable) {
+			host.logger.warn(`Could not resolve table for relation "${relName}" — skipping`);
+			continue;
+		}
+		const filter = withRel.filter && Object.keys(withRel.filter).length > 0 ? withRel.filter : undefined;
+		const flatRel = withRel;
+		const nested = withRel.controls || {};
+		const controls = { ...nested };
+		if (flatRel.$sort && !controls.$sort) controls.$sort = flatRel.$sort;
+		if (flatRel.$limit !== null && flatRel.$limit !== undefined && (controls.$limit === null || controls.$limit === undefined)) controls.$limit = flatRel.$limit;
+		if (flatRel.$skip !== null && flatRel.$skip !== undefined && (controls.$skip === null || controls.$skip === undefined)) controls.$skip = flatRel.$skip;
+		if (flatRel.$select && !controls.$select) controls.$select = flatRel.$select;
+		if (flatRel.$with && !controls.$with) controls.$with = flatRel.$with;
+		const relQuery = {
+			filter,
+			controls
+		};
+		if (relation.direction === "to") tasks.push(loadToRelation(rows, {
+			relName,
+			relation,
+			targetTable,
+			relQuery
+		}, host));
+else if (relation.direction === "via") tasks.push(loadViaRelation(rows, {
+			relName,
+			relation,
+			targetTable,
+			relQuery
+		}, host));
+else tasks.push(loadFromRelation(rows, {
+			relName,
+			relation,
+			targetTable,
+			relQuery
+		}, host));
+	}
+	await Promise.all(tasks);
+}
+/**
+* Loads a `@db.rel.to` relation (FK is on this table).
+*/ async function loadToRelation(rows, opts, host) {
+	const { relName, relation, targetTable, relQuery } = opts;
+	const fkEntry = findFKForRelation(relation, host._meta.foreignKeys);
+	if (!fkEntry) return;
+	const { localFields, targetFields } = fkEntry;
+	if (localFields.length === 1) {
+		const localField = localFields[0];
+		const targetField = targetFields[0];
+		const fkValues = collectUniqueValues(rows, localField);
+		if (fkValues.length === 0) {
+			for (const row of rows) row[relName] = null;
+			return;
+		}
+		const inFilter = { [targetField]: { $in: fkValues } };
+		const targetFilter = relQuery.filter ? { $and: [inFilter, relQuery.filter] } : inFilter;
+		const controls = ensureSelectIncludesFields(relQuery.controls, targetFields);
+		const related = await targetTable.findMany({
+			filter: targetFilter,
+			controls
+		});
+		assignSingle({
+			rows,
+			related,
+			localField,
+			remoteField: targetField,
+			relName
+		});
+	} else {
+		const related = await queryCompositeFK(rows, {
+			localFields,
+			targetFields,
+			targetTable,
+			relQuery
+		});
+		const index = new Map();
+		for (const item of related) index.set(compositeKey(targetFields, item), item);
+		for (const row of rows) row[relName] = index.get(compositeKey(localFields, row)) ?? null;
+	}
+}
+/**
+* Loads a `@db.rel.from` relation (FK is on the target table).
+*/ async function loadFromRelation(rows, opts, host) {
+	const { relName, relation, targetTable, relQuery } = opts;
+	const remoteFK = findRemoteFK(targetTable, host.tableName, relation.alias);
+	if (!remoteFK) {
+		host.logger.warn(`Could not find FK on target table for relation "${relName}"`);
+		return;
+	}
+	const localFields = remoteFK.targetFields;
+	const remoteFields = remoteFK.fields;
+	if (localFields.length === 1) {
+		const localField = localFields[0];
+		const remoteField = remoteFields[0];
+		const pkValues = collectUniqueValues(rows, localField);
+		if (pkValues.length === 0) return;
+		const inFilter = { [remoteField]: { $in: pkValues } };
+		const targetFilter = relQuery.filter ? { $and: [inFilter, relQuery.filter] } : inFilter;
+		const controls = ensureSelectIncludesFields(relQuery.controls, remoteFields);
+		const related = await targetTable.findMany({
+			filter: targetFilter,
+			controls
+		});
+		if (relation.isArray) assignGrouped({
+			rows,
+			related,
+			localField,
+			remoteField,
+			relName
+		});
+else assignSingle({
+			rows,
+			related,
+			localField,
+			remoteField,
+			relName
+		});
+	} else {
+		const related = await queryCompositeFK(rows, {
+			localFields,
+			targetFields: remoteFields,
+			targetTable,
+			relQuery
+		});
+		if (relation.isArray) {
+			const groups = new Map();
+			for (const item of related) {
+				const key = compositeKey(remoteFields, item);
+				let group = groups.get(key);
+				if (!group) {
+					group = [];
+					groups.set(key, group);
+				}
+				group.push(item);
+			}
+			for (const row of rows) row[relName] = groups.get(compositeKey(localFields, row)) ?? [];
+		} else {
+			const index = new Map();
+			for (const item of related) {
+				const key = compositeKey(remoteFields, item);
+				if (!index.has(key)) index.set(key, item);
+			}
+			for (const row of rows) row[relName] = index.get(compositeKey(localFields, row)) ?? null;
+		}
+	}
+}
+/**
+* Loads a `@db.rel.via` relation (M:N through a junction table).
+*/ async function loadViaRelation(rows, opts, host) {
+	const { relName, relation, targetTable, relQuery } = opts;
+	if (!relation.viaType || !host._tableResolver) return;
+	const junctionType = relation.viaType();
+	if (!junctionType) return;
+	const junctionTable = host._tableResolver(junctionType);
+	if (!junctionTable) {
+		host.logger.warn(`Could not resolve junction table for via relation "${relName}"`);
+		return;
+	}
+	const fkToThis = findRemoteFK(junctionTable, host.tableName);
+	if (!fkToThis) {
+		host.logger.warn(`Could not find FK on junction table pointing to "${host.tableName}" for via relation "${relName}"`);
+		return;
+	}
+	const targetTableName = resolveRelationTargetTable(relation);
+	const fkToTarget = findRemoteFK(junctionTable, targetTableName);
+	if (!fkToTarget) {
+		host.logger.warn(`Could not find FK on junction table pointing to target "${targetTableName}" for via relation "${relName}"`);
+		return;
+	}
+	const localPKFields = fkToThis.targetFields;
+	const junctionLocalFields = fkToThis.fields;
+	const targetPKFields = fkToTarget.targetFields;
+	const junctionTargetFields = fkToTarget.fields;
+	if (localPKFields.length === 1) await loadViaSingleKey(rows, {
+		relName,
+		relation,
+		targetTable,
+		relQuery,
+		localPKFields,
+		junctionLocalFields,
+		targetPKFields,
+		junctionTargetFields,
+		junctionTable
+	});
+else await loadViaCompositeKey(rows, {
+		relName,
+		relation,
+		targetTable,
+		relQuery,
+		localPKFields,
+		junctionLocalFields,
+		targetPKFields,
+		junctionTargetFields,
+		junctionTable
+	});
+}
+async function loadViaSingleKey(rows, opts) {
+	const { relName, relation, targetTable, relQuery, localPKFields, junctionLocalFields, targetPKFields, junctionTargetFields, junctionTable } = opts;
+	const localField = localPKFields[0];
+	const junctionLocalField = junctionLocalFields[0];
+	const junctionTargetField = junctionTargetFields[0];
+	const targetPKField = targetPKFields[0];
+	const pkValues = collectUniqueValues(rows, localField);
+	if (pkValues.length === 0) {
+		for (const row of rows) row[relName] = [];
+		return;
+	}
+	const junctionFilter = { [junctionLocalField]: { $in: pkValues } };
+	const junctionRows = await junctionTable.findMany({
+		filter: junctionFilter,
+		controls: { $select: [junctionLocalField, junctionTargetField] }
+	});
+	if (junctionRows.length === 0) {
+		for (const row of rows) row[relName] = relation.isArray ? [] : null;
+		return;
+	}
+	const targetFKValues = collectUniqueValues(junctionRows, junctionTargetField);
+	const inFilter = { [targetPKField]: { $in: targetFKValues } };
+	const targetFilter = relQuery.filter ? { $and: [inFilter, relQuery.filter] } : inFilter;
+	const controls = ensureSelectIncludesFields(relQuery.controls, targetPKFields);
+	const targetRows = await targetTable.findMany({
+		filter: targetFilter,
+		controls
+	});
+	const targetIndex = new Map();
+	for (const item of targetRows) targetIndex.set(String(item[targetPKField]), item);
+	const groups = new Map();
+	for (const jRow of junctionRows) {
+		const localKey = String(jRow[junctionLocalField]);
+		const targetKey = String(jRow[junctionTargetField]);
+		const target = targetIndex.get(targetKey);
+		if (!target) continue;
+		let group = groups.get(localKey);
+		if (!group) {
+			group = [];
+			groups.set(localKey, group);
+		}
+		group.push(target);
+	}
+	for (const row of rows) {
+		const key = String(row[localField]);
+		row[relName] = relation.isArray ? groups.get(key) ?? [] : groups.get(key)?.[0] ?? null;
+	}
+}
+async function loadViaCompositeKey(rows, opts) {
+	const { relName, relation, targetTable, relQuery, localPKFields, junctionLocalFields, targetPKFields, junctionTargetFields, junctionTable } = opts;
+	const orFilters = [];
+	for (const row of rows) {
+		const condition = {};
+		let valid = true;
+		for (let i = 0; i < localPKFields.length; i++) {
+			const val = row[localPKFields[i]];
+			if (val === null || val === undefined) {
+				valid = false;
+				break;
+			}
+			condition[junctionLocalFields[i]] = val;
+		}
+		if (valid) orFilters.push(condition);
+	}
+	if (orFilters.length === 0) {
+		for (const row of rows) row[relName] = relation.isArray ? [] : null;
+		return;
+	}
+	const junctionFilter = orFilters.length === 1 ? orFilters[0] : { $or: orFilters };
+	const junctionRows = await junctionTable.findMany({
+		filter: junctionFilter,
+		controls: { $select: [...junctionLocalFields, ...junctionTargetFields] }
+	});
+	if (junctionRows.length === 0) {
+		for (const row of rows) row[relName] = relation.isArray ? [] : null;
+		return;
+	}
+	const targetOrFilters = [];
+	const seenTargets = new Set();
+	for (const jRow of junctionRows) {
+		const key = compositeKey(junctionTargetFields, jRow);
+		if (seenTargets.has(key)) continue;
+		seenTargets.add(key);
+		const condition = {};
+		for (let i = 0; i < junctionTargetFields.length; i++) condition[targetPKFields[i]] = jRow[junctionTargetFields[i]];
+		targetOrFilters.push(condition);
+	}
+	const targetBaseFilter = targetOrFilters.length === 1 ? targetOrFilters[0] : { $or: targetOrFilters };
+	const finalFilter = relQuery.filter ? { $and: [targetBaseFilter, relQuery.filter] } : targetBaseFilter;
+	const targetRows = await targetTable.findMany({
+		filter: finalFilter,
+		controls: relQuery.controls
+	});
+	const targetIndex = new Map();
+	for (const item of targetRows) targetIndex.set(compositeKey(targetPKFields, item), item);
+	const groups = new Map();
+	for (const jRow of junctionRows) {
+		const localKey = compositeKey(junctionLocalFields, jRow);
+		const targetKey = compositeKey(junctionTargetFields, jRow);
+		const target = targetIndex.get(targetKey);
+		if (!target) continue;
+		let group = groups.get(localKey);
+		if (!group) {
+			group = [];
+			groups.set(localKey, group);
+		}
+		group.push(target);
+	}
+	for (const row of rows) {
+		const key = compositeKey(localPKFields, row);
+		row[relName] = relation.isArray ? groups.get(key) ?? [] : groups.get(key)?.[0] ?? null;
+	}
+}
+/**
+* If controls include an array-style $select, ensure the given join fields
+* are present so that FK matching works after the query returns.
+*/ function ensureSelectIncludesFields(controls, fields) {
+	if (!controls) return controls;
+	const sel = controls.$select;
+	if (!Array.isArray(sel)) return controls;
+	const augmented = [...sel];
+	for (const f of fields) if (!augmented.includes(f)) augmented.push(f);
+	return {
+		...controls,
+		$select: augmented
+	};
+}
+function compositeKey(fields, obj) {
+	let key = "";
+	for (let i = 0; i < fields.length; i++) {
+		if (i > 0) key += "\0\0";
+		const v = obj[fields[i]];
+		key += v === null || v === undefined ? "\0" : String(v);
+	}
+	return key;
+}
+/** Collects unique non-null values for a field across rows. */ function collectUniqueValues(rows, field) {
+	const set = new Set();
+	for (const row of rows) {
+		const v = row[field];
+		if (v !== null && v !== undefined) set.add(v);
+	}
+	return [...set];
+}
+/** Assigns related items grouped by FK value (one-to-many). */ function assignGrouped(opts) {
+	const { rows, related, localField, remoteField, relName } = opts;
+	const groups = new Map();
+	for (const item of related) {
+		const key = item[remoteField];
+		let group = groups.get(key);
+		if (!group) {
+			group = [];
+			groups.set(key, group);
+		}
+		group.push(item);
+	}
+	for (const row of rows) row[relName] = groups.get(row[localField]) ?? [];
+}
+/** Assigns related items by FK value (many-to-one / one-to-one). */ function assignSingle(opts) {
+	const { rows, related, localField, remoteField, relName } = opts;
+	const index = new Map();
+	for (const item of related) {
+		const key = item[remoteField];
+		if (!index.has(key)) index.set(key, item);
+	}
+	for (const row of rows) row[relName] = index.get(row[localField]) ?? null;
+}
+/** Batch query for composite FK. */ function queryCompositeFK(rows, opts) {
+	const { localFields, targetFields, targetTable, relQuery } = opts;
+	const seen = new Set();
+	const orFilters = [];
+	for (const row of rows) {
+		const key = compositeKey(localFields, row);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		const condition = {};
+		let valid = true;
+		for (let i = 0; i < localFields.length; i++) {
+			const val = row[localFields[i]];
+			if (val === null || val === undefined) {
+				valid = false;
+				break;
+			}
+			condition[targetFields[i]] = val;
+		}
+		if (valid) orFilters.push(condition);
+	}
+	if (orFilters.length === 0) return Promise.resolve([]);
+	const baseFilter = orFilters.length === 1 ? orFilters[0] : { $or: orFilters };
+	const targetFilter = relQuery.filter ? { $and: [baseFilter, relQuery.filter] } : baseFilter;
+	return targetTable.findMany({
+		filter: targetFilter,
+		controls: relQuery.controls
+	});
+}
+
+//#endregion
+export { loadRelationsImpl };

package/dist/relation-loader-Ggy1ujwR.mjs

@@ -0,0 +1,4 @@
+import "./relation-helpers-DyBIlQnB.mjs";
+import { loadRelationsImpl } from "./relation-loader-Dv7qXYq7.mjs";
+
+export { loadRelationsImpl };

package/dist/shared.cjs

@@ -0,0 +1,13 @@
+const require_validation_utils = require('./validation-utils-DEoCMmEb.cjs');
+
+exports.findFKFieldsPointingTo = require_validation_utils.findFKFieldsPointingTo
+exports.getAnnotationAlias = require_validation_utils.getAnnotationAlias
+exports.getDbTableOwner = require_validation_utils.getDbTableOwner
+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.refActionAnnotation = require_validation_utils.refActionAnnotation
+exports.validateFieldBaseType = require_validation_utils.validateFieldBaseType
+exports.validateQueryScope = require_validation_utils.validateQueryScope
+exports.validateRefArgument = require_validation_utils.validateRefArgument

package/dist/shared.d.ts

@@ -0,0 +1,70 @@
+import { SemanticNode, Token, SemanticStructureNode, AnnotationSpec, AtscriptDoc, TMessages, SemanticPropNode, SemanticInterfaceNode } from '@atscript/core';
+
+/**
+ * Traverse from annotation token → prop → structure → interface
+ * to check if the parent interface has @db.table.
+ */
+declare function getDbTableOwner(token: Token): SemanticNode | undefined;
+/**
+ * Get the parent structure node from an annotation token.
+ */
+declare function getParentStruct(token: Token): SemanticStructureNode | undefined;
+/**
+ * Get the parent interface name (for error messages and cross-type resolution).
+ */
+declare function getParentTypeName(token: Token): string | undefined;
+/**
+ * Validate that an annotation is on a field with the expected base type.
+ */
+declare function validateFieldBaseType(token: Token, doc: AtscriptDoc, annotationName: string, expectedType: string | string[]): TMessages;
+/**
+ * Extract target type name from a navigational field definition.
+ * Unwraps arrays (e.g., `Post[]` → `Post`).
+ */
+declare function getNavTargetTypeName(field: SemanticNode): string | undefined;
+/**
+ * Get the alias argument from an annotation on a field.
+ */
+declare function getAnnotationAlias(prop: SemanticNode, annotationName: string): string | undefined;
+/**
+ * Factory for @db.rel.onDelete / @db.rel.onUpdate — identical validation logic,
+ * only the annotation name and description verb differ.
+ */
+declare function refActionAnnotation(name: 'onDelete' | 'onUpdate'): AnnotationSpec;
+
+/**
+ * Validate a ref annotation argument against the document's type registry.
+ * Returns diagnostic messages for unknown types or fields.
+ */
+declare function validateRefArgument(token: Token, doc: AtscriptDoc, options?: {
+    requireDbTable?: boolean;
+}): TMessages;
+interface TFKFieldMatch {
+    name: string;
+    prop: SemanticPropNode;
+    chainRef: {
+        type: string;
+        field: string;
+    };
+}
+/**
+ * Find all `@db.rel.FK` fields on a type that reference `targetTypeName`.
+ * Resolves `extends` to include inherited fields.
+ */
+declare function findFKFieldsPointingTo(doc: AtscriptDoc, iface: SemanticInterfaceNode | SemanticStructureNode, targetTypeName: string, alias?: string): TFKFieldMatch[];
+/**
+ * Check if a node has any @db.view.* annotation.
+ */
+declare function hasAnyViewAnnotation(node: SemanticNode): boolean;
+/**
+ * Validate that all type refs in a query expression are within the allowed scope.
+ *
+ * @param queryToken - The query arg token (must have .queryNode)
+ * @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
+ */
+declare function validateQueryScope(queryToken: Token, allowedTypes: string[], unqualifiedTarget: string | null, doc: AtscriptDoc): TMessages;
+
+export { findFKFieldsPointingTo, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, refActionAnnotation, validateFieldBaseType, validateQueryScope, validateRefArgument };
+export type { TFKFieldMatch };

package/dist/shared.mjs

@@ -0,0 +1,3 @@
+import { findFKFieldsPointingTo, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, refActionAnnotation, validateFieldBaseType, validateQueryScope, validateRefArgument } from "./validation-utils-DhR_mtKa.mjs";
+
+export { findFKFieldsPointingTo, getAnnotationAlias, getDbTableOwner, getNavTargetTypeName, getParentStruct, getParentTypeName, hasAnyViewAnnotation, refActionAnnotation, validateFieldBaseType, validateQueryScope, validateRefArgument };