Support nullable values with explicit delete() in storage API

- add delete(key) to StorageInstance
- make set(key, value) store null as a real value
- notify subscribers with undefined when keys are deleted
- update tests and docs for the new contract

Author: titouanmathis

packages/docs/utils/storage/createStorage.md

@@ -53,6 +53,7 @@ storage.set('theme', 'dark'); // ✅ typed
 // @errors: 2345
 storage.set('theme', 'blue'); // ❌ type error
 storage.get('user'); // { name: string; id: number } | undefined
+storage.delete('user');
 ```
 
 ## Parameters
@@ -68,11 +69,12 @@ A `StorageInstance<T>` with the following methods:
 
 - **`get(key)`** — Get the value for a key. Returns `undefined` if not set or if the stored value is corrupted.
 - **`get(key, defaultValue)`** — Get the value for a key, returning `defaultValue` if not set.
-- **`set(key, value)`** — Set a value. Pass `null` to remove the key.
+- **`set(key, value)`** — Set a value. `null` is stored as a real value when your type allows it.
+- **`delete(key)`** — Remove a key from storage. Subscribers are notified with `undefined`.
 - **`has(key)`** — Check if a key exists in storage.
 - **`keys()`** — List all keys managed by this instance. When a `prefix` is set, only prefixed keys are returned (with the prefix stripped).
 - **`clear()`** — Remove all entries. When a `prefix` is set, only prefixed keys are cleared — other keys in the same provider are left untouched. Subscribers are notified with `undefined`.
-- **`subscribe(key, callback)`** — Subscribe to changes on a key. Returns an unsubscribe function. Listeners are notified on both local changes and external sync events (cross-tab, navigation).
+- **`subscribe(key, callback)`** — Subscribe to changes on a key. Returns an unsubscribe function. Listeners are notified on both local changes and external sync events (cross-tab, navigation). `undefined` means the key is absent.
 - **`destroy()`** — Clean up all listeners and event handlers.
 
 ::: warning Cleanup

packages/js-toolkit/utils/storage/StorageStore.ts

@@ -40,17 +40,17 @@ export class StorageStore<T extends Record<string, any> = Record<string, any>>
     return defaultValue;
   }
 
-  set<K extends keyof T>(key: K, value: T[K] | null): void {
+  set<K extends keyof T>(key: K, value: T[K]): void {
     const resolved = this.resolveKey(key as string);
-    if (value === null) {
-      this.provider.remove(resolved);
-    } else {
-      this.provider.set(resolved, this.serializer.serialize(value));
-    }
-
+    this.provider.set(resolved, this.serializer.serialize(value));
     this.listeners.get(key)?.forEach((callback) => callback(value));
   }
 
+  delete<K extends keyof T>(key: K): void {
+    this.provider.remove(this.resolveKey(key as string));
+    this.listeners.get(key)?.forEach((callback) => callback(undefined));
+  }
+
   has<K extends keyof T>(key: K): boolean {
     return this.provider.has(this.resolveKey(key as string));
   }

packages/js-toolkit/utils/storage/types.ts

@@ -12,7 +12,8 @@ export interface StorageProvider {
 export interface StorageInstance<T = any> {
   get<K extends keyof T>(key: K): T[K] | undefined;
   get<K extends keyof T>(key: K, defaultValue: T[K]): T[K];
-  set<K extends keyof T>(key: K, value: T[K] | null): void;
+  set<K extends keyof T>(key: K, value: T[K]): void;
+  delete<K extends keyof T>(key: K): void;
   has<K extends keyof T>(key: K): boolean;
   keys(): (keyof T)[];
   clear(): void;

packages/tests/utils/storage.spec.ts

@@ -58,14 +58,23 @@ describe('Storage utilities', () => {
       expect(storage.get('theme', 'light')).toBe('dark');
     });
 
-    it('should remove key when set to null', () => {
+    it('should support storing null as a value', () => {
+      type Storage = { theme: string | null };
+      const storage = createLocalStorage<Storage>();
+
+      storage.set('theme', null);
+      expect(storage.get('theme')).toBeNull();
+      expect(localStorage.getItem('theme')).toBe('null');
+    });
+
+    it('should remove key when delete() is called', () => {
       type Storage = { theme: string };
       const storage = createLocalStorage<Storage>();
 
       storage.set('theme', 'dark');
       expect(storage.get('theme')).toBe('dark');
 
-      storage.set('theme', null);
+      storage.delete('theme');
       expect(storage.get('theme')).toBeUndefined();
       expect(localStorage.getItem('theme')).toBeNull();
     });
@@ -106,6 +115,19 @@ describe('Storage utilities', () => {
       expect(callback).toHaveBeenCalledTimes(1);
     });
 
+    it('should notify subscribers with undefined on delete()', () => {
+      type Storage = { theme: string | null };
+      const storage = createLocalStorage<Storage>();
+      const callback = vi.fn();
+
+      storage.subscribe('theme', callback);
+      storage.set('theme', null);
+      expect(callback).toHaveBeenCalledWith(null);
+
+      storage.delete('theme');
+      expect(callback).toHaveBeenLastCalledWith(undefined);
+    });
+
     it('should use custom serializer', () => {
       type Storage = { count: string };
       const serializer = {
@@ -313,7 +335,7 @@ describe('Storage utilities', () => {
       storage.set('theme', 'dark');
       expect(localStorage.getItem('myapp:theme')).toBe(JSON.stringify('dark'));
 
-      storage.set('theme', null);
+      storage.delete('theme');
       expect(localStorage.getItem('myapp:theme')).toBeNull();
     });
   });
@@ -326,7 +348,7 @@ describe('Storage utilities', () => {
       expect(storage.has('theme')).toBe(false);
       storage.set('theme', 'dark');
       expect(storage.has('theme')).toBe(true);
-      storage.set('theme', null);
+      storage.delete('theme');
       expect(storage.has('theme')).toBe(false);
     });