@rozenite/storage-plugin 1.13.0 → 2.1.0

package/src/react-native/__tests__/import.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it, vi } from 'vitest';
-import { handleImportEntries, type ImportEmittedEvent } from '../import';
+import {
+  handleImportEntries,
+  handleImportPreviewRequest,
+  type ImportEmittedEvent,
+} from '../import';
 import type { StorageView } from '../storage-view';
 import { getStorageViewId } from '../../shared/types';
 import type { StorageEntry, StorageTarget } from '../../shared/types';
@@ -24,10 +28,12 @@ const buildView = (overrides?: Partial<StorageView>): StorageView => {
     get: unexpected('get'),
     set: vi.fn(async () => {}),
     delete: unexpected('delete'),
-    getAllKeys: unexpected('getAllKeys'),
+    purge: unexpected('purge'),
+    getAllKeys: vi.fn(async () => []),
     getAllEntries: unexpected('getAllEntries'),
     watch: unexpected('watch'),
     ...overrides,
+    supportsSubscriptions: overrides?.supportsSubscriptions ?? false,
   };
 };
 
@@ -39,11 +45,12 @@ const buildEntries = (count: number): StorageEntry[] =>
   }));
 
 describe('handleImportEntries', () => {
-  it('emits a set-entry echo per write followed by a success import-result', async () => {
+  it('emits value-free progress, one invalidation, and one success import-result', async () => {
     const view = buildView();
     const entries = buildEntries(5);
     const event: StorageImportEntriesEvent = {
       type: 'import-entries',
+      requestId: 'request-1',
       target,
       entries,
     };
@@ -53,16 +60,25 @@ describe('handleImportEntries', () => {
 
     expect(view.set).toHaveBeenCalledTimes(5);
 
-    expect(emitted).toHaveLength(6);
+    expect(emitted).toHaveLength(7);
     expect(emitted.slice(0, 5)).toEqual(
-      entries.map((entry) => ({
-        type: 'set-entry',
+      entries.map((_, index) => ({
+        type: 'import-progress',
+        requestId: 'request-1',
         target,
-        entry,
+        written: index + 1,
+        total: 5,
       })),
     );
     expect(emitted[5]).toEqual({
+      type: 'storage-invalidated',
+      target,
+      operation: 'import',
+      entryCount: 0,
+    });
+    expect(emitted[6]).toEqual({
       type: 'import-result',
+      requestId: 'request-1',
       target,
       ok: true,
       written: 5,
@@ -82,6 +98,7 @@ describe('handleImportEntries', () => {
     const entries = buildEntries(5);
     const event: StorageImportEntriesEvent = {
       type: 'import-entries',
+      requestId: 'request-1',
       target,
       entries,
     };
@@ -89,13 +106,28 @@ describe('handleImportEntries', () => {
 
     await handleImportEntries([view], event, (out) => emitted.push(out));
 
-    // 2 set-entry echoes (k0, k1), then the failure result. No echoes for k2+.
+    // 2 value-free progress events (k0, k1), one batch invalidation, then failure.
     expect(view.set).toHaveBeenCalledTimes(3);
-    expect(emitted).toHaveLength(3);
-    expect(emitted[0]).toMatchObject({ type: 'set-entry', entry: entries[0] });
-    expect(emitted[1]).toMatchObject({ type: 'set-entry', entry: entries[1] });
+    expect(emitted).toHaveLength(4);
+    expect(emitted[0]).toMatchObject({
+      type: 'import-progress',
+      requestId: 'request-1',
+      written: 1,
+    });
+    expect(emitted[1]).toMatchObject({
+      type: 'import-progress',
+      requestId: 'request-1',
+      written: 2,
+    });
     expect(emitted[2]).toEqual({
+      type: 'storage-invalidated',
+      target,
+      operation: 'import',
+      entryCount: 0,
+    });
+    expect(emitted[3]).toEqual({
       type: 'import-result',
+      requestId: 'request-1',
       target,
       ok: false,
       written: 2,
@@ -113,6 +145,7 @@ describe('handleImportEntries', () => {
     });
     const event: StorageImportEntriesEvent = {
       type: 'import-entries',
+      requestId: 'request-1',
       target,
       entries: buildEntries(1),
     };
@@ -123,6 +156,7 @@ describe('handleImportEntries', () => {
     expect(emitted).toHaveLength(1);
     expect(emitted[0]).toMatchObject({
       type: 'import-result',
+      requestId: 'request-1',
       ok: false,
       error: 'plain string failure',
     });
@@ -137,6 +171,7 @@ describe('handleImportEntries', () => {
     const entries = buildEntries(3);
     const event: StorageImportEntriesEvent = {
       type: 'import-entries',
+      requestId: 'request-1',
       target: unknownTarget,
       entries,
     };
@@ -148,6 +183,7 @@ describe('handleImportEntries', () => {
     expect(emitted).toEqual([
       {
         type: 'import-result',
+        requestId: 'request-1',
         target: unknownTarget,
         ok: false,
         written: 0,
@@ -161,6 +197,7 @@ describe('handleImportEntries', () => {
     const view = buildView();
     const event: StorageImportEntriesEvent = {
       type: 'import-entries',
+      requestId: 'request-1',
       target,
       entries: [],
     };
@@ -172,6 +209,7 @@ describe('handleImportEntries', () => {
     expect(emitted).toEqual([
       {
         type: 'import-result',
+        requestId: 'request-1',
         target,
         ok: true,
         written: 0,
@@ -179,4 +217,129 @@ describe('handleImportEntries', () => {
       },
     ]);
   });
+
+  it('previews current device keys and blacklist decisions without reading values', async () => {
+    const view = buildView({
+      getAllKeys: vi.fn(async () => ['existing', 'unseen']),
+      blacklist: /^private$/,
+    });
+
+    const result = await handleImportPreviewRequest([view], {
+      type: 'preview-import',
+      requestId: 'preview-1',
+      target,
+      snapshot: {
+        version: 1,
+        plugin: '@rozenite/storage-plugin',
+        createdAt: '2026-01-01T00:00:00.000Z',
+        storage: {
+          adapterId: target.adapterId,
+          storageId: target.storageId,
+          adapterName: 'MMKV',
+          storageName: 'user',
+          capabilities: view.capabilities,
+        },
+        entries: [
+          { key: 'existing', type: 'string', value: 'new' },
+          { key: 'fresh', type: 'string', value: 'value' },
+          { key: 'private', type: 'string', value: 'hidden' },
+        ],
+      },
+    });
+
+    expect(result).toMatchObject({
+      type: 'import-preview',
+      requestId: 'preview-1',
+      target,
+      preview: {
+        overwriteKeys: ['existing'],
+        newKeys: ['fresh'],
+        skippedKeys: [{ key: 'private', reason: 'blacklist' }],
+        acceptedEntryIndexes: [0, 1],
+      },
+    });
+    expect(view.get).not.toHaveBeenCalled();
+  });
+
+  it('rechecks blacklist and supported types when applying a stale preview', async () => {
+    const view = buildView({
+      capabilities: { supportedTypes: ['string'] },
+      blacklist: /^blocked$/,
+    });
+    const emitted: ImportEmittedEvent[] = [];
+
+    await handleImportEntries(
+      [view],
+      {
+        type: 'import-entries',
+        requestId: 'request-1',
+        target,
+        entries: [
+          { key: 'blocked', type: 'string', value: 'skip' },
+          { key: 'binary', type: 'buffer', value: [1] },
+          { key: 'kept', type: 'string', value: 'write' },
+        ],
+      },
+      (out) => emitted.push(out),
+    );
+
+    expect(view.set).toHaveBeenCalledTimes(1);
+    expect(emitted).toEqual([
+      {
+        type: 'import-progress',
+        requestId: 'request-1',
+        target,
+        written: 1,
+        total: 1,
+      },
+      {
+        type: 'storage-invalidated',
+        target,
+        operation: 'import',
+        entryCount: 0,
+      },
+      {
+        type: 'import-result',
+        requestId: 'request-1',
+        target,
+        ok: true,
+        written: 1,
+        total: 1,
+      },
+    ]);
+  });
+
+  it('returns predictable errors for malformed and unknown preview targets', async () => {
+    const view = buildView();
+
+    await expect(handleImportPreviewRequest([view], {})).resolves.toMatchObject({
+      type: 'storage-request-error',
+      requestId: '',
+      code: 'INVALID_REQUEST',
+    });
+    await expect(
+      handleImportPreviewRequest([view], {
+        type: 'preview-import',
+        requestId: 'preview-1',
+        target: { adapterId: 'missing', storageId: 'missing' },
+        snapshot: {
+          version: 1,
+          plugin: '@rozenite/storage-plugin',
+          createdAt: '2026-01-01T00:00:00.000Z',
+          storage: {
+            adapterId: target.adapterId,
+            storageId: target.storageId,
+            adapterName: 'MMKV',
+            storageName: 'user',
+            capabilities: view.capabilities,
+          },
+          entries: [],
+        },
+      }),
+    ).resolves.toMatchObject({
+      type: 'storage-request-error',
+      requestId: 'preview-1',
+      code: 'TARGET_NOT_FOUND',
+    });
+  });
 });

package/src/react-native/__tests__/storage-discovery.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { StorageAdapter, StorageCapabilities, StorageTarget } from '../../shared/types';
+import { handleStorageDiscoveryRequest } from '../storage-discovery';
+import { createStorageViews, type StorageView } from '../storage-view';
+
+const capabilities: StorageCapabilities = {
+  supportedTypes: ['string', 'number', 'boolean', 'buffer'],
+};
+
+const createAdapter = (): StorageAdapter => {
+  const unexpectedRead = (method: string) =>
+    vi.fn(() => {
+      throw new Error(`Unexpected ${method} during discovery`);
+    });
+
+  return {
+    id: 'adapter',
+    name: 'Adapter',
+    storages: [
+      {
+        id: 'subscribed',
+        name: 'Subscribed storage',
+        capabilities,
+        storage: {
+          kind: 'sync',
+          getAllKeys: vi.fn(() => ['theme', 'token']),
+          get: unexpectedRead('get'),
+          set: vi.fn(),
+          delete: vi.fn(),
+          clear: vi.fn(),
+          subscribe: vi.fn(() => ({ remove: vi.fn() })),
+        },
+      },
+      {
+        id: 'manual',
+        name: 'Manual storage',
+        capabilities,
+        storage: {
+          kind: 'sync',
+          getAllKeys: vi.fn(() => ['session']),
+          get: unexpectedRead('get'),
+          set: vi.fn(),
+          delete: vi.fn(),
+          clear: vi.fn(),
+        },
+      },
+    ],
+  };
+};
+
+const request = { type: 'discover-storages', requestId: 'request-1' };
+
+describe('handleStorageDiscoveryRequest', () => {
+  it('returns ordered descriptors with key counts without reading values', async () => {
+    const adapter = createAdapter();
+    const views = createStorageViews([adapter]);
+
+    const result = await handleStorageDiscoveryRequest(views, request);
+
+    expect(result).toEqual({
+      type: 'storage-descriptors',
+      requestId: 'request-1',
+      storages: [
+        {
+          target: { adapterId: 'adapter', storageId: 'subscribed' },
+          adapterName: 'Adapter',
+          storageName: 'Subscribed storage',
+          entryCount: 2,
+          capabilities,
+          supportsSubscriptions: true,
+        },
+        {
+          target: { adapterId: 'adapter', storageId: 'manual' },
+          adapterName: 'Adapter',
+          storageName: 'Manual storage',
+          entryCount: 1,
+          capabilities,
+          supportsSubscriptions: false,
+        },
+      ],
+    });
+
+    for (const storage of adapter.storages) {
+      expect(storage.storage.getAllKeys).toHaveBeenCalledTimes(1);
+      expect(storage.storage.get).not.toHaveBeenCalled();
+    }
+  });
+
+  it('returns a correlated structured error for invalid requests', async () => {
+    expect(
+      await handleStorageDiscoveryRequest(createStorageViews([createAdapter()]), {
+        type: 'discover-storages',
+        requestId: ' ',
+      }),
+    ).toEqual({
+      type: 'storage-request-error',
+      requestId: ' ',
+      code: 'INVALID_REQUEST',
+      message: 'Storage discovery requires a non-empty request ID.',
+    });
+  });
+
+  it('rejects duplicate configured targets predictably', async () => {
+    const target: StorageTarget = { adapterId: 'adapter', storageId: 'shared' };
+    const view = (storageName: string): StorageView => ({
+      id: `adapter:${storageName}`,
+      target,
+      adapterName: 'Adapter',
+      storageName,
+      capabilities,
+      supportsSubscriptions: false,
+      get: vi.fn(),
+      set: vi.fn(),
+      delete: vi.fn(),
+      purge: vi.fn(),
+      getAllKeys: vi.fn(),
+      getAllEntries: vi.fn(),
+      watch: vi.fn(),
+    });
+
+    expect(await handleStorageDiscoveryRequest([view('One'), view('Two')], request)).toEqual({
+      type: 'storage-request-error',
+      requestId: 'request-1',
+      code: 'INVALID_REQUEST',
+      message: 'Configured storages must have unique targets.',
+    });
+  });
+
+  it('does not expose adapter exceptions over the bridge', async () => {
+    const view = {
+      target: { adapterId: 'adapter', storageId: 'broken' },
+      get adapterName() {
+        throw new Error('adapter internals');
+      },
+    } as unknown as StorageView;
+
+    await expect(handleStorageDiscoveryRequest([view], request)).resolves.toEqual({
+      type: 'storage-request-error',
+      requestId: 'request-1',
+      code: 'READ_FAILED',
+      message: 'Failed to discover configured storages.',
+    });
+  });
+});

package/src/react-native/__tests__/storage-view.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createMMKVStorageAdapter } from '../adapters/mmkv';
+import { createStorageViews } from '../storage-view';
+import type { StorageAdapter, StorageEntry } from '../../shared/types';
+
+describe('StorageView subscriptions', () => {
+  it('uses the storage clear operation when purging', async () => {
+    const clear = vi.fn();
+    const adapter: StorageAdapter = {
+      id: 'manual',
+      name: 'Manual',
+      storages: [
+        {
+          id: 'storage',
+          name: 'Storage',
+          capabilities: { supportedTypes: ['string'] },
+          storage: {
+            kind: 'sync',
+            getAllKeys: vi.fn(() => ['key']),
+            get: vi.fn(),
+            set: vi.fn(),
+            delete: vi.fn(),
+            clear,
+          },
+        },
+      ],
+    };
+
+    const [view] = createStorageViews([adapter]);
+    await view.purge();
+
+    expect(clear).toHaveBeenCalledOnce();
+  });
+
+  it('delegates purging to the storage implementation', async () => {
+    const clear = vi.fn();
+    const adapter: StorageAdapter = {
+      id: 'manual',
+      name: 'Manual',
+      storages: [
+        {
+          id: 'storage',
+          name: 'Storage',
+          capabilities: { supportedTypes: ['string'] },
+          storage: {
+            kind: 'sync',
+            getAllKeys: vi.fn(() => ['first', 'second']),
+            get: vi.fn(),
+            set: vi.fn(),
+            delete: vi.fn(),
+            clear,
+          },
+        },
+      ],
+    };
+
+    const [view] = createStorageViews([adapter]);
+    await view.purge();
+
+    expect(clear).toHaveBeenCalledOnce();
+  });
+
+  it('does not create a watcher or read unsupported storage while idle', async () => {
+    const getAllKeys = vi.fn(() => ['key']);
+    const get = vi.fn((): StorageEntry | undefined => ({
+      key: 'key',
+      type: 'string',
+      value: 'value',
+    }));
+    const adapter: StorageAdapter = {
+      id: 'manual',
+      name: 'Manual',
+      storages: [
+        {
+          id: 'storage',
+          name: 'Storage',
+          capabilities: { supportedTypes: ['string'] },
+          storage: {
+            kind: 'sync',
+            getAllKeys,
+            get,
+            set: vi.fn(),
+            delete: vi.fn(),
+            clear: vi.fn(),
+          },
+        },
+      ],
+    };
+
+    const [view] = createStorageViews([adapter]);
+
+    expect(view.supportsSubscriptions).toBe(false);
+    expect(view.watch).toBeUndefined();
+    expect(getAllKeys).not.toHaveBeenCalled();
+    expect(get).not.toHaveBeenCalled();
+  });
+
+  it('forwards native MMKV changes as key-only invalidations without reading values', async () => {
+    let onValueChanged: ((key: string) => void) | undefined;
+    const remove = vi.fn();
+    const storage = {
+      getBoolean: vi.fn(() => undefined),
+      getString: vi.fn((key: string) => (key === 'theme' ? 'dark' : undefined)),
+      getNumber: vi.fn(() => undefined),
+      getBuffer: vi.fn(() => undefined),
+      set: vi.fn(),
+      remove: vi.fn(),
+      getAllKeys: vi.fn(() => ['theme']),
+      addOnValueChangedListener: vi.fn((listener: (key: string) => void) => {
+        onValueChanged = listener;
+        return { remove };
+      }),
+    };
+    const [view] = createStorageViews([
+      createMMKVStorageAdapter({ storages: { settings: storage as never } }),
+    ]);
+    const onChange = vi.fn();
+
+    expect(view.supportsSubscriptions).toBe(true);
+    expect(view.watch).toBeDefined();
+    const subscription = await view.watch?.(onChange);
+    expect(storage.addOnValueChangedListener).toHaveBeenCalledTimes(1);
+
+    onValueChanged?.('theme');
+    expect(onChange).toHaveBeenCalledWith('theme');
+
+    onValueChanged?.('removed');
+    expect(onChange).toHaveBeenCalledWith('removed');
+    expect(storage.getString).not.toHaveBeenCalled();
+    expect(storage.getNumber).not.toHaveBeenCalled();
+    expect(storage.getBoolean).not.toHaveBeenCalled();
+    expect(storage.getBuffer).not.toHaveBeenCalled();
+    expect(storage.getAllKeys).not.toHaveBeenCalled();
+
+    subscription?.remove();
+    expect(remove).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not duplicate synchronous callbacks caused by plugin-originated writes', async () => {
+    let onValueChanged: ((key: string) => void) | undefined;
+    const adapter: StorageAdapter = {
+      id: 'subscribed',
+      name: 'Subscribed',
+      storages: [
+        {
+          id: 'storage',
+          name: 'Storage',
+          capabilities: { supportedTypes: ['string'] },
+          storage: {
+            kind: 'sync',
+            getAllKeys: vi.fn(() => []),
+            get: vi.fn(),
+            set: vi.fn((entry: StorageEntry) => onValueChanged?.(entry.key)),
+            delete: vi.fn(),
+            clear: vi.fn(),
+            subscribe: vi.fn((listener) => {
+              onValueChanged = listener;
+              return { remove: vi.fn() };
+            }),
+          },
+        },
+      ],
+    };
+    const [view] = createStorageViews([adapter]);
+    const onChange = vi.fn();
+    await view.watch?.(onChange);
+
+    await view.set({ key: 'written', type: 'string', value: 'value' });
+
+    expect(onChange).not.toHaveBeenCalled();
+  });
+});