Add useLocalStorage hook

docs/utils-reference/SUMMARY.md

@@ -22,3 +22,4 @@
   - [useSQL](utils-reference/react-hooks/useSQL.md)
   - [useAI](utils-reference/react-hooks/useAI.md)
   - [useFrecencySorting](utils-reference/react-hooks/useFrecencySorting.md)
+  - [useLocalStorage](utils-reference/react-hooks/useLocalStorage.md)

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

@@ -0,0 +1,90 @@
+# `useLocalStorage`
+
+A hook to manage a value in the local storage.
+
+The hook uses `useCachedPromise` internally to cache the value and provide a loading state. The value is stored as a JSON string in the local storage.
+
+## Signature
+
+```ts
+function useLocalStorage<T>(key: string, initialValue: T): UseLocalStorageReturnValue<T>;
+function useLocalStorage<T>(key: string): UseLocalStorageReturnValueWithUndefined<T>;
+```
+
+### Arguments
+
+- `key` - The key to use for the value in the local storage.
+- `initialValue` - The initial value to use if the key doesn't exist in the local storage.
+
+### Return
+
+Returns an object with the following properties:
+
+- `value` - The value from the local storage or the initial value if the key doesn't exist.
+- `setValue` - A function to update the value in the local storage.
+- `removeValue` - A function to remove the value from the local storage.
+- `isLoading` - A boolean indicating if the value is loading.
+
+## Example
+
+```tsx
+import { Action, ActionPanel, Color, Icon, List } from "@raycast/api";
+import { useLocalStorage } from "@raycast/utils";
+
+const exampleTodos = [
+  { id: "1", title: "Buy milk", done: false },
+  { id: "2", title: "Walk the dog", done: false },
+  { id: "3", title: "Call mom", done: false },
+];
+
+export default function Command() {
+  const { value: todos, setValue: setTodos } = useLocalStorage("todos", exampleTodos);
+
+  async function toggleTodo(id: string) {
+    const newTodos = todos.map((todo) => (todo.id === id ? { ...todo, done: !todo.done } : todo));
+    await setTodos(newTodos);
+  }
+
+  return (
+    <List>
+      {todos.map((todo) => (
+        <List.Item
+          icon={todo.done ? { source: Icon.Checkmark, tintColor: Color.Green } : Icon.Circle}
+          key={todo.id}
+          title={todo.title}
+          actions={
+            <ActionPanel>
+              <Action title={todo.done ? "Uncomplete" : "Complete"} onAction={() => toggleTodo(todo.id)} />
+              <Action title="Delete" onAction={() => toggleTodo(todo.id)} />
+            </ActionPanel>
+          }
+        />
+      ))}
+    </List>
+  );
+}
+```
+
+## Types
+
+### UseLocalStorageReturnValue
+
+```ts
+type UseLocalStorageReturnValue<T> = {
+  value: T;
+  setValue: (value: T) => Promise<void>;
+  removeValue: () => Promise<void>;
+  isLoading: boolean;
+};
+```
+
+### UseLocalStorageReturnValueWithUndefined
+
+```ts
+type UseLocalStorageReturnValueWithUndefined<T> = {
+  value?: T;
+  setValue: (value: T) => Promise<void>;
+  removeValue: () => Promise<void>;
+  isLoading: boolean;
+};
+```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raycast/utils",
-  "version": "1.13.5",
+  "version": "1.14.0",
   "description": "Set of utilities to streamline building Raycast extensions",
   "author": "Raycast Technologies Ltd.",
   "homepage": "https://developers.raycast.com/utils-reference",

src/index.ts

@@ -7,6 +7,7 @@ export * from "./useSQL";
 export * from "./useForm";
 export * from "./useAI";
 export * from "./useFrecencySorting";
+export * from "./useLocalStorage";
 
 export * from "./icon";
 

src/useLocalStorage.ts

@@ -0,0 +1,81 @@
+import { LocalStorage } from "@raycast/api";
+import { useCachedPromise } from "./useCachedPromise";
+import { showFailureToast } from "./showFailureToast";
+
+export type UseLocalStorageReturnValue<T> = {
+  value: T;
+  setValue: (value: T) => Promise<void>;
+  removeValue: () => Promise<void>;
+  isLoading: boolean;
+};
+
+export type UseLocalStorageReturnValueWithUndefined<T> = {
+  value?: T;
+  setValue: (value: T) => Promise<void>;
+  removeValue: () => Promise<void>;
+  isLoading: boolean;
+};
+
+/**
+ * A hook to manage a value in the local storage.
+ *
+ * @remark The hook uses `useCachedPromise` internally to cache the value and provide a loading state.
+ * @remark The value is stored as a JSON string in the local storage.
+ *
+ * @param key - The key to use for the value in the local storage.
+ * @param initialValue - The initial value to use if the key doesn't exist in the local storage.
+ * @returns An object with the following properties:
+ * - `value`: The value from the local storage or the initial value if the key doesn't exist.
+ * - `setValue`: A function to update the value in the local storage.
+ * - `removeValue`: A function to remove the value from the local storage.
+ * - `isLoading`: A boolean indicating if the value is loading.
+ *
+ * @example
+ * ```
+ * const { value, setValue } = useLocalStorage<string>("my-key");
+ * const { value, setValue } = useLocalStorage<string>("my-key", "default value");
+ * ```
+ */
+export function useLocalStorage<T>(key: string, initialValue: T): UseLocalStorageReturnValue<T>;
+export function useLocalStorage<T>(key: string): UseLocalStorageReturnValueWithUndefined<T>;
+export function useLocalStorage<T>(key: string, initialValue?: T) {
+  const {
+    data: value,
+    isLoading,
+    mutate,
+  } = useCachedPromise(
+    async (storageKey: string) => {
+      const item = await LocalStorage.getItem<string>(storageKey);
+
+      if (item) {
+        return JSON.parse(item);
+      }
+    },
+    [key],
+    {
+      onError(error) {
+        showFailureToast(error, { title: "Failed to get value from local storage" });
+      },
+    },
+  );
+
+  async function setValue(value: T) {
+    try {
+      await LocalStorage.setItem(key, JSON.stringify(value));
+      await mutate();
+    } catch (error) {
+      await showFailureToast(error, { title: "Failed to set value in local storage" });
+    }
+  }
+
+  async function removeValue() {
+    try {
+      await LocalStorage.removeItem(key);
+      await mutate();
+    } catch (error) {
+      await showFailureToast(error, { title: "Failed to remove value from local storage" });
+    }
+  }
+
+  return { value: value ?? initialValue, setValue, removeValue, isLoading };
+}

tests/package.json

@@ -178,6 +178,13 @@
           "required": true
         }
       ]
+    },
+    {
+      "name": "local-storage",
+      "title": "useLocalStorage",
+      "subtitle": "Utils Smoke Tests",
+      "description": "Utils Smoke Tests",
+      "mode": "view"
     }
   ],
   "dependencies": {

tests/src/local-storage.tsx

@@ -0,0 +1,35 @@
+import { Action, ActionPanel, Color, Icon, List } from "@raycast/api";
+import { useLocalStorage } from "@raycast/utils";
+
+const exampleTodos = [
+  { id: "1", title: "Buy milk", done: false },
+  { id: "2", title: "Walk the dog", done: false },
+  { id: "3", title: "Call mom", done: false },
+];
+
+export default function Command() {
+  const { value: todos, setValue: setTodos } = useLocalStorage("todos", exampleTodos);
+
+  async function toggleTodo(id: string) {
+    const newTodos = todos.map((todo) => (todo.id === id ? { ...todo, done: !todo.done } : todo));
+    await setTodos(newTodos);
+  }
+
+  return (
+    <List>
+      {todos.map((todo) => (
+        <List.Item
+          icon={todo.done ? { source: Icon.Checkmark, tintColor: Color.Green } : Icon.Circle}
+          key={todo.id}
+          title={todo.title}
+          actions={
+            <ActionPanel>
+              <Action title={todo.done ? "Uncomplete" : "Complete"} onAction={() => toggleTodo(todo.id)} />
+              <Action title="Delete" onAction={() => toggleTodo(todo.id)} />
+            </ActionPanel>
+          }
+        />
+      ))}
+    </List>
+  );
+}