@rozenite/storage-plugin 1.13.0 → 2.0.0

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

@@ -0,0 +1,153 @@
+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,231 @@
+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/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 = {
@@ -36,7 +37,7 @@ const toStorageNode = (
   storageId: string,
   config: AsyncStorageLike | AsyncStorageInstanceConfig,
   fallbackName?: string,
-  fallbackBlacklist?: RegExp
+  fallbackBlacklist?: RegExp,
 ): StorageNode => {
   const resolved =
     'storage' in config
@@ -77,27 +78,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,
           ),
         ];
 
@@ -112,4 +113,5 @@ export const createAsyncStorageAdapter = (
  * @deprecated Use createAsyncStorageAdapter instead.
  */
 export const createExpoAsyncStorageAdapter = createAsyncStorageAdapter;
-export type CreateExpoAsyncStorageAdapterOptions = CreateAsyncStorageAdapterOptions;
+export type CreateExpoAsyncStorageAdapterOptions =
+  CreateAsyncStorageAdapterOptions;

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

@@ -17,6 +17,7 @@ type MMKVAdapter = {
   getBuffer: (key: string) => ArrayBuffer | undefined;
   delete: (key: string) => void;
   getAllKeys: () => string[];
+  clear: () => void;
   addOnValueChangedListener: (callback: (key: string) => void) => {
     remove: () => void;
   };
@@ -52,6 +53,7 @@ const normalizeStorages = (storages: MMKV[] | Record<string, MMKV>) => {
 };
 
 const getMMKVAdapter = (mmkv: MMKV): MMKVAdapter => {
+  const clear = () => mmkv.clearAll();
   if (isMMKVV4(mmkv)) {
     return {
       set: (key, value) => mmkv.set(key, value),
@@ -61,6 +63,7 @@ const getMMKVAdapter = (mmkv: MMKV): MMKVAdapter => {
       getBuffer: (key) => mmkv.getBuffer(key),
       delete: (key) => mmkv.remove(key),
       getAllKeys: () => mmkv.getAllKeys(),
+      clear,
       addOnValueChangedListener: (callback) =>
         mmkv.addOnValueChangedListener(callback),
     };
@@ -74,6 +77,7 @@ const getMMKVAdapter = (mmkv: MMKV): MMKVAdapter => {
     getBuffer: (key) => mmkv.getBuffer(key) as ArrayBuffer | undefined,
     delete: (key) => mmkv.delete(key),
     getAllKeys: () => mmkv.getAllKeys(),
+    clear,
     addOnValueChangedListener: (callback) =>
       mmkv.addOnValueChangedListener(callback),
   };
@@ -199,6 +203,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

@@ -59,12 +59,20 @@ export const createExpoSecureStorageAdapter = ({
       },
       set: async (entry) => {
         if (entry.type !== 'string') {
-          throw new Error('Expo SecureStore adapter supports only string values.');
+          throw new Error(
+            'Expo SecureStore adapter supports only string values.',
+          );
         }
 
         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)),
+        );
+      },
     },
   };