@rozenite/storage-plugin 1.8.1 → 1.10.0

package/src/shared/snapshot.ts

@@ -0,0 +1,276 @@
+import {
+  DEFAULT_SUPPORTED_TYPES,
+  supportsType,
+  type StorageCapabilities,
+  type StorageEntry,
+  type StorageEntryType,
+  type StorageTarget,
+} from './types';
+
+const PLUGIN_ID = '@rozenite/storage-plugin';
+const SUPPORTED_VERSION = 1;
+
+export type StorageSnapshotV1 = {
+  version: 1;
+  plugin: string;
+  createdAt: string;
+  storage: {
+    adapterId: string;
+    storageId: string;
+    adapterName: string;
+    storageName: string;
+    capabilities: StorageCapabilities;
+  };
+  entries: StorageEntry[];
+};
+
+export type ParseError = { path: string; message: string };
+
+export type ParseResult =
+  | { ok: true; snapshot: StorageSnapshotV1 }
+  | { ok: false; error: ParseError };
+
+class ParseException extends Error {
+  constructor(
+    public path: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+const describe = (value: unknown): string => {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  return typeof value;
+};
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const expectObject = (
+  value: unknown,
+  path: string,
+): Record<string, unknown> => {
+  if (!isPlainObject(value)) {
+    throw new ParseException(path, `Expected object, got ${describe(value)}`);
+  }
+  return value;
+};
+
+const expectString = (value: unknown, path: string): string => {
+  if (typeof value !== 'string') {
+    throw new ParseException(path, `Expected string, got ${describe(value)}`);
+  }
+  return value;
+};
+
+const expectArray = (value: unknown, path: string): unknown[] => {
+  if (!Array.isArray(value)) {
+    throw new ParseException(path, `Expected array, got ${describe(value)}`);
+  }
+  return value;
+};
+
+const expectEntryType = (value: unknown, path: string): StorageEntryType => {
+  if (
+    typeof value !== 'string' ||
+    !DEFAULT_SUPPORTED_TYPES.includes(value as StorageEntryType)
+  ) {
+    throw new ParseException(
+      path,
+      `Expected one of ${DEFAULT_SUPPORTED_TYPES.join(', ')}, got ${describe(value)}`,
+    );
+  }
+  return value as StorageEntryType;
+};
+
+const parseCapabilities = (raw: unknown, path: string): StorageCapabilities => {
+  const obj = expectObject(raw, path);
+  const supported = expectArray(obj.supportedTypes, `${path}.supportedTypes`);
+  const supportedTypes = supported.map((type, index) =>
+    expectEntryType(type, `${path}.supportedTypes[${index}]`),
+  );
+  return { supportedTypes };
+};
+
+const parseStorageMeta = (raw: unknown): StorageSnapshotV1['storage'] => {
+  const obj = expectObject(raw, 'storage');
+  return {
+    adapterId: expectString(obj.adapterId, 'storage.adapterId'),
+    storageId: expectString(obj.storageId, 'storage.storageId'),
+    adapterName: expectString(obj.adapterName, 'storage.adapterName'),
+    storageName: expectString(obj.storageName, 'storage.storageName'),
+    capabilities: parseCapabilities(obj.capabilities, 'storage.capabilities'),
+  };
+};
+
+const parseEntry = (raw: unknown, path: string): StorageEntry => {
+  const obj = expectObject(raw, path);
+  const key = expectString(obj.key, `${path}.key`);
+  const type = expectEntryType(obj.type, `${path}.type`);
+  const valuePath = `${path}.value`;
+
+  switch (type) {
+    case 'string': {
+      const value = obj.value;
+      if (typeof value !== 'string') {
+        throw new ParseException(
+          valuePath,
+          `Expected string for type "string", got ${describe(value)}`,
+        );
+      }
+      return { key, type: 'string', value };
+    }
+    case 'number': {
+      const value = obj.value;
+      if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new ParseException(
+          valuePath,
+          `Expected finite number for type "number", got ${describe(value)}`,
+        );
+      }
+      return { key, type: 'number', value };
+    }
+    case 'boolean': {
+      const value = obj.value;
+      if (typeof value !== 'boolean') {
+        throw new ParseException(
+          valuePath,
+          `Expected boolean for type "boolean", got ${describe(value)}`,
+        );
+      }
+      return { key, type: 'boolean', value };
+    }
+    case 'buffer': {
+      const value = obj.value;
+      if (!Array.isArray(value)) {
+        throw new ParseException(
+          valuePath,
+          `Expected number[] for type "buffer", got ${describe(value)}`,
+        );
+      }
+      const bytes = value.map((byte, index) => {
+        if (
+          typeof byte !== 'number' ||
+          !Number.isInteger(byte) ||
+          byte < 0 ||
+          byte > 255
+        ) {
+          throw new ParseException(
+            `${valuePath}[${index}]`,
+            `Expected uint8 (integer 0-255), got ${describe(byte)}`,
+          );
+        }
+        return byte;
+      });
+      return { key, type: 'buffer', value: bytes };
+    }
+  }
+};
+
+export const parseSnapshot = (raw: unknown): ParseResult => {
+  try {
+    const root = expectObject(raw, '$');
+    const version = root.version;
+    if (version !== SUPPORTED_VERSION) {
+      throw new ParseException(
+        'version',
+        `Unsupported snapshot version: ${describe(version)} (this build supports version ${SUPPORTED_VERSION})`,
+      );
+    }
+    const plugin = expectString(root.plugin, 'plugin');
+    const createdAt = expectString(root.createdAt, 'createdAt');
+    const storage = parseStorageMeta(root.storage);
+    const rawEntries = expectArray(root.entries, 'entries');
+    const entries = rawEntries.map((entry, index) =>
+      parseEntry(entry, `entries[${index}]`),
+    );
+    return {
+      ok: true,
+      snapshot: {
+        version: SUPPORTED_VERSION,
+        plugin,
+        createdAt,
+        storage,
+        entries,
+      },
+    };
+  } catch (error) {
+    if (error instanceof ParseException) {
+      return { ok: false, error: { path: error.path, message: error.message } };
+    }
+    throw error;
+  }
+};
+
+export const buildSnapshot = (args: {
+  target: StorageTarget;
+  adapterName: string;
+  storageName: string;
+  capabilities: StorageCapabilities;
+  entries: StorageEntry[];
+}): StorageSnapshotV1 => ({
+  version: 1,
+  plugin: PLUGIN_ID,
+  createdAt: new Date().toISOString(),
+  storage: {
+    adapterId: args.target.adapterId,
+    storageId: args.target.storageId,
+    adapterName: args.adapterName,
+    storageName: args.storageName,
+    capabilities: args.capabilities,
+  },
+  entries: args.entries,
+});
+
+export type ImportPreview = {
+  newKeys: string[];
+  overwriteKeys: string[];
+  skippedKeys: { key: string; reason: 'blacklist' }[];
+  unsupportedTypes: { key: string; type: StorageEntryType }[];
+  metadataMismatch: boolean;
+};
+
+export const computePreview = (
+  snapshot: StorageSnapshotV1,
+  current: {
+    target: StorageTarget;
+    capabilities: StorageCapabilities;
+    entryKeys: Set<string>;
+    isBlacklisted: (key: string) => boolean;
+  },
+): ImportPreview => {
+  const newKeys: string[] = [];
+  const overwriteKeys: string[] = [];
+  const skippedKeys: { key: string; reason: 'blacklist' }[] = [];
+  const unsupportedTypes: { key: string; type: StorageEntryType }[] = [];
+
+  for (const entry of snapshot.entries) {
+    if (!supportsType(current.capabilities, entry.type)) {
+      unsupportedTypes.push({ key: entry.key, type: entry.type });
+      continue;
+    }
+    if (current.isBlacklisted(entry.key)) {
+      skippedKeys.push({ key: entry.key, reason: 'blacklist' });
+      continue;
+    }
+    if (current.entryKeys.has(entry.key)) {
+      overwriteKeys.push(entry.key);
+    } else {
+      newKeys.push(entry.key);
+    }
+  }
+
+  const metadataMismatch =
+    snapshot.storage.adapterId !== current.target.adapterId ||
+    snapshot.storage.storageId !== current.target.storageId;
+
+  return {
+    newKeys,
+    overwriteKeys,
+    skippedKeys,
+    unsupportedTypes,
+    metadataMismatch,
+  };
+};

package/src/shared/types.ts

@@ -37,6 +37,7 @@ export type StorageNode = {
   storage: SyncStorage | AsyncStorage;
   capabilities: StorageCapabilities;
   blacklist?: RegExp;
+  shouldFilterKey?: (key: string) => boolean;
 };
 
 export type StorageAdapter = {

package/src/ui/__tests__/binary-value-editor-state.test.ts

@@ -0,0 +1,199 @@
+import { describe, expect, it } from 'vitest';
+import {
+  initialState,
+  reduce,
+  validate,
+  type EditorState,
+} from '../binary-value-editor-state';
+
+const hexState = (bytes?: number[]): EditorState =>
+  initialState({ initialBytes: bytes, mode: 'hex' });
+
+describe('initialState', () => {
+  it('defaults to hex mode and empty text when no initialBytes', () => {
+    expect(initialState({})).toEqual({
+      mode: 'hex',
+      text: '',
+      bytes: null,
+      error: null,
+    });
+  });
+
+  it('encodes initial bytes as grouped hex when mode is hex', () => {
+    expect(initialState({ initialBytes: [0x89, 0x50, 0x4e, 0x47] })).toEqual({
+      mode: 'hex',
+      text: '89 50 4E 47',
+      bytes: [0x89, 0x50, 0x4e, 0x47],
+      error: null,
+    });
+  });
+
+  it('encodes initial bytes as base64 when mode is base64', () => {
+    expect(
+      initialState({ initialBytes: [0x48, 0x69], mode: 'base64' }),
+    ).toEqual({
+      mode: 'base64',
+      text: 'SGk=',
+      bytes: [0x48, 0x69],
+      error: null,
+    });
+  });
+
+  it('treats empty initial bytes the same as no bytes', () => {
+    expect(initialState({ initialBytes: [] })).toEqual({
+      mode: 'hex',
+      text: '',
+      bytes: null,
+      error: null,
+    });
+  });
+});
+
+describe('reduce: set-text', () => {
+  it('parses valid hex into bytes', () => {
+    const next = reduce(hexState(), { type: 'set-text', text: '89 50 4E 47' });
+    expect(next).toEqual({
+      mode: 'hex',
+      text: '89 50 4E 47',
+      bytes: [0x89, 0x50, 0x4e, 0x47],
+      error: null,
+    });
+  });
+
+  it('keeps invalid hex text but clears bytes and surfaces the parse error', () => {
+    const next = reduce(hexState(), { type: 'set-text', text: 'gg' });
+    expect(next).toEqual({
+      mode: 'hex',
+      text: 'gg',
+      bytes: null,
+      error: 'Hex input contains invalid characters.',
+    });
+  });
+
+  it('keeps trailing-nibble text but reports incomplete bytes', () => {
+    const next = reduce(hexState(), { type: 'set-text', text: '89 5' });
+    expect(next).toEqual({
+      mode: 'hex',
+      text: '89 5',
+      bytes: null,
+      error: 'Hex input must contain complete bytes.',
+    });
+  });
+
+  it('surfaces the empty-input error for cleared text', () => {
+    const next = reduce(hexState([0x89]), { type: 'set-text', text: '' });
+    expect(next).toEqual({
+      mode: 'hex',
+      text: '',
+      bytes: null,
+      error: 'Enter at least one byte.',
+    });
+  });
+
+  it('does not rewrite text (paste filter is responsible for that)', () => {
+    // Even though "DEAD" would canonicalise to "DE AD", set-text must
+    // preserve the user's exact text. Only normalize-paste rewrites it.
+    const next = reduce(hexState(), { type: 'set-text', text: 'DEAD' });
+    expect(next.text).toBe('DEAD');
+    expect(next.bytes).toEqual([0xde, 0xad]);
+  });
+});
+
+describe('reduce: normalize-paste', () => {
+  it('rewrites pasted hexdump into canonical grouped hex', () => {
+    const pasted =
+      '00000000  89 50 4E 47 0D 0A 1A 0A  00 00 00 0D 49 48 44 52  |.PNG........IHDR|';
+    const next = reduce(hexState(), { type: 'normalize-paste', text: pasted });
+    expect(next.text).toBe('89 50 4E 47 0D 0A 1A 0A  00 00 00 0D 49 48 44 52');
+    expect(next.bytes).toEqual([
+      0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d,
+      0x49, 0x48, 0x44, 0x52,
+    ]);
+    expect(next.error).toBeNull();
+  });
+
+  it('rewrites pasted base64 into canonical base64', () => {
+    const state = initialState({ mode: 'base64' });
+    const next = reduce(state, {
+      type: 'normalize-paste',
+      text: '  SGVs\nbG8=  ',
+    });
+    expect(next.text).toBe('SGVsbG8=');
+    expect(next.bytes).toEqual([0x48, 0x65, 0x6c, 0x6c, 0x6f]);
+  });
+
+  it('keeps the raw pasted text and reports the error when invalid', () => {
+    const next = reduce(hexState(), {
+      type: 'normalize-paste',
+      text: 'oh no',
+    });
+    expect(next.text).toBe('oh no');
+    expect(next.bytes).toBeNull();
+    expect(next.error).toBe('Hex input contains invalid characters.');
+  });
+});
+
+describe('reduce: switch-mode', () => {
+  it('converts valid bytes in place when switching hex -> base64', () => {
+    const start = reduce(hexState(), { type: 'set-text', text: '48 69' });
+    const next = reduce(start, { type: 'switch-mode', mode: 'base64' });
+    expect(next).toEqual({
+      mode: 'base64',
+      text: 'SGk=',
+      bytes: [0x48, 0x69],
+      error: null,
+    });
+  });
+
+  it('converts valid bytes in place when switching base64 -> hex', () => {
+    const start = reduce(initialState({ mode: 'base64' }), {
+      type: 'set-text',
+      text: 'SGk=',
+    });
+    const next = reduce(start, { type: 'switch-mode', mode: 'hex' });
+    expect(next).toEqual({
+      mode: 'hex',
+      text: '48 69',
+      bytes: [0x48, 0x69],
+      error: null,
+    });
+  });
+
+  it('clears text and error when current input is invalid', () => {
+    const invalid = reduce(hexState(), { type: 'set-text', text: '89 5' });
+    const next = reduce(invalid, { type: 'switch-mode', mode: 'base64' });
+    expect(next).toEqual({
+      mode: 'base64',
+      text: '',
+      bytes: null,
+      error: null,
+    });
+  });
+
+  it('is a no-op when the mode is unchanged', () => {
+    const state = reduce(hexState(), { type: 'set-text', text: '89 50' });
+    expect(reduce(state, { type: 'switch-mode', mode: 'hex' })).toBe(state);
+  });
+});
+
+describe('validate', () => {
+  it('passes when bytes are valid and non-empty', () => {
+    const state = reduce(hexState(), { type: 'set-text', text: '89 50' });
+    expect(validate(state)).toEqual({ ok: true, bytes: [0x89, 0x50] });
+  });
+
+  it('fails with the parse error when input is invalid', () => {
+    const state = reduce(hexState(), { type: 'set-text', text: 'gg' });
+    expect(validate(state)).toEqual({
+      ok: false,
+      reason: 'Hex input contains invalid characters.',
+    });
+  });
+
+  it('fails with the empty-input message when nothing is entered', () => {
+    expect(validate(hexState())).toEqual({
+      ok: false,
+      reason: 'Enter at least one byte.',
+    });
+  });
+});