silgi 0.0.13 → 0.1.0-beta.1

package/dist/integrations/react/index.d.mts

@@ -0,0 +1,83 @@
+import { ProcedureDef, RouterDef } from "../../types.mjs";
+
+//#region src/integrations/react/index.d.ts
+type ActionResult<TOutput> = [error: null, data: TOutput] | [error: {
+  code: string;
+  status: number;
+  message: string;
+  data?: unknown;
+}, data: undefined];
+/**
+ * Create a server action from a v2 ProcedureDef.
+ *
+ * @example
+ * ```ts
+ * // app/actions.ts
+ * "use server"
+ * import { createAction } from "silgi/react"
+ *
+ * export const createUser = createAction(appRouter.users.create)
+ *
+ * // app/page.tsx
+ * const [error, user] = await createUser({ name: "Alice" })
+ * ```
+ */
+declare function createAction<TInput = unknown, TOutput = unknown>(procedure: ProcedureDef): (input: TInput) => Promise<ActionResult<TOutput>>;
+/**
+ * Create a FormData-accepting server action from a v2 procedure.
+ */
+declare function createFormAction<TOutput = unknown>(procedure: ProcedureDef, options?: {
+  parseFormData?: (fd: FormData) => unknown;
+}): (formData: FormData) => Promise<ActionResult<TOutput>>;
+/**
+ * Create actions for all procedures in a router.
+ *
+ * @example
+ * ```ts
+ * const actions = createActions(appRouter)
+ * const [error, users] = await actions.users.list({ limit: 10 })
+ * ```
+ */
+declare function createActions<T extends RouterDef>(router: T): ActionRouter<T>;
+/**
+ * React hook for calling server actions with loading/error state.
+ *
+ * @example
+ * ```tsx
+ * const { execute, data, error, isPending } = useServerAction(createUser)
+ *
+ * <button onClick={() => execute({ name: "Alice" })} disabled={isPending}>
+ *   {isPending ? "Creating..." : "Create User"}
+ * </button>
+ * ```
+ */
+declare function useServerAction<TInput, TOutput>(action: (input: TInput) => Promise<ActionResult<TOutput>>): {
+  execute: any;
+  data: any;
+  error: any;
+  isPending: any;
+  reset: any;
+};
+/**
+ * React hook for server actions with optimistic UI updates.
+ *
+ * @example
+ * ```tsx
+ * const { execute, data, optimisticData, isPending } = useOptimisticServerAction(updateUser, {
+ *   optimistic: (input) => ({ ...currentUser, ...input }),
+ * })
+ * ```
+ */
+declare function useOptimisticServerAction<TInput, TOutput>(action: (input: TInput) => Promise<ActionResult<TOutput>>, options: {
+  optimistic: (input: TInput) => TOutput;
+}): {
+  execute: any; /** Confirmed server data */
+  data: any; /** Optimistic data (shown while pending, cleared on settle) */
+  optimisticData: any; /** The value to display: optimistic while pending, confirmed otherwise */
+  displayData: any;
+  error: any;
+  isPending: any;
+};
+type ActionRouter<T extends RouterDef> = { [K in keyof T]: T[K] extends ProcedureDef<any, infer TInput, infer TOutput> ? (input: TInput extends undefined ? void : TInput) => Promise<ActionResult<TOutput>> : T[K] extends RouterDef ? ActionRouter<T[K]> : never };
+//#endregion
+export { ActionResult, createAction, createActions, createFormAction, useOptimisticServerAction, useServerAction };

package/dist/integrations/react/index.mjs

@@ -0,0 +1,197 @@
+import { __require } from "../../_virtual/_rolldown/runtime.mjs";
+import { SilgiError, toSilgiError } from "../../core/error.mjs";
+import { compileProcedure } from "../../compile.mjs";
+//#region src/integrations/react/index.ts
+/**
+* React Server Actions — v2 integration.
+*
+* Creates type-safe server actions from v2 procedures.
+* Returns [error, data] tuples instead of throwing.
+*/
+/**
+* Create a server action from a v2 ProcedureDef.
+*
+* @example
+* ```ts
+* // app/actions.ts
+* "use server"
+* import { createAction } from "silgi/react"
+*
+* export const createUser = createAction(appRouter.users.create)
+*
+* // app/page.tsx
+* const [error, user] = await createUser({ name: "Alice" })
+* ```
+*/
+function createAction(procedure) {
+	const handler = compileProcedure(procedure);
+	const signal = new AbortController().signal;
+	return async (input) => {
+		try {
+			const result = handler(Object.create(null), input, signal);
+			return [null, result instanceof Promise ? await result : result];
+		} catch (error) {
+			if (isFrameworkError(error)) throw error;
+			return [(error instanceof SilgiError ? error : toSilgiError(error)).toJSON(), void 0];
+		}
+	};
+}
+/**
+* Create a FormData-accepting server action from a v2 procedure.
+*/
+function createFormAction(procedure, options) {
+	const action = createAction(procedure);
+	const parse = options?.parseFormData ?? defaultFormDataParser;
+	return (formData) => action(parse(formData));
+}
+/**
+* Create actions for all procedures in a router.
+*
+* @example
+* ```ts
+* const actions = createActions(appRouter)
+* const [error, users] = await actions.users.list({ limit: 10 })
+* ```
+*/
+function createActions(router) {
+	const result = {};
+	for (const [key, value] of Object.entries(router)) if (isProcedureDef(value)) result[key] = createAction(value);
+	else if (typeof value === "object" && value !== null) result[key] = createActions(value);
+	return result;
+}
+/**
+* React hook for calling server actions with loading/error state.
+*
+* @example
+* ```tsx
+* const { execute, data, error, isPending } = useServerAction(createUser)
+*
+* <button onClick={() => execute({ name: "Alice" })} disabled={isPending}>
+*   {isPending ? "Creating..." : "Create User"}
+* </button>
+* ```
+*/
+function useServerAction(action) {
+	const { useState, useCallback, useRef } = __require("react");
+	const [data, setData] = useState(void 0);
+	const [error, setError] = useState(null);
+	const [isPending, setIsPending] = useState(false);
+	const mountedRef = useRef(true);
+	const { useEffect } = __require("react");
+	useEffect(() => {
+		mountedRef.current = true;
+		return () => {
+			mountedRef.current = false;
+		};
+	}, []);
+	return {
+		execute: useCallback(async (input) => {
+			setIsPending(true);
+			setError(null);
+			try {
+				const [err, result] = await action(input);
+				if (!mountedRef.current) return;
+				if (err) {
+					setError(err);
+					setData(void 0);
+				} else {
+					setData(result);
+					setError(null);
+				}
+				return [err, result];
+			} finally {
+				if (mountedRef.current) setIsPending(false);
+			}
+		}, [action]),
+		data,
+		error,
+		isPending,
+		reset: useCallback(() => {
+			setData(void 0);
+			setError(null);
+			setIsPending(false);
+		}, [])
+	};
+}
+/**
+* React hook for server actions with optimistic UI updates.
+*
+* @example
+* ```tsx
+* const { execute, data, optimisticData, isPending } = useOptimisticServerAction(updateUser, {
+*   optimistic: (input) => ({ ...currentUser, ...input }),
+* })
+* ```
+*/
+function useOptimisticServerAction(action, options) {
+	const { useState, useCallback, useRef } = __require("react");
+	const { useEffect } = __require("react");
+	const [data, setData] = useState(void 0);
+	const [optimisticData, setOptimisticData] = useState(void 0);
+	const [error, setError] = useState(null);
+	const [isPending, setIsPending] = useState(false);
+	const mountedRef = useRef(true);
+	useEffect(() => {
+		mountedRef.current = true;
+		return () => {
+			mountedRef.current = false;
+		};
+	}, []);
+	return {
+		execute: useCallback(async (input) => {
+			setIsPending(true);
+			setError(null);
+			setOptimisticData(options.optimistic(input));
+			try {
+				const [err, result] = await action(input);
+				if (!mountedRef.current) return;
+				if (err) {
+					setError(err);
+					setOptimisticData(void 0);
+				} else {
+					setData(result);
+					setOptimisticData(void 0);
+				}
+				return [err, result];
+			} catch (e) {
+				if (mountedRef.current) setOptimisticData(void 0);
+				throw e;
+			} finally {
+				if (mountedRef.current) setIsPending(false);
+			}
+		}, [action, options.optimistic]),
+		data,
+		optimisticData,
+		displayData: optimisticData ?? data,
+		error,
+		isPending
+	};
+}
+function isProcedureDef(v) {
+	return typeof v === "object" && v !== null && "type" in v && "resolve" in v;
+}
+function isFrameworkError(error) {
+	if (typeof error !== "object" || error === null) return false;
+	if (typeof error.digest === "string" && error.digest.startsWith("NEXT_")) return true;
+	if (error.isNotFound === true) return true;
+	if (error instanceof Response) return true;
+	return false;
+}
+function defaultFormDataParser(formData) {
+	const result = {};
+	for (const [key, value] of formData.entries()) setNestedValue(result, key, value instanceof File && value.size === 0 ? void 0 : value);
+	return result;
+}
+function setNestedValue(obj, path, value) {
+	const keys = path.split("[").map((k) => k.replace("]", ""));
+	let current = obj;
+	for (let i = 0; i < keys.length - 1; i++) {
+		const k = keys[i];
+		const next = keys[i + 1];
+		if (!(k in current)) current[k] = /^\d+$/.test(next) ? [] : {};
+		current = current[k];
+	}
+	current[keys[keys.length - 1]] = value;
+}
+//#endregion
+export { createAction, createActions, createFormAction, useOptimisticServerAction, useServerAction };

package/dist/integrations/tanstack-query/index.d.mts

@@ -0,0 +1,120 @@
+import { Client, NestedClient } from "../../client/types.mjs";
+
+//#region src/integrations/tanstack-query/index.d.ts
+type OperationType = 'query' | 'infinite' | 'mutation';
+type OperationKey = [path: readonly string[], options: {
+  type?: OperationType;
+  input?: unknown;
+}];
+declare function generateKey(path: readonly string[], options?: {
+  type?: OperationType;
+  input?: unknown;
+}): OperationKey;
+interface QueryOptionsIn<TInput, TOutput, _TError> {
+  input: TInput;
+  queryKey?: unknown[];
+  enabled?: boolean;
+  staleTime?: number;
+  gcTime?: number;
+  refetchInterval?: number | false;
+  retry?: boolean | number;
+  select?: (data: TOutput) => unknown;
+}
+interface MutationOptionsIn<TInput, TOutput, TError> {
+  onSuccess?: (data: TOutput, input: TInput) => void;
+  onError?: (error: TError, input: TInput) => void;
+  onSettled?: (data: TOutput | undefined, error: TError | null, input: TInput) => void;
+  retry?: boolean | number;
+}
+/** Sentinel value to disable a query in a type-safe way. */
+declare const skipToken: unique symbol;
+type SkipToken = typeof skipToken;
+interface InfiniteQueryOptionsIn<TInput, TOutput, _TError, TPageParam> {
+  input: (pageParam: TPageParam) => TInput;
+  initialPageParam: TPageParam;
+  getNextPageParam: (lastPage: TOutput, allPages: TOutput[], lastPageParam: TPageParam) => TPageParam | undefined;
+  queryKey?: unknown[];
+  enabled?: boolean;
+  staleTime?: number;
+  gcTime?: number;
+}
+interface ProcedureQueryUtils<TInput, TOutput, TError> {
+  /** Direct call to the procedure */
+  call: (input: TInput, options?: {
+    signal?: AbortSignal;
+  }) => Promise<TOutput>;
+  /** Generate a query key for this procedure */
+  queryKey: (input?: TInput) => OperationKey;
+  /** Generate full query options for useQuery. Pass `skipToken` as input to disable. */
+  queryOptions: (options: QueryOptionsIn<TInput | SkipToken, TOutput, TError>) => {
+    queryKey: OperationKey;
+    queryFn: (ctx: {
+      signal: AbortSignal;
+    }) => Promise<TOutput>;
+    enabled?: boolean;
+    staleTime?: number;
+    gcTime?: number;
+    refetchInterval?: number | false;
+    retry?: boolean | number;
+    select?: (data: TOutput) => unknown;
+  };
+  /** Generate infinite query options for useInfiniteQuery */
+  infiniteOptions: <TPageParam = number>(options: InfiniteQueryOptionsIn<TInput, TOutput, TError, TPageParam>) => {
+    queryKey: OperationKey;
+    queryFn: (ctx: {
+      signal: AbortSignal;
+      pageParam: TPageParam;
+    }) => Promise<TOutput>;
+    initialPageParam: TPageParam;
+    getNextPageParam: (lastPage: TOutput, allPages: TOutput[], lastPageParam: TPageParam) => TPageParam | undefined;
+    enabled?: boolean;
+    staleTime?: number;
+    gcTime?: number;
+  };
+  /** Generate streamed query options — data appends to array as events arrive */
+  streamedOptions: (options: QueryOptionsIn<TInput, TOutput[], TError>) => {
+    queryKey: OperationKey;
+    queryFn: (ctx: {
+      signal: AbortSignal;
+    }) => Promise<TOutput[]>;
+    enabled?: boolean;
+    staleTime?: number;
+    gcTime?: number;
+  };
+  /** Generate live query options — latest event replaces previous data */
+  liveOptions: (options: QueryOptionsIn<TInput, TOutput, TError>) => {
+    queryKey: OperationKey;
+    queryFn: (ctx: {
+      signal: AbortSignal;
+    }) => Promise<TOutput>;
+    refetchInterval: number;
+    enabled?: boolean;
+    staleTime?: number;
+    gcTime?: number;
+  };
+  /** Generate a mutation key */
+  mutationKey: () => OperationKey;
+  /** Generate full mutation options for useMutation */
+  mutationOptions: (options?: MutationOptionsIn<TInput, TOutput, TError>) => {
+    mutationKey: OperationKey;
+    mutationFn: (input: TInput) => Promise<TOutput>;
+    onSuccess?: (data: TOutput, input: TInput) => void;
+    onError?: (error: TError, input: TInput) => void;
+    onSettled?: (data: TOutput | undefined, error: TError | null, input: TInput) => void;
+    retry?: boolean | number;
+  };
+}
+interface GeneralUtils {
+  /** Generate a key prefix for bulk invalidation */
+  key: (input?: unknown) => OperationKey;
+}
+type QueryUtils<T extends NestedClient> = T extends Client<any, infer TInput, infer TOutput, infer TError> ? ProcedureQueryUtils<TInput, TOutput, TError> & GeneralUtils : T extends Record<string, NestedClient> ? { [K in keyof T]: QueryUtils<T[K]> } & GeneralUtils : GeneralUtils;
+/**
+ * Create TanStack Query utilities from a Silgi client.
+ *
+ * Returns a recursive proxy that mirrors the client structure,
+ * with `.queryOptions()`, `.mutationOptions()`, `.queryKey()` at each level.
+ */
+declare function createQueryUtils<T extends NestedClient>(client: T, path?: readonly string[]): QueryUtils<T>;
+//#endregion
+export { GeneralUtils, InfiniteQueryOptionsIn, MutationOptionsIn, OperationKey, OperationType, ProcedureQueryUtils, QueryOptionsIn, QueryUtils, SkipToken, createQueryUtils, generateKey, skipToken };

package/dist/integrations/tanstack-query/index.mjs

@@ -0,0 +1,100 @@
+//#region src/integrations/tanstack-query/index.ts
+function generateKey(path, options) {
+	const keyOptions = {};
+	if (options?.type) keyOptions.type = options.type;
+	if (options?.input !== void 0) keyOptions.input = options.input;
+	return [path, keyOptions];
+}
+/** Sentinel value to disable a query in a type-safe way. */
+const skipToken = Symbol.for("silgi.skipToken");
+function createProcedureUtils(client, path) {
+	return {
+		call: (input, options) => client(input, options),
+		queryKey: (input) => generateKey(path, {
+			type: "query",
+			input
+		}),
+		queryOptions: (options) => {
+			const isSkipped = options.input === skipToken;
+			return {
+				queryKey: options.queryKey ? options.queryKey : generateKey(path, {
+					type: "query",
+					input: isSkipped ? void 0 : options.input
+				}),
+				queryFn: ({ signal }) => client(options.input, { signal }),
+				...isSkipped && { enabled: false },
+				...options.enabled !== void 0 && { enabled: options.enabled },
+				...options.staleTime !== void 0 && { staleTime: options.staleTime },
+				...options.gcTime !== void 0 && { gcTime: options.gcTime },
+				...options.refetchInterval !== void 0 && { refetchInterval: options.refetchInterval },
+				...options.retry !== void 0 && { retry: options.retry },
+				...options.select !== void 0 && { select: options.select }
+			};
+		},
+		infiniteOptions: (options) => ({
+			queryKey: options.queryKey ? options.queryKey : generateKey(path, { type: "infinite" }),
+			queryFn: ({ signal, pageParam }) => client(options.input(pageParam), { signal }),
+			initialPageParam: options.initialPageParam,
+			getNextPageParam: options.getNextPageParam,
+			...options.enabled !== void 0 && { enabled: options.enabled },
+			...options.staleTime !== void 0 && { staleTime: options.staleTime },
+			...options.gcTime !== void 0 && { gcTime: options.gcTime }
+		}),
+		streamedOptions: (options) => ({
+			queryKey: options.queryKey ? options.queryKey : generateKey(path, {
+				type: "query",
+				input: options.input
+			}),
+			queryFn: async ({ signal }) => {
+				const result = await client(options.input, { signal });
+				if (result && typeof result === "object" && Symbol.asyncIterator in result) {
+					const items = [];
+					for await (const item of result) items.push(item);
+					return items;
+				}
+				return Array.isArray(result) ? result : [result];
+			},
+			...options.enabled !== void 0 && { enabled: options.enabled },
+			...options.staleTime !== void 0 && { staleTime: options.staleTime },
+			...options.gcTime !== void 0 && { gcTime: options.gcTime }
+		}),
+		liveOptions: (options) => ({
+			queryKey: options.queryKey ? options.queryKey : generateKey(path, {
+				type: "query",
+				input: options.input
+			}),
+			queryFn: ({ signal }) => client(options.input, { signal }),
+			refetchInterval: options.refetchInterval ?? 1e3,
+			...options.enabled !== void 0 && { enabled: options.enabled },
+			...options.staleTime !== void 0 && { staleTime: options.staleTime },
+			...options.gcTime !== void 0 && { gcTime: options.gcTime }
+		}),
+		mutationKey: () => generateKey(path, { type: "mutation" }),
+		mutationOptions: (options) => ({
+			mutationKey: generateKey(path, { type: "mutation" }),
+			mutationFn: (input) => client(input),
+			...options
+		})
+	};
+}
+/**
+* Create TanStack Query utilities from a Silgi client.
+*
+* Returns a recursive proxy that mirrors the client structure,
+* with `.queryOptions()`, `.mutationOptions()`, `.queryKey()` at each level.
+*/
+function createQueryUtils(client, path = []) {
+	const generalUtils = { key: (input) => generateKey(path, input !== void 0 ? { input } : void 0) };
+	const procedureUtils = typeof client === "function" ? createProcedureUtils(client, path) : {};
+	return new Proxy({}, { get(_target, prop) {
+		if (prop === "then") return void 0;
+		if (prop === "key") return generalUtils.key;
+		if (typeof prop === "string" && prop in procedureUtils) return procedureUtils[prop];
+		if (typeof prop === "string") {
+			const child = client[prop];
+			if (child) return createQueryUtils(child, [...path, prop]);
+		}
+	} });
+}
+//#endregion
+export { createQueryUtils, generateKey, skipToken };

package/dist/integrations/tanstack-query/ssr.d.mts

@@ -0,0 +1,51 @@
+//#region src/integrations/tanstack-query/ssr.d.ts
+/**
+ * SSR Hydration for TanStack Query — prevent refetch waterfalls.
+ *
+ * Prefetch queries on the server and dehydrate them for the client.
+ * The client hydrates without refetching — zero waterfall.
+ *
+ * @example
+ * ```ts
+ * // Server (SSR)
+ * import { prefetchQueries, dehydrate } from "silgi/tanstack-query/ssr"
+ *
+ * const queryClient = new QueryClient()
+ * await prefetchQueries(queryClient, utils, [
+ *   utils.users.list.queryOptions({ input: { limit: 10 } }),
+ *   utils.health.queryOptions({ input: undefined }),
+ * ])
+ * const dehydratedState = dehydrate(queryClient)
+ *
+ * // Client
+ * <HydrationBoundary state={dehydratedState}>
+ *   <App />
+ * </HydrationBoundary>
+ * ```
+ */
+/**
+ * Prefetch multiple queries on the server.
+ * Pass the same options you'd use with `useQuery`.
+ */
+declare function prefetchQueries(queryClient: any, ...optionsArray: Array<{
+  queryKey: unknown;
+  queryFn: Function;
+} | Array<{
+  queryKey: unknown;
+  queryFn: Function;
+}>>): Promise<void>;
+/**
+ * Dehydrate the query client for SSR transfer.
+ * Wraps TanStack Query's dehydrate with Silgi-aware serialization.
+ */
+declare function dehydrate(queryClient: any): unknown;
+/**
+ * Create a custom serializer for SSR hydration that handles
+ * Silgi-specific types (Date, Map, etc.) during dehydration.
+ */
+declare function createSSRSerializer(): {
+  serialize: (value: unknown) => string;
+  deserialize: (text: string) => unknown;
+};
+//#endregion
+export { createSSRSerializer, dehydrate, prefetchQueries };

package/dist/integrations/tanstack-query/ssr.mjs

@@ -0,0 +1,89 @@
+//#region src/integrations/tanstack-query/ssr.ts
+/**
+* SSR Hydration for TanStack Query — prevent refetch waterfalls.
+*
+* Prefetch queries on the server and dehydrate them for the client.
+* The client hydrates without refetching — zero waterfall.
+*
+* @example
+* ```ts
+* // Server (SSR)
+* import { prefetchQueries, dehydrate } from "silgi/tanstack-query/ssr"
+*
+* const queryClient = new QueryClient()
+* await prefetchQueries(queryClient, utils, [
+*   utils.users.list.queryOptions({ input: { limit: 10 } }),
+*   utils.health.queryOptions({ input: undefined }),
+* ])
+* const dehydratedState = dehydrate(queryClient)
+*
+* // Client
+* <HydrationBoundary state={dehydratedState}>
+*   <App />
+* </HydrationBoundary>
+* ```
+*/
+/**
+* Prefetch multiple queries on the server.
+* Pass the same options you'd use with `useQuery`.
+*/
+async function prefetchQueries(queryClient, ...optionsArray) {
+	const flat = optionsArray.flat();
+	await Promise.all(flat.map((opts) => queryClient.prefetchQuery(opts)));
+}
+/**
+* Dehydrate the query client for SSR transfer.
+* Wraps TanStack Query's dehydrate with Silgi-aware serialization.
+*/
+function dehydrate(queryClient) {
+	if (typeof queryClient.dehydrate === "function") return queryClient.dehydrate();
+	const cache = queryClient.getQueryCache?.();
+	if (!cache) return {};
+	return { queries: cache.getAll().map((query) => ({
+		queryKey: query.queryKey,
+		state: query.state
+	})) };
+}
+/**
+* Create a custom serializer for SSR hydration that handles
+* Silgi-specific types (Date, Map, etc.) during dehydration.
+*/
+function createSSRSerializer() {
+	return {
+		serialize: (value) => {
+			return JSON.stringify(value, function(_key, val) {
+				const original = this[_key];
+				if (original instanceof Date) return {
+					__type: "Date",
+					value: original.toISOString()
+				};
+				if (original instanceof Map) return {
+					__type: "Map",
+					value: Array.from(original.entries())
+				};
+				if (original instanceof Set) return {
+					__type: "Set",
+					value: Array.from(original)
+				};
+				if (typeof original === "bigint") return {
+					__type: "BigInt",
+					value: original.toString()
+				};
+				return val;
+			});
+		},
+		deserialize: (text) => {
+			return JSON.parse(text, (_key, val) => {
+				if (val && typeof val === "object" && "__type" in val) switch (val.__type) {
+					case "Date": return new Date(val.value);
+					case "Map": return new Map(val.value);
+					case "Set": return new Set(val.value);
+					case "BigInt": return BigInt(val.value);
+				}
+				return val;
+			});
+		}
+	};
+}
+//#endregion
+export { createSSRSerializer, dehydrate, prefetchQueries };