V2.3

.github/workflows/test.yml

@@ -5,12 +5,26 @@ on:
   pull_request:
     paths:
       - "src/**"
+      - "test/**"
       - "tests/**"
+      - "package.json"
+      - "package-lock.json"
+      - "tsconfig.json"
+      - "eslint.config.js"
+      - "vitest.config.mts"
+      - ".github/workflows/test.yml"
     branches: [main, master]
   push:
     paths:
       - "src/**"
+      - "test/**"
       - "tests/**"
+      - "package.json"
+      - "package-lock.json"
+      - "tsconfig.json"
+      - "eslint.config.js"
+      - "vitest.config.mts"
+      - ".github/workflows/test.yml"
     branches: [main, master]
 
 jobs:
@@ -21,18 +35,20 @@ jobs:
       - name: Checkout
         uses: raycast/github-actions/git-checkout@v1.13.0
       - name: Setup Node
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
-          node-version: 22.14.0
+          node-version: 22.22.2
       - name: Npm Install
         run: npm ci
       - name: Npm Lint
+        run: npm run lint
+      - name: Npm Test
         run: npm run test
       - name: Build
         run: npm run build
       - name: Npm Install Tests
         run: npm ci
-        working-directory: ./tests
+        working-directory: ./smoke-tests
       - name: Build tests
         run: npm run build
-        working-directory: ./tests
+        working-directory: ./smoke-tests

.nvmrc

@@ -0,0 +1 @@
+22.22.2

docs/utils-reference/getting-started.md

@@ -16,9 +16,24 @@ npm install --save @raycast/utils
 
 ## Changelog
 
-### v2.2.7
-
-- Fixed `runAppleScript` timeout error messages reporting `undefined` instead of the effective timeout.
+### v2.3.0
+
+- Added `cacheWriteDebounce` to `useCachedState`, `useCachedPromise`, `useFetch`, `useExec`, and `useStreamJSON`
+- Fixed paginated `useFetch` URL factories running during render, repeatedly revalidating when passed inline, and bypassing the hook's error handling when they throw
+- Fixed `usePromise` handling of synchronous errors, asynchronous callbacks, and automatic optimistic-update rollbacks
+- Fixed `useCachedPromise` returning data and pagination state belonging to a previous cache key when `keepPreviousData` is disabled
+- Fixed `useExec` commands waiting forever for stdin, and restored support for disabling its timeout with `timeout: 0`
+- Fixed OAuth token refresh recovery and custom Google and Slack refresh-token URLs
+- Fixed `runAppleScript` and `runPowerShellScript` ignoring `parseOutput` and always returning a string
+- Fixed `useSQL` throwing during render when a database is missing and retaining a stale permission view after subsequent results
+- Fixed stale `useAI` streams overwriting newer results and model changes not triggering a new request
+- Fixed `useStreamJSON` not flattening arrays returned by `transform` before filtering and paginating them
+- Fixed failed `useStreamJSON` downloads replacing valid caches with partial files
+- Fixed SQLite connections leaking when queries fail or are aborted
+- Fixed frecency decay calculations, in-place sorting of caller-owned arrays
+- Fixed `useForm.reset` ignoring explicit falsy values
+- Fixed `getProgressIcon` ignoring `backgroundOpacity: 0`
+- Fixed `runAppleScript` timeout error messages reporting `undefined` instead of the effective timeout
 
 ### v2.2.6
 

docs/utils-reference/oauth/getAccessToken.md

@@ -1,9 +1,9 @@
 # `getAccessToken`
 
-Utility function designed for retrieving authorization tokens within a component. It ensures that your React components have the necessary authentication state, either through OAuth or a personal access token.
+Synchronous utility function for retrieving the OAuth or personal access token authorized by [`withAccessToken`](./withAccessToken.md). It can be called from components, event callbacks, and plain helper functions.
 
 {% hint style="info" %}
-`getAccessToken` **must** be used within components that are nested inside a component wrapped with [`withAccessToken`](./withAccessToken.md). Otherwise, the function will fail with an error.
+The command **must** first be authenticated by [`withAccessToken`](./withAccessToken.md). Calling `getAccessToken` before authentication finishes throws an error.
 {% endhint %}
 
 ## Signature
@@ -20,7 +20,7 @@ function getAccessToken(): {
 The function returns an object containing the following properties:
 
 - `token`: A string representing the access token.
-- `type`: An optional string that indicates the type of token retrieved. It can either be `oauth` for OAuth tokens or `personal` for personal access tokens.
+- `type`: Indicates the type of token retrieved. It is either `oauth` for OAuth tokens or `personal` for personal access tokens.
 
 ## Example
 

docs/utils-reference/oauth/withAccessToken.md

@@ -26,7 +26,7 @@ function withAccessToken<T = any>(
 Returns the wrapped component if used in a `view` command or the wrapped function if used in a `no-view` command.
 
 {% hint style="info" %}
-Note that the access token isn't injected into the wrapped component props. Instead, it's been set as a global variable that you can get with [getAccessToken](./getAccessToken.md).
+The access token isn't injected into the wrapped component or function's props. Read it synchronously with [getAccessToken](./getAccessToken.md), including from helpers and callbacks used by the authenticated command.
 {% endhint %}
 
 ## Example

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

@@ -47,6 +47,7 @@ With a few options:
 Including the [useCachedState](./useCachedState.md)'s options:
 
 - `options.initialData` is the initial value of the state if there aren't any in the Cache yet.
+- `options.cacheWriteDebounce` is a number to set if you want to debounce the cache writes. This can be useful to prevent memory pressure.
 
 Including the [usePromise](./usePromise.md)'s options:
 

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

@@ -26,6 +26,7 @@ With a few options:
 
 - `initialState` is the initial value of the state if there aren't any in the Cache yet.
 - `config.cacheNamespace` is a string that can be used to namespace the key.
+- `config.cacheWriteDebounce` is a number to set if you want to debounce the cache writes. This can be useful to prevent memory pressure.
 
 ## Example
 

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

@@ -26,6 +26,7 @@ function useExec<T, U>(
     timeout?: number;
     parseOutput?: ParseExecOutputHandler<T>;
     initialData?: U;
+    cacheWriteDebounce?: number;
     keepPreviousData?: boolean;
     execute?: boolean;
     onError?: (error: Error) => void;
@@ -58,6 +59,7 @@ function useExec<T, U>(
     timeout?: number;
     parseOutput?: ParseExecOutputHandler<T>;
     initialData?: U;
+    cacheWriteDebounce?: number;
     keepPreviousData?: boolean;
     execute?: boolean;
     onError?: (error: Error) => void;
@@ -100,6 +102,7 @@ With a few options:
 
 Including the [useCachedPromise](./useCachedPromise.md)'s options:
 
+- `options.cacheWriteDebounce` is the debounce time in milliseconds for writing results to the cache.
 - `options.keepPreviousData` is a boolean to tell the hook to keep the previous results instead of returning the initial value if there aren't any in the cache for the new arguments. This is particularly useful when used for data for a List to avoid flickering. See [Argument dependent on user input](#argument-dependent-on-user-input) for more information.
 
 Including the [useCachedState](./useCachedState.md)'s options:

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

@@ -15,6 +15,7 @@ export function useFetch<V, U, T = V>(
     parseResponse?: (response: Response) => Promise<V>;
     mapResult?: (result: V) => { data: T };
     initialData?: U;
+    cacheWriteDebounce?: number;
     keepPreviousData?: boolean;
     execute?: boolean;
     onError?: (error: Error) => void;
@@ -40,6 +41,7 @@ With a few options:
 
 Including the [useCachedPromise](./useCachedPromise.md)'s options:
 
+- `options.cacheWriteDebounce` is the debounce time in milliseconds for writing results to the cache.
 - `options.keepPreviousData` is a boolean to tell the hook to keep the previous results instead of returning the initial value if there aren't any in the cache for the new arguments. This is particularly useful when used for data for a List to avoid flickering. See [Argument dependent on List search text](#argument-dependent-on-list-search-text) for more information.
 
 Including the [useCachedState](./useCachedState.md)'s options:

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

@@ -12,6 +12,7 @@ export function useStreamJSON<T, U>(
     transform?: (item: any) => T;
     pageSize?: number;
     initialData?: U;
+    cacheWriteDebounce?: number;
     keepPreviousData?: boolean;
     execute?: boolean;
     onError?: (error: Error) => void;
@@ -38,6 +39,7 @@ With a few options:
 
 Including the [useCachedPromise](./useCachedPromise.md)'s options:
 
+- `options.cacheWriteDebounce` is the debounce time in milliseconds for writing results to the cache.
 - `options.keepPreviousData` is a boolean to tell the hook to keep the previous results instead of returning the initial value if there aren't any in the cache for the new arguments. This is particularly useful when used for data for a List to avoid flickering.
 
 Including the [useCachedState](./useCachedState.md)'s options: