mtmsdk 0.0.51 → 0.0.52

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

@@ -1,340 +1,352 @@
-/**
- * 将 supabase api封装位 react query的 形式.
- * 原官方库: https://github.com/psteinroe/supabase-cache-helpers
- */
-
-import type {
-  AnyPostgrestResponse,
-  BuildNormalizedQueryOps,
-  PostgrestQueryParserOptions,
-} from "@supabase-cache-helpers/postgrest-core";
-import { PostgrestFilter, encodeObject, type DecodedKey } from "@supabase-cache-helpers/postgrest-core";
-import type {
-  PostgrestError,
-  PostgrestMaybeSingleResponse,
-  PostgrestResponse,
-  PostgrestResponseSuccess,
-  PostgrestSingleResponse,
-} from "@supabase/postgrest-js";
-import {
-  useQueryClient,
-  useQuery as useReactQuery,
-  useSuspenseQuery as useReactSuspenseQuery,
-  type UseQueryOptions as UseReactQueryOptions,
-  type UseQueryResult as UseReactQueryResult,
-  type UseSuspenseQueryResult as UseReactSuspenseQueryResult,
-  type UseSuspenseQueryOptions as UserReactSuspenseQueryOptions,
-} from "@tanstack/react-query";
-import { buildQueryOpts, buildSuspenseQueryOpts } from "./build-query-opts";
-import { decode, encode } from "./key";
-
-export const KEY_PREFIX = "postgrest";
-export const INFINITE_KEY_PREFIX = "page";
-
-export type DecodedReactQueryKey = DecodedKey & {
-  isInfinite: boolean;
-  key: string[];
-};
-
-export const POSTGREST_FILTER_KEY_PREFIX = "postgrest-filter";
-
-export const usePostgrestFilterCache = <R extends Record<string, unknown>>() => {
-  const queryClient = useQueryClient();
-
-  return (query: string, opts?: PostgrestQueryParserOptions) => {
-    const key = [POSTGREST_FILTER_KEY_PREFIX, query, opts ? encodeObject(opts) : null];
-    const cacheData = queryClient.getQueryData(key);
-    if (cacheData instanceof PostgrestFilter) {
-      return cacheData;
-    }
-    const filter = PostgrestFilter.fromQuery(query, opts);
-    queryClient.setQueryData(key, filter);
-    return filter as PostgrestFilter<R>;
-  };
-};
-
-export const useQueriesForTableLoader = (table: string) => {
-  const queryClient = useQueryClient();
-  const getPostgrestFilter = usePostgrestFilterCache();
-
-  return () =>
-    queryClient
-      .getQueryCache()
-      .getAll()
-      .map((c) => c.queryKey)
-      .reduce<ReturnType<BuildNormalizedQueryOps["queriesForTable"]>>((prev, curr) => {
-        const decodedKey = decode(curr);
-        if (decodedKey?.table === table) {
-          prev.push(getPostgrestFilter(decodedKey.queryKey).params);
-        }
-        return prev;
-      }, []);
-};
-
-/**
- * Applies Omit over a union, while preserving its union-ness.
- */
-// biome-ignore lint/suspicious/noExplicitAny: keyof any 是 TypeScript 泛型约束的标准用法
-type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K> : never;
-
-/**
- * Represents the return value of the `useQuery` hook when `query` is expected to return
- * a single row.
- */
-export type UseQuerySingleReturn<Result> = DistributiveOmit<
-  UseReactQueryResult<PostgrestSingleResponse<Result>["data"], PostgrestError>,
-  "refetch"
-> &
-  Pick<UseReactQueryResult<PostgrestSingleResponse<Result>, PostgrestError>, "refetch"> &
-  Pick<PostgrestSingleResponse<Result>, "count">;
-
-/**
- * Represents the return value of the `useQuery` hook when `query` is expected to return
- * either a single row or an empty response.
- */
-export type UseQueryMaybeSingleReturn<Result> = DistributiveOmit<
-  UseReactQueryResult<PostgrestMaybeSingleResponse<Result>["data"], PostgrestError>,
-  "refetch"
-> &
-  Pick<UseReactQueryResult<PostgrestMaybeSingleResponse<Result>, PostgrestError>, "refetch"> &
-  Pick<PostgrestMaybeSingleResponse<Result>, "count">;
-
-/**
- * Represents the return value of the `useQuery` hook when `query` is expected to return
- * one or more rows.
- */
-export type UseQueryReturn<Result> = DistributiveOmit<
-  UseReactQueryResult<PostgrestResponse<Result>["data"], PostgrestError>,
-  "refetch"
-> &
-  Pick<UseReactQueryResult<PostgrestResponse<Result>, PostgrestError>, "refetch"> &
-  Pick<PostgrestResponse<Result>, "count">;
-
-/**
- * Represents the return value of the `useQuery` hook when the type of the query response
- * is not known.
- */
-export type UseQueryAnyReturn<Result> = DistributiveOmit<
-  UseReactQueryResult<AnyPostgrestResponse<Result>["data"], PostgrestError>,
-  "refetch"
-> &
-  Pick<UseReactQueryResult<AnyPostgrestResponse<Result>, PostgrestError>, "refetch"> &
-  Pick<AnyPostgrestResponse<Result>, "count">;
-
-/**
- * React hook to execute a PostgREST query and return a single item response.
- *
- * @param {PromiseLike<PostgrestSingleResponse<Result>>} query A promise that resolves to a PostgREST single item response.
- * @param {Omit<UseReactQueryOptions<PostgrestSingleResponse<Result>, PostgrestError>, 'queryKey' | 'queryFn'>} [config] The React Query options.
- * @returns {UseQuerySingleReturn<Result>} The hook result containing the single item response data.
- */
-function useQuery<Result>(
-  query: PromiseLike<PostgrestSingleResponse<Result>>,
-  config?: Omit<UseReactQueryOptions<PostgrestSingleResponse<Result>, PostgrestError>, "queryKey" | "queryFn">,
-): UseQuerySingleReturn<Result>;
-/**
- * React hook to execute a PostgREST query and return a maybe single item response.
- *
- * @param {PromiseLike<PostgrestMaybeSingleResponse<Result>>} query A promise that resolves to a PostgREST maybe single item response.
- * @param {Omit<UseReactQueryOptions<PostgrestMaybeSingleResponse<Result>, PostgrestError>, 'queryKey' | 'queryFn'>} [config] The React Query options.
- * @returns {UseQueryMaybeSingleReturn<Result>} The hook result containing the maybe single item response data.
- */
-function useQuery<Result>(
-  query: PromiseLike<PostgrestMaybeSingleResponse<Result>>,
-  config?: Omit<UseReactQueryOptions<PostgrestMaybeSingleResponse<Result>, PostgrestError>, "queryKey" | "queryFn">,
-): UseQueryMaybeSingleReturn<Result>;
-/**
- * React hook to execute a PostgREST query.
- *
- * @template Result The expected response data type.
- * @param {PromiseLike<PostgrestResponse<Result>>} query A promise that resolves to a PostgREST response.
- * @param {Omit<UseReactQueryOptions<PostgrestResponse<Result>, PostgrestError>, 'queryKey' | 'queryFn'>} [config] The React Query options.
- * @returns {UseQueryReturn<Result>} The hook result containing the response data.
- */
-function useQuery<Result>(
-  query: PromiseLike<PostgrestResponse<Result>>,
-  config?: Omit<UseReactQueryOptions<PostgrestResponse<Result>, PostgrestError>, "queryKey" | "queryFn">,
-): UseQueryReturn<Result>;
-
-/**
- * React hook to execute a PostgREST query.
- *
- * @template Result The expected response data type.
- * @param {PromiseLike<AnyPostgrestResponse<Result>>} query A promise that resolves to a PostgREST response of any kind.
- * @param {Omit<UseReactQueryOptions<AnyPostgrestResponse<Result>, PostgrestError>, 'queryKey' | 'queryFn'>} [config] The React Query options.
- * @returns {UseQueryAnyReturn<Result>} The hook result containing the response data.
- */
-function useQuery<Result>(
-  query: PromiseLike<AnyPostgrestResponse<Result>>,
-  config?: Omit<UseReactQueryOptions<AnyPostgrestResponse<Result>, PostgrestError>, "queryKey" | "queryFn">,
-): UseQueryAnyReturn<Result> {
-  const result = useReactQuery<AnyPostgrestResponse<Result>, PostgrestError>(buildQueryOpts<Result>(query, config));
-
-  // isPending and isLoadingError are the only cases in which no data is present
-  if (result.isPending || result.isLoadingError) {
-    return {
-      ...result,
-      data: undefined,
-      count: null,
-    } as UseQueryAnyReturn<Result>;
-  }
-
-  return {
-    ...result,
-    data: result.data?.data,
-    count: result.data?.count,
-  } as UseQueryAnyReturn<Result>;
-}
-
-export { useQuery };
-
-// 增加 queryQuery 获取函数
-
-/**
- * 获取 PostgREST 查询的完整 QueryKey
- * @param query Supabase PostgrestBuilder 实例 (例如: sb.from('...').select() 或 sb.rpc(...))
- * @param isInfinite 是否为无限查询 (默认 false)
- */
-export function getSbQueryKey<Result>(query: PromiseLike<AnyPostgrestResponse<Result>>, isInfinite = false): string[] {
-  return encode(query, isInfinite);
-}
-
-/**
- * 获取 PostgREST 查询的 "Base Key" (仅包含前缀、Schema、Table/RPC名称)
- * 用于 invalidateQueries 时模糊匹配整个表或RPC的所有查询，忽略具体的 filter/page 参数。
- *
- * 结构: ['postgrest', 'null'|'page', schema, table|rpc, ...]
- * 返回: 前4个元素
- */
-export function getSbTableKey<Result>(query: PromiseLike<AnyPostgrestResponse<Result>>): string[] {
-  const fullKey = encode(query, false);
-  // 截取前4个元素作为基础Key: [prefix, infinitePrefix, schema, table]
-  // 这样 invalidateQueries(baseKey) 将会匹配该表/RPC下的所有查询变体
-  return fullKey.slice(0, 4);
-}
-
-// 增加 suspense query 的支持 ========================================================================================
-
-/**
- * Represents the return value of the `useSuspenseQuery` hook when `query` is expected to return
- * a single row.
- */
-export type useSuspenseQuerySingleReturn<Result> = DistributiveOmit<
-  UseReactSuspenseQueryResult<PostgrestMaybeSingleResponseV4<Result>["data"], PostgrestError>,
-  "refetch"
-> &
-  Pick<
-    UseReactSuspenseQueryResult<
-      // PostgrestSingleResponse<Result>,
-      Result,
-      PostgrestError
-    >,
-    "refetch"
-  > &
-  Pick<PostgrestSingleResponse<Result>, "count">;
-
-export type PostgrestMaybeSingleResponseV4<T> = PostgrestResponseSuccess<T>;
-
-/**
- * Represents the return value of the `useSuspenseQuery` hook when `query` is expected to return
- * either a single row or an empty response.
- */
-export type useSuspenseQueryMaybeSingleReturn<Result> = DistributiveOmit<
-  UseReactSuspenseQueryResult<PostgrestMaybeSingleResponseV4<NonNullable<Result>>["data"], PostgrestError>,
-  "refetch"
-> &
-  Pick<UseReactSuspenseQueryResult<PostgrestMaybeSingleResponseV4<NonNullable<Result>>, PostgrestError>, "refetch"> &
-  Pick<PostgrestMaybeSingleResponseV4<Result>, "count">;
-
-/**
- * Represents the return value of the `useSuspenseQuery` hook when `query` is expected to return
- * one or more rows.
- */
-export type useSuspenseQueryReturn<Result> = DistributiveOmit<
-  UseReactSuspenseQueryResult<PostgrestResponse<Result>["data"], PostgrestError>,
-  "refetch"
-> &
-  Pick<UseReactSuspenseQueryResult<PostgrestResponse<Result>, PostgrestError>, "refetch"> &
-  Pick<PostgrestResponse<Result>, "count">;
-
-/**
- * Represents the return value of the `useSuspenseQuery` hook when the type of the query response
- * is not known.
- */
-export type useSuspenseQueryAnyReturn<Result> = DistributiveOmit<
-  UseReactSuspenseQueryResult<PostgrestResponse<Result>["data"], PostgrestError>,
-  "refetch"
-> &
-  Pick<UseReactSuspenseQueryResult<PostgrestResponse<Result>, PostgrestError>, "refetch"> &
-  Pick<PostgrestResponse<Result>, "count">;
-
-/**
- * React hook to execute a PostgREST query and return a single item response.
- *
- * @param {PromiseLike<PostgrestSingleResponse<Result>>} query A promise that resolves to a PostgREST single item response.
- * @param {Omit<UseReactQueryOptions<PostgrestSingleResponse<Result>, PostgrestError>, 'queryKey' | 'queryFn'>} [config] The React Query options.
- * @returns {useSuspenseQuerySingleReturn<Result>} The hook result containing the single item response data.
- */
-function useSbSuspenseQuery<Result>(
-  query: PromiseLike<PostgrestSingleResponse<Result>>,
-  config?: Omit<UseReactQueryOptions<PostgrestSingleResponse<Result>, PostgrestError>, "queryKey" | "queryFn">,
-): useSuspenseQuerySingleReturn<NonNullable<Result>>;
-/**
- * React hook to execute a PostgREST query and return a maybe single item response.
- *
- * @param {PromiseLike<PostgrestMaybeSingleResponse<Result>>} query A promise that resolves to a PostgREST maybe single item response.
- * @param {Omit<UseReactQueryOptions<PostgrestMaybeSingleResponse<Result>, PostgrestError>, 'queryKey' | 'queryFn'>} [config] The React Query options.
- * @returns {useSuspenseQueryMaybeSingleReturn<Result>} The hook result containing the maybe single item response data.
- */
-function useSbSuspenseQuery<Result>(
-  query: PromiseLike<PostgrestMaybeSingleResponse<Result>>,
-  config?: Omit<UseReactQueryOptions<PostgrestMaybeSingleResponse<Result>, PostgrestError>, "queryKey" | "queryFn">,
-): useSuspenseQueryMaybeSingleReturn<NonNullable<Result>>;
-/**
- * React hook to execute a PostgREST query.
- *
- * @template Result The expected response data type.
- * @param {PromiseLike<PostgrestResponse<Result>>} query A promise that resolves to a PostgREST response.
- * @param {Omit<UseReactQueryOptions<PostgrestResponse<Result>, PostgrestError>, 'queryKey' | 'queryFn'>} [config] The React Query options.
- * @returns {useSuspenseQueryReturn<Result>} The hook result containing the response data.
- */
-function useSbSuspenseQuery<Result>(
-  query: PromiseLike<PostgrestResponse<Result>>,
-  config?: Omit<UseReactQueryOptions<PostgrestResponse<Result>, PostgrestError>, "queryKey" | "queryFn">,
-): useSuspenseQueryReturn<NonNullable<Result>>;
-
-/**
- * React hook to execute a PostgREST query.
- *
- * @template Result The expected response data type.
- * @param {PromiseLike<AnyPostgrestResponse<Result>>} query A promise that resolves to a PostgREST response of any kind.
- * @param {Omit<UseReactQueryOptions<AnyPostgrestResponse<Result>, PostgrestError>, 'queryKey' | 'queryFn'>} [config] The React Query options.
- * @returns {useSuspenseQueryAnyReturn<Result>} The hook result containing the response data.
- */
-function useSbSuspenseQuery<Result>(
-  query: PromiseLike<PostgrestResponse<Result>>,
-  config?: Omit<UserReactSuspenseQueryOptions<AnyPostgrestResponse<Result>, PostgrestError>, "queryKey" | "queryFn">,
-): useSuspenseQueryReturn<NonNullable<Result>> {
-  const result = useReactSuspenseQuery<AnyPostgrestResponse<Result>, PostgrestError>(
-    buildSuspenseQueryOpts<Result>(query, config),
-  );
-
-  // isPending and isLoadingError are the only cases in which no data is present
-  // if (result.isPending || result.isLoadingError) {
-  // 	return {
-  // 		...result,
-  // 		data: undefined,
-  // 		count: null,
-  // 	} //as useSuspenseQueryAnyReturn<Result>;
-  // }
-
-  return {
-    ...result,
-    data: result.data.data, // NonNullable<Result|Result[]>,
-    count: result.data.count,
-  } as useSuspenseQueryAnyReturn<NonNullable<Result>>;
-}
-
-export const useSbQuery = useQuery;
-
-export { useSbSuspenseQuery };
+/**
+ * 将 supabase api封装位 react query的 形式.
+ * 原官方库: https://github.com/psteinroe/supabase-cache-helpers
+ */
+
+import type {
+  AnyPostgrestResponse,
+  BuildNormalizedQueryOps,
+  PostgrestQueryParserOptions,
+} from "@supabase-cache-helpers/postgrest-core";
+import { PostgrestFilter, encodeObject, type DecodedKey } from "@supabase-cache-helpers/postgrest-core";
+import type {
+  PostgrestError,
+  PostgrestMaybeSingleResponse,
+  PostgrestResponse,
+  PostgrestResponseSuccess,
+  PostgrestSingleResponse,
+} from "@supabase/postgrest-js";
+import {
+  useQueryClient,
+  useQuery as useReactQuery,
+  useSuspenseQuery as useReactSuspenseQuery,
+  type UseQueryOptions as UseReactQueryOptions,
+  type UseQueryResult as UseReactQueryResult,
+  type UseSuspenseQueryResult as UseReactSuspenseQueryResult,
+  type UseSuspenseQueryOptions as UserReactSuspenseQueryOptions,
+} from "@tanstack/react-query";
+import { buildQueryOpts, buildSuspenseQueryOpts } from "./build-query-opts";
+import { decode, encode } from "./key";
+
+export const KEY_PREFIX = "postgrest";
+export const INFINITE_KEY_PREFIX = "page";
+
+export type DecodedReactQueryKey = DecodedKey & {
+  isInfinite: boolean;
+  key: string[];
+};
+
+export const POSTGREST_FILTER_KEY_PREFIX = "postgrest-filter";
+
+type QueryKeySuffixOption = {
+  queryKeySuffix?: readonly unknown[];
+};
+
+export const usePostgrestFilterCache = <R extends Record<string, unknown>>() => {
+  const queryClient = useQueryClient();
+
+  return (query: string, opts?: PostgrestQueryParserOptions) => {
+    const key = [POSTGREST_FILTER_KEY_PREFIX, query, opts ? encodeObject(opts) : null];
+    const cacheData = queryClient.getQueryData(key);
+    if (cacheData instanceof PostgrestFilter) {
+      return cacheData;
+    }
+    const filter = PostgrestFilter.fromQuery(query, opts);
+    queryClient.setQueryData(key, filter);
+    return filter as PostgrestFilter<R>;
+  };
+};
+
+export const useQueriesForTableLoader = (table: string) => {
+  const queryClient = useQueryClient();
+  const getPostgrestFilter = usePostgrestFilterCache();
+
+  return () =>
+    queryClient
+      .getQueryCache()
+      .getAll()
+      .map((c) => c.queryKey)
+      .reduce<ReturnType<BuildNormalizedQueryOps["queriesForTable"]>>((prev, curr) => {
+        const decodedKey = decode(curr);
+        if (decodedKey?.table === table) {
+          prev.push(getPostgrestFilter(decodedKey.queryKey).params);
+        }
+        return prev;
+      }, []);
+};
+
+/**
+ * Applies Omit over a union, while preserving its union-ness.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: keyof any 是 TypeScript 泛型约束的标准用法
+type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K> : never;
+
+/**
+ * Represents the return value of the `useQuery` hook when `query` is expected to return
+ * a single row.
+ */
+export type UseQuerySingleReturn<Result> = DistributiveOmit<
+  UseReactQueryResult<PostgrestSingleResponse<Result>["data"], PostgrestError>,
+  "refetch"
+> &
+  Pick<UseReactQueryResult<PostgrestSingleResponse<Result>, PostgrestError>, "refetch"> &
+  Pick<PostgrestSingleResponse<Result>, "count">;
+
+/**
+ * Represents the return value of the `useQuery` hook when `query` is expected to return
+ * either a single row or an empty response.
+ */
+export type UseQueryMaybeSingleReturn<Result> = DistributiveOmit<
+  UseReactQueryResult<PostgrestMaybeSingleResponse<Result>["data"], PostgrestError>,
+  "refetch"
+> &
+  Pick<UseReactQueryResult<PostgrestMaybeSingleResponse<Result>, PostgrestError>, "refetch"> &
+  Pick<PostgrestMaybeSingleResponse<Result>, "count">;
+
+/**
+ * Represents the return value of the `useQuery` hook when `query` is expected to return
+ * one or more rows.
+ */
+export type UseQueryReturn<Result> = DistributiveOmit<
+  UseReactQueryResult<PostgrestResponse<Result>["data"], PostgrestError>,
+  "refetch"
+> &
+  Pick<UseReactQueryResult<PostgrestResponse<Result>, PostgrestError>, "refetch"> &
+  Pick<PostgrestResponse<Result>, "count">;
+
+/**
+ * Represents the return value of the `useQuery` hook when the type of the query response
+ * is not known.
+ */
+export type UseQueryAnyReturn<Result> = DistributiveOmit<
+  UseReactQueryResult<AnyPostgrestResponse<Result>["data"], PostgrestError>,
+  "refetch"
+> &
+  Pick<UseReactQueryResult<AnyPostgrestResponse<Result>, PostgrestError>, "refetch"> &
+  Pick<AnyPostgrestResponse<Result>, "count">;
+
+/**
+ * React hook to execute a PostgREST query and return a single item response.
+ *
+ * @param {PromiseLike<PostgrestSingleResponse<Result>>} query A promise that resolves to a PostgREST single item response.
+ * @param {Omit<UseReactQueryOptions<PostgrestSingleResponse<Result>, PostgrestError>, 'queryKey' | 'queryFn'>} [config] The React Query options.
+ * @returns {UseQuerySingleReturn<Result>} The hook result containing the single item response data.
+ */
+function useQuery<Result>(
+  query: PromiseLike<PostgrestSingleResponse<Result>>,
+  config?: Omit<UseReactQueryOptions<PostgrestSingleResponse<Result>, PostgrestError>, "queryKey" | "queryFn"> &
+    QueryKeySuffixOption,
+): UseQuerySingleReturn<Result>;
+/**
+ * React hook to execute a PostgREST query and return a maybe single item response.
+ *
+ * @param {PromiseLike<PostgrestMaybeSingleResponse<Result>>} query A promise that resolves to a PostgREST maybe single item response.
+ * @param {Omit<UseReactQueryOptions<PostgrestMaybeSingleResponse<Result>, PostgrestError>, 'queryKey' | 'queryFn'>} [config] The React Query options.
+ * @returns {UseQueryMaybeSingleReturn<Result>} The hook result containing the maybe single item response data.
+ */
+function useQuery<Result>(
+  query: PromiseLike<PostgrestMaybeSingleResponse<Result>>,
+  config?: Omit<UseReactQueryOptions<PostgrestMaybeSingleResponse<Result>, PostgrestError>, "queryKey" | "queryFn"> &
+    QueryKeySuffixOption,
+): UseQueryMaybeSingleReturn<Result>;
+/**
+ * React hook to execute a PostgREST query.
+ *
+ * @template Result The expected response data type.
+ * @param {PromiseLike<PostgrestResponse<Result>>} query A promise that resolves to a PostgREST response.
+ * @param {Omit<UseReactQueryOptions<PostgrestResponse<Result>, PostgrestError>, 'queryKey' | 'queryFn'>} [config] The React Query options.
+ * @returns {UseQueryReturn<Result>} The hook result containing the response data.
+ */
+function useQuery<Result>(
+  query: PromiseLike<PostgrestResponse<Result>>,
+  config?: Omit<UseReactQueryOptions<PostgrestResponse<Result>, PostgrestError>, "queryKey" | "queryFn"> &
+    QueryKeySuffixOption,
+): UseQueryReturn<Result>;
+
+/**
+ * React hook to execute a PostgREST query.
+ *
+ * @template Result The expected response data type.
+ * @param {PromiseLike<AnyPostgrestResponse<Result>>} query A promise that resolves to a PostgREST response of any kind.
+ * @param {Omit<UseReactQueryOptions<AnyPostgrestResponse<Result>, PostgrestError>, 'queryKey' | 'queryFn'>} [config] The React Query options.
+ * @returns {UseQueryAnyReturn<Result>} The hook result containing the response data.
+ */
+function useQuery<Result>(
+  query: PromiseLike<AnyPostgrestResponse<Result>>,
+  config?: Omit<UseReactQueryOptions<AnyPostgrestResponse<Result>, PostgrestError>, "queryKey" | "queryFn"> &
+    QueryKeySuffixOption,
+): UseQueryAnyReturn<Result> {
+  const result = useReactQuery<AnyPostgrestResponse<Result>, PostgrestError>(buildQueryOpts<Result>(query, config));
+
+  // isPending and isLoadingError are the only cases in which no data is present
+  if (result.isPending || result.isLoadingError) {
+    return {
+      ...result,
+      data: undefined,
+      count: null,
+    } as UseQueryAnyReturn<Result>;
+  }
+
+  return {
+    ...result,
+    data: result.data?.data,
+    count: result.data?.count,
+  } as UseQueryAnyReturn<Result>;
+}
+
+export { useQuery };
+
+// 增加 queryQuery 获取函数
+
+/**
+ * 获取 PostgREST 查询的完整 QueryKey
+ * @param query Supabase PostgrestBuilder 实例 (例如: sb.from('...').select() 或 sb.rpc(...))
+ * @param isInfinite 是否为无限查询 (默认 false)
+ */
+export function getSbQueryKey<Result>(query: PromiseLike<AnyPostgrestResponse<Result>>, isInfinite = false): string[] {
+  return encode(query, isInfinite);
+}
+
+/**
+ * 获取 PostgREST 查询的 "Base Key" (仅包含前缀、Schema、Table/RPC名称)
+ * 用于 invalidateQueries 时模糊匹配整个表或RPC的所有查询，忽略具体的 filter/page 参数。
+ *
+ * 结构: ['postgrest', 'null'|'page', schema, table|rpc, ...]
+ * 返回: 前4个元素
+ */
+export function getSbTableKey<Result>(query: PromiseLike<AnyPostgrestResponse<Result>>): string[] {
+  const fullKey = encode(query, false);
+  // 截取前4个元素作为基础Key: [prefix, infinitePrefix, schema, table]
+  // 这样 invalidateQueries(baseKey) 将会匹配该表/RPC下的所有查询变体
+  return fullKey.slice(0, 4);
+}
+
+// 增加 suspense query 的支持 ========================================================================================
+
+/**
+ * Represents the return value of the `useSuspenseQuery` hook when `query` is expected to return
+ * a single row.
+ */
+export type useSuspenseQuerySingleReturn<Result> = DistributiveOmit<
+  UseReactSuspenseQueryResult<PostgrestMaybeSingleResponseV4<Result>["data"], PostgrestError>,
+  "refetch"
+> &
+  Pick<
+    UseReactSuspenseQueryResult<
+      // PostgrestSingleResponse<Result>,
+      Result,
+      PostgrestError
+    >,
+    "refetch"
+  > &
+  Pick<PostgrestSingleResponse<Result>, "count">;
+
+export type PostgrestMaybeSingleResponseV4<T> = PostgrestResponseSuccess<T>;
+
+/**
+ * Represents the return value of the `useSuspenseQuery` hook when `query` is expected to return
+ * either a single row or an empty response.
+ */
+export type useSuspenseQueryMaybeSingleReturn<Result> = DistributiveOmit<
+  UseReactSuspenseQueryResult<PostgrestMaybeSingleResponseV4<NonNullable<Result>>["data"], PostgrestError>,
+  "refetch"
+> &
+  Pick<UseReactSuspenseQueryResult<PostgrestMaybeSingleResponseV4<NonNullable<Result>>, PostgrestError>, "refetch"> &
+  Pick<PostgrestMaybeSingleResponseV4<Result>, "count">;
+
+/**
+ * Represents the return value of the `useSuspenseQuery` hook when `query` is expected to return
+ * one or more rows.
+ */
+export type useSuspenseQueryReturn<Result> = DistributiveOmit<
+  UseReactSuspenseQueryResult<PostgrestResponse<Result>["data"], PostgrestError>,
+  "refetch"
+> &
+  Pick<UseReactSuspenseQueryResult<PostgrestResponse<Result>, PostgrestError>, "refetch"> &
+  Pick<PostgrestResponse<Result>, "count">;
+
+/**
+ * Represents the return value of the `useSuspenseQuery` hook when the type of the query response
+ * is not known.
+ */
+export type useSuspenseQueryAnyReturn<Result> = DistributiveOmit<
+  UseReactSuspenseQueryResult<PostgrestResponse<Result>["data"], PostgrestError>,
+  "refetch"
+> &
+  Pick<UseReactSuspenseQueryResult<PostgrestResponse<Result>, PostgrestError>, "refetch"> &
+  Pick<PostgrestResponse<Result>, "count">;
+
+/**
+ * React hook to execute a PostgREST query and return a single item response.
+ *
+ * @param {PromiseLike<PostgrestSingleResponse<Result>>} query A promise that resolves to a PostgREST single item response.
+ * @param {Omit<UseReactQueryOptions<PostgrestSingleResponse<Result>, PostgrestError>, 'queryKey' | 'queryFn'>} [config] The React Query options.
+ * @returns {useSuspenseQuerySingleReturn<Result>} The hook result containing the single item response data.
+ */
+function useSbSuspenseQuery<Result>(
+  query: PromiseLike<PostgrestSingleResponse<Result>>,
+  config?: Omit<UseReactQueryOptions<PostgrestSingleResponse<Result>, PostgrestError>, "queryKey" | "queryFn"> &
+    QueryKeySuffixOption,
+): useSuspenseQuerySingleReturn<NonNullable<Result>>;
+/**
+ * React hook to execute a PostgREST query and return a maybe single item response.
+ *
+ * @param {PromiseLike<PostgrestMaybeSingleResponse<Result>>} query A promise that resolves to a PostgREST maybe single item response.
+ * @param {Omit<UseReactQueryOptions<PostgrestMaybeSingleResponse<Result>, PostgrestError>, 'queryKey' | 'queryFn'>} [config] The React Query options.
+ * @returns {useSuspenseQueryMaybeSingleReturn<Result>} The hook result containing the maybe single item response data.
+ */
+function useSbSuspenseQuery<Result>(
+  query: PromiseLike<PostgrestMaybeSingleResponse<Result>>,
+  config?: Omit<UseReactQueryOptions<PostgrestMaybeSingleResponse<Result>, PostgrestError>, "queryKey" | "queryFn"> &
+    QueryKeySuffixOption,
+): useSuspenseQueryMaybeSingleReturn<NonNullable<Result>>;
+/**
+ * React hook to execute a PostgREST query.
+ *
+ * @template Result The expected response data type.
+ * @param {PromiseLike<PostgrestResponse<Result>>} query A promise that resolves to a PostgREST response.
+ * @param {Omit<UseReactQueryOptions<PostgrestResponse<Result>, PostgrestError>, 'queryKey' | 'queryFn'>} [config] The React Query options.
+ * @returns {useSuspenseQueryReturn<Result>} The hook result containing the response data.
+ */
+function useSbSuspenseQuery<Result>(
+  query: PromiseLike<PostgrestResponse<Result>>,
+  config?: Omit<UseReactQueryOptions<PostgrestResponse<Result>, PostgrestError>, "queryKey" | "queryFn"> &
+    QueryKeySuffixOption,
+): useSuspenseQueryReturn<NonNullable<Result>>;
+
+/**
+ * React hook to execute a PostgREST query.
+ *
+ * @template Result The expected response data type.
+ * @param {PromiseLike<AnyPostgrestResponse<Result>>} query A promise that resolves to a PostgREST response of any kind.
+ * @param {Omit<UseReactQueryOptions<AnyPostgrestResponse<Result>, PostgrestError>, 'queryKey' | 'queryFn'>} [config] The React Query options.
+ * @returns {useSuspenseQueryAnyReturn<Result>} The hook result containing the response data.
+ */
+function useSbSuspenseQuery<Result>(
+  query: PromiseLike<PostgrestResponse<Result>>,
+  config?: Omit<UserReactSuspenseQueryOptions<AnyPostgrestResponse<Result>, PostgrestError>, "queryKey" | "queryFn"> &
+    QueryKeySuffixOption,
+): useSuspenseQueryReturn<NonNullable<Result>> {
+  const result = useReactSuspenseQuery<AnyPostgrestResponse<Result>, PostgrestError>(
+    buildSuspenseQueryOpts<Result>(query, config),
+  );
+
+  // isPending and isLoadingError are the only cases in which no data is present
+  // if (result.isPending || result.isLoadingError) {
+  // 	return {
+  // 		...result,
+  // 		data: undefined,
+  // 		count: null,
+  // 	} //as useSuspenseQueryAnyReturn<Result>;
+  // }
+
+  return {
+    ...result,
+    data: result.data.data, // NonNullable<Result|Result[]>,
+    count: result.data.count,
+  } as useSuspenseQueryAnyReturn<NonNullable<Result>>;
+}
+
+export const useSbQuery = useQuery;
+
+export { useSbSuspenseQuery };