appflare 0.0.1

package/cli/generators/generate-api-client/index.ts

@@ -0,0 +1,529 @@
+import {
+	DiscoveredHandler,
+	groupBy,
+	pascalCase,
+	toImportPathFromGeneratedSrc,
+} from "../../utils/utils";
+import {
+	generateMutationsClientLines,
+	generateQueriesClientLines,
+} from "./client";
+import {
+	generateMutationsTypeLines,
+	generateQueriesTypeLines,
+	generateTypeBlocks,
+} from "./types";
+
+const HEADER_TEMPLATE = `/* eslint-disable */
+/**
+ * This file is auto-generated by appflare/handler-build.ts.
+ * Do not edit directly.
+ */
+
+import fetch from "better-fetch";
+import { z } from "zod";
+
+import type {
+	AnyValidator,
+	InferQueryArgs,
+	MutationDefinition,
+	QueryArgsShape,
+	QueryDefinition,
+} from "./schema-types";
+
+`;
+
+const TYPE_DEFINITIONS_TEMPLATE = `
+type AnyArgsShape = Record<string, AnyValidator>;
+
+type AnyHandlerDefinition = QueryDefinition<AnyArgsShape, unknown> | MutationDefinition<AnyArgsShape, unknown>;
+
+type Simplify<T> = { [K in keyof T]: T[K] };
+
+type OptionalKeys<TArgs extends QueryArgsShape> = {
+	[K in keyof TArgs]: TArgs[K] extends z.ZodOptional<any> | z.ZodDefault<any> ? K : never;
+}[keyof TArgs];
+
+type RequiredKeys<TArgs extends QueryArgsShape> = Exclude<keyof TArgs, OptionalKeys<TArgs>>;
+
+type HandlerArgsFromShape<TArgs extends QueryArgsShape> = Simplify<
+	Partial<Pick<InferQueryArgs<TArgs>, OptionalKeys<TArgs>>> &
+		Pick<InferQueryArgs<TArgs>, RequiredKeys<TArgs>>
+>;
+
+type HandlerArgs<THandler extends AnyHandlerDefinition> =
+	THandler extends { args: infer TArgs extends QueryArgsShape }
+		? HandlerArgsFromShape<TArgs>
+		: never;
+
+type HandlerResult<THandler extends AnyHandlerDefinition> = THandler extends {
+	handler: (...args: any[]) => Promise<infer TResult>;
+}
+	? TResult
+	: never;
+
+type HandlerInvoker<TArgs, TResult> = (args: TArgs, init?: RequestInit) => Promise<TResult>;
+
+type HandlerArgsShape<THandler extends AnyHandlerDefinition> =
+	THandler extends { args: infer TArgs extends QueryArgsShape }
+		? TArgs
+		: never;
+
+type HandlerSchemaFromShape<TArgs extends QueryArgsShape> = z.ZodObject<{
+	[K in keyof TArgs]: z.ZodType<InferQueryArgs<TArgs>[K]>;
+}>;
+
+type HandlerSchema<THandler extends AnyHandlerDefinition> = HandlerSchemaFromShape<
+	HandlerArgsShape<THandler>
+>;
+
+type WebSocketFactory = (url: string, protocols?: string | string[]) => WebSocket;
+
+export type RealtimeMessage<TResult> = {
+	type?: string;
+	data?: TResult[];
+	table?: string;
+	where?: unknown;
+	[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?: WebSocketFactory;
+	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;
+};
+
+type HandlerMetadata<THandler extends AnyHandlerDefinition> = {
+	schema: HandlerSchema<THandler>;
+	websocket: HandlerWebsocket<
+		HandlerArgs<THandler>,
+		HandlerResult<THandler>
+	>;
+	path: string;
+};
+
+export type HandlerWebsocket<TArgs, TResult> = (
+	args?: TArgs,
+	options?: HandlerWebsocketOptions<TResult>
+) => WebSocket;
+
+export type AppflareHandler<THandler extends AnyHandlerDefinition> = HandlerInvoker<
+	HandlerArgs<THandler>,
+	HandlerResult<THandler>
+> &
+	HandlerMetadata<THandler>;
+
+type RequestExecutor = (
+	input: RequestInfo | URL,
+	init?: RequestInit
+) => Promise<Response>;
+
+const defaultFetcher: RequestExecutor = (input, init) => fetch(input, init);
+
+const defaultWebSocketFactory: WebSocketFactory = (url, protocols) => {
+	if (typeof WebSocket === "undefined") {
+		throw new Error(
+			"WebSocket is not available in this environment. Provide options.realtime.websocketImpl to create websockets."
+		);
+	}
+	return new WebSocket(url, protocols);
+};
+
+type ResolvedRealtimeConfig = {
+	baseUrl?: string;
+	path: string;
+	websocketImpl?: WebSocketFactory;
+};
+
+type RealtimeConfig = {
+	baseUrl?: string;
+	path?: string;
+	websocketImpl?: WebSocketFactory;
+};
+
+`;
+
+const CLIENT_TYPES_TEMPLATE = `
+export type QueriesClient = {{queriesTypeDef}};
+
+export type MutationsClient = {{mutationsTypeDef}};
+
+export type AppflareApiClient = {
+	queries: QueriesClient;
+	mutations: MutationsClient;
+};
+
+export type AppflareApiOptions = {
+	baseUrl?: string;
+	fetcher?: RequestExecutor;
+	realtime?: RealtimeConfig;
+};
+
+export function createAppflareApi(options: AppflareApiOptions = {}): AppflareApiClient {
+	const baseUrl = normalizeBaseUrl(options.baseUrl);
+	const request = options.fetcher ?? defaultFetcher;
+	const realtime = resolveRealtimeConfig(baseUrl, options.realtime);
+	const queries: QueriesClient = {{queriesInit}};
+	const mutations: MutationsClient = {{mutationsInit}};
+	return { queries, mutations };
+}
+
+`;
+
+const UTILITY_FUNCTIONS_TEMPLATE_PART1 = `
+function withHandlerMetadata<THandler extends AnyHandlerDefinition>(
+	invoke: HandlerInvoker<HandlerArgs<THandler>, HandlerResult<THandler>>,
+	meta: HandlerMetadata<THandler>
+): AppflareHandler<THandler> {
+	const fn = invoke as AppflareHandler<THandler>;
+	fn.schema = meta.schema;
+	fn.websocket = meta.websocket;
+	fn.path = meta.path;
+	return fn;
+}
+
+function resolveRealtimeConfig(
+	baseUrl: string,
+	realtime?: RealtimeConfig
+): ResolvedRealtimeConfig {
+	return {
+		baseUrl: normalizeWsBaseUrl(realtime?.baseUrl ?? baseUrl),
+		path: realtime?.path ?? "/ws",
+		websocketImpl: realtime?.websocketImpl ?? defaultWebSocketFactory,
+	};
+}
+
+function createHandlerSchema<TArgs extends QueryArgsShape>(
+	args: TArgs
+): HandlerSchemaFromShape<TArgs> {
+	return z.object(args as any as Record<string, z.ZodTypeAny>) as HandlerSchemaFromShape<TArgs>;
+}
+`;
+
+const UTILITY_FUNCTIONS_TEMPLATE_PART2 = `
+function createHandlerWebsocket<TArgs, TResult>(
+	realtime: ResolvedRealtimeConfig,
+	defaults: { defaultTable: string; defaultHandler: { file: string; name: string } }
+): HandlerWebsocket<TArgs, TResult> {
+	return (args, options) => {
+		const baseUrl = normalizeWsBaseUrl(options?.baseUrl ?? realtime.baseUrl);
+		if (!baseUrl) {
+			throw new Error(
+				"Missing realtime baseUrl. Provide createAppflareApi({ realtime: { baseUrl } }) or handler websocket options.baseUrl."
+			);
+		}
+		const params = new URLSearchParams();
+		const tableParam = options?.table ?? defaults.defaultTable;
+		const normalizedTable = tableParam.endsWith("s")
+			? tableParam
+			: tableParam + "s";
+		params.set("table", normalizedTable);
+
+		const handlerRef =
+			options?.handler ??
+			(options?.handlerFile && options?.handlerName
+				? { file: options.handlerFile, name: options.handlerName }
+				: defaults.defaultHandler);
+		if (handlerRef) {
+			params.set("handler", JSON.stringify(handlerRef));
+		}
+		const where = options?.where ?? (isPlainObject(args) ? (args as Record<string, unknown>) : undefined);
+		if (where && Object.keys(where).length > 0) {
+			params.set("where", JSON.stringify(where));
+		}
+		if (options?.orderBy) params.set("orderBy", JSON.stringify(options.orderBy));
+		if (options?.take !== undefined) params.set("take", String(options.take));
+		if (options?.skip !== undefined) params.set("skip", String(options.skip));
+
+		const path = options?.path ?? realtime.path;
+		const url = buildRealtimeUrl(baseUrl, path, params);
+		const websocketFactory = options?.websocketImpl ?? realtime.websocketImpl ?? defaultWebSocketFactory;
+		const socket = websocketFactory(url, options?.protocols);
+
+		if (options?.onOpen) socket.addEventListener("open", options.onOpen as any);
+		if (options?.onClose) socket.addEventListener("close", options.onClose as any);
+		if (options?.onError) socket.addEventListener("error", options.onError as any);
+
+		const onMessage = (event: any) => {
+			const message = parseRealtimeMessage<TResult>(event?.data ?? event);
+			if (options?.onMessage) options.onMessage(message, event);
+			if (message?.type === "data" && Array.isArray((message as any).data)) {
+				options?.onData?.((message as any).data as TResult[], message);
+			}
+		};
+
+		socket.addEventListener("message", onMessage as any);
+
+		if (options?.signal) {
+			const abortHandler = () => socket.close(1000, "aborted");
+			if (options.signal.aborted) abortHandler();
+			else options.signal.addEventListener("abort", abortHandler, { once: true });
+		}
+
+		return socket;
+	};
+}
+`;
+
+const UTILITY_FUNCTIONS_TEMPLATE_PART3 = `
+function normalizeBaseUrl(baseUrl?: string): string {
+	if (!baseUrl) {
+		return "";
+	}
+	return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+}
+
+function normalizeWsBaseUrl(baseUrl?: string): string | undefined {
+	if (!baseUrl) return undefined;
+	if (baseUrl.startsWith("ws://") || baseUrl.startsWith("wss://")) {
+		return baseUrl.replace(/\\/+$/, "");
+	}
+	if (baseUrl.startsWith("https://")) return baseUrl.replace(/^https/, "wss").replace(/\\/$/, "");
+	if (baseUrl.startsWith("http://")) return baseUrl.replace(/^http/, "ws").replace(/\\/$/, "");
+	return baseUrl.replace(/\\/$/, "");
+}
+
+function buildUrl(baseUrl: string, path: string): string {
+	if (!baseUrl) {
+		return path;
+	}
+	const normalizedPath = path.startsWith("/") ? path : "/" + path;
+	return baseUrl + normalizedPath;
+}
+
+function buildRealtimeUrl(
+	baseUrl: string,
+	path: string,
+	params: URLSearchParams
+): string {
+	const normalizedBase = baseUrl.replace(/\\/+$/, "");
+	const normalizedPath = path.startsWith("/") ? path : "/" + path;
+	const query = params.toString();
+	return query ? normalizedBase + normalizedPath + "?" + query : normalizedBase + normalizedPath;
+}
+
+function buildQueryUrl(
+	baseUrl: string,
+	path: string,
+	params: Record<string, unknown> | undefined
+): string {
+	const url = buildUrl(baseUrl, path);
+	const query = serializeQueryParams(params);
+	return query ? url + "?" + query : url;
+}
+
+function serializeQueryParams(
+	params: Record<string, unknown> | undefined
+): string {
+	if (!params) {
+		return "";
+	}
+	const searchParams = new URLSearchParams();
+	for (const [key, value] of Object.entries(params)) {
+		if (value === undefined || value === null) {
+			continue;
+		}
+		if (Array.isArray(value)) {
+			for (const entry of value) {
+				searchParams.append(key, serializeQueryValue(entry));
+			}
+			continue;
+		}
+		searchParams.append(key, serializeQueryValue(value));
+	}
+	return searchParams.toString();
+}
+
+function serializeQueryValue(value: unknown): string {
+	if (value instanceof Date) {
+		return value.toISOString();
+	}
+	if (typeof value === "object") {
+		return JSON.stringify(value);
+	}
+	return String(value);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function parseRealtimeMessage<TResult>(value: unknown): RealtimeMessage<TResult> {
+	if (typeof value === "string") {
+		try {
+			return JSON.parse(value) as RealtimeMessage<TResult>;
+		} catch {
+			return { type: "message", raw: value } as any;
+		}
+	}
+	return value as RealtimeMessage<TResult>;
+}
+
+function ensureJsonHeaders(headers?: HeadersInit): HeadersInit {
+	if (!headers) {
+		return { "content-type": "application/json" };
+	}
+	if (typeof Headers !== "undefined" && headers instanceof Headers) {
+		const next = new Headers(headers);
+		if (!next.has("content-type")) {
+			next.set("content-type", "application/json");
+		}
+		return next;
+	}
+	if (Array.isArray(headers)) {
+		const entries = headers.slice();
+		const hasContentType = entries.some(
+			([key]) => key.toLowerCase() === "content-type"
+		);
+		if (!hasContentType) {
+			entries.push(["content-type", "application/json"]);
+		}
+		return entries;
+	}
+	if (typeof headers === "object") {
+		const record = { ...(headers as Record<string, string>) };
+		if (!hasHeader(record, "content-type")) {
+			record["content-type"] = "application/json";
+		}
+		return record;
+	}
+	return { "content-type": "application/json" };
+}
+
+function hasHeader(record: Record<string, string>, name: string): boolean {
+	const needle = name.toLowerCase();
+	return Object.keys(record).some((key) => key.toLowerCase() === needle);
+}
+
+async function parseJson<TResult>(response: Response): Promise<TResult> {
+	if (!response.ok) {
+		throw new Error("Request failed with status " + response.status);
+	}
+	return (await response.json()) as TResult;
+}
+`;
+
+const UTILITY_FUNCTIONS_TEMPLATE =
+	UTILITY_FUNCTIONS_TEMPLATE_PART1 +
+	UTILITY_FUNCTIONS_TEMPLATE_PART2 +
+	UTILITY_FUNCTIONS_TEMPLATE_PART3;
+
+function generateImports(params: {
+	handlers: DiscoveredHandler[];
+	outDirAbs: string;
+}): { importLines: string[]; importAliasBySource: Map<string, string> } {
+	const handlerImportsGrouped = groupBy(
+		params.handlers,
+		(h) => h.sourceFileAbs
+	);
+
+	const importLines: string[] = [];
+	const importAliasBySource = new Map<string, string>();
+	for (const [fileAbs, list] of Array.from(handlerImportsGrouped.entries())) {
+		const alias = `__appflare_${pascalCase(list[0].fileName)}`;
+		importAliasBySource.set(fileAbs, alias);
+		const importPath = toImportPathFromGeneratedSrc(params.outDirAbs, fileAbs);
+		importLines.push(
+			`import * as ${alias} from ${JSON.stringify(importPath)};`
+		);
+	}
+	return { importLines, importAliasBySource };
+}
+
+function generateGroupedHandlers(handlers: DiscoveredHandler[]): {
+	queriesByFile: Map<string, DiscoveredHandler[]>;
+	mutationsByFile: Map<string, DiscoveredHandler[]>;
+} {
+	const queries = handlers.filter((h) => h.kind === "query");
+	const mutations = handlers.filter((h) => h.kind === "mutation");
+
+	const queriesByFile = groupBy(queries, (h) => h.fileName);
+	const mutationsByFile = groupBy(mutations, (h) => h.fileName);
+
+	return { queriesByFile, mutationsByFile };
+}
+
+function generateTypeDefs(
+	queriesByFile: Map<string, DiscoveredHandler[]>,
+	mutationsByFile: Map<string, DiscoveredHandler[]>
+): { queriesTypeDef: string; mutationsTypeDef: string } {
+	const queriesTypeLines = generateQueriesTypeLines(queriesByFile);
+	const mutationsTypeLines = generateMutationsTypeLines(mutationsByFile);
+
+	const queriesTypeDef =
+		queriesByFile.size === 0 ? "{}" : `{\n${queriesTypeLines}\n}`;
+	const mutationsTypeDef =
+		mutationsByFile.size === 0 ? "{}" : `{\n${mutationsTypeLines}\n}`;
+
+	return { queriesTypeDef, mutationsTypeDef };
+}
+
+function generateClientInits(
+	queriesByFile: Map<string, DiscoveredHandler[]>,
+	mutationsByFile: Map<string, DiscoveredHandler[]>,
+	importAliasBySource: Map<string, string>
+): { queriesInit: string; mutationsInit: string } {
+	const queriesClientLines = generateQueriesClientLines(
+		queriesByFile,
+		importAliasBySource
+	);
+	const mutationsClientLines = generateMutationsClientLines(
+		mutationsByFile,
+		importAliasBySource
+	);
+
+	const queriesInit =
+		queriesByFile.size === 0 ? "{}" : `{\n${queriesClientLines}\n\t}`;
+	const mutationsInit =
+		mutationsByFile.size === 0 ? "{}" : `{\n${mutationsClientLines}\n\t}`;
+
+	return { queriesInit, mutationsInit };
+}
+
+export function generateApiClient(params: {
+	handlers: DiscoveredHandler[];
+	outDirAbs: string;
+}): string {
+	const { importLines, importAliasBySource } = generateImports(params);
+	const { queriesByFile, mutationsByFile } = generateGroupedHandlers(
+		params.handlers
+	);
+	const { queriesTypeDef, mutationsTypeDef } = generateTypeDefs(
+		queriesByFile,
+		mutationsByFile
+	);
+	const { queriesInit, mutationsInit } = generateClientInits(
+		queriesByFile,
+		mutationsByFile,
+		importAliasBySource
+	);
+
+	const typeBlocks = generateTypeBlocks(params.handlers, importAliasBySource);
+
+	return (
+		HEADER_TEMPLATE +
+		importLines.join("\n") +
+		TYPE_DEFINITIONS_TEMPLATE +
+		typeBlocks.join("\n\n") +
+		CLIENT_TYPES_TEMPLATE.replace("{{queriesTypeDef}}", queriesTypeDef)
+			.replace("{{mutationsTypeDef}}", mutationsTypeDef)
+			.replace("{{queriesInit}}", queriesInit)
+			.replace("{{mutationsInit}}", mutationsInit) +
+		UTILITY_FUNCTIONS_TEMPLATE
+	);
+}

package/cli/generators/generate-api-client/types.ts

@@ -0,0 +1,59 @@
+import { DiscoveredHandler } from "../../utils/utils";
+import { handlerTypePrefix, renderObjectKey, sortedEntries } from "./utils";
+
+export function generateTypeBlocks(
+	handlers: DiscoveredHandler[],
+	importAliasBySource: Map<string, string>
+): string[] {
+	const typeBlocks: string[] = [];
+	for (const h of handlers) {
+		const importAlias = importAliasBySource.get(h.sourceFileAbs)!;
+		const handlerAccessor = `${importAlias}[${JSON.stringify(h.name)}]`;
+		const pascal = handlerTypePrefix(h);
+		typeBlocks.push(
+			`type ${pascal}Definition = typeof ${handlerAccessor};\n` +
+				`type ${pascal}Args = HandlerArgs<${pascal}Definition>;\n` +
+				`type ${pascal}Result = HandlerResult<${pascal}Definition>;\n` +
+				`type ${pascal}Client = AppflareHandler<${pascal}Definition>;`
+		);
+	}
+	return typeBlocks;
+}
+
+export function generateQueriesTypeLines(
+	queriesByFile: Map<string, DiscoveredHandler[]>
+): string {
+	return sortedEntries(queriesByFile)
+		.map(([fileName, list]) => {
+			const fileKey = renderObjectKey(fileName);
+			const inner = list
+				.slice()
+				.sort((a, b) => a.name.localeCompare(b.name))
+				.map((h) => {
+					const pascal = handlerTypePrefix(h);
+					return `\t\t${h.name}: ${pascal}Client;`;
+				})
+				.join("\n");
+			return `\t${fileKey}: {\n${inner || "\t\t// (none)"}\n\t};`;
+		})
+		.join("\n");
+}
+
+export function generateMutationsTypeLines(
+	mutationsByFile: Map<string, DiscoveredHandler[]>
+): string {
+	return sortedEntries(mutationsByFile)
+		.map(([fileName, list]) => {
+			const fileKey = renderObjectKey(fileName);
+			const inner = list
+				.slice()
+				.sort((a, b) => a.name.localeCompare(b.name))
+				.map((h) => {
+					const pascal = handlerTypePrefix(h);
+					return `\t\t${h.name}: ${pascal}Client;`;
+				})
+				.join("\n");
+			return `\t${fileKey}: {\n${inner || "\t\t// (none)"}\n\t};`;
+		})
+		.join("\n");
+}

package/cli/generators/generate-api-client/utils.ts

@@ -0,0 +1,18 @@
+import { isValidIdentifier } from "../../utils/utils";
+
+export const sortedEntries = <T>(map: Map<string, T[]>): Array<[string, T[]]> =>
+	Array.from(map.entries()).sort(([a], [b]) => a.localeCompare(b));
+
+export const renderObjectKey = (key: string): string =>
+	isValidIdentifier(key) ? key : JSON.stringify(key);
+
+export const handlerTypePrefix = (h: any): string =>
+	h.fileName
+		.replace(/[^a-zA-Z0-9]/g, "")
+		.replace(/^./, (c: string) => c.toUpperCase()) +
+	h.name
+		.replace(/[^a-zA-Z0-9]/g, "")
+		.replace(/^./, (c: string) => c.toUpperCase());
+
+export const normalizeTableName = (fileName: string): string =>
+	fileName.endsWith("s") ? fileName : `${fileName}s`;

package/cli/generators/generate-api-client.ts

@@ -0,0 +1 @@
+export { generateApiClient } from "./generate-api-client/index";