@warp-drive-mirror/experiments 0.2.7-beta.0 → 0.2.7-beta.1

package/dist/storage.js

@@ -0,0 +1,914 @@
+import { getGlobalConfig, macroCondition } from "@embroider/macros";
+import { defineSignal, entangleSignal, getOrCreateInternalSignal, makeInitializer, memoized, notifyInternalSignal, withSignalStore } from "@warp-drive-mirror/core/signals/-leaked";
+
+//#region src/storage/-private/reactive-map.ts
+/**
+* A reactive wrapper around the browser's Map API that provides
+* granular per-key reactivity via WarpDrive's signal system.
+*/
+var SignalMap = class {
+	_map = {};
+	_signals = withSignalStore(this._map);
+	subscribe(key) {
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error(`ReactiveMap keys must be strings, got ${typeof key}`);
+		})(typeof key === "string");
+		const existing = this._signals.has(key);
+		entangleSignal(this._signals, this._map, key, void 0);
+		const size = this._size;
+		this._size = existing ? size : size + 1;
+		return existing;
+	}
+	notify(key) {
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error(`ReactiveMap keys must be strings, got ${typeof key}`);
+		})(typeof key === "string");
+		const signal = getOrCreateInternalSignal(this._signals, this._map, key, 0);
+		notifyInternalSignal(signal);
+	}
+	clear() {
+		for (const value of this._signals.values()) notifyInternalSignal(value);
+		this._size = 0;
+	}
+	get size() {
+		return this._size;
+	}
+};
+defineSignal(SignalMap.prototype, "_size", 0);
+
+//#endregion
+//#region src/storage/cache.ts
+const DEFAULT_CACHE_ID = "reactive-cache";
+const CACHES = /* @__PURE__ */ new Map();
+const StorageEvents = new BroadcastChannel("reactive-cache-events");
+const CACHE_URL = `${location.origin}/api/reactive-cache.json`;
+/**
+* Emits a {@link StorageEvent} on the local context to
+* match the broadcast event.
+*/
+function emitStorageEvent(event) {
+	window.dispatchEvent(new CustomEvent("storage", { detail: event }));
+}
+/**
+* Updates the cache and re-emits the event on the local context as a StorageEvent
+* This is necessary to trigger the reactive updates in the current tab.
+*/
+function handleCacheEvent(event) {
+	const { data } = event;
+	const cache = CACHES.get(data.storageArea);
+	if (!cache) return;
+	if (data.key === null) {
+		cache._data = /* @__PURE__ */ new Map();
+		emitStorageEvent({
+			storageArea: cache,
+			key: null,
+			oldValue: null,
+			newValue: null
+		});
+		return;
+	}
+	if (data.newValue === null) cache._data.delete(data.key);
+	else cache._data.set(data.key, data.newValue);
+	emitStorageEvent({
+		storageArea: cache,
+		key: data.key,
+		oldValue: data.oldValue,
+		newValue: data.newValue
+	});
+}
+StorageEvents.addEventListener("message", handleCacheEvent);
+/**
+* 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.
+*/
+var CacheStorage = class CacheStorage {
+	#cache;
+	#cacheId;
+	#inititalization;
+	_data = /* @__PURE__ */ new Map();
+	_nextUpdate = null;
+	_bufferedEvents = [];
+	async #initialize() {
+		const cache = await caches.open(this.#cacheId);
+		this.#cache = cache;
+		this._data = await deserializeFromCache(cache);
+		return this;
+	}
+	constructor(cacheId) {
+		this.#cacheId = cacheId;
+		this.#cache = null;
+		this.#inititalization = this.#initialize();
+	}
+	get length() {
+		return this._data.size;
+	}
+	#update(key, oldValue, newValue) {
+		const cache = this.#cache;
+		if (!cache) throw new Error("Cache not initialized");
+		this._bufferedEvents.push({
+			storageArea: this.#cacheId,
+			key,
+			oldValue,
+			newValue
+		});
+		if (!this._nextUpdate) this._nextUpdate = window.setTimeout(() => {
+			const events = this._bufferedEvents;
+			this._bufferedEvents = [];
+			this._nextUpdate = null;
+			serializeToCache(cache, this._data);
+			for (const event of events) StorageEvents.postMessage(event);
+		}, 0);
+	}
+	clear() {
+		this._data = /* @__PURE__ */ new Map();
+		this.#update(null, null, null);
+	}
+	getItem(key) {
+		return this._data.get(key) ?? null;
+	}
+	key(index) {
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error("ReactiveStorage.key: index must be a number");
+		})(typeof index === "number");
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error("ReactiveStorage.key: index must be a non-negative integer");
+		})(index >= 0 && Number.isInteger(index));
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error("ReactiveStorage.key: index must be less than the number of items in storage");
+		})(index < this.length);
+		let i = 0;
+		for (const value of this._data.keys()) {
+			if (i === index) return value;
+			i++;
+		}
+		return null;
+	}
+	removeItem(key) {
+		if (this._data.has(key)) {
+			const oldValue = this._data.get(key) ?? null;
+			this._data.delete(key);
+			this.#update(key, oldValue, null);
+		}
+	}
+	setItem(key, value) {
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error("ReactiveStorage.setItem: key must be a string");
+		})(typeof key === "string");
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error("ReactiveStorage.setItem: value must be a string");
+		})(typeof value === "string");
+		const oldValue = this._data.get(key) ?? null;
+		if (oldValue === value) return;
+		this._data.set(key, value);
+		this.#update(key, oldValue, value);
+	}
+	/**
+	* Get the singleton CacheStorage instance.
+	*
+	*/
+	static get(cacheId = DEFAULT_CACHE_ID) {
+		let cache = CACHES.get(cacheId);
+		if (!cache) {
+			cache = new CacheStorage(cacheId);
+			CACHES.set(cacheId, cache);
+		}
+		return cache.#inititalization;
+	}
+	static expectCache(cacheId = DEFAULT_CACHE_ID) {
+		const cache = CACHES.get(cacheId);
+		if (!cache) throw new Error(`Cache with id ${cacheId} not found. Make sure to call CacheStorage.get(${cacheId}) first.`);
+		return cache;
+	}
+	/**
+	* Returns the IDs of all {@link CacheStorage} instances that have been
+	* opened in this context via {@link CacheStorage.get}.
+	*/
+	static getAllCacheIds() {
+		return Array.from(CACHES.keys());
+	}
+};
+function serializeToCache(cache, data) {
+	const entries = Array.from(data.entries());
+	const blob = JSON.stringify({
+		version: 1,
+		data: entries
+	});
+	const response = new Response(blob);
+	return cache.put(CACHE_URL, response);
+}
+function deserializeFromCache(cache) {
+	return cache.match(CACHE_URL).then((response) => {
+		if (!response) return /* @__PURE__ */ new Map();
+		return response.json().then((json) => {
+			if (json.version !== 1) throw new Error(`Unsupported cache version: ${json.version}`);
+			return new Map(json.data);
+		});
+	});
+}
+
+//#endregion
+//#region src/storage/storage.ts
+let localStorageInstance = null;
+let sessionStorageInstance = null;
+let localStorageOptions = {};
+let sessionStorageOptions = {};
+/**
+* Retrieves the singleton instance of the LocalStorage service.
+*
+* If the instance does not already exist, it is created.
+*/
+function getLocalStorage() {
+	if (!localStorageInstance) localStorageInstance = new ReactiveStorage(localStorage, localStorageOptions);
+	return localStorageInstance;
+}
+function getSessionStorage() {
+	if (!sessionStorageInstance) sessionStorageInstance = new ReactiveStorage(sessionStorage, sessionStorageOptions);
+	return sessionStorageInstance;
+}
+const CacheStorages = /* @__PURE__ */ new Map();
+function getCacheStorage(namespace = null) {
+	const key = namespace ?? "reactive-cache";
+	let cache = CacheStorages.get(key);
+	if (!cache) {
+		const storage = CacheStorage.expectCache(key);
+		cache = new ReactiveStorage(storage);
+		CacheStorages.set(key, cache);
+	}
+	return cache;
+}
+/**
+* Configure options for the localStorage singleton.
+* Must be called before getLocalStorage() is first invoked.
+*/
+function configureLocalStorage(options) {
+	localStorageOptions = options;
+}
+/**
+* Configure options for the sessionStorage singleton.
+* Must be called before getSessionStorage() is first invoked.
+*/
+function configureSessionStorage(options) {
+	sessionStorageOptions = options;
+}
+/**
+* Check if an error is a quota exceeded error
+*/
+function isQuotaExceededError(error) {
+	if (error instanceof DOMException) {
+		if (error.name === "QuotaExceededError") return true;
+		if (error.name === "NS_ERROR_DOM_QUOTA_REACHED") return true;
+	}
+	return false;
+}
+/**
+* Check if an error indicates storage is unavailable (private browsing, etc.)
+*/
+function isStorageUnavailableError(error) {
+	if (error instanceof DOMException) {
+		if (error.name === "SecurityError") return true;
+		if (error.name === "InvalidStateError") return true;
+	}
+	return false;
+}
+/**
+* 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.
+*/
+var ReactiveStorage = class {
+	_storage;
+	_options;
+	_memoryOnly = false;
+	_values = {};
+	_effects = /* @__PURE__ */ new Map();
+	setEffect(key, fn) {
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error(`Can only set effect once for key: ${key}`);
+		})(!this._effects.has(key));
+		this._effects.set(key, fn);
+	}
+	constructor(storage, options = {}) {
+		this._storage = storage;
+		this._options = options;
+		if (!(storage instanceof CacheStorage)) try {
+			const testKey = "__storage_test__";
+			storage.setItem(testKey, testKey);
+			storage.removeItem(testKey);
+			this._length = storage.length;
+		} catch (error) {
+			if (options.fallbackToMemory && isStorageUnavailableError(error)) {
+				this._memoryOnly = true;
+				this._length = 0;
+			} else throw error;
+		}
+		if (!this._memoryOnly) window.addEventListener("storage", (event) => {
+			const data = "detail" in event ? event.detail : event;
+			if (data.storageArea === storage) {
+				this._values[data.key] = data.newValue;
+				this._signals.notify(data.key);
+				this._length = this._storage.length;
+				const effect = this._effects.get(data.key);
+				if (effect) effect(data);
+			}
+		});
+	}
+	/**
+	* Reactive access to the number of keys in Storage
+	*/
+	get length() {
+		return this._length;
+	}
+	/**
+	* Non-reactive way to peek the current value of a key in Storage
+	*/
+	peekItem(key) {
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error("ReactiveStorage.peekItem: key must be a string");
+		})(typeof key === "string");
+		const keyStr = String(key);
+		if (this._memoryOnly) return this._values[keyStr] ?? null;
+		const value = this._values[keyStr];
+		if (value !== void 0) return value;
+		return this._storage.getItem(keyStr);
+	}
+	/**
+	* Reactive access to Storage contents
+	*/
+	getItem(key) {
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error("ReactiveStorage.getItem: key must be a string");
+		})(typeof key === "string");
+		const keyStr = String(key);
+		if (this._memoryOnly) {
+			this._signals.subscribe(keyStr);
+			return this._values[keyStr] ?? null;
+		}
+		const value = this._values[keyStr];
+		if (value !== void 0) {
+			this._signals.subscribe(keyStr);
+			return value;
+		}
+		const item = this._storage.getItem(keyStr);
+		this._values[keyStr] = item;
+		this._signals.subscribe(keyStr);
+		return item;
+	}
+	/**
+	* Set a value in Storage, triggering reactivity
+	*/
+	setItem(key, value) {
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error("ReactiveStorage.setItem: key must be a string");
+		})(typeof key === "string");
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error("ReactiveStorage.setItem: value must be a string");
+		})(typeof value === "string");
+		const keyStr = String(key);
+		const valueStr = String(value);
+		if (this._values[keyStr] === valueStr) return;
+		if (this._memoryOnly) {
+			const currentValue = this._values[keyStr];
+			if (currentValue === null || currentValue === void 0) this._length += 1;
+			this._values[keyStr] = valueStr;
+			this._signals.notify(keyStr);
+			return;
+		}
+		try {
+			this._storage.setItem(keyStr, valueStr);
+			this._values[keyStr] = valueStr;
+			this._signals.notify(keyStr);
+			this._length = this._storage.length;
+		} catch (error) {
+			if (isQuotaExceededError(error)) {
+				if (this._options.updateOnQuotaExceeded) {
+					this._values[keyStr] = valueStr;
+					this._signals.notify(keyStr);
+				}
+				if (this._options.onQuotaExceeded) {
+					const result = this._options.onQuotaExceeded(keyStr, valueStr);
+					if (result instanceof Promise ? false : result) {
+						this._storage.setItem(keyStr, valueStr);
+						this._length = this._storage.length;
+					}
+				} else throw error;
+			} else throw error;
+		}
+	}
+	/**
+	* Remove a value from Storage, triggering reactivity
+	*/
+	removeItem(key) {
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error("ReactiveStorage.removeItem: key must be a string");
+		})(typeof key === "string");
+		const keyStr = String(key);
+		if (this._memoryOnly) {
+			const value = this._values[keyStr];
+			if (value !== null && value !== void 0) this._length -= 1;
+			this._values[keyStr] = null;
+			return;
+		}
+		this._storage.removeItem(keyStr);
+		this._values[keyStr] = null;
+		this._signals.notify(keyStr);
+		this._length = this._storage.length;
+	}
+	/**
+	* Clears all keys from Storage, triggering reactivity
+	*/
+	clear() {
+		this._values = {};
+		this._signals.clear();
+		this._length = 0;
+		if (this._memoryOnly) return;
+		this._storage.clear();
+	}
+	/**
+	* Reactive access to the key at the given index
+	*/
+	key(index) {
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error("ReactiveStorage.key: index must be a number");
+		})(typeof index === "number");
+		this._length;
+		if (this._memoryOnly) return Object.keys(this._values).filter((k) => this._values[k] !== null)[index] ?? null;
+		return this._storage.key(index);
+	}
+};
+defineSignal(ReactiveStorage.prototype, "_length", 0);
+defineSignal(ReactiveStorage.prototype, "_signals", makeInitializer(() => new SignalMap()));
+
+//#endregion
+//#region src/storage/-private/storage-infra.ts
+/**
+* Configuration options for fields that are also query parameters
+*/
+/**
+* Metadata attached to persisted resource classes
+*/
+/**
+* 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.
+*/
+/**
+* Symbol used to store persistence metadata on classes
+*/
+const PERSISTED_RESOURCE_META = Symbol("StorageResourceMeta");
+/**
+* Setup persisted resource metadata on target
+* if not already present
+*
+* @private
+*/
+function initMeta(target) {
+	let meta = target[PERSISTED_RESOURCE_META];
+	if (!meta) {
+		meta = {
+			id: "",
+			namespace: null,
+			pkFn: null,
+			type: "",
+			fields: /* @__PURE__ */ new Map(),
+			initializers: /* @__PURE__ */ new Map(),
+			paramConfigs: null,
+			paramCompanion: null,
+			instances: null,
+			typeOverrides: null
+		};
+		target[PERSISTED_RESOURCE_META] = meta;
+	}
+	return meta;
+}
+function useMeta(meta, instance) {
+	if (meta.id === "" && meta.pkFn) {
+		meta.instances = meta.instances ?? /* @__PURE__ */ new WeakMap();
+		let instanceMeta = meta.instances.get(instance);
+		if (!instanceMeta) {
+			instanceMeta = { ...meta };
+			const pk = meta.pkFn(instance);
+			macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+				if (!test) throw new Error("Primary key function must return a non-empty string.");
+			})(typeof pk === "string" && pk.length > 0);
+			instanceMeta.id = pk;
+			meta.instances.set(instance, instanceMeta);
+		}
+		return instanceMeta;
+	}
+	macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+		if (!test) throw new Error("StorageResourceMeta must have a valid id.");
+	})(typeof meta.id === "string" && meta.id.length > 0);
+	return meta;
+}
+/**
+* Load storage field
+*/
+function getField(instance, meta, key, overrideType) {
+	const stored = getStorage(overrideType || meta.type, meta.namespace).getItem(keyFor(meta, key));
+	if (stored) return JSON.parse(stored);
+	else {
+		const initializer = meta.initializers.get(key);
+		if (initializer) {
+			const value = initializer.call(instance);
+			if (value !== void 0) return value;
+		}
+	}
+	return null;
+}
+function keyFor(meta, key) {
+	return `persisted:${meta.id}:${key}`;
+}
+function getStorage(type, namespace) {
+	if (type === "local-resource") return getLocalStorage();
+	else if (type === "session-resource") return getSessionStorage();
+	else return getCacheStorage(namespace);
+}
+/**
+* Update storage field
+*/
+function setField(meta, key, value, overrideType) {
+	getStorage(overrideType || meta.type, meta.namespace).setItem(keyFor(meta, key), JSON.stringify(value));
+}
+function getResourceMeta(target) {
+	const meta = target[PERSISTED_RESOURCE_META];
+	macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+		if (!test) throw new Error("StorageResourceMeta not found on target. Did you forget to use the @LocalResource() or @SessionResource() decorator?");
+	})(meta !== void 0);
+	return meta;
+}
+function _createStorageResource(id, type, namespace) {
+	return function(target) {
+		const meta = getResourceMeta(target.prototype);
+		meta.id = typeof id === "string" ? id : "";
+		meta.pkFn = typeof id === "function" ? id : null;
+		meta.type = type;
+		meta.namespace = namespace;
+		if (meta.pkFn !== null) {
+			const originalConstructor = target.prototype.constructor;
+			target.prototype.constructor = function DynamicStorageInitializer(...args) {
+				const instance = new originalConstructor(...args);
+				installEffectsForDynamicInstance(meta, instance);
+				return instance;
+			};
+		}
+		if (!("toJSON" in target.prototype)) target.prototype.toJSON = function() {
+			const instanceMeta = useMeta(meta, this);
+			const isLocalResource = meta.type === "local-resource" || meta.type === "cache-resource";
+			const fields = isLocalResource ? new Set(meta.fields.keys()) : /* @__PURE__ */ new Set();
+			for (const [key, overrideType] of meta.typeOverrides?.entries() ?? []) if (overrideType === "local-storage") fields.add(key);
+			else if (overrideType === "session-storage" && isLocalResource) fields.delete(key);
+			let idKey = "$key";
+			while (fields.has(idKey)) idKey = `_${idKey}`;
+			const data = { [idKey]: instanceMeta.id };
+			for (const key of fields) {
+				const value = getField(this, instanceMeta, key, meta.typeOverrides?.get(key) ?? null);
+				if (value !== null) data[key] = value;
+			}
+			return data;
+		};
+	};
+}
+async function installEffectsForDynamicInstance(meta, instance) {
+	await Promise.resolve();
+	for (const [key, value] of meta.fields.entries()) if (typeof value === "function") installEffect(useMeta(meta, instance), key);
+}
+/**
+* Returns the descriptor but is cast
+* to void to satisfy Typescript's incorrect
+* typing for legacy decorators.
+*/
+function setupField(target, key, orgDesc, type) {
+	const meta = initMeta(target);
+	meta.fields.set(key, null);
+	const overrideType = type === "local" ? "local-storage" : type === "session" ? "session-storage" : type === "cache" ? "cache-storage" : null;
+	if (overrideType) {
+		meta.typeOverrides = meta.typeOverrides || /* @__PURE__ */ new Map();
+		meta.typeOverrides.set(key, overrideType);
+	}
+	const initializer = orgDesc?.initializer || null;
+	meta.initializers.set(key, initializer);
+	return memoized(target, key, {
+		configurable: true,
+		enumerable: true,
+		get() {
+			return getField(this, useMeta(meta, this), key, overrideType);
+		},
+		set(value) {
+			setField(useMeta(meta, this), key, value, overrideType);
+		}
+	});
+}
+async function installEffect(meta, key) {
+	await Promise.resolve();
+	const effect = meta.fields.get(key);
+	getStorage(meta.type, meta.namespace).setEffect(keyFor(meta, key), (event) => {
+		const oldValue = event.oldValue ? JSON.parse(event.oldValue) : null;
+		const newValue = event.newValue ? JSON.parse(event.newValue) : null;
+		effect({
+			key,
+			from: oldValue,
+			to: newValue
+		});
+	});
+}
+/**
+* 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
+*/
+function getParamCompanion(instance, groupControlMap) {
+	const meta = getResourceMeta(instance);
+	const instanceMeta = useMeta(meta, instance);
+	if (instanceMeta.paramCompanion) return instanceMeta.paramCompanion;
+	const companion = {};
+	instanceMeta.paramCompanion = companion;
+	const paramConfigs = instanceMeta.paramConfigs;
+	if (!paramConfigs || paramConfigs.size === 0) return companion;
+	for (const [fieldName, config] of paramConfigs.entries()) {
+		const controlFieldName = groupControlMap?.[fieldName];
+		createParamField(companion, fieldName, config, controlFieldName, instance, meta);
+	}
+	return companion;
+}
+function isActiveGroupParam(companion, controlFieldName) {
+	return companion[controlFieldName] !== null;
+}
+/**
+* The default value of a param is determined by:
+* - the getDefault() function if provided, and its return is not undefined
+* - the initializer value provided to the field, if not undefined
+* - null otherwise
+*
+* The value is the deserialized form (i.e., the local storage value type)
+*/
+function getParamFieldDefaultValue(meta, config, fieldName, instance) {
+	const defaultValue = config.getDefault?.(instance);
+	if (defaultValue !== void 0) return defaultValue;
+	const initializer = meta.initializers.get(fieldName);
+	if (initializer) {
+		const initValue = initializer.call(instance);
+		if (initValue !== void 0) return initValue;
+	}
+	return null;
+}
+function createParamField(companion, fieldName, config, controlFieldName, instance, meta) {
+	const desc = {
+		configurable: true,
+		enumerable: true,
+		get() {
+			if (!config.initialized) {
+				config.initialized = true;
+				return null;
+			}
+			if (controlFieldName && !isActiveGroupParam(companion, controlFieldName)) return null;
+			const defaultValue = getParamFieldDefaultValue(meta, config, fieldName, instance);
+			const rawValue = instance[fieldName];
+			if (rawValue === defaultValue) return null;
+			const serialized = config.serialize(rawValue, instance);
+			if (!serialized) return null;
+			return serialized;
+		},
+		set(urlValue) {
+			/**
+			* set will never come from anything except URL deserialization.
+			* which is managed by Ember.
+			*
+			* Our job is to not unnecessarily update the storage resource
+			* so we need to run the compare function to see if the
+			* incoming URL value is different from the existing local value.
+			*/
+			if (!urlValue) return;
+			const rawValue = instance[fieldName];
+			if (config.serialize(rawValue, instance) === urlValue) return;
+			instance[fieldName] = config.deserialize(urlValue, instance);
+		}
+	};
+	memoized(companion, fieldName, desc);
+	Object.defineProperty(companion, fieldName, desc);
+}
+
+//#endregion
+//#region src/storage/storage-resource.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.
+*/
+function LocalResource(id) {
+	return _createStorageResource(id, "local-resource", null);
+}
+/**
+* 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.
+*/
+function SessionResource(id) {
+	return _createStorageResource(id, "session-resource", null);
+}
+/**
+* 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.
+*/
+function CacheResource(id, namespace = null) {
+	return _createStorageResource(id, "cache-resource", namespace);
+}
+/**
+* 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;
+* }
+* ```
+*
+*/
+function field(...args) {
+	if (args.length === 0) {
+		macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+			if (!test) throw new Error("field decorator requires at least 1 argument or should be used without parens");
+		})(true);
+		return setupField;
+	}
+	if (args.length === 1) {
+		const type = args[0];
+		return (target, key, desc) => setupField(target, key, desc, type);
+	}
+	if (args.length === 2 || args.length === 3) {
+		const [target, key, descriptor] = args;
+		return setupField(target, key, descriptor);
+	}
+}
+function input(type) {
+	macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+		if (!test) throw new Error("input decorator requires a valid type argument");
+	})([
+		"number",
+		"boolean",
+		"float"
+	].includes(type));
+	return function(target, key, desc) {
+		const originalSet = desc.set;
+		desc.set = function(value) {
+			switch (type) {
+				case "number":
+					value = Number(value);
+					break;
+				case "boolean":
+					value = value === "false" || value === "" || value === "0" || value === "undefined" || value === "null" || value === false || value === 0 || value === null || value === void 0 ? 0 : 1;
+					break;
+				default: macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) && ((test) => {
+					if (!test) throw new Error(`Unsupported input type: ${type}`);
+				})(false);
+			}
+			originalSet.call(this, value);
+		};
+		return desc;
+	};
+}
+/**
+* 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');
+*   }
+* }
+* ```
+*/
+function effect(fn, type) {
+	const overrideType = type === "local" ? "local-storage" : type === "session" ? "session-storage" : null;
+	return function effectField(target, key, _descriptor) {
+		const meta = initMeta(target);
+		meta.fields.set(key, fn);
+		if (meta.pkFn === null) installEffect(meta, key);
+		return {
+			configurable: true,
+			enumerable: true,
+			get() {
+				return getField(this, useMeta(meta, this), key, overrideType);
+			},
+			set(value) {
+				setField(useMeta(meta, this), key, value, overrideType);
+			}
+		};
+	};
+}
+
+//#endregion
+export { CacheResource, CacheStorage, DEFAULT_CACHE_ID, LocalResource, SessionResource, getParamCompanion as _getParamCompanion, initMeta as _initMeta, configureLocalStorage, configureSessionStorage, effect, field, getCacheStorage, getLocalStorage, getSessionStorage, input };
+//# sourceMappingURL=storage.js.map