@rozenite/storage-plugin 1.4.0

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

@@ -0,0 +1,76 @@
+import type { StorageAdapter, StorageNode } from '../../shared/types';
+
+export type SecureStorageLike = {
+  getItemAsync: (key: string) => Promise<string | null>;
+  setItemAsync: (key: string, value: string) => Promise<void>;
+  deleteItemAsync: (key: string) => Promise<void>;
+};
+
+type KeySource = string[] | (() => Promise<string[]>);
+
+export type CreateExpoSecureStorageAdapterOptions = {
+  storage: SecureStorageLike;
+  keys: KeySource;
+  adapterId?: string;
+  adapterName?: string;
+  storageId?: string;
+  storageName?: string;
+  blacklist?: RegExp;
+};
+
+const resolveKeys = async (source: KeySource) => {
+  if (Array.isArray(source)) {
+    return source;
+  }
+
+  return source();
+};
+
+export const createExpoSecureStorageAdapter = ({
+  storage,
+  keys,
+  adapterId = 'expo-secure-store',
+  adapterName = 'Expo SecureStore',
+  storageId = 'default',
+  storageName = 'Default Secure Storage',
+  blacklist,
+}: CreateExpoSecureStorageAdapterOptions): StorageAdapter => {
+  const storageNode: StorageNode = {
+    id: storageId,
+    name: storageName,
+    blacklist,
+    capabilities: {
+      supportedTypes: ['string'],
+    },
+    storage: {
+      kind: 'async',
+      getAllKeys: () => resolveKeys(keys),
+      get: async (key) => {
+        const value = await storage.getItemAsync(key);
+        if (value === null) {
+          return undefined;
+        }
+
+        return {
+          key,
+          type: 'string',
+          value,
+        };
+      },
+      set: async (entry) => {
+        if (entry.type !== 'string') {
+          throw new Error('Expo SecureStore adapter supports only string values.');
+        }
+
+        await storage.setItemAsync(entry.key, entry.value);
+      },
+      delete: (key) => storage.deleteItemAsync(key),
+    },
+  };
+
+  return {
+    id: adapterId,
+    name: adapterName,
+    storages: [storageNode],
+  };
+};

package/src/react-native/is-garbled.ts

@@ -0,0 +1,17 @@
+// This is a heuristic to determine if a string is garbled.
+export const looksLikeGarbled = (str: string): boolean => {
+  // 1. Check for replacement character (�)
+  if (str.includes('\uFFFD')) return true;
+
+  // 2. Check for unusual control characters
+  // eslint-disable-next-line no-control-regex
+  const controlChars = /[\u0000-\u001F\u007F-\u009F]/;
+  if (controlChars.test(str)) return true;
+
+  // 3. Optionally, check if most chars are non-printable
+  const printableRatio =
+    [...str].filter((c) => c >= ' ' && c <= '~').length / str.length;
+  if (printableRatio < 0.7) return true; // mostly non-printable → probably binary
+
+  return false; // seems like valid string
+};

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

@@ -0,0 +1,245 @@
+import {
+  getStorageViewId,
+  supportsType,
+  type AsyncStorage,
+  type StorageAdapter,
+  type StorageCapabilities,
+  type StorageEntry,
+  type StorageEntryType,
+  type StorageNode,
+  type StorageSubscription,
+  type StorageTarget,
+  type SyncStorage,
+} from '../shared/types';
+
+const POLLING_INTERVAL_MS = 1500;
+
+type StorageSnapshotMap = Map<string, StorageEntry>;
+
+type AsyncStorageLike = SyncStorage | AsyncStorage;
+
+const isAsyncStorage = (storage: AsyncStorageLike): storage is AsyncStorage =>
+  storage.kind === 'async';
+
+const fingerprintEntry = (entry: StorageEntry) => {
+  if (entry.type === 'buffer') {
+    return `${entry.type}:${entry.value.join(',')}`;
+  }
+
+  return `${entry.type}:${String(entry.value)}`;
+};
+
+const toSnapshotMap = (entries: StorageEntry[]) => {
+  return new Map(entries.map((entry) => [entry.key, entry]));
+};
+
+const shouldFilterKey = (storage: StorageNode, key: string) => {
+  if (!storage.blacklist) {
+    return false;
+  }
+
+  storage.blacklist.lastIndex = 0;
+  return storage.blacklist.test(key);
+};
+
+const checkTypeSupport = (
+  capabilities: StorageCapabilities,
+  type: StorageEntryType,
+  target: StorageTarget
+) => {
+  if (supportsType(capabilities, type)) {
+    return;
+  }
+
+  throw new Error(
+    `Type "${type}" is not supported by storage "${target.storageId}" in adapter "${target.adapterId}".`
+  );
+};
+
+const getAllKeys = async (storage: AsyncStorageLike) => {
+  if (isAsyncStorage(storage)) {
+    return storage.getAllKeys();
+  }
+
+  return storage.getAllKeys();
+};
+
+const getEntry = async (storage: AsyncStorageLike, key: string) => {
+  if (isAsyncStorage(storage)) {
+    return storage.get(key);
+  }
+
+  return storage.get(key);
+};
+
+const setEntry = async (storage: AsyncStorageLike, entry: StorageEntry) => {
+  if (isAsyncStorage(storage)) {
+    await storage.set(entry);
+    return;
+  }
+
+  storage.set(entry);
+};
+
+const deleteEntry = async (storage: AsyncStorageLike, key: string) => {
+  if (isAsyncStorage(storage)) {
+    await storage.delete(key);
+    return;
+  }
+
+  storage.delete(key);
+};
+
+export type StorageView = {
+  id: string;
+  target: StorageTarget;
+  adapterName: string;
+  storageName: string;
+  capabilities: StorageCapabilities;
+  get: (key: string) => Promise<StorageEntry | undefined>;
+  set: (entry: StorageEntry) => Promise<void>;
+  delete: (key: string) => Promise<void>;
+  getAllKeys: () => Promise<string[]>;
+  getAllEntries: () => Promise<StorageEntry[]>;
+  watch: (callbacks: {
+    onSet: (entry: StorageEntry) => void;
+    onDelete: (key: string) => void;
+  }) => Promise<StorageSubscription>;
+};
+
+const buildSnapshotMap = async (
+  getAllEntries: () => Promise<StorageEntry[]>
+): Promise<StorageSnapshotMap> => {
+  const entries = await getAllEntries();
+  return toSnapshotMap(entries);
+};
+
+const diffSnapshots = (
+  previous: StorageSnapshotMap,
+  next: StorageSnapshotMap,
+  handlers: {
+    onSet: (entry: StorageEntry) => void;
+    onDelete: (key: string) => void;
+  }
+) => {
+  next.forEach((nextEntry, key) => {
+    const previousEntry = previous.get(key);
+
+    if (!previousEntry) {
+      handlers.onSet(nextEntry);
+      return;
+    }
+
+    if (fingerprintEntry(previousEntry) !== fingerprintEntry(nextEntry)) {
+      handlers.onSet(nextEntry);
+    }
+  });
+
+  previous.forEach((_value, key) => {
+    if (!next.has(key)) {
+      handlers.onDelete(key);
+    }
+  });
+};
+
+const createPollingSubscription = async (
+  getAllEntries: () => Promise<StorageEntry[]>,
+  handlers: {
+    onSet: (entry: StorageEntry) => void;
+    onDelete: (key: string) => void;
+  }
+): Promise<StorageSubscription> => {
+  let previousSnapshot = await buildSnapshotMap(getAllEntries);
+
+  const interval = setInterval(async () => {
+    try {
+      const nextSnapshot = await buildSnapshotMap(getAllEntries);
+      diffSnapshots(previousSnapshot, nextSnapshot, handlers);
+      previousSnapshot = nextSnapshot;
+    } catch {
+      // Silently ignore polling errors and try again on next tick.
+    }
+  }, POLLING_INTERVAL_MS);
+
+  return {
+    remove: () => {
+      clearInterval(interval);
+    },
+  };
+};
+
+export const createStorageView = (
+  adapter: StorageAdapter,
+  storageNode: StorageNode
+): StorageView => {
+  const storage = storageNode.storage;
+  const target: StorageTarget = {
+    adapterId: adapter.id,
+    storageId: storageNode.id,
+  };
+
+  const get = async (key: string) => {
+    if (shouldFilterKey(storageNode, key)) {
+      return undefined;
+    }
+
+    return getEntry(storage, key);
+  };
+
+  const getAllEntries = async () => {
+    const keys = await getAllKeys(storage);
+    const visibleEntries = await Promise.all(
+      keys
+        .filter((key) => !shouldFilterKey(storageNode, key))
+        .map((key) => getEntry(storage, key))
+    );
+
+    return visibleEntries.filter((entry): entry is StorageEntry => !!entry);
+  };
+
+  return {
+    id: getStorageViewId(target),
+    target,
+    adapterName: adapter.name,
+    storageName: storageNode.name,
+    capabilities: storageNode.capabilities,
+    get,
+    set: async (entry) => {
+      checkTypeSupport(storageNode.capabilities, entry.type, target);
+      await setEntry(storage, entry);
+    },
+    delete: async (key) => {
+      await deleteEntry(storage, key);
+    },
+    getAllKeys: async () => {
+      const keys = await getAllKeys(storage);
+      return keys.filter((key) => !shouldFilterKey(storageNode, key));
+    },
+    getAllEntries,
+    watch: async ({ onSet, onDelete }) => {
+      if (storage.subscribe) {
+        return storage.subscribe(async (key) => {
+          try {
+            const entry = await get(key);
+
+            if (!entry) {
+              onDelete(key);
+              return;
+            }
+
+            onSet(entry);
+          } catch {
+            // Ignore runtime callback errors; polling fallback is not needed when subscribe exists.
+          }
+        });
+      }
+
+      return createPollingSubscription(getAllEntries, { onSet, onDelete });
+    },
+  };
+};
+
+export const createStorageViews = (storages: StorageAdapter[]) =>
+  storages.flatMap((adapter) =>
+    adapter.storages.map((storageNode) => createStorageView(adapter, storageNode))
+  );

package/src/react-native/useRozeniteStoragePlugin.ts

@@ -0,0 +1,162 @@
+import { useRozeniteDevToolsClient } from '@rozenite/plugin-bridge';
+import { useEffect, useMemo } from 'react';
+import type {
+  StorageDeleteEntryEvent,
+  StorageEventMap,
+  StorageGetSnapshotEvent,
+  StorageSetEntryEvent,
+} from '../shared/messaging';
+import type { StorageAdapter } from '../shared/types';
+import { createStorageViews } from './storage-view';
+
+export type RozeniteStoragePluginOptions = {
+  storages: StorageAdapter[];
+};
+
+export const useRozeniteStoragePlugin = ({
+  storages,
+}: RozeniteStoragePluginOptions) => {
+  const views = useMemo(() => createStorageViews(storages), [storages]);
+
+  const client = useRozeniteDevToolsClient<StorageEventMap>({
+    pluginId: '@rozenite/storage-plugin',
+  });
+
+  useEffect(() => {
+    if (!client) {
+      return;
+    }
+
+    const pushSnapshot = async (viewId?: string) => {
+      const selectedViews = viewId ? views.filter((view) => view.id === viewId) : views;
+
+      for (const view of selectedViews) {
+        try {
+          const entries = await view.getAllEntries();
+          client.send('snapshot', {
+            type: 'snapshot',
+            target: view.target,
+            adapterName: view.adapterName,
+            storageName: view.storageName,
+            capabilities: view.capabilities,
+            entries,
+          });
+        } catch (error) {
+          console.warn(
+            `[Rozenite] Storage Plugin: Failed to snapshot ${view.target.adapterId}/${view.target.storageId}.`,
+            error
+          );
+        }
+      }
+    };
+
+    void pushSnapshot();
+
+    const viewSubscriptions: { remove: () => void }[] = [];
+    let disposed = false;
+
+    // Prevent one storage watcher failure from breaking the whole plugin.
+    void Promise.all(
+      views.map(async (view) => {
+        try {
+          const subscription = await view.watch({
+            onSet: (entry) => {
+              client.send('set-entry', {
+                type: 'set-entry',
+                target: view.target,
+                entry,
+              });
+            },
+            onDelete: (key) => {
+              client.send('delete-entry', {
+                type: 'delete-entry',
+                target: view.target,
+                key,
+              });
+            },
+          });
+
+          if (disposed) {
+            subscription.remove();
+            return;
+          }
+
+          viewSubscriptions.push(subscription);
+        } catch (error) {
+          console.warn(
+            `[Rozenite] Storage Plugin: Failed to attach watcher for ${view.target.adapterId}/${view.target.storageId}.`,
+            error
+          );
+        }
+      })
+    );
+
+    const messageSubscriptions = [
+      client.onMessage('set-entry', async ({ target, entry }: StorageSetEntryEvent) => {
+        const view = views.find(
+          (candidate) =>
+            candidate.target.adapterId === target.adapterId &&
+            candidate.target.storageId === target.storageId
+        );
+
+        if (!view) {
+          console.warn(
+            `[Rozenite] Storage Plugin: Storage target not found for ${target.adapterId}/${target.storageId}`
+          );
+          return;
+        }
+
+        try {
+          await view.set(entry);
+        } catch (error) {
+          console.warn(
+            `[Rozenite] Storage Plugin: Failed to set entry in ${target.adapterId}/${target.storageId}.`,
+            error
+          );
+        }
+      }),
+      client.onMessage(
+        'delete-entry',
+        async ({ target, key }: StorageDeleteEntryEvent) => {
+          const view = views.find(
+            (candidate) =>
+              candidate.target.adapterId === target.adapterId &&
+              candidate.target.storageId === target.storageId
+          );
+
+          if (!view) {
+            console.warn(
+              `[Rozenite] Storage Plugin: Storage target not found for ${target.adapterId}/${target.storageId}`
+            );
+            return;
+          }
+
+          try {
+            await view.delete(key);
+          } catch (error) {
+            console.warn(
+              `[Rozenite] Storage Plugin: Failed to delete entry in ${target.adapterId}/${target.storageId}.`,
+              error
+            );
+          }
+        }
+      ),
+      client.onMessage('get-snapshot', async ({ target }: StorageGetSnapshotEvent) => {
+        if (target === 'all') {
+          await pushSnapshot();
+          return;
+        }
+
+        await pushSnapshot(`${target.adapterId}:${target.storageId}`);
+      }),
+    ];
+
+    return () => {
+      disposed = true;
+      viewSubscriptions.forEach((subscription) => subscription.remove());
+      messageSubscriptions.forEach((subscription) => subscription.remove());
+    };
+  }, [client, views]);
+
+  return client;
+};

package/src/shared/messaging.ts

@@ -0,0 +1,37 @@
+import type { StorageCapabilities, StorageEntry, StorageTarget } from './types';
+
+export type StorageSnapshotEvent = {
+  type: 'snapshot';
+  target: StorageTarget;
+  adapterName: string;
+  storageName: string;
+  capabilities: StorageCapabilities;
+  entries: StorageEntry[];
+};
+
+export type StorageSetEntryEvent = {
+  type: 'set-entry';
+  target: StorageTarget;
+  entry: StorageEntry;
+};
+
+export type StorageDeleteEntryEvent = {
+  type: 'delete-entry';
+  target: StorageTarget;
+  key: string;
+};
+
+export type StorageGetSnapshotEvent = {
+  type: 'get-snapshot';
+  target: StorageTarget | 'all';
+};
+
+export type StorageEvent =
+  | StorageSnapshotEvent
+  | StorageSetEntryEvent
+  | StorageDeleteEntryEvent
+  | StorageGetSnapshotEvent;
+
+export type StorageEventMap = {
+  [K in StorageEvent['type']]: Extract<StorageEvent, { type: K }>;
+};

package/src/shared/types.ts

@@ -0,0 +1,66 @@
+export type StorageEntry =
+  | { key: string; type: 'string'; value: string }
+  | { key: string; type: 'number'; value: number }
+  | { key: string; type: 'boolean'; value: boolean }
+  | { key: string; type: 'buffer'; value: number[] };
+
+export type StorageEntryType = StorageEntry['type'];
+export type StorageEntryValue = StorageEntry['value'];
+
+export type StorageCapabilities = {
+  supportedTypes: StorageEntryType[];
+};
+
+export type StorageSubscription = { remove: () => void };
+
+export type SyncStorage = {
+  kind: 'sync';
+  getAllKeys: () => string[];
+  get: (key: string) => StorageEntry | undefined;
+  set: (entry: StorageEntry) => void;
+  delete: (key: string) => void;
+  subscribe?: (callback: (key: string) => void) => StorageSubscription;
+};
+
+export type AsyncStorage = {
+  kind: 'async';
+  getAllKeys: () => Promise<string[]>;
+  get: (key: string) => Promise<StorageEntry | undefined>;
+  set: (entry: StorageEntry) => Promise<void>;
+  delete: (key: string) => Promise<void>;
+  subscribe?: (callback: (key: string) => void) => StorageSubscription;
+};
+
+export type StorageNode = {
+  id: string;
+  name: string;
+  storage: SyncStorage | AsyncStorage;
+  capabilities: StorageCapabilities;
+  blacklist?: RegExp;
+};
+
+export type StorageAdapter = {
+  id: string;
+  name: string;
+  storages: StorageNode[];
+};
+
+export type StorageTarget = {
+  adapterId: string;
+  storageId: string;
+};
+
+export const DEFAULT_SUPPORTED_TYPES: StorageEntryType[] = [
+  'string',
+  'number',
+  'boolean',
+  'buffer',
+];
+
+export const getStorageViewId = ({ adapterId, storageId }: StorageTarget) =>
+  `${adapterId}:${storageId}`;
+
+export const supportsType = (
+  capabilities: StorageCapabilities,
+  type: StorageEntryType
+) => capabilities.supportedTypes.includes(type);