@storesjs/stores 0.10.0 → 0.12.0

package/dist/plugins/chrome/index.d.ts

@@ -1,4 +1,186 @@
-export { ChromeExtensionSyncEngine, ChromeExtensionSyncEngineOptions } from './chromeExtensionSyncEngine';
-export { AreaName, ChromeStorageAdapter, ChromeStorageAdapterOptions } from './chromeStorageAdapter';
-export { createSyncedChromeStorage } from './createSyncedChromeStorage';
-//# sourceMappingURL=index.d.ts.map
+//#region src/types/functions.d.ts
+/**
+* Unknown generic function type.
+*/
+type UnknownFunction = (...args: never[]) => unknown;
+//#endregion
+//#region src/sync/types.d.ts
+type SyncStateKey<T extends Record<string, unknown>> = Extract<{ [K in keyof T]-?: T[K] extends UnknownFunction ? never : K }[keyof T], string>;
+type SyncValues<T extends Record<string, unknown>> = Partial<T> & { [K in SyncStateKey<T>]?: T[K] };
+type SyncUpdate<T extends Record<string, unknown>> = {
+  replace: boolean;
+  sessionId: string;
+  timestamp: number;
+  values: SyncValues<T>;
+};
+/**
+* Passed to `SyncEngine.register()` to connect a store to the sync system.
+*/
+type SyncRegistration<T extends Record<string, unknown>> = {
+  /** Callback invoked by the engine to apply incoming remote updates to the store. */apply: (update: SyncUpdate<T>) => void; /** The state keys to sync. Non-function properties only. */
+  fields: ReadonlyArray<SyncStateKey<T>>; /** Returns the store's current state. Used by engines that need to read state (e.g., for diffing). */
+  getState: () => T; /** Unique identifier for this store. Must match across clients to sync the same data. */
+  key: string;
+};
+/**
+* Returned by `SyncEngine.register()`. Controls the lifecycle of a synced store.
+*/
+interface SyncHandle<T extends Record<string, unknown>> {
+  /**
+  * Permanently removes this store from the sync engine. After calling, the handle
+  * is invalid and the store will no longer send or receive updates. To temporarily
+  * pause sync, use `onFirstSubscribe`/`onLastUnsubscribe` lifecycle hooks instead.
+  */
+  destroy: () => void;
+  /** Returns `true` once the store has received its initial state from the engine. */
+  hydrated?: () => boolean;
+  /**
+  * Called when the store's subscriber count goes from 0 to 1. The registration
+  * remains active. Use for lazy resource acquisition (e.g., opening a WebSocket).
+  */
+  onFirstSubscribe?: () => void;
+  /** Registers a one-time callback to run when hydration completes. */
+  onHydrated?: (callback: () => void) => void;
+  /**
+  * Called when the store's subscriber count drops to 0. The registration remains
+  * active and `onFirstSubscribe` will fire again on the next subscription.
+  * Use for resource cleanup (e.g., closing idle connections).
+  */
+  onLastUnsubscribe?: () => void;
+  /**
+  * Broadcasts a state update to other clients. Set to `null` for engines where
+  * publishing is implicit (e.g., `chrome.storage` where the write itself triggers sync).
+  */
+  publish: ((update: SyncUpdate<T>) => void) | null;
+}
+/**
+* Interface for multi-client state synchronization. Stores register to send and receive updates.
+*/
+interface SyncEngine {
+  /**
+  * When `true`, embeds sync metadata (`{ origin, timestamp, fields }`) into persisted
+  * storage values. Required for engines that use storage writes as their transport.
+  * Only effective when the store is also persisted.
+  * @default false
+  */
+  readonly injectStorageMetadata?: boolean;
+  /** Registers a store for synchronization. Returns a handle to control the sync lifecycle. */
+  register: {
+    <T extends Record<string, unknown>>(registration: SyncRegistration<T>): SyncHandle<T>;
+    (registration: SyncRegistration<Record<string, unknown>>): SyncHandle<Record<string, unknown>>;
+  };
+  /** Unique identifier for this client session. Used for conflict resolution and filtering self-updates. */
+  readonly sessionId: string;
+}
+//#endregion
+//#region src/storage/storageTypes.d.ts
+type StorageValue<S, HideSyncMetadata extends boolean = false> = HideSyncMetadata extends true ? {
+  state: S;
+  version?: number;
+} : {
+  state: S;
+  syncMetadata?: {
+    origin?: string;
+    timestamp?: number;
+    fields?: Record<string, number>;
+  };
+  version?: number;
+};
+//#endregion
+//#region src/types.d.ts
+/**
+* Asynchronous storage interface.
+* Used for Chrome storage and other async storage implementations.
+*/
+type AsyncStorageInterface<SerializedState = unknown> = {
+  readonly async: true;
+  /**
+  * Adapter-level deserializer used when a store does not supply its own.
+  * Acts as the default before falling back to the framework implementation.
+  */
+  deserializer?<PersistedState>(serializedState: SerializedState): StorageValue<PersistedState>;
+  /**
+  * Adapter-level serializer used when a store does not supply its own.
+  * Acts as the default before falling back to the framework implementation.
+  */
+  serializer?<PersistedState>(storageValue: StorageValue<PersistedState>): SerializedState;
+  clearAll(): Promise<void>;
+  contains(key: string): Promise<boolean>;
+  delete(key: string): Promise<void>;
+  get(key: string): Promise<SerializedState | undefined>;
+  getAllKeys(): Promise<string[]>;
+  set(key: string, value: SerializedState): Promise<void>;
+};
+//#endregion
+//#region src/plugins/chrome/chromeStorageAdapter.d.ts
+type AreaName = keyof Pick<typeof chrome.storage, "local" | "managed" | "session" | "sync">;
+type ChromeStorageAdapterOptions = {
+  area?: AreaName;
+  storageKeyPrefix?: string;
+};
+declare class ChromeStorageAdapter implements AsyncStorageInterface {
+  readonly area: AreaName;
+  readonly storageKeyPrefix: string;
+  readonly async = true;
+  readonly deserializer: typeof deserializeChromeStorageValue;
+  readonly serializer: typeof serializeChromeStorageValue;
+  constructor(options?: ChromeStorageAdapterOptions);
+  clearAll(): Promise<void>;
+  contains(key: string): Promise<boolean>;
+  delete(key: string): Promise<void>;
+  getAllKeys(): Promise<string[]>;
+  get(key: string): Promise<unknown>;
+  set(key: string, value: unknown): Promise<void>;
+  private ensureStorage;
+  private toStorageKey;
+  private listPrefixedKeys;
+  private getFromStorage;
+  private execute;
+  private invokeWithCallbackSupport;
+}
+declare function serializeChromeStorageValue<PersistedState>(storageValue: StorageValue<PersistedState>): unknown;
+declare function deserializeChromeStorageValue<PersistedState>(serializedState: unknown): StorageValue<PersistedState>;
+//#endregion
+//#region src/plugins/chrome/chromeExtensionSyncEngine.d.ts
+type ChromeExtensionSyncEngineOptions = ChromeStorageAdapterOptions | {
+  storage: ChromeStorageAdapter;
+};
+declare class ChromeExtensionSyncEngine implements SyncEngine {
+  readonly injectStorageMetadata = true;
+  readonly sessionId: string;
+  private readonly area;
+  private readonly storageKeyPrefix;
+  private readonly registrations;
+  private isListening;
+  constructor(options?: ChromeExtensionSyncEngineOptions);
+  destroy(): void;
+  register<T extends Record<string, unknown>>(registration: SyncRegistration<T>): SyncHandle<T>;
+  private generateSessionId;
+  private attachListener;
+  private detachListener;
+  private onStorageChanged;
+  /**
+  * Extracts which fields changed in this update.
+  * Prefers field-level metadata when available, falls back to full state diff.
+  * Does NOT perform conflict resolution - that's handled by syncEnhancer.processUpdate.
+  */
+  private extractChangedFields;
+  private setRegistration;
+  private toStorageKey;
+  private parsePersistValue;
+}
+//#endregion
+//#region src/plugins/chrome/createSyncedChromeStorage.d.ts
+/**
+* Creates a synced Chrome storage engine for extension environments.
+* @returns
+* ```ts
+* { engine: ChromeExtensionSyncEngine; storage: ChromeStorageAdapter }
+* ```
+*/
+declare function createSyncedChromeStorage(options?: ChromeStorageAdapterOptions): {
+  storage: ChromeStorageAdapter;
+  syncEngine: ChromeExtensionSyncEngine;
+};
+//#endregion
+export { type AreaName, ChromeExtensionSyncEngine, type ChromeExtensionSyncEngineOptions, ChromeStorageAdapter, type ChromeStorageAdapterOptions, createSyncedChromeStorage };

package/dist/vanilla/index.js

@@ -1 +1 @@
-var e=require("../web/internal/runtime.js");function t(e,t,r,n){return e}Object.defineProperty(exports,"QueryStatuses",{enumerable:!0,get:function(){return e.QueryStatuses}}),Object.defineProperty(exports,"StoresError",{enumerable:!0,get:function(){return e.StoresError}}),Object.defineProperty(exports,"applyStateUpdate",{enumerable:!0,get:function(){return e.applyStateUpdate}}),Object.defineProperty(exports,"configureStores",{enumerable:!0,get:function(){return e.configureStores}}),Object.defineProperty(exports,"createStoreActions",{enumerable:!0,get:function(){return e.createStoreActions}}),Object.defineProperty(exports,"deepEqual",{enumerable:!0,get:function(){return e.deepEqual}}),Object.defineProperty(exports,"defaultRetryDelay",{enumerable:!0,get:function(){return e.defaultRetryDelay}}),Object.defineProperty(exports,"destroyStore",{enumerable:!0,get:function(){return e.destroyStore}}),Object.defineProperty(exports,"destroyStores",{enumerable:!0,get:function(){return e.destroyStores}}),Object.defineProperty(exports,"getStoreName",{enumerable:!0,get:function(){return e.getStoreName}}),Object.defineProperty(exports,"hasGetSnapshot",{enumerable:!0,get:function(){return e.hasGetSnapshot}}),Object.defineProperty(exports,"identity",{enumerable:!0,get:function(){return e.identity}}),Object.defineProperty(exports,"isDerivedStore",{enumerable:!0,get:function(){return e.isDerivedStore}}),Object.defineProperty(exports,"isPersistedStore",{enumerable:!0,get:function(){return e.isPersistedStore}}),Object.defineProperty(exports,"isQueryStore",{enumerable:!0,get:function(){return e.isQueryStore}}),Object.defineProperty(exports,"isVirtualStore",{enumerable:!0,get:function(){return e.isVirtualStore}}),Object.defineProperty(exports,"nullObject",{enumerable:!0,get:function(){return e.nullObject}}),Object.defineProperty(exports,"replacer",{enumerable:!0,get:function(){return e.replacer}}),Object.defineProperty(exports,"reviver",{enumerable:!0,get:function(){return e.reviver}}),Object.defineProperty(exports,"shallowEqual",{enumerable:!0,get:function(){return e.shallowEqual}}),Object.defineProperty(exports,"time",{enumerable:!0,get:function(){return e.time}}),exports.createBaseStore=function(r,n){const o=e.baseStore(r,n);return t(o,o.getState,o.getInitialState)},exports.createDerivedStore=function(r,n=Object.is){const o=e.derivedStore(r,n);return t(o,o.getSnapshot)},exports.createQueryStore=function(r,n,o){const u=e.queryStore(r,n,o);return t(u,u.getState,u.getInitialState)},exports.createVirtualStore=function(r,n,o){const u=e.virtualStore(r,n,o);return t(u,u.getState,u.getInitialState)},exports.getQueryKey=function(t){return e.getQueryKey(t)},exports.parseQueryKey=function(t){return e.parseQueryKey(t)};
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("../web/internal/runtime.js");function t(e,t,n,r){return e}function n(n,r){let i=(0,e.baseStore)(n,r);return t(i,i.getState,i.getInitialState)}function r(n,r=Object.is){let i=(0,e.derivedStore)(n,r);return t(i,i.getSnapshot,void 0)}function i(e){if(typeof e!=`object`||!e)return!1;let t=Object.getPrototypeOf(e);return t===null||t===Object.prototype}process.env.NODE_ENV,process.env.NODE_ENV;const a=Object.freeze(Object.create(null));function o(){return Object.create(a)}function s(e){return JSON.stringify(l(e))}function c(e){return JSON.parse(e)}function l(e){return typeof e!=`object`||!e?e:Object.keys(e).sort().reduce((t,n)=>{let r=e[n];return t[n]=i(r)?l(r):r,t},o())}const u=Symbol(`stores.queryParamConfig`);function d(e,t){return{[u]:!0,key:t.key,value:e}}function f(n,r,i){let a=(0,e.queryStore)(n,r,i);return t(a,a.getState,a.getInitialState)}function p(n,r,i){let a=(0,e.virtualStore)(n,r,i);return t(a,a.getState,a.getInitialState)}Object.defineProperty(exports,"QueryStatuses",{enumerable:!0,get:function(){return e.QueryStatuses}}),Object.defineProperty(exports,"StoresError",{enumerable:!0,get:function(){return e.StoresError}}),Object.defineProperty(exports,"applyStateUpdate",{enumerable:!0,get:function(){return e.applyStateUpdate}}),Object.defineProperty(exports,"configureStores",{enumerable:!0,get:function(){return e.configureStores}}),exports.createBaseStore=n,exports.createDerivedStore=r,exports.createQueryStore=f,Object.defineProperty(exports,"createStoreActions",{enumerable:!0,get:function(){return e.createStoreActions}}),exports.createVirtualStore=p,Object.defineProperty(exports,"deepEqual",{enumerable:!0,get:function(){return e.deepEqual}}),exports.defaultRetryDelay=e.defaultRetryDelay,Object.defineProperty(exports,"destroyStore",{enumerable:!0,get:function(){return e.destroyStore}}),Object.defineProperty(exports,"destroyStores",{enumerable:!0,get:function(){return e.destroyStores}}),exports.getQueryKey=s,Object.defineProperty(exports,"getStoreName",{enumerable:!0,get:function(){return e.getStoreName}}),Object.defineProperty(exports,"hasGetSnapshot",{enumerable:!0,get:function(){return e.hasGetSnapshot}}),Object.defineProperty(exports,"identity",{enumerable:!0,get:function(){return e.identity}}),Object.defineProperty(exports,"isDerivedStore",{enumerable:!0,get:function(){return e.isDerivedStore}}),Object.defineProperty(exports,"isPersistedStore",{enumerable:!0,get:function(){return e.isPersistedStore}}),Object.defineProperty(exports,"isQueryStore",{enumerable:!0,get:function(){return e.isQueryStore}}),Object.defineProperty(exports,"isVirtualStore",{enumerable:!0,get:function(){return e.isVirtualStore}}),Object.defineProperty(exports,"nullObject",{enumerable:!0,get:function(){return e.nullObject}}),exports.parseQueryKey=c,exports.queryParam=d,Object.defineProperty(exports,"replacer",{enumerable:!0,get:function(){return e.replacer}}),Object.defineProperty(exports,"reviver",{enumerable:!0,get:function(){return e.reviver}}),Object.defineProperty(exports,"shallowEqual",{enumerable:!0,get:function(){return e.shallowEqual}}),Object.defineProperty(exports,"time",{enumerable:!0,get:function(){return e.time}});

package/dist/vanilla/index.mjs

@@ -1 +1 @@
-import{baseStore as t,derivedStore as e,queryStore as r,getQueryKey as n,parseQueryKey as o,virtualStore as i}from"../web/internal/runtime.mjs";export{QueryStatuses,StoresError,applyStateUpdate,configureStores,createStoreActions,deepEqual,defaultRetryDelay,destroyStore,destroyStores,getStoreName,hasGetSnapshot,identity,isDerivedStore,isPersistedStore,isQueryStore,isVirtualStore,nullObject,replacer,reviver,shallowEqual,time}from"../web/internal/runtime.mjs";function a(t,e,r,n){return t}function s(e,r){const n=t(e,r);return a(n,n.getState,n.getInitialState)}function u(t,r=Object.is){const n=e(t,r);return a(n,n.getSnapshot)}function S(t,e,n){const o=r(t,e,n);return a(o,o.getState,o.getInitialState)}function c(t){return n(t)}function l(t){return o(t)}function y(t,e,r){const n=i(t,e,r);return a(n,n.getState,n.getInitialState)}export{s as createBaseStore,u as createDerivedStore,S as createQueryStore,y as createVirtualStore,c as getQueryKey,l as parseQueryKey};
+import{QueryStatuses as e,StoresError as t,applyStateUpdate as n,baseStore as r,configureStores as i,createStoreActions as a,deepEqual as o,defaultRetryDelay as s,derivedStore as c,destroyStore as l,destroyStores as u,getStoreName as d,hasGetSnapshot as f,identity as p,isDerivedStore as m,isPersistedStore as h,isQueryStore as g,isVirtualStore as _,nullObject as v,queryStore as y,replacer as b,reviver as x,shallowEqual as S,time as C,virtualStore as w}from"../web/internal/runtime.mjs";function T(e,t,n,r){return e}function E(e,t){let n=r(e,t);return T(n,n.getState,n.getInitialState)}function D(e,t=Object.is){let n=c(e,t);return T(n,n.getSnapshot,void 0)}function O(e){if(typeof e!=`object`||!e)return!1;let t=Object.getPrototypeOf(e);return t===null||t===Object.prototype}process.env.NODE_ENV,process.env.NODE_ENV;const k=Object.freeze(Object.create(null));function A(){return Object.create(k)}function j(e){return JSON.stringify(N(e))}function M(e){return JSON.parse(e)}function N(e){return typeof e!=`object`||!e?e:Object.keys(e).sort().reduce((t,n)=>{let r=e[n];return t[n]=O(r)?N(r):r,t},A())}const P=Symbol(`stores.queryParamConfig`);function F(e,t){return{[P]:!0,key:t.key,value:e}}function I(e,t,n){let r=y(e,t,n);return T(r,r.getState,r.getInitialState)}function L(e,t,n){let r=w(e,t,n);return T(r,r.getState,r.getInitialState)}export{e as QueryStatuses,t as StoresError,n as applyStateUpdate,i as configureStores,E as createBaseStore,D as createDerivedStore,I as createQueryStore,a as createStoreActions,L as createVirtualStore,o as deepEqual,s as defaultRetryDelay,l as destroyStore,u as destroyStores,j as getQueryKey,d as getStoreName,f as hasGetSnapshot,p as identity,m as isDerivedStore,h as isPersistedStore,g as isQueryStore,_ as isVirtualStore,v as nullObject,M as parseQueryKey,F as queryParam,b as replacer,x as reviver,S as shallowEqual,C as time};