unjs · kricsleo · Apr 11, 2025 · Apr 11, 2025
@@ -182,6 +182,14 @@ You can also use the `keys` alias:
 await storage.keys();
 ```
 
+By default, key retrieval errors halt the process. To ignore errors and fetch available keys, enable `try: true` in the options.
+Failed retrievals will include error details in the result array's `errors` property.
+
+```js
+const keys = await storage.getKeys("base", { try: true });
+// Errors are accessible via `keys.errors`
+```
+
 ### `clear(base?, opts?)`
 
 Removes all stored key/values. If a base is provided, only mounts matching base will be cleared.

@@ -7,6 +7,7 @@ import type {
   StorageValue,
   WatchEvent,
   TransactionOptions,
+  StorageError,
 } from "./types";
 import memory from "./drivers/memory";
 import { asyncCall, deserializeRaw, serializeRaw, stringify } from "./_utils";
@@ -348,6 +349,7 @@ export function createStorage<T extends StorageValue>(
       const mounts = getMounts(base, true);
       let maskedMounts: string[] = [];
       const allKeys = [];
+      const errors: StorageError[] = [];
       let allMountsSupportMaxDepth = true;
       for (const mount of mounts) {
         if (!mount.driver.flags?.maxDepth) {
@@ -357,7 +359,25 @@ export function createStorage<T extends StorageValue>(
           mount.driver.getKeys,
           mount.relativeBase,
           opts
-        );
+        ).catch((error) => {
+          if (!opts.try) {
+            throw error;
+          }
+
+          console.warn(
+            `[unstorage]: Failed to get keys for "${mount.mountpoint}":`,
+            error
+          );
+          errors.push({
+            error,
+            mount: {
+              base: mount.mountpoint,
+              driver: mount.driver,
+            },
+          });
+          return [];
+        });
+
         for (const key of rawKeys) {
           const fullKey = mount.mountpoint + normalizeKey(key);
           if (!maskedMounts.some((p) => fullKey.startsWith(p))) {
@@ -374,11 +394,19 @@ export function createStorage<T extends StorageValue>(
       }
       const shouldFilterByDepth =
         opts.maxDepth !== undefined && !allMountsSupportMaxDepth;
-      return allKeys.filter(
+      const keys = allKeys.filter(
         (key) =>
           (!shouldFilterByDepth || filterKeyByDepth(key, opts.maxDepth)) &&
           filterKeyByBase(key, base)
       );
+      if (opts.try) {
+        Object.defineProperty(keys, "errors", {
+          enumerable: false,
+          value: errors,
+        });
+      }
+
+      return keys;
     },
     // Utils
     async clear(base, opts = {}) {

@@ -20,6 +20,23 @@ export type TransactionOptions = Record<string, any>;
 
 export type GetKeysOptions = TransactionOptions & {
   maxDepth?: number;
+  /**
+   * Whether to ignore errors during key retrieval and return available keys.
+   * @default false
+   */
+  try?: boolean;
+};
+
+export interface StorageError {
+  error: unknown;
+  mount: {
+    base: string;
+    driver: Driver;
+  };
+}
+
+export type WithErrors<T> = T & {
+  errors?: StorageError[];
 };
 
 export interface DriverFlags {
@@ -65,7 +82,10 @@ export interface Driver<OptionsT = any, InstanceT = any> {
     key: string,
     opts: TransactionOptions
   ) => MaybePromise<StorageMeta | null>;
-  getKeys: (base: string, opts: GetKeysOptions) => MaybePromise<string[]>;
+  getKeys: (
+    base: string,
+    opts: GetKeysOptions
+  ) => MaybePromise<WithErrors<string[]>>;
   clear?: (base: string, opts: TransactionOptions) => MaybePromise<void>;
   dispose?: () => MaybePromise<void>;
   watch?: (callback: WatchCallback) => MaybePromise<Unwatch>;
@@ -173,7 +193,10 @@ export interface Storage<T extends StorageValue = StorageValue> {
   ) => Promise<void>;
   removeMeta: (key: string, opts?: TransactionOptions) => Promise<void>;
   // Keys
-  getKeys: (base?: string, opts?: GetKeysOptions) => Promise<string[]>;
+  getKeys: (
+    base?: string,
+    opts?: GetKeysOptions
+  ) => Promise<WithErrors<string[]>>;
   // Utils
   clear: (base?: string, opts?: TransactionOptions) => Promise<void>;
   dispose: () => Promise<void>;

@@ -42,7 +42,16 @@
     storage
       .getKeys(base + key, ...arguments_)
       // Remove Prefix
-      .then((keys) => keys.map((key) => key.slice(base.length)));
+      .then((_keys) => {
+        const keys = _keys.map((key) => key.slice(base.length));
+        if (_keys.errors) {
+          Object.defineProperty(keys, "errors", {
+            enumerable: false,
+            value: _keys.errors,
+          });
+        }
+        return keys;
+      });
 
   nsStorage.getItems = async <U extends T>(
     items: (string | { key: string; options?: TransactionOptions })[],

@@ -7,6 +7,7 @@ import {
   prefixStorage,
 } from "../src";
 import memory from "../src/drivers/memory";
+import redisDriver from "../src/drivers/redis";
 import fs from "../src/drivers/fs";
 
 const data = {
@@ -250,6 +251,28 @@ describe("Regression", () => {
     }
   });
 
+  it("getKeys - ignore errors and fetch available keys ", async () => {
+    const storage = createStorage();
+    const invalidDriver = redisDriver({
+      url: "ioredis://localhost:9999/0",
+      connectTimeout: 10,
+      retryStrategy: () => null,
+    });
+    storage.mount("/invalid", invalidDriver);
+
+    await storage.setItem("foo", "bar");
+
+    await expect(storage.getKeys()).rejects.toThrowError(
+      "Connection is closed"
+    );
+
+    const keys = await storage.getKeys(undefined, { try: true });
+    expect(keys).toMatchObject(["foo"]);
+    expect(keys.errors![0]!.error).toMatchInlineSnapshot(
+      `[Error: Connection is closed.]`
+    );
+  });
+
   it("prefixStorage getItems to not returns null (issue #396)", async () => {
     const storage = createStorage();
     await storage.setItem("namespace:key", "value");