v2 (#49)

* Update to @raycast/api@1.94.0

* make it tree-shakeable

* remove deprecated MutableRefObject

* abort requests when mutating

* complete tree shaking

* add changelog

* add runPowerShellScript

* add docs

* fix types

* update workflow

* use React.JSX

Author: mathieudutour

.github/workflows/test.yml

@@ -20,8 +20,10 @@ jobs:
     steps:
       - name: Checkout
         uses: raycast/github-actions/git-checkout@v1.13.0
-      - name: Setup node
-        uses: raycast/github-actions/setup-node@v1.13.0
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.14.0
       - name: Npm Install
         run: npm ci
       - name: Npm Lint

.gitignore

@@ -1,2 +1,3 @@
 node_modules
 dist
+.parcel-cache

docs/utils-reference/functions/runAppleScript.md

@@ -2,6 +2,10 @@
 
 Function that executes an AppleScript script.
 
+{% hint style="info" %}
+Only available on macOS
+{% endhint %}
+
 ## Signature
 
 There are two ways to use the function.

docs/utils-reference/functions/runPowerShellScript.md

@@ -0,0 +1,76 @@
+# `runPowerShellScript`
+
+Function that executes an PowerShell script.
+
+{% hint style="info" %}
+Only available on Windows
+{% endhint %}
+
+## Signature
+
+```ts
+function runPowerShellScript<T>(
+  script: string,
+  options?: {
+    signal?: AbortSignal;
+    timeout?: number;
+    parseOutput?: ParseExecOutputHandler<T>;
+  },
+): Promise<T>;
+```
+
+### Arguments
+
+- `script` is the script to execute.
+
+With a few options:
+
+- `options.signal` is a Signal object that allows you to abort the request if required via an AbortController object.
+- `options.timeout` is a number. If greater than `0`, the parent will send the signal `SIGTERM` if the script runs longer than timeout milliseconds. By default, the execution will timeout after 10000ms (eg. 10s).
+- `options.parseOutput` is a function that accepts the output of the script as an argument and returns the data the hooks will return - see [ParseExecOutputHandler](#parseexecoutputhandler). By default, the function will return `stdout` as a string.
+
+### Return
+
+Returns a Promise which resolves to a string by default. You can control what it returns by passing `options.parseOutput`.
+
+## Example
+
+```tsx
+import { showHUD } from "@raycast/api";
+import { runPowerShellScript } from "@raycast/utils";
+
+export default async function () {
+  const res = await runPowerShellScript(
+    `
+Write-Host "hello, world."
+`,
+  );
+  await showHUD(res);
+}
+```
+
+## Types
+
+### ParseExecOutputHandler
+
+A function that accepts the output of the script as an argument and returns the data the function will return.
+
+```ts
+export type ParseExecOutputHandler<T> = (args: {
+  /** The output of the script on stdout. */
+  stdout: string;
+  /** The output of the script on stderr. */
+  stderr: string;
+  error?: Error | undefined;
+  /** The numeric exit code of the process that was run. */
+  exitCode: number | null;
+  /** The name of the signal that was used to terminate the process. For example, SIGFPE. */
+  signal: NodeJS.Signals | null;
+  /** Whether the process timed out. */
+  timedOut: boolean;
+  /** The command that was run, for logging purposes. */
+  command: string;
+  /** The options passed to the script, for logging purposes. */
+  options?: ExecOptions | undefined;
+}) => T;
+```

docs/utils-reference/getting-started.md

@@ -16,6 +16,12 @@ npm install --save @raycast/utils
 
 ## Changelog
 
+### 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`](./functions/runPowerShellScript.md) function.
+
 ### v1.19.1
 
 - Fixed an issue where arguments weren't passed to `withCache`.

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

@@ -22,7 +22,7 @@ function useCachedPromise<T, U>(
   options?: {
     initialData?: U;
     keepPreviousData?: boolean;
-    abortable?: MutableRefObject<AbortController | null | undefined>;
+    abortable?: RefObject<AbortController | null | undefined>;
     execute?: boolean;
     onError?: (error: Error) => void;
     onData?: (data: Result<T>) => void;

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

@@ -15,7 +15,7 @@ function usePromise<T>(
   fn: T,
   args?: Parameters<T>,
   options?: {
-    abortable?: MutableRefObject<AbortController | null | undefined>;
+    abortable?: RefObject<AbortController | null | undefined>;
     execute?: boolean;
     onError?: (error: Error) => void;
     onData?: (data: Result<T>) => void;

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

@@ -71,7 +71,7 @@ import { useCallback, useState } from "react";
 
 type Formula = { name: string; desc?: string };
 
-export default function Main(): JSX.Element {
+export default function Main(): React.JSX.Element {
   const [searchText, setSearchText] = useState("");
 
   const formulaFilter = useCallback(
@@ -122,7 +122,7 @@ import { setTimeout } from "timers/promises";
 
 type Formula = { name: string; desc?: string };
 
-export default function Main(): JSX.Element {
+export default function Main(): React.JSX.Element {
   const [searchText, setSearchText] = useState("");
 
   const formulaFilter = useCallback(