appflare 0.0.1

package/react/shared/queryShared.ts

@@ -0,0 +1,169 @@
+import { useEffect, useRef } from "react";
+import { QueryKey } from "@tanstack/react-query";
+
+export type RealtimeMessage<TResult> = {
+	type?: string;
+	data?: TResult[];
+	[key: string]: unknown;
+};
+
+export type HandlerWebsocketOptions<TResult> = {
+	baseUrl?: string;
+	table?: string;
+	handler?: { file: string; name: string };
+	handlerFile?: string;
+	handlerName?: string;
+	where?: Record<string, unknown>;
+	orderBy?: Record<string, unknown>;
+	take?: number;
+	skip?: number;
+	path?: string;
+	protocols?: string | string[];
+	signal?: AbortSignal;
+	websocketImpl?: (url: string, protocols?: string | string[]) => WebSocket;
+	onOpen?: (event: any) => void;
+	onClose?: (event: any) => void;
+	onError?: (event: any) => void;
+	onMessage?: (message: RealtimeMessage<TResult>, raw: any) => void;
+	onData?: (data: TResult[], message: RealtimeMessage<TResult>) => void;
+};
+
+export type HandlerWithRealtime<TArgs, TResult> = {
+	(args: TArgs, init?: RequestInit): Promise<TResult>;
+	websocket?: (
+		args?: TArgs,
+		options?: HandlerWebsocketOptions<TResult>
+	) => WebSocket;
+	schema?: unknown;
+	path?: string;
+};
+
+export type RealtimeHookOptions<TResult> = HandlerWebsocketOptions<TResult> & {
+	enabled?: boolean;
+	replaceData?: boolean;
+};
+
+type RealtimeOptions<TResult> = {
+	enabled: boolean;
+	options: RealtimeHookOptions<TResult>;
+};
+
+type RealtimeSubscriptionParams<TArgs, TResult> = {
+	handler: HandlerWithRealtime<TArgs, TResult>;
+	args?: TArgs;
+	realtime?: boolean | RealtimeHookOptions<TResult>;
+	finalQueryKey: QueryKey;
+	deps?: unknown[];
+	applyIncoming: (
+		data: TResult[] | undefined,
+		message: RealtimeMessage<TResult> | undefined
+	) => void;
+};
+
+export function stableSerialize(value: unknown): string {
+	try {
+		return JSON.stringify(value) ?? "";
+	} catch {
+		return String(value);
+	}
+}
+
+export function buildQueryKey(
+	queryKey: QueryKey | undefined,
+	handler: { path?: string },
+	argsKey: string
+): QueryKey {
+	return queryKey ?? [handler?.path ?? "appflare-handler", argsKey];
+}
+
+export function useRealtimeSubscription<TArgs, TResult>(
+	params: RealtimeSubscriptionParams<TArgs, TResult>
+): WebSocket | null {
+	const { handler, args, realtime, finalQueryKey, deps, applyIncoming } =
+		params;
+	const depsArray = deps;
+	const websocketRef = useRef<WebSocket | null>(null);
+
+	// Track latest realtime options so callbacks stay fresh without forcing reconnects.
+	const latestRealtimeOptionsRef = useRef<
+		RealtimeHookOptions<TResult> | undefined
+	>();
+	const realtimeKey = buildRealtimeKey(realtime);
+	const parsedRealtime = parseRealtimeOptions<TResult>(realtime);
+	latestRealtimeOptionsRef.current = parsedRealtime.options;
+
+	useEffect(() => {
+		const hasWebsocket = typeof handler.websocket === "function";
+		const { enabled, options } = parsedRealtime;
+
+		if (!enabled || !hasWebsocket) {
+			return undefined;
+		}
+
+		const socket = handler.websocket!(args, {
+			...options,
+			onData: (data, message) => {
+				latestRealtimeOptionsRef.current?.onData?.(data, message);
+				if (options.replaceData === false) return;
+				applyIncoming(data, message);
+			},
+			onMessage: (message, raw) => {
+				latestRealtimeOptionsRef.current?.onMessage?.(message, raw);
+				if (
+					options.replaceData === false ||
+					!message ||
+					message.type !== "data" ||
+					!Array.isArray((message as any).data)
+				) {
+					return;
+				}
+				applyIncoming((message as any).data, message as any);
+			},
+		});
+
+		websocketRef.current = socket;
+
+		return () => {
+			try {
+				socket.close(1000, "cleanup");
+			} catch {
+				// ignore
+			}
+		};
+	}, [handler, finalQueryKey, realtimeKey, applyIncoming, ...depsArray]);
+
+	return websocketRef.current;
+}
+
+function parseRealtimeOptions<TResult>(
+	realtime?: boolean | RealtimeHookOptions<TResult>
+): RealtimeOptions<TResult> {
+	const options =
+		typeof realtime === "object"
+			? (realtime as RealtimeHookOptions<TResult>)
+			: ({} as RealtimeHookOptions<TResult>);
+
+	const enabled =
+		realtime === true ||
+		(typeof realtime === "object" && options.enabled !== false);
+
+	return { enabled, options };
+}
+
+function buildRealtimeKey<TResult>(
+	realtime?: boolean | RealtimeHookOptions<TResult>
+): string {
+	if (realtime === true) return "true";
+	if (!realtime) return "false";
+	const {
+		onOpen,
+		onClose,
+		onError,
+		onMessage,
+		onData,
+		websocketImpl,
+		signal,
+		...rest
+	} = realtime;
+	return stableSerialize(rest);
+}

package/server/README.md

@@ -0,0 +1,153 @@
+# Appflare Server (MongoDB) Module
+
+Appflare's server package provides a small MongoDB data layer with typed helpers for querying, writing, and populating referenced documents inferred from your schema. The entrypoint is `createMongoDbContext`, which builds per-table clients that expose a Prisma-like API (`findMany`, `create`, `update`, `delete`, etc.).
+
+## Directory Map
+
+- `db.ts`: Public exports for the module (re-exports context and types).
+- `database/context.ts`: Builds the MongoDB context and per-table client facade.
+- `database/builders.ts`: Low-level delete/update/patch builders used by the context.
+- `database/query-builder.ts`: Chainable query API (`where`, `sort`, `limit`, `offset`, `select`, `populate`, `find`, `findOne`).
+- `database/query-utils.ts`: Projection and sort normalization helpers.
+- `database/populate.ts`: Populates referenced documents via forward or reverse lookups.
+- `types/`: Shared TypeScript types for docs, queries, and table clients. `schema-refs.ts` derives reference metadata from Zod schemas.
+- `utils/id-utils.ts`: Id normalization helpers (string/ObjectId) and ref field coercion.
+
+## Quick Start
+
+```ts
+import { MongoClient } from "mongodb";
+import { z } from "zod";
+import { createMongoDbContext } from "@appflare/server/db";
+
+const client = await MongoClient.connect(process.env.MONGO_URL!);
+const db = client.db("appflare-demo");
+
+const schema = {
+	users: z.object({
+		_id: z.string(),
+		_creationTime: z.number(),
+		email: z.string(),
+		// ref:tickets tells the system this field references the tickets table
+		tickets: z.array(z.string().describe("ref:tickets")).optional(),
+	}),
+	tickets: z.object({
+		_id: z.string(),
+		_creationTime: z.number(),
+		title: z.string(),
+		user: z.string().describe("ref:users"),
+	}),
+} as const;
+
+const ctx = createMongoDbContext({ db, schema });
+
+// typed table clients
+const users = ctx.users;
+const tickets = ctx.tickets;
+
+// create
+const user = await users.create({ data: { email: "a@demo.com", tickets: [] } });
+
+// query with select + populate
+const withTickets = await users.findUnique({
+	where: { _id: user._id },
+	select: ["_id", "email"],
+	include: ["tickets"],
+});
+
+// update many
+await tickets.updateMany({
+	where: { user: user._id },
+	data: { title: "Updated" },
+});
+```
+
+## Core Concepts
+
+- **Context**: `createMongoDbContext` wires a MongoDB `Db`, a Zod schema map, and optional collection naming into typed table clients. Each table client wraps insert/update/delete/query logic and handles reference normalization.
+- **Reference inference**: `buildSchemaRefMap` inspects Zod field descriptions that start with `ref:` to discover forward references. This enables automatic population and reference normalization.
+- **Id normalization**: `normalizeIdValue` coerces valid string ids into `ObjectId` for filters and writes; `stringifyIdField` converts `_id` back to hex string on reads. Ref fields are normalized similarly via `normalizeRefFields`/`stringifyRefFields`.
+- **Populate**: `populate()` on a query triggers `applyPopulate`, which performs `$lookup` pipelines. Forward populate (table stores the ref) is preferred; if absent, reverse populate finds documents that reference the current table (e.g., `tickets.user -> users._id`).
+- **Typed chaining**: Query builders keep result types in sync when `select` or `populate` is used. Update/delete builders offer a fluent `where(...).set(...).exec()` style when called with one argument.
+
+## API Reference
+
+### Context Factory
+
+- `createMongoDbContext(options)`:
+  - `db`: MongoDB `Db` instance.
+  - `schema`: Record of Zod schemas for each table (must include `_id` and `_creationTime`).
+  - `collectionName?`: Optional mapper `(tableName) => collectionName`.
+  - Returns `MongoDbContext` — a map of table names to `AppflareTableClient`.
+
+### Table Client (`AppflareTableClient`)
+
+Methods match Prisma-like signatures:
+
+- `findMany({ where?, orderBy?, skip?, take?, select?, include? })`
+- `findFirst({ ... })`
+- `findUnique({ where, select?, include? })`
+- `create({ data, select?, include? })`
+- `update({ where, data, select?, include? })`
+- `updateMany({ where?, data })`
+- `delete({ where, select?, include? })`
+- `deleteMany({ where? })`
+- `count({ where? })`
+
+`select` accepts an array or object of field keys; `include` accepts populatable relation keys. Both adjust the result type.
+
+### Query Builder
+
+Produced via `ctx.<table>.findMany()` under the hood and exposed through `core.query()`:
+
+- `where(filter)`: chainable; multiple calls AND together.
+- `sort(sortSpec)`: accepts object or tuples; `desc` maps to `-1` for Mongo.
+- `limit(n)` / `offset(n)`
+- `select(...keys)`
+- `populate(key | keys[])`
+- `find()` returns an array; `findOne()` returns first or `null`.
+
+### Update/Patch/Delete Builders
+
+When `update`, `patch`, or `delete` are called with only the table name, they return a builder:
+
+```ts
+await ctx.users
+	.update("users")
+	.where({ email: /@demo/ })
+	.set({ email: "x" })
+	.exec();
+await ctx.users.delete("users").where("someId").exec();
+```
+
+`patch` is an alias of `update`.
+
+### Populate Behavior
+
+- Forward populate uses `$lookup` from the current collection to the referenced table (`localField` = ref field, `foreignField` = `_id`). Arrays are matched element-wise.
+- Reverse populate triggers when the current table lacks the ref but others point to it. It looks up documents in the referencing table and groups them by current `_id`.
+- Populate respects `select`: projection is expanded to include ref keys so lookups have ids even when omitted from the requested fields.
+
+### Utilities
+
+- `buildProjection(keys)`: builds a Mongo projection, ensuring `_id` and `_creationTime` are excluded when not selected.
+- `normalizeSort(sort)`: converts sort objects/tuples to Mongo format.
+- `normalizeIdFilter`, `normalizeRefFields`, `stringifyIdField`: ensure consistent id types across reads/writes.
+
+## Usage Notes
+
+- Always include `_id` and `_creationTime` in your Zod schema; they are used by the helpers and default projections.
+- Reference discovery relies on `describe("ref:<table>")` on string fields (optionally inside arrays/optional/nullable/default wrappers).
+- All writes normalize ids to `ObjectId` when valid; reads stringify `_id` for consumer-friendly output.
+- `findUnique` requires a `where` clause; `findFirst` defaults `take` to `1` when unset.
+
+## Extending
+
+- Supply a custom `collectionName` to map logical table names to physical collections.
+- Customize partial normalization by passing `normalizePartial` to `createUpdateBuilder`/`createPatchBuilder` if you wrap the builders yourself.
+
+## Related Files
+
+- Types: `types/types.ts`, `types/schema-refs.ts`
+- Database helpers: `database/context.ts`, `database/query-builder.ts`, `database/builders.ts`, `database/populate.ts`, `database/query-utils.ts`
+- Id helpers: `utils/id-utils.ts`

package/server/database/builders.ts

@@ -0,0 +1,83 @@
+import type { Collection, Document } from "mongodb";
+import { isIdValue, normalizeIdFilter, toMongoFilter } from "../utils/id-utils";
+import type {
+	MongoDbDeleteBuilder,
+	MongoDbPatchBuilder,
+	MongoDbUpdateBuilder,
+} from "../types/types";
+
+export function createDeleteBuilder(params: {
+	table: string;
+	getCollection: (table: string) => Collection<Document>;
+}): MongoDbDeleteBuilder<any, any> {
+	return {
+		where(where) {
+			const filter = normalizeIdFilter(toMongoFilter(where));
+			return {
+				exec: async () => {
+					const coll = params.getCollection(params.table);
+					if (isIdValue(where)) {
+						await coll.deleteOne(filter as any);
+					} else {
+						await coll.deleteMany(filter as any);
+					}
+				},
+			};
+		},
+	};
+}
+
+export function createUpdateBuilder(params: {
+	table: string;
+	getCollection: (table: string) => Collection<Document>;
+	normalizePartial?: (
+		partial: Record<string, unknown>
+	) => Record<string, unknown>;
+}): MongoDbUpdateBuilder<any, any> {
+	return {
+		where(where) {
+			const filter = normalizeIdFilter(toMongoFilter(where));
+			return {
+				set(partial) {
+					const normalized = params.normalizePartial
+						? params.normalizePartial(partial as any)
+						: partial;
+					return {
+						exec: async () => {
+							const coll = params.getCollection(params.table);
+							const update = { $set: normalized as any };
+							if (isIdValue(where)) {
+								await coll.updateOne(filter as any, update);
+							} else {
+								await coll.updateMany(filter as any, update);
+							}
+						},
+					};
+				},
+				exec: async (partial) => {
+					if (!partial) throw new Error("update requires a partial to set");
+					const normalized = params.normalizePartial
+						? params.normalizePartial(partial as any)
+						: partial;
+					const coll = params.getCollection(params.table);
+					const update = { $set: normalized as any };
+					if (isIdValue(where)) {
+						await coll.updateOne(filter as any, update);
+					} else {
+						await coll.updateMany(filter as any, update);
+					}
+				},
+			};
+		},
+	};
+}
+
+export function createPatchBuilder(params: {
+	table: string;
+	getCollection: (table: string) => Collection<Document>;
+	normalizePartial?: (
+		partial: Record<string, unknown>
+	) => Record<string, unknown>;
+}): MongoDbPatchBuilder<any, any> {
+	return createUpdateBuilder(params) as MongoDbPatchBuilder<any, any>;
+}

package/server/database/context.ts

@@ -0,0 +1,265 @@
+import type { Collection, Document } from "mongodb";
+import { ObjectId } from "mongodb";
+import {
+	createDeleteBuilder,
+	createPatchBuilder,
+	createUpdateBuilder,
+} from "./builders";
+import { createQueryBuilder } from "./query-builder";
+import {
+	isIdValue,
+	normalizeIdFilter,
+	normalizeRefFields,
+	toMongoFilter,
+} from "../utils/id-utils";
+import { buildSchemaRefMap } from "../types/schema-refs";
+import type {
+	CreateMongoDbContextOptions,
+	MongoDbCoreContext,
+	MongoDbContext,
+	MongoDbQuery,
+	AppflareTableClient,
+	TableDocBase,
+} from "../types/types";
+
+export function createMongoDbContext<
+	TTableNames extends string,
+	TTableDocMap extends Record<TTableNames, TableDocBase>,
+>(
+	options: CreateMongoDbContextOptions<TTableNames>
+): MongoDbContext<TTableNames, TTableDocMap> {
+	const collectionName = options.collectionName ?? ((t) => t);
+	const collections = new Map<string, Collection<Document>>();
+	const refs = buildSchemaRefMap(options.schema);
+	const tableNames = Object.keys(options.schema) as TTableNames[];
+
+	const getCollection = (table: string): Collection<Document> => {
+		const key = collectionName(table as any);
+		const existing = collections.get(key);
+		if (existing) return existing;
+		const created = options.db.collection(key);
+		collections.set(key, created);
+		return created;
+	};
+
+	const core: MongoDbCoreContext<TTableNames, TTableDocMap> = {
+		query: (table) =>
+			createQueryBuilder<TTableNames, TTableDocMap, any>({
+				table: table as any,
+				getCollection,
+				refs,
+			}),
+		insert: async (table, value) => {
+			const coll = getCollection(table as string);
+			const objectId = new ObjectId();
+			const normalized = normalizeRefFields(
+				table as string,
+				value as Record<string, unknown>,
+				refs
+			);
+			const doc = {
+				...normalized,
+				_id: objectId,
+				_creationTime: Date.now(),
+			} as unknown as Document;
+
+			await coll.insertOne(doc);
+			return objectId.toHexString() as any;
+		},
+		update: ((table: any, where?: any, partial?: any) => {
+			if (arguments.length === 1) {
+				return createUpdateBuilder({
+					table,
+					getCollection,
+					normalizePartial: (p) =>
+						normalizeRefFields(table as string, p as any, refs),
+				});
+			}
+			const coll = getCollection(table as string);
+			const filter = normalizeIdFilter(toMongoFilter(where));
+			const update = {
+				$set: normalizeRefFields(table as string, partial as any, refs) as any,
+			};
+			if (isIdValue(where)) {
+				return coll.updateOne(filter, update).then(() => {});
+			}
+			return coll.updateMany(filter, update).then(() => {});
+		}) as any,
+		patch: ((table: any, where?: any, partial?: any) => {
+			if (arguments.length === 1) {
+				return createPatchBuilder({
+					table,
+					getCollection,
+					normalizePartial: (p) =>
+						normalizeRefFields(table as string, p as any, refs),
+				});
+			}
+			const coll = getCollection(table as string);
+			const filter = normalizeIdFilter(toMongoFilter(where));
+			const update = {
+				$set: normalizeRefFields(table as string, partial as any, refs) as any,
+			};
+			if (isIdValue(where)) {
+				return coll.updateOne(filter, update).then(() => {});
+			}
+			return coll.updateMany(filter, update).then(() => {});
+		}) as any,
+		delete: ((table: any, where?: any) => {
+			if (arguments.length === 1) {
+				return createDeleteBuilder({
+					table,
+					getCollection,
+				});
+			}
+			const coll = getCollection(table as string);
+			const filter = normalizeIdFilter(toMongoFilter(where));
+			if (isIdValue(where)) {
+				return coll.deleteOne(filter).then(() => {});
+			}
+			return coll.deleteMany(filter).then(() => {});
+		}) as any,
+	};
+
+	const ctx = {} as MongoDbContext<TTableNames, TTableDocMap>;
+
+	for (const table of tableNames) {
+		(ctx as any)[table] = createAppflareTableClient({
+			table: table as TTableNames,
+			core,
+			refs,
+			getCollection,
+		});
+	}
+
+	return ctx;
+}
+
+function toKeyList(arg: unknown): string[] | undefined {
+	if (!arg) return undefined;
+	if (Array.isArray(arg)) return arg.map((k) => String(k));
+	if (typeof arg === "object") {
+		return Object.entries(arg as Record<string, unknown>)
+			.filter(([, v]) => Boolean(v))
+			.map(([k]) => k);
+	}
+	return undefined;
+}
+
+function createAppflareTableClient<
+	TTableNames extends string,
+	TTableDocMap extends Record<TTableNames, TableDocBase>,
+	TableName extends TTableNames,
+>(params: {
+	table: TableName;
+	core: MongoDbCoreContext<TTableNames, TTableDocMap>;
+	refs: ReturnType<typeof buildSchemaRefMap>;
+	getCollection: (table: string) => Collection<Document>;
+}): AppflareTableClient<TableName, TTableDocMap> {
+	const selectKeys = (select: unknown) => toKeyList(select);
+	const includeKeys = (include: unknown) => toKeyList(include);
+
+	const buildQuery = (args?: {
+		where?: any;
+		orderBy?: any;
+		skip?: number;
+		take?: number;
+		select?: unknown;
+		include?: unknown;
+	}) => {
+		let q: MongoDbQuery<TableName, TTableDocMap, any> = params.core.query(
+			params.table as any
+		) as any;
+		if (args?.where) q = q.where(args.where as any);
+		if (args?.orderBy) q = q.sort(args.orderBy as any);
+		if (args?.skip !== undefined) q = q.offset(args.skip);
+		if (args?.take !== undefined) q = q.limit(args.take);
+		const s = selectKeys(args?.select);
+		if (s?.length) q = q.select(s as any);
+		const i = includeKeys(args?.include);
+		if (i?.length) q = q.populate(i as any);
+		return q;
+	};
+
+	const fetchOne = async (args: {
+		where: any;
+		select?: unknown;
+		include?: unknown;
+	}) => {
+		const q = buildQuery({ ...args, take: 1 });
+		return q.findOne();
+	};
+
+	return {
+		findMany: async (args) => buildQuery(args as any).find() as any,
+		findFirst: async (args) =>
+			buildQuery({
+				...(args as any),
+				take: (args as any)?.take ?? 1,
+			}).findOne() as any,
+		findUnique: async (args) => {
+			if (!args?.where) throw new Error("findUnique requires a where clause");
+			return fetchOne(args as any) as any;
+		},
+		create: async (args) => {
+			const id = await params.core.insert(
+				params.table as any,
+				args.data as any
+			);
+			const created = await fetchOne({
+				where: { _id: id } as any,
+				select: (args as any)?.select,
+				include: (args as any)?.include,
+			});
+			return (created ?? {
+				_id: id,
+				_creationTime: Date.now(),
+				...args.data,
+			}) as any;
+		},
+		update: async (args) => {
+			await params.core.update(
+				params.table as any,
+				args.where as any,
+				args.data as any
+			);
+			return fetchOne({
+				where: args.where as any,
+				select: (args as any)?.select,
+				include: (args as any)?.include,
+			}) as any;
+		},
+		updateMany: async (args) => {
+			const coll = params.getCollection(params.table as string);
+			const filter = normalizeIdFilter(toMongoFilter(args.where ?? {}));
+			const normalized = normalizeRefFields(
+				params.table as string,
+				args.data as any,
+				params.refs
+			);
+			const result = await coll.updateMany(filter as any, {
+				$set: normalized as any,
+			});
+			return { count: result.modifiedCount ?? 0 };
+		},
+		delete: async (args) => {
+			const existing = await fetchOne({
+				where: args.where as any,
+				select: (args as any)?.select,
+				include: (args as any)?.include,
+			});
+			await params.core.delete(params.table as any, args.where as any);
+			return existing as any;
+		},
+		deleteMany: async (args) => {
+			const coll = params.getCollection(params.table as string);
+			const filter = normalizeIdFilter(toMongoFilter(args?.where ?? {}));
+			const result = await coll.deleteMany(filter as any);
+			return { count: result.deletedCount ?? 0 };
+		},
+		count: async (args) => {
+			const coll = params.getCollection(params.table as string);
+			const filter = normalizeIdFilter(toMongoFilter(args?.where ?? {}));
+			return coll.countDocuments(filter ?? {});
+		},
+	};
+}