react-wire-persisted 2.1.0 → 3.1.0

package/src/providers/{StorageProvider.js → RWPStorageProvider.ts}

@@ -1,17 +1,20 @@
 /**
  * Base class to allow storage access
- * @see `LocalStorageProvider.js` for an example implementation
+ * @see `LocalStorageProvider.ts` for an example implementation
  */
 /** biome-ignore-all lint/correctness/noUnusedFunctionParameters: WIP next PR will switch to TypeScript */
-class StorageProvider {
+export abstract class RWPStorageProvider {
+    namespace: string | null
+    registry: Record<string, unknown>
+
     /**
      * Initializes the class
-     * @param {String} namespace Namespace to prefix all keys with. Mostly used for the logging & reset functions
+     * @param {String} namespace Namespace to prefix all keys with. Mostly used for the logging and reset functions
      * @param {Object} registry (Optional) Initialize the storage provider with an existing registry
      */
-    constructor(namespace, registry) {
+    protected constructor(namespace: string, registry: Record<string, unknown>) {
         // Simulate being an abstract class
-        if (new.target === StorageProvider)
+        if (new.target === RWPStorageProvider)
             throw TypeError(`StorageProvider is abstract. Extend this class to implement it`)
 
         this.namespace = namespace || null
@@ -24,14 +27,14 @@ class StorageProvider {
      * @param {String} namespace New namespace for this storage provider
      */
     /* istanbul ignore next */
-    setNamespace(namespace) {}
+    abstract setNamespace(namespace: string | null): void
 
     /**
-     * Registers an item with it's initial value. This is used for logging, resetting, etc.
-     * @param {String} key Storage item's key
-     * @param {*} initialValue Storage item's initial value
+     * Registers an item with its initial value. This is used for logging, resetting, etc.
+     * @param {String} key InternalStorage item's key
+     * @param {*} initialValue InternalStorage item's initial value
      */
-    register(key, initialValue) {
+    register<T>(key: string, initialValue: T | null) {
         this.registry[key] = initialValue
     }
 
@@ -40,7 +43,7 @@ class StorageProvider {
      * @param {String} key Key for the item to retrieve
      */
     /* istanbul ignore next */
-    getItem(key) {}
+    abstract getItem<T>(key: string): T | null
 
     /**
      * Stores a value
@@ -48,7 +51,7 @@ class StorageProvider {
      * @param {String} value Item's value to store
      */
     /* istanbul ignore next */
-    setItem(key, value) {}
+    abstract setItem<T>(key: string, value: T | null): void
 
     /**
      * Removes an item from storage
@@ -56,14 +59,14 @@ class StorageProvider {
      * @param {Boolean} fromRegistry (Optional) If the item should also be removed from the registry
      */
     /* istanbul ignore next */
-    removeItem(key, fromRegistry = false) {}
+    abstract removeItem(key: string, fromRegistry: boolean): void
 
     /**
-     * Gets all stored keys & values
+     * Gets all stored keys and values
      * If a `namespace` was set, only keys prefixed with the namespace will be returned
      */
     /* istanbul ignore next */
-    getAll() {}
+    abstract getAll(): Record<string, unknown>
 
     /**
      *
@@ -72,7 +75,7 @@ class StorageProvider {
      * @param {Boolean} clearRegistry (Optional) If the registry should also be cleared
      */
     /* istanbul ignore next */
-    _resetAll(useInitialValues = true, excludedKeys = [], clearRegistry = false) {}
+    abstract _resetAll(useInitialValues: boolean, excludedKeys: string[], clearRegistry: boolean): void
 
     /**
      * Resets all values to their initial values
@@ -80,7 +83,7 @@ class StorageProvider {
      * @param {String[]} excludedKeys (Optional) List of keys to exclude
      */
     /* istanbul ignore next */
-    resetAll(excludedKeys = []) {}
+    abstract resetAll(excludedKeys: string[]): void
 
     /**
      * Removes all items from local storage.
@@ -88,7 +91,15 @@ class StorageProvider {
      * @param {String[]} excludedKeys (Optional) List of keys to exclude
      */
     /* istanbul ignore next */
-    removeAll(excludedKeys = []) {}
+    abstract removeAll(excludedKeys: string[]): void
+
+    upgradeToRealStorage(): boolean {
+        return false
+    }
+
+    isUsingFakeStorage(): boolean {
+        return false
+    }
 }
 
-export default StorageProvider
+export default RWPStorageProvider

package/src/{react-wire-persisted.js → react-wire-persisted.ts}

@@ -1,21 +1,28 @@
-import { createWire } from '@forminator/react-wire'
-import LocalStorageProvider from './providers/LocalStorageProvider.js'
-import { getHasHydratedStorage, getIsClient, markStorageAsHydrated } from './utils/index.js'
+import { createWire, type Defined, type Wire } from '@forminator/react-wire'
+import LocalStorageProvider from '@/providers/LocalStorageProvider'
+import type RWPStorageProvider from '@/providers/RWPStorageProvider'
+import type { PersistedWire, RWPOptions, WireLikeObject } from '@/types'
+import { getHasHydratedStorage, getIsClient, markStorageAsHydrated } from '@/utils'
 
 // Generate unique instance ID
 const instanceId = Math.random().toString(36).substring(7)
-const rwpLog = (...args) => {
+const rwpLog = (...args: unknown[]) => {
     if (typeof globalThis !== 'undefined' && globalThis.__RWP_LOGGING_ENABLED__ !== false) {
         console.log(...args)
     }
 }
 
-export const defaultOptions = {
+export const defaultOptions: RWPOptions = {
     logging: {
         enabled: false,
     },
+    storageProvider: LocalStorageProvider,
 }
 
+let options: RWPOptions = { ...defaultOptions }
+let storage: RWPStorageProvider
+const pendingLogs: unknown[][] = []
+
 // Set global logging flag on startup
 if (typeof globalThis !== 'undefined' && globalThis.__RWP_LOGGING_ENABLED__ === undefined) {
     globalThis.__RWP_LOGGING_ENABLED__ = defaultOptions.logging.enabled
@@ -23,26 +30,21 @@ if (typeof globalThis !== 'undefined' && globalThis.__RWP_LOGGING_ENABLED__ ===
 
 rwpLog('[RWP] Module initialized, instance ID:', instanceId)
 
-const Provider = LocalStorageProvider
-
 // Make storage global so all instances share the same storage after upgrade
 rwpLog('[RWP] About to check global storage, instanceId:', instanceId)
-let storage
 try {
     if (!globalThis.__RWP_STORAGE__) {
         rwpLog('[RWP] Creating global storage in instance:', instanceId)
-        globalThis.__RWP_STORAGE__ = new Provider()
+        globalThis.__RWP_STORAGE__ = new LocalStorageProvider('__internal_rwp_storage__')
     } else {
         rwpLog('[RWP] Using existing global storage in instance:', instanceId)
     }
     storage = globalThis.__RWP_STORAGE__
-    rwpLog('[RWP] Storage assigned successfully')
+    rwpLog('[RWP] InternalStorage assigned successfully')
 } catch (error) {
     if (globalThis.__RWP_LOGGING_ENABLED__) console.error('[RWP] Error setting up global storage:', error)
-    storage = new Provider()
+    storage = new LocalStorageProvider('__internal_rwp_storage__')
 }
-let options = { ...defaultOptions }
-const pendingLogs = []
 
 // Use a global registry to handle multiple module instances
 // This ensures all instances share the same wire registry
@@ -56,38 +58,32 @@ if (typeof globalThis !== 'undefined') {
 }
 
 // Registry to track wire instances for hydration refresh
-const registeredWires = globalThis.__RWP_REGISTERED_WIRES__ || new Map()
+const registeredWires = globalThis.__RWP_REGISTERED_WIRES__ || new Map<string, WireLikeObject>()
 rwpLog('[RWP] registeredWires Map reference in instance:', instanceId, 'size:', registeredWires.size)
 
-/**
- * Gets the namespace of the storage provider
- *
- * @returns {String}
- */
-export const getNamespace = () => storage.namespace
+export const getNamespace = (): string | null => storage.namespace
 
-/**
- * Gets the current storage provider class instance
- *
- * @returns {StorageProvider}
- */
-export const getStorage = () => storage
-
-export const getOptions = () => options
+export const getStorage = (): RWPStorageProvider => storage
 
 /**
  * Sets the namespace for the storage provider
  *
  * @param {String} namespace The namespace for the storage provider
  */
-export const setNamespace = (namespace) => {
+export const setNamespace = (namespace: string) => {
     rwpLog('[RWP] setNamespace() called with:', namespace, 'registered wires before:', registeredWires.size)
+    const currentNamespace = namespace || getNamespace()
+
+    if (!currentNamespace) throw new Error('react-wire-persisted: Cannot set namespace to null or undefined')
+
     storage.setNamespace(namespace)
-    storage = new Provider(namespace || getNamespace())
-    rwpLog('[RWP] setNamespace() done, registered wires after:', registeredWires.size)
+    storage = new LocalStorageProvider(currentNamespace)
+    rwpLog(`[RWP] setNamespace() done, registered wires after:`, registeredWires.size)
 }
 
-export const setOptions = (value) => {
+export const getOptions = (): RWPOptions => options
+
+export const setOptions = (value: Partial<RWPOptions>) => {
     options = {
         ...options,
         ...value,
@@ -101,7 +97,7 @@ export const setOptions = (value) => {
         console.info('Flushing', pendingLogs.length, 'pending logs')
         while (pendingLogs.length)
             /* istanbul ignore next */
-            console.log(...pendingLogs.shift())
+            console.log(...(pendingLogs.shift() || []))
     }
 }
 
@@ -113,7 +109,7 @@ const refreshAllWires = () => {
     rwpLog('[RWP] refreshAllWires() called in instance:', instanceId, 'registered wires:', registeredWires.size)
     log('react-wire-persisted: refreshAllWires() called, registered wires:', registeredWires.size)
 
-    registeredWires.forEach((wire, key) => {
+    registeredWires.forEach((wire: Wire<unknown> | WireLikeObject, key: string) => {
         const storedValue = storage.getItem(key)
         const currentValue = wire.getValue()
 
@@ -141,9 +137,9 @@ const refreshAllWires = () => {
  * Attempts to upgrade the storage provider from fake storage to real localStorage
  * This should be called on the client side after hydration
  *
- * @returns {Boolean} True if upgrade was successful
+ * @returns true if upgrade was successful
  */
-export const upgradeStorage = () => {
+export const upgradeStorage = (): boolean => {
     rwpLog('[RWP] upgradeStorage() called in instance:', instanceId, {
         isClient: getIsClient(),
         isUsingFakeStorage: storage.isUsingFakeStorage(),
@@ -173,7 +169,7 @@ export const upgradeStorage = () => {
     return upgraded
 }
 
-const log = (...args) => {
+const log = (...args: unknown[]) => {
     /* istanbul ignore next */
     if (options.logging.enabled)
         /* istanbul ignore next */
@@ -182,28 +178,28 @@ const log = (...args) => {
 }
 
 /**
- * Creates a persisted Wire using the `StorageProvider` that is currently set
+ * Creates a persisted Wire using the `RWPStorageProvider` that is currently set
  * Defaults to `localStorage` via `LocalStorageProvider`
  *
  * @param {String} key Unique key for storing this value
  * @param {*} value Initial value of this Wire
  * @returns A new Wire decorated with localStorage functionality
  */
-export const createPersistedWire = (key, value = null) => {
+export const createPersistedWire = <T = null>(key: string, value: T = null as T): PersistedWire<T> => {
     rwpLog('[RWP] createPersistedWire() called in instance:', instanceId, 'key:', key, 'value:', value)
 
     // This check helps ensure no accidental key typos occur
-    if (!key && typeof key !== 'number') throw new Error(`createPersistedWire: Key cannot be a falsey value (${key}}`)
+    if (!key) throw new Error(`createPersistedWire: Key cannot be a falsey value (${key}}`)
 
     // Track this writable entry so we can easily clear all
     storage.register(key, value)
 
     // The actual Wire backing object
-    const wire = createWire(value)
+    const wire = createWire<T>(value)
 
     const getValue = () => wire.getValue()
 
-    const setValue = (newValue) => {
+    const setValue = (newValue: Defined<T>) => {
         rwpLog(
             '[RWP] setValue called in instance:',
             instanceId,
@@ -216,19 +212,19 @@ export const createPersistedWire = (key, value = null) => {
         return wire.setValue(newValue)
     }
 
-    const subscribe = (fn) => {
-        wire.subscribe(fn)
+    const subscribe = (callback: (value: Defined<T>) => void) => {
+        return wire.subscribe(callback)
     }
 
     // Always start with default value to ensure SSR consistency
-    let initialValue = value
+    let initialValue: T = value
 
     // Only read from storage if we've hydrated OR if storage is already using real localStorage
     // (prevents hydration mismatch in SSR, but allows normal behavior in client-only apps)
     const canReadStorage = getHasHydratedStorage() || !storage.isUsingFakeStorage()
 
     if (canReadStorage && getIsClient()) {
-        const storedValue = storage.getItem(key)
+        const storedValue = storage.getItem<T>(key)
 
         if (storedValue !== null) initialValue = storedValue
     }
@@ -241,7 +237,7 @@ export const createPersistedWire = (key, value = null) => {
         canReadStorage,
     })
 
-    if (initialValue !== value) setValue(initialValue)
+    if (initialValue !== value && initialValue !== undefined) setValue(initialValue as Defined<T>)
 
     // Register wire for post-hydration refresh
     registeredWires.set(key, {

package/src/types.ts

@@ -0,0 +1,19 @@
+import type { Wire } from '@forminator/react-wire'
+import type RWPStorageProvider from '@/providers/RWPStorageProvider'
+
+export type RWPOptions = {
+    logging: { enabled: boolean }
+    storageProvider?: typeof RWPStorageProvider
+}
+
+export type PersistedWire<T> = Wire<T>
+
+export interface InternalStorage {
+    getItem: (key: string) => string | null
+    setItem: (key: string, value: string) => void
+    removeItem: (key: string) => void
+}
+
+export type AnyStorage = InternalStorage | Storage
+
+export type WireLikeObject = Pick<Wire<unknown>, 'getValue' | 'setValue' | 'subscribe'>

package/src/utils/fakeLocalStorage.ts

@@ -0,0 +1,17 @@
+import type { InternalStorage } from '@/types'
+
+const storage: Record<string, string> = {
+    __IS_FAKE_LOCAL_STORAGE__: 'true',
+}
+
+export const fakeLocalStorage: InternalStorage = {
+    getItem: (key: string): string | null => storage[key],
+    setItem: (key: string, value: string): void => {
+        storage[key] = value
+    },
+    removeItem: (key: string): void => {
+        delete storage[key]
+    },
+    // Make Object.keys() work properly for _resetAll method
+    ...storage,
+}

package/src/utils/{index.js → index.ts}

@@ -1,6 +1,6 @@
-export * from './fakeLocalStorage.js'
-export * from './isomorphic.js'
-export * from './keys.js'
+export * from './fakeLocalStorage'
+export * from './isomorphic'
+export * from './keys'
 
 /**
  * Checks if a value is a primitive type
@@ -8,7 +8,7 @@ export * from './keys.js'
  * @param {*} val Value to check
  * @returns {Boolean} True if value is a primitive type
  */
-export const isPrimitive = (val) => {
+export const isPrimitive = (val: unknown): boolean => {
     const type = typeof val
 
     if (val === null) return true

package/src/utils/{isomorphic.js → isomorphic.ts}

@@ -2,9 +2,9 @@
  * Utilities for handling server-side rendering and client-side hydration
  */
 
-let isClient = false
-let hasHydrated = false
-let hasHydratedStorage = false
+let isClient: boolean = false
+let hasHydrated: boolean = false
+let hasHydratedStorage: boolean = false
 
 // Detect if we're running in a browser environment
 if (typeof window !== 'undefined') {
@@ -21,29 +21,29 @@ if (typeof window !== 'undefined') {
 /**
  * Check if we're running in a browser environment
  */
-export const getIsClient = () => isClient
+export const getIsClient = (): boolean => isClient
 
 /**
  * Check if the client has finished hydrating
  */
-export const getHasHydrated = () => hasHydrated
+export const getHasHydrated = (): boolean => hasHydrated
 
 /**
  * Check if storage has been hydrated (safe to read from real localStorage)
  */
-export const getHasHydratedStorage = () => hasHydratedStorage
+export const getHasHydratedStorage = (): boolean => hasHydratedStorage
 
 /**
  * Mark storage as hydrated (called after upgradeStorage)
  */
-export const markStorageAsHydrated = () => {
+export const markStorageAsHydrated = (): void => {
     hasHydratedStorage = true
 }
 
 /**
  * Check if localStorage is available and safe to use
  */
-export const isLocalStorageAvailable = () => {
+export const isLocalStorageAvailable = (): boolean => {
     if (!isClient) return false
 
     try {

package/src/utils/keys.ts

@@ -0,0 +1,49 @@
+/**
+ * Convenience map of keys
+ */
+const storageKeys: Record<string, string> = {}
+
+/**
+ * Adds a key to the keys map
+ *
+ * @param {String} value Key name
+ */
+export const addKey = (value: string): void => {
+    storageKeys[value] = value
+}
+
+/**
+ * Adds a key to the keys map
+ * (Alias for `addKey`)
+ *
+ * @param {String} value Key name
+ */
+export const key = (value: string) => addKey(value)
+
+/**
+ * Convenience method to get internally managed storage keys
+ *
+ * @returns {Object} InternalStorage keys map
+ */
+export const getKeys = (): Record<string, string> => storageKeys
+
+/**
+ * Helper utility to prefix all keys in a map to use a namespace
+ *
+ * @param {String} namespace InternalStorage namespace prefix
+ * @param {Object} keys (Optional) InternalStorage key/values. Defaults to the internally managed keys map
+ */
+export const getPrefixedKeys = (namespace: string, keys: Record<string, string> | null = null) => {
+    const items = keys || storageKeys
+
+    if (!namespace) return items
+
+    return Object.keys(items).reduce(
+        (acc, it) => {
+            acc[it] = `${namespace}.${items[it]}`
+
+            return acc
+        },
+        {} as Record<string, string>,
+    )
+}

package/src/components/HydrationProvider.js

@@ -1,45 +0,0 @@
-'use client'
-
-import { useEffect, useRef } from 'react'
-import { upgradeStorage } from '../react-wire-persisted.js'
-import { getHasHydrated, getIsClient } from '../utils/index.js'
-
-/**
- * A Next.js App Router compatible component that handles automatic storage upgrade
- * after hydration. Use this in your root layout.
- *
- * @param {Object} props Component props
- * @param {React.ReactNode} props.children Child components to render
- * @param {Function} props.onUpgrade Callback called when storage is upgraded
- * @param {Boolean} props.autoUpgrade Whether to automatically upgrade storage (default: true)
- */
-export function HydrationProvider({ children, onUpgrade, autoUpgrade = true }) {
-    const hasUpgraded = useRef(false)
-
-    useEffect(() => {
-        if (!autoUpgrade || hasUpgraded.current || !getIsClient()) {
-            return
-        }
-
-        const attemptUpgrade = () => {
-            if (getHasHydrated() && !hasUpgraded.current) {
-                const upgraded = upgradeStorage()
-
-                if (upgraded) {
-                    hasUpgraded.current = true
-                    onUpgrade?.()
-                }
-            }
-        }
-
-        // Try to upgrade immediately if already hydrated
-        attemptUpgrade()
-
-        // Also try after a short delay to ensure DOM is ready
-        const timeoutId = setTimeout(attemptUpgrade, 0)
-
-        return () => clearTimeout(timeoutId)
-    }, [autoUpgrade, onUpgrade])
-
-    return children
-}

package/src/components/index.js

@@ -1 +0,0 @@
-export { HydrationProvider } from './HydrationProvider.js'

package/src/providers/MemoryStorageProvider.js

@@ -1,14 +0,0 @@
-import { fakeLocalStorage } from '../utils/index.js'
-import LocalStorageProvider from './LocalStorageProvider.js'
-
-class MemoryStorageProvider extends LocalStorageProvider {
-    constructor(namespace = null, registry = {}) {
-        super(namespace, registry)
-    }
-
-    getStorage() {
-        return fakeLocalStorage
-    }
-}
-
-export default MemoryStorageProvider

package/src/utils/fakeLocalStorage.js

@@ -1,15 +0,0 @@
-const storage = {
-    __IS_FAKE_LOCAL_STORAGE__: true,
-}
-
-export const fakeLocalStorage = {
-    getItem: (key) => storage[key],
-    setItem: (key, value) => {
-        storage[key] = value
-    },
-    removeItem: (key) => {
-        delete storage[key]
-    },
-    // Make Object.keys() work properly for _resetAll method
-    ...storage,
-}

package/src/utils/keys.js

@@ -1,46 +0,0 @@
-/**
- * Convenience map of keys
- */
-const storageKeys = {}
-
-/**
- * Adds a key to the keys map
- *
- * @param {String} value Key name
- */
-export const addKey = (value) => {
-    storageKeys[value] = value
-}
-
-/**
- * Adds a key to the keys map
- * (Alias for `addKey`)
- *
- * @param {String} value Key name
- */
-export const key = (value) => addKey(value)
-
-/**
- * Convenience method to get internally managed storage keys
- *
- * @returns {Object} Storage keys map
- */
-export const getKeys = () => storageKeys
-
-/**
- * Helper utility to prefix all keys in a map to use a namespace
- *
- * @param {String} namespace Storage namespace prefix
- * @param {Object} keys (Optional) Storage key/values. Defaults to the internally managed keys map
- */
-export const getPrefixedKeys = (namespace, keys = null) => {
-    const items = keys || storageKeys
-
-    if (!namespace) return items
-
-    return Object.keys(items).reduce((acc, it) => {
-        acc[it] = `${namespace}.${items[it]}`
-
-        return acc
-    }, {})
-}