appflare 0.0.1

package/server/database/populate.ts

@@ -0,0 +1,160 @@
+import type { Collection, Document } from "mongodb";
+import { ObjectId } from "mongodb";
+import { normalizeIdValue, stringifyIdField } from "../utils/id-utils";
+import type { SchemaRefMap } from "../types/types";
+
+export async function applyPopulate(params: {
+	docs: Array<Record<string, unknown>>;
+	currentTable: string;
+	populateKeys: string[];
+	selectedKeys: string[] | undefined;
+	refs: SchemaRefMap;
+	getCollection: (table: string) => Collection<Document>;
+}) {
+	const tableRefs = params.refs.get(params.currentTable) ?? new Map();
+
+	const ensureStringId = (val: unknown): string | null => {
+		if (!val) return null;
+		if (typeof val === "string") return val;
+		if (val instanceof ObjectId) return val.toHexString();
+		if (typeof val === "object" && "_id" in (val as any)) {
+			const maybeId = (val as any)._id;
+			if (typeof maybeId === "string") return maybeId;
+			if (maybeId instanceof ObjectId) return maybeId.toHexString();
+		}
+		return null;
+	};
+
+	const docIds = params.docs
+		.map((doc) => {
+			const id = ensureStringId(doc._id);
+			return id ? normalizeIdValue(id) : null;
+		})
+		.filter((v): v is string | ObjectId => Boolean(v));
+
+	if (docIds.length === 0) return;
+
+	// Build reverse ref lookup so populate can work even when the current table
+	// doesn't store the forward reference (e.g., populate tickets on users by
+	// matching tickets.user -> users._id).
+	const reverseRefs = new Map<string, { table: string; field: string }[]>();
+	for (const [table, refs] of params.refs.entries()) {
+		for (const [field, refTable] of refs.entries()) {
+			const list = reverseRefs.get(refTable) ?? [];
+			list.push({ table, field });
+			reverseRefs.set(refTable, list);
+		}
+	}
+
+	const buildLookupMap = (rows: Array<Record<string, unknown>>) => {
+		const byId = new Map<string, Record<string, unknown>[]>();
+		for (const row of rows) {
+			const id = ensureStringId(row._id);
+			if (!id) continue;
+			const items = Array.isArray((row as any).__pop)
+				? ((row as any).__pop as Array<Record<string, unknown>>)
+				: [];
+			items.forEach(stringifyIdField);
+			byId.set(id, items);
+		}
+		return byId;
+	};
+
+	for (const key of params.populateKeys) {
+		const forwardTarget = tableRefs.get(key);
+		const backwardCandidates = reverseRefs.get(params.currentTable) ?? [];
+		const backward = backwardCandidates.find((c) => c.table === key);
+
+		// Prefer forward populate via $lookup when the table carries the ref.
+		if (forwardTarget) {
+			const hasForwardValues = params.docs.some((doc) => {
+				const value = doc[key];
+				return Array.isArray(value)
+					? value.length > 0
+					: value !== undefined && value !== null;
+			});
+
+			if (hasForwardValues) {
+				const coll = params.getCollection(params.currentTable);
+				const pipeline = [
+					{ $match: { _id: { $in: docIds } } },
+					{
+						$lookup: {
+							from: forwardTarget,
+							localField: key,
+							foreignField: "_id",
+							as: "__pop",
+						},
+					},
+					{ $project: { _id: 1, __pop: 1 } },
+				];
+
+				const populated = (await coll
+					.aggregate(pipeline as any)
+					.toArray()) as Array<Record<string, unknown>>;
+
+				const byId = buildLookupMap(populated);
+
+				for (const doc of params.docs) {
+					const docId = ensureStringId(doc._id);
+					if (!docId) continue;
+					const populatedDocs = byId.get(docId) ?? [];
+					const currentValue = doc[key];
+
+					if (Array.isArray(currentValue)) {
+						const byRelId = new Map<string, Record<string, unknown>>();
+						for (const rel of populatedDocs) {
+							const relId = ensureStringId(rel._id);
+							if (relId) byRelId.set(relId, rel);
+						}
+						doc[key] = currentValue
+							.map((v) => {
+								const relId = ensureStringId(v);
+								return relId ? (byRelId.get(relId) ?? null) : null;
+							})
+							.filter((v): v is Record<string, unknown> => Boolean(v));
+						continue;
+					}
+
+					const relId = ensureStringId(currentValue);
+					doc[key] = relId
+						? (populatedDocs.find((v) => ensureStringId(v._id) === relId) ??
+							currentValue)
+						: (populatedDocs[0] ?? currentValue);
+				}
+
+				continue;
+			}
+
+			if (!backward) continue;
+		}
+
+		// Backward populate: find docs in another table that reference this table's _id.
+		if (backward) {
+			const coll = params.getCollection(params.currentTable);
+			const pipeline = [
+				{ $match: { _id: { $in: docIds } } },
+				{
+					$lookup: {
+						from: backward.table,
+						localField: "_id",
+						foreignField: backward.field,
+						as: "__pop",
+					},
+				},
+				{ $project: { _id: 1, __pop: 1 } },
+			];
+
+			const populated = (await coll
+				.aggregate(pipeline as any)
+				.toArray()) as Array<Record<string, unknown>>;
+
+			const grouped = buildLookupMap(populated);
+			for (const doc of params.docs) {
+				const id = ensureStringId(doc._id);
+				if (!id) continue;
+				doc[key] = grouped.get(id) ?? [];
+			}
+		}
+	}
+}

package/server/database/query-builder.ts

@@ -0,0 +1,101 @@
+import type { Collection, Document, Filter, FindOptions, Sort } from "mongodb";
+import { applyPopulate } from "./populate";
+import { normalizeIdFilter, stringifyIdField } from "../utils/id-utils";
+import type { MongoDbQuery, SchemaRefMap } from "../types/types";
+import { buildProjection, normalizeSort } from "./query-utils";
+
+export function createQueryBuilder<
+	TTableNames extends string,
+	TTableDocMap extends Record<TTableNames, any>,
+	TableName extends TTableNames,
+>(params: {
+	table: TableName;
+	getCollection: (table: string) => Collection<Document>;
+	refs: SchemaRefMap;
+}): MongoDbQuery<TableName, TTableDocMap, TTableDocMap[TableName]> {
+	let filter: Filter<Document> | undefined;
+	let sort: Sort | undefined;
+	let limit: number | undefined;
+	let offset: number | undefined;
+	let selectedKeys: string[] | undefined;
+	let populateKeys: string[] = [];
+
+	const api: MongoDbQuery<any, any, any> = {
+		where(next) {
+			const nextFilter = next as unknown as Filter<Document>;
+			if (!filter) {
+				filter = nextFilter;
+			} else {
+				filter = { $and: [filter as any, nextFilter as any] } as any;
+			}
+			return api;
+		},
+		sort(next) {
+			sort = normalizeSort(next as any);
+			return api;
+		},
+		limit(n) {
+			limit = n;
+			return api;
+		},
+		offset(n) {
+			offset = n;
+			return api;
+		},
+		select(...args) {
+			const keys = Array.isArray(args[0])
+				? (args[0] as any[])
+				: (args as any[]);
+			selectedKeys = keys.map(String);
+			return api;
+		},
+		populate(arg: any) {
+			const keys = Array.isArray(arg) ? arg : [arg];
+			for (const k of keys) {
+				const ks = String(k);
+				if (!populateKeys.includes(ks)) populateKeys.push(ks);
+			}
+			return api;
+		},
+		async find() {
+			const coll = params.getCollection(params.table as string);
+			const options: FindOptions = {};
+			if (selectedKeys) {
+				// Ensure referenced ids are available for populate even when the caller selected a subset.
+				const projectionKeys = Array.from(
+					new Set([...selectedKeys, ...populateKeys])
+				);
+				options.projection = buildProjection(projectionKeys);
+			}
+			const normalizedFilter = normalizeIdFilter(filter);
+			let cursor = coll.find(normalizedFilter ?? ({} as any), options);
+			if (sort) cursor = cursor.sort(sort);
+			if (offset !== undefined) cursor = cursor.skip(offset);
+			if (limit !== undefined) cursor = cursor.limit(limit);
+			const docs = (await cursor.toArray()) as Array<Record<string, unknown>>;
+			docs.forEach(stringifyIdField);
+
+			if (populateKeys.length > 0) {
+				await applyPopulate({
+					docs,
+					currentTable: params.table as string,
+					populateKeys,
+					selectedKeys,
+					refs: params.refs,
+					getCollection: params.getCollection,
+				});
+			}
+
+			return docs as any;
+		},
+		async findOne() {
+			if (limit === undefined || limit > 1) {
+				limit = 1;
+			}
+			const result = await api.find();
+			return (result[0] ?? null) as any;
+		},
+	};
+
+	return api as any;
+}

package/server/database/query-utils.ts

@@ -0,0 +1,25 @@
+import type { Sort } from "mongodb";
+import type { QuerySort } from "../types/types";
+
+export function buildProjection(keys: string[]): Record<string, 0 | 1> {
+	const projection: Record<string, 0 | 1> = {};
+	for (const k of keys) projection[k] = 1;
+
+	// Mongo includes _id by default; keep runtime aligned with schema-types `select()`.
+	if (!keys.includes("_id")) projection._id = 0;
+	if (!keys.includes("_creationTime")) projection._creationTime = 0;
+	return projection;
+}
+
+export function normalizeSort(sort: QuerySort<string>): Sort {
+	if (Array.isArray(sort)) {
+		return Object.fromEntries(
+			sort.map(([k, dir]) => [k, dir === "desc" ? -1 : 1])
+		);
+	}
+	const out: Record<string, 1 | -1> = {};
+	for (const [k, v] of Object.entries(sort ?? {})) {
+		out[k] = v === "desc" ? -1 : 1;
+	}
+	return out;
+}

package/server/db.ts

@@ -0,0 +1,2 @@
+export * from "./database/context";
+export * from "./types/types";

package/server/types/schema-refs.ts

@@ -0,0 +1,66 @@
+import type { AnyZod, SchemaRefMap } from "./types";
+
+export function buildSchemaRefMap(
+	schema: Record<string, AnyZod>
+): SchemaRefMap {
+	const result: SchemaRefMap = new Map();
+	for (const [tableName, validator] of Object.entries(schema)) {
+		const tableRefs = new Map<string, string>();
+		const shape = getZodObjectShape(validator);
+		for (const [field, fieldSchema] of Object.entries(shape)) {
+			const ref = extractRefTableName(fieldSchema);
+			if (ref) tableRefs.set(field, ref);
+		}
+		result.set(tableName, tableRefs);
+	}
+	return result;
+}
+
+function extractRefTableName(schema: AnyZod): string | null {
+	if (!schema) return null;
+	const def = schema?._def;
+	const typeName: string | undefined = def?.typeName ?? def?.type;
+
+	if (typeName === "ZodOptional" || typeName === "optional") {
+		return extractRefTableName(
+			def?.innerType ?? def?.schema ?? schema?._def?.innerType
+		);
+	}
+	if (typeName === "ZodNullable" || typeName === "nullable") {
+		return extractRefTableName(def?.innerType ?? def?.schema);
+	}
+	if (typeName === "ZodDefault" || typeName === "default") {
+		return extractRefTableName(def?.innerType ?? def?.schema);
+	}
+	if (typeName === "ZodArray" || typeName === "array") {
+		return extractRefTableName(def?.element ?? def?.innerType ?? def?.type);
+	}
+	if (typeName === "ZodString" || typeName === "string") {
+		const description: string | undefined =
+			schema?.description ?? def?.description;
+		if (typeof description === "string" && description.startsWith("ref:")) {
+			return description.slice("ref:".length);
+		}
+		return null;
+	}
+
+	return null;
+}
+
+function getZodObjectShape(schema: AnyZod): Record<string, AnyZod> {
+	if (!schema || typeof schema !== "object") {
+		throw new Error(`Schema table is not an object`);
+	}
+
+	const def = schema?._def;
+	if (def?.typeName === "ZodObject" || def?.type === "object") {
+		const shape = def.shape;
+		if (typeof shape === "function") return shape();
+		if (shape && typeof shape === "object") return shape;
+	}
+
+	if (typeof schema.shape === "function") return schema.shape();
+	if (schema.shape && typeof schema.shape === "object") return schema.shape;
+
+	throw new Error(`Table schema is not a Zod object`);
+}