react-wire-persisted 2.0.1 → 3.0.0

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

@@ -1,102 +1,105 @@
-
 /**
  * Base class to allow storage access
- * @see `LocalStorageProvider.js` for an example implementation
+ * @see `LocalStorageProvider.ts` for an example implementation
  */
-class StorageProvider {
-    
+/** biome-ignore-all lint/correctness/noUnusedFunctionParameters: WIP next PR will switch to TypeScript */
+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
         this.registry = registry || /* istanbul ignore next */ {}
-        
     }
-    
+
     /**
      * Sets the namespace for this storage provider, and migrates
      * all stored values to the new namespace
      * @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
     }
-    
+
     /**
      * Reads an item from storage
      * @param {String} key Key for the item to retrieve
      */
     /* istanbul ignore next */
-    getItem(key) {}
-    
+    abstract getItem<T>(key: string): T | null
+
     /**
      * Stores a value
      * @param {String} key Item's storage key
      * @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
      * @param {String} key Item's storage key
      * @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>
+
     /**
-     * 
+     *
      * @param {Boolean} useInitialValues If values should be replaced with their initial values. If false, keys are removed
      * @param {String[]} excludedKeys (Optional) List of keys to exclude
      * @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
      * If a `namespace` is set, only keys prefixed with the namespace will be reset
      * @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.
      * If a `namespace` is set, only keys prefixed with the namespace will be removed
      * @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.ts

@@ -0,0 +1,257 @@
+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: unknown[]) => {
+    if (typeof globalThis !== 'undefined' && globalThis.__RWP_LOGGING_ENABLED__ !== false) {
+        console.log(...args)
+    }
+}
+
+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
+}
+
+rwpLog('[RWP] Module initialized, instance ID:', instanceId)
+
+// Make storage global so all instances share the same storage after upgrade
+rwpLog('[RWP] About to check global storage, instanceId:', instanceId)
+try {
+    if (!globalThis.__RWP_STORAGE__) {
+        rwpLog('[RWP] Creating global storage in instance:', instanceId)
+        globalThis.__RWP_STORAGE__ = new LocalStorageProvider('__internal_rwp_storage__')
+    } else {
+        rwpLog('[RWP] Using existing global storage in instance:', instanceId)
+    }
+    storage = globalThis.__RWP_STORAGE__
+    rwpLog('[RWP] InternalStorage assigned successfully')
+} catch (error) {
+    if (globalThis.__RWP_LOGGING_ENABLED__) console.error('[RWP] Error setting up global storage:', error)
+    storage = new LocalStorageProvider('__internal_rwp_storage__')
+}
+
+// Use a global registry to handle multiple module instances
+// This ensures all instances share the same wire registry
+if (typeof globalThis !== 'undefined') {
+    if (!globalThis.__RWP_REGISTERED_WIRES__) {
+        rwpLog('[RWP] Creating global registeredWires in instance:', instanceId)
+        globalThis.__RWP_REGISTERED_WIRES__ = new Map()
+    } else {
+        rwpLog('[RWP] Using existing global registeredWires in instance:', instanceId)
+    }
+}
+
+// Registry to track wire instances for hydration refresh
+const registeredWires = globalThis.__RWP_REGISTERED_WIRES__ || new Map<string, WireLikeObject>()
+rwpLog('[RWP] registeredWires Map reference in instance:', instanceId, 'size:', registeredWires.size)
+
+export const getNamespace = (): string | null => storage.namespace
+
+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: 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 LocalStorageProvider(currentNamespace)
+    rwpLog(`[RWP] setNamespace() done, registered wires after:`, registeredWires.size)
+}
+
+export const getOptions = (): RWPOptions => options
+
+export const setOptions = (value: Partial<RWPOptions>) => {
+    options = {
+        ...options,
+        ...value,
+    }
+    // Update global logging flag
+    if (typeof globalThis !== 'undefined') {
+        globalThis.__RWP_LOGGING_ENABLED__ = options.logging.enabled
+    }
+    /* istanbul ignore next */
+    if (options.logging.enabled) {
+        console.info('Flushing', pendingLogs.length, 'pending logs')
+        while (pendingLogs.length)
+            /* istanbul ignore next */
+            console.log(...(pendingLogs.shift() || []))
+    }
+}
+
+/**
+ * Refresh all registered wires by reading from storage
+ * Called after storage upgrade to sync wires with persisted values
+ */
+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: Wire<unknown> | WireLikeObject, key: string) => {
+        const storedValue = storage.getItem(key)
+        const currentValue = wire.getValue()
+
+        rwpLog('[RWP] Checking wire', key, {
+            storedValue,
+            currentValue,
+            willUpdate: storedValue !== null && storedValue !== currentValue,
+        })
+
+        log('react-wire-persisted: Checking wire', key, {
+            storedValue,
+            currentValue,
+            willUpdate: storedValue !== null && storedValue !== currentValue,
+        })
+
+        if (storedValue !== null && storedValue !== currentValue) {
+            rwpLog('[RWP] Refreshing wire', key, 'with stored value', storedValue)
+            log('react-wire-persisted: Refreshing wire', key, 'with stored value', storedValue)
+            wire.setValue(storedValue)
+        }
+    })
+}
+
+/**
+ * Attempts to upgrade the storage provider from fake storage to real localStorage
+ * This should be called on the client side after hydration
+ *
+ * @returns true if upgrade was successful
+ */
+export const upgradeStorage = (): boolean => {
+    rwpLog('[RWP] upgradeStorage() called in instance:', instanceId, {
+        isClient: getIsClient(),
+        isUsingFakeStorage: storage.isUsingFakeStorage(),
+    })
+
+    log('react-wire-persisted: upgradeStorage() called', {
+        isClient: getIsClient(),
+        isUsingFakeStorage: storage.isUsingFakeStorage(),
+    })
+
+    if (!getIsClient()) return false
+
+    const upgraded = storage.upgradeToRealStorage()
+
+    rwpLog('[RWP] upgradeToRealStorage() returned', upgraded)
+    log('react-wire-persisted: upgradeToRealStorage() returned', upgraded)
+
+    if (upgraded) {
+        markStorageAsHydrated()
+        rwpLog('[RWP] Upgraded to real localStorage, calling refreshAllWires()')
+        log('react-wire-persisted: Upgraded to real localStorage after hydration')
+
+        // Refresh all wires with stored values
+        refreshAllWires()
+    }
+
+    return upgraded
+}
+
+const log = (...args: unknown[]) => {
+    /* istanbul ignore next */
+    if (options.logging.enabled)
+        /* istanbul ignore next */
+        console.log(...args)
+    else pendingLogs.push(args)
+}
+
+/**
+ * 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 = <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) 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<T>(value)
+
+    const getValue = () => wire.getValue()
+
+    const setValue = (newValue: Defined<T>) => {
+        rwpLog(
+            '[RWP] setValue called in instance:',
+            instanceId,
+            'key:',
+            key,
+            'isUsingFakeStorage:',
+            storage.isUsingFakeStorage(),
+        )
+        storage.setItem(key, newValue)
+        return wire.setValue(newValue)
+    }
+
+    const subscribe = (callback: (value: Defined<T>) => void) => {
+        return wire.subscribe(callback)
+    }
+
+    // Always start with default value to ensure SSR consistency
+    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<T>(key)
+
+        if (storedValue !== null) initialValue = storedValue
+    }
+
+    log('react-wire-persisted: create', key, {
+        value,
+        initialValue,
+        hasHydratedStorage: getHasHydratedStorage(),
+        isUsingFakeStorage: storage.isUsingFakeStorage(),
+        canReadStorage,
+    })
+
+    if (initialValue !== value && initialValue !== undefined) setValue(initialValue as Defined<T>)
+
+    // Register wire for post-hydration refresh
+    registeredWires.set(key, {
+        getValue,
+        setValue,
+        subscribe,
+    })
+
+    rwpLog('[RWP] Wire registered, total wires:', registeredWires.size, 'keys:', Array.from(registeredWires.keys()))
+
+    return {
+        ...wire,
+        getValue,
+        setValue,
+        subscribe,
+    }
+}

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,21 +1,19 @@
-export * from './keys'
 export * from './fakeLocalStorage'
 export * from './isomorphic'
+export * from './keys'
 
 /**
  * Checks if a value is a primitive type
- * 
+ *
  * @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
     if (Array.isArray(val)) return false
     if (type === 'object') return false
-    
+
     return type !== 'function'
-    
 }

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

@@ -2,45 +2,58 @@
  * Utilities for handling server-side rendering and client-side hydration
  */
 
-let isClient = false
-let hasHydrated = 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') {
     isClient = true
 
     // Mark as hydrated when the DOM is ready
-    if (document.readyState === 'loading') {
+    if (document.readyState === 'loading')
         document.addEventListener('DOMContentLoaded', () => {
             hasHydrated = true
         })
-    } else {
-        hasHydrated = true
-    }
+    else hasHydrated = true
 }
 
 /**
  * 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 = (): boolean => hasHydratedStorage
+
+/**
+ * Mark storage as hydrated (called after upgradeStorage)
+ */
+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 {
         const testKey = '__rwp_test__'
+
         window.localStorage.setItem(testKey, 'test')
         window.localStorage.removeItem(testKey)
+
         return true
-    } catch (e) {
+    } catch (_) {
         return false
     }
-}
+}

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'
-import { getIsClient, getHasHydrated } from '../utils'
-
-/**
- * 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/index.js

@@ -1,6 +0,0 @@
-import * as utils from './utils'
-
-export { utils }
-export * from './react-wire-persisted'
-export * from './hooks/useHydration'
-export * from './components'