appflare 0.0.28 → 0.1.0

package/react/use-mutation.ts

@@ -0,0 +1,54 @@
+import {
+	type UseMutationOptions,
+	type UseMutationResult,
+	useMutation as useTanstackMutation,
+} from "@tanstack/react-query";
+
+type AppflareRequestErrorLike = {
+	message: string;
+	status?: number;
+};
+
+type AppflareRequestResultLike<TData> = {
+	data: TData | null;
+	error: AppflareRequestErrorLike | null;
+};
+
+type AppflareMutationLike<TArgs, TData> = {
+	run: (
+		args: TArgs,
+		options?: any,
+	) => Promise<AppflareRequestResultLike<TData>>;
+};
+
+function toError(error: AppflareRequestErrorLike): Error {
+	const next = new Error(error.message);
+	if (error.status !== undefined) {
+		(next as Error & { status?: number }).status = error.status;
+	}
+	return next;
+}
+
+export function useMutation<TArgs, TData, TContext = unknown>(
+	mutation: AppflareMutationLike<TArgs, TData>,
+	args: TArgs,
+	mutationOptions?: Omit<
+		UseMutationOptions<TData, Error, void, TContext>,
+		"mutationFn"
+	>,
+): UseMutationResult<TData, Error, void, TContext> {
+	return useTanstackMutation<TData, Error, void, TContext>({
+		...(mutationOptions as Omit<
+			UseMutationOptions<TData, Error, void, TContext>,
+			"mutationFn"
+		>),
+		mutationFn: async () => {
+			const response = await mutation.run(args);
+			if (response.error) {
+				throw toError(response.error);
+			}
+
+			return response.data as TData;
+		},
+	});
+}

package/react/use-query.ts

@@ -0,0 +1,158 @@
+import {
+	type QueryKey,
+	type UseQueryOptions,
+	type UseQueryResult,
+	useQuery as useTanstackQuery,
+	useQueryClient,
+} from "@tanstack/react-query";
+import { useEffect, useMemo } from "react";
+
+type AppflareRequestErrorLike = {
+	message: string;
+	status?: number;
+};
+
+type AppflareRequestResultLike<TData> = {
+	data: TData | null;
+	error: AppflareRequestErrorLike | null;
+};
+
+type AppflareRealtimeSubscriptionLike = {
+	remove: () => void;
+};
+
+type AppflareRealtimeQueryUpdateLike<TData> = {
+	event: "query:update";
+	payload: {
+		queryName: string;
+		signature: string;
+		data: TData;
+	};
+};
+
+type AppflareQueryLike<TArgs, TData> = {
+	run: (
+		args: TArgs,
+		options?: any,
+	) => Promise<AppflareRequestResultLike<TData>>;
+	subscribe?: (options: {
+		args?: TArgs;
+		authToken?: string;
+		requestOptions?: any;
+		signal?: AbortSignal;
+		onChange: (
+			data: TData,
+			update: AppflareRealtimeQueryUpdateLike<TData>,
+		) => void;
+		onError?: (error: unknown) => void;
+	}) => AppflareRealtimeSubscriptionLike;
+};
+
+export type UseAppflareQueryOptions<
+	TArgs,
+	TData,
+	TSelected = TData,
+	TKey extends QueryKey = QueryKey,
+> = {
+	realtime?: {
+		enabled?: boolean;
+		authToken?: string;
+		requestOptions?: any;
+		onChange?: (
+			data: TData,
+			update: AppflareRealtimeQueryUpdateLike<TData>,
+		) => void;
+		onError?: (error: unknown) => void;
+	};
+	requestOptions?: any;
+	queryOptions?: Omit<
+		UseQueryOptions<TData, Error, TSelected, TKey>,
+		"queryFn" | "queryKey"
+	> & {
+		queryKey?: TKey;
+	};
+};
+
+function toError(error: AppflareRequestErrorLike): Error {
+	const next = new Error(error.message);
+	if (error.status !== undefined) {
+		(next as Error & { status?: number }).status = error.status;
+	}
+	return next;
+}
+
+export function useQuery<
+	TArgs,
+	TData,
+	TSelected = TData,
+	TKey extends QueryKey = QueryKey,
+>(
+	query: AppflareQueryLike<TArgs, TData>,
+	args: TArgs,
+	options?: UseAppflareQueryOptions<TArgs, TData, TSelected, TKey>,
+): UseQueryResult<TSelected, Error> {
+	const queryClient = useQueryClient();
+	const resolvedQueryKey = useMemo(() => {
+		return (
+			options?.queryOptions?.queryKey ??
+			(["appflare", "query", query, args] as unknown as TKey)
+		);
+	}, [args, options?.queryOptions?.queryKey, query]);
+
+	const result = useTanstackQuery<TData, Error, TSelected, TKey>({
+		...(options?.queryOptions as Omit<
+			UseQueryOptions<TData, Error, TSelected, TKey>,
+			"queryFn" | "queryKey"
+		>),
+		queryKey: resolvedQueryKey,
+		queryFn: async () => {
+			const response = await query.run(args, options?.requestOptions);
+			if (response.error) {
+				throw toError(response.error);
+			}
+			return response.data as TData;
+		},
+	});
+
+	useEffect(() => {
+		if (options?.realtime?.enabled === false || !query.subscribe) {
+			return;
+		}
+
+		const controller = new AbortController();
+		const subscription = query.subscribe({
+			args,
+			authToken: options.realtime?.authToken,
+			requestOptions: options.realtime?.requestOptions,
+			signal: controller.signal,
+			onChange: (data, update) => {
+				queryClient.setQueryData<TData>(resolvedQueryKey, data as TData);
+				options.realtime?.onChange?.(
+					data as TData,
+					update as AppflareRealtimeQueryUpdateLike<TData>,
+				);
+			},
+			onError: (error) => {
+				options.realtime?.onError?.(error);
+			},
+		});
+
+		return () => {
+			controller.abort();
+			subscription.remove();
+		};
+	}, [
+		args,
+		options?.realtime?.authToken,
+		options?.realtime?.enabled,
+		options?.realtime?.onChange,
+		options?.realtime?.onError,
+		options?.realtime?.requestOptions,
+		query,
+		query.subscribe,
+		queryClient,
+		resolvedQueryKey,
+	]);
+
+	return result;
+}

package/schema.ts

@@ -0,0 +1,262 @@
+export type ColumnType = "int" | "string" | "boolean" | "date";
+
+export type ColumnBuilderOptions = {
+	sqlName?: string;
+	length?: number;
+};
+
+export type PrimaryKeyOptions = {
+	autoIncrement?: boolean;
+};
+
+export type RelationOneOptions = {
+	referenceField?: string;
+	field?: string;
+	fkType?: ColumnType;
+	sqlName?: string;
+	notNull?: boolean;
+};
+
+export type RelationManyOptions = {
+	referenceField?: string;
+	field?: string;
+	fkType?: ColumnType;
+	sqlName?: string;
+	notNull?: boolean;
+};
+
+export type ColumnReference = {
+	table: string;
+	column: string;
+};
+
+export type ColumnDefinition = {
+	kind: "column";
+	type: ColumnType;
+	sqlName?: string;
+	length?: number;
+	notNull?: boolean;
+	primaryKey?: boolean;
+	autoIncrement?: boolean;
+	unique?: true | { name?: string };
+	index?: true | { name?: string };
+	sqlDefault?: unknown;
+	runtimeDefaultFn?: () => unknown;
+	references?: ColumnReference;
+};
+
+export type OneRelationDefinition = {
+	kind: "relation";
+	relation: "one";
+	targetTable: string;
+	field?: string;
+	referenceField?: string;
+	fkType?: ColumnType;
+	sqlName?: string;
+	notNull?: boolean;
+};
+
+export type ManyRelationDefinition = {
+	kind: "relation";
+	relation: "many";
+	targetTable: string;
+	field?: string;
+	referenceField?: string;
+	fkType?: ColumnType;
+	sqlName?: string;
+	notNull?: boolean;
+};
+
+export type RelationDefinition = OneRelationDefinition | ManyRelationDefinition;
+
+export type TableOptions = {
+	sqlName?: string;
+};
+
+export type TableShape = Record<string, ColumnBuilder | RelationDefinition>;
+
+export type TableDefinition = {
+	kind: "table";
+	sqlName?: string;
+	columns: Record<string, ColumnDefinition>;
+	relations: Record<string, RelationDefinition>;
+};
+
+export type SchemaDefinition = {
+	kind: "schema";
+	tables: Record<string, TableDefinition>;
+};
+
+export class ColumnBuilder {
+	private definition: ColumnDefinition;
+
+	public constructor(
+		typeOrDefinition: ColumnType | ColumnDefinition,
+		options: ColumnBuilderOptions = {},
+	) {
+		if (typeof typeOrDefinition === "string") {
+			this.definition = {
+				kind: "column",
+				type: typeOrDefinition,
+				sqlName: options.sqlName,
+				length: options.length,
+			};
+			return;
+		}
+
+		this.definition = {
+			...typeOrDefinition,
+		};
+	}
+
+	private with(patch: Partial<ColumnDefinition>): ColumnBuilder {
+		return new ColumnBuilder({
+			...this.definition,
+			...patch,
+		});
+	}
+
+	public sql(name: string): ColumnBuilder {
+		return this.with({ sqlName: name });
+	}
+
+	public notNull(): ColumnBuilder {
+		return this.with({ notNull: true });
+	}
+
+	public primaryKey(options: PrimaryKeyOptions = {}): ColumnBuilder {
+		return this.with({
+			primaryKey: true,
+			autoIncrement: options.autoIncrement ?? this.definition.autoIncrement,
+		});
+	}
+
+	public unique(name?: string): ColumnBuilder {
+		return this.with({ unique: name ? { name } : true });
+	}
+
+	public index(name?: string): ColumnBuilder {
+		return this.with({ index: name ? { name } : true });
+	}
+
+	public default(value: unknown): ColumnBuilder {
+		return this.with({ sqlDefault: value });
+	}
+
+	public defaultFn(fn: () => unknown): ColumnBuilder {
+		return this.with({ runtimeDefaultFn: fn });
+	}
+
+	public references(table: string, column = "id"): ColumnBuilder {
+		return this.with({ references: { table, column } });
+	}
+
+	public toDefinition(): ColumnDefinition {
+		return { ...this.definition };
+	}
+}
+
+export function table(
+	shape: TableShape,
+	options: TableOptions = {},
+): TableDefinition {
+	const columns: Record<string, ColumnDefinition> = {};
+	const relations: Record<string, RelationDefinition> = {};
+
+	for (const [fieldName, value] of Object.entries(shape)) {
+		if (value instanceof ColumnBuilder) {
+			columns[fieldName] = value.toDefinition();
+			continue;
+		}
+
+		if (value.kind === "relation") {
+			relations[fieldName] = value;
+			continue;
+		}
+
+		throw new Error(
+			`Invalid table field '${fieldName}'. Use column builders or relation helpers.`,
+		);
+	}
+
+	return {
+		kind: "table",
+		sqlName: options.sqlName,
+		columns,
+		relations,
+	};
+}
+
+export function schema(
+	tables: Record<string, TableDefinition>,
+): SchemaDefinition {
+	return {
+		kind: "schema",
+		tables,
+	};
+}
+
+export function isSchemaDefinition(value: unknown): value is SchemaDefinition {
+	if (typeof value !== "object" || value === null) {
+		return false;
+	}
+	const candidate = value as { kind?: string; tables?: unknown };
+	return candidate.kind === "schema" && typeof candidate.tables === "object";
+}
+
+export const v = {
+	int: (options: ColumnBuilderOptions = {}) =>
+		new ColumnBuilder("int", options),
+	string: (options: ColumnBuilderOptions = {}) =>
+		new ColumnBuilder("string", options),
+	boolean: (options: ColumnBuilderOptions = {}) =>
+		new ColumnBuilder("boolean", options),
+	date: (options: ColumnBuilderOptions = {}) =>
+		new ColumnBuilder("date", options),
+	one: (
+		targetTable: string,
+		fieldOrOptions?: string | RelationOneOptions,
+		options: RelationOneOptions = {},
+	): OneRelationDefinition => {
+		const field =
+			typeof fieldOrOptions === "string" ? fieldOrOptions : undefined;
+		const mergedOptions =
+			typeof fieldOrOptions === "string"
+				? options
+				: (fieldOrOptions ?? options);
+
+		return {
+			kind: "relation",
+			relation: "one",
+			targetTable,
+			field: mergedOptions.field ?? field,
+			referenceField: mergedOptions.referenceField,
+			fkType: mergedOptions.fkType,
+			sqlName: mergedOptions.sqlName,
+			notNull: mergedOptions.notNull,
+		};
+	},
+	many: (
+		targetTable: string,
+		fieldOrOptions?: string | RelationManyOptions,
+		options: RelationManyOptions = {},
+	): ManyRelationDefinition => {
+		const field =
+			typeof fieldOrOptions === "string" ? fieldOrOptions : undefined;
+		const mergedOptions =
+			typeof fieldOrOptions === "string"
+				? options
+				: (fieldOrOptions ?? options);
+
+		return {
+			kind: "relation",
+			relation: "many",
+			targetTable,
+			field: mergedOptions.field ?? field,
+			referenceField: mergedOptions.referenceField,
+			fkType: mergedOptions.fkType,
+			sqlName: mergedOptions.sqlName,
+			notNull: mergedOptions.notNull,
+		};
+	},
+};

package/tsconfig.json

@@ -1,8 +1,6 @@
 {
+	"extends": "../../tsconfig.json",
 	"compilerOptions": {
-		"target": "es2022",
-		"module": "es2022",
-		"moduleResolution": "bundler",
-		"types": ["@cloudflare/workers-types/2023-07-01", "@types/node"]
+		"rootDir": "."
 	}
 }

package/cli/README.md

@@ -1,108 +0,0 @@
-# Appflare CLI
-
-This folder contains the build toolchain that turns an Appflare project (schema + query/mutation handlers) into a fully generated API surface (typed client, Hono server, websocket durable object, and optional JS/.d.ts emit). The CLI is Bun-based and is intended to run inside a project that exports `appflare.config.ts`.
-
-## Command surface
-
-- **build**: entrypoint defined in [packages/appflare/cli/index.ts](packages/appflare/cli/index.ts). Generates all artifacts into the configured `outDir` and optionally emits compiled output.
-  - `-c, --config <path>`: path to the config file (defaults to `appflare.config.ts`).
-  - `--emit`: after generation, run `bunx tsc` with a temporary tsconfig to emit JS and .d.ts into `outDir/dist`.
-  - `-w, --watch`: keep the process alive, watch for file changes (excluding `outDir`/`node_modules`/build artifacts), and rerun the build. Recomputes watched paths when the config changes.
-
-### Config shape
-
-`appflare.config.ts` must default-export an object with:
-
-```ts
-export default {
-	dir: "./app", // Root folder containing your handlers
-	schema: "./schema.ts", // Path to the Zod schema file
-	outDir: "./_generated", // Where generated files are written
-	auth: {
-		// Optional: Better Auth config forwarded to the generated server
-		enabled: false,
-		basePath: "/auth",
-		options: {},
-	},
-};
-```
-
-The loader in [packages/appflare/cli/core/config.ts](packages/appflare/cli/core/config.ts) validates presence and types of `dir`, `schema`, and `outDir`, lightly checks optional `auth` (base path, enabled flag, options object), and resolves paths relative to the config file location.
-
-## Build pipeline
-
-The build orchestrator in [packages/appflare/cli/core/build.ts](packages/appflare/cli/core/build.ts) performs the following steps when `build` runs:
-
-1. Resolve absolute paths for `dir`, `schema`, and `outDir`; ensure `dir` and `schema` exist.
-2. Create `outDir/src` and `outDir/server` if missing.
-3. Generate typed schema helpers into `outDir/src/schema-types.ts` using [packages/appflare/cli/schema/schema.ts](packages/appflare/cli/schema/schema.ts). This produces table doc interfaces, `TableNames`, `Id`, query helpers, and convenience types from [packages/appflare/cli/schema/schema-static-types.ts](packages/appflare/cli/schema/schema-static-types.ts).
-4. Generate built-in CRUD handlers for every table into `outDir/src/handlers/<table>.ts` plus an index via [packages/appflare/cli/generators/generate-db-handlers.ts](packages/appflare/cli/generators/generate-db-handlers.ts). These include `find*`, `findOne*`, `insert*`, `update*`, and `delete*` operations backed by the generated schema types.
-5. Discover user-defined handlers under `dir` with [packages/appflare/cli/core/discover-handlers.ts](packages/appflare/cli/core/discover-handlers.ts):
-   - Recurses through `.ts` files (excluding `node_modules`, `.git`, `dist`, `build`, and the configured `outDir`).
-   - Recognizes handlers declared as `export const <name> = query(` or `export const <name> = mutation(`.
-   - Skips the schema file and the config file; deduplicates by kind/file/name.
-6. Generate a typed client at `outDir/src/api.ts` via [packages/appflare/cli/generators/generate-api-client.ts](packages/appflare/cli/generators/generate-api-client.ts):
-   - Produces `createAppflareApi()` with `queries` and `mutations` collections keyed by `<file>/<handler>`.
-   - Each handler function wraps `fetch` (default `better-fetch`) and carries metadata: Zod schema, websocket helper, and route path.
-   - Realtime helpers build websocket URLs for subscriptions, normalizing `ws`/`wss` bases and providing hooks (`onOpen`, `onMessage`, `onData`, etc.).
-7. Generate a Hono server at `outDir/server/server.ts` with [packages/appflare/cli/generators/generate-hono-server.ts](packages/appflare/cli/generators/generate-hono-server.ts):
-   - Routes: `GET /queries/<file>/<name>` and `POST /mutations/<file>/<name>`.
-   - Uses `@hono/standard-validator` + Zod arg schemas and wraps Mongo via `createMongoDbContext` from `appflare/server/db`.
-   - Supports optional mutation notifications for realtime (custom notifier or Durable Object hook).
-8. Generate a websocket Durable Object shim at `outDir/server/websocket-hibernation-server.ts` via [packages/appflare/cli/generators/generate-websocket-durable-object.ts](packages/appflare/cli/generators/generate-websocket-durable-object.ts):
-   - Implements `WebSocketHibernationServer` to handle subscriptions at `/ws` and mutation notifications at `/notify`.
-   - Selects a default query handler per table (or a specific handler) and re-fetches data on mutation notifications, emitting `data` messages to subscribers.
-9. If `--emit` is set, remove any previous `outDir/dist`, write a temporary tsconfig (includes generated schema types and handlers only), and run `bunx tsc` to emit JS + .d.ts into `outDir/dist` (logic in [packages/appflare/cli/utils/tsc.ts](packages/appflare/cli/utils/tsc.ts)).
-
-## Handler authoring guidelines
-
-- Handlers must be exported as `query({ args, handler })` or `mutation({ args, handler })` objects.
-- Filenames become the first route/path segment and grouping key in the client (`<file>/<handler>`).
-- Arguments are validated with Zod; the client infers optional vs required keys and provides typed `args` for both client and server.
-- The discovery step ignores `.d.ts` files and anything outside the configured `dir`.
-
-## Generated layout (relative to `outDir`)
-
-```
-src/
-  schema-types.ts          # Typed schema exports, helpers, and Zod-powered validator types
-  handlers/               # Auto CRUD handlers per table + index
-    <table>.ts
-    index.ts
-  api.ts                  # Typed queries/mutations client with realtime helpers
-server/
-  server.ts               # Hono server that wires handlers + Mongo context
-  websocket-hibernation-server.ts # Durable Object websocket bridge
-```
-
-## Realtime and Durable Object flow
-
-- Client websockets are created via `handler.websocket(args?, options?)`, building URLs against `realtime.baseUrl` (or handler override) and defaulting the `table` and `handler` params based on the handler’s file/name.
-- The Durable Object handles `/ws` upgrades, parses subscription params (`table`, `handler`, `where`, `orderBy`, `take`, `skip`, `select`, `include`, `args`), and caches subscriptions. On `/notify` payloads, it re-runs the relevant query or table fetch and pushes a `data` message to connected sockets.
-- Mutation notifications can be sent by the generated Hono server (if `realtime.notify` or `realtime.durableObject` is provided) so subscriptions stay in sync.
-
-## Error handling and safeguards
-
-- Config, schema, and project directories are validated before generation; missing paths throw with readable errors.
-- Build de-duplicates discovered handlers to avoid duplicate route generation.
-- `--emit` uses a scoped tsconfig that only references generated files to prevent user code outside `rootDir` from breaking emit.
-- Generated files include `/* eslint-disable */` headers to avoid lint noise.
-
-## Typical usage
-
-```sh
-# From the repo root (config defaults to ./appflare.config.ts)
-bunx appflare build
-
-# Custom config location and emit compiled JS
-bunx appflare build --config ./config/appflare.config.ts --emit
-```
-
-After running, import the generated client/server:
-
-```ts
-import { createAppflareApi } from "./_generated/src/api";
-import server from "./_generated/server/server";
-```
-
-Use the client in web/React or server contexts, and deploy the generated Hono server + Durable Object to your runtime of choice (e.g., Cloudflare Workers with Mongo).