appflare 0.0.28 → 0.1.0

package/lib/values.ts

@@ -1,27 +0,0 @@
-import { z } from "zod";
-import { geoPointSchema } from "./location";
-
-export const v = {
-	string: () => z.string(),
-	number: () => z.number(),
-	boolean: () => z.boolean(),
-	date: () => z.date(),
-	point: () => geoPointSchema,
-	location: () => geoPointSchema,
-	id: (table: string) =>
-		z
-			.string()
-			.regex(/^[a-f\d]{24}$/i, "Invalid ObjectId")
-			.describe(`ref:${table}`) as z.ZodString,
-	array: <T extends z.ZodTypeAny>(item: T) => z.array(item),
-	object: (shape: Record<string, z.ZodTypeAny>) => z.object(shape),
-	optional: <T extends z.ZodTypeAny>(schema: T) => schema.optional(),
-	nullable: <T extends z.ZodTypeAny>(schema: T) => schema.nullable(),
-	union: <T extends [z.ZodTypeAny, ...z.ZodTypeAny[]]>(...schemas: T) =>
-		z.union(schemas),
-	literal: (value: any) => z.literal(value),
-	buffer: () => z.string(), // or z.instanceof(Buffer) if using Buffer
-	any: () => z.any(),
-	unknown: () => z.unknown(),
-	// Add more as needed
-};

package/react/README.md

@@ -1,67 +0,0 @@
-## React hooks (`react/`)
-
-Entry point re-exports hooks ([packages/appflare/react/index.ts](packages/appflare/react/index.ts)). Hooks expect handlers generated by the Appflare client (each handler has `.path`, `.schema`, and `.websocket` metadata).
-
-### Shared realtime utilities
-
-- Located in [packages/appflare/react/shared/queryShared.ts](packages/appflare/react/shared/queryShared.ts).
-- `useRealtimeSubscription` wires a handler’s `websocket` helper into React Query caches; accepts `realtime` options (`enabled`, `baseUrl`, `where`, `orderBy`, `onMessage`, `onData`, etc.).
-- Helpers: `buildQueryKey(queryKey, handler, argsKey)` and `stableSerialize(value)` for deterministic keys.
-
-### `useQuery`
-
-- File: [packages/appflare/react/hooks/useQuery.ts](packages/appflare/react/hooks/useQuery.ts).
-- Wraps `@tanstack/react-query` `useQuery` and injects realtime updates when the handler exposes `websocket`.
-- Signature: `useQuery({ handler, args?, queryKey?, queryOptions?, realtime? })` or `useQuery(handler, { ... })`.
-- Returns the React Query result plus `{ websocket }` (the live socket or `null`).
-- Realtime: if enabled, incoming `data` arrays replace the cached result via `setQueryData`.
-
-### `usePaginatedQuery`
-
-- File: [packages/appflare/react/hooks/usePaginatedQuery.ts](packages/appflare/react/hooks/usePaginatedQuery.ts).
-- Wraps `useInfiniteQuery` for cursor pagination.
-- Options: `pageParamKey` (default `"cursor"`), `initialPageParam`, `getNextPageParam`, `getPreviousPageParam`, plus `realtime` controls.
-- On realtime `data`, replaces the first page in the cache to keep pagination metadata intact.
-
-### `useMutation`
-
-- File: [packages/appflare/react/hooks/useMutation.ts](packages/appflare/react/hooks/useMutation.ts).
-- Thin wrapper over `useMutation`; builds a `mutationKey` from `handler.path` when provided.
-- Signature: `useMutation({ handler, mutationKey?, mutationOptions? })` or `useMutation(handler, { ... })`.
-
-### React usage example
-
-```tsx
-import { createAppflareApi } from "../_generated/src/api";
-import { useQuery, useMutation } from "appflare/react";
-
-const api = createAppflareApi({ baseUrl: "/api" });
-
-export function Users() {
-	const users = useQuery(api.queries.users.list, {
-		realtime: { baseUrl: "wss://my-app/ws" },
-	});
-
-	const createUser = useMutation(api.mutations.users.create, {
-		mutationOptions: { onSuccess: () => users.refetch() },
-	});
-
-	return (
-		<div>
-			<button onClick={() => createUser.mutate({ name: "Ada" })}>
-				Add user
-			</button>
-			{users.data?.map((u) => (
-				<div key={u._id}>{u.name}</div>
-			))}
-		</div>
-	);
-}
-```
-
-## Integration tips
-
-- Handlers come from the generated client; ensure you pass the same `baseUrl`/`realtime.baseUrl` you configured in the server/Durable Object.
-- Realtime is opt-in per hook via `realtime: true` or options; if the handler lacks `websocket`, no socket is opened.
-- Use `queryKey`/`mutationKey` overrides when multiple instances of the same handler need isolated caches.
-- `v.id("table")` pairs with `describe("ref:<table>")`; keep table names consistent with your schema for proper typing in generated code.

package/react/hooks/useMutation.ts

@@ -1,89 +0,0 @@
-import {
-	MutationKey,
-	UseMutationOptions,
-	UseMutationResult,
-	useMutation as useNativeMutation,
-} from "@tanstack/react-query";
-
-export type Handler<TArgs, TResult> = {
-	(args: TArgs, init?: RequestInit): Promise<TResult>;
-	path?: string;
-	schema?: unknown;
-};
-
-export type UseAppflareMutationOptions<
-	TArgs,
-	TResult,
-	TError = unknown,
-	TContext = unknown,
-> = {
-	handler: Handler<TArgs, TResult>;
-	mutationKey?: MutationKey;
-	mutationOptions?: Omit<
-		UseMutationOptions<TResult, TError, TArgs, TContext>,
-		"mutationFn" | "mutationKey"
-	>;
-};
-
-export type UseAppflareMutationResult<
-	TResult,
-	TError = unknown,
-	TArgs = unknown,
-	TContext = unknown,
-> = UseMutationResult<TResult, TError, TArgs, TContext>;
-
-export function useMutation<
-	TArgs,
-	TResult,
-	TError = unknown,
-	TContext = unknown,
->(
-	options: UseAppflareMutationOptions<TArgs, TResult, TError, TContext>
-): UseAppflareMutationResult<TResult, TError, TArgs, TContext>;
-
-export function useMutation<
-	TArgs,
-	TResult,
-	TError = unknown,
-	TContext = unknown,
->(
-	handler: Handler<TArgs, TResult>,
-	options?: Omit<
-		UseAppflareMutationOptions<TArgs, TResult, TError, TContext>,
-		"handler"
-	>
-): UseAppflareMutationResult<TResult, TError, TArgs, TContext>;
-
-export function useMutation<
-	TArgs,
-	TResult,
-	TError = unknown,
-	TContext = unknown,
->(
-	optionsOrHandler:
-		| UseAppflareMutationOptions<TArgs, TResult, TError, TContext>
-		| Handler<TArgs, TResult>,
-	options?: Omit<
-		UseAppflareMutationOptions<TArgs, TResult, TError, TContext>,
-		"handler"
-	>
-): UseAppflareMutationResult<TResult, TError, TArgs, TContext> {
-	const normalizedOptions =
-		typeof optionsOrHandler === "function"
-			? ({
-					handler: optionsOrHandler,
-					...(options ?? {}),
-				} as UseAppflareMutationOptions<TArgs, TResult, TError, TContext>)
-			: optionsOrHandler;
-
-	const { handler, mutationKey, mutationOptions } = normalizedOptions;
-	const finalMutationKey: MutationKey = mutationKey ?? [
-		handler?.path ?? "appflare-handler",
-	];
-
-	return useNativeMutation<TResult, TError, TArgs, TContext>({
-		mutationKey: finalMutationKey,
-		mutationFn: (variables: TArgs) => handler(variables),
-		...(mutationOptions ?? {}),
-	});
-}

package/react/hooks/usePaginatedQuery.ts

@@ -1,213 +0,0 @@
-import { useCallback, useMemo } from "react";
-import {
-	InfiniteData,
-	QueryKey,
-	UseInfiniteQueryOptions,
-	UseInfiniteQueryResult,
-	useInfiniteQuery as useNativeInfiniteQuery,
-	useQueryClient,
-} from "@tanstack/react-query";
-import {
-	HandlerWithRealtime,
-	RealtimeHookOptions,
-	RealtimeMessage,
-	buildQueryKey,
-	stableSerialize,
-	useRealtimeSubscription,
-} from "../shared/queryShared";
-
-export type PaginatedResult<TResult, TCursor = unknown> = {
-	items: TResult[];
-	nextCursor?: TCursor | null;
-	prevCursor?: TCursor | null;
-};
-
-export type UseAppflarePaginatedQueryOptions<
-	TArgs,
-	TResult,
-	TCursor = unknown,
-	TError = unknown,
-> = {
-	handler: HandlerWithRealtime<TArgs, PaginatedResult<TResult, TCursor>>;
-	args?: TArgs;
-	queryKey?: QueryKey;
-	pageParamKey?: string;
-	initialPageParam?: TCursor;
-	getNextPageParam?: (
-		lastPage: PaginatedResult<TResult, TCursor>,
-		pages: PaginatedResult<TResult, TCursor>[]
-	) => TCursor | undefined;
-	getPreviousPageParam?: (
-		firstPage: PaginatedResult<TResult, TCursor>,
-		pages: PaginatedResult<TResult, TCursor>[]
-	) => TCursor | undefined;
-	queryOptions?: Omit<
-		UseInfiniteQueryOptions<
-			PaginatedResult<TResult, TCursor>,
-			TError,
-			InfiniteData<PaginatedResult<TResult, TCursor>, TCursor>,
-			QueryKey,
-			TCursor
-		>,
-		| "queryKey"
-		| "queryFn"
-		| "initialPageParam"
-		| "getNextPageParam"
-		| "getPreviousPageParam"
-	>;
-	realtime?: boolean | RealtimeHookOptions<PaginatedResult<TResult, TCursor>>;
-};
-
-export type UseAppflarePaginatedQueryResult<
-	TResult,
-	TCursor = unknown,
-	TError = unknown,
-> = UseInfiniteQueryResult<
-	InfiniteData<PaginatedResult<TResult, TCursor>, TCursor>,
-	TError
-> & {
-	websocket: WebSocket | null;
-};
-
-export function usePaginatedQuery<
-	TArgs,
-	TResult,
-	TCursor = unknown,
-	TError = unknown,
->(
-	options: UseAppflarePaginatedQueryOptions<TArgs, TResult, TCursor, TError>
-): UseAppflarePaginatedQueryResult<TResult, TCursor, TError>;
-
-export function usePaginatedQuery<
-	TArgs,
-	TResult,
-	TCursor = unknown,
-	TError = unknown,
->(
-	handler: HandlerWithRealtime<TArgs, PaginatedResult<TResult, TCursor>>,
-	options?: Omit<
-		UseAppflarePaginatedQueryOptions<TArgs, TResult, TCursor, TError>,
-		"handler"
-	>
-): UseAppflarePaginatedQueryResult<TResult, TCursor, TError>;
-
-export function usePaginatedQuery<
-	TArgs,
-	TResult,
-	TCursor = unknown,
-	TError = unknown,
->(
-	optionsOrHandler:
-		| UseAppflarePaginatedQueryOptions<TArgs, TResult, TCursor, TError>
-		| HandlerWithRealtime<TArgs, PaginatedResult<TResult, TCursor>>,
-	options?: Omit<
-		UseAppflarePaginatedQueryOptions<TArgs, TResult, TCursor, TError>,
-		"handler"
-	>
-): UseAppflarePaginatedQueryResult<TResult, TCursor, TError> {
-	const normalizedOptions = useMemo(
-		() =>
-			typeof optionsOrHandler === "function"
-				? ({
-						handler: optionsOrHandler,
-						...(options ?? {}),
-					} as UseAppflarePaginatedQueryOptions<
-						TArgs,
-						TResult,
-						TCursor,
-						TError
-					>)
-				: optionsOrHandler,
-		[optionsOrHandler, options]
-	);
-
-	const realtime = normalizedOptions.realtime;
-	const handler = normalizedOptions.handler;
-	const args = normalizedOptions.args;
-	const queryKey = normalizedOptions.queryKey;
-	const queryOptions = normalizedOptions.queryOptions;
-
-	const pageParamKey = normalizedOptions.pageParamKey ?? "cursor";
-	const initialPageParam = normalizedOptions.initialPageParam;
-	const getNextPageParam = normalizedOptions.getNextPageParam;
-	const getPreviousPageParam = normalizedOptions.getPreviousPageParam;
-
-	const queryClient = useQueryClient();
-	const argsKey = useMemo(() => stableSerialize(args), [args]);
-	const finalQueryKey = useMemo<QueryKey>(
-		() => buildQueryKey(queryKey, handler, argsKey),
-		[queryKey, handler, argsKey]
-	);
-
-	const infiniteQuery = useNativeInfiniteQuery<
-		PaginatedResult<TResult, TCursor>,
-		TError,
-		InfiniteData<PaginatedResult<TResult, TCursor>, TCursor>,
-		QueryKey,
-		TCursor
-	>({
-		queryKey: finalQueryKey,
-		initialPageParam: initialPageParam as TCursor,
-		getNextPageParam:
-			getNextPageParam ?? ((lastPage) => lastPage?.nextCursor ?? undefined),
-		getPreviousPageParam:
-			getPreviousPageParam ??
-			((firstPage) => firstPage?.prevCursor ?? undefined),
-		queryFn: ({ pageParam }) =>
-			handler(mergeArgsWithPageParam(args, pageParam as TCursor, pageParamKey)),
-		...(queryOptions ?? {}),
-	});
-
-	const handleIncomingPage = useCallback(
-		(
-			data?:
-				| PaginatedResult<TResult, TCursor>[]
-				| PaginatedResult<TResult, TCursor>
-				| null,
-			_message?: RealtimeMessage<PaginatedResult<TResult, TCursor>>
-		) => {
-			const nextFirstPage = Array.isArray(data) ? data[0] : undefined;
-			if (!nextFirstPage) return;
-			queryClient.setQueryData<
-				InfiniteData<PaginatedResult<TResult, TCursor>, TCursor>
-			>(finalQueryKey, (prev) =>
-				prev
-					? {
-							...prev,
-							pages: prev.pages.map((page, index) =>
-								index === 0 ? nextFirstPage : page
-							),
-						}
-					: prev
-			);
-		},
-		[finalQueryKey, queryClient]
-	);
-	const deps = useMemo(() => [argsKey], [argsKey]);
-
-	const websocket = useRealtimeSubscription({
-		handler,
-		args,
-		realtime,
-		finalQueryKey,
-		deps,
-		applyIncoming: handleIncomingPage,
-	});
-
-	return { ...infiniteQuery, websocket };
-}
-
-function mergeArgsWithPageParam<TArgs, TPageParam>(
-	args: TArgs | undefined,
-	pageParam: TPageParam,
-	pageParamKey?: string
-): TArgs {
-	if (!pageParamKey) return (args ?? (pageParam as unknown as TArgs)) as TArgs;
-	if (typeof args === "object" && args !== null) {
-		return { ...(args as any), [pageParamKey]: pageParam } as TArgs;
-	}
-	if (args === undefined) {
-		return { [pageParamKey]: pageParam } as unknown as TArgs;
-	}
-	return args as TArgs;
-}

package/react/hooks/useQuery.ts

@@ -1,106 +0,0 @@
-import { useCallback, useMemo } from "react";
-import {
-	QueryKey,
-	UseQueryOptions,
-	UseQueryResult,
-	useQuery as useNativeQuery,
-	useQueryClient,
-} from "@tanstack/react-query";
-import {
-	RealtimeHookOptions,
-	RealtimeMessage,
-	HandlerWithRealtime,
-	HandlerWebsocketOptions,
-	buildQueryKey,
-	stableSerialize,
-	useRealtimeSubscription,
-} from "../shared/queryShared";
-
-export type UseAppflareQueryOptions<TArgs, TResult, TError = unknown> = {
-	handler: HandlerWithRealtime<TArgs, TResult>;
-	args?: TArgs;
-	queryKey?: QueryKey;
-	queryOptions?: Omit<UseQueryOptions<TResult, TError>, "queryFn" | "queryKey">;
-	realtime?: boolean | RealtimeHookOptions<TResult>;
-};
-
-export type UseAppflareQueryResult<TResult, TError = unknown> = UseQueryResult<
-	TResult,
-	TError
-> & { websocket: WebSocket | null };
-
-export function useQuery<TArgs, TResult, TError = unknown>(
-	options: UseAppflareQueryOptions<TArgs, TResult, TError>
-): UseAppflareQueryResult<TResult, TError>;
-
-export function useQuery<TArgs, TResult, TError = unknown>(
-	handler: HandlerWithRealtime<TArgs, TResult>,
-	options?: Omit<UseAppflareQueryOptions<TArgs, TResult, TError>, "handler">
-): UseAppflareQueryResult<TResult, TError>;
-
-export function useQuery<TArgs, TResult, TError = unknown>(
-	optionsOrHandler:
-		| UseAppflareQueryOptions<TArgs, TResult, TError>
-		| HandlerWithRealtime<TArgs, TResult>,
-	options?: Omit<UseAppflareQueryOptions<TArgs, TResult, TError>, "handler">
-): UseAppflareQueryResult<TResult, TError> {
-	const normalizedOptions = useMemo(
-		() =>
-			typeof optionsOrHandler === "function"
-				? ({
-						handler: optionsOrHandler,
-						...(options ?? {}),
-					} as UseAppflareQueryOptions<TArgs, TResult, TError>)
-				: optionsOrHandler,
-		[optionsOrHandler, options]
-	);
-
-	const realtime = normalizedOptions.realtime;
-	const handler = normalizedOptions.handler;
-	const args = normalizedOptions.args;
-	const queryKey = normalizedOptions.queryKey;
-	const queryOptions = normalizedOptions.queryOptions;
-
-	const queryClient = useQueryClient();
-	const argsKey = useMemo(() => stableSerialize(args), [args]);
-	const finalQueryKey = useMemo<QueryKey>(
-		() => buildQueryKey(queryKey, handler, argsKey),
-		[queryKey, handler, argsKey]
-	);
-
-	const query = useNativeQuery<TResult, TError>({
-		queryKey: finalQueryKey,
-		queryFn: () => handler(args),
-		...(queryOptions ?? {}),
-	});
-
-	const handleIncomingData = useCallback(
-		(
-			data?: TResult[] | TResult | null,
-			_message?: RealtimeMessage<TResult>
-		) => {
-			if (!Array.isArray(data)) return;
-			queryClient.setQueryData(finalQueryKey, () => data as unknown as TResult);
-		},
-		[finalQueryKey, queryClient]
-	);
-	const deps = useMemo(() => [argsKey], [argsKey]);
-
-	const websocket = useRealtimeSubscription({
-		handler,
-		args,
-		realtime,
-		finalQueryKey,
-		deps,
-		applyIncoming: handleIncomingData,
-	});
-
-	return { ...query, websocket };
-}
-
-export type {
-	RealtimeMessage,
-	HandlerWebsocketOptions,
-	HandlerWithRealtime,
-	RealtimeHookOptions,
-} from "../shared/queryShared";

package/react/shared/queryShared.ts

@@ -1,174 +0,0 @@
-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[];
-	headers?: Record<string, string>;
-	signal?: AbortSignal;
-	websocketImpl?: (
-		url: string,
-		protocols?: string | string[],
-		options?: { headers?: Record<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);
-}