@warp-drive-mirror/experiments 5.10.0-alpha.12 → 5.10.0-alpha.14

package/dist/storage.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @module
+ * @summary Experimental reactive wrappers over localStorage, sessionStorage and the Cache API, with decorators such as
+ * `LocalResource` and `param` that bind class fields to storage or query params.
+ */
 //#region src/storage/cache.d.ts
 export declare const DEFAULT_CACHE_ID = "reactive-cache";
 export interface InternalCacheStorageEvent {
@@ -17,6 +22,9 @@ export interface CacheStorageEvent {
  *
  * 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.
+ *
+ * @summary Experimental `Storage`-compatible interface over the browser Cache API, suited to larger JSON data sets than
+ * localStorage.
  */
 export declare class CacheStorage implements Storage {
   #private;
@@ -65,6 +73,9 @@ export interface ReactiveStorageOptions {
  * Retrieves the singleton instance of the LocalStorage service.
  *
  * If the instance does not already exist, it is created.
+ *
+ * @summary Experimental function that returns the shared reactive wrapper around localStorage, creating it on first
+ * call.
  */
 export declare function getLocalStorage(): ReactiveStorage;
 export declare function getSessionStorage(): ReactiveStorage;
@@ -72,11 +83,17 @@ export declare function getCacheStorage(namespace?: string | null): ReactiveStor
 /**
  * Configure options for the localStorage singleton.
  * Must be called before getLocalStorage() is first invoked.
+ *
+ * @summary Experimental function that sets fallback and quota-handling options for the reactive localStorage singleton
+ * before its first use.
  */
 export declare function configureLocalStorage(options: ReactiveStorageOptions): void;
 /**
  * Configure options for the sessionStorage singleton.
  * Must be called before getSessionStorage() is first invoked.
+ *
+ * @summary Experimental function that sets fallback and quota-handling options for the reactive sessionStorage
+ * singleton before its first use.
  */
 export declare function configureSessionStorage(options: ReactiveStorageOptions): void;
 export type EffectStorageEvent = CacheStorageEvent | StorageEvent;
@@ -97,6 +114,9 @@ export type EffectStorageEvent = CacheStorageEvent | StorageEvent;
  *
  * Route storage-event subscribers through this helper instead of calling
  * `window.addEventListener('storage', ...)` directly.
+ *
+ * @summary Experimental helper that subscribes to storage changes from both native `StorageEvent`s and `CacheStorage`
+ * notifications, returning an unsubscribe function.
  */
 export declare function onStorageEvent(listener: (event: EffectStorageEvent) => void): () => void;
 /**
@@ -104,6 +124,9 @@ export declare function onStorageEvent(listener: (event: EffectStorageEvent) =>
  * that provides signal-based access to storage items and length.
  *
  * Will automatically update when storage events occur in other tabs/windows.
+ *
+ * @summary Experimental signal-backed wrapper around a `Storage` area that makes reads reactive and updates on changes
+ * from other tabs.
  */
 declare class ReactiveStorage implements Storage {
   private _storage;
@@ -148,6 +171,9 @@ declare class ReactiveStorage implements Storage {
 //#region src/storage/query-params.d.ts
 /**
  * Configuration options for fields that are also query parameters
+ *
+ * @summary Experimental config passed to the `param` decorator that describes how a field is serialized to and parsed
+ * from a URL query parameter.
  */
 export interface ParamConfig {
   /**
@@ -174,6 +200,8 @@ export interface ParamConfig {
 /**
  * Creates a {@link ParamConfig} for boolean fields that serialize to '1' or null.
  *
+ * @summary Experimental helper that creates a query-param config serializing a boolean field as '1' when true and
+ * omitting it when false.
  * @returns ParamConfig for boolean fields
  *
  * @example
@@ -187,6 +215,8 @@ export declare function BooleanParam(): ParamConfig;
 /**
  * Creates a {@link ParamConfig} for numeric fields with default value checking.
  *
+ * @summary Experimental helper that creates a query-param config serializing numbers, optionally to a fixed precision,
+ * with an optional default value.
  * @param precision - When given, the number of digits to serialize after the decimal point
  * @param getDefault - Function to get the default value for comparison
  * @returns ParamConfig for number fields
@@ -211,6 +241,8 @@ export declare function NumberParam(precision?: number, getDefault?: (instance:
  * - Compare URL and local values
  * - Determine when to include/exclude params from the URL
  *
+ * @summary Experimental decorator that marks a storage resource field as a URL query parameter, recording how to
+ * serialize it for a router integration.
  * @param config - Configuration for URL serialization/deserialization
  *
  * @example
@@ -260,6 +292,9 @@ interface StorageResourceMeta {
  * Use functions when you want to create more than
  * one instance of a resource type, each with its own
  * persisted data.
+ *
+ * @summary Experimental function type that derives a unique storage key from a storage resource instance, so each
+ * instance persists its own data.
  */
 type KeyFn = (obj: any) => string;
 /**
@@ -304,6 +339,9 @@ declare function getParamCompanion(instance: object, groupControlMap?: Record<st
  *
  * The function will be called once per instance during
  * initialization to determine the unique ID for that instance.
+ *
+ * @summary Experimental class decorator that turns a class into a reactive resource whose fields persist in
+ * localStorage.
  */
 export declare function LocalResource(id: string | KeyFn): ClassDecorator;
 /**
@@ -319,6 +357,9 @@ export declare function LocalResource(id: string | KeyFn): ClassDecorator;
  *
  * The function will be called once per instance during
  * initialization to determine the unique ID for that instance.
+ *
+ * @summary Experimental class decorator that turns a class into a reactive resource whose fields persist in
+ * sessionStorage.
  */
 export declare function SessionResource(id: string | KeyFn): ClassDecorator;
 /**
@@ -339,6 +380,9 @@ export declare function SessionResource(id: string | KeyFn): ClassDecorator;
  * 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.
+ *
+ * @summary Experimental class decorator that turns a class into a reactive resource whose fields persist via the Cache
+ * API and are shared across tabs.
  */
 export declare function CacheResource(id: string | KeyFn, namespace?: string | null): ClassDecorator;
 /**
@@ -371,6 +415,8 @@ export declare function CacheResource(id: string | KeyFn, namespace?: string | n
  * }
  * ```
  *
+ * @summary Experimental decorator that makes a storage resource property a reactive field persisted to local, session,
+ * or cache storage.
  */
 export declare function field(type: "local" | "session" | "cache"): PropertyDecorator;
 export declare function field(target: object, key: string, descriptor?: PropertyDescriptor): void;
@@ -425,6 +471,9 @@ export declare function input(type: "number" | "boolean" | "float"): PropertyDec
  *   }
  * }
  * ```
+ *
+ * @summary Experimental field decorator for storage resources that runs a callback when the stored value changes in
+ * another tab or window.
  */
 export declare function effect(fn: <K>(update: ValueTransition<K>) => void, type?: "local" | "session"): PropertyDecorator;
 //#endregion

package/dist/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","names":[],"sources":["../src/storage/cache.ts","../src/storage/storage.ts","../src/storage/query-params.ts","../src/storage/-private/storage-infra.ts","../src/storage/storage-resource.ts"],"mappings":";qBAEa;iBAKI;EACf;EACA;EACA;EACA;;iBAEe;EACf,aAAa;EACb;EACA;EACA;;;;;;;;qBAkEW,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;;;;iBCtMQ;;;;;EAKf;;;;;EAMA;;;;;EAMA,mBAAmB,aAAa,4BAA4B;;;;;;;wBAgB9C,mBAAmB;wBAOnB,qBAAqB;wBAQrB,gBAAgB,4BAAkC;;;;;wBAelD,sBAAsB,SAAS;;;;;wBAQ/B,wBAAwB,SAAS;YA8BrC,qBAAqB,oBAAoB;;;;;;;;;;;;;;;;;;;wBAoBrC,eAAe,WAAW,OAAO;;;;;;;cAe3C,2BAA2B;UACvB;UACA;UACA;UACA;UAEQ;UACA;UAER;EACR,UAAU,aAAa,KAAK,OAAO;EAKnC,YAAY,SAAS,SAAS,UAAS;;;;MAyCnC;;;;EAOJ,SAAS;;;;EAsBT,QAAQ;;;;EAyBR,QAAQ,aAAa;;;;EA2DrB,WAAW;;;;EAsBX;;;;EAeA,IAAI;;;;;;;iBCpVW;;;;;EAKf,YAAY,gBAAgB;;;;;EAK5B,cAAc,kBAAkB;;;;;;;;;;EAUhC,cAAc;;;;;;;;;;;;;;wBAeA,gBAAgB;;;;;;;;;;;;;;;wBAqBhB,YAAY,oBAAoB,cAAc,uCAAuC;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA+CrF,MAAM,QAAQ,cAAc;;;UCzGlC,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;iBAsG1B,iBAAiB,kBAAkB;;;;;;;;;;;;;;;;;;;iBAgNnC,kBAAkB,kBAAkB,kBAAkB;;;;;;;;;;;;;;;;;wBCjVtD,cAAc,aAAa,QAAQ;;;;;;;;;;;;;;;wBAkBnC,gBAAgB,aAAa,QAAQ;;;;;;;;;;;;;;;;;;;;wBAuBrC,cAAc,aAAa,OAAO,4BAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAmCpE,MAAM,sCAAsC;wBAC5C,MAAM,gBAAgB,aAAa,aAAa;wBAgBhD,MAAM,uCAAuC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAoF7C,OAAO,KAAK,GAAG,QAAQ,gBAAgB,aAAa,6BAA6B"}
+{"version":3,"file":"storage.d.ts","names":[],"sources":["../src/storage/cache.ts","../src/storage/storage.ts","../src/storage/query-params.ts","../src/storage/-private/storage-infra.ts","../src/storage/storage-resource.ts"],"mappings":";;;;;;qBAEa;iBAKI;EACf;EACA;EACA;EACA;;iBAEe;EACf,aAAa;EACb;EACA;EACA;;;;;;;;;;;qBAqEW,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;;;;iBCzMQ;;;;;EAKf;;;;;EAMA;;;;;EAMA,mBAAmB,aAAa,4BAA4B;;;;;;;;;;wBAmB9C,mBAAmB;wBAOnB,qBAAqB;wBAQrB,gBAAgB,4BAAkC;;;;;;;;wBAkBlD,sBAAsB,SAAS;;;;;;;;wBAW/B,wBAAwB,SAAS;YA8BrC,qBAAqB,oBAAoB;;;;;;;;;;;;;;;;;;;;;;wBAuBrC,eAAe,WAAW,OAAO;;;;;;;;;;cAkB3C,2BAA2B;UACvB;UACA;UACA;UACA;UAEQ;UACA;UAER;EACR,UAAU,aAAa,KAAK,OAAO;EAKnC,YAAY,SAAS,SAAS,UAAS;;;;MAyCnC;;;;EAOJ,SAAS;;;;EAsBT,QAAQ;;;;EAyBR,QAAQ,aAAa;;;;EA2DrB,WAAW;;;;EAsBX;;;;EAeA,IAAI;;;;;;;;;;iBChWW;;;;;EAKf,YAAY,gBAAgB;;;;;EAK5B,cAAc,kBAAkB;;;;;;;;;;EAUhC,cAAc;;;;;;;;;;;;;;;;wBAiBA,gBAAgB;;;;;;;;;;;;;;;;;wBAuBhB,YAAY,oBAAoB,cAAc,uCAAuC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAiDrF,MAAM,QAAQ,cAAc;;;UClHlC,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;;;;;;;;;;;;;;KAgBjB,SAAS;;;;;;;iBAaL,SAAS,iBAAiB;iBAsG1B,iBAAiB,kBAAkB;;;;;;;;;;;;;;;;;;;iBAgNnC,kBAAkB,kBAAkB,kBAAkB;;;;;;;;;;;;;;;;;;;;wBCjVtD,cAAc,aAAa,QAAQ;;;;;;;;;;;;;;;;;;wBAqBnC,gBAAgB,aAAa,QAAQ;;;;;;;;;;;;;;;;;;;;;;;wBA0BrC,cAAc,aAAa,OAAO,4BAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAqCpE,MAAM,sCAAsC;wBAC5C,MAAM,gBAAgB,aAAa,aAAa;wBAgBhD,MAAM,uCAAuC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAuF7C,OAAO,KAAK,GAAG,QAAQ,gBAAgB,aAAa,6BAA6B"}

package/dist/storage.js

@@ -81,6 +81,9 @@ StorageEvents.addEventListener("message", handleCacheEvent);
 *
 * 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.
+*
+* @summary Experimental `Storage`-compatible interface over the browser Cache API, suited to larger JSON data sets than
+* localStorage.
 */
 var CacheStorage = class CacheStorage {
 	#cache;
@@ -217,6 +220,9 @@ let sessionStorageOptions = {};
 * Retrieves the singleton instance of the LocalStorage service.
 *
 * If the instance does not already exist, it is created.
+*
+* @summary Experimental function that returns the shared reactive wrapper around localStorage, creating it on first
+* call.
 */
 function getLocalStorage() {
 	if (!localStorageInstance) localStorageInstance = new ReactiveStorage(localStorage, localStorageOptions);
@@ -240,6 +246,9 @@ function getCacheStorage(namespace = null) {
 /**
 * Configure options for the localStorage singleton.
 * Must be called before getLocalStorage() is first invoked.
+*
+* @summary Experimental function that sets fallback and quota-handling options for the reactive localStorage singleton
+* before its first use.
 */
 function configureLocalStorage(options) {
 	localStorageOptions = options;
@@ -247,6 +256,9 @@ function configureLocalStorage(options) {
 /**
 * Configure options for the sessionStorage singleton.
 * Must be called before getSessionStorage() is first invoked.
+*
+* @summary Experimental function that sets fallback and quota-handling options for the reactive sessionStorage
+* singleton before its first use.
 */
 function configureSessionStorage(options) {
 	sessionStorageOptions = options;
@@ -288,6 +300,9 @@ function isStorageUnavailableError(error) {
 *
 * Route storage-event subscribers through this helper instead of calling
 * `window.addEventListener('storage', ...)` directly.
+*
+* @summary Experimental helper that subscribes to storage changes from both native `StorageEvent`s and `CacheStorage`
+* notifications, returning an unsubscribe function.
 */
 function onStorageEvent(listener) {
 	const handler = (event) => {
@@ -301,6 +316,9 @@ function onStorageEvent(listener) {
 * that provides signal-based access to storage items and length.
 *
 * Will automatically update when storage events occur in other tabs/windows.
+*
+* @summary Experimental signal-backed wrapper around a `Storage` area that makes reads reactive and updates on changes
+* from other tabs.
 */
 var ReactiveStorage = class {
 	_storage;
@@ -477,6 +495,9 @@ defineSignal(ReactiveStorage.prototype, "_signals", makeInitializer(() => new Si
 * Use functions when you want to create more than
 * one instance of a resource type, each with its own
 * persisted data.
+*
+* @summary Experimental function type that derives a unique storage key from a storage resource instance, so each
+* instance persists its own data.
 */
 /**
 * Symbol used to store persistence metadata on classes
@@ -761,6 +782,9 @@ function createParamField(companion, fieldName, config, controlFieldName, instan
 *
 * The function will be called once per instance during
 * initialization to determine the unique ID for that instance.
+*
+* @summary Experimental class decorator that turns a class into a reactive resource whose fields persist in
+* localStorage.
 */
 function LocalResource(id) {
 	return _createStorageResource(id, "local-resource", null);
@@ -778,6 +802,9 @@ function LocalResource(id) {
 *
 * The function will be called once per instance during
 * initialization to determine the unique ID for that instance.
+*
+* @summary Experimental class decorator that turns a class into a reactive resource whose fields persist in
+* sessionStorage.
 */
 function SessionResource(id) {
 	return _createStorageResource(id, "session-resource", null);
@@ -800,6 +827,9 @@ function SessionResource(id) {
 * 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.
+*
+* @summary Experimental class decorator that turns a class into a reactive resource whose fields persist via the Cache
+* API and are shared across tabs.
 */
 function CacheResource(id, namespace = null) {
 	return _createStorageResource(id, "cache-resource", namespace);
@@ -834,6 +864,8 @@ function CacheResource(id, namespace = null) {
 * }
 * ```
 *
+* @summary Experimental decorator that makes a storage resource property a reactive field persisted to local, session,
+* or cache storage.
 */
 function field(...args) {
 	if (args.length === 0) {
@@ -928,6 +960,9 @@ function input(type) {
 *   }
 * }
 * ```
+*
+* @summary Experimental field decorator for storage resources that runs a callback when the stored value changes in
+* another tab or window.
 */
 function effect(fn, type) {
 	const overrideType = type === "local" ? "local-storage" : type === "session" ? "session-storage" : null;
@@ -952,10 +987,15 @@ function effect(fn, type) {
 //#region src/storage/query-params.ts
 /**
 * Configuration options for fields that are also query parameters
+*
+* @summary Experimental config passed to the `param` decorator that describes how a field is serialized to and parsed
+* from a URL query parameter.
 */
 /**
 * Creates a {@link ParamConfig} for boolean fields that serialize to '1' or null.
 *
+* @summary Experimental helper that creates a query-param config serializing a boolean field as '1' when true and
+* omitting it when false.
 * @returns ParamConfig for boolean fields
 *
 * @example
@@ -974,6 +1014,8 @@ function BooleanParam() {
 /**
 * Creates a {@link ParamConfig} for numeric fields with default value checking.
 *
+* @summary Experimental helper that creates a query-param config serializing numbers, optionally to a fixed precision,
+* with an optional default value.
 * @param precision - When given, the number of digits to serialize after the decimal point
 * @param getDefault - Function to get the default value for comparison
 * @returns ParamConfig for number fields
@@ -1013,6 +1055,8 @@ function NumberParam(precision, getDefault) {
 * - Compare URL and local values
 * - Determine when to include/exclude params from the URL
 *
+* @summary Experimental decorator that marks a storage resource field as a URL query parameter, recording how to
+* serialize it for a router integration.
 * @param config - Configuration for URL serialization/deserialization
 *
 * @example