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

package/dist/unpkg/dev/storage.js

@@ -0,0 +1,1169 @@
+import { defineSignal as defineSignal$1, makeInitializer, memoized } from '@warp-drive-mirror/core/signals/-leaked';
+import { defineSignal, withSignalStore, entangleSignal, getOrCreateInternalSignal, notifyInternalSignal } from '@warp-drive-mirror/core/signals/-private';
+
+/**
+ * A reactive wrapper around the browser's Map API that provides
+ * granular per-key reactivity via WarpDrive's signal system.
+ */
+class SignalMap {
+  _map = {};
+  // _size is signal-backed via defineSignal below
+
+  _signals = withSignalStore(this._map);
+  subscribe(key) {
+    (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, undefined);
+    const size = this._size;
+    this._size = existing ? size : size + 1;
+    return existing;
+  }
+  notify(key) {
+    (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);
+
+const DEFAULT_CACHE_ID = 'reactive-cache';
+const CACHES = 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 we don't have an instance of the cache in this context
+  // then we don't need to do anything since there are no reactive
+  // subscribers to update
+  if (!cache) {
+    return;
+  }
+
+  // a StorageEvent with a key of null
+  // is a signal that the entire cache should be cleared.
+  if (data.key === null) {
+    cache._data = new Map();
+    emitStorageEvent({
+      storageArea: cache,
+      key: null,
+      oldValue: null,
+      newValue: null
+    });
+    return;
+  }
+  if (data.newValue === null) {
+    // remove the key from the cache
+    cache._data.delete(data.key);
+  } else {
+    // update the cache with the new value
+    cache._data.set(data.key, data.newValue);
+  }
+
+  // emit a StorageEvent to trigger reactive updates in this context
+  emitStorageEvent({
+    storageArea: cache,
+    key: data.key,
+    oldValue: data.oldValue,
+    newValue: data.newValue
+  });
+}
+
+// subscribe to all storage events from other contexts to
+// keep caches in sync
+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.
+ */
+class CacheStorage {
+  #cache;
+  #cacheId;
+  #inititalization;
+  _data = new Map();
+  _nextUpdate = null;
+  _bufferedEvents = [];
+  async #initialize() {
+    const cache = await caches.open(this.#cacheId);
+    this.#cache = cache;
+
+    // Load all existing entries into memory
+    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: key,
+      oldValue: oldValue,
+      newValue: newValue
+    });
+    if (!this._nextUpdate) {
+      this._nextUpdate = window.setTimeout(() => {
+        const events = this._bufferedEvents;
+        this._bufferedEvents = [];
+        this._nextUpdate = null;
+        void serializeToCache(cache, this._data);
+        for (const event of events) {
+          StorageEvents.postMessage(event);
+        }
+      }, 0);
+    }
+  }
+  clear() {
+    this._data = new Map();
+    this.#update(null, null, null);
+  }
+  getItem(key) {
+    return this._data.get(key) ?? null;
+  }
+  key(index) {
+    (test => {
+      if (!test) {
+        throw new Error('ReactiveStorage.key: index must be a number');
+      }
+    })(typeof index === 'number');
+    (test => {
+      if (!test) {
+        throw new Error('ReactiveStorage.key: index must be a non-negative integer');
+      }
+    })(index >= 0 && Number.isInteger(index));
+    (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) {
+    (test => {
+      if (!test) {
+        throw new Error('ReactiveStorage.setItem: key must be a string');
+      }
+    })(typeof key === 'string');
+    (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 new Map();
+    }
+    return response.json().then(json => {
+      if (json.version !== 1) {
+        throw new Error(`Unsupported cache version: ${json.version}`);
+      }
+      return new Map(json.data);
+    });
+  });
+}
+
+let localStorageInstance = null;
+let sessionStorageInstance = null;
+let localStorageOptions = {};
+let sessionStorageOptions = {};
+
+// This pattern enables us to have a singleton service-like
+// instance that also functions as a global singleton that
+// can be imported and used outside of Ember's DI system.
+/**
+ * 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 = new Map();
+function getCacheStorage(namespace = null) {
+  const key = namespace ?? DEFAULT_CACHE_ID;
+  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) {
+    // Most browsers
+    if (error.name === 'QuotaExceededError') return true;
+    // Firefox
+    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) {
+    // Safari private browsing, some security restrictions
+    if (error.name === 'SecurityError') return true;
+    // Some browsers throw this in private mode
+    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.
+ */
+class ReactiveStorage {
+  _storage;
+  _options;
+  _memoryOnly = false;
+  _values = {};
+  _effects = new Map();
+  setEffect(key, fn) {
+    (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)) {
+      // Test if storage is accessible
+      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;
+        }
+      }
+    }
+
+    // bind to localStorage events to trigger reactivity
+    if (!this._memoryOnly) {
+      window.addEventListener('storage', event => {
+        const data = 'detail' in event ? event.detail : event;
+
+        // Only react to changes in the same storage area
+        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) {
+    (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 !== undefined) {
+      return value;
+    }
+
+    // Not yet loaded, fetch from storage, but don't track access
+    const item = this._storage.getItem(keyStr);
+    // this._values[keyStr] = item;
+    return item;
+  }
+
+  /**
+   * Reactive access to Storage contents
+   */
+  getItem(key) {
+    (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 !== undefined) {
+      this._signals.subscribe(keyStr);
+      return value;
+    }
+
+    // Not yet loaded, fetch from storage
+    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) {
+    (test => {
+      if (!test) {
+        throw new Error('ReactiveStorage.setItem: key must be a string');
+      }
+    })(typeof key === 'string');
+    (test => {
+      if (!test) {
+        throw new Error('ReactiveStorage.setItem: value must be a string');
+      }
+    })(typeof value === 'string');
+
+    // Coerce to strings to match Storage API behavior
+    const keyStr = String(key);
+    const valueStr = String(value);
+    const current = this._values[keyStr];
+    if (current === valueStr) {
+      // No change
+      return;
+    }
+
+    // console.trace(`set field ${key} => ${String(value)}`);
+
+    if (this._memoryOnly) {
+      const currentValue = this._values[keyStr];
+      if (currentValue === null || currentValue === undefined) {
+        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) {
+          // Update signal state even though write failed
+          this._values[keyStr] = valueStr;
+          this._signals.notify(keyStr);
+        }
+        if (this._options.onQuotaExceeded) {
+          const result = this._options.onQuotaExceeded(keyStr, valueStr);
+          const retry = result instanceof Promise ? false : result;
+          if (retry) {
+            // Retry the write after callback freed space
+            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) {
+    (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 !== undefined) {
+        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) {
+    (test => {
+      if (!test) {
+        throw new Error('ReactiveStorage.key: index must be a number');
+      }
+    })(typeof index === 'number');
+    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+    this._length; // track length access
+
+    if (this._memoryOnly) {
+      const keys = Object.keys(this._values).filter(k => this._values[k] !== null);
+      return keys[index] ?? null;
+    }
+    return this._storage.key(index);
+  }
+}
+defineSignal$1(ReactiveStorage.prototype, '_length', 0);
+defineSignal$1(ReactiveStorage.prototype, '_signals', makeInitializer(() => new SignalMap()));
+
+/**
+ * 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.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+/**
+ * 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: new Map(),
+      initializers: new Map(),
+      paramConfigs: null,
+      paramCompanion: null,
+      instances: null,
+      typeOverrides: null
+    };
+    target[PERSISTED_RESOURCE_META] = meta;
+  }
+  return meta;
+}
+function useMeta(meta, instance) {
+  // If a primary key function is defined, use it to generate
+  // a unique ID for this instance
+  if (meta.id === '' && meta.pkFn) {
+    // we are in an instance context
+    meta.instances = meta.instances ?? new WeakMap();
+    let instanceMeta = meta.instances.get(instance);
+    if (!instanceMeta) {
+      instanceMeta = {
+        ...meta
+      };
+      const pk = meta.pkFn(instance);
+      (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;
+  }
+  (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 type = overrideType || meta.type;
+  const storage = getStorage(type, meta.namespace);
+  const stored = storage.getItem(keyFor(meta, key));
+  if (stored) {
+    return JSON.parse(stored);
+  } else {
+    // No stored value, check for initializer
+    const initializer = meta.initializers.get(key);
+    if (initializer) {
+      const value = initializer.call(instance);
+      if (value !== undefined) {
+        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) {
+  const type = overrideType || meta.type;
+  const storage = getStorage(type, meta.namespace);
+  storage.setItem(keyFor(meta, key), JSON.stringify(value));
+}
+function getResourceMeta(target) {
+  const meta = target[PERSISTED_RESOURCE_META];
+  (test => {
+    if (!test) {
+      throw new Error('StorageResourceMeta not found on target. Did you forget to use the @LocalResource() or @SessionResource() decorator?');
+    }
+  })(meta !== undefined);
+  return meta;
+}
+function _createStorageResource(id, type, namespace) {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  return function (target) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+    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) {
+      // for dynamic instances, we install effects only once
+      // fields have been defined and a key created for the
+      // instance.
+      // for this, we defer effect installation until
+      // until object instantiation by wrapping the constructor
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+      const originalConstructor = target.prototype.constructor;
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      target.prototype.constructor = function DynamicStorageInitializer(...args) {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-call, new-cap
+        const instance = new originalConstructor(...args);
+        void installEffectsForDynamicInstance(meta, instance);
+        return instance;
+      };
+    }
+    if (!('toJSON' in target.prototype)) {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      target.prototype.toJSON = function () {
+        const instanceMeta = useMeta(meta, this);
+        // we only serialize the id and any localStorage fields, not sessionStorage fields.
+        const isLocalResource = meta.type === 'local-resource' || meta.type === 'cache-resource';
+        const fields = isLocalResource ? new Set(meta.fields.keys()) : 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') {
+      void 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 || new Map();
+    meta.typeOverrides.set(key, overrideType);
+  }
+  // @ts-expect-error initializer does exist
+  const initializer = orgDesc?.initializer || null;
+  meta.initializers.set(key, initializer);
+  const desc = {
+    configurable: true,
+    enumerable: true,
+    get() {
+      return getField(this, useMeta(meta, this), key, overrideType);
+    },
+    set(value) {
+      setField(useMeta(meta, this), key, value, overrideType);
+    }
+  };
+  return memoized(target, key, desc);
+}
+async function installEffect(meta, key) {
+  await Promise.resolve();
+  const effect = meta.fields.get(key);
+  const storage = getStorage(meta.type, meta.namespace);
+  storage.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);
+
+  // Return existing companion if already created
+  if (instanceMeta.paramCompanion) {
+    return instanceMeta.paramCompanion;
+  }
+
+  // Create new companion object
+  const companion = {};
+  instanceMeta.paramCompanion = companion;
+
+  // Install a property for each param
+  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) {
+  // if the url value for the control param is `null` we are inactive
+  const controlValue = companion[controlFieldName];
+  return controlValue !== 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 !== undefined) {
+    return defaultValue;
+  }
+  const initializer = meta.initializers.get(fieldName);
+  if (initializer) {
+    const initValue = initializer.call(instance);
+    if (initValue !== undefined) {
+      return initValue;
+    }
+  }
+  return null;
+}
+function createParamField(companion, fieldName, config, controlFieldName, instance, meta) {
+  const desc = {
+    configurable: true,
+    enumerable: true,
+    get() {
+      // Mark as initialized on first access, but continue with normal logic
+      if (!config.initialized) {
+        config.initialized = true;
+        return null;
+      }
+
+      // Next, check if this param is part of a group and if its control param is active
+      // If not active, return null to indicate inactive state
+      if (controlFieldName && !isActiveGroupParam(companion, controlFieldName)) {
+        return null;
+      }
+
+      // Next, check if the currently stored value is the default
+      // value. If so, return null to indicate inactive state
+      const defaultValue = getParamFieldDefaultValue(meta, config, fieldName, instance);
+      const rawValue = instance[fieldName];
+      if (rawValue === defaultValue) {
+        return null;
+      }
+
+      // Serialize to URL format
+      const serialized = config.serialize(rawValue, instance);
+
+      // Return null if serialization returns empty, indicating no URL representation
+      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 null or empty, skip deserialization
+      if (!urlValue) {
+        return;
+      }
+      const rawValue = instance[fieldName];
+
+      // Compare incoming URL value with existing local value
+      const rawValueSerialized = config.serialize(rawValue, instance);
+      if (rawValueSerialized === urlValue) {
+        // No change
+        return;
+      }
+
+      // Deserialize from URL format
+      const newRawValue = config.deserialize(urlValue, instance);
+
+      // Update the storage resource
+      instance[fieldName] = newRawValue;
+    }
+  };
+  memoized(companion, fieldName, desc);
+  Object.defineProperty(companion, fieldName, desc);
+}
+
+/**
+ * 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) {
+    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) {
+  (test => {
+    if (!test) {
+      throw new Error('input decorator requires a valid type argument');
+    }
+  })(['number', 'boolean', 'float'].includes(type));
+  return function (target, key, desc) {
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    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 === undefined ? 0 : 1;
+          break;
+        default:
+          (test => {
+            {
+              throw new Error(`Unsupported input type: ${type}`);
+            }
+          })();
+      }
+      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);
+
+    // only install the effect if we are not in a primary-keyed instance context
+    if (meta.pkFn === null) void 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);
+      }
+    };
+  };
+}
+
+export { CacheResource, CacheStorage, DEFAULT_CACHE_ID, LocalResource, SessionResource, getParamCompanion as _getParamCompanion, initMeta as _initMeta, configureLocalStorage, configureSessionStorage, effect, field, getCacheStorage, getLocalStorage, getSessionStorage, input };