@fluixi/storage 0.1.0-alpha.0

package/dist/core/storage.mjs

@@ -0,0 +1,759 @@
+// src/adapters/memory.ts
+function memoryStorage() {
+  const values = /* @__PURE__ */ new Map();
+  return {
+    name: "memory",
+    scope: "memory",
+    capabilities: {
+      synchronous: true,
+      persistent: false,
+      reactive: false,
+      crossContext: false,
+      expiration: false,
+      transactions: false
+    },
+    get: (key) => values.get(key) ?? null,
+    set: (key, value) => void values.set(key, value),
+    remove: (key) => void values.delete(key),
+    has: (key) => values.has(key),
+    keys: () => [...values.keys()],
+    clear: () => values.clear()
+  };
+}
+
+// src/core/errors.ts
+var StorageError = class extends Error {
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.key = options.key;
+    if (options.cause !== void 0) this.cause = options.cause;
+  }
+};
+var StorageSerializationError = class extends StorageError {
+  constructor(message, options = {}) {
+    super("serialization", message, options);
+  }
+};
+var StorageDeserializationError = class extends StorageError {
+  constructor(message, options = {}) {
+    super("deserialization", message, options);
+  }
+};
+var StorageEncryptionError = class extends StorageError {
+};
+var StorageEncryptionKeyError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-key", message, options);
+  }
+};
+var StorageEncryptionMetadataError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-metadata", message, options);
+  }
+};
+var StorageEncryptionVersionError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-version", message, options);
+  }
+};
+var StorageEncryptionAlgorithmError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-algorithm", message, options);
+  }
+};
+var StorageDecryptionError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("decryption", message, options);
+  }
+};
+var StorageEncryptedPayloadError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-payload", message, options);
+  }
+};
+var StorageEncryptionUnavailableError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-unavailable", message, options);
+  }
+};
+
+// src/serialization/json.ts
+function assertJson(value, path, seen) {
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return;
+    case "number":
+      if (!Number.isFinite(value)) throw new StorageSerializationError(`${path} is ${value}, which JSON cannot hold.`);
+      return;
+    case "object":
+      break;
+    default:
+      throw new StorageSerializationError(`${path} is a ${typeof value}, which JSON cannot hold.`);
+  }
+  if (value === null) return;
+  if (seen.has(value)) throw new StorageSerializationError(`${path} refers back to itself.`);
+  seen.add(value);
+  if (Array.isArray(value)) {
+    value.forEach((item, i) => assertJson(item, `${path}[${i}]`, seen));
+  } else {
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+      const name = value.constructor?.name ?? "an object with a prototype";
+      throw new StorageSerializationError(`${path} is ${name}, which does not survive JSON. Convert it to plain data first.`);
+    }
+    for (const [key, item] of Object.entries(value)) {
+      if (item === void 0) throw new StorageSerializationError(`${path}.${key} is undefined, which JSON drops. Omit the key or use null.`);
+      assertJson(item, `${path}.${key}`, seen);
+    }
+  }
+  seen.delete(value);
+}
+var jsonSerializer = {
+  serialize(value) {
+    assertJson(value, "value", /* @__PURE__ */ new Set());
+    return JSON.stringify(value);
+  },
+  deserialize(text) {
+    return JSON.parse(text);
+  }
+};
+
+// src/utils/keys.ts
+function namespacePrefix(namespace) {
+  return namespace ? `${namespace}:` : "";
+}
+function joinNamespace(parent, child) {
+  if (!child) throw new TypeError("A namespace needs a name.");
+  return parent ? `${parent}:${child}` : child;
+}
+
+// src/encryption/base64.ts
+function toBase64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += 32768) binary += String.fromCharCode(...bytes.subarray(i, i + 32768));
+  return btoa(binary);
+}
+function fromBase64(text) {
+  if (text.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(text)) throw new TypeError("Not base64.");
+  const binary = atob(text);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+
+// src/encryption/seal.ts
+var PAYLOAD_VERSION = 1;
+var encoder = new TextEncoder();
+var decoder = new TextDecoder("utf-8", { fatal: true });
+var aad = (storedKey, alg, kid, meta) => encoder.encode(JSON.stringify(["fx-storage", PAYLOAD_VERSION, alg, storedKey, meta.createdAt, meta.expiresAt ?? null, meta.version ?? null, kid ?? null]));
+async function keyFor(sealer, context) {
+  if (!sealer.keyProvider) {
+    throw new StorageEncryptionKeyError(`${context.key} is encrypted, and this storage has no encryption key provider.`, { key: context.key });
+  }
+  let result;
+  try {
+    result = await sealer.keyProvider.getKey(context);
+  } catch (error) {
+    if (error instanceof StorageEncryptionError) throw error;
+    throw new StorageEncryptionKeyError(`The key provider failed for ${context.key}.`, { key: context.key, cause: error });
+  }
+  const pair = result && "key" in result && "id" in result ? result : { key: result };
+  const algorithm = pair.key?.algorithm;
+  if (!algorithm || algorithm.name !== "AES-GCM" || algorithm.length !== 256) {
+    throw new StorageEncryptionKeyError(`The key provider must return an AES-GCM 256-bit key for ${context.key}.`, { key: context.key });
+  }
+  if (!pair.key.usages.includes(context.operation)) {
+    throw new StorageEncryptionKeyError(`The key for ${context.key} does not allow ${context.operation}.`, { key: context.key });
+  }
+  return pair;
+}
+async function seal(sealer, context, storedKey, plaintext, meta) {
+  const { key, id } = await keyFor(sealer, { ...context, operation: "encrypt" });
+  const alg = sealer.provider.algorithm;
+  const out = await sealer.provider.encrypt(encoder.encode(plaintext), key, aad(storedKey, alg, id, meta));
+  const payload = { v: PAYLOAD_VERSION, alg, iv: toBase64(out.iv), data: toBase64(out.ciphertext), tag: toBase64(out.tag) };
+  if (id !== void 0) payload.kid = id;
+  return payload;
+}
+async function open(sealer, context, storedKey, payload, meta) {
+  const k = context.key;
+  const p = payload;
+  if (!p || typeof p !== "object" || typeof p.v !== "number") {
+    throw new StorageEncryptionMetadataError(`The encryption metadata of ${k} is missing its version.`, { key: k });
+  }
+  if (p.v !== PAYLOAD_VERSION) throw new StorageEncryptionVersionError(`${k} uses encryption format ${p.v}, which this release cannot read.`, { key: k });
+  if (typeof p.alg !== "string" || typeof p.iv !== "string" || typeof p.data !== "string" || typeof p.tag !== "string" || p.kid !== void 0 && typeof p.kid !== "string") {
+    throw new StorageEncryptionMetadataError(`The encryption metadata of ${k} is malformed.`, { key: k });
+  }
+  if (p.alg !== sealer.provider.algorithm) {
+    throw new StorageEncryptionAlgorithmError(`${k} is encrypted with ${p.alg}; the provider implements ${sealer.provider.algorithm}.`, { key: k });
+  }
+  let iv, ciphertext, tag;
+  try {
+    iv = fromBase64(p.iv);
+    ciphertext = fromBase64(p.data);
+    tag = fromBase64(p.tag);
+  } catch (error) {
+    throw new StorageEncryptedPayloadError(`The encrypted payload of ${k} is not valid base64.`, { key: k, cause: error });
+  }
+  if (iv.length !== 12 || tag.length !== 16) throw new StorageEncryptedPayloadError(`The encrypted payload of ${k} has a wrong IV or tag length.`, { key: k });
+  const { key } = await keyFor(sealer, { ...context, operation: "decrypt", keyId: p.kid });
+  let bytes;
+  try {
+    bytes = await sealer.provider.decrypt({ algorithm: p.alg, iv, ciphertext, tag }, key, aad(storedKey, p.alg, p.kid, meta));
+  } catch (error) {
+    throw new StorageDecryptionError(`${k} failed authentication: wrong key, or the stored entry was changed.`, { key: k, cause: error });
+  }
+  try {
+    return decoder.decode(bytes);
+  } catch (error) {
+    throw new StorageEncryptedPayloadError(`The decrypted value of ${k} is not UTF-8.`, { key: k, cause: error });
+  }
+}
+
+// src/encryption/web-crypto.ts
+var IV_BYTES = 12;
+var TAG_BYTES = 16;
+function webCryptoProvider(crypto) {
+  const resolve = () => {
+    const c = crypto ?? globalThis.crypto;
+    if (!c?.subtle || !c.getRandomValues) {
+      throw new StorageEncryptionUnavailableError("Web Crypto is not available in this runtime; pass a provider in the encryption options.");
+    }
+    return c;
+  };
+  return {
+    algorithm: "AES-256-GCM",
+    async encrypt(data, key, aad2) {
+      const c = resolve();
+      const iv = c.getRandomValues(new Uint8Array(IV_BYTES));
+      const params = { name: "AES-GCM", iv, tagLength: TAG_BYTES * 8 };
+      if (aad2) params.additionalData = aad2;
+      const sealed = new Uint8Array(await c.subtle.encrypt(params, key, data));
+      return {
+        algorithm: "AES-256-GCM",
+        iv,
+        ciphertext: sealed.slice(0, sealed.length - TAG_BYTES),
+        tag: sealed.slice(sealed.length - TAG_BYTES)
+      };
+    },
+    async decrypt(data, key, aad2) {
+      const c = resolve();
+      const sealed = new Uint8Array(data.ciphertext.length + data.tag.length);
+      sealed.set(data.ciphertext);
+      sealed.set(data.tag, data.ciphertext.length);
+      const params = { name: "AES-GCM", iv: data.iv, tagLength: TAG_BYTES * 8 };
+      if (aad2) params.additionalData = aad2;
+      return new Uint8Array(await c.subtle.decrypt(params, key, sealed));
+    }
+  };
+}
+
+// src/core/envelope.ts
+function isEnvelope(x) {
+  return !!x && typeof x === "object" && x.v === 1 && ("value" in x || "enc" in x) && typeof x.createdAt === "number";
+}
+function serializeOrThrow(serializer, key, value) {
+  try {
+    return serializer.serialize(value);
+  } catch (error) {
+    if (error instanceof StorageError) throw Object.assign(error, { key });
+    throw new StorageSerializationError(`The value of ${key} could not be serialized.`, { key, cause: error });
+  }
+}
+function deserializeOrThrow(serializer, key, text) {
+  try {
+    return serializer.deserialize(text);
+  } catch (error) {
+    throw new StorageDeserializationError(`The stored value of ${key} could not be read.`, { key, cause: error });
+  }
+}
+function decodeEnvelope(serializer, key, text) {
+  const parsed = deserializeOrThrow(serializer, key, text);
+  return isEnvelope(parsed) ? parsed : { v: 1, value: parsed, createdAt: 0 };
+}
+var isExpired = (envelope, now) => envelope.expiresAt !== void 0 && envelope.expiresAt <= now;
+function latestVersion(steps) {
+  if (!steps) return void 0;
+  const versions = Object.keys(steps).map(Number).filter(Number.isFinite);
+  return versions.length ? Math.max(...versions) : void 0;
+}
+function migrate(steps, from, value) {
+  const latest = latestVersion(steps);
+  if (!steps || latest === void 0 || (from ?? 0) >= latest) return void 0;
+  for (const version of Object.keys(steps).map(Number).sort((a, b) => a - b)) {
+    if (version > (from ?? 0)) value = steps[version](value);
+  }
+  return { value, version: latest };
+}
+function metaFor(createdAt, ttl, version) {
+  const meta = { createdAt };
+  if (ttl !== void 0) meta.expiresAt = createdAt + ttl;
+  if (version !== void 0) meta.version = version;
+  return meta;
+}
+function toEntry(envelope, value) {
+  const entry = { value, createdAt: envelope.createdAt };
+  if (envelope.expiresAt !== void 0) entry.expiresAt = envelope.expiresAt;
+  if (envelope.version !== void 0) entry.version = envelope.version;
+  if (envelope.enc) entry.encrypted = true;
+  return entry;
+}
+var globToRegExp = (glob) => new RegExp(`^${glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".")}$`);
+function selectItems(items, query) {
+  const pattern = typeof query.match === "string" ? globToRegExp(query.match) : query.match;
+  const out = [];
+  for (const item of items) {
+    if (query.prefix !== void 0 && !item.key.startsWith(query.prefix)) continue;
+    if (pattern && !pattern.test(item.key)) continue;
+    if (query.where && !query.where(item)) continue;
+    out.push(item);
+    if (query.limit !== void 0 && out.length >= query.limit) break;
+  }
+  return out;
+}
+
+// src/core/bus.ts
+var buses = /* @__PURE__ */ new WeakMap();
+function joinBus(adapter, subscriber) {
+  let bus = buses.get(adapter);
+  if (!bus) buses.set(adapter, bus = { subscribers: /* @__PURE__ */ new Set() });
+  const current = bus;
+  current.subscribers.add(subscriber);
+  if (current.subscribers.size === 1 && adapter.subscribe) {
+    current.stop = adapter.subscribe((change) => {
+      for (const s of [...current.subscribers]) s.external(change);
+    });
+  }
+  return () => {
+    current.subscribers.delete(subscriber);
+    if (current.subscribers.size === 0) {
+      current.stop?.();
+      current.stop = void 0;
+    }
+  };
+}
+function publish(adapter, type, key, prefix, value) {
+  const bus = buses.get(adapter);
+  if (!bus) return;
+  for (const s of [...bus.subscribers]) {
+    if (key === null ? s.prefix.startsWith(prefix) : key.startsWith(s.prefix)) s.local(type, key, value);
+  }
+}
+
+// src/core/async-storage.ts
+function createAsyncStorage(options = {}) {
+  const adapter = options.adapter ?? memoryStorage();
+  const serializer = options.serializer ?? jsonSerializer;
+  const now = options.now ?? Date.now;
+  const migrations = options.migrations ?? {};
+  const prefix = namespacePrefix(options.namespace);
+  const listeners = /* @__PURE__ */ new Set();
+  let leave;
+  const sealer = {
+    keyProvider: options.encryption?.keyProvider,
+    provider: options.encryption?.provider ?? webCryptoProvider()
+  };
+  const context = (key) => options.namespace ? { key, namespace: options.namespace } : { key };
+  const deliver = (event) => {
+    for (const { key, fn } of [...listeners]) if (key === void 0 || event.key === null || key === event.key) fn(event);
+  };
+  const emit = (event) => publish(adapter, event.type, event.key === null ? null : prefix + event.key, prefix, event.value);
+  const store = async (key, value, meta, encrypt) => {
+    const envelope = { v: 1, ...meta };
+    if (encrypt) {
+      if (!sealer.keyProvider) throw new StorageEncryptionKeyError(`Encrypting ${key} needs encryption on the storage.`, { key });
+      envelope.enc = await seal(sealer, context(key), prefix + key, serializeOrThrow(serializer, key, value), meta);
+    } else {
+      envelope.value = value;
+    }
+    await adapter.set(prefix + key, serializeOrThrow(serializer, key, envelope), { expiresAt: meta.expiresAt });
+  };
+  const write = async (key, value, meta, encrypt) => {
+    await store(key, value, meta, encrypt);
+    emit({ type: "set", key, value, external: false });
+  };
+  const metaOf = ({ createdAt, expiresAt, version }) => {
+    const meta = { createdAt };
+    if (expiresAt !== void 0) meta.expiresAt = expiresAt;
+    if (version !== void 0) meta.version = version;
+    return meta;
+  };
+  const read = async (key) => {
+    const text = await adapter.get(prefix + key);
+    if (text === null) return null;
+    let envelope = decodeEnvelope(serializer, key, text);
+    if (isExpired(envelope, now())) {
+      await adapter.remove(prefix + key);
+      emit({ type: "expire", key, external: false });
+      return null;
+    }
+    let value = envelope.enc ? deserializeOrThrow(serializer, key, await open(sealer, context(key), prefix + key, envelope.enc, metaOf(envelope))) : envelope.value;
+    const migrated = migrate(migrations[key], envelope.version, value);
+    if (migrated) {
+      value = migrated.value;
+      const meta = { ...metaOf(envelope), version: migrated.version };
+      await store(key, value, meta, !!envelope.enc);
+      envelope = { v: 1, ...meta, ...envelope.enc ? { enc: envelope.enc } : { value } };
+    }
+    return { envelope, value };
+  };
+  const ownKeys = async () => (await adapter.keys()).filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length));
+  const external = (change) => {
+    if (change.key === null) return deliver({ type: "clear", key: null, external: true });
+    if (!change.key.startsWith(prefix)) return;
+    const key = change.key.slice(prefix.length);
+    if (change.value === null) return deliver({ type: "remove", key, external: true });
+    try {
+      const envelope = decodeEnvelope(serializer, key, change.value);
+      deliver({ type: "set", key, value: envelope.enc ? void 0 : envelope.value, external: true });
+    } catch {
+    }
+  };
+  const liveItems = async () => {
+    const items = [];
+    for (const key of (await ownKeys()).sort()) {
+      const current = await read(key);
+      if (current) items.push({ key, value: current.value, entry: toEntry(current.envelope, current.value) });
+    }
+    return items;
+  };
+  const storage = {
+    scope: adapter.scope,
+    keyPrefix: prefix,
+    capabilities: { ...adapter.capabilities, expiration: true },
+    encryption: !!sealer.keyProvider,
+    async get(key) {
+      return (await read(key))?.value ?? null;
+    },
+    async getEntry(key) {
+      const current = await read(key);
+      return current ? toEntry(current.envelope, current.value) : null;
+    },
+    async set(key, value, setOptions = {}) {
+      const meta = metaFor(now(), setOptions.ttl, setOptions.version ?? latestVersion(migrations[key]));
+      await write(key, value, meta, setOptions.encrypt === true);
+    },
+    entries: liveItems,
+    async search(query) {
+      return selectItems(await liveItems(), query);
+    },
+    async size() {
+      let count = 0;
+      for (const key of await ownKeys()) {
+        const text = await adapter.get(prefix + key);
+        if (text !== null && !isExpired(decodeEnvelope(serializer, key, text), now())) count++;
+      }
+      return count;
+    },
+    async prune() {
+      let removed = 0;
+      for (const key of await ownKeys()) {
+        const text = await adapter.get(prefix + key);
+        if (text === null) continue;
+        if (isExpired(decodeEnvelope(serializer, key, text), now())) {
+          await adapter.remove(prefix + key);
+          emit({ type: "expire", key, external: false });
+          removed++;
+        }
+      }
+      return removed;
+    },
+    async usage() {
+      let bytes = 0;
+      const keys = await ownKeys();
+      for (const key of keys) bytes += ((prefix + key).length + ((await adapter.get(prefix + key))?.length ?? 0)) * 2;
+      return { keys: keys.length, bytes };
+    },
+    async update(key, fn, updateOptions = {}) {
+      const current = await read(key);
+      const value = await fn(current?.value ?? null);
+      const meta = metaFor(now(), void 0, current?.envelope.version ?? latestVersion(migrations[key]));
+      if (current?.envelope.expiresAt !== void 0) meta.expiresAt = current.envelope.expiresAt;
+      await write(key, value, meta, updateOptions.encrypt ?? !!current?.envelope.enc);
+      return value;
+    },
+    async getOrSet(key, factory, setOptions) {
+      const current = await read(key);
+      if (current) return current.value;
+      const value = await factory();
+      await storage.set(key, value, setOptions);
+      return value;
+    },
+    async touch(key, ttl) {
+      const current = await read(key);
+      if (!current) return false;
+      await store(key, current.value, { ...metaOf(current.envelope), expiresAt: now() + ttl }, !!current.envelope.enc);
+      return true;
+    },
+    async snapshot() {
+      const out = {};
+      for (const item of await liveItems()) out[item.key] = item.entry;
+      return out;
+    },
+    async restore(snapshot, restoreOptions = {}) {
+      let written = 0;
+      for (const [key, entry] of Object.entries(snapshot)) {
+        if (!entry) continue;
+        if (!restoreOptions.overwrite && await read(key)) continue;
+        if (entry.expiresAt !== void 0 && entry.expiresAt <= now()) continue;
+        const meta = { createdAt: entry.createdAt };
+        if (entry.expiresAt !== void 0) meta.expiresAt = entry.expiresAt;
+        if (entry.version !== void 0) meta.version = entry.version;
+        await write(key, entry.value, meta, entry.encrypted === true);
+        written++;
+      }
+      return written;
+    },
+    async remove(key) {
+      await adapter.remove(prefix + key);
+      emit({ type: "remove", key, external: false });
+    },
+    async has(key) {
+      const text = await adapter.get(prefix + key);
+      if (text === null) return false;
+      if (!isExpired(decodeEnvelope(serializer, key, text), now())) return true;
+      await adapter.remove(prefix + key);
+      emit({ type: "expire", key, external: false });
+      return false;
+    },
+    async keys() {
+      return await ownKeys();
+    },
+    async clear() {
+      if (prefix) for (const key of await ownKeys()) await adapter.remove(prefix + key);
+      else await adapter.clear();
+      emit({ type: "clear", key: null, external: false });
+    },
+    namespace(name) {
+      return createAsyncStorage({ ...options, migrations: void 0, namespace: joinNamespace(options.namespace, name) });
+    },
+    subscribe(keyOrListener, maybeListener) {
+      const entry = typeof keyOrListener === "function" ? { fn: keyOrListener } : { key: keyOrListener, fn: maybeListener };
+      listeners.add(entry);
+      if (listeners.size === 1) {
+        leave = joinBus(adapter, {
+          prefix,
+          external,
+          local(type, key, value) {
+            const event = { type, key: key === null ? null : key.slice(prefix.length), external: false };
+            if (type === "set") event.value = value;
+            deliver(event);
+          }
+        });
+      }
+      return () => {
+        if (listeners.delete(entry) && listeners.size === 0) {
+          leave?.();
+          leave = void 0;
+        }
+      };
+    }
+  };
+  return storage;
+}
+
+// src/core/storage.ts
+function createStorage(options = {}) {
+  if ("encryption" in options && options.encryption) return createAsyncStorage(options);
+  return createSyncStorage(options);
+}
+function createSyncStorage(options = {}) {
+  const adapter = options.adapter ?? memoryStorage();
+  const serializer = options.serializer ?? jsonSerializer;
+  const now = options.now ?? Date.now;
+  const migrations = options.migrations ?? {};
+  const prefix = namespacePrefix(options.namespace);
+  const listeners = /* @__PURE__ */ new Set();
+  let leave;
+  const deliver = (event) => {
+    for (const { key, fn } of [...listeners]) if (key === void 0 || event.key === null || key === event.key) fn(event);
+  };
+  const emit = (event) => publish(adapter, event.type, event.key === null ? null : prefix + event.key, prefix, event.value);
+  const encode = (key, envelope) => serializeOrThrow(serializer, key, envelope);
+  const valueOf = (key, envelope) => {
+    if (envelope.enc) {
+      throw new StorageEncryptionUnavailableError(`${key} is encrypted; read it through createStorage({ encryption }), which is asynchronous.`, { key });
+    }
+    return envelope.value;
+  };
+  const read = (key) => {
+    const text = adapter.get(prefix + key);
+    if (text === null) return null;
+    const envelope = decodeEnvelope(serializer, key, text);
+    if (isExpired(envelope, now())) {
+      adapter.remove(prefix + key);
+      emit({ type: "expire", key, external: false });
+      return null;
+    }
+    if (envelope.enc) return envelope;
+    const migrated = migrate(migrations[key], envelope.version, envelope.value);
+    if (!migrated) return envelope;
+    const next = { ...envelope, ...migrated };
+    adapter.set(prefix + key, encode(key, next), { expiresAt: next.expiresAt });
+    return next;
+  };
+  const ownKeys = () => adapter.keys().filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length));
+  const external = (change) => {
+    if (change.key === null) return deliver({ type: "clear", key: null, external: true });
+    if (!change.key.startsWith(prefix)) return;
+    const key = change.key.slice(prefix.length);
+    if (change.value === null) return deliver({ type: "remove", key, external: true });
+    try {
+      const envelope = decodeEnvelope(serializer, key, change.value);
+      deliver({ type: "set", key, value: envelope.enc ? void 0 : envelope.value, external: true });
+    } catch {
+    }
+  };
+  const liveItems = () => {
+    const items = [];
+    for (const key of ownKeys().sort()) {
+      const envelope = read(key);
+      if (!envelope) continue;
+      const value = valueOf(key, envelope);
+      items.push({ key, value, entry: toEntry(envelope, value) });
+    }
+    return items;
+  };
+  const write = (key, value, meta) => {
+    adapter.set(prefix + key, encode(key, { v: 1, value, ...meta }), { expiresAt: meta.expiresAt });
+    emit({ type: "set", key, value, external: false });
+  };
+  const storage = {
+    scope: adapter.scope,
+    keyPrefix: prefix,
+    // The storage expires entries itself, whatever the adapter can do.
+    capabilities: { ...adapter.capabilities, expiration: true },
+    get(key) {
+      const envelope = read(key);
+      return envelope ? valueOf(key, envelope) ?? null : null;
+    },
+    getEntry(key) {
+      const envelope = read(key);
+      return envelope ? toEntry(envelope, valueOf(key, envelope)) : null;
+    },
+    set(key, value, setOptions = {}) {
+      write(key, value, metaFor(now(), setOptions.ttl, setOptions.version ?? latestVersion(migrations[key])));
+    },
+    entries() {
+      return liveItems();
+    },
+    search(query) {
+      return selectItems(liveItems(), query);
+    },
+    size() {
+      return ownKeys().filter((key) => read(key) !== null).length;
+    },
+    prune() {
+      let removed = 0;
+      for (const key of ownKeys()) {
+        const text = adapter.get(prefix + key);
+        if (text === null) continue;
+        if (isExpired(decodeEnvelope(serializer, key, text), now())) {
+          adapter.remove(prefix + key);
+          emit({ type: "expire", key, external: false });
+          removed++;
+        }
+      }
+      return removed;
+    },
+    usage() {
+      let bytes = 0;
+      const keys = ownKeys();
+      for (const key of keys) bytes += ((prefix + key).length + (adapter.get(prefix + key)?.length ?? 0)) * 2;
+      return { keys: keys.length, bytes };
+    },
+    update(key, fn) {
+      const current = read(key);
+      const value = fn(current ? valueOf(key, current) : null);
+      const meta = metaFor(now(), void 0, current?.version ?? latestVersion(migrations[key]));
+      if (current?.expiresAt !== void 0) meta.expiresAt = current.expiresAt;
+      write(key, value, meta);
+      return value;
+    },
+    getOrSet(key, factory, setOptions) {
+      const current = read(key);
+      if (current) return valueOf(key, current);
+      const value = factory();
+      storage.set(key, value, setOptions);
+      return value;
+    },
+    touch(key, ttl) {
+      const current = read(key);
+      if (!current) return false;
+      valueOf(key, current);
+      const expiresAt = now() + ttl;
+      adapter.set(prefix + key, encode(key, { ...current, expiresAt }), { expiresAt });
+      return true;
+    },
+    snapshot() {
+      const out = {};
+      for (const item of liveItems()) out[item.key] = item.entry;
+      return out;
+    },
+    restore(snapshot, restoreOptions = {}) {
+      let written = 0;
+      for (const [key, entry] of Object.entries(snapshot)) {
+        if (!entry) continue;
+        if (entry.encrypted) {
+          throw new StorageEncryptionUnavailableError(`${key} was encrypted; restore it through createStorage({ encryption }).`, { key });
+        }
+        if (!restoreOptions.overwrite && read(key)) continue;
+        if (entry.expiresAt !== void 0 && entry.expiresAt <= now()) continue;
+        const meta = { createdAt: entry.createdAt };
+        if (entry.expiresAt !== void 0) meta.expiresAt = entry.expiresAt;
+        if (entry.version !== void 0) meta.version = entry.version;
+        write(key, entry.value, meta);
+        written++;
+      }
+      return written;
+    },
+    remove(key) {
+      adapter.remove(prefix + key);
+      emit({ type: "remove", key, external: false });
+    },
+    has(key) {
+      return read(key) !== null;
+    },
+    keys() {
+      return ownKeys();
+    },
+    clear() {
+      if (prefix) for (const key of ownKeys()) adapter.remove(prefix + key);
+      else adapter.clear();
+      emit({ type: "clear", key: null, external: false });
+    },
+    namespace(name) {
+      return createSyncStorage({ adapter, serializer, now, namespace: joinNamespace(options.namespace, name) });
+    },
+    subscribe(keyOrListener, maybeListener) {
+      const entry = typeof keyOrListener === "function" ? { fn: keyOrListener } : { key: keyOrListener, fn: maybeListener };
+      listeners.add(entry);
+      if (listeners.size === 1) {
+        leave = joinBus(adapter, {
+          prefix,
+          external,
+          local(type, key, value) {
+            const event = { type, key: key === null ? null : key.slice(prefix.length), external: false };
+            if (type === "set") event.value = value;
+            deliver(event);
+          }
+        });
+      }
+      return () => {
+        if (listeners.delete(entry) && listeners.size === 0) {
+          leave?.();
+          leave = void 0;
+        }
+      };
+    }
+  };
+  return storage;
+}
+export {
+  createStorage,
+  createSyncStorage
+};