Open source @raycast/utils

.eslintrc.json

@@ -0,0 +1,32 @@
+{
+  "root": true,
+  "env": {
+    "es2021": true,
+    "node": true
+  },
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint", "react-hooks"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:import/recommended",
+    "plugin:import/typescript",
+    "plugin:@typescript-eslint/recommended",
+    "prettier",
+    "plugin:react-hooks/recommended"
+  ],
+  "rules": {
+    "react-hooks/rules-of-hooks": "error",
+    "react-hooks/exhaustive-deps": "warn",
+    "@typescript-eslint/no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }],
+    "import/no-unresolved": [2, { "ignore": ["@raycast/api"] }]
+  },
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {
+        "@typescript-eslint/explicit-module-boundary-types": "off",
+        "@typescript-eslint/no-namespace": "off"
+      }
+    }
+  ]
+}

.github/workflows/test.yml

@@ -0,0 +1,36 @@
+name: Test
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - "src/**"
+      - "tests/**"
+    branches: [main, master]
+  push:
+    paths:
+      - "src/**"
+      - "tests/**"
+    branches: [main, master]
+
+jobs:
+  tests:
+    if: github.repository == 'raycast/utils'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: raycast/github-actions/[email protected]
+      - name: Setup node
+        uses: raycast/github-actions/[email protected]
+      - name: Npm Install
+        run: npm ci
+      - name: Npm Lint
+        run: npm run test
+      - name: Build
+        run: npm run build
+      - name: Npm Install Tests
+        run: npm ci
+        working-directory: ./tests
+      - name: Build tests
+        run: npm run build
+        working-directory: ./tests

.gitignore

@@ -0,0 +1,2 @@
+node_modules
+dist

.prettierrc

@@ -0,0 +1,5 @@
+{
+  "tabWidth": 2,
+  "printWidth": 120,
+  "singleQuote": false
+}

README.md

@@ -0,0 +1,19 @@
+# Raycast Utilities
+
+In addition to the [Raycast API](https://developers.raycast.com/api-reference/ai) 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.
+
+![image](https://user-images.githubusercontent.com/3254314/181186048-37bf34c2-a317-4181-8976-2122af6a8506.png)
+
+## Installation
+
+This package can be installed independently using `npm`.
+
+```
+npm install --save @raycast/utils
+```
+
+[`@raycast/utils`](https://www.npmjs.com/package/@raycast/utils) has a [peer dependency](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#peerdependencies) on [`@raycast/api`](https://www.npmjs.com/package/@raycast/api). This means that a certain version of `@raycast/utils` will require a version above a certain version of `@raycast/api`. `npm` will warn you if that is not the case.
+
+## Documentation
+
+Find the documentation on [developers.raycast.com](https://developers.raycast.com/utils-reference).

docs/utils-reference/SUMMARY.md

@@ -0,0 +1,16 @@
+## Utilities
+
+- [Getting Started](utils-reference/getting-started.md)
+- [Icons](utils-reference/icons/README.md)
+  - [getAvatarIcon](utils-reference/icons/getAvatarIcon.md)
+  - [getFavicon](utils-reference/icons/getFavicon.md)
+  - [getProgressIcon](utils-reference/icons/getProgressIcon.md)
+- [React hooks](utils-reference/react-hooks/README.md)
+  - [useCachedState](utils-reference/react-hooks/useCachedState.md)
+  - [usePromise](utils-reference/react-hooks/usePromise.md)
+  - [useCachedPromise](utils-reference/react-hooks/useCachedPromise.md)
+  - [useFetch](utils-reference/react-hooks/useFetch.md)
+  - [useForm](utils-reference/react-hooks/useForm.md)
+  - [useExec](utils-reference/react-hooks/useExec.md)
+  - [useSQL](utils-reference/react-hooks/useSQL.md)
+  - [useAI](utils-reference/react-hooks/useAI.md)

docs/utils-reference/getting-started.md

@@ -0,0 +1,42 @@
+# Raycast Utilities
+
+In addition to the [Raycast API](../api-reference/cache.md) 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.
+
+![](../.gitbook/assets/utils-illustration.jpg)
+
+## Installation
+
+This package can be installed independently using `npm`.
+
+```
+npm install --save @raycast/utils
+```
+
+`@raycast/utils` has a [peer dependency](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#peerdependencies) 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
+
+### v1.4.0
+
+Added the [`useSQL`](./react-hooks/useSQL.md) 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`](./react-hooks/useExec.md) and [`useForm`](./react-hooks/useForm.md) hooks.
+
+### v1.1.0
+
+Added [`getFavicon`](./icons/getFavicon.md) method.
+
+### v1.0.0
+
+First release of the utilities.

docs/utils-reference/icons/README.md

@@ -0,0 +1 @@
+# Icons

docs/utils-reference/icons/getAvatarIcon.md

@@ -0,0 +1,38 @@
+# `getAvatarIcon`
+
+Icon to represent an avatar when you don't have one. The generated avatar will be generated from the initials of the name and have a colorful but consistent background.
+
+![Avatar Icon example](../../.gitbook/assets/utils-avatar-icon.png)
+
+## Signature
+
+```ts
+function getAvatarIcon(
+  name: string,
+  options?: {
+    background?: string;
+    gradient?: boolean;
+  }
+): Image.Asset;
+```
+
+- `name` is a string of the subject's name.
+- `options.background` is a hexadecimal representation of a color to be used as the background color. By default, the hook will pick a random but consistent (eg. the same name will the same color) color from a set handpicked to nicely match Raycast.
+- `options.gradient` is a boolean to choose whether the background should have a slight gradient or not. By default, it will.
+
+Returns an [Image.Asset](../../api-reference/user-interface/icons-and-images.md) that can be used where Raycast expects them.
+
+## Example
+
+```tsx
+import { List } from "@raycast/api";
+import { getAvatarIcon } from "@raycast/utils";
+
+export default function Command() {
+  return (
+    <List>
+      <List.Item icon={getAvatarIcon("John Doe")} title="John Doe" />
+    </List>
+  );
+}
+```

docs/utils-reference/icons/getFavicon.md

@@ -0,0 +1,42 @@
+# `getFavicon`
+
+Icon showing the favicon of a website.
+
+A favicon (favorite icon) is a tiny icon included along with a website, which is displayed in places like the browser's address bar, page tabs, and bookmarks menu.
+
+![Favicon example](../../.gitbook/assets/utils-favicon.png)
+
+## Signature
+
+```ts
+function getFavicon(
+  url: string | URL,
+  options?: {
+    fallback?: Image.Fallback;
+    size?: boolean;
+    mask?: Image.Mask;
+  }
+): Image.ImageLike;
+```
+
+- `name` is a string of the subject's name.
+- `options.fallback` is a [Image.Fallback](../../api-reference/user-interface/icons-and-images.md#image.fallback) icon in case the Favicon is not found. By default, the fallback will be `Icon.Link`.
+- `options.size` is the size of the returned favicon. By default, it is 64 pixels.
+- `options.mask` is the size of the [Image.Mask](../../api-reference/user-interface/icons-and-images.md#image.mask) to apply to the favicon.
+
+Returns an [Image.ImageLike](../../api-reference/user-interface/icons-and-images.md) that can be used where Raycast expects them.
+
+## Example
+
+```tsx
+import { List } from "@raycast/api";
+import { getFavicon } from "@raycast/utils";
+
+export default function Command() {
+  return (
+    <List>
+      <List.Item icon={getFavicon("https://raycast.com")} title="Raycast Website" />
+    </List>
+  );
+}
+```

docs/utils-reference/icons/getProgressIcon.md

@@ -0,0 +1,40 @@
+# `getProgressIcon`
+
+Icon to represent the progress of a task, a project, _something_.
+
+![Progress Icon example](../../.gitbook/assets/utils-progress-icon.png)
+
+## Signature
+
+```ts
+function getProgressIcon(
+  progress: number,
+  color?: Color | string,
+  options?: {
+    background?: string;
+    backgroundOpacity?: number;
+  }
+): Image.Asset;
+```
+
+- `progress` is a number between 0 and 1 (0 meaning not started, 1 meaning finished).
+- `color` is a Raycast `Color` or a hexadecimal representation of a color. By default it will be `Color.Red`.
+- `options.background` is the color of the background of the progress icon. By default, it will be `white` if the Raycast's appearance is `dark`, and `black` if the appearance is `light`.
+- `options.backgroundOpacity` is the opacity of the background of the progress icon. By default, it will be `0.1`.
+
+Returns an [Image.Asset](../../api-reference/user-interface/icons-and-images.md) that can be used where Raycast expects them.
+
+## Example
+
+```tsx
+import { List } from "@raycast/api";
+import { getProgressIcon } from "@raycast/utils";
+
+export default function Command() {
+  return (
+    <List>
+      <List.Item icon={getProgressIcon(0.1)} title="Project" />
+    </List>
+  );
+}
+```

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

@@ -0,0 +1 @@
+# React Hooks

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

@@ -0,0 +1,95 @@
+# `useAI`
+
+Hook which asks the AI to answer a prompt and returns the [AsyncState](#asyncstate) corresponding to the execution of the query.
+
+## Signature
+
+```ts
+function useAI(
+  prompt: string,
+  options?: {
+    creativity?: AI.Creativity;
+    model?: AI.Model;
+    stream?: boolean;
+    execute?: boolean;
+    onError?: (error: Error) => void;
+    onData?: (data: T) => void;
+    onWillExecute?: (args: string[]) -> void;
+  }
+): AsyncState<String> & {
+  revalidate: () => void;
+};
+```
+
+### Arguments
+
+- `prompt` is the prompt to ask the AI.
+
+With a few options:
+
+- `options.creativity` is a number between 0 and 2 to control the creativity of the answer. Concrete tasks, such as fixing grammar, require less creativity while open-ended questions, such as generating ideas, require more.
+- `options.model` is a string determining which AI model will be used to answer.
+- `options.stream` is a boolean controlling whether to stream the answer or only update the data when the entire answer has been received. By default, the `data` will be streamed.
+
+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.
+
+### Return
+
+Returns an object with the [AsyncState](#asyncstate) corresponding to the execution of the function as well as a couple of methods to manipulate it.
+
+- `data`, `error`, `isLoading` - see [AsyncState](#asyncstate).
+- `revalidate` is a method to manually call the function with the same arguments again.
+
+## Example
+
+```tsx
+import { Detail } from "@raycast/api";
+import { useAI } from "@raycast/utils";
+
+export default function Command() {
+  const { data, isLoading } = useAI("Suggest 5 jazz songs");
+
+  return <Detail isLoading={isLoading} markdown={data} />;
+}
+```
+
+## Types
+
+### AsyncState
+
+An object corresponding to the execution state of the function.
+
+```ts
+// Initial State
+{
+  isLoading: true, // or `false` if `options.execute` is `false`
+  data: undefined,
+  error: undefined
+}
+
+// Success State
+{
+  isLoading: false,
+  data: string,
+  error: undefined
+}
+
+// Error State
+{
+  isLoading: false,
+  data: undefined,
+  error: Error
+}
+
+// Reloading State
+{
+  isLoading: true,
+  data: string | undefined,
+  error: Error | undefined
+}
+```