@lovrozagar/flare 0.6.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lovrozagar/flare",
-	"version": "0.6.0",
+	"version": "0.7.1",
 	"description": "Solid meta-framework. Server-driven, NDJSON streaming, renderToStream.",
 	"keywords": [
 		"flare",

package/src/plugins/server-fn.ts

@@ -605,7 +605,7 @@ export function createServerFnPlugin(_config?: { ignorePrefix?: string }): ViteP
 				if (hasServerFnCalls(transformed)) {
 					transformed = replaceServerFnConfigs(transformed, (content) => {
 						const fnId = computeFnId(id, content);
-						return ` __id: "${fnId}",${content}`;
+						return ` __client: true, __id: "${fnId}",${content}`;
 					});
 				}
 

package/src/server/index.ts

@@ -54,7 +54,7 @@ export interface ServerBuilder<
 					callerData?: unknown[];
 					env: TEnv;
 					request: Request;
-					serverContext: Record<string, unknown>;
+					serverContext: TServerContext;
 					url: URL;
 				}) => TNewAuth | null | Promise<TNewAuth | null>,
 			) => ServerBuilder<TExcluded | "authenticateFn", TNewAuth, TServerContext, TEnv>;
@@ -72,12 +72,7 @@ export interface ServerBuilder<
 		: (
 				config:
 					| SecurityConfig
-					| ((ctx: {
-							env: TEnv;
-							nonce: string;
-							request: Request;
-							serverContext: Record<string, unknown>;
-					  }) => SecurityConfig),
+					| ((ctx: { env: TEnv; nonce: string; request: Request; serverContext: TServerContext }) => SecurityConfig),
 			) => ServerBuilder<TExcluded | "security", TAuth, TServerContext, TEnv>;
 	serverContext: "serverContext" extends TExcluded
 		? never

package/src/server-fn/index.ts

@@ -1,4 +1,6 @@
+import type { ResolvedAuth, ResolvedEnv, ResolvedServerContext } from "../route-builder/register.ts";
 import { FORM_FN_FIELD, parseServerFnPathname, serverFnPath } from "../protocol.ts";
+import { callServerFnOverHttp } from "./rpc.ts";
 import {
 	isNotFoundError,
 	isRedirectResponse,
@@ -26,6 +28,8 @@ import { runValidator } from "../validation/index.ts";
 export type { Validator } from "../validation/index.ts";
 
 export interface ServerFnConfig {
+	/** Set by the client build transform: calls go over HTTP, the handler body is gone. */
+	__client?: boolean;
 	__id?: string;
 	method?: "get" | "post";
 	name: string;
@@ -36,7 +40,8 @@ export interface PiggybackedQuery {
 	key: unknown[];
 }
 
-export interface HandlerContext<TAuth, TInput, TEnv = unknown> {
+/* TEnv defaults to the app's registered env (`createServer<Env>()`) */
+export interface HandlerContext<TAuth, TInput, TEnv = ResolvedEnv> {
 	auth: TAuth;
 	env: TEnv;
 	input: TInput;
@@ -53,15 +58,17 @@ export interface HandlerContext<TAuth, TInput, TEnv = unknown> {
 	piggyback: (key: unknown[], data: unknown) => void;
 	request: Request;
 	revalidate: RevalidateFn;
-	serverContext: Record<string, unknown>;
+	/* the app's `.serverContext()` result, typed through FlareRegister */
+	serverContext: ResolvedServerContext;
 }
 
-export interface StreamContext<TAuth, TInput, TEnv = unknown> {
+export interface StreamContext<TAuth, TInput, TEnv = ResolvedEnv> {
 	auth: TAuth;
 	env: TEnv;
 	input: TInput;
 	request: Request;
-	serverContext: Record<string, unknown>;
+	/* the app's `.serverContext()` result, typed through FlareRegister */
+	serverContext: ResolvedServerContext;
 	signal: AbortSignal;
 }
 
@@ -75,18 +82,19 @@ export interface ServerFnRegistrationBase {
 }
 
 export interface ServerFnHandlerRegistration extends ServerFnRegistrationBase {
-	fn: (ctx: HandlerContext<unknown, unknown>) => unknown | Promise<unknown>;
+	fn: (ctx: HandlerContext<unknown, unknown, unknown>) => unknown | Promise<unknown>;
 	stream?: false;
 }
 
 export interface ServerFnStreamRegistration extends ServerFnRegistrationBase {
-	fn: (ctx: StreamContext<unknown, unknown>) => AsyncGenerator<unknown>;
+	fn: (ctx: StreamContext<unknown, unknown, unknown>) => AsyncGenerator<unknown>;
 	stream: true;
 }
 
 export type ServerFnRegistration = ServerFnHandlerRegistration | ServerFnStreamRegistration;
 
 interface BuilderState {
+	__client?: boolean;
 	__id?: string;
 	authenticate: boolean;
 	authorizeFn?: (ctx: { auth: unknown; input: unknown }) => boolean | Promise<boolean>;
@@ -95,22 +103,24 @@ interface BuilderState {
 	name: string;
 }
 
-interface ServerFnBuilderTerminal<TAuth, TInput, TOutput> {
-	handler(fn: (ctx: HandlerContext<TAuth, TInput>) => TOutput | Promise<TOutput>): ServerFn<TInput, TOutput>;
-	input<T>(validator: Validator<T>): ServerFnBuilderTerminal<TAuth, T, TOutput>;
+interface ServerFnBuilderTerminal<TAuth, TInput> {
+	/* the output type is the handler's: callers get it without restating it */
+	handler<TOutput>(fn: (ctx: HandlerContext<TAuth, TInput>) => TOutput | Promise<TOutput>): ServerFn<TInput, TOutput>;
+	input<T>(validator: Validator<T>): ServerFnBuilderTerminal<TAuth, T>;
 	stream<TChunk>(fn: (ctx: StreamContext<TAuth, TInput>) => AsyncGenerator<TChunk>): StreamFn<TInput, TChunk>;
 }
 
-interface ServerFnBuilderAfterAuth<TAuth, TInput, TOutput> extends ServerFnBuilderTerminal<TAuth, TInput, TOutput> {
+interface ServerFnBuilderAfterAuth<TAuth, TInput> extends ServerFnBuilderTerminal<TAuth, TInput> {
 	authorize(
 		fn: (ctx: { auth: TAuth; input: TInput }) => boolean | Promise<boolean>,
-	): ServerFnBuilderTerminal<TAuth, TInput, TOutput>;
-	input<T>(validator: Validator<T>): ServerFnBuilderAfterAuth<TAuth, T, TOutput>;
+	): ServerFnBuilderTerminal<TAuth, TInput>;
+	input<T>(validator: Validator<T>): ServerFnBuilderAfterAuth<TAuth, T>;
 }
 
-interface ServerFnBuilder<TAuth, TInput, TOutput> extends ServerFnBuilderAfterAuth<TAuth, TInput, TOutput> {
-	authenticate(): ServerFnBuilderAfterAuth<unknown, TInput, TOutput>;
-	input<T>(validator: Validator<T>): ServerFnBuilder<TAuth, T, TOutput>;
+interface ServerFnBuilder<TAuth, TInput> extends ServerFnBuilderAfterAuth<TAuth, TInput> {
+	/* the app's `authenticateFn` result, typed through FlareRegister */
+	authenticate(): ServerFnBuilderAfterAuth<ResolvedAuth<true>, TInput>;
+	input<T>(validator: Validator<T>): ServerFnBuilder<TAuth, T>;
 }
 
 export type ServerFn<_TInput, TOutput> = ((_input: _TInput) => Promise<TOutput>) & {
@@ -124,21 +134,27 @@ export type StreamFn<_TInput, TChunk> = ((
 	_registration?: ServerFnRegistration;
 };
 
-function createBuilderTerminal<TAuth, TInput, TOutput>(
-	state: BuilderState,
-): ServerFnBuilderTerminal<TAuth, TInput, TOutput> {
+function createBuilderTerminal<TAuth, TInput>(state: BuilderState): ServerFnBuilderTerminal<TAuth, TInput> {
 	return {
-		handler(fn) {
+		handler<TOutput>(fn: (ctx: HandlerContext<TAuth, TInput>) => TOutput | Promise<TOutput>) {
 			const registration: ServerFnHandlerRegistration = {
 				authenticate: state.authenticate,
 				authorizeFn: state.authorizeFn,
-				fn: fn as (ctx: HandlerContext<unknown, unknown>) => unknown | Promise<unknown>,
+				fn: fn as (ctx: HandlerContext<unknown, unknown, unknown>) => unknown | Promise<unknown>,
 				id: state.__id && state.__id.length > 0 ? state.__id : state.name,
 				input: state.input,
 				method: state.method,
 				name: state.name,
 			};
 
+			if (state.__client) {
+				/* browser: the server validates, authenticates, and runs the handler */
+				const clientFn: ServerFn<TInput, TOutput> = async (input: TInput): Promise<TOutput> =>
+					(await callServerFnOverHttp<TOutput>(registration, input)).data;
+				clientFn._registration = registration;
+				return clientFn;
+			}
+
 			const serverFn: ServerFn<TInput, TOutput> = async (_input: TInput): Promise<TOutput> => {
 				if (state.authenticate) {
 					throw new Error(
@@ -156,7 +172,8 @@ function createBuilderTerminal<TAuth, TInput, TOutput>(
 				};
 				return await fn({
 					auth: null as TAuth,
-					env: {},
+					/* direct server-side invocation runs outside a request: there are no bindings */
+					env: {} as ResolvedEnv,
 					input: validated,
 					piggyback: () => {},
 					request: new Request("http://localhost"),
@@ -168,7 +185,7 @@ function createBuilderTerminal<TAuth, TInput, TOutput>(
 			return serverFn;
 		},
 		input<T>(validator: Validator<T>) {
-			return createBuilderTerminal<TAuth, T, TOutput>({
+			return createBuilderTerminal<TAuth, T>({
 				...state,
 				input: validator as Validator<unknown>,
 			});
@@ -177,7 +194,7 @@ function createBuilderTerminal<TAuth, TInput, TOutput>(
 			const registration: ServerFnStreamRegistration = {
 				authenticate: state.authenticate,
 				authorizeFn: state.authorizeFn,
-				fn: fn as (ctx: StreamContext<unknown, unknown>) => AsyncGenerator<unknown>,
+				fn: fn as (ctx: StreamContext<unknown, unknown, unknown>) => AsyncGenerator<unknown>,
 				id: state.__id && state.__id.length > 0 ? state.__id : state.name,
 				input: state.input,
 				method: state.method,
@@ -206,7 +223,7 @@ function createBuilderTerminal<TAuth, TInput, TOutput>(
 									const validated = (await validatedPromise) as TInput;
 									generator = fn({
 										auth: null as TAuth,
-										env: {} as unknown,
+										env: {} as ResolvedEnv,
 										input: validated,
 										request: new Request("http://localhost"),
 										serverContext: getServerContext(),
@@ -231,19 +248,17 @@ function createBuilderTerminal<TAuth, TInput, TOutput>(
 	};
 }
 
-function createBuilderAfterAuth<TAuth, TInput, TOutput>(
-	state: BuilderState,
-): ServerFnBuilderAfterAuth<TAuth, TInput, TOutput> {
+function createBuilderAfterAuth<TAuth, TInput>(state: BuilderState): ServerFnBuilderAfterAuth<TAuth, TInput> {
 	return {
-		...createBuilderTerminal<TAuth, TInput, TOutput>(state),
+		...createBuilderTerminal<TAuth, TInput>(state),
 		authorize(fn) {
-			return createBuilderTerminal<TAuth, TInput, TOutput>({
+			return createBuilderTerminal<TAuth, TInput>({
 				...state,
 				authorizeFn: fn as (ctx: { auth: unknown; input: unknown }) => boolean | Promise<boolean>,
 			});
 		},
 		input<T>(validator: Validator<T>) {
-			return createBuilderAfterAuth<TAuth, T, TOutput>({
+			return createBuilderAfterAuth<TAuth, T>({
 				...state,
 				input: validator as Validator<unknown>,
 			});
@@ -251,17 +266,17 @@ function createBuilderAfterAuth<TAuth, TInput, TOutput>(
 	};
 }
 
-function createBuilder<TAuth, TInput, TOutput>(state: BuilderState): ServerFnBuilder<TAuth, TInput, TOutput> {
+function createBuilder<TAuth, TInput>(state: BuilderState): ServerFnBuilder<TAuth, TInput> {
 	return {
-		...createBuilderAfterAuth<TAuth, TInput, TOutput>(state),
+		...createBuilderAfterAuth<TAuth, TInput>(state),
 		authenticate() {
-			return createBuilderAfterAuth<unknown, TInput, TOutput>({
+			return createBuilderAfterAuth<ResolvedAuth<true>, TInput>({
 				...state,
 				authenticate: true,
 			});
 		},
 		input<T>(validator: Validator<T>) {
-			return createBuilder<TAuth, T, TOutput>({
+			return createBuilder<TAuth, T>({
 				...state,
 				input: validator as Validator<unknown>,
 			});
@@ -269,8 +284,9 @@ function createBuilder<TAuth, TInput, TOutput>(state: BuilderState): ServerFnBui
 	};
 }
 
-export function createServerFn(config: ServerFnConfig): ServerFnBuilder<null, void, unknown> {
-	return createBuilder<null, void, unknown>({
+export function createServerFn(config: ServerFnConfig): ServerFnBuilder<null, void> {
+	return createBuilder<null, void>({
+		__client: config.__client,
 		__id: config.__id,
 		authenticate: false,
 		method: config.method ?? "post",

package/src/server-fn/rpc.ts

@@ -0,0 +1,41 @@
+/**
+ * Browser side of a server fn call: one HTTP request to `/_flare/server-fn/{id}/{name}`.
+ * Client-safe — must not import server-context or anything that reaches node:*.
+ */
+
+import { serverFnPath } from "../protocol.ts";
+import { serverFnGetUrl } from "./get-input.ts";
+import { throwServerFnHttpError } from "./http-error.ts";
+
+export interface ServerFnTarget {
+	id?: string;
+	method?: string;
+	name: string;
+}
+
+export interface ServerFnEnvelope<TOutput> {
+	data: TOutput;
+	queries?: Array<{ data: unknown; key: unknown[] }>;
+	revalidatedTags?: string[];
+}
+
+export async function callServerFnOverHttp<TOutput>(
+	target: ServerFnTarget,
+	input: unknown,
+): Promise<ServerFnEnvelope<TOutput>> {
+	const url = serverFnPath(target.id ?? target.name, target.name);
+	const res =
+		target.method === "get"
+			? await fetch(serverFnGetUrl(url, input))
+			: await fetch(url, {
+					body: input !== undefined ? JSON.stringify(input) : undefined,
+					headers: { "content-type": "application/json" },
+					method: "POST",
+				});
+
+	if (!res.ok) {
+		const body: unknown = await res.json().catch(() => null);
+		throwServerFnHttpError(body, res.status, target.name);
+	}
+	return (await res.json()) as ServerFnEnvelope<TOutput>;
+}

package/src/server-fn-query.ts

@@ -4,9 +4,7 @@
  * to avoid pulling in node:async_hooks on the client.
  */
 
-import { serverFnGetUrl } from "./server-fn/get-input.ts";
-import { throwServerFnHttpError } from "./server-fn/http-error.ts";
-import { serverFnPath } from "./protocol.ts";
+import { callServerFnOverHttp } from "./server-fn/rpc.ts";
 
 export interface PiggybackedQuery {
 	data: unknown;
@@ -52,28 +50,7 @@ export function serverFnQueryOptions<TInput, TOutput>(
 				return serverFn(config?.input as TInput);
 			}
 
-			const url = serverFnPath(id, name);
-			const method = reg?.method ?? "post";
-
-			const res =
-				method === "get"
-					? await fetch(serverFnGetUrl(url, config?.input))
-					: await fetch(url, {
-							body: config?.input !== undefined ? JSON.stringify(config.input) : undefined,
-							headers: { "content-type": "application/json" },
-							method: "POST",
-						});
-
-			if (!res.ok) {
-				const body: unknown = await res.json().catch(() => null);
-				throwServerFnHttpError(body, res.status, name);
-			}
-
-			const json = (await res.json()) as {
-				data: TOutput;
-				queries?: Array<{ data: unknown; key: unknown[] }>;
-				revalidatedTags?: string[];
-			};
+			const json = await callServerFnOverHttp<TOutput>({ id, method: reg?.method ?? "post", name }, config?.input);
 
 			if (json.queries && config?.queryClient) {
 				for (const q of json.queries) {
@@ -117,23 +94,8 @@ export function serverFnMutationOptions<TInput, TOutput>(
 				return serverFn(input);
 			}
 
-			const url = serverFnPath(id, name);
-			const res = await fetch(url, {
-				body: input !== undefined ? JSON.stringify(input) : undefined,
-				headers: { "content-type": "application/json" },
-				method: "POST",
-			});
-
-			if (!res.ok) {
-				const body: unknown = await res.json().catch(() => null);
-				throwServerFnHttpError(body, res.status, name);
-			}
-
-			const json = (await res.json()) as {
-				data: TOutput;
-				queries?: Array<{ data: unknown; key: unknown[] }>;
-				revalidatedTags?: string[];
-			};
+			/* mutations always POST, whatever the fn's own method */
+			const json = await callServerFnOverHttp<TOutput>({ id, method: "post", name }, input);
 
 			if (json.queries && config?.queryClient) {
 				for (const q of json.queries) {