react-wire-persisted 2.1.0 → 3.1.0

package/README.md

@@ -5,23 +5,13 @@
 ## Install
 
 ```shell
-$ pnpm add -D @forminator/react-wire react-wire-persisted
-```
-
-## Building
-
-```shell
-$ pnpm build
-$ npm version patch # patch, minor, major
-$ git push
-$ git push --tags
-$ npm publish
+$ pnpm add @forminator/react-wire react-wire-persisted
 ```
 
 ## Usage
 
-```javascript
-// constants.js
+```typescript
+// constants.ts
 import { key, getPrefixedKeys } from 'react-wire-persisted/lib/utils'
 
 export const NS = 'myapp'
@@ -33,36 +23,48 @@ const prefixedKeys = getPrefixedKeys(NS)
 export { prefixedKeys as keys }
 ```
 
-```javascript
-// index.js
+```tsx
+// index.tsx
 import { NS } from './constants'
-import * as reactWirePersisted from 'react-wire-persisted'
+import * as rwp from 'react-wire-persisted'
+
+rwp.setNamespace(NS)
 
-reactWirePersisted.setNamespace(NS)
+rwp.setOptions({
+    logging: {
+        enabled: true,
+    },
+    storageProvider: rwp.MemoryStorageProvider,
+})
 
 // Normal React init code
 ```
 
-```javascript
-// store.js
+```typescript
+// store.ts
 import { createPersistedWire } from 'react-wire-persisted'
 import { keys } from './constants'
 
-export const foo = createPersistedWire(keys.foo, null)
+type User = {
+    id: number
+    email: string
+}
+
+export const user = createPersistedWire<User | null>(keys.foo, null)
 ```
 
-```javascript
-// SomeComponent.js
+```tsx
+// SomeComponent.tsx
 import { useWireState } from '@forminator/react-wire'
 import * as store from './store'
 
 const SomeComponent = () => {
-    const [foo, setFoo] = useWireState(store.foo)
+    const [user, setUser] = useWireState(store.user)
     return (
         <div>
-            <p>Foo: {foo}</p>
-            <button onClick={() => setFoo('bar')}>
-                CHANGE FOO
+            <p>User: {user?.email}</p>
+            <button onClick={() => setUser({ ...user, email: 'example@gmail.com'})}>
+                Change Email
             </button>
         </div>
     )
@@ -75,9 +77,100 @@ See the [demo](demo) folder for a more complete example.
 
 ## Storage Providers
 
-This library uses `localStorage`, and will only work in browser environments.
+By default, this library uses `localStorage` via `LocalStorageProvider` in browser environments. However, you can customize the storage behavior using `setOptions`:
+
+```typescript
+import { setOptions, createPersistedWire } from 'react-wire-persisted'
+import { MemoryStorageProvider } from 'react-wire-persisted'
+
+// Use in-memory storage (useful for testing or SSR)
+setOptions({
+    storageProvider: MemoryStorageProvider,
+})
+```
+
+This is useful for:
+- **Testing**: Avoid localStorage in unit tests
+- **SSR**: Use in-memory storage during server-side rendering
+- **Custom storage**: Implement your own provider by extending `RWPStorageProvider`
+
+See [LocalStorageProvider](src/providers/LocalStorageProvider.ts) and [MemoryStorageProvider](src/providers/MemoryStorageProvider.ts) for implementation examples.
+
+## API
+
+### `createPersistedWire<T = null>(key: string, value?: T): PersistedWire<T>`
+
+Creates a persisted Wire that automatically syncs with the configured storage provider.
+
+### `setNamespace(namespace: string): void`
+
+Sets the namespace for storage keys. This prefixes all keys to avoid collisions.
+
+### `setOptions(options: Partial<RWPOptions>): void`
+
+Configure library options:
+- `logging.enabled`: Enable/disable logging (default: `false`)
+- `storageProvider`: Custom storage provider class
+
+### `getOptions(): RWPOptions`
+
+Get current options.
 
-See [LocalStorageProvider](src/LocalStorageProvider.js) for implementation.
+### `getNamespace(): string | null`
+
+Get current namespace.
+
+### `getStorage(): RWPStorageProvider`
+
+Get the current storage provider instance.
+
+### `upgradeStorage(): boolean`
+
+Attempts to upgrade from fake storage (used during SSR) to real localStorage. Returns `true` if upgrade was successful. Call this after hydration in client-side code.
+
+## Building
+
+```shell
+$ pnpm build
+```
+
+## Contributing
+
+Contributions are welcome. Please feel free to submit a [GitHub Issue](https://github.com/forminator/react-wire-persisted/issues) or pull request.
+
+### Development
+
+```shell
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Run linter
+pnpm lint
+```
+
+## Publishing
+
+To publish a new version to npm:
+
+```shell
+# Build the project
+pnpm build
+
+# Bump version (choose one)
+npm version patch  # bug fixes (e.g., 2.1.0 -> 2.1.1)
+npm version minor  # new features (e.g., 2.1.0 -> 2.2.0)
+npm version major  # breaking changes (e.g., 2.1.0 -> 3.0.0)
+
+# Push changes and tags
+git push
+git push --tags
+
+# Publish to npm
+npm publish
+```
 
 ## Miscellaneous
 

package/dist/index.d.ts

@@ -0,0 +1,276 @@
+import { ReactNode } from 'react';
+import { Wire } from '@forminator/react-wire';
+
+/**
+ * Adds a key to the keys map
+ *
+ * @param {String} value Key name
+ */
+declare const addKey: (value: string) => void;
+
+declare type AnyStorage = InternalStorage | Storage;
+
+/**
+ * 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 declare const createPersistedWire: <T = null>(key: string, value?: T) => PersistedWire<T>;
+
+export declare const defaultOptions: RWPOptions;
+
+declare const fakeLocalStorage: InternalStorage;
+
+/**
+ * Check if the client has finished hydrating
+ */
+declare const getHasHydrated: () => boolean;
+
+/**
+ * Check if storage has been hydrated (safe to read from real localStorage)
+ */
+declare const getHasHydratedStorage: () => boolean;
+
+/**
+ * Check if we're running in a browser environment
+ */
+declare const getIsClient: () => boolean;
+
+/**
+ * Convenience method to get internally managed storage keys
+ *
+ * @returns {Object} InternalStorage keys map
+ */
+declare const getKeys: () => Record<string, string>;
+
+export declare const getNamespace: () => string | null;
+
+export declare const getOptions: () => RWPOptions;
+
+/**
+ * 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
+ */
+declare const getPrefixedKeys: (namespace: string, keys?: Record<string, string> | null) => Record<string, string>;
+
+export declare const getStorage: () => RWPStorageProvider;
+
+export declare const HydrationProvider: ({ children, onUpgrade, autoUpgrade }: HydrationProviderProps) => ReactNode;
+
+/**
+ * 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)
+ */
+declare type HydrationProviderProps = {
+    children: ReactNode;
+    onUpgrade?: () => void;
+    autoUpgrade?: boolean;
+};
+
+declare interface InternalStorage {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+}
+
+/**
+ * Check if localStorage is available and safe to use
+ */
+declare const isLocalStorageAvailable: () => boolean;
+
+/**
+ * Checks if a value is a primitive type
+ *
+ * @param {*} val Value to check
+ * @returns {Boolean} True if value is a primitive type
+ */
+declare const isPrimitive: (val: unknown) => boolean;
+
+/**
+ * Adds a key to the keys map
+ * (Alias for `addKey`)
+ *
+ * @param {String} value Key name
+ */
+declare const key: (value: string) => void;
+
+/**
+ * A storage provider for `localStorage`
+ * @see `RWPStorageProvider.ts` for documentation
+ */
+export declare class LocalStorageProvider extends RWPStorageProvider {
+    storage: AnyStorage;
+    private _isUsingFakeStorage;
+    constructor(namespace: string, registry?: Record<string, unknown>);
+    getStorage(): AnyStorage;
+    setNamespace(namespace: string): void;
+    getItem(key: string): any;
+    setItem(key: string, value: unknown): void;
+    removeItem(key: string, fromRegistry?: boolean): void;
+    getAll(): Record<string, unknown>;
+    _resetAll(useInitialValues?: boolean, excludedKeys?: string[], clearRegistry?: boolean): void;
+    resetAll(excludedKeys?: string[], clearRegistry?: boolean): void;
+    removeAll(excludedKeys?: string[], clearRegistry?: boolean): void;
+    /**
+     * Attempt to upgrade from fake storage to real localStorage
+     * This is useful for hydration scenarios
+     */
+    upgradeToRealStorage(): boolean;
+    /**
+     * Check if currently using fake storage
+     */
+    isUsingFakeStorage(): boolean;
+}
+
+/**
+ * Mark storage as hydrated (called after upgradeStorage)
+ */
+declare const markStorageAsHydrated: () => void;
+
+export declare class MemoryStorageProvider extends LocalStorageProvider {
+    constructor(namespace: string, registry?: Record<string, unknown>);
+    getStorage(): InternalStorage;
+}
+
+declare type PersistedWire<T> = Wire<T>;
+
+declare type RWPOptions = {
+    logging: {
+        enabled: boolean;
+    };
+    storageProvider?: typeof RWPStorageProvider;
+};
+
+/**
+ * Base class to allow storage access
+ * @see `LocalStorageProvider.ts` for an example implementation
+ */
+/** biome-ignore-all lint/correctness/noUnusedFunctionParameters: WIP next PR will switch to TypeScript */
+export declare 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 and reset functions
+     * @param {Object} registry (Optional) Initialize the storage provider with an existing registry
+     */
+    protected constructor(namespace: string, registry: Record<string, unknown>);
+    /**
+     * 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
+     */
+    abstract setNamespace(namespace: string | null): void;
+    /**
+     * 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<T>(key: string, initialValue: T | null): void;
+    /**
+     * Reads an item from storage
+     * @param {String} key Key for the item to retrieve
+     */
+    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
+     */
+    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
+     */
+    abstract removeItem(key: string, fromRegistry: boolean): void;
+    /**
+     * Gets all stored keys and values
+     * If a `namespace` was set, only keys prefixed with the namespace will be returned
+     */
+    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
+     */
+    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
+     */
+    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
+     */
+    abstract removeAll(excludedKeys: string[]): void;
+    upgradeToRealStorage(): boolean;
+    isUsingFakeStorage(): boolean;
+}
+
+/**
+ * Sets the namespace for the storage provider
+ *
+ * @param {String} namespace The namespace for the storage provider
+ */
+export declare const setNamespace: (namespace: string) => void;
+
+export declare const setOptions: (value: Partial<RWPOptions>) => void;
+
+/**
+ * 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 declare const upgradeStorage: () => boolean;
+
+/**
+ * React hook that handles automatic storage upgrade after hydration
+ * This should be used in the root component of your application
+ *
+ * @param {Object} options Configuration options
+ * @param {Boolean} options.autoUpgrade Whether to automatically upgrade storage (default: true)
+ * @param {Function} options.onUpgrade Callback called when storage is upgraded
+ */
+export declare const useHydration: (options?: UseHydrationOptions) => {
+    hasUpgraded: boolean;
+};
+
+export declare type UseHydrationOptions = {
+    autoUpgrade?: boolean;
+    onUpgrade?: () => void;
+};
+
+declare namespace utils {
+    export {
+        isPrimitive,
+        fakeLocalStorage,
+        getIsClient,
+        getHasHydrated,
+        getHasHydratedStorage,
+        markStorageAsHydrated,
+        isLocalStorageAvailable,
+        addKey,
+        key,
+        getKeys,
+        getPrefixedKeys
+    }
+}
+export { utils }
+
+export { }