Add useLocalStorage hook

docs/utils-reference/SUMMARY.md

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

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

@@ -0,0 +1,68 @@
+# `useLocalStorage`
+
+A hook to manage a value in the local storage.
+
+## Signature
+
+```ts
+function useLocalStorage<T>(key: string, initialValue?: T): {
+  value: T | undefined;
+  setValue: (value: T) => Promise<void>;
+  removeValue: () => Promise<void>;
+  isLoading: boolean;
+}
+```
+
+### 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, isLoading } = 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 isLoading={isLoading}>
+      {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" style={Action.Style.Destructive} onAction={() => toggleTodo(todo.id)} />
+            </ActionPanel>
+          }
+        />
+      ))}
+    </List>
+  );
+}
+```

package.json

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

src/helpers.ts

@@ -0,0 +1,21 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function replacer(this: any, key: string, _value: unknown) {
+  const value = this[key];
+  if (value instanceof Date) {
+    return `__raycast_cached_date__${value.toString()}`;
+  }
+  if (Buffer.isBuffer(value)) {
+    return `__raycast_cached_buffer__${value.toString("base64")}`;
+  }
+  return _value;
+}
+
+export function reviver(_key: string, value: unknown) {
+  if (typeof value === "string" && value.startsWith("__raycast_cached_date__")) {
+    return new Date(value.replace("__raycast_cached_date__", ""));
+  }
+  if (typeof value === "string" && value.startsWith("__raycast_cached_buffer__")) {
+    return Buffer.from(value.replace("__raycast_cached_buffer__", ""), "base64");
+  }
+  return value;
+}

src/index.ts

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

src/useCachedState.ts

@@ -1,28 +1,7 @@
 import { useCallback, Dispatch, SetStateAction, useSyncExternalStore, useMemo } from "react";
 import { Cache } from "@raycast/api";
 import { useLatest } from "./useLatest";
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function replacer(this: any, key: string, _value: unknown) {
-  const value = this[key];
-  if (value instanceof Date) {
-    return `__raycast_cached_date__${value.toString()}`;
-  }
-  if (Buffer.isBuffer(value)) {
-    return `__raycast_cached_buffer__${value.toString("base64")}`;
-  }
-  return _value;
-}
-
-function reviver(_key: string, value: unknown) {
-  if (typeof value === "string" && value.startsWith("__raycast_cached_date__")) {
-    return new Date(value.replace("__raycast_cached_date__", ""));
-  }
-  if (typeof value === "string" && value.startsWith("__raycast_cached_buffer__")) {
-    return Buffer.from(value.replace("__raycast_cached_buffer__", ""), "base64");
-  }
-  return value;
-}
+import { replacer, reviver } from "./helpers";
 
 const rootCache = Symbol("cache without namespace");
 const cacheMap = new Map<string | symbol, Cache>();

src/useLocalStorage.ts

@@ -0,0 +1,64 @@
+import { LocalStorage } from "@raycast/api";
+import { showFailureToast } from "./showFailureToast";
+import { replacer, reviver } from "./helpers";
+import { usePromise } from "./usePromise";
+
+/**
+ * A hook to manage a value in the local storage.
+ *
+ * @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) {
+  const {
+    data: value,
+    isLoading,
+    mutate,
+  } = usePromise(
+    async (storageKey: string) => {
+      const item = await LocalStorage.getItem<string>(storageKey);
+
+      return typeof item !== "undefined" ? (JSON.parse(item, reviver) as T) : initialValue;
+    },
+    [key],
+  );
+
+  async function setValue(value: T) {
+    try {
+      await mutate(LocalStorage.setItem(key, JSON.stringify(value, replacer)), {
+        optimisticUpdate(value) {
+          return value;
+        },
+      });
+    } catch (error) {
+      await showFailureToast(error, { title: "Failed to set value in local storage" });
+    }
+  }
+
+  async function removeValue() {
+    try {
+      await mutate(LocalStorage.removeItem(key), {
+        optimisticUpdate() {
+          return undefined;
+        },
+      });
+    } catch (error) {
+      await showFailureToast(error, { title: "Failed to remove value from local storage" });
+    }
+  }
+
+  return { value, setValue, removeValue, isLoading };
+}

tests/package.json

@@ -185,6 +185,13 @@
       "subtitle": "Utils Smoke Tests",
       "description": "Utils Smoke Tests",
       "mode": "view"
+    },
+    {
+      "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, isLoading } = 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 isLoading={isLoading}>
+      {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" style={Action.Style.Destructive} onAction={() => toggleTodo(todo.id)} />
+            </ActionPanel>
+          }
+        />
+      ))}
+    </List>
+  );
+}