@rozenite/storage-plugin 2.2.0 → 2.3.0

package/dist/react-native/src/react-native/import.d.ts

@@ -0,0 +1,7 @@
+import type { StorageImportPreviewResponseEvent, StorageImportProgressEvent, StorageImportResultEvent, StorageInvalidatedEvent, StorageRequestErrorEvent } from '../shared/messaging';
+import type { StorageView } from './storage-view';
+export type ImportEmittedEvent = StorageImportProgressEvent | StorageImportResultEvent | StorageInvalidatedEvent;
+type ImportPreviewResult = StorageImportPreviewResponseEvent | StorageRequestErrorEvent;
+export declare const handleImportPreviewRequest: (views: readonly StorageView[], payload: unknown) => Promise<ImportPreviewResult>;
+export declare const handleImportEntries: (views: StorageView[], payload: unknown, emit: (out: ImportEmittedEvent) => void) => Promise<void>;
+export {};

package/dist/react-native/src/react-native/import.js

@@ -0,0 +1,180 @@
+import { computePreview, parseSnapshot } from '../shared/snapshot';
+import { supportsType } from '../shared/types';
+const isSameTarget = (left, right) => left.adapterId === right.adapterId && left.storageId === right.storageId;
+const isTarget = (value) => typeof value === 'object' &&
+    value != null &&
+    !Array.isArray(value) &&
+    typeof value.adapterId === 'string' &&
+    value.adapterId.trim().length > 0 &&
+    typeof value.storageId === 'string' &&
+    value.storageId.trim().length > 0;
+const getRequestId = (payload) => typeof payload === 'object' &&
+    payload != null &&
+    !Array.isArray(payload) &&
+    typeof payload.requestId === 'string'
+    ? payload.requestId
+    : '';
+const isEntry = (value) => {
+    if (typeof value !== 'object' || value == null || Array.isArray(value)) {
+        return false;
+    }
+    const entry = value;
+    if (typeof entry.key !== 'string')
+        return false;
+    if (entry.type === 'string')
+        return typeof entry.value === 'string';
+    if (entry.type === 'number')
+        return typeof entry.value === 'number';
+    if (entry.type === 'boolean')
+        return typeof entry.value === 'boolean';
+    return (entry.type === 'buffer' &&
+        Array.isArray(entry.value) &&
+        entry.value.every((byte) => typeof byte === 'number' && Number.isInteger(byte) && byte >= 0 && byte <= 255));
+};
+const isBlacklisted = (view, key) => {
+    if (!view.blacklist)
+        return false;
+    view.blacklist.lastIndex = 0;
+    return view.blacklist.test(key);
+};
+const findView = (views, target) => views.find((candidate) => isSameTarget(candidate.target, target));
+export const handleImportPreviewRequest = async (views, payload) => {
+    const requestId = getRequestId(payload);
+    const request = payload;
+    const parsedSnapshot = parseSnapshot(request.snapshot);
+    if (typeof request !== 'object' ||
+        request == null ||
+        request.type !== 'preview-import' ||
+        typeof request.requestId !== 'string' ||
+        request.requestId.trim().length === 0 ||
+        !isTarget(request.target) ||
+        !parsedSnapshot.ok) {
+        return {
+            type: 'storage-request-error',
+            requestId,
+            code: 'INVALID_REQUEST',
+            message: 'Import preview requests require a valid target, request ID, and snapshot.',
+        };
+    }
+    const view = findView(views, request.target);
+    if (!view) {
+        return {
+            type: 'storage-request-error',
+            requestId,
+            code: 'TARGET_NOT_FOUND',
+            message: 'The requested storage target was not found.',
+        };
+    }
+    try {
+        const entryKeys = new Set(await view.getAllKeys());
+        return {
+            type: 'import-preview',
+            requestId,
+            target: view.target,
+            preview: computePreview(parsedSnapshot.snapshot, {
+                target: view.target,
+                capabilities: view.capabilities,
+                entryKeys,
+                isBlacklisted: (key) => isBlacklisted(view, key),
+            }),
+        };
+    }
+    catch {
+        return {
+            type: 'storage-request-error',
+            requestId,
+            code: 'READ_FAILED',
+            message: 'Failed to inspect the requested storage for import.',
+        };
+    }
+};
+export const handleImportEntries = async (views, payload, emit) => {
+    const requestId = getRequestId(payload);
+    const event = payload;
+    if (typeof event !== 'object' ||
+        event == null ||
+        event.type !== 'import-entries' ||
+        typeof event.requestId !== 'string' ||
+        event.requestId.trim().length === 0 ||
+        !isTarget(event.target) ||
+        !Array.isArray(event.entries) ||
+        !event.entries.every(isEntry)) {
+        emit({
+            type: 'import-result',
+            requestId,
+            target: isTarget(event.target) ? event.target : { adapterId: '', storageId: '' },
+            ok: false,
+            written: 0,
+            total: 0,
+            error: 'Import requests require a valid target, request ID, and entries.',
+        });
+        return;
+    }
+    const view = findView(views, event.target);
+    if (!view) {
+        emit({
+            type: 'import-result',
+            requestId: event.requestId,
+            target: event.target,
+            ok: false,
+            written: 0,
+            total: event.entries.length,
+            error: 'Target storage not found',
+        });
+        return;
+    }
+    // Recheck policy at apply time so a preview cannot bypass a changed target.
+    const entries = event.entries.filter((entry) => supportsType(view.capabilities, entry.type) && !isBlacklisted(view, entry.key));
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i];
+        try {
+            await view.set(entry);
+        }
+        catch (error) {
+            if (i > 0) {
+                const entryCount = (await view.getAllKeys()).length;
+                emit({
+                    type: 'storage-invalidated',
+                    target: event.target,
+                    operation: 'import',
+                    entryCount,
+                });
+            }
+            emit({
+                type: 'import-result',
+                requestId: event.requestId,
+                target: event.target,
+                ok: false,
+                written: i,
+                total: entries.length,
+                failedKey: entry.key,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return;
+        }
+        emit({
+            type: 'import-progress',
+            requestId: event.requestId,
+            target: event.target,
+            written: i + 1,
+            total: entries.length,
+        });
+    }
+    if (entries.length > 0) {
+        const entryCount = (await view.getAllKeys()).length;
+        emit({
+            type: 'storage-invalidated',
+            target: event.target,
+            operation: 'import',
+            entryCount,
+        });
+    }
+    emit({
+        type: 'import-result',
+        requestId: event.requestId,
+        target: event.target,
+        ok: true,
+        written: entries.length,
+        total: entries.length,
+    });
+};

package/dist/react-native/src/react-native/storage-discovery.d.ts

@@ -0,0 +1,5 @@
+import type { StorageDiscoverStoragesResponseEvent, StorageRequestErrorEvent } from '../shared/messaging';
+import type { StorageView } from './storage-view';
+type DiscoveryResult = StorageDiscoverStoragesResponseEvent | StorageRequestErrorEvent;
+export declare const handleStorageDiscoveryRequest: (views: readonly StorageView[], payload: unknown) => Promise<DiscoveryResult>;
+export {};

package/dist/react-native/src/react-native/storage-discovery.js

@@ -0,0 +1,65 @@
+const getRequestId = (payload) => {
+    if (typeof payload === 'object' &&
+        payload != null &&
+        !Array.isArray(payload) &&
+        typeof payload.requestId === 'string') {
+        return payload.requestId;
+    }
+    return '';
+};
+const validateRequest = (payload) => typeof payload === 'object' &&
+    payload != null &&
+    !Array.isArray(payload) &&
+    payload.type === 'discover-storages' &&
+    typeof payload.requestId === 'string' &&
+    payload.requestId.trim().length > 0;
+const toDescriptor = async (view) => ({
+    target: view.target,
+    adapterName: view.adapterName,
+    storageName: view.storageName,
+    entryCount: (await view.getAllKeys()).length,
+    capabilities: view.capabilities,
+    supportsSubscriptions: view.supportsSubscriptions,
+});
+const hasDuplicateTargets = (views) => {
+    const targets = new Set();
+    return views.some(({ target }) => {
+        const id = `${target.adapterId}:${target.storageId}`;
+        if (targets.has(id)) {
+            return true;
+        }
+        targets.add(id);
+        return false;
+    });
+};
+export const handleStorageDiscoveryRequest = async (views, payload) => {
+    const requestId = getRequestId(payload);
+    if (!validateRequest(payload)) {
+        return {
+            type: 'storage-request-error',
+            requestId,
+            code: 'INVALID_REQUEST',
+            message: 'Storage discovery requires a non-empty request ID.',
+        };
+    }
+    try {
+        if (hasDuplicateTargets(views)) {
+            return {
+                type: 'storage-request-error',
+                requestId,
+                code: 'INVALID_REQUEST',
+                message: 'Configured storages must have unique targets.',
+            };
+        }
+        const storages = await Promise.all(views.map(toDescriptor));
+        return { type: 'storage-descriptors', requestId, storages };
+    }
+    catch {
+        return {
+            type: 'storage-request-error',
+            requestId,
+            code: 'READ_FAILED',
+            message: 'Failed to discover configured storages.',
+        };
+    }
+};

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

@@ -0,0 +1,19 @@
+import { type StorageAdapter, type StorageCapabilities, type StorageEntry, type StorageNode, type StorageSubscription, type StorageTarget } from '../shared/types';
+export type StorageView = {
+    id: string;
+    target: StorageTarget;
+    adapterName: string;
+    storageName: string;
+    capabilities: StorageCapabilities;
+    supportsSubscriptions: boolean;
+    blacklist?: RegExp;
+    get: (key: string) => Promise<StorageEntry | undefined>;
+    set: (entry: StorageEntry) => Promise<void>;
+    delete: (key: string) => Promise<void>;
+    purge: () => Promise<void>;
+    getAllKeys: () => Promise<readonly string[]>;
+    getAllEntries: () => Promise<StorageEntry[]>;
+    watch?: (onChange: (key: string) => void) => Promise<StorageSubscription>;
+};
+export declare const createStorageView: (adapter: StorageAdapter, storageNode: StorageNode) => StorageView;
+export declare const createStorageViews: (storages: StorageAdapter[]) => StorageView[];

package/dist/react-native/src/react-native/storage-view.js

@@ -0,0 +1,123 @@
+import { getStorageViewId, supportsType, } from '../shared/types';
+const isAsyncStorage = (storage) => storage.kind === 'async';
+const shouldFilterKey = (storage, key) => {
+    if (storage.shouldFilterKey?.(key)) {
+        return true;
+    }
+    if (!storage.blacklist) {
+        return false;
+    }
+    storage.blacklist.lastIndex = 0;
+    return storage.blacklist.test(key);
+};
+const checkTypeSupport = (capabilities, type, target) => {
+    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) => {
+    if (isAsyncStorage(storage)) {
+        return storage.getAllKeys();
+    }
+    return storage.getAllKeys();
+};
+const getEntry = async (storage, key) => {
+    if (isAsyncStorage(storage)) {
+        return storage.get(key);
+    }
+    return storage.get(key);
+};
+const setEntry = async (storage, entry) => {
+    if (isAsyncStorage(storage)) {
+        await storage.set(entry);
+        return;
+    }
+    storage.set(entry);
+};
+const deleteEntry = async (storage, key) => {
+    if (isAsyncStorage(storage)) {
+        await storage.delete(key);
+        return;
+    }
+    storage.delete(key);
+};
+const clearStorage = async (storage) => {
+    await storage.clear();
+};
+export const createStorageView = (adapter, storageNode) => {
+    const storage = storageNode.storage;
+    const subscribe = storage.subscribe;
+    const locallyMutatingKeys = new Set();
+    let isLocallyPurging = false;
+    const target = {
+        adapterId: adapter.id,
+        storageId: storageNode.id,
+    };
+    const get = async (key) => {
+        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);
+    };
+    return {
+        id: getStorageViewId(target),
+        target,
+        adapterName: adapter.name,
+        storageName: storageNode.name,
+        capabilities: storageNode.capabilities,
+        supportsSubscriptions: subscribe != null,
+        blacklist: storageNode.blacklist,
+        get,
+        set: async (entry) => {
+            checkTypeSupport(storageNode.capabilities, entry.type, target);
+            locallyMutatingKeys.add(entry.key);
+            try {
+                await setEntry(storage, entry);
+            }
+            finally {
+                locallyMutatingKeys.delete(entry.key);
+            }
+        },
+        delete: async (key) => {
+            locallyMutatingKeys.add(key);
+            try {
+                await deleteEntry(storage, key);
+            }
+            finally {
+                locallyMutatingKeys.delete(key);
+            }
+        },
+        purge: async () => {
+            isLocallyPurging = true;
+            try {
+                await clearStorage(storage);
+            }
+            finally {
+                isLocallyPurging = false;
+            }
+        },
+        getAllKeys: async () => {
+            const keys = await getAllKeys(storage);
+            return keys.filter((key) => !shouldFilterKey(storageNode, key));
+        },
+        getAllEntries,
+        ...(subscribe
+            ? {
+                watch: async (onChange) => subscribe((key) => {
+                    if (!isLocallyPurging &&
+                        !locallyMutatingKeys.has(key) &&
+                        !shouldFilterKey(storageNode, key)) {
+                        onChange(key);
+                    }
+                }),
+            }
+            : {}),
+    };
+};
+export const createStorageViews = (storages) => storages.flatMap((adapter) => adapter.storages.map((storageNode) => createStorageView(adapter, storageNode)));

package/dist/react-native/src/react-native/useRozeniteStoragePlugin.d.ts

@@ -0,0 +1,6 @@
+import type { StorageEventMap } from '../shared/messaging';
+import type { StorageAdapter } from '../shared/types';
+export type RozeniteStoragePluginOptions = {
+    storages: StorageAdapter[];
+};
+export declare const useRozeniteStoragePlugin: ({ storages }: RozeniteStoragePluginOptions) => import("@rozenite/plugin-bridge").RozeniteDevToolsRequestClient<StorageEventMap> | null;

package/dist/react-native/src/react-native/useRozeniteStoragePlugin.js

@@ -0,0 +1,141 @@
+import { useRozeniteDevToolsClient } from '@rozenite/plugin-bridge';
+import { useEffect, useMemo } from 'react';
+import { handleImportEntries, handleImportPreviewRequest } from './import';
+import { handleStorageDiscoveryRequest } from './storage-discovery';
+import { handleListEntryPreviewsRequest } from './entry-preview-pagination';
+import { handleFullEntryRequest } from './full-entry-request';
+import { handleExportSnapshotRequest } from './export-snapshot';
+import { createStorageViews } from './storage-view';
+import { useStorageAgentTools } from './useStorageAgentTools';
+export const useRozeniteStoragePlugin = ({ storages }) => {
+    const views = useMemo(() => createStorageViews(storages), [storages]);
+    useStorageAgentTools(views);
+    const client = useRozeniteDevToolsClient({
+        pluginId: '@rozenite/storage-plugin',
+    });
+    useEffect(() => {
+        if (!client) {
+            return;
+        }
+        const viewSubscriptions = [];
+        let disposed = false;
+        const sendInvalidation = async (target, key, operation) => {
+            const view = views.find((candidate) => candidate.target.adapterId === target.adapterId &&
+                candidate.target.storageId === target.storageId);
+            const entryCount = view ? (await view.getAllKeys()).length : 0;
+            client.send('storage-invalidated', {
+                type: 'storage-invalidated',
+                target,
+                key,
+                operation,
+                entryCount,
+            });
+        };
+        // Prevent one storage watcher failure from breaking the whole plugin.
+        void Promise.all(views
+            .filter((view) => view.supportsSubscriptions && view.watch)
+            .map(async (view) => {
+            try {
+                const watch = view.watch;
+                if (!watch) {
+                    return;
+                }
+                const subscription = await watch((key) => {
+                    void sendInvalidation(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 }) => {
+                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);
+                    await sendInvalidation(view.target, entry.key, 'set');
+                }
+                catch (error) {
+                    console.warn(`[Rozenite] Storage Plugin: Failed to set entry in ${target.adapterId}/${target.storageId}.`, error);
+                }
+            }),
+            client.onMessage('delete-entry', async ({ target, key }) => {
+                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);
+                    await sendInvalidation(view.target, key, 'delete');
+                }
+                catch (error) {
+                    console.warn(`[Rozenite] Storage Plugin: Failed to delete entry in ${target.adapterId}/${target.storageId}.`, error);
+                }
+            }),
+            client.onMessage('purge-storage', async ({ target }) => {
+                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.purge();
+                    await sendInvalidation(view.target, undefined, 'purge');
+                }
+                catch (error) {
+                    console.warn(`[Rozenite] Storage Plugin: Failed to purge storage in ${target.adapterId}/${target.storageId}.`, error);
+                }
+            }),
+            client.onMessage('discover-storages', async (event) => {
+                const response = await handleStorageDiscoveryRequest(views, event);
+                client.send(response.type, response);
+            }),
+            client.onMessage('list-entry-previews', async (event) => {
+                const response = await handleListEntryPreviewsRequest(views, event);
+                client.send(response.type, response);
+            }),
+            client.onMessage('get-entry', async (event) => {
+                const response = await handleFullEntryRequest(views, event);
+                client.send(response.type, response);
+            }),
+            client.onMessage('export-snapshot', async (event) => {
+                const response = await handleExportSnapshotRequest(views, event);
+                client.send(response.type, response);
+            }),
+            client.onMessage('preview-import', async (event) => {
+                const response = await handleImportPreviewRequest(views, event);
+                client.send(response.type, response);
+            }),
+            client.onMessage('import-entries', async (event) => {
+                await handleImportEntries(views, event, (out) => {
+                    client.send(out.type, out);
+                });
+            }),
+        ];
+        // Sent last, so a panel that reacts to it is guaranteed to find the
+        // handlers above already listening. The panel is recreated on every app
+        // reload and asks for storages as soon as it boots, which usually beats the
+        // app's React tree to the punch; without this the panel's only request is
+        // dropped and it waits for storages forever.
+        client.send('device-ready', { type: 'device-ready' });
+        return () => {
+            disposed = true;
+            viewSubscriptions.forEach((subscription) => subscription.remove());
+            messageSubscriptions.forEach((subscription) => subscription.remove());
+        };
+    }, [client, views]);
+    return client;
+};

package/dist/react-native/src/react-native/useStorageAgentTools.d.ts

@@ -0,0 +1,37 @@
+import { type StorageListEntriesArgs } from '../shared/agent-tools';
+import type { StorageEntry } from '../shared/types';
+import type { StorageView } from './storage-view';
+export declare const createStorageAgentHandlers: (views: readonly StorageView[]) => {
+    listStorages: () => Promise<{
+        storages: {
+            adapterId: string;
+            storageId: string;
+            adapterName: string;
+            storageName: string;
+            supportedTypes: ("string" | "number" | "boolean" | "buffer")[];
+        }[];
+    }>;
+    listEntries: (input: StorageListEntriesArgs) => Promise<{
+        adapterId: string;
+        storageId: string;
+        total: number;
+        items: {
+            key: string;
+        }[];
+        page: {
+            nextCursor?: string | undefined;
+            limit: number;
+            hasMore: boolean;
+        };
+    }>;
+    readEntry: ({ adapterId, storageId, key, }: {
+        adapterId?: string;
+        storageId?: string;
+        key: string;
+    }) => Promise<{
+        adapterId: string;
+        storageId: string;
+        entry: StorageEntry;
+    }>;
+};
+export declare const useStorageAgentTools: (views: StorageView[]) => void;