@rozenite/storage-plugin 1.13.0 → 2.1.0

package/src/react-native/__tests__/stress-verification.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { StorageAdapter, StorageEntry, StorageEntryType } from '../../shared/types';
+import {
+  ENTRY_PREVIEW_READ_CONCURRENCY,
+  MAX_ENTRY_PREVIEW_PAGE_SIZE,
+  handleListEntryPreviewsRequest,
+} from '../entry-preview-pagination';
+import { handleStorageDiscoveryRequest } from '../storage-discovery';
+import { createStorageViews } from '../storage-view';
+
+const STORAGE_COUNT = 250;
+const ENTRIES_PER_STORAGE = 1_000;
+const MEGABYTE_VALUE = 'x'.repeat(1024 * 1024);
+const selectedTarget = { adapterId: 'stress', storageId: 'storage-000' };
+
+const keys = Array.from(
+  { length: ENTRIES_PER_STORAGE },
+  (_, index) => `entry-${String(index).padStart(4, '0')}`,
+);
+
+const previewRequest = (overrides: Record<string, unknown> = {}) => ({
+  type: 'list-entry-previews' as const,
+  requestId: 'stress-request',
+  target: selectedTarget,
+  limit: MAX_ENTRY_PREVIEW_PAGE_SIZE,
+  ...overrides,
+});
+
+const createStressAdapter = () => {
+  let activeReads = 0;
+  let maxActiveReads = 0;
+  const storageReads = Array.from({ length: STORAGE_COUNT }, (_, index) => {
+    const getAllKeys = vi.fn(async () => keys);
+    const get = vi.fn(async (key: string): Promise<StorageEntry> => {
+      activeReads += 1;
+      maxActiveReads = Math.max(maxActiveReads, activeReads);
+      // This fixture is intentionally asynchronous. The assertion below uses
+      // counts, rather than duration, so it stays deterministic under load.
+      await new Promise((resolve) => setTimeout(resolve, 1));
+      activeReads -= 1;
+      return { key, type: 'string', value: MEGABYTE_VALUE };
+    });
+
+    return {
+      getAllKeys,
+      get,
+      node: {
+        id: `storage-${String(index).padStart(3, '0')}`,
+        name: `Stress storage ${index}`,
+        capabilities: { supportedTypes: ['string'] as StorageEntryType[] },
+        storage: {
+          kind: 'async' as const,
+          getAllKeys,
+          get,
+          set: vi.fn(async () => undefined),
+          delete: vi.fn(async () => undefined),
+          clear: vi.fn(async () => undefined),
+        },
+      },
+    };
+  });
+
+  const adapter: StorageAdapter = {
+    id: 'stress',
+    name: 'Stress adapter',
+    storages: storageReads.map(({ node }) => node),
+  };
+
+  return {
+    maxActiveReads: () => maxActiveReads,
+    storageReads,
+    views: createStorageViews([adapter]),
+  };
+};
+
+describe('storage scalability stress fixture', () => {
+  it('discovers many storages without starting value work', async () => {
+    const fixture = createStressAdapter();
+
+    expect(
+      await handleStorageDiscoveryRequest(fixture.views, {
+        type: 'discover-storages',
+        requestId: 'discover-stress',
+      }),
+    ).toMatchObject({
+      type: 'storage-descriptors',
+      storages: expect.any(Array),
+    });
+    expect(fixture.views).toHaveLength(STORAGE_COUNT);
+    for (const { get, getAllKeys } of fixture.storageReads) {
+      expect(getAllKeys).toHaveBeenCalledTimes(1);
+      expect(get).not.toHaveBeenCalled();
+    }
+  });
+
+  it('reads only one bounded page from the selected storage when values are slow and large', async () => {
+    const fixture = createStressAdapter();
+
+    const result = await handleListEntryPreviewsRequest(fixture.views, previewRequest());
+
+    expect(result).toMatchObject({
+      type: 'entry-previews',
+      items: Array.from({ length: MAX_ENTRY_PREVIEW_PAGE_SIZE }, () =>
+        expect.objectContaining({
+          preview: 'x'.repeat(256),
+          valueSize: MEGABYTE_VALUE.length,
+          isTruncated: true,
+        }),
+      ),
+    });
+    if (result.type === 'entry-previews') {
+      expect(result.items.every((item) => !('value' in item))).toBe(true);
+    }
+    expect(fixture.storageReads[0]?.getAllKeys).toHaveBeenCalledTimes(1);
+    expect(fixture.storageReads[0]?.get).toHaveBeenCalledTimes(MAX_ENTRY_PREVIEW_PAGE_SIZE);
+    expect(fixture.maxActiveReads()).toBeLessThanOrEqual(ENTRY_PREVIEW_READ_CONCURRENCY);
+    for (const { get, getAllKeys } of fixture.storageReads.slice(1)) {
+      expect(getAllKeys).not.toHaveBeenCalled();
+      expect(get).not.toHaveBeenCalled();
+    }
+  });
+
+  it('searches keys first and reads only the resulting page', async () => {
+    const fixture = createStressAdapter();
+
+    const result = await handleListEntryPreviewsRequest(
+      fixture.views,
+      previewRequest({ search: '  0999  ' }),
+    );
+
+    expect(result).toMatchObject({
+      type: 'entry-previews',
+      items: [expect.objectContaining({ key: 'entry-0999' })],
+    });
+    expect(fixture.storageReads[0]?.get).toHaveBeenCalledExactlyOnceWith('entry-0999');
+    for (const { get } of fixture.storageReads.slice(1)) {
+      expect(get).not.toHaveBeenCalled();
+    }
+  });
+});

package/src/react-native/__tests__/use-storage-agent-tools.test.ts

@@ -0,0 +1,221 @@
+import { describe, expect, it, vi } from 'vitest';
+import { MAX_PAGE_LIMIT } from '@rozenite/agent-shared';
+import { storageToolDefinitions } from '../../shared/agent-tools';
+import type { StorageAdapter, StorageEntry } from '../../shared/types';
+
+vi.mock('@rozenite/agent-bridge', () => ({
+  useRozenitePluginAgentTool: vi.fn(),
+}));
+
+import { createStorageAgentHandlers } from '../useStorageAgentTools';
+import { createStorageViews } from '../storage-view';
+
+const createViews = (
+  storages: Array<{
+    adapterId: string;
+    storageId: string;
+    entries: Record<string, StorageEntry>;
+  }>,
+) => {
+  const adapters = storages.map(({ adapterId, storageId, entries }): StorageAdapter => ({
+    id: adapterId,
+    name: `Adapter ${adapterId}`,
+    storages: [
+      {
+        id: storageId,
+        name: `Storage ${storageId}`,
+        capabilities: { supportedTypes: ['string', 'buffer'] },
+        storage: {
+          kind: 'sync',
+          getAllKeys: vi.fn(() => Object.keys(entries)),
+          get: vi.fn((key: string) => entries[key]),
+          set: vi.fn(),
+          delete: vi.fn(),
+          clear: vi.fn(),
+        },
+      },
+    ],
+  }));
+
+  return { adapters, views: createStorageViews(adapters) };
+};
+
+const entries = (...keys: string[]): Record<string, StorageEntry> =>
+  Object.fromEntries(keys.map((key) => [key, { key, type: 'string', value: `value:${key}` }]));
+
+describe('storage Agent tool handlers', () => {
+  it('lists storage descriptors without reading keys or values', async () => {
+    const { adapters, views } = createViews([
+      { adapterId: 'one', storageId: 'first', entries: entries('a') },
+      { adapterId: 'two', storageId: 'second', entries: entries('b') },
+    ]);
+
+    await expect(createStorageAgentHandlers(views).listStorages()).resolves.toEqual({
+      storages: [
+        {
+          adapterId: 'one',
+          storageId: 'first',
+          adapterName: 'Adapter one',
+          storageName: 'Storage first',
+          supportedTypes: ['string', 'buffer'],
+        },
+        {
+          adapterId: 'two',
+          storageId: 'second',
+          adapterName: 'Adapter two',
+          storageName: 'Storage second',
+          supportedTypes: ['string', 'buffer'],
+        },
+      ],
+    });
+    for (const adapter of adapters) {
+      const storage = adapter.storages[0].storage;
+      expect(storage.getAllKeys).not.toHaveBeenCalled();
+      expect(storage.get).not.toHaveBeenCalled();
+    }
+  });
+
+  it('uses the shared cursor pagination contract and returns keys without values', async () => {
+    const { adapters, views } = createViews([
+      {
+        adapterId: 'adapter',
+        storageId: 'storage',
+        entries: entries('first', 'second', 'third'),
+      },
+    ]);
+    const handlers = createStorageAgentHandlers(views);
+
+    expect(storageToolDefinitions.listEntries.pagination).toEqual({
+      kind: 'cursor',
+      fields: ['key'],
+      defaultFields: ['key'],
+    });
+
+    const first = await handlers.listEntries({ limit: 2 });
+    expect(first).toEqual({
+      adapterId: 'adapter',
+      storageId: 'storage',
+      total: 3,
+      items: [{ key: 'first' }, { key: 'second' }],
+      page: {
+        limit: 2,
+        hasMore: true,
+        nextCursor: expect.any(String),
+      },
+    });
+    expect(first.items.every((item) => !('value' in item))).toBe(true);
+
+    await expect(handlers.listEntries({ cursor: first.page.nextCursor })).resolves.toEqual({
+      adapterId: 'adapter',
+      storageId: 'storage',
+      total: 3,
+      items: [{ key: 'third' }],
+      page: { limit: 20, hasMore: false },
+    });
+    expect(adapters[0].storages[0].storage.get).not.toHaveBeenCalled();
+  });
+
+  it('defaults invalid limits and offsets and caps oversized finite limits', async () => {
+    const { views } = createViews([
+      {
+        adapterId: 'adapter',
+        storageId: 'storage',
+        entries: entries(
+          ...Array.from({ length: MAX_PAGE_LIMIT + 1 }, (_, index) => String(index)),
+        ),
+      },
+    ]);
+    const handlers = createStorageAgentHandlers(views);
+
+    for (const limit of [-1, 1.5, Number.NaN, Number.POSITIVE_INFINITY]) {
+      await expect(handlers.listEntries({ limit })).resolves.toMatchObject({
+        page: { limit: 20 },
+      });
+    }
+    for (const offset of [
+      -1,
+      1.5,
+      Number.NaN,
+      Number.POSITIVE_INFINITY,
+      Number.MAX_SAFE_INTEGER + 1,
+    ]) {
+      await expect(handlers.listEntries({ offset })).resolves.toMatchObject({
+        items: expect.arrayContaining([{ key: '0' }]),
+      });
+    }
+    const capped = await handlers.listEntries({ limit: MAX_PAGE_LIMIT + 1 });
+    expect(capped.items).toHaveLength(MAX_PAGE_LIMIT);
+    expect(capped.page).toMatchObject({
+      limit: MAX_PAGE_LIMIT,
+      hasMore: true,
+    });
+  });
+
+  it('rejects malformed and target-mismatched cursors and ambiguous selections', async () => {
+    const { views } = createViews([
+      { adapterId: 'adapter', storageId: 'one', entries: entries('a', 'b') },
+      { adapterId: 'adapter', storageId: 'two', entries: entries('c') },
+      { adapterId: 'other', storageId: 'one', entries: entries('d') },
+    ]);
+    const handlers = createStorageAgentHandlers(views);
+    const cursor = (
+      await handlers.listEntries({
+        adapterId: 'adapter',
+        storageId: 'one',
+        limit: 1,
+      })
+    ).page.nextCursor!;
+
+    await expect(
+      handlers.listEntries({
+        adapterId: 'adapter',
+        storageId: 'one',
+        cursor: 'bad',
+      }),
+    ).rejects.toThrow('Invalid cursor');
+    await expect(
+      handlers.listEntries({
+        adapterId: 'other',
+        storageId: 'one',
+        cursor,
+      }),
+    ).rejects.toThrow('Cursor does not match the requested storage');
+    await expect(
+      handlers.listEntries({
+        adapterId: 'adapter',
+        storageId: 'one',
+        cursor,
+        offset: 0,
+      }),
+    ).rejects.toThrow('either cursor or offset');
+    await expect(handlers.listEntries({ adapterId: 'adapter' })).rejects.toThrow(
+      'Multiple storages matched',
+    );
+    await expect(handlers.listEntries({ storageId: 'one' })).rejects.toThrow(
+      'Multiple storages matched',
+    );
+  });
+
+  it('returns a complete large value only when read-entry explicitly requests it', async () => {
+    const value = 'x'.repeat(100_000);
+    const { adapters, views } = createViews([
+      {
+        adapterId: 'adapter',
+        storageId: 'storage',
+        entries: {
+          large: { key: 'large', type: 'string', value },
+          other: { key: 'other', type: 'string', value: 'not read' },
+        },
+      },
+    ]);
+    const handlers = createStorageAgentHandlers(views);
+
+    await expect(handlers.readEntry({ key: 'large' })).resolves.toEqual({
+      adapterId: 'adapter',
+      storageId: 'storage',
+      entry: { key: 'large', type: 'string', value },
+    });
+    expect(adapters[0].storages[0].storage.get).toHaveBeenCalledTimes(1);
+    expect(adapters[0].storages[0].storage.get).toHaveBeenCalledWith('large');
+  });
+});

package/src/react-native/adapters/__tests__/mmkv.test.ts

@@ -109,9 +109,9 @@ describe('createMMKVStorageAdapter', () => {
   it('rejects MMKV v4 storages passed as an array', () => {
     const storage = createFakeMMKVV4();
 
-    expect(() =>
-      createMMKVStorageAdapter({ storages: [storage as any] }),
-    ).toThrow(/MMKV arrays are not supported for v4 storages/);
+    expect(() => createMMKVStorageAdapter({ storages: [storage as any] })).toThrow(
+      /MMKV arrays are not supported for v4 storages/,
+    );
   });
 
   it('applies global blacklist patterns against storageId:key', async () => {
@@ -129,12 +129,8 @@ describe('createMMKVStorageAdapter', () => {
     });
 
     const views = createStorageViews([adapter]);
-    const userView = views.find(
-      (view) => view.target.storageId === 'user-storage',
-    );
-    const cacheView = views.find(
-      (view) => view.target.storageId === 'cache-storage',
-    );
+    const userView = views.find((view) => view.target.storageId === 'user-storage');
+    const cacheView = views.find((view) => view.target.storageId === 'cache-storage');
 
     expect(userView).toBeDefined();
     expect(cacheView).toBeDefined();
@@ -173,22 +169,20 @@ const createAmbiguousFakeMMKVV4 = ({
   const values = new Map<string, Stored>();
 
   return {
-    set: vi.fn(
-      (key: string, value: string | number | boolean | ArrayBuffer) => {
-        if (typeof value === 'string') {
-          values.set(key, { kind: 'string', value });
-        } else if (typeof value === 'number') {
-          values.set(key, { kind: 'number', value });
-        } else if (typeof value === 'boolean') {
-          values.set(key, { kind: 'boolean', value });
-        } else {
-          values.set(key, {
-            kind: 'buffer',
-            bytes: new Uint8Array(value),
-          });
-        }
-      },
-    ),
+    set: vi.fn((key: string, value: string | number | boolean | ArrayBuffer) => {
+      if (typeof value === 'string') {
+        values.set(key, { kind: 'string', value });
+      } else if (typeof value === 'number') {
+        values.set(key, { kind: 'number', value });
+      } else if (typeof value === 'boolean') {
+        values.set(key, { kind: 'boolean', value });
+      } else {
+        values.set(key, {
+          kind: 'buffer',
+          bytes: new Uint8Array(value),
+        });
+      }
+    }),
     getString: vi.fn((key: string) => {
       const stored = values.get(key);
       if (!stored) return undefined;
@@ -205,11 +199,7 @@ const createAmbiguousFakeMMKVV4 = ({
     getNumber: vi.fn((key: string) => {
       const stored = values.get(key);
       if (stored?.kind === 'number') return stored.value;
-      if (
-        lenientGetNumber &&
-        stored?.kind === 'buffer' &&
-        stored.bytes.byteLength === 8
-      ) {
+      if (lenientGetNumber && stored?.kind === 'buffer' && stored.bytes.byteLength === 8) {
         return new DataView(stored.bytes.buffer).getFloat64(0, true);
       }
       return undefined;

package/src/react-native/adapters/async-storage.ts

@@ -5,6 +5,7 @@ export type AsyncStorageLike = {
   getItem: (key: string) => Promise<string | null>;
   setItem: (key: string, value: string) => Promise<void>;
   removeItem: (key: string) => Promise<void>;
+  clear: () => Promise<void>;
 };
 
 export type AsyncStorageInstanceConfig = {
@@ -28,15 +29,13 @@ type MultiStorageOptions = {
   adapterName?: string;
 };
 
-export type CreateAsyncStorageAdapterOptions =
-  | SingleStorageOptions
-  | MultiStorageOptions;
+export type CreateAsyncStorageAdapterOptions = SingleStorageOptions | MultiStorageOptions;
 
 const toStorageNode = (
   storageId: string,
   config: AsyncStorageLike | AsyncStorageInstanceConfig,
   fallbackName?: string,
-  fallbackBlacklist?: RegExp
+  fallbackBlacklist?: RegExp,
 ): StorageNode => {
   const resolved =
     'storage' in config
@@ -77,27 +76,27 @@ const toStorageNode = (
         await storage.setItem(entry.key, entry.value);
       },
       delete: (key) => storage.removeItem(key),
+      clear: () => storage.clear(),
     },
   };
 };
 
 export const createAsyncStorageAdapter = (
-  options: CreateAsyncStorageAdapterOptions
+  options: CreateAsyncStorageAdapterOptions,
 ): StorageAdapter => {
-  const { adapterId = 'async-storage', adapterName = 'AsyncStorage' } =
-    options;
+  const { adapterId = 'async-storage', adapterName = 'AsyncStorage' } = options;
 
   const storageNodes: StorageNode[] =
     'storages' in options
       ? Object.entries(options.storages).map(([storageId, config]) =>
-          toStorageNode(storageId, config)
+          toStorageNode(storageId, config),
         )
       : [
           toStorageNode(
             options.storageId ?? 'default',
             options.storage,
             options.storageName ?? 'Default Storage',
-            options.blacklist
+            options.blacklist,
           ),
         ];
 

package/src/react-native/adapters/index.ts

@@ -1,10 +1,7 @@
 export { createMMKVStorageAdapter } from './mmkv';
 export type { CreateMMKVStorageAdapterOptions } from './mmkv';
 
-export {
-  createAsyncStorageAdapter,
-  createExpoAsyncStorageAdapter,
-} from './async-storage';
+export { createAsyncStorageAdapter, createExpoAsyncStorageAdapter } from './async-storage';
 export type {
   AsyncStorageInstanceConfig,
   AsyncStorageLike,
@@ -13,7 +10,4 @@ export type {
 } from './async-storage';
 
 export { createExpoSecureStorageAdapter } from './secure-storage';
-export type {
-  CreateExpoSecureStorageAdapterOptions,
-  SecureStorageLike,
-} from './secure-storage';
+export type { CreateExpoSecureStorageAdapterOptions, SecureStorageLike } from './secure-storage';

package/src/react-native/adapters/mmkv.ts

@@ -1,10 +1,6 @@
 import type { MMKV as MMKVV3 } from 'react-native-mmkv-v3';
 import type { MMKV as MMKVV4 } from 'react-native-mmkv-v4';
-import type {
-  StorageAdapter,
-  StorageEntry,
-  StorageNode,
-} from '../../shared/types';
+import type { StorageAdapter, StorageEntry, StorageNode } from '../../shared/types';
 import { DEFAULT_SUPPORTED_TYPES } from '../../shared/types';
 
 type MMKV = MMKVV3 | MMKVV4;
@@ -17,6 +13,7 @@ type MMKVAdapter = {
   getBuffer: (key: string) => ArrayBuffer | undefined;
   delete: (key: string) => void;
   getAllKeys: () => string[];
+  clear: () => void;
   addOnValueChangedListener: (callback: (key: string) => void) => {
     remove: () => void;
   };
@@ -43,15 +40,14 @@ const normalizeStorages = (storages: MMKV[] | Record<string, MMKV>) => {
       );
     }
 
-    return Object.fromEntries(
-      (storages as MMKVV3[]).map((storage) => [storage['id'], storage]),
-    );
+    return Object.fromEntries((storages as MMKVV3[]).map((storage) => [storage['id'], storage]));
   }
 
   return storages;
 };
 
 const getMMKVAdapter = (mmkv: MMKV): MMKVAdapter => {
+  const clear = () => mmkv.clearAll();
   if (isMMKVV4(mmkv)) {
     return {
       set: (key, value) => mmkv.set(key, value),
@@ -61,8 +57,8 @@ const getMMKVAdapter = (mmkv: MMKV): MMKVAdapter => {
       getBuffer: (key) => mmkv.getBuffer(key),
       delete: (key) => mmkv.remove(key),
       getAllKeys: () => mmkv.getAllKeys(),
-      addOnValueChangedListener: (callback) =>
-        mmkv.addOnValueChangedListener(callback),
+      clear,
+      addOnValueChangedListener: (callback) => mmkv.addOnValueChangedListener(callback),
     };
   }
 
@@ -74,8 +70,8 @@ const getMMKVAdapter = (mmkv: MMKV): MMKVAdapter => {
     getBuffer: (key) => mmkv.getBuffer(key) as ArrayBuffer | undefined,
     delete: (key) => mmkv.delete(key),
     getAllKeys: () => mmkv.getAllKeys(),
-    addOnValueChangedListener: (callback) =>
-      mmkv.addOnValueChangedListener(callback),
+    clear,
+    addOnValueChangedListener: (callback) => mmkv.addOnValueChangedListener(callback),
   };
 };
 
@@ -98,10 +94,7 @@ const getMMKVAdapter = (mmkv: MMKV): MMKVAdapter => {
 //      those keys, so the chain falls through.
 //   4. Empty string — intentional `setString(key, "")` lands here once
 //      we've ruled out a non-empty buffer payload at the same key.
-const getEntry = (
-  adapter: MMKVAdapter,
-  key: string,
-): StorageEntry | undefined => {
+const getEntry = (adapter: MMKVAdapter, key: string): StorageEntry | undefined => {
   const stringValue = adapter.getString(key);
   if (stringValue !== undefined && stringValue.length > 0) {
     return { key, type: 'string', value: stringValue };
@@ -141,10 +134,7 @@ const setEntry = (adapter: MMKVAdapter, entry: StorageEntry) => {
   }
 };
 
-const getStorageBlacklist = (
-  config: MMKVBlacklistConfig | undefined,
-  storageId: string,
-) => {
+const getStorageBlacklist = (config: MMKVBlacklistConfig | undefined, storageId: string) => {
   if (!config) {
     return undefined;
   }
@@ -176,10 +166,7 @@ export const createMMKVStorageAdapter = ({
   storages,
   blacklist,
 }: CreateMMKVStorageAdapterOptions): StorageAdapter => {
-  const normalizedStorages = normalizeStorages(storages) as Record<
-    string,
-    MMKV
-  >;
+  const normalizedStorages = normalizeStorages(storages) as Record<string, MMKV>;
 
   const storageNodes: StorageNode[] = Object.entries(normalizedStorages).map(
     ([storageId, storage]) => {
@@ -199,6 +186,7 @@ export const createMMKVStorageAdapter = ({
           get: (key) => getEntry(mmkv, key),
           set: (entry) => setEntry(mmkv, entry),
           delete: (key) => mmkv.delete(key),
+          clear: mmkv.clear,
           subscribe: (callback) => mmkv.addOnValueChangedListener(callback),
         },
       };

package/src/react-native/adapters/secure-storage.ts

@@ -65,6 +65,10 @@ export const createExpoSecureStorageAdapter = ({
         await storage.setItemAsync(entry.key, entry.value);
       },
       delete: (key) => storage.deleteItemAsync(key),
+      clear: async () => {
+        const storageKeys = await resolveKeys(keys);
+        await Promise.all(storageKeys.map((key) => storage.deleteItemAsync(key)));
+      },
     },
   };