@channel-state/core/dist/index.d.ts

Core-library for channel-state, providing framework-agnostic, zero-dependency state management with cross-context synchronization and persistence.

/**
 * Represents the status of the ChannelStore.
 * - 'initializing': The store is initializing.
 * - 'ready': The store is ready to be used.
 * - 'destroyed': The store has been destroyed.
 */
type StoreStatus = 'initializing' | 'ready' | 'destroyed';
/**
 * Callback function type for store status changes.
 */
type StoreStatusCallback = (status: StoreStatus) => void;
/**
 * Callback function type for store changes.
 */
type StoreChangeCallback<T> = (value: T) => void;
/**
 * Options for configuring a ChannelStore instance.
 * @template T The type of the state managed by the store.
 */
interface ChannelStoreOptions<T> {
    /**
     * The name of the channel. This is used for both BroadcastChannel and IndexedDB.
     * @remarks Required.
     */
    name: string;
    /**
     * Whether the store should persist its state to IndexedDB.
     * @remarks Defaults to `false`.
     */
    persist?: boolean;
    /**
     * The initial state of the store.
     * @remarks Required.
     */
    initial: T;
}
/**
 * A class that manages and shares state across different browser tabs or windows
 * using BroadcastChannel and IndexedDB for persistence.
 * @template T The type of the state managed by the store.
 *
 * @property {StoreStatus} status The current status of the store, indicating its readiness and lifecycle phase.
 */
declare class ChannelStore<T> {
    private _db;
    private _subscribers;
    private _statusSubscribers;
    private _value;
    private readonly _name;
    private readonly _persist;
    private readonly _initial;
    private readonly _channel;
    private readonly _dbKey;
    private readonly _prefixedName;
    private _instanceId;
    private _initialStateRequestTimeout;
    /**
     * The current status of the store.
     */
    status: StoreStatus;
    /**
     * Creates an instance of ChannelStore.
     * @param options The options for configuring the store.
     */
    constructor(options: ChannelStoreOptions<T>);
    private _initDB;
    private _loadCacheFromDB;
    private _requestInitialStateFromOtherTabs;
    /**
     * Handles messages received from the BroadcastChannel, updating the cache and notifying subscribers.
     * @param messageEvent The MessageEvent containing the broadcasted data.
     * @private
     */
    private _handleBroadcast;
    /**
     * Notifies all registered subscribers about a change in the store's state.
     * @private
     */
    private _notifySubscribers;
    private _notifyStatusSubscribers;
    /**
     * Triggers a change notification by posting the current cache to the BroadcastChannel
     * and notifying local subscribers.
     * @private
     */
    private _triggerChange;
    /**
     * Synchronously retrieves the current state from the cache.
     * @returns The current state of the store.
     */
    get(): T;
    /**
     * Sets the new value for the store's state, updates the value, and optionally persists it to IndexedDB asynchronously.
     * @param value The new state value to set.
     * @returns A Promise that resolves when the state has been set and persisted (if applicable).
     */
    set(value: T): void;
    /**
     * Subscribes a callback function to state changes.
     * @param callback The function to call when the state changes.
     * @returns A function that can be called to unsubscribe the callback.
     */
    subscribe(callback: StoreChangeCallback<T>): () => void;
    /**
     * Subscribes a callback function to status changes.
     * @param callback The function to call when the status changes.
     * @returns A function that can be called to unsubscribe the callback.
     */
    subscribeStatus(callback: StoreStatusCallback): () => void;
    /**
     * Cleans up resources used by the ChannelStore, including closing the BroadcastChannel
     * and IndexedDB connection, and clearing subscribers.
     */
    destroy(): void;
    /**
     * Resets the store's state to its initial value.
     * @returns A Promise that resolves when the state has been reset.
     */
    reset(): Promise<void>;
}

export { ChannelStore, type ChannelStoreOptions, type StoreStatus, type StoreStatusCallback };