mtmsdk 0.0.52 → 0.0.53

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

@@ -1,267 +0,0 @@
-/**
- * 简化版的 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 };
-}

package/src/supabase/utils.ts

@@ -1,75 +0,0 @@
-// --- 类型工具定义开始 ---
-
-import type { SBFunctions, TypedSupabaseClient } from "../types";
-
-export type SnakeCase<S extends string> = S extends `${infer T}${infer U}`
-	? `${T extends Uncapitalize<T> ? T : `_${Lowercase<T>}`}${SnakeCase<U>}`
-	: S;
-
-export type DbFunctionParams<T> = {
-	// 遍历 Key -> 转换为 snake_case -> 添加 p_ 前缀
-	[K in keyof T as `p_${SnakeCase<string & K>}`]: T[K];
-};
-const toSnakeCase = (str: string) => {
-	return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
-};
-/**
- * 实用工具, 将参数的名称,添加"p_"前缀,并且以"snake_case"的方式转换参数名称.
- * 原因是 postgresql 函数,都约定了这样的参数形式.
- *
- * Input: { chatId: string } -> Output Type: { p_chat_id: string }
- * Input: { chat_id: string } -> Output Type: { p_chat_id: string }
- */
-export const convertToDbFunctionParams = <InputT extends Record<string, any>>(
-	input: InputT,
-): DbFunctionParams<InputT> => {
-	const result: Record<string, any> = {};
-
-	// biome-ignore lint/complexity/noForEach: .
-	Object.entries(input).forEach(([key, value]) => {
-		const snakeKey = toSnakeCase(key);
-		const newKey = `p_${snakeKey}`;
-		result[newKey] = value;
-	});
-	return result as DbFunctionParams<InputT>;
-};
-
-export const sbRpc = async <
-	TRpcName extends keyof SBFunctions,
-	TInput extends Record<string, any>,
->(
-	sb: TypedSupabaseClient,
-	rpcName: TRpcName,
-
-	// 3. 【核心黑魔法】在参数位置进行校验
-	//    我们允许传入 input: TInput
-	//    但是，我们附加了一个“条件类型”检查：
-	//    如果 "转换后的类型" (DbFunctionParams<TInput>) 不能赋值给 "数据库要求的类型" (SBFunctions[TRpcName]["Args"])
-	//    那么，我们将 input 的类型强制判定为 never (导致报错) 或者给出一个具体的错误提示类型。
-	input: TInput &
-		(DbFunctionParams<TInput> extends SBFunctions[TRpcName]["Args"]
-			? unknown // 如果匹配，啥也不做，类型检查通过
-			: // 如果不匹配，返回数据库需要的类型，这样 IDE 会提示缺少什么属性
-				SBFunctions[TRpcName]["Args"]),
-	// 或者更高级一点，返回一个去除 p_ 前缀的提示类型（取决于你的偏好）
-) => {
-	return await sb.rpc(rpcName as any, convertToDbFunctionParams(input) as any);
-};
-
-
-/**
- * 仅作为类型测试,用于确认 sbRpc 的正确实现.
- * @param sb
- * @returns
- */
-export const sbRpcTesting = async (sb: TypedSupabaseClient) => {
-	//用例1: 正确的参数
-	await sbRpc(sb, "chat_message_list", { chat_id: "123" });
-	await sbRpc(sb, "chat_message_list", { p_chat_id: "123" });
-	await sbRpc(sb, "chat_message_list", { chatId: "123" });
-	// await sbRpc(sb, "chat_message_list", { ChatId: "123" });
-
-	//用例2: 以下应当出现类型错误
-	//不正确的参数名称
-	//await sbRpc(sb, "chat_message_list", { chat_id_xxxx: "123" });
-};