Docs: Update the utils docs

docs/utils-reference/getting-started.md

@@ -16,9 +16,13 @@ npm install --save @raycast/utils
 
 ## Changelog
 
+### v1.16.5
+
+- Fixed the bug where `failureToastOptions` did not apply for `useExec` and `useStreamJSON` hooks.
+
 ### v1.16.4
 
-- Avoid throwing an error when `useFetch` can't parse the `Content-Type` header of the response
+- Avoid throwing an error when `useFetch` can't parse the `Content-Type` header of the response.
 
 ### v1.16.3
 

docs/utils-reference/react-hooks/useAI.md

@@ -14,7 +14,8 @@ function useAI(
     execute?: boolean;
     onError?: (error: Error) => void;
     onData?: (data: T) => void;
-    onWillExecute?: (args: string[]) -> void;
+    onWillExecute?: (args: Parameters<T>) => void;
+    failureToastOptions?: Partial<Pick<Toast.Options, "title" | "primaryAction" | "message">>;
   }
 ): AsyncState<String> & {
   revalidate: () => void;
@@ -37,6 +38,7 @@ Including the [usePromise](./usePromise.md)'s options:
 - `options.onError` is a function called when an execution fails. By default, it will log the error and show a generic failure toast with an action to retry.
 - `options.onData` is a function called when an execution succeeds.
 - `options.onWillExecute` is a function called when an execution will start.
+- `options.failureToastOptions` are the options to customize the title, message, and primary action of the failure toast.
 
 ### Return
 

docs/utils-reference/react-hooks/useCachedPromise.md

@@ -27,6 +27,7 @@ function useCachedPromise<T, U>(
     onError?: (error: Error) => void;
     onData?: (data: Result<T>) => void;
     onWillExecute?: (args: Parameters<T>) => void;
+    failureToastOptions?: Partial<Pick<Toast.Options, "title" | "primaryAction" | "message">>;
   },
 ): AsyncState<Result<T>> & {
   revalidate: () => void;
@@ -54,6 +55,7 @@ Including the [usePromise](./usePromise.md)'s options:
 - `options.onError` is a function called when an execution fails. By default, it will log the error and show a generic failure toast with an action to retry.
 - `options.onData` is a function called when an execution succeeds.
 - `options.onWillExecute` is a function called when an execution will start.
+- `options.failureToastOptions` are the options to customize the title, message, and primary action of the failure toast.
 
 ### Return
 
@@ -233,7 +235,7 @@ to
 const { isLoading, data, pagination } = useCachedPromise(
   (searchText: string) => async (options) => {
     const response = await fetch(`https://api.example?q=${searchText}&page=${options.page}`);
-    const data = await response.json();
+    const { data } = await response.json();
     const hasMore = options.page < 50;
     return { data, hasMore };
   },
@@ -245,13 +247,32 @@ const { isLoading, data, pagination } = useCachedPromise(
 );
 ```
 
+or, if your data source uses cursor-based pagination, you can return a `cursor` alongside `data` and `hasMore`, and the cursor will be passed as an argument the next time the function gets called:
+
+```ts
+const { isLoading, data, pagination } = useCachedPromise(
+  (searchText: string) => async (options) => {
+    const response = await fetch(`https://api.example?q=${searchText}&cursor=${options.cursor}`);
+    const { data, nextCursor } = await response.json();
+    const hasMore = nextCursor !== undefined;
+    return { data, hasMore, cursor: nextCursor };
+  },
+  [searchText],
+  {
+    // to make sure the screen isn't flickering when the searchText changes
+    keepPreviousData: true,
+  },
+);
+```
+
 You'll notice that, in the second case, the hook returns an additional item: `pagination`. This can be passed to Raycast's `List` or `Grid` components in order to enable pagination.
 Another thing to notice is that the async function receives a [PaginationOptions](#paginationoptions) argument, and returns a specific data format:
 
 ```ts
 {
   data: any[];
   hasMore: boolean;
+  cursor?: any;
 }
 ```
 

docs/utils-reference/react-hooks/useExec.md

@@ -30,7 +30,8 @@ function useExec<T, U>(
     execute?: boolean;
     onError?: (error: Error) => void;
     onData?: (data: T) => void;
-    onWillExecute?: (args: string[]) -> void;
+    onWillExecute?: (args: string[]) => void;
+    failureToastOptions?: Partial<Pick<Toast.Options, "title" | "primaryAction" | "message">>;
   }
 ): AsyncState<T> & {
   revalidate: () => void;
@@ -61,7 +62,8 @@ function useExec<T, U>(
     execute?: boolean;
     onError?: (error: Error) => void;
     onData?: (data: T) => void;
-    onWillExecute?: (args: string[]) -> void;
+    onWillExecute?: (args: string[]) => void;
+    failureToastOptions?: Partial<Pick<Toast.Options, "title" | "primaryAction" | "message">>;
   }
 ): AsyncState<T> & {
   revalidate: () => void;
@@ -110,6 +112,7 @@ Including the [usePromise](./usePromise.md)'s options:
 - `options.onError` is a function called when an execution fails. By default, it will log the error and show a generic failure toast with an action to retry.
 - `options.onData` is a function called when an execution succeeds.
 - `options.onWillExecute` is a function called when an execution will start.
+- `options.failureToastOptions` are the options to customize the title, message, and primary action of the failure toast.
 
 ### Return
 

docs/utils-reference/react-hooks/useFetch.md

@@ -20,6 +20,7 @@ export function useFetch<V, U, T = V>(
     onError?: (error: Error) => void;
     onData?: (data: T) => void;
     onWillExecute?: (args: [string, RequestInit]) => void;
+    failureToastOptions?: Partial<Pick<Toast.Options, "title" | "primaryAction" | "message">>;
   },
 ): AsyncState<T> & {
   revalidate: () => void;
@@ -51,6 +52,7 @@ Including the [usePromise](./usePromise.md)'s options:
 - `options.onError` is a function called when an execution fails. By default, it will log the error and show a generic failure toast with an action to retry.
 - `options.onData` is a function called when an execution succeeds.
 - `options.onWillExecute` is a function called when an execution will start.
+- `options.failureToastOptions` are the options to customize the title, message, and primary action of the failure toast.
 
 ### Return
 
@@ -211,13 +213,33 @@ const { isLoading, data, pagination } = useFetch(
 );
 ```
 
+or, if your data source uses cursor-based pagination, you can return a `cursor` alongside `data` and `hasMore`, and the cursor will be passed as an argument the next time the function gets called:
+
+```ts
+const { isLoading, data, pagination } = useFetch(
+  (options) =>
+    "https://api.ycombinator.com/v0.1/companies?" +
+    new URLSearchParams({ cursor: options.cursor, q: searchText }).toString(),
+  {
+    mapResult(result: SearchResult) {
+      const { companies, nextCursor } = result;
+      const hasMore = nextCursor !== undefined;
+      return { data: companies, hasMore, cursor: nextCursor, };
+    },
+    keepPreviousData: true,
+    initialData: [],
+  },
+);
+```
+
 You'll notice that, in the second case, the hook returns an additional item: `pagination`. This can be passed to Raycast's `List` or `Grid` components in order to enable pagination.
 Another thing to notice is that `mapResult`, which is normally optional, is actually required when using pagination. Furthermore, its return type is
 
 ```ts
 {
   data: any[],
   hasMore?: boolean;
+  cursor?: any;
 }
 ```
 

docs/utils-reference/react-hooks/usePromise.md

@@ -20,6 +20,7 @@ function usePromise<T>(
     onError?: (error: Error) => void;
     onData?: (data: Result<T>) => void;
     onWillExecute?: (args: Parameters<T>) => void;
+    failureToastOptions?: Partial<Pick<Toast.Options, "title" | "primaryAction" | "message">>;
   },
 ): AsyncState<Result<T>> & {
   revalidate: () => void;
@@ -39,6 +40,7 @@ With a few options:
 - `options.onError` is a function called when an execution fails. By default, it will log the error and show a generic failure toast with an action to retry.
 - `options.onData` is a function called when an execution succeeds.
 - `options.onWillExecute` is a function called when an execution will start.
+- `options.failureToastOptions` are the options to customize the title, message, and primary action of the failure toast.
 
 ### Returns
 
@@ -168,12 +170,26 @@ const { isLoading, data } = usePromise(
 
 to
 
+```ts
+const { isLoading, data, pagination } = usePromise(
+  (searchText: string) =>
+    async ({ page, lastItem, cursor }) => {
+      const { data } = await getUsers(page); // or any other asynchronous logic you need to perform
+      const hasMore = page < 50;
+      return { data, hasMore };
+    },
+  [searchText],
+);
+```
+
+or, if your data source uses cursor-based pagination, you can return a `cursor` alongside `data` and `hasMore`, and the cursor will be passed as an argument the next time the function gets called:
+
 ```ts
 const { isLoading, data, pagination } = usePromise(
   (searchText: string) =>
     async ({ page, lastItem, cursor }) => {
       const { data, nextCursor } = await getUsers(cursor); // or any other asynchronous logic you need to perform
-      const hasMore = page < 50; //
+      const hasMore = nextCursor !== undefined;
       return { data, hasMore, cursor: nextCursor };
     },
   [searchText],

docs/utils-reference/react-hooks/useSQL.md

@@ -13,7 +13,8 @@ function useSQL<T>(
     execute?: boolean;
     onError?: (error: Error) => void;
     onData?: (data: T) => void;
-    onWillExecute?: (args: string[]) -> void;
+    onWillExecute?: (args: string[]) => void;
+    failureToastOptions?: Partial<Pick<Toast.Options, "title" | "primaryAction" | "message">>;
   }
 ): AsyncState<T> & {
   revalidate: () => void;
@@ -37,6 +38,7 @@ Including the [usePromise](./usePromise.md)'s options:
 - `options.onError` is a function called when an execution fails. By default, it will log the error and show a generic failure toast with an action to retry.
 - `options.onData` is a function called when an execution succeeds.
 - `options.onWillExecute` is a function called when an execution will start.
+- `options.failureToastOptions` are the options to customize the title, message, and primary action of the failure toast.
 
 ### Return
 

docs/utils-reference/react-hooks/useStreamJSON.md

@@ -17,6 +17,7 @@ export function useStreamJSON<T, U>(
     onError?: (error: Error) => void;
     onData?: (data: T) => void;
     onWillExecute?: (args: [string, RequestInit]) => void;
+    failureToastOptions?: Partial<Pick<Toast.Options, "title" | "primaryAction" | "message">>;
   },
 ): AsyncState<Result<T>> & {
   revalidate: () => void;
@@ -48,7 +49,8 @@ Including the [usePromise](./usePromise.md)'s options:
 - `options.execute` is a boolean to indicate whether to actually execute the function or not. This is useful for cases where one of the function's arguments depends on something that might not be available right away (for example, depends on some user inputs). Because React requires every hook to be defined on the render, this flag enables you to define the hook right away but wait until you have all the arguments ready to execute the function.
 - `options.onError` is a function called when an execution fails. By default, it will log the error and show a generic failure toast with an action to retry.
 - `options.onData` is a function called when an execution succeeds.
-- `options.onWillExecute` is a function called when an execution will start..
+- `options.onWillExecute` is a function called when an execution will start.
+- `options.failureToastOptions` are the options to customize the title, message, and primary action of the failure toast.
 
 ### Return