@suspensive/react-query-4 0.0.1-beta.0

package/src/useSuspenseQueries.ts

@@ -0,0 +1,127 @@
+import { type QueryFunction, type UseQueryOptions, useQueries } from '@tanstack/react-query'
+import type { UseSuspenseQueryOptions, UseSuspenseQueryResult } from './useSuspenseQuery'
+
+// Avoid TS depth-limit error in case of large array literal
+type MAXIMUM_DEPTH = 20
+
+type GetSuspenseOptions<T> =
+  // Part 1: responsible for applying explicit type parameter to function arguments, if object { queryFnData: TQueryFnData, error: TError, data: TData }
+  T extends {
+    queryFnData: infer TQueryFnData
+    error?: infer TError
+    data: infer TData
+  }
+    ? UseSuspenseQueryOptions<TQueryFnData, TError, TData>
+    : T extends { queryFnData: infer TQueryFnData; error?: infer TError }
+      ? UseSuspenseQueryOptions<TQueryFnData, TError>
+      : T extends { data: infer TData; error?: infer TError }
+        ? UseSuspenseQueryOptions<unknown, TError, TData>
+        : // Part 2: responsible for applying explicit type parameter to function arguments, if tuple [TQueryFnData, TError, TData]
+          T extends [infer TQueryFnData, infer TError, infer TData]
+          ? UseSuspenseQueryOptions<TQueryFnData, TError, TData>
+          : T extends [infer TQueryFnData, infer TError]
+            ? UseSuspenseQueryOptions<TQueryFnData, TError>
+            : T extends [infer TQueryFnData]
+              ? UseSuspenseQueryOptions<TQueryFnData>
+              : // Part 3: responsible for inferring and enforcing type if no explicit parameter was provided
+                T extends {
+                    queryFn?: QueryFunction<infer TQueryFnData, infer TQueryKey>
+                    select?: (data: any) => infer TData
+                  }
+                ? UseSuspenseQueryOptions<TQueryFnData, unknown, TData, TQueryKey>
+                : T extends {
+                      queryFn?: QueryFunction<infer TQueryFnData, infer TQueryKey>
+                    }
+                  ? UseSuspenseQueryOptions<TQueryFnData, unknown, TQueryFnData, TQueryKey>
+                  : // Fallback
+                    UseSuspenseQueryOptions
+
+type GetSuspenseResults<T> =
+  // Part 1: responsible for mapping explicit type parameter to function result, if object
+  T extends { queryFnData: any; error?: infer TError; data: infer TData }
+    ? UseSuspenseQueryResult<TData, TError>
+    : T extends { queryFnData: infer TQueryFnData; error?: infer TError }
+      ? UseSuspenseQueryResult<TQueryFnData, TError>
+      : T extends { data: infer TData; error?: infer TError }
+        ? UseSuspenseQueryResult<TData, TError>
+        : // Part 2: responsible for mapping explicit type parameter to function result, if tuple
+          T extends [any, infer TError, infer TData]
+          ? UseSuspenseQueryResult<TData, TError>
+          : T extends [infer TQueryFnData, infer TError]
+            ? UseSuspenseQueryResult<TQueryFnData, TError>
+            : T extends [infer TQueryFnData]
+              ? UseSuspenseQueryResult<TQueryFnData>
+              : // Part 3: responsible for mapping inferred type to results, if no explicit parameter was provided
+                T extends {
+                    queryFn?: QueryFunction<infer TQueryFnData, any>
+                    select?: (data: any) => infer TData
+                  }
+                ? UseSuspenseQueryResult<unknown extends TData ? TQueryFnData : TData>
+                : T extends {
+                      queryFn?: QueryFunction<infer TQueryFnData, any>
+                    }
+                  ? UseSuspenseQueryResult<TQueryFnData>
+                  : // Fallback
+                    UseSuspenseQueryResult
+
+/**
+ * SuspenseQueriesOptions reducer recursively unwraps function arguments to infer/enforce type param
+ */
+export type SuspenseQueriesOptions<
+  T extends Array<any>,
+  TResult extends Array<any> = [],
+  TDepth extends ReadonlyArray<number> = [],
+> = TDepth['length'] extends MAXIMUM_DEPTH
+  ? Array<UseSuspenseQueryOptions>
+  : T extends []
+    ? []
+    : T extends [infer Head]
+      ? [...TResult, GetSuspenseOptions<Head>]
+      : T extends [infer Head, ...infer Tail]
+        ? SuspenseQueriesOptions<[...Tail], [...TResult, GetSuspenseOptions<Head>], [...TDepth, 1]>
+        : Array<unknown> extends T
+          ? T
+          : // If T is *some* array but we couldn't assign unknown[] to it, then it must hold some known/homogenous type!
+            // use this to infer the param types in the case of Array.map() argument
+            T extends Array<UseSuspenseQueryOptions<infer TQueryFnData, infer TError, infer TData, infer TQueryKey>>
+            ? Array<UseSuspenseQueryOptions<TQueryFnData, TError, TData, TQueryKey>>
+            : // Fallback
+              Array<UseSuspenseQueryOptions>
+
+/**
+ * SuspenseQueriesResults reducer recursively maps type param to results
+ */
+export type SuspenseQueriesResults<
+  T extends Array<any>,
+  TResult extends Array<any> = [],
+  TDepth extends ReadonlyArray<number> = [],
+> = TDepth['length'] extends MAXIMUM_DEPTH
+  ? Array<UseSuspenseQueryResult>
+  : T extends []
+    ? []
+    : T extends [infer Head]
+      ? [...TResult, GetSuspenseResults<Head>]
+      : T extends [infer Head, ...infer Tail]
+        ? SuspenseQueriesResults<[...Tail], [...TResult, GetSuspenseResults<Head>], [...TDepth, 1]>
+        : T extends Array<UseSuspenseQueryOptions<infer TQueryFnData, infer TError, infer TData, any>>
+          ? // Dynamic-size (homogenous) UseQueryOptions array: map directly to array of results
+            Array<UseSuspenseQueryResult<unknown extends TData ? TQueryFnData : TData, TError>>
+          : // Fallback
+            Array<UseSuspenseQueryResult>
+
+/**
+ * This hook is wrapping useQueries of `@tanstack/react-query` v4 with default suspense option.
+ * @see {@link https://suspensive.org/docs/react-query/useSuspenseQueries}
+ */
+export function useSuspenseQueries<T extends any[]>({
+  queries,
+  context,
+}: {
+  queries: readonly [...SuspenseQueriesOptions<T>]
+  context?: UseQueryOptions['context']
+}): SuspenseQueriesResults<T> {
+  return useQueries({
+    queries: queries.map((query: typeof queries) => ({ ...query, suspense: true })),
+    context,
+  }) as SuspenseQueriesResults<T>
+}

package/src/useSuspenseQuery.test-d.ts

@@ -0,0 +1,51 @@
+import { queryFn, queryKey } from '@suspensive/test-utils'
+import { describe, expectTypeOf, it } from 'vitest'
+import { type UseSuspenseQueryResult, useSuspenseQuery } from './useSuspenseQuery'
+
+describe('useSuspenseQuery', () => {
+  it('type error', () => {
+    //@ts-expect-error no arg
+    useSuspenseQuery()
+    useSuspenseQuery({
+      queryKey,
+      queryFn,
+      //@ts-expect-error no suspense
+      suspense: boolean,
+    })
+    useSuspenseQuery({
+      queryKey,
+      queryFn,
+      //@ts-expect-error no useErrorBoundary
+      useErrorBoundary: boolean,
+    })
+    useSuspenseQuery({
+      queryKey,
+      queryFn,
+      //@ts-expect-error no enabled
+      enabled: boolean,
+    })
+    useSuspenseQuery({
+      queryKey,
+      queryFn,
+      //@ts-expect-error no placeholderData
+      placeholderData: 'placeholder',
+    })
+    useSuspenseQuery({
+      queryKey,
+      queryFn,
+      //@ts-expect-error no isPlaceholderData
+    }).isPlaceholderData
+  })
+
+  it('type check', () => {
+    const result = useSuspenseQuery({ queryKey, queryFn })
+    expectTypeOf(result).toEqualTypeOf<UseSuspenseQueryResult<{ text: string }>>()
+    expectTypeOf(result.data).toEqualTypeOf<{ text: string }>()
+    expectTypeOf(result.status).toEqualTypeOf<'success'>()
+
+    const selectedResult = useSuspenseQuery({ queryKey, queryFn, select: (data) => data.text })
+    expectTypeOf(selectedResult).toEqualTypeOf<UseSuspenseQueryResult<string>>()
+    expectTypeOf(selectedResult.data).toEqualTypeOf<string>()
+    expectTypeOf(selectedResult.status).toEqualTypeOf<'success'>()
+  })
+})

package/src/useSuspenseQuery.ts

@@ -0,0 +1,36 @@
+import { type QueryKey, type UseQueryOptions, type UseQueryResult, useQuery } from '@tanstack/react-query'
+import type { OmitKeyof } from './utility-types'
+
+export interface UseSuspenseQueryResult<TData = unknown, TError = unknown>
+  extends OmitKeyof<UseQueryResult<TData, TError>, keyof Pick<UseQueryResult, 'isPlaceholderData'>> {
+  data: TData
+  status: 'success'
+}
+
+export interface UseSuspenseQueryOptions<
+  TQueryFnData = unknown,
+  TError = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> extends OmitKeyof<
+    UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
+    'suspense' | 'useErrorBoundary' | 'enabled' | 'placeholderData'
+  > {}
+
+/**
+ * This hook is wrapping useQuery of `@tanstack/react-query` v4 with default suspense option.
+ * @see {@link https://suspensive.org/docs/react-query/useSuspenseQuery}
+ */
+export function useSuspenseQuery<
+  TQueryFnData = unknown,
+  TError = unknown,
+  TData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(options: UseSuspenseQueryOptions<TQueryFnData, TError, TData, TQueryKey>) {
+  return useQuery<TQueryFnData, TError, TData, TQueryKey>({
+    ...options,
+    enabled: true,
+    useErrorBoundary: true,
+    suspense: true,
+  }) as UseSuspenseQueryResult<TData, TError>
+}

package/src/utility-types/OmitKeyof.test-d.ts

@@ -0,0 +1,175 @@
+import type { OmitKeyof } from './OmitKeyof'
+
+describe('OmitKeyof', () => {
+  it("'s string key type check", () => {
+    type A = {
+      x: string
+      y: number
+    }
+
+    type ExpectedType = {
+      x: string
+    }
+
+    // Bad point
+    // 1. original Omit can use 'z' as type parameter with no type error
+    // 2. original Omit have no auto complete for 2nd type parameter
+    expectTypeOf<Omit<A, 'z' | 'y'>>().toEqualTypeOf<ExpectedType>()
+
+    // Solution
+
+    // 1. strictly
+    expectTypeOf<
+      OmitKeyof<
+        A,
+        // OmitKeyof can't use 'z' as type parameter with type error because A don't have key 'z'
+        // @ts-expect-error Type does not satisfy the constraint keyof A
+        'z' | 'y'
+      >
+    >().toEqualTypeOf<ExpectedType>
+    expectTypeOf<
+      OmitKeyof<
+        A,
+        // OmitKeyof can't use 'z' as type parameter with type error because A don't have key 'z'
+        // @ts-expect-error Type does not satisfy the constraint keyof A
+        'z' | 'y',
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments
+        'strictly'
+      >
+    >().toEqualTypeOf<ExpectedType>
+
+    // 2. safely
+    expectTypeOf<
+      OmitKeyof<
+        A,
+        // OmitKeyof can't use 'z' as type parameter type error with strictly parameter or default parameter
+        // @ts-expect-error Type does not satisfy the constraint keyof A
+        'z' | 'y'
+      >
+    >().toEqualTypeOf<ExpectedType>
+    expectTypeOf<
+      OmitKeyof<
+        A,
+        // With 'safely', OmitKeyof can use 'z' as type parameter like original Omit but This support autocomplete too yet for DX.
+        'z' | 'y',
+        'safely'
+      >
+    >().toEqualTypeOf<ExpectedType>
+  })
+
+  it("'s number key type check", () => {
+    type A = {
+      [1]: string
+      [2]: number
+    }
+
+    type ExpectedType = {
+      [1]: string
+    }
+
+    // Bad point
+    // 1. original Omit can use 3 as type parameter with no type error
+    // 2. original Omit have no auto complete for 2nd type parameter
+    expectTypeOf<Omit<A, 3 | 2>>().toEqualTypeOf<ExpectedType>()
+
+    // Solution
+
+    // 1. strictly
+    expectTypeOf<
+      OmitKeyof<
+        A,
+        // OmitKeyof can't use 3 as type parameter with type error because A don't have key 3
+        // @ts-expect-error Type does not satisfy the constraint keyof A
+        3 | 2
+      >
+    >().toEqualTypeOf<ExpectedType>
+    expectTypeOf<
+      OmitKeyof<
+        A,
+        // OmitKeyof can't use 3 as type parameter with type error because A don't have key 3
+        // @ts-expect-error Type does not satisfy the constraint keyof A
+        3 | 2,
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments
+        'strictly'
+      >
+    >().toEqualTypeOf<ExpectedType>
+
+    // 2. safely
+    expectTypeOf<
+      OmitKeyof<
+        A,
+        // OmitKeyof can't use 3 as type parameter type error with strictly parameter or default parameter
+        // @ts-expect-error Type does not satisfy the constraint keyof A
+        3 | 2
+      >
+    >().toEqualTypeOf<ExpectedType>
+    expectTypeOf<
+      OmitKeyof<
+        A,
+        // With 'safely', OmitKeyof can use 3 as type parameter like original Omit but This support autocomplete too yet for DX.
+        3 | 2,
+        'safely'
+      >
+    >().toEqualTypeOf<ExpectedType>
+  })
+
+  it("'s symbol key type check", () => {
+    const symbol1 = Symbol()
+    const symbol2 = Symbol()
+    const symbol3 = Symbol()
+
+    type A = {
+      [symbol1]: string
+      [symbol2]: number
+    }
+
+    type ExpectedType = {
+      [symbol1]: string
+    }
+
+    // Bad point
+    // 1. original Omit can use symbol3 as type parameter with no type error
+    // 2. original Omit have no auto complete for 2nd type parameter
+    expectTypeOf<Omit<A, typeof symbol3 | typeof symbol2>>().toEqualTypeOf<ExpectedType>()
+
+    // Solution
+
+    // 1. strictly
+    expectTypeOf<
+      OmitKeyof<
+        A,
+        // OmitKeyof can't use symbol3 as type parameter with type error because A don't have key symbol3
+        // @ts-expect-error Type does not satisfy the constraint keyof A
+        typeof symbol3 | typeof symbol2
+      >
+    >().toEqualTypeOf<ExpectedType>
+    expectTypeOf<
+      OmitKeyof<
+        A,
+        // OmitKeyof can't use symbol3 as type parameter with type error because A don't have key symbol3
+        // @ts-expect-error Type does not satisfy the constraint keyof A
+        typeof symbol3 | typeof symbol2,
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-arguments
+        'strictly'
+      >
+    >().toEqualTypeOf<ExpectedType>
+
+    // 2. safely
+    expectTypeOf<
+      OmitKeyof<
+        A,
+        // OmitKeyof can't use symbol3 as type parameter type error with strictly parameter or default parameter
+        // @ts-expect-error Type does not satisfy the constraint keyof A
+        typeof symbol3 | typeof symbol2
+      >
+    >().toEqualTypeOf<ExpectedType>
+    expectTypeOf<
+      OmitKeyof<
+        A,
+        // With 'safely', OmitKeyof can use symbol3 as type parameter like original Omit but This support autocomplete too yet for DX.
+        typeof symbol3 | typeof symbol2,
+        'safely'
+      >
+    >().toEqualTypeOf<ExpectedType>
+  })
+})

package/src/utility-types/OmitKeyof.ts

@@ -0,0 +1,11 @@
+export type OmitKeyof<
+  TObject,
+  TKey extends TStrictly extends 'safely'
+    ?
+        | keyof TObject
+        | (string & Record<never, never>)
+        | (number & Record<never, never>)
+        | (symbol & Record<never, never>)
+    : keyof TObject,
+  TStrictly extends 'strictly' | 'safely' = 'strictly',
+> = Omit<TObject, TKey>

package/src/utility-types/RequiredKeyof.ts

@@ -0,0 +1,3 @@
+export type RequiredKeyof<T, TKey extends keyof T> = T & {
+  [_ in TKey]: Record<never, never>
+}

package/src/utility-types/index.ts

@@ -0,0 +1,2 @@
+export type { OmitKeyof } from './OmitKeyof'
+export type { RequiredKeyof } from './RequiredKeyof'