mtmsdk 0.0.50 → 0.0.52

package/src/supabase/use-sb-query/use-rpc-query.ts

@@ -1,231 +1,267 @@
-/**
- * 简化版的 Supabase RPC 查询 Hook
- * 自动处理 Supabase Client 的获取，无需手动调用 useSupabaseBrowser()
- *
- * 使用示例:
- * ```tsx
- * // 方式1: 自动推断类型
- * const query1 = useRpcQuery("dash_navitems_list", { p_location: "sidebar_admin" });
- *
- * // 方式2: 使用 Zod Schema 进行类型验证和推断 (推荐)
- * const navItemSchema = z.object({ label: z.string(), url: z.string().optional() });
- * const query2 = useRpcQuery("dash_navitems_list", { p_location: "sidebar_admin" }, {
- *   schema: z.object({ rows: z.array(navItemSchema) })
- * });
- * // data 的类型为 { rows: { label: string; url?: string }[] } | undefined
- *
- * // 方式3: 显式泛型指定返回类型
- * type NavItem = { label: string; url?: string };
- * const query3 = useRpcQuery<NavItem[]>("dash_navitems_list", { p_location: "sidebar_admin" });
- * ```
- */
-
-import { useMemo } from "react";
-import type { z } from "zod";
-import type { SBFunctions } from "../../types";
-import { useSupabaseBrowser } from "../context";
-import {
-    KEY_PREFIX,
-    type UseQueryAnyReturn,
-    type UseQuerySingleReturn,
-    useSbQuery,
-    useSbSuspenseQuery,
-} from "./use-query";
-
-/** 从 SBFunctions 中提取 RPC 函数名的类型 */
-export type RPCFunctionName = keyof SBFunctions;
-
-/**
- * 获取 RPC 查询的通用 Query Key 前缀 (用于 invalidation)
- * 对应 supabase-cache-helpers 生成的 key 结构: ['postgrest', 'null'|'page', schema, table|rpc, ...]
- *
- * @param functionName RPC 函数名
- * @returns Standard Query Key Prefix e.g. ["postgrest", "null", "public", "function_name"]
- */
-export function getRpcQueryKey(functionName: string): string[] {
-  // 默认 schema 为 public, infinite prefix 默认为 "null" (即使是 infinite query, invalidate prefix 通常也能匹配?)
-  // 注意: explicit invalidation 最好匹配 prefix.
-  // supabase-cache-helpers 的 getSbTableKey 返回的是 4 个元素
-  // 注: 对于 RPC，表名解析为 rpc/名称
-  return [KEY_PREFIX, "null", "public", `rpc/${functionName}`];
-}
-
-/** 提取指定 RPC 函数的参数类型 */
-export type RPCFunctionArgs<T extends RPCFunctionName> = SBFunctions[T]["Args"] extends never
-  ? Record<string, never>
-  : SBFunctions[T]["Args"];
-
-/** 提取指定 RPC 函数的返回类型 */
-export type RPCFunctionReturns<T extends RPCFunctionName> = SBFunctions[T]["Returns"];
-
-/**
- * RPC 查询的额外选项
- */
-export interface RpcQueryOptions {
-  /**
-   * 可选的 Zod Schema 用于验证和推断返回类型
-   * 当传入时，将自动验证数据并从 schema 推断类型
-   *
-   * @example
-   * ```tsx
-   * const navItemSchema = z.object({ label: z.string(), url: z.string().optional() });
-   * const resultSchema = z.object({ rows: z.array(navItemSchema), meta: z.any() });
-   *
-   * const { data } = useRpcQuery("dash_navitems_list", { p_location: "sidebar_admin" }, {
-   *   schema: resultSchema
-   * });
-   * // data 类型自动推断为 { rows: { label: string; url?: string }[]; meta: any } | undefined
-   * ```
-   */
-  schema?: z.ZodType;
-}
-
-/**
- * 基于 RPC 函数名和参数进行查询的 Hook (普通模式)
- *
- * @template TData 返回数据类型（显式指定或从数据库函数推断）
- * @param functionName RPC 函数名
- * @param args RPC 函数参数
- * @param options 配置选项，包含 React Query 配置和可选的 schema
- * @returns 查询结果
- *
- * @example
- * ```tsx
- * // 示例1: 基础使用（自动推断）
- * const { data } = useRpcQuery("sys_config_get", { p_key: "github_app" });
- *
- * // 示例2: 使用 Zod Schema（推荐）
- * const navItemSchema = z.object({ label: z.string(), url: z.string().optional() });
- * const { data } = useRpcQuery("dash_navitems_list", { p_location: "sidebar_admin" }, {
- *   schema: z.object({ rows: z.array(navItemSchema), meta: z.any() })
- * });
- *
- * // 示例3: 显式泛型
- * type NavItem = { label: string; url?: string };
- * const { data } = useRpcQuery<NavItem[]>("dash_navitems_list", { p_location: "sidebar_admin" });
- * ```
- */
-// Overload 1: Schema provided -> Infer TData from Schema
-export function useRpcQuery<TFunc extends RPCFunctionName, TSchema extends z.ZodType>(
-  functionName: TFunc,
-  args: RPCFunctionArgs<TFunc> | undefined,
-  options: { schema: TSchema } & Record<string, any>,
-): UseQuerySingleReturn<z.infer<TSchema>>;
-
-// Overload 2: No schema provided -> Infer TData from Generic (defaulting to RPC return)
-export function useRpcQuery<TFunc extends RPCFunctionName, TData = RPCFunctionReturns<TFunc>>(
-  functionName: TFunc,
-  args?: RPCFunctionArgs<TFunc>,
-  options?: { schema?: undefined } & Record<string, any>,
-): UseQueryAnyReturn<TData>;
-
-// Overload 3: Legacy/Fallback
-export function useRpcQuery<TData = any>(
-  functionName: string,
-  args?: any,
-  options?: { schema?: z.ZodType } & Record<string, any>,
-): UseQueryAnyReturn<TData>;
-
-export function useRpcQuery<TFunc extends RPCFunctionName, TData = RPCFunctionReturns<TFunc>>(
-  functionName: TFunc,
-  args?: RPCFunctionArgs<TFunc>,
-  options?: RpcQueryOptions & Record<string, any>,
-): UseQueryAnyReturn<TData> {
-  const sb = useSupabaseBrowser();
-  const query = sb.rpc(functionName, args as never);
-
-  const { schema, ...reactQueryConfig } = options || {};
-
-  // biome-ignore lint/suspicious/noExplicitAny: 绕过 Supabase 内部类型系统
-  const baseResult = useSbQuery(query as any, reactQueryConfig);
-
-  // 如果提供了 schema，对数据进行验证和转换
-  const transformedResult = useMemo(() => {
-    if (!schema || !baseResult.data) {
-      return baseResult;
-    }
-
-    try {
-      const validatedData = schema.parse(baseResult.data);
-      return {
-        ...baseResult,
-        data: validatedData as TData,
-      };
-    } catch (error) {
-      console.error(`[useRpcQuery] Schema validation failed for ${String(functionName)}:`, error);
-      // 验证失败时返回原始数据，避免阻断用户流程
-      return baseResult;
-    }
-  }, [schema, baseResult, functionName]);
-
-  return transformedResult as UseQueryAnyReturn<TData>;
-}
-
-/**
- * 基于 RPC 函数名和参数进行查询的 Hook (Suspense 模式)
- *
- * @template TData 返回数据类型（通过 schema 或泛型指定）
- * @param functionName RPC 函数名
- * @param args RPC 函数参数
- * @param options 配置选项
- * @returns Suspense 查询结果
- *
- * @example
- * ```tsx
- * const navItemSchema = z.object({ label: z.string(), url: z.string().optional() });
- * const { data } = useRpcSuspenseQuery("dash_navitems_list", { p_location: "sidebar_admin" }, {
- *   schema: z.object({ rows: z.array(navItemSchema) })
- * });
- * // data 类型: { rows: { label: string; url?: string }[] }
- * ```
- */
-// Overload 1: Schema provided
-export function useRpcSuspenseQuery<TFunc extends RPCFunctionName, TSchema extends z.ZodType>(
-  functionName: TFunc,
-  args: RPCFunctionArgs<TFunc> | undefined,
-  // biome-ignore lint/suspicious/noExplicitAny: 允许传入 schema
-  options: { schema: TSchema } & Omit<any, "queryKey" | "queryFn">,
-): { data: z.infer<TSchema>; [key: string]: unknown };
-
-// Overload 2: No schema
-export function useRpcSuspenseQuery<TFunc extends RPCFunctionName, TData = RPCFunctionReturns<TFunc>>(
-  functionName: TFunc,
-  args?: RPCFunctionArgs<TFunc>,
-  // biome-ignore lint/suspicious/noExplicitAny: 普通模式
-  options?: { schema?: undefined } & Omit<any, "queryKey" | "queryFn">,
-): { data: TData; [key: string]: unknown };
-
-export function useRpcSuspenseQuery<TFunc extends RPCFunctionName, TData = RPCFunctionReturns<TFunc>>(
-  functionName: TFunc,
-  args?: RPCFunctionArgs<TFunc>,
-  // biome-ignore lint/suspicious/noExplicitAny: 绕过 Supabase 和 ReactQuery 过于复杂的类型推断系统，保持对外类型安全
-  options?: RpcQueryOptions & Omit<any, "queryKey" | "queryFn">,
-): { data: TData; [key: string]: unknown } {
-  const sb = useSupabaseBrowser();
-  const query = sb.rpc(functionName, args as never);
-
-  const { schema, ...reactQueryConfig } = options || {};
-
-  // biome-ignore lint/suspicious/noExplicitAny: 绕过 Supabase 内部类型系统
-  const baseResult = useSbSuspenseQuery(query as any, reactQueryConfig);
-
-  // 如果提供了 schema，对数据进行验证和转换
-  const transformedResult = useMemo(() => {
-    if (!schema) {
-      return baseResult;
-    }
-
-    try {
-      const validatedData = schema.parse(baseResult.data);
-      return {
-        ...baseResult,
-        data: validatedData as TData,
-      };
-    } catch (error) {
-      console.error(`[useRpcSuspenseQuery] Schema validation failed for ${String(functionName)}:`, error);
-      return baseResult;
-    }
-  }, [schema, baseResult, functionName]);
-
-  return transformedResult as { data: TData; [key: string]: unknown };
-}
+/**
+ * 简化版的 Supabase RPC 查询 Hook
+ * 自动处理 Supabase Client 的获取，无需手动调用 useSupabaseBrowser()
+ *
+ * 使用示例:
+ * ```tsx
+ * // 方式1: 自动推断类型
+ * const query1 = useRpcQuery("dash_navitems_list", { p_location: "sidebar_admin" });
+ *
+ * // 方式2: 使用 Zod Schema 进行类型验证和推断 (推荐)
+ * const navItemSchema = z.object({ label: z.string(), url: z.string().optional() });
+ * const query2 = useRpcQuery("dash_navitems_list", { p_location: "sidebar_admin" }, {
+ *   schema: z.object({ rows: z.array(navItemSchema) })
+ * });
+ * // data 的类型为 { rows: { label: string; url?: string }[] } | undefined
+ *
+ * // 方式3: 显式泛型指定返回类型
+ * type NavItem = { label: string; url?: string };
+ * const query3 = useRpcQuery<NavItem[]>("dash_navitems_list", { p_location: "sidebar_admin" });
+ * ```
+ */
+
+import { useMemo } from "react";
+import type { PostgrestError } from "@supabase/postgrest-js";
+import type { z } from "zod";
+import type { SBFunctions } from "../../types";
+import { useSupabaseBrowser } from "../context";
+import {
+    KEY_PREFIX,
+    type UseQueryAnyReturn,
+    useSbQuery,
+    useSbSuspenseQuery,
+} from "./use-query";
+
+/** 从 SBFunctions 中提取 RPC 函数名的类型 */
+export type RPCFunctionName = keyof SBFunctions;
+
+/**
+ * 获取 RPC 查询的通用 Query Key 前缀 (用于 invalidation)
+ * 对应 supabase-cache-helpers 生成的 key 结构: ['postgrest', 'null'|'page', schema, table|rpc, ...]
+ *
+ * @param functionName RPC 函数名
+ * @returns Standard Query Key Prefix e.g. ["postgrest", "null", "public", "function_name"]
+ */
+export function getRpcQueryKey(functionName: string): string[] {
+  // 默认 schema 为 public, infinite prefix 默认为 "null" (即使是 infinite query, invalidate prefix 通常也能匹配?)
+  // 注意: explicit invalidation 最好匹配 prefix.
+  // supabase-cache-helpers 的 getSbTableKey 返回的是 4 个元素
+  // 注: 对于 RPC，表名解析为 rpc/名称
+  return [KEY_PREFIX, "null", "public", `rpc/${functionName}`];
+}
+
+/** 提取指定 RPC 函数的参数类型 */
+export type RPCFunctionArgs<T extends RPCFunctionName> = SBFunctions[T]["Args"] extends never
+  ? Record<string, never>
+  : SBFunctions[T]["Args"];
+
+/** 提取指定 RPC 函数的返回类型 */
+export type RPCFunctionReturns<T extends RPCFunctionName> = SBFunctions[T]["Returns"];
+
+type RpcExtraQueryOptions<TSchema extends z.ZodTypeAny | undefined = undefined> = {
+  /**
+   * 可选的 Zod Schema 用于验证和推断返回类型
+   * 当传入时，将自动验证数据并从 schema 推断类型
+   *
+   * @example
+   * ```tsx
+   * const navItemSchema = z.object({ label: z.string(), url: z.string().optional() });
+   * const resultSchema = z.object({ rows: z.array(navItemSchema), meta: z.any() });
+   *
+   * const { data } = useRpcQuery("dash_navitems_list", { p_location: "sidebar_admin" }, {
+   *   schema: resultSchema
+   * });
+   * // data 类型自动推断为 { rows: { label: string; url?: string }[]; meta: any } | undefined
+   * ```
+   */
+  schema?: TSchema;
+  queryKeySuffix?: readonly unknown[];
+};
+
+type RpcQueryOptions<TSchema extends z.ZodTypeAny | undefined = undefined> = RpcExtraQueryOptions<TSchema> &
+  Record<string, unknown>;
+
+type RpcSuspenseQueryOptions<TSchema extends z.ZodTypeAny | undefined = undefined> = RpcExtraQueryOptions<TSchema> &
+  Record<string, unknown>;
+
+type UseRpcSchemaQueryReturn<TData> = Omit<UseQueryAnyReturn<unknown>, "data" | "error"> & {
+  data: TData | undefined;
+  error: PostgrestError | RpcSchemaValidationError | null;
+};
+
+class RpcSchemaValidationError extends Error {
+  readonly functionName: RPCFunctionName;
+  readonly originalError: Error;
+
+  constructor(functionName: RPCFunctionName, error: Error) {
+    super(`[${String(functionName)}] RPC 响应不符合 schema: ${error.message}`);
+    this.name = "RpcSchemaValidationError";
+    this.functionName = functionName;
+    this.originalError = error;
+  }
+}
+
+function validateRpcData<TSchema extends z.ZodTypeAny>(
+  hookName: "useRpcQuery" | "useRpcSuspenseQuery",
+  functionName: RPCFunctionName,
+  schema: TSchema,
+  data: unknown,
+): { success: true; data: z.infer<TSchema> } | { success: false; error: RpcSchemaValidationError } {
+  const result = schema.safeParse(data);
+  if (result.success) {
+    return {
+      success: true,
+      data: result.data,
+    };
+  }
+
+  console.error(`[${hookName}] Schema validation failed for ${String(functionName)}:`, result.error);
+  return {
+    success: false,
+    error: new RpcSchemaValidationError(functionName, result.error),
+  };
+}
+
+/**
+ * 基于 RPC 函数名和参数进行查询的 Hook (普通模式)
+ *
+ * @template TData 返回数据类型（显式指定或从数据库函数推断）
+ * @param functionName RPC 函数名
+ * @param args RPC 函数参数
+ * @param options 配置选项，包含 React Query 配置和可选的 schema
+ * @returns 查询结果
+ *
+ * @example
+ * ```tsx
+ * // 示例1: 基础使用（自动推断）
+ * const { data } = useRpcQuery("sys_config_get", { p_key: "github_app" });
+ *
+ * // 示例2: 使用 Zod Schema（推荐）
+ * const navItemSchema = z.object({ label: z.string(), url: z.string().optional() });
+ * const { data } = useRpcQuery("dash_navitems_list", { p_location: "sidebar_admin" }, {
+ *   schema: z.object({ rows: z.array(navItemSchema), meta: z.any() })
+ * });
+ *
+ * // 示例3: 显式泛型
+ * type NavItem = { label: string; url?: string };
+ * const { data } = useRpcQuery<NavItem[]>("dash_navitems_list", { p_location: "sidebar_admin" });
+ * ```
+ */
+// Overload 1: Schema provided -> Infer TData from Schema
+export function useRpcQuery<TFunc extends RPCFunctionName, TSchema extends z.ZodTypeAny>(
+  functionName: TFunc,
+  args: RPCFunctionArgs<TFunc> | undefined,
+  options: RpcQueryOptions<TSchema> & { schema: TSchema },
+): UseRpcSchemaQueryReturn<z.infer<TSchema>>;
+
+// Overload 2: No schema provided -> Infer TData from Generic (defaulting to RPC return)
+export function useRpcQuery<TFunc extends RPCFunctionName, TData = RPCFunctionReturns<TFunc>>(
+  functionName: TFunc,
+  args?: RPCFunctionArgs<TFunc>,
+  options?: RpcQueryOptions<undefined> & { schema?: undefined },
+): UseQueryAnyReturn<TData>;
+
+export function useRpcQuery<TFunc extends RPCFunctionName, TData = RPCFunctionReturns<TFunc>>(
+  functionName: TFunc,
+  args?: RPCFunctionArgs<TFunc>,
+  options?: RpcQueryOptions,
+): UseQueryAnyReturn<TData> {
+  const sb = useSupabaseBrowser();
+  const query = sb.rpc(functionName, args as never);
+
+  const { schema, ...reactQueryConfig } = options || {};
+
+  // biome-ignore lint/suspicious/noExplicitAny: 绕过 Supabase 内部类型系统
+  const baseResult = useSbQuery(query as any, reactQueryConfig as any);
+
+  // 如果提供了 schema，对数据进行验证和转换
+  const transformedResult = useMemo(() => {
+    if (!schema || baseResult.error || baseResult.data === undefined) {
+      return baseResult;
+    }
+
+    const validationResult = validateRpcData("useRpcQuery", functionName, schema, baseResult.data);
+    if (validationResult.success) {
+      return {
+        ...baseResult,
+        data: validationResult.data as TData,
+      };
+    }
+
+    return {
+      ...baseResult,
+      data: undefined,
+      error: validationResult.error,
+      isError: true,
+      isSuccess: false,
+      status: "error",
+    } as unknown as UseQueryAnyReturn<TData>;
+  }, [schema, baseResult, functionName]);
+
+  return transformedResult as UseQueryAnyReturn<TData>;
+}
+
+/**
+ * 基于 RPC 函数名和参数进行查询的 Hook (Suspense 模式)
+ *
+ * @template TData 返回数据类型（通过 schema 或泛型指定）
+ * @param functionName RPC 函数名
+ * @param args RPC 函数参数
+ * @param options 配置选项
+ * @returns Suspense 查询结果
+ *
+ * @example
+ * ```tsx
+ * const navItemSchema = z.object({ label: z.string(), url: z.string().optional() });
+ * const { data } = useRpcSuspenseQuery("dash_navitems_list", { p_location: "sidebar_admin" }, {
+ *   schema: z.object({ rows: z.array(navItemSchema) })
+ * });
+ * // data 类型: { rows: { label: string; url?: string }[] }
+ * ```
+ */
+// Overload 1: Schema provided
+export function useRpcSuspenseQuery<TFunc extends RPCFunctionName, TSchema extends z.ZodTypeAny>(
+  functionName: TFunc,
+  args: RPCFunctionArgs<TFunc> | undefined,
+  options: RpcSuspenseQueryOptions<TSchema> & { schema: TSchema },
+): { data: z.infer<TSchema>; [key: string]: unknown };
+
+// Overload 2: No schema
+export function useRpcSuspenseQuery<TFunc extends RPCFunctionName, TData = RPCFunctionReturns<TFunc>>(
+  functionName: TFunc,
+  args?: RPCFunctionArgs<TFunc>,
+  options?: RpcSuspenseQueryOptions<undefined> & { schema?: undefined },
+): { data: TData; [key: string]: unknown };
+
+export function useRpcSuspenseQuery<TFunc extends RPCFunctionName, TData = RPCFunctionReturns<TFunc>>(
+  functionName: TFunc,
+  args?: RPCFunctionArgs<TFunc>,
+  options?: RpcSuspenseQueryOptions,
+): { data: TData; [key: string]: unknown } {
+  const sb = useSupabaseBrowser();
+  const query = sb.rpc(functionName, args as never);
+
+  const { schema, ...reactQueryConfig } = options || {};
+
+  // biome-ignore lint/suspicious/noExplicitAny: 绕过 Supabase 内部类型系统
+  const baseResult = useSbSuspenseQuery(query as any, reactQueryConfig as any);
+
+  // 如果提供了 schema，对数据进行验证和转换
+  const transformedData = useMemo(() => {
+    if (!schema) {
+      return baseResult.data as TData;
+    }
+
+    const validationResult = validateRpcData("useRpcSuspenseQuery", functionName, schema, baseResult.data);
+    if (!validationResult.success) {
+      throw validationResult.error;
+    }
+
+    return validationResult.data as TData;
+  }, [schema, baseResult.data, functionName]);
+
+  return {
+    ...baseResult,
+    data: transformedData,
+  } as { data: TData; [key: string]: unknown };
+}