feat(storage): add custom serializer hook for BaseStorageManager (#58)

marcstraube · claude · web-flow · commit 052bf669c0c2 · 2026-04-17T13:15:04.000Z
## Summary - Add configurable `serializer`/`deserializer` options to `StorageConfig` (defaults to `JSON.stringify`/`JSON.parse` for backwards compatibility) - Replace hardcoded JSON calls in `BaseStorageManager` and `StorageManager` with config hooks - Add `withSerializer()` fluent method to `StorageConfig` Closes #6 ## Test plan - [x] Default behavior unchanged (JSON.stringify/JSON.parse) - [x] Custom serializer/deserializer roundtrip via set/get - [x] Custom serializer works with entries() and getResult() - [x] Date revival with custom deserializer reviver - [x] Fluent chain preserves serializer through all with* methods - [x] 100% line coverage maintained 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
diff --git a/src/storage/BaseStorageManager.ts b/src/storage/BaseStorageManager.ts
@@ -57,10 +57,10 @@ export interface BaseStorageStats {
  * Implements common logic for localStorage and sessionStorage wrappers.
  *
  * @remarks
- * Values are serialized via `JSON.stringify` and deserialized via `JSON.parse`.
- * Types without native JSON representation (Date, Map, Set, RegExp, etc.)
- * will lose their type information. Use plain objects and primitives, or
- * convert values before storing and after retrieval.
+ * Values are serialized and deserialized using configurable hooks
+ * (defaults to `JSON.stringify` / `JSON.parse`). To preserve non-JSON-native
+ * types (Date, Map, Set, RegExp, etc.), provide custom `serializer` and
+ * `deserializer` functions via {@link StorageConfig}.
  */
 export abstract class BaseStorageManager<T = unknown> {
   protected readonly config: StorageConfig;
@@ -141,7 +141,7 @@ export abstract class BaseStorageManager<T = unknown> {
     const storage = this.getNativeStorage();
 
     try {
-      const serialized = JSON.stringify(entry);
+      const serialized = this.config.serializer(entry);
       storage.setItem(fullKey, serialized);
       this.enforceLimits();
       this.config.logger.debug('Stored:', key);
@@ -152,7 +152,7 @@ export abstract class BaseStorageManager<T = unknown> {
 
         // Retry once
         try {
-          storage.setItem(fullKey, JSON.stringify(entry));
+          storage.setItem(fullKey, this.config.serializer(entry));
           this.config.logger.debug('Stored after eviction:', key);
         } catch (retryError) {
           throw StorageError.quotaExceeded(key, retryError);
@@ -184,7 +184,7 @@ export abstract class BaseStorageManager<T = unknown> {
     }
 
     try {
-      const parsed: unknown = JSON.parse(raw);
+      const parsed: unknown = this.config.deserializer(raw);
 
       if (!isStorageEntry<T>(parsed)) {
         this.config.logger.error('Invalid storage entry structure:', key);
@@ -221,7 +221,7 @@ export abstract class BaseStorageManager<T = unknown> {
     }
 
     try {
-      const parsed: unknown = JSON.parse(raw);
+      const parsed: unknown = this.config.deserializer(raw);
 
       if (!isStorageEntry<T>(parsed)) {
         return Result.err(StorageError.corrupted(key, 'invalid storage entry structure'));
@@ -303,7 +303,7 @@ export abstract class BaseStorageManager<T = unknown> {
       try {
         const raw = storage.getItem(this.getFullKey(key));
         if (raw !== null) {
-          const parsed: unknown = JSON.parse(raw);
+          const parsed: unknown = this.config.deserializer(raw);
 
           if (!isStorageEntry<T>(parsed)) {
             // Skip entries with invalid structure
diff --git a/src/storage/StorageConfig.ts b/src/storage/StorageConfig.ts
@@ -54,6 +54,20 @@ export interface StorageConfigOptions {
    * @default true
    */
   readonly useMemoryFallback?: boolean;
+
+  /**
+   * Custom serializer function to convert values to strings for storage.
+   * Must produce output that the corresponding `deserializer` can parse.
+   * @default JSON.stringify
+   */
+  readonly serializer?: (value: unknown) => string;
+
+  /**
+   * Custom deserializer function to parse stored strings back to values.
+   * Must handle output produced by the corresponding `serializer`.
+   * @default JSON.parse
+   */
+  readonly deserializer?: (raw: string) => unknown;
 }
 
 export class StorageConfig {
@@ -62,19 +76,25 @@ export class StorageConfig {
   readonly minSafeEntries: number;
   readonly logger: LoggerLike;
   readonly useMemoryFallback: boolean;
+  readonly serializer: (value: unknown) => string;
+  readonly deserializer: (raw: string) => unknown;
 
   private constructor(
     prefix: string,
     maxEntries: number,
     minSafeEntries: number,
     logger: LoggerLike,
-    useMemoryFallback: boolean
+    useMemoryFallback: boolean,
+    serializer: (value: unknown) => string,
+    deserializer: (raw: string) => unknown
   ) {
     this.prefix = prefix;
     this.maxEntries = maxEntries;
     this.minSafeEntries = minSafeEntries;
     this.logger = logger;
     this.useMemoryFallback = useMemoryFallback;
+    this.serializer = serializer;
+    this.deserializer = deserializer;
   }
 
   // =========================================================================
@@ -99,7 +119,18 @@ export class StorageConfig {
 
     const useMemoryFallback = options.useMemoryFallback ?? true;
 
-    return new StorageConfig(prefix, maxEntries, minSafeEntries, logger, useMemoryFallback);
+    const serializer = options.serializer ?? JSON.stringify;
+    const deserializer = options.deserializer ?? JSON.parse;
+
+    return new StorageConfig(
+      prefix,
+      maxEntries,
+      minSafeEntries,
+      logger,
+      useMemoryFallback,
+      serializer,
+      deserializer
+    );
   }
 
   /**
@@ -141,7 +172,9 @@ export class StorageConfig {
       this.maxEntries,
       this.minSafeEntries,
       this.logger,
-      this.useMemoryFallback
+      this.useMemoryFallback,
+      this.serializer,
+      this.deserializer
     );
   }
 
@@ -155,7 +188,9 @@ export class StorageConfig {
       maxEntries,
       Math.min(this.minSafeEntries, maxEntries),
       this.logger,
-      this.useMemoryFallback
+      this.useMemoryFallback,
+      this.serializer,
+      this.deserializer
     );
   }
 
@@ -169,7 +204,9 @@ export class StorageConfig {
       this.maxEntries,
       minSafeEntries,
       this.logger,
-      this.useMemoryFallback
+      this.useMemoryFallback,
+      this.serializer,
+      this.deserializer
     );
   }
 
@@ -182,7 +219,9 @@ export class StorageConfig {
       this.maxEntries,
       this.minSafeEntries,
       logger,
-      this.useMemoryFallback
+      this.useMemoryFallback,
+      this.serializer,
+      this.deserializer
     );
   }
 
@@ -195,7 +234,28 @@ export class StorageConfig {
       this.maxEntries,
       this.minSafeEntries,
       this.logger,
-      enabled
+      enabled,
+      this.serializer,
+      this.deserializer
+    );
+  }
+
+  /**
+   * Create new config with custom serializer and deserializer.
+   * Both must be provided together to ensure roundtrip compatibility.
+   */
+  withSerializer(
+    serializer: (value: unknown) => string,
+    deserializer: (raw: string) => unknown
+  ): StorageConfig {
+    return new StorageConfig(
+      this.prefix,
+      this.maxEntries,
+      this.minSafeEntries,
+      this.logger,
+      this.useMemoryFallback,
+      serializer,
+      deserializer
     );
   }
 }
diff --git a/src/storage/StorageManager.ts b/src/storage/StorageManager.ts
@@ -126,7 +126,7 @@ export class StorageManager<T = unknown> extends BaseStorageManager<T> {
       const parseValue = (raw: string | null): T | null => {
         if (raw === null) return null;
         try {
-          const parsed: unknown = JSON.parse(raw);
+          const parsed: unknown = this.config.deserializer(raw);
           return isStorageEntry<T>(parsed) ? parsed.data : null;
         } catch {
           return null;
diff --git a/tests/storage/BaseStorageManager.test.ts b/tests/storage/BaseStorageManager.test.ts
@@ -259,8 +259,7 @@ describe('BaseStorageManager', () => {
       const origSetItem = mockStorage.setItem.bind(mockStorage);
       mockStorage.setItem = (key: string, value: string) => {
         if (key === 'test.big' && callCount++ === 0) {
-          const err = new DOMException('', 'QuotaExceededError');
-          throw err;
+          throw new DOMException('', 'QuotaExceededError');
         }
         origSetItem(key, value);
       };
@@ -270,6 +269,69 @@ describe('BaseStorageManager', () => {
     });
   });
 
+  describe('custom serializer', () => {
+    it('should use custom serializer for set and deserializer for get', () => {
+      const serializer = vi.fn((value: unknown): string => `custom:${JSON.stringify(value)}`);
+      const deserializer = vi.fn((raw: string): unknown => JSON.parse(raw.replace('custom:', '')));
+      const config = StorageConfig.create({ prefix: 'test', serializer, deserializer });
+      const manager = StorageManager.create(config);
+
+      manager.set('key', 'value');
+      expect(serializer).toHaveBeenCalled();
+
+      const result = manager.get('key');
+      expect(deserializer).toHaveBeenCalled();
+      expect(result).toBe('value');
+    });
+
+    it('should use custom serializer for entries()', () => {
+      const serializer = (value: unknown): string => `custom:${JSON.stringify(value)}`;
+      const deserializer = (raw: string): unknown => JSON.parse(raw.replace('custom:', ''));
+      const config = StorageConfig.create({ prefix: 'test', serializer, deserializer });
+      const manager = StorageManager.create(config);
+
+      manager.set('key', 'value');
+      const entries = manager.entries();
+      expect(entries).toHaveLength(1);
+      expect(entries[0]!.value).toBe('value');
+    });
+
+    it('should use custom serializer with getResult()', () => {
+      const serializer = (value: unknown): string => `custom:${JSON.stringify(value)}`;
+      const deserializer = (raw: string): unknown => JSON.parse(raw.replace('custom:', ''));
+      const config = StorageConfig.create({ prefix: 'test', serializer, deserializer });
+      const manager = StorageManager.create(config);
+
+      manager.set('key', 'value');
+      const result = manager.getResult('key');
+      expect(Result.isOk(result)).toBe(true);
+      if (Result.isOk(result)) {
+        expect(result.value).toBe('value');
+      }
+    });
+
+    it('should preserve Date objects with custom serializer using reviver', () => {
+      // JSON.stringify calls Date.toJSON() before the replacer sees the value,
+      // so a reviver-based approach is needed to restore Date instances.
+      const ISO_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z$/;
+      const serializer = JSON.stringify;
+      const deserializer = (raw: string): unknown =>
+        JSON.parse(raw, (_key, val: unknown) =>
+          typeof val === 'string' && ISO_REGEX.test(val) ? new Date(val) : val
+        );
+      const config = StorageConfig.create({ prefix: 'test', serializer, deserializer });
+      const manager = StorageManager.create<{ createdAt: Date }>(config);
+
+      const date = new Date('2024-06-15T12:00:00Z');
+      manager.set('item', { createdAt: date });
+
+      const retrieved = manager.get('item');
+      expect(retrieved).not.toBeNull();
+      expect(retrieved!.createdAt).toBeInstanceOf(Date);
+      expect(retrieved!.createdAt.toISOString()).toBe('2024-06-15T12:00:00.000Z');
+    });
+  });
+
   describe('isQuotaError', () => {
     it('should detect QuotaExceededError by name', () => {
       const config = StorageConfig.create({ prefix: 'test', minSafeEntries: 0 });
@@ -279,8 +341,7 @@ describe('BaseStorageManager', () => {
       const origSetItem = mockStorage.setItem.bind(mockStorage);
       mockStorage.setItem = (key: string, value: string) => {
         if (key === 'test.item' && callCount++ === 0) {
-          const err = new DOMException('', 'QuotaExceededError');
-          throw err;
+          throw new DOMException('', 'QuotaExceededError');
         }
         origSetItem(key, value);
       };
diff --git a/tests/storage/StorageConfig.test.ts b/tests/storage/StorageConfig.test.ts
@@ -267,6 +267,71 @@ describe('StorageConfig', () => {
     });
   });
 
+  describe('create with custom serializer', () => {
+    it('should use JSON.stringify and JSON.parse by default', () => {
+      const config = StorageConfig.create();
+
+      expect(config.serializer).toBe(JSON.stringify);
+      expect(config.deserializer).toBe(JSON.parse);
+    });
+
+    it('should accept custom serializer and deserializer', () => {
+      const serializer = (value: unknown): string => `custom:${JSON.stringify(value)}`;
+      const deserializer = (raw: string): unknown => JSON.parse(raw.replace('custom:', ''));
+      const config = StorageConfig.create({ serializer, deserializer });
+
+      expect(config.serializer).toBe(serializer);
+      expect(config.deserializer).toBe(deserializer);
+    });
+  });
+
+  describe('withSerializer', () => {
+    it('should create new config with custom serializer and deserializer', () => {
+      const original = StorageConfig.create();
+      const serializer = (value: unknown): string => `custom:${JSON.stringify(value)}`;
+      const deserializer = (raw: string): unknown => JSON.parse(raw.replace('custom:', ''));
+      const modified = original.withSerializer(serializer, deserializer);
+
+      expect(modified.serializer).toBe(serializer);
+      expect(modified.deserializer).toBe(deserializer);
+      expect(original.serializer).toBe(JSON.stringify);
+      expect(original.deserializer).toBe(JSON.parse);
+    });
+
+    it('should preserve other settings', () => {
+      const original = StorageConfig.create({
+        prefix: 'myApp',
+        maxEntries: 100,
+        useMemoryFallback: false,
+      });
+      const serializer = JSON.stringify;
+      const deserializer = JSON.parse;
+      const modified = original.withSerializer(serializer, deserializer);
+
+      expect(modified.prefix).toBe('myApp');
+      expect(modified.maxEntries).toBe(100);
+      expect(modified.useMemoryFallback).toBe(false);
+    });
+  });
+
+  describe('fluent methods preserve serializer', () => {
+    it('should preserve custom serializer through fluent chain', () => {
+      const serializer = (value: unknown): string => `custom:${JSON.stringify(value)}`;
+      const deserializer = (raw: string): unknown => JSON.parse(raw.replace('custom:', ''));
+      const config = StorageConfig.create({ serializer, deserializer });
+
+      const chained = config
+        .withPrefix('newApp')
+        .withMaxEntries(200)
+        .withMinSafeEntries(10)
+        .withLogger(Logger.silent())
+        .withMemoryFallback(false);
+
+      expect(chained.serializer).toBe(serializer);
+      expect(chained.deserializer).toBe(deserializer);
+    });
+  });
+
   describe('immutability', () => {
     it('should not modify original config', () => {
       const original = StorageConfig.create({
