@warp-drive-mirror/experiments 0.2.8 → 5.9.1

package/dist/storage.d.ts

@@ -0,0 +1,354 @@
+//#region src/storage/cache.d.ts
+declare const DEFAULT_CACHE_ID = "reactive-cache";
+interface InternalCacheStorageEvent {
+  storageArea: string;
+  key: string | null;
+  oldValue: string | null;
+  newValue: string | null;
+}
+interface CacheStorageEvent {
+  storageArea: CacheStorage;
+  key: string | null;
+  oldValue: string | null;
+  newValue: string | null;
+}
+/**
+ * A reactive interface for json stored in the browser [Cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache) API.
+ *
+ * This is a good option for larger data sets than can be efficiently stored in localStorage
+ * but should not be used as a permanent DB or storage solution.
+ */
+declare class CacheStorage implements Storage {
+  #private;
+  _data: Map<string, string | null>;
+  _nextUpdate: number | null;
+  _bufferedEvents: InternalCacheStorageEvent[];
+  constructor(cacheId: string);
+  get length(): number;
+  clear(): void;
+  getItem(key: string): string | null;
+  key(index: number): string | null;
+  removeItem(key: string): void;
+  setItem(key: string, value: string): void;
+  /**
+   * Get the singleton CacheStorage instance.
+   *
+   */
+  static get(cacheId?: string): Promise<CacheStorage>;
+  static expectCache(cacheId?: string): CacheStorage;
+  /**
+   * Returns the IDs of all {@link CacheStorage} instances that have been
+   * opened in this context via {@link CacheStorage.get}.
+   */
+  static getAllCacheIds(): string[];
+}
+//#endregion
+//#region src/storage/storage.d.ts
+interface ReactiveStorageOptions {
+  /**
+   * If true, falls back to in-memory storage when the underlying
+   * storage is unavailable (e.g., private browsing mode).
+   */
+  fallbackToMemory?: boolean;
+  /**
+   * If true, updates signal state even when writes fail due to quota.
+   * The onQuotaExceeded callback will be invoked before retrying.
+   */
+  updateOnQuotaExceeded?: boolean;
+  /**
+   * Called when a write fails due to quota exceeded.
+   * Return true to retry the write after freeing space.
+   */
+  onQuotaExceeded?: (key: string, value: string) => boolean | Promise<boolean>;
+}
+/**
+ * Retrieves the singleton instance of the LocalStorage service.
+ *
+ * If the instance does not already exist, it is created.
+ */
+declare function getLocalStorage(): ReactiveStorage;
+declare function getSessionStorage(): ReactiveStorage;
+declare function getCacheStorage(namespace?: string | null): ReactiveStorage;
+/**
+ * Configure options for the localStorage singleton.
+ * Must be called before getLocalStorage() is first invoked.
+ */
+declare function configureLocalStorage(options: ReactiveStorageOptions): void;
+/**
+ * Configure options for the sessionStorage singleton.
+ * Must be called before getSessionStorage() is first invoked.
+ */
+declare function configureSessionStorage(options: ReactiveStorageOptions): void;
+type EffectStorageEvent = CacheStorageEvent | StorageEvent;
+/**
+ * A reactive wrapper around the Web Storage API (localStorage/sessionStorage)
+ * that provides signal-based access to storage items and length.
+ *
+ * Will automatically update when storage events occur in other tabs/windows.
+ */
+declare class ReactiveStorage implements Storage {
+  private _storage;
+  private _options;
+  private _memoryOnly;
+  private _values;
+  private _signals;
+  private _length;
+  private _effects;
+  setEffect(key: string, fn: (value: EffectStorageEvent) => void): void;
+  constructor(storage: Storage, options?: ReactiveStorageOptions);
+  /**
+   * Reactive access to the number of keys in Storage
+   */
+  get length(): number;
+  /**
+   * Non-reactive way to peek the current value of a key in Storage
+   */
+  peekItem(key: string): string | null;
+  /**
+   * Reactive access to Storage contents
+   */
+  getItem(key: string): string | null;
+  /**
+   * Set a value in Storage, triggering reactivity
+   */
+  setItem(key: string, value: string): void;
+  /**
+   * Remove a value from Storage, triggering reactivity
+   */
+  removeItem(key: string): void;
+  /**
+   * Clears all keys from Storage, triggering reactivity
+   */
+  clear(): void;
+  /**
+   * Reactive access to the key at the given index
+   */
+  key(index: number): string | null;
+}
+//#endregion
+//#region src/storage/-private/storage-infra.d.ts
+/**
+ * Configuration options for fields that are also query parameters
+ */
+interface ParamConfig {
+  /**
+   * Convert a value into a string for storage in the URL.
+   * `null` indicates the value should be omitted from the URL.
+   */
+  serialize: (value: unknown, instance: any) => string | null;
+  /**
+   * Convert a string value from the URL back into
+   * its original type
+   */
+  deserialize: (urlValue: string, instance: any) => unknown;
+  /**
+   * Get the default value for this param from the given instance.
+   *
+   * If not present, the value passed to the field initializer
+   * will be used as the default.
+   *
+   * This should return the value in the field's native type,
+   * not the serialized URL form.
+   */
+  getDefault?: (instance: any) => unknown;
+}
+interface InternalParamConfig extends ParamConfig {
+  initialized?: boolean;
+}
+interface ValueTransition<T = unknown> {
+  key: string;
+  from: T;
+  to: T;
+}
+/**
+ * Metadata attached to persisted resource classes
+ */
+interface StorageResourceMeta {
+  id: string;
+  namespace: string | null;
+  pkFn: KeyFn | null;
+  type: "local-resource" | "session-resource" | "cache-resource";
+  typeOverrides: Map<string, "local-storage" | "session-storage" | "cache-storage"> | null;
+  fields: Map<string, null | ((update: ValueTransition<string>) => void)>;
+  initializers: Map<string, (() => unknown) | null>;
+  paramConfigs: Map<string, InternalParamConfig> | null;
+  paramCompanion: object | null;
+  instances: WeakMap<object, StorageResourceMeta> | null;
+}
+/**
+ * A function which generates a unique primary-key
+ * string for a given LocalResource or SessionResource
+ * instance.
+ *
+ * Use functions when you want to create more than
+ * one instance of a resource type, each with its own
+ * persisted data.
+ */
+type KeyFn = (obj: any) => string;
+/**
+ * Setup persisted resource metadata on target
+ * if not already present
+ *
+ * @private
+ */
+declare function initMeta(target: object): StorageResourceMeta;
+/**
+ * Get or create the param companion object for a StorageResource instance.
+ *
+ * The companion object contains URL-serialized versions of all @param decorated fields.
+ * Each param field gets a corresponding property on the companion that:
+ * - Reads: Serializes the storage value to a URL string (returns null if not active)
+ * - Writes: Deserializes the URL string and updates the storage value
+ *
+ * The companion object is reactive using trackedObject, ensuring that changes
+ * to the underlying storage fields trigger updates in the query param system.
+ *
+ * This companion object is what QPRoute will bind to for URL query params.
+ *
+ * @private
+ * @param instance - The StorageResource instance
+ * @param groupControlMap - Optional map of fieldName -> controlFieldName for grouped params
+ * @returns The companion object with serialized param properties
+ */
+declare function getParamCompanion(instance: object, groupControlMap?: Record<string, string>): object;
+//#endregion
+//#region src/storage/storage-resource.d.ts
+/**
+ * Decorator which transforms a class into a StorageResource
+ * persisted in localStorage.
+ *
+ * LocalResources must either be singletons or expect all instances
+ * to share state unless a primary key function is provided.
+ *
+ * When a primary key function is provided, each instance
+ * will have its own persisted data based on the key generated
+ * by the function.
+ *
+ * The function will be called once per instance during
+ * initialization to determine the unique ID for that instance.
+ */
+declare function LocalResource(id: string | KeyFn): ClassDecorator;
+/**
+ * Decorator which transforms a class into a StorageResource
+ * persisted in sessionStorage.
+ *
+ * SessionResources must either be singletons or expect all instances
+ * to share state unless a primary key function is provided.
+ *
+ * When a primary key function is provided, each instance
+ * will have its own persisted data based on the key generated
+ * by the function.
+ *
+ * The function will be called once per instance during
+ * initialization to determine the unique ID for that instance.
+ */
+declare function SessionResource(id: string | KeyFn): ClassDecorator;
+/**
+ * Decorator which transforms a class into a StorageResource
+ * persisted via the [Cache API](https://developer.mozilla.org/en-US/docs/Web/API/Cache).
+ * api and shared across all tabs/windows under the same origin.
+ *
+ * CacheResources must either be singletons or expect all instances
+ * to share state unless a primary key function is provided.
+ *
+ * When a primary key function is provided, each instance
+ * will have its own persisted data based on the key generated
+ * by the function.
+ *
+ * The function will be called once per instance during
+ * initialization to determine the unique ID for that instance.
+ *
+ * All object cached in the same `namespace` share the namespace's storage context,
+ * so partitioning can be achieved by using different namespaces for different groups
+ * of data.
+ */
+declare function CacheResource(id: string | KeyFn, namespace?: string | null): ClassDecorator;
+/**
+ * Decorator which marks a property as a field on
+ * a LocalResource or SessionResource
+ *
+ * The field's value will be initialized from the persisted resource data
+ * if available, falling back to the property's default value otherwise.
+ *
+ * Fields can be of any type that is serializable to and restorable from JSON,
+ * but complex types (like objects or arrays) should be handled with care to avoid
+ * unintended mutations or reactivity issues.
+ *
+ * By default, fields are persisted in the storage type defined by the resource decorator
+ * (@LocalResource or @SessionResource). However, you can override this behavior
+ * by passing 'local' or 'session' as an argument to the decorator.
+ *
+ * ---
+ *
+ * **Example:**
+ *
+ * ```ts
+ * @LocalResource('user-settings')
+ * class UserSettings {
+ *   @field
+ *   theme: 'light' | 'dark' = 'light';
+ *
+ *   @field('session')
+ *   sessionToken: string | null = null;
+ * }
+ * ```
+ *
+ */
+declare function field(type: "local" | "session" | "cache"): PropertyDecorator;
+declare function field(target: object, key: string, descriptor?: PropertyDescriptor): void;
+declare function input(type: "number" | "boolean" | "float"): PropertyDecorator;
+/**
+ * Effects are fields that run a side-effecting function.
+ *
+ * Effects are intended to enable synchronizing get states between
+ * tabs or windows that result in needing to synchronize other
+ * non-reactive state.
+ *
+ * For example, when a user selects a light/dark mode theme preference
+ * that differs from the system preference, effects can be used to trigger
+ * DOM updates on the documentElement necessary to ensure its state is
+ * consistent with the persisted resource state and reactive application state.
+ *
+ * To do this without an effect would require either setting up your own
+ * storage event listeners or consuming the reactive state of the property
+ * in another effect-like API such as an Ember modifier or React useEffect,
+ *
+ * Effects *only* run when the stored value changes due to storage events
+ * emitted from other tabs or windows. They do not run when the property
+ * is updated in the same context.
+ *
+ * ---
+ *
+ * **Example:**
+ *
+ * ```ts
+ * @LocalResource('user-preferences')
+ * class UserPreferences {
+ *   @effect(syncThemeToDOM)
+ *   explicitThemePreference: 'light' | 'dark' | null = null;
+ *
+ *   @matchMedia('(prefers-color-scheme: dark)')
+ *   systemPrefersDarkMode: boolean = false;
+ * }
+ *
+ * function syncThemeToDOM(update: ValueTransition<'light' | 'dark' | null>): void {
+ *   const newTheme = update.to;
+ *   document.documentElement.style.colorScheme = newTheme ?? 'light dark';
+ *
+ *   if (newTheme === 'dark') {
+ *     document.documentElement.classList.add('dark-theme');
+ *     document.documentElement.classList.remove('light-theme');
+ *   } else if (newTheme === 'light') {
+ *     document.documentElement.classList.add('light-theme');
+ *     document.documentElement.classList.remove('dark-theme');
+ *   } else {
+ *     document.documentElement.classList.remove('light-theme');
+ *     document.documentElement.classList.remove('dark-theme');
+ *   }
+ * }
+ * ```
+ */
+declare function effect(fn: <K>(update: ValueTransition<K>) => void, type?: "local" | "session"): PropertyDecorator;
+//#endregion
+export { CacheResource, CacheStorage, CacheStorageEvent, DEFAULT_CACHE_ID, EffectStorageEvent, InternalCacheStorageEvent, LocalResource, type ReactiveStorage, ReactiveStorageOptions, SessionResource, getParamCompanion as _getParamCompanion, initMeta as _initMeta, configureLocalStorage, configureSessionStorage, effect, field, getCacheStorage, getLocalStorage, getSessionStorage, input };
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","names":[],"sources":["../src/storage/cache.ts","../src/storage/storage.ts","../src/storage/-private/storage-infra.ts","../src/storage/storage-resource.ts"],"mappings":";cAEa;UAKI;EACf;EACA;EACA;EACA;;UAEe;EACf,aAAa;EACb;EACA;EACA;;;;;;;;cAkEW,wBAAwB;;EAInC,OAAO;EACP;EACA,iBAAiB;EAYjB,YAAY;MAMR;EA4BJ;EAKA,QAAQ;EAIR,IAAI;EAgBJ,WAAW;EAQX,QAAQ,aAAa;;;;;SAed,IAAI,mBAAqC,QAAQ;SASjD,YAAY,mBAAqC;;;;;SAYjD;;;;UCtMQ;;;;;EAKf;;;;;EAMA;;;;;EAMA,mBAAmB,aAAa,4BAA4B;;;;;;;iBAgB9C,mBAAmB;iBAOnB,qBAAqB;iBAQrB,gBAAgB,4BAAkC;;;;;iBAelD,sBAAsB,SAAS;;;;;iBAQ/B,wBAAwB,SAAS;KA8BrC,qBAAqB,oBAAoB;;;;;;;cAQ/C,2BAA2B;UACvB;UACA;UACA;UACA;UAEQ;UACA;UAER;EACR,UAAU,aAAa,KAAK,OAAO;EAKnC,YAAY,SAAS,SAAS,UAAS;;;;MA2CnC;;;;EAOJ,SAAS;;;;EAsBT,QAAQ;;;;EAyBR,QAAQ,aAAa;;;;EA2DrB,WAAW;;;;EAsBX;;;;EAeA,IAAI;;;;;;;UC3TW;;;;;EAMf,YAAY,gBAAgB;;;;;EAM5B,cAAc,kBAAkB;;;;;;;;;;EAWhC,cAAc;;UAGN,4BAA4B;EACpC;;UAGe,gBAAgB;EAC/B;EACA,MAAM;EACN,IAAI;;;;;UAMW;EACf;EACA;EACA,MAAM;EACN;EACA,eAAe;EACf,QAAQ,qBAAqB,QAAQ;EACrC,cAAc;EACd,cAAc,YAAY;EAC1B;EACA,WAAW,gBAAgB;;;;;;;;;;;KAajB,SAAS;;;;;;;iBAaL,SAAS,iBAAiB;;;;;;;;;;;;;;;;;;;iBAkT1B,kBAAkB,kBAAkB,kBAAkB;;;;;;;;;;;;;;;;;iBCzWtD,cAAc,aAAa,QAAQ;;;;;;;;;;;;;;;iBAkBnC,gBAAgB,aAAa,QAAQ;;;;;;;;;;;;;;;;;;;;iBAuBrC,cAAc,aAAa,OAAO,4BAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmCpE,MAAM,sCAAsC;iBAC5C,MAAM,gBAAgB,aAAa,aAAa;iBAgBhD,MAAM,uCAAuC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoF7C,OAAO,KAAK,GAAG,QAAQ,gBAAgB,aAAa,6BAA6B"}