@studiometa/js-toolkit 3.9.0 → 4.0.0-alpha.1

package/dist/services/until.js

@@ -0,0 +1,25 @@
+//#region src/services/until.ts
+/**
+* Wait for current or future service props that satisfy a predicate.
+*
+* The subscription is released before resolution. Object props are copied because services can reuse them.
+* @link https://js-toolkit-v4.studiometa.dev/api/services/until.html
+*/
+function until(service, predicate) {
+	return new Promise((resolve) => {
+		let unsubscribe = null;
+		let isSettled = false;
+		const check = (props) => {
+			if (isSettled || !predicate(props)) return;
+			isSettled = true;
+			unsubscribe?.();
+			resolve(typeof props === "object" && props !== null ? { ...props } : props);
+		};
+		unsubscribe = service.subscribe(check, { immediate: true });
+		if (isSettled) unsubscribe();
+	});
+}
+//#endregion
+export { until };
+
+//# sourceMappingURL=until.js.map

package/dist/services/until.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"until.js","names":[],"sources":["../../src/services/until.ts"],"sourcesContent":["import type { Service, Unsubscribe } from './service.js';\n\n/**\n * Wait for current or future service props that satisfy a predicate.\n *\n * The subscription is released before resolution. Object props are copied because services can reuse them.\n * @link https://js-toolkit-v4.studiometa.dev/api/services/until.html\n */\nexport function until<T>(service: Service<T>, predicate: (props: T) => boolean): Promise<T> {\n  return new Promise<T>((resolve) => {\n    let unsubscribe: Unsubscribe | null = null;\n    let isSettled = false;\n\n    const check = (props: T) => {\n      if (isSettled || !predicate(props)) {\n        return;\n      }\n      isSettled = true;\n      // Immediate delivery can match before `subscribe()` returns its release function.\n      unsubscribe?.();\n      // Copy objects before the service can reuse them. Preserve primitive values.\n      resolve(typeof props === 'object' && props !== null ? { ...props } : props);\n    };\n\n    unsubscribe = service.subscribe(check, { immediate: true });\n    if (isSettled) {\n      unsubscribe();\n    }\n  });\n}\n"],"mappings":";;;;;;;AAQA,SAAgB,MAAS,SAAqB,WAA8C;CAC1F,OAAO,IAAI,SAAY,YAAY;EACjC,IAAI,cAAkC;EACtC,IAAI,YAAY;EAEhB,MAAM,SAAS,UAAa;GAC1B,IAAI,aAAa,CAAC,UAAU,KAAK,GAC/B;GAEF,YAAY;GAEZ,cAAc;GAEd,QAAQ,OAAO,UAAU,YAAY,UAAU,OAAO,EAAE,GAAG,MAAM,IAAI,KAAK;EAC5E;EAEA,cAAc,QAAQ,UAAU,OAAO,EAAE,WAAW,KAAK,CAAC;EAC1D,IAAI,WACF,YAAY;CAEhB,CAAC;AACH"}

package/dist/shared-runtime.d.ts

@@ -0,0 +1,8 @@
+//#region src/shared-runtime.d.ts
+/**
+ * Reuse a revision-checked state slot across evaluated package copies.
+ * @internal
+ */
+declare function getSharedRuntimeSlot<T>(name: string, revision: number, initialize: () => T, host?: object): T;
+//#endregion
+export { getSharedRuntimeSlot };

package/dist/shared-runtime.js

@@ -0,0 +1,43 @@
+//#region src/shared-runtime.ts
+const RUNTIME_KEY = Symbol.for("@studiometa/js-toolkit/runtime");
+const RUNTIME_REVISION = 1;
+const DIAGNOSTIC_PREFIX = "[@studiometa/js-toolkit/runtime]";
+function incompatible(message) {
+	throw new Error(`${DIAGNOSTIC_PREFIX} ${message}`);
+}
+function runtimeFor(host) {
+	const globalObject = host;
+	const existing = globalObject[RUNTIME_KEY];
+	if (existing === void 0) {
+		const runtime = {
+			revision: RUNTIME_REVISION,
+			slots: /* @__PURE__ */ new Map()
+		};
+		globalObject[RUNTIME_KEY] = runtime;
+		return runtime;
+	}
+	if (typeof existing !== "object" || existing === null || existing.revision !== RUNTIME_REVISION || !(existing.slots instanceof Map)) return incompatible(`An incompatible value already owns globalThis[Symbol.for('@studiometa/js-toolkit/runtime')].`);
+	return existing;
+}
+/**
+* Reuse a revision-checked state slot across evaluated package copies.
+* @internal
+*/
+function getSharedRuntimeSlot(name, revision, initialize, host = globalThis) {
+	const runtime = runtimeFor(host);
+	const existing = runtime.slots.get(name);
+	if (existing) {
+		if (existing.revision !== revision) return incompatible(`Shared slot "${name}" has revision ${existing.revision}; revision ${revision} is required.`);
+		return existing.value;
+	}
+	const value = initialize();
+	runtime.slots.set(name, {
+		revision,
+		value
+	});
+	return value;
+}
+//#endregion
+export { getSharedRuntimeSlot };
+
+//# sourceMappingURL=shared-runtime.js.map

package/dist/shared-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-runtime.js","names":[],"sources":["../src/shared-runtime.ts"],"sourcesContent":["const RUNTIME_KEY = Symbol.for('@studiometa/js-toolkit/runtime');\nconst RUNTIME_REVISION = 1;\nconst DIAGNOSTIC_PREFIX = '[@studiometa/js-toolkit/runtime]';\n\ninterface SharedRuntimeSlot {\n  readonly revision: number;\n  readonly value: unknown;\n}\n\ninterface SharedRuntime {\n  readonly revision: typeof RUNTIME_REVISION;\n  readonly slots: Map<string, SharedRuntimeSlot>;\n}\n\nfunction incompatible(message: string): never {\n  throw new Error(`${DIAGNOSTIC_PREFIX} ${message}`);\n}\n\nfunction runtimeFor(host: object): SharedRuntime {\n  const globalObject = host as Record<PropertyKey, unknown>;\n  const existing = globalObject[RUNTIME_KEY];\n\n  if (existing === undefined) {\n    const runtime: SharedRuntime = {\n      revision: RUNTIME_REVISION,\n      slots: new Map(),\n    };\n    globalObject[RUNTIME_KEY] = runtime;\n    return runtime;\n  }\n\n  if (\n    typeof existing !== 'object' ||\n    existing === null ||\n    (existing as Partial<SharedRuntime>).revision !== RUNTIME_REVISION ||\n    !((existing as Partial<SharedRuntime>).slots instanceof Map)\n  ) {\n    return incompatible(\n      `An incompatible value already owns globalThis[Symbol.for('@studiometa/js-toolkit/runtime')].`,\n    );\n  }\n\n  return existing as SharedRuntime;\n}\n\n/**\n * Reuse a revision-checked state slot across evaluated package copies.\n * @internal\n */\nexport function getSharedRuntimeSlot<T>(\n  name: string,\n  revision: number,\n  initialize: () => T,\n  host: object = globalThis,\n): T {\n  const runtime = runtimeFor(host);\n  const existing = runtime.slots.get(name);\n\n  if (existing) {\n    if (existing.revision !== revision) {\n      return incompatible(\n        `Shared slot \"${name}\" has revision ${existing.revision}; revision ${revision} is required.`,\n      );\n    }\n    return existing.value as T;\n  }\n\n  const value = initialize();\n  runtime.slots.set(name, { revision, value });\n  return value;\n}\n"],"mappings":";AAAA,MAAM,cAAc,OAAO,IAAI,gCAAgC;AAC/D,MAAM,mBAAmB;AACzB,MAAM,oBAAoB;AAY1B,SAAS,aAAa,SAAwB;CAC5C,MAAM,IAAI,MAAM,GAAG,kBAAkB,GAAG,SAAS;AACnD;AAEA,SAAS,WAAW,MAA6B;CAC/C,MAAM,eAAe;CACrB,MAAM,WAAW,aAAa;CAE9B,IAAI,aAAa,KAAA,GAAW;EAC1B,MAAM,UAAyB;GAC7B,UAAU;GACV,uBAAO,IAAI,IAAI;EACjB;EACA,aAAa,eAAe;EAC5B,OAAO;CACT;CAEA,IACE,OAAO,aAAa,YACpB,aAAa,QACZ,SAAoC,aAAa,oBAClD,EAAG,SAAoC,iBAAiB,MAExD,OAAO,aACL,8FACF;CAGF,OAAO;AACT;;;;;AAMA,SAAgB,qBACd,MACA,UACA,YACA,OAAe,YACZ;CACH,MAAM,UAAU,WAAW,IAAI;CAC/B,MAAM,WAAW,QAAQ,MAAM,IAAI,IAAI;CAEvC,IAAI,UAAU;EACZ,IAAI,SAAS,aAAa,UACxB,OAAO,aACL,gBAAgB,KAAK,iBAAiB,SAAS,SAAS,aAAa,SAAS,cAChF;EAEF,OAAO,SAAS;CAClB;CAEA,MAAM,QAAQ,WAAW;CACzB,QAAQ,MAAM,IAAI,MAAM;EAAE;EAAU;CAAM,CAAC;CAC3C,OAAO;AACT"}

package/dist/storage/createStorage.d.ts

@@ -0,0 +1,12 @@
+import { StorageInstance, StorageOptions } from "./types.js";
+//#region src/storage/createStorage.d.ts
+/**
+ * Build a storage over a provider.
+ *
+ * Values are namespaced by `prefix`, serialized on the way in and out, and
+ * observable per key.
+ * @link https://js-toolkit-v4.studiometa.dev/api/storage/createStorage.html
+ */
+declare function createStorage<T extends object = Record<string, unknown>>(options?: StorageOptions): StorageInstance<T>;
+//#endregion
+export { createStorage };

package/dist/storage/createStorage.js

@@ -0,0 +1,120 @@
+import { reportDiagnostic } from "../diagnostics.js";
+import { signal } from "../context.js";
+import { localStorageProvider } from "./providers.js";
+import { jsonSerializer } from "./serializers.js";
+import { useStorageSync } from "./sync.js";
+//#region src/storage/createStorage.ts
+/**
+* Build a storage over a provider.
+*
+* Values are namespaced by `prefix`, serialized on the way in and out, and
+* observable per key.
+* @link https://js-toolkit-v4.studiometa.dev/api/storage/createStorage.html
+*/
+function createStorage(options = {}) {
+	const { provider = localStorageProvider, serializer = jsonSerializer, prefix = "" } = options;
+	/**
+	* Signals hold the *serialized* value, so identity comparison is the right
+	* one: two writes of an equal value settle to the same string and notify
+	* once, where the deserialized objects would be distinct every time.
+	*
+	* They are created on first subscription — an unobserved key needs no state.
+	*/
+	const signals = /* @__PURE__ */ new Map();
+	let subscriberCount = 0;
+	let releases = [];
+	function resolveKey(key) {
+		return `${prefix}${key}`;
+	}
+	function decode(key, raw) {
+		if (raw === null) return;
+		try {
+			return serializer.deserialize(raw);
+		} catch (error) {
+			reportDiagnostic("storage.deserialize-failed", `The value stored under "${resolveKey(key)}" could not be deserialized.`, error);
+			return;
+		}
+	}
+	/** Publish what the provider holds now. Unchanged keys notify nobody. */
+	function refresh() {
+		for (const [key, keySignal] of signals) keySignal.value = provider.get(resolveKey(key));
+	}
+	function retainSync() {
+		subscriberCount += 1;
+		if (subscriberCount > 1) return;
+		releases = (provider.syncEvents ?? []).map((name) => useStorageSync(name).subscribe(refresh));
+	}
+	function releaseSync() {
+		if (subscriberCount === 0) return;
+		subscriberCount -= 1;
+		if (subscriberCount > 0) return;
+		for (const release of releases) release();
+		releases = [];
+	}
+	function publish(key, raw) {
+		const keySignal = signals.get(key);
+		if (keySignal) keySignal.value = raw;
+	}
+	return {
+		get: (key, defaultValue) => {
+			const value = decode(key, provider.get(resolveKey(key)));
+			return value === void 0 ? defaultValue : value;
+		},
+		set(key, value) {
+			let raw;
+			try {
+				raw = serializer.serialize(value);
+			} catch (error) {
+				reportDiagnostic("storage.serialize-failed", `The value for "${resolveKey(key)}" could not be serialized.`, error);
+				return;
+			}
+			provider.set(resolveKey(key), raw);
+			publish(key, raw);
+		},
+		delete(key) {
+			provider.remove(resolveKey(key));
+			publish(key, null);
+		},
+		has(key) {
+			return provider.has(resolveKey(key));
+		},
+		keys() {
+			const keys = provider.keys();
+			if (!prefix) return keys;
+			return keys.filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length));
+		},
+		clear() {
+			if (prefix) {
+				for (const key of provider.keys()) if (key.startsWith(prefix)) provider.remove(key);
+			} else provider.clear();
+			for (const keySignal of signals.values()) keySignal.value = null;
+		},
+		subscribe(key, callback, { immediate = false } = {}) {
+			const name = key;
+			let keySignal = signals.get(name);
+			if (!keySignal) {
+				keySignal = signal(provider.get(resolveKey(name)));
+				signals.set(name, keySignal);
+			}
+			retainSync();
+			const unsubscribe = keySignal.subscribe((raw) => callback(decode(name, raw)), { immediate });
+			let isReleased = false;
+			return () => {
+				if (isReleased) return;
+				isReleased = true;
+				unsubscribe();
+				releaseSync();
+			};
+		},
+		destroy() {
+			for (const release of releases) release();
+			releases = [];
+			subscriberCount = 0;
+			signals.clear();
+		}
+	};
+}
+//#endregion
+export { createStorage };
+
+//# sourceMappingURL=createStorage.js.map

package/dist/storage/createStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createStorage.js","names":[],"sources":["../../src/storage/createStorage.ts"],"sourcesContent":["import { signal, type Signal } from '../context.js';\nimport { reportDiagnostic } from '../diagnostics.js';\nimport type { Unsubscribe } from '../services/service.js';\nimport { localStorageProvider } from './providers.js';\nimport { jsonSerializer } from './serializers.js';\nimport { useStorageSync } from './sync.js';\nimport type { StorageInstance, StorageOptions } from './types.js';\n\n/**\n * Build a storage over a provider.\n *\n * Values are namespaced by `prefix`, serialized on the way in and out, and\n * observable per key.\n * @link https://js-toolkit-v4.studiometa.dev/api/storage/createStorage.html\n */\nexport function createStorage<T extends object = Record<string, unknown>>(\n  options: StorageOptions = {},\n): StorageInstance<T> {\n  const { provider = localStorageProvider, serializer = jsonSerializer, prefix = '' } = options;\n\n  /**\n   * Signals hold the *serialized* value, so identity comparison is the right\n   * one: two writes of an equal value settle to the same string and notify\n   * once, where the deserialized objects would be distinct every time.\n   *\n   * They are created on first subscription — an unobserved key needs no state.\n   */\n  const signals = new Map<string, Signal<string | null>>();\n  let subscriberCount = 0;\n  let releases: Unsubscribe[] = [];\n\n  function resolveKey(key: string): string {\n    return `${prefix}${key}`;\n  }\n\n  function decode(key: string, raw: string | null): unknown {\n    if (raw === null) {\n      return undefined;\n    }\n    try {\n      return serializer.deserialize(raw);\n    } catch (error) {\n      // A stored value that cannot be read is not the same as a missing one,\n      // even though both fall back to the default.\n      reportDiagnostic(\n        'storage.deserialize-failed',\n        `The value stored under \"${resolveKey(key)}\" could not be deserialized.`,\n        error,\n      );\n      return undefined;\n    }\n  }\n\n  /** Publish what the provider holds now. Unchanged keys notify nobody. */\n  function refresh(): void {\n    for (const [key, keySignal] of signals) {\n      keySignal.value = provider.get(resolveKey(key));\n    }\n  }\n\n  function retainSync(): void {\n    subscriberCount += 1;\n    if (subscriberCount > 1) {\n      return;\n    }\n    releases = (provider.syncEvents ?? []).map((name) => useStorageSync(name).subscribe(refresh));\n  }\n\n  function releaseSync(): void {\n    // `destroy()` resets the count, so a late unsubscribe must not go negative.\n    if (subscriberCount === 0) {\n      return;\n    }\n    subscriberCount -= 1;\n    if (subscriberCount > 0) {\n      return;\n    }\n    for (const release of releases) {\n      release();\n    }\n    releases = [];\n  }\n\n  function publish(key: string, raw: string | null): void {\n    const keySignal = signals.get(key);\n    if (keySignal) {\n      keySignal.value = raw;\n    }\n  }\n\n  return {\n    // Asserted because one implementation cannot satisfy both overloads: the\n    // two differ only in whether a default rules `undefined` out.\n    get: (key: string, defaultValue?: unknown) => {\n      const value = decode(key, provider.get(resolveKey(key)));\n      return value === undefined ? defaultValue : value;\n    },\n\n    set(key, value) {\n      let raw: string;\n      try {\n        raw = serializer.serialize(value);\n      } catch (error) {\n        reportDiagnostic(\n          'storage.serialize-failed',\n          `The value for \"${resolveKey(key as string)}\" could not be serialized.`,\n          error,\n        );\n        return;\n      }\n      provider.set(resolveKey(key as string), raw);\n      publish(key as string, raw);\n    },\n\n    delete(key) {\n      provider.remove(resolveKey(key as string));\n      publish(key as string, null);\n    },\n\n    has(key) {\n      return provider.has(resolveKey(key as string));\n    },\n\n    keys() {\n      const keys = provider.keys();\n      if (!prefix) {\n        return keys as (keyof T)[];\n      }\n      return keys\n        .filter((key) => key.startsWith(prefix))\n        .map((key) => key.slice(prefix.length) as keyof T);\n    },\n\n    clear() {\n      if (prefix) {\n        // A prefixed storage owns its namespace, not the whole provider.\n        for (const key of provider.keys()) {\n          if (key.startsWith(prefix)) {\n            provider.remove(key);\n          }\n        }\n      } else {\n        provider.clear();\n      }\n      for (const keySignal of signals.values()) {\n        keySignal.value = null;\n      }\n    },\n\n    subscribe(key, callback, { immediate = false } = {}) {\n      const name = key as string;\n      let keySignal = signals.get(name);\n      if (!keySignal) {\n        keySignal = signal(provider.get(resolveKey(name)));\n        signals.set(name, keySignal);\n      }\n\n      retainSync();\n\n      const unsubscribe = keySignal.subscribe((raw) => callback(decode(name, raw) as never), {\n        immediate,\n      });\n\n      let isReleased = false;\n      return () => {\n        // Unsubscribe is idempotent; the sync refcount must not go negative.\n        if (isReleased) {\n          return;\n        }\n        isReleased = true;\n        unsubscribe();\n        releaseSync();\n      };\n    },\n\n    destroy() {\n      for (const release of releases) {\n        release();\n      }\n      releases = [];\n      subscriberCount = 0;\n      signals.clear();\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/storage/index.d.ts

@@ -0,0 +1,28 @@
+import { StorageInstance, StorageOptions, StorageProvider, StorageSerializer, StorageSubscribeOptions, UrlProviderOptions } from "./types.js";
+import { createStorage } from "./createStorage.js";
+import { createFallbackProvider, createMemoryStorageProvider, createUrlSearchParamsInHashProvider, createUrlSearchParamsProvider, localStorageProvider, memoryStorageProvider, sessionStorageProvider, urlSearchParamsInHashProvider, urlSearchParamsProvider } from "./providers.js";
+import { jsonSerializer } from "./serializers.js";
+//#region src/storage/index.d.ts
+type PresetOptions = Omit<StorageOptions, 'provider'>;
+/**
+ * A storage over `localStorage`.
+ * @link https://js-toolkit-v4.studiometa.dev/api/storage/presets.html
+ */
+declare function createLocalStorage<T extends object = Record<string, unknown>>(options?: PresetOptions): StorageInstance<T>;
+/**
+ * A storage over `sessionStorage`.
+ * @link https://js-toolkit-v4.studiometa.dev/api/storage/presets.html
+ */
+declare function createSessionStorage<T extends object = Record<string, unknown>>(options?: PresetOptions): StorageInstance<T>;
+/**
+ * A storage over the query string.
+ * @link https://js-toolkit-v4.studiometa.dev/api/storage/presets.html
+ */
+declare function createUrlSearchParamsStorage<T extends object = Record<string, unknown>>(options?: PresetOptions & UrlProviderOptions): StorageInstance<T>;
+/**
+ * A storage over search params held in the hash.
+ * @link https://js-toolkit-v4.studiometa.dev/api/storage/presets.html
+ */
+declare function createUrlSearchParamsInHashStorage<T extends object = Record<string, unknown>>(options?: PresetOptions & UrlProviderOptions): StorageInstance<T>;
+//#endregion
+export { type StorageInstance, type StorageOptions, type StorageProvider, type StorageSerializer, type StorageSubscribeOptions, type UrlProviderOptions, createFallbackProvider, createLocalStorage, createMemoryStorageProvider, createSessionStorage, createStorage, createUrlSearchParamsInHashProvider, createUrlSearchParamsInHashStorage, createUrlSearchParamsProvider, createUrlSearchParamsStorage, jsonSerializer, localStorageProvider, memoryStorageProvider, sessionStorageProvider, urlSearchParamsInHashProvider, urlSearchParamsProvider };

package/dist/storage/index.js

@@ -0,0 +1,50 @@
+import { createFallbackProvider, createMemoryStorageProvider, createUrlSearchParamsInHashProvider, createUrlSearchParamsProvider, localStorageProvider, memoryStorageProvider, sessionStorageProvider, urlSearchParamsInHashProvider, urlSearchParamsProvider } from "./providers.js";
+import { jsonSerializer } from "./serializers.js";
+import { createStorage } from "./createStorage.js";
+//#region src/storage/index.ts
+/**
+* A storage over `localStorage`.
+* @link https://js-toolkit-v4.studiometa.dev/api/storage/presets.html
+*/
+function createLocalStorage(options) {
+	return createStorage({
+		...options,
+		provider: localStorageProvider
+	});
+}
+/**
+* A storage over `sessionStorage`.
+* @link https://js-toolkit-v4.studiometa.dev/api/storage/presets.html
+*/
+function createSessionStorage(options) {
+	return createStorage({
+		...options,
+		provider: sessionStorageProvider
+	});
+}
+/**
+* A storage over the query string.
+* @link https://js-toolkit-v4.studiometa.dev/api/storage/presets.html
+*/
+function createUrlSearchParamsStorage(options) {
+	const { push, ...storageOptions } = options ?? {};
+	return createStorage({
+		...storageOptions,
+		provider: push ? createUrlSearchParamsProvider({ push }) : urlSearchParamsProvider
+	});
+}
+/**
+* A storage over search params held in the hash.
+* @link https://js-toolkit-v4.studiometa.dev/api/storage/presets.html
+*/
+function createUrlSearchParamsInHashStorage(options) {
+	const { push, ...storageOptions } = options ?? {};
+	return createStorage({
+		...storageOptions,
+		provider: push ? createUrlSearchParamsInHashProvider({ push }) : urlSearchParamsInHashProvider
+	});
+}
+//#endregion
+export { createFallbackProvider, createLocalStorage, createMemoryStorageProvider, createSessionStorage, createStorage, createUrlSearchParamsInHashProvider, createUrlSearchParamsInHashStorage, createUrlSearchParamsProvider, createUrlSearchParamsStorage, jsonSerializer, localStorageProvider, memoryStorageProvider, sessionStorageProvider, urlSearchParamsInHashProvider, urlSearchParamsProvider };
+
+//# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/storage/index.ts"],"sourcesContent":["import { createStorage } from './createStorage.js';\nimport {\n  createUrlSearchParamsInHashProvider,\n  createUrlSearchParamsProvider,\n  localStorageProvider,\n  sessionStorageProvider,\n  urlSearchParamsInHashProvider,\n  urlSearchParamsProvider,\n} from './providers.js';\nimport type { StorageInstance, StorageOptions, UrlProviderOptions } from './types.js';\n\nexport { createStorage } from './createStorage.js';\nexport {\n  createFallbackProvider,\n  createMemoryStorageProvider,\n  createUrlSearchParamsInHashProvider,\n  createUrlSearchParamsProvider,\n  localStorageProvider,\n  memoryStorageProvider,\n  sessionStorageProvider,\n  urlSearchParamsInHashProvider,\n  urlSearchParamsProvider,\n} from './providers.js';\nexport { jsonSerializer } from './serializers.js';\nexport type {\n  StorageInstance,\n  StorageOptions,\n  StorageProvider,\n  StorageSerializer,\n  StorageSubscribeOptions,\n  UrlProviderOptions,\n} from './types.js';\n\ntype PresetOptions = Omit<StorageOptions, 'provider'>;\n\n/**\n * A storage over `localStorage`.\n * @link https://js-toolkit-v4.studiometa.dev/api/storage/presets.html\n */\nexport function createLocalStorage<T extends object = Record<string, unknown>>(\n  options?: PresetOptions,\n): StorageInstance<T> {\n  return createStorage<T>({ ...options, provider: localStorageProvider });\n}\n\n/**\n * A storage over `sessionStorage`.\n * @link https://js-toolkit-v4.studiometa.dev/api/storage/presets.html\n */\nexport function createSessionStorage<T extends object = Record<string, unknown>>(\n  options?: PresetOptions,\n): StorageInstance<T> {\n  return createStorage<T>({ ...options, provider: sessionStorageProvider });\n}\n\n/**\n * A storage over the query string.\n * @link https://js-toolkit-v4.studiometa.dev/api/storage/presets.html\n */\nexport function createUrlSearchParamsStorage<T extends object = Record<string, unknown>>(\n  options?: PresetOptions & UrlProviderOptions,\n): StorageInstance<T> {\n  const { push, ...storageOptions } = options ?? {};\n  return createStorage<T>({\n    ...storageOptions,\n    provider: push ? createUrlSearchParamsProvider({ push }) : urlSearchParamsProvider,\n  });\n}\n\n/**\n * A storage over search params held in the hash.\n * @link https://js-toolkit-v4.studiometa.dev/api/storage/presets.html\n */\nexport function createUrlSearchParamsInHashStorage<T extends object = Record<string, unknown>>(\n  options?: PresetOptions & UrlProviderOptions,\n): StorageInstance<T> {\n  const { push, ...storageOptions } = options ?? {};\n  return createStorage<T>({\n    ...storageOptions,\n    provider: push ? createUrlSearchParamsInHashProvider({ push }) : urlSearchParamsInHashProvider,\n  });\n}\n"],"mappings":";;;;;;;;AAuCA,SAAgB,mBACd,SACoB;CACpB,OAAO,cAAiB;EAAE,GAAG;EAAS,UAAU;CAAqB,CAAC;AACxE;;;;;AAMA,SAAgB,qBACd,SACoB;CACpB,OAAO,cAAiB;EAAE,GAAG;EAAS,UAAU;CAAuB,CAAC;AAC1E;;;;;AAMA,SAAgB,6BACd,SACoB;CACpB,MAAM,EAAE,MAAM,GAAG,mBAAmB,WAAW,CAAC;CAChD,OAAO,cAAiB;EACtB,GAAG;EACH,UAAU,OAAO,8BAA8B,EAAE,KAAK,CAAC,IAAI;CAC7D,CAAC;AACH;;;;;AAMA,SAAgB,mCACd,SACoB;CACpB,MAAM,EAAE,MAAM,GAAG,mBAAmB,WAAW,CAAC;CAChD,OAAO,cAAiB;EACtB,GAAG;EACH,UAAU,OAAO,oCAAoC,EAAE,KAAK,CAAC,IAAI;CACnE,CAAC;AACH"}

package/dist/storage/providers.d.ts

@@ -0,0 +1,52 @@
+import { StorageProvider, UrlProviderOptions } from "./types.js";
+//#region src/storage/providers.d.ts
+/**
+ * A provider backed by a `Map`, for tests and for opting out of persistence.
+ * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+ */
+declare function createMemoryStorageProvider(): StorageProvider;
+/**
+ * Read from the first provider holding the key; write through to all of them.
+ * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+ */
+declare function createFallbackProvider(...providers: StorageProvider[]): StorageProvider;
+/**
+ * Store values in the query string.
+ * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+ */
+declare function createUrlSearchParamsProvider(options?: UrlProviderOptions): StorageProvider;
+/**
+ * Store values in the hash, as search params.
+ *
+ * Back and forward navigation announces itself as `hashchange`, and as
+ * `popstate` when the write replaced the entry rather than pushing one.
+ * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+ */
+declare function createUrlSearchParamsInHashProvider(options?: UrlProviderOptions): StorageProvider;
+/**
+ * A storage provider over `localStorage`.
+ * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+ */
+declare const localStorageProvider: StorageProvider;
+/**
+ * A storage provider over `sessionStorage`.
+ * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+ */
+declare const sessionStorageProvider: StorageProvider;
+/**
+ * The shared in-memory storage provider.
+ * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+ */
+declare const memoryStorageProvider: StorageProvider;
+/**
+ * A storage provider over `location.search`.
+ * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+ */
+declare const urlSearchParamsProvider: StorageProvider;
+/**
+ * A storage provider over `location.hash`, read as search params.
+ * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+ */
+declare const urlSearchParamsInHashProvider: StorageProvider;
+//#endregion
+export { createFallbackProvider, createMemoryStorageProvider, createUrlSearchParamsInHashProvider, createUrlSearchParamsProvider, localStorageProvider, memoryStorageProvider, sessionStorageProvider, urlSearchParamsInHashProvider, urlSearchParamsProvider };

package/dist/storage/providers.js

@@ -0,0 +1,172 @@
+import { getSharedRuntimeSlot } from "../shared-runtime.js";
+import { reportDiagnostic } from "../diagnostics.js";
+//#region src/storage/providers.ts
+/**
+* Run one provider operation, reporting instead of throwing.
+*
+* Web storage fails for reasons the caller cannot prevent: a quota that is
+* full, or an area the browser refuses to hand over. Both are reported once
+* per occurrence rather than swallowed, because a silent write is data loss.
+*/
+function guard(fallback, operation) {
+	try {
+		return operation();
+	} catch (error) {
+		reportDiagnostic("storage.access-failed", "A storage operation failed.", error);
+		return fallback;
+	}
+}
+/**
+* `localStorage` and `sessionStorage` differ only in which area they name.
+*
+* Internal, and called twice: the adapter holds no state of its own — every
+* method resolves `globalThis[name]` per call — so a second instance would
+* behave exactly like the shared one. The package exports the instances.
+*/
+function createWebStorageProvider(name) {
+	const area = () => globalThis[name];
+	return {
+		syncEvents: ["storage"],
+		get: (key) => guard(null, () => area().getItem(key)),
+		set: (key, value) => guard(void 0, () => area().setItem(key, value)),
+		remove: (key) => guard(void 0, () => area().removeItem(key)),
+		has: (key) => guard(false, () => area().getItem(key) !== null),
+		keys: () => guard([], () => {
+			const storage = area();
+			return Array.from({ length: storage.length }, (_, index) => storage.key(index)).filter((key) => key !== null);
+		}),
+		clear: () => guard(void 0, () => area().clear())
+	};
+}
+/**
+* A provider backed by a `Map`, for tests and for opting out of persistence.
+* @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+*/
+function createMemoryStorageProvider() {
+	const map = /* @__PURE__ */ new Map();
+	return {
+		get: (key) => map.get(key) ?? null,
+		set: (key, value) => void map.set(key, value),
+		remove: (key) => void map.delete(key),
+		has: (key) => map.has(key),
+		keys: () => [...map.keys()],
+		clear: () => map.clear()
+	};
+}
+/**
+* Read from the first provider holding the key; write through to all of them.
+* @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+*/
+function createFallbackProvider(...providers) {
+	return {
+		syncEvents: [...new Set(providers.flatMap((provider) => provider.syncEvents ?? []))],
+		get(key) {
+			for (const provider of providers) {
+				const value = provider.get(key);
+				if (value !== null) return value;
+			}
+			return null;
+		},
+		set(key, value) {
+			for (const provider of providers) provider.set(key, value);
+		},
+		remove(key) {
+			for (const provider of providers) provider.remove(key);
+		},
+		has(key) {
+			return providers.some((provider) => provider.has(key));
+		},
+		keys() {
+			return [...new Set(providers.flatMap((provider) => provider.keys()))];
+		},
+		clear() {
+			for (const provider of providers) provider.clear();
+		}
+	};
+}
+/** Build the URL a write lands on, keeping the parts the provider does not own. */
+function createUrlProvider(read, toUrl, syncEvents, { push = false }) {
+	const commit = (params) => {
+		history[push ? "pushState" : "replaceState"]({}, "", toUrl(params));
+	};
+	return {
+		syncEvents,
+		get: (key) => read().get(key),
+		set(key, value) {
+			const params = read();
+			params.set(key, value);
+			commit(params);
+		},
+		remove(key) {
+			const params = read();
+			params.delete(key);
+			commit(params);
+		},
+		has: (key) => read().has(key),
+		keys: () => [...new Set(read().keys())],
+		clear: () => commit(new URLSearchParams())
+	};
+}
+/**
+* Store values in the query string.
+* @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+*/
+function createUrlSearchParamsProvider(options = {}) {
+	return createUrlProvider(() => new URLSearchParams(location.search), (params) => {
+		const search = params.toString();
+		return `${location.pathname}${search ? `?${search}` : ""}${location.hash}`;
+	}, ["popstate"], options);
+}
+/**
+* Store values in the hash, as search params.
+*
+* Back and forward navigation announces itself as `hashchange`, and as
+* `popstate` when the write replaced the entry rather than pushing one.
+* @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+*/
+function createUrlSearchParamsInHashProvider(options = {}) {
+	return createUrlProvider(() => new URLSearchParams(location.hash.slice(1)), (params) => {
+		const hash = params.toString();
+		return `${location.pathname}${location.search}${hash ? `#${hash}` : ""}`;
+	}, ["hashchange", "popstate"], options);
+}
+/**
+* Shared default providers. The memory provider holds state, so evaluated
+* package copies must resolve the same one.
+*/
+const defaults = /* @__PURE__ */ getSharedRuntimeSlot("storage:providers", 1, () => ({
+	local: createWebStorageProvider("localStorage"),
+	session: createWebStorageProvider("sessionStorage"),
+	memory: createMemoryStorageProvider(),
+	urlSearchParams: createUrlSearchParamsProvider(),
+	urlSearchParamsInHash: createUrlSearchParamsInHashProvider()
+}));
+/**
+* A storage provider over `localStorage`.
+* @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+*/
+const localStorageProvider = defaults.local;
+/**
+* A storage provider over `sessionStorage`.
+* @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+*/
+const sessionStorageProvider = defaults.session;
+/**
+* The shared in-memory storage provider.
+* @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+*/
+const memoryStorageProvider = defaults.memory;
+/**
+* A storage provider over `location.search`.
+* @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+*/
+const urlSearchParamsProvider = defaults.urlSearchParams;
+/**
+* A storage provider over `location.hash`, read as search params.
+* @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html
+*/
+const urlSearchParamsInHashProvider = defaults.urlSearchParamsInHash;
+//#endregion
+export { createFallbackProvider, createMemoryStorageProvider, createUrlSearchParamsInHashProvider, createUrlSearchParamsProvider, localStorageProvider, memoryStorageProvider, sessionStorageProvider, urlSearchParamsInHashProvider, urlSearchParamsProvider };
+
+//# sourceMappingURL=providers.js.map

package/dist/storage/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","names":[],"sources":["../../src/storage/providers.ts"],"sourcesContent":["import { reportDiagnostic } from '../diagnostics.js';\nimport { getSharedRuntimeSlot } from '../shared-runtime.js';\nimport type { StorageProvider, UrlProviderOptions } from './types.js';\n\n/**\n * Run one provider operation, reporting instead of throwing.\n *\n * Web storage fails for reasons the caller cannot prevent: a quota that is\n * full, or an area the browser refuses to hand over. Both are reported once\n * per occurrence rather than swallowed, because a silent write is data loss.\n */\nfunction guard<T>(fallback: T, operation: () => T): T {\n  try {\n    return operation();\n  } catch (error) {\n    reportDiagnostic('storage.access-failed', 'A storage operation failed.', error);\n    return fallback;\n  }\n}\n\n/**\n * `localStorage` and `sessionStorage` differ only in which area they name.\n *\n * Internal, and called twice: the adapter holds no state of its own — every\n * method resolves `globalThis[name]` per call — so a second instance would\n * behave exactly like the shared one. The package exports the instances.\n */\nfunction createWebStorageProvider(name: 'localStorage' | 'sessionStorage'): StorageProvider {\n  // Resolved per call: the area getter itself throws when storage is denied.\n  const area = () => globalThis[name];\n\n  return {\n    syncEvents: ['storage'],\n    get: (key) => guard(null, () => area().getItem(key)),\n    set: (key, value) => guard(undefined, () => area().setItem(key, value)),\n    remove: (key) => guard(undefined, () => area().removeItem(key)),\n    has: (key) => guard(false, () => area().getItem(key) !== null),\n    keys: () =>\n      guard([], () => {\n        const storage = area();\n        return Array.from({ length: storage.length }, (_, index) => storage.key(index)).filter(\n          (key): key is string => key !== null,\n        );\n      }),\n    clear: () => guard(undefined, () => area().clear()),\n  };\n}\n\n/**\n * A provider backed by a `Map`, for tests and for opting out of persistence.\n * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html\n */\nexport function createMemoryStorageProvider(): StorageProvider {\n  const map = new Map<string, string>();\n\n  return {\n    get: (key) => map.get(key) ?? null,\n    set: (key, value) => void map.set(key, value),\n    remove: (key) => void map.delete(key),\n    has: (key) => map.has(key),\n    keys: () => [...map.keys()],\n    clear: () => map.clear(),\n  };\n}\n\n/**\n * Read from the first provider holding the key; write through to all of them.\n * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html\n */\nexport function createFallbackProvider(...providers: StorageProvider[]): StorageProvider {\n  const syncEvents = [...new Set(providers.flatMap((provider) => provider.syncEvents ?? []))];\n\n  return {\n    syncEvents,\n    get(key) {\n      for (const provider of providers) {\n        const value = provider.get(key);\n        if (value !== null) {\n          return value;\n        }\n      }\n      return null;\n    },\n    set(key, value) {\n      for (const provider of providers) {\n        provider.set(key, value);\n      }\n    },\n    remove(key) {\n      for (const provider of providers) {\n        provider.remove(key);\n      }\n    },\n    has(key) {\n      return providers.some((provider) => provider.has(key));\n    },\n    keys() {\n      return [...new Set(providers.flatMap((provider) => provider.keys()))];\n    },\n    clear() {\n      for (const provider of providers) {\n        provider.clear();\n      }\n    },\n  };\n}\n\n/** Build the URL a write lands on, keeping the parts the provider does not own. */\nfunction createUrlProvider(\n  read: () => URLSearchParams,\n  toUrl: (params: URLSearchParams) => string,\n  syncEvents: readonly string[],\n  { push = false }: UrlProviderOptions,\n): StorageProvider {\n  const commit = (params: URLSearchParams) => {\n    history[push ? 'pushState' : 'replaceState']({}, '', toUrl(params));\n  };\n\n  return {\n    syncEvents,\n    get: (key) => read().get(key),\n    set(key, value) {\n      const params = read();\n      params.set(key, value);\n      commit(params);\n    },\n    remove(key) {\n      const params = read();\n      params.delete(key);\n      commit(params);\n    },\n    has: (key) => read().has(key),\n    keys: () => [...new Set(read().keys())],\n    clear: () => commit(new URLSearchParams()),\n  };\n}\n\n/**\n * Store values in the query string.\n * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html\n */\nexport function createUrlSearchParamsProvider(options: UrlProviderOptions = {}): StorageProvider {\n  return createUrlProvider(\n    () => new URLSearchParams(location.search),\n    (params) => {\n      const search = params.toString();\n      return `${location.pathname}${search ? `?${search}` : ''}${location.hash}`;\n    },\n    ['popstate'],\n    options,\n  );\n}\n\n/**\n * Store values in the hash, as search params.\n *\n * Back and forward navigation announces itself as `hashchange`, and as\n * `popstate` when the write replaced the entry rather than pushing one.\n * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html\n */\nexport function createUrlSearchParamsInHashProvider(\n  options: UrlProviderOptions = {},\n): StorageProvider {\n  return createUrlProvider(\n    () => new URLSearchParams(location.hash.slice(1)),\n    (params) => {\n      const hash = params.toString();\n      return `${location.pathname}${location.search}${hash ? `#${hash}` : ''}`;\n    },\n    ['hashchange', 'popstate'],\n    options,\n  );\n}\n\n/**\n * Shared default providers. The memory provider holds state, so evaluated\n * package copies must resolve the same one.\n */\nconst defaults = /* @__PURE__ */ getSharedRuntimeSlot('storage:providers', 1, () => ({\n  local: createWebStorageProvider('localStorage'),\n  session: createWebStorageProvider('sessionStorage'),\n  memory: createMemoryStorageProvider(),\n  urlSearchParams: createUrlSearchParamsProvider(),\n  urlSearchParamsInHash: createUrlSearchParamsInHashProvider(),\n}));\n\n/**\n * A storage provider over `localStorage`.\n * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html\n */\nexport const localStorageProvider = defaults.local;\n/**\n * A storage provider over `sessionStorage`.\n * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html\n */\nexport const sessionStorageProvider = defaults.session;\n/**\n * The shared in-memory storage provider.\n * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html\n */\nexport const memoryStorageProvider = defaults.memory;\n/**\n * A storage provider over `location.search`.\n * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html\n */\nexport const urlSearchParamsProvider = defaults.urlSearchParams;\n/**\n * A storage provider over `location.hash`, read as search params.\n * @link https://js-toolkit-v4.studiometa.dev/api/storage/providers.html\n */\nexport const urlSearchParamsInHashProvider = defaults.urlSearchParamsInHash;\n"],"mappings":"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"}

package/dist/storage/serializers.d.ts

@@ -0,0 +1,10 @@
+import { StorageSerializer } from "./types.js";
+//#region src/storage/serializers.d.ts
+/**
+ * The default serializer. `deserialize` throws on malformed input so the
+ * storage instance can name the key it failed on.
+ * @link https://js-toolkit-v4.studiometa.dev/api/storage/createStorage.html
+ */
+declare const jsonSerializer: StorageSerializer;
+//#endregion
+export { jsonSerializer };

package/dist/storage/serializers.js

@@ -0,0 +1,14 @@
+//#region src/storage/serializers.ts
+/**
+* The default serializer. `deserialize` throws on malformed input so the
+* storage instance can name the key it failed on.
+* @link https://js-toolkit-v4.studiometa.dev/api/storage/createStorage.html
+*/
+const jsonSerializer = {
+	serialize: (value) => JSON.stringify(value),
+	deserialize: (value) => JSON.parse(value)
+};
+//#endregion
+export { jsonSerializer };
+
+//# sourceMappingURL=serializers.js.map

package/dist/storage/serializers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializers.js","names":[],"sources":["../../src/storage/serializers.ts"],"sourcesContent":["import type { StorageSerializer } from './types.js';\n\n/**\n * The default serializer. `deserialize` throws on malformed input so the\n * storage instance can name the key it failed on.\n * @link https://js-toolkit-v4.studiometa.dev/api/storage/createStorage.html\n */\nexport const jsonSerializer: StorageSerializer = {\n  serialize: (value) => JSON.stringify(value),\n  deserialize: (value) => JSON.parse(value) as unknown,\n};\n"],"mappings":";;;;;;AAOA,MAAa,iBAAoC;CAC/C,YAAY,UAAU,KAAK,UAAU,KAAK;CAC1C,cAAc,UAAU,KAAK,MAAM,KAAK;AAC1C"}

package/dist/storage/sync.d.ts

@@ -0,0 +1,19 @@
+import { Service } from "../services/service.js";
+//#region src/storage/sync.d.ts
+/**
+ * Announce out-of-band storage changes.
+ *
+ * The event carries no state a subscriber can use — a `StorageEvent` names one
+ * key, a `hashchange` names none — so subscribers re-read what they hold. The
+ * service exists for its refcounting: the listener is attached while at least
+ * one storage observes this event, and released with the last of them. Held in
+ * a shared slot so every storage in the page shares one listener per event.
+ *
+ * `createStorage` is the only caller. A provider declares `syncEvents` and is
+ * wired up for it.
+ *
+ * @internal
+ */
+declare function useStorageSync(eventName: string): Service<void>;
+//#endregion
+export { useStorageSync };