@warp-drive-mirror/experiments 0.2.7-alpha.15 → 0.2.7-alpha.16

package/README.md

@@ -28,3 +28,4 @@
 - [DataWorker](./src/data-worker/README.md)
 - [DocumentStorage](./src/document-storage/README.md)
 - [ImageWorker](./src/image-worker/README.md)
+- ReactiveStorage

package/declarations/storage/-private/reactive-map.d.ts

@@ -0,0 +1,13 @@
+/**
+* A reactive wrapper around the browser's Map API that provides
+* granular per-key reactivity via WarpDrive's signal system.
+*/
+export declare class SignalMap<K extends string> {
+	private _map;
+	private _size;
+	private _signals;
+	subscribe(key: K): boolean;
+	notify(key: K): void;
+	clear(): void;
+	get size(): number;
+}

package/declarations/storage/-private/storage-infra.d.ts

@@ -0,0 +1,104 @@
+/**
+* Configuration options for fields that are also query parameters
+*/
+export 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;
+}
+export interface ValueTransition<T = unknown> {
+	key: string;
+	from: T;
+	to: T;
+}
+/**
+* Metadata attached to persisted resource classes
+*/
+export 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.
+*/
+export type KeyFn = (obj: any) => string;
+/**
+* Setup persisted resource metadata on target
+* if not already present
+*
+* @private
+*/
+export declare function initMeta(target: object): StorageResourceMeta;
+export declare function useMeta(meta: StorageResourceMeta, instance: object): StorageResourceMeta;
+/**
+* Load storage field
+*/
+export declare function getField(instance: object, meta: StorageResourceMeta, key: string, overrideType: "local-storage" | "session-storage" | "cache-storage" | null): Record<string, unknown> | null;
+export declare function peekField(meta: StorageResourceMeta, key: string, overrideType: "local-storage" | "session-storage" | "cache-storage" | null): unknown;
+export declare function initializeFields(instance: object, source: object): void;
+/**
+* Update storage field
+*/
+export declare function setField(meta: StorageResourceMeta, key: string, value: string | boolean | null | number | Record<string, unknown> | unknown[], overrideType: "local-storage" | "session-storage" | "cache-storage" | null): void;
+export declare function _createStorageResource(id: string | KeyFn, type: "local-resource" | "session-resource" | "cache-resource", namespace: string | null): ClassDecorator;
+/**
+* Returns the descriptor but is cast
+* to void to satisfy Typescript's incorrect
+* typing for legacy decorators.
+*/
+export declare function setupField(target: object, key: string, orgDesc?: PropertyDescriptor, type?: "local" | "session" | "cache"): void;
+export declare function installEffect(meta: StorageResourceMeta, key: string): Promise<void>;
+/**
+* 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
+*/
+export declare function getParamCompanion(instance: object, groupControlMap?: Record<string, string>): object;
+export {};

package/declarations/storage/cache.d.ts

@@ -0,0 +1,43 @@
+export declare const DEFAULT_CACHE_ID = "reactive-cache";
+export interface InternalCacheStorageEvent {
+	storageArea: string;
+	key: string | null;
+	oldValue: string | null;
+	newValue: string | null;
+}
+export 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.
+*/
+export 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[];
+}

package/declarations/storage/storage-resource.d.ts

@@ -0,0 +1,137 @@
+import { type KeyFn, type ValueTransition } from "./-private/storage-infra.js";
+/**
+* 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.
+*/
+export 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.
+*/
+export 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.
+*/
+export 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;
+* }
+* ```
+*
+*/
+export declare function field(type: "local" | "session" | "cache"): PropertyDecorator;
+export declare function field(target: object, key: string, descriptor?: PropertyDescriptor): void;
+export 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');
+*   }
+* }
+* ```
+*/
+export declare function effect(fn: <K>(update: ValueTransition<K>) => void, type?: "local" | "session"): PropertyDecorator;

package/declarations/storage/storage.d.ts

@@ -0,0 +1,88 @@
+import { type CacheStorageEvent } from "./cache.js";
+export 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.
+*/
+export declare function getLocalStorage(): ReactiveStorage;
+export declare function getSessionStorage(): ReactiveStorage;
+export declare function getCacheStorage(namespace?: string | null): ReactiveStorage;
+/**
+* Configure options for the localStorage singleton.
+* Must be called before getLocalStorage() is first invoked.
+*/
+export declare function configureLocalStorage(options: ReactiveStorageOptions): void;
+/**
+* Configure options for the sessionStorage singleton.
+* Must be called before getSessionStorage() is first invoked.
+*/
+export declare function configureSessionStorage(options: ReactiveStorageOptions): void;
+export type EffectStorageEvent = CacheStorageEvent | StorageEvent;
+declare global {
+	interface WindowEventMap {
+		storage: CustomEvent<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;
+}
+export type { ReactiveStorage };

package/declarations/storage.d.ts

@@ -0,0 +1,7 @@
+export * from "./storage/storage.js";
+export type * from "./storage/storage.js";
+export * from "./storage/storage-resource.js";
+export type * from "./storage/storage-resource.js";
+export * from "./storage/cache.js";
+export type * from "./storage/cache.js";
+export { initMeta as _initMeta, getParamCompanion as _getParamCompanion } from "./storage/-private/storage-infra.js";