Ctrlk
GitHub
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Getting Started

In addition to the Raycast API which is bundled as part of the app, we also provide a sibling package that contains a set of utilities to streamline common patterns and operations used in extensions.

Installation

This package can be installed independently using npm.

@raycast/utils has a peer dependency on @raycast/api. This means that a certain version of utils will require a version above a certain version of api. npm will warn you if that is not the case.

Changelog

v2.3.2

  • Allow overriding providerName and description in built-in OAuthService providers (Thanks @smorin!)

v2.3.1

  • Allow overriding providerId and extraParameters in built-in OAuthService providers (Thanks @smorin!)

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

  • Fixed an issue where refreshing OAuth tokens would fails for providers that return scope as an array instead of a string

v2.2.5

  • Fixed an issue where useSql would not properly show the permission priming screen

v2.2.4

  • Fixed an issue where an avatar's initials wouldn't be centered

v2.2.3

  • Fixed an issue with useSQL on Windows where the query would refuse to be executed because the database is locked

v2.2.2

  • Fix useCachedState to preserve Date objects more precisely.

v2.2.1

  • Fix compiled file to actually make useSQL and executeSQL work on Windows.

v2.2.0

  • Make useSQL and executeSQL work on Windows.

v2.1.1

  • Fix the default size of getFavicon.

v2.1.0

  • getFavicon will now respect the user's setting for the favicon provider. Note that the Apple provider isn't supported since it relies on a native API.

v2.0.1

  • Fix types for ESM extensions

v2.0.0

  • The library can now be tree-shaken, reducing its size considerably.

  • When using usePromise and mutating the data with an optimistic update before it is fetched, the current fetch will be aborted to avoid a race condition.

  • Add a new runPowerShellScript function.

v1.19.1

  • Fixed an issue where arguments weren't passed to withCache.

v1.19.0

v1.18.1

  • Fixed an issue where setting timeout to 0 in runAppleScript would not work.

v1.18.0

v1.17.0

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.

v1.16.3

  • Fix an issue where URLSearchParams couldn't be passed as an option to useFetch or useCachedPromise, causing extensions to crash.

v1.16.2

  • Fixed the refresh token flow to log out the user instead of throwing an error.

v1.16.1

  • Fixed an issue where bodyEncoding wasn't properly used in OAuthService.

v1.16.0

  • Add a failureToastOptions prop to useFetch, useCachedPromise, and usePromise to make it possible to customize the error displayed instead of a generic "Failed to fetch latest data".

v1.15.0

v1.14.0

v1.13.6

  • Updated useFetch's mapResult type to allow returning cursor in addition to data and hasMore.

v1.13.5

  • Extended PaginationOptions with cursor.

v1.13.4

  • Fixed non-paginated version of useFetch not being re-run when url changes.

v1.13.3

  • Fixed optimisticUpdate not working when paginating beyond the first page when using useCachedPromise or other hooks that build on top of it..

  • Fixed useFetch type requiring mapResult for non-paginated overload.

v1.13.2

  • Added default OAuth URLs for Google, Jira, and Zoom

v1.13.1

  • Fixed useFetch type for non-paginated overload.

v1.13.0

  • Added pagination support to usePromise, useCachedPromise and useFetch.

v1.12.5

  • Add string array support for OAuth scope (Thanks @tonka3000!).

v1.12.4

  • Add tokenResponseParser and tokenRefreshResponseParser in the options of OAuthService.

  • Fix built-in Slack OAuthServices.

v1.12.3

  • Fixed bodyEncoding for some built-in OAuthServices.

v1.12.2

  • Fixed types for OAuthService.slack.

v1.12.1

  • Fixed the refresh flow of OAuthService that would return outdated tokens.

v1.12.0

  • Removed some default OAuth clientIDs that could not work with generic scopes.

  • Fixed withAccessToken when used in no-view commands.

v1.11.1

  • Fixed Google OAuth configuration.

v1.11.0

v1.10.1

  • Fix an issue where the values passed to the reset function of the useForm hook wouldn't be respected.

v1.10.0

v1.9.1

  • Fix an issue where useForm's reset function would not reset the value of some fields (which defeats its purpose...)

v1.9.0

v1.8.0

  • Add a new runAppleScript function.

  • Change the default options.timeout of useExec to 10s.

v1.7.1

Change the signature of getProgressIcon to accept a Color in addition to a string for the options.background.

v1.7.0

Change the signature of getProgressIcon to accept a Color in addition to a string for the color.

v1.6.0

Added the useAI hook.

v1.4.0

Added the useSQL hook.

v1.3.1

  • Added the reset method to useForm.

v1.3.0

  • Added the focus method to useForm.

  • Added the input option to useExec.

v1.2.0

Added useExec and useForm hooks.

v1.1.0

Added getFavicon method.

v1.0.0

First release of the utilities.

PreviousWindow Management
NextFunctions

Last updated