@valentinkolb/sync 2.2.0 → 3.0.0

package/browser/registry.js

@@ -0,0 +1,662 @@
+// src/browser/internal/emitter.ts
+class Emitter {
+  listeners = new Set;
+  on(fn) {
+    this.listeners.add(fn);
+    return () => {
+      this.listeners.delete(fn);
+    };
+  }
+  emit(value) {
+    for (const fn of this.listeners) {
+      fn(value);
+    }
+  }
+  once() {
+    return new Promise((resolve) => {
+      const unsub = this.on((value) => {
+        unsub();
+        resolve(value);
+      });
+    });
+  }
+  onceWithSignal(signal) {
+    if (!signal)
+      return this.once();
+    if (signal.aborted)
+      return Promise.reject(Object.assign(new Error("aborted"), { name: "AbortError" }));
+    return new Promise((resolve, reject) => {
+      const unsub = this.on((value) => {
+        unsub();
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      });
+      const onAbort = () => {
+        unsub();
+        signal.removeEventListener("abort", onAbort);
+        reject(Object.assign(new Error("aborted"), { name: "AbortError" }));
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+}
+
+// src/browser/internal/event-log.ts
+class EventLog {
+  entries = [];
+  seq = 0;
+  emitter = new Emitter;
+  maxLen;
+  retentionMs;
+  constructor(config = {}) {
+    this.maxLen = config.maxLen ?? 50000;
+    this.retentionMs = config.retentionMs ?? 5 * 60 * 1000;
+  }
+  append(fields) {
+    const id = String(++this.seq);
+    const entry = { id, ts: Date.now(), fields };
+    this.entries.push(entry);
+    this.trim();
+    this.emitter.emit(entry);
+    return id;
+  }
+  range(after, count) {
+    const afterNum = Number(after) || 0;
+    const result = [];
+    for (const entry of this.entries) {
+      if (Number(entry.id) <= afterNum)
+        continue;
+      result.push(entry);
+      if (count !== undefined && result.length >= count)
+        break;
+    }
+    return result;
+  }
+  latest() {
+    if (this.entries.length === 0)
+      return "0";
+    return this.entries[this.entries.length - 1].id;
+  }
+  earliest() {
+    if (this.entries.length === 0)
+      return null;
+    return this.entries[0].id;
+  }
+  has(cursor) {
+    const num = Number(cursor);
+    return this.entries.some((e) => Number(e.id) === num);
+  }
+  async* subscribe(after, signal) {
+    let cursor = after;
+    while (!signal?.aborted) {
+      const buffered = this.range(cursor);
+      if (buffered.length > 0) {
+        for (const entry of buffered) {
+          cursor = entry.id;
+          yield entry;
+        }
+        continue;
+      }
+      try {
+        const entry = await this.emitter.onceWithSignal(signal);
+        if (Number(entry.id) > Number(cursor)) {
+          cursor = entry.id;
+          yield entry;
+        }
+      } catch {
+        break;
+      }
+    }
+  }
+  trim() {
+    if (this.entries.length > this.maxLen) {
+      this.entries.splice(0, this.entries.length - this.maxLen);
+    }
+    if (this.retentionMs > 0) {
+      const cutoff = Date.now() - this.retentionMs;
+      let trimCount = 0;
+      for (const entry of this.entries) {
+        if (entry.ts >= cutoff)
+          break;
+        trimCount++;
+      }
+      if (trimCount > 0) {
+        this.entries.splice(0, trimCount);
+      }
+    }
+  }
+  get size() {
+    return this.entries.length;
+  }
+}
+
+// src/browser/registry.ts
+var DEFAULT_MAX_ENTRIES = 1e4;
+var DEFAULT_MAX_PAYLOAD_BYTES = 128 * 1024;
+var DEFAULT_EVENT_RETENTION_MS = 5 * 60 * 1000;
+var DEFAULT_EVENT_MAXLEN = 50000;
+var DEFAULT_TOMBSTONE_RETENTION_MS = 5 * 60 * 1000;
+var DEFAULT_LIST_LIMIT = 1000;
+var DEFAULT_TIMEOUT_MS = 30000;
+var MAX_KEY_BYTES = 512;
+var MAX_KEY_DEPTH = 8;
+var textEncoder = new TextEncoder;
+
+class RegistryCapacityError extends Error {
+  constructor(message = "registry capacity reached") {
+    super(message);
+    this.name = "RegistryCapacityError";
+  }
+}
+
+class RegistryPayloadTooLargeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RegistryPayloadTooLargeError";
+  }
+}
+var assertLogicalKey = (value) => {
+  if (value.length === 0)
+    throw new Error("key must be non-empty");
+  if (value.startsWith("/"))
+    throw new Error("key must not start with '/'");
+  if (value.endsWith("/"))
+    throw new Error("key must not end with '/'");
+  if (value.includes("//"))
+    throw new Error("key must not contain '//'");
+  const bytes = textEncoder.encode(value).byteLength;
+  if (bytes > MAX_KEY_BYTES)
+    throw new Error(`key exceeds max length (${MAX_KEY_BYTES} bytes)`);
+  const segments = value.split("/").filter(Boolean);
+  if (segments.length > MAX_KEY_DEPTH)
+    throw new Error(`key depth exceeds max (${MAX_KEY_DEPTH})`);
+};
+var assertIdentifier = (value, label) => {
+  if (value.length === 0)
+    throw new Error(`${label} must be non-empty`);
+  if (value.length > 256)
+    throw new Error(`${label} too long (max 256 chars)`);
+};
+var ancestorPrefixes = (key) => {
+  const parts = key.split("/").filter(Boolean);
+  const prefixes = [];
+  let current = "";
+  for (const part of parts) {
+    current += part + "/";
+    prefixes.push(current);
+  }
+  if (prefixes.length > 0) {
+    prefixes.pop();
+  }
+  return prefixes;
+};
+var registry = (config) => {
+  assertIdentifier(config.id, "config.id");
+  const defaultTenant = config.tenantId ?? "default";
+  assertIdentifier(defaultTenant, "tenantId");
+  const maxEntries = config.limits?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  const maxPayloadBytes = config.limits?.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES;
+  const eventRetentionMs = config.limits?.eventRetentionMs ?? DEFAULT_EVENT_RETENTION_MS;
+  const eventMaxLen = config.limits?.eventMaxLen ?? DEFAULT_EVENT_MAXLEN;
+  const tombstoneRetentionMs = config.limits?.tombstoneRetentionMs ?? DEFAULT_TOMBSTONE_RETENTION_MS;
+  const resolveTenant = (tenantId) => {
+    const resolved = tenantId ?? defaultTenant;
+    assertIdentifier(resolved, "tenantId");
+    return resolved;
+  };
+  const tenantStates = new Map;
+  const getTenantState = (tenantId) => {
+    let state = tenantStates.get(tenantId);
+    if (!state) {
+      state = {
+        seq: 0,
+        entries: new Map,
+        ttlTimers: new Map,
+        tombstones: new Map,
+        tombstoneTimers: new Map,
+        prefixRefs: new Map,
+        rootEventLog: new EventLog({ maxLen: eventMaxLen, retentionMs: eventRetentionMs }),
+        keyEventLogs: new Map,
+        prefixEventLogs: new Map
+      };
+      tenantStates.set(tenantId, state);
+    }
+    return state;
+  };
+  const getKeyEventLog = (state, key) => {
+    let log = state.keyEventLogs.get(key);
+    if (!log) {
+      log = new EventLog({ maxLen: eventMaxLen, retentionMs: eventRetentionMs });
+      state.keyEventLogs.set(key, log);
+    }
+    return log;
+  };
+  const getPrefixEventLog = (state, pfx) => {
+    let log = state.prefixEventLogs.get(pfx);
+    if (!log) {
+      log = new EventLog({ maxLen: eventMaxLen, retentionMs: eventRetentionMs });
+      state.prefixEventLogs.set(pfx, log);
+    }
+    return log;
+  };
+  const prefixRefInc = (state, key) => {
+    for (const pfx of ancestorPrefixes(key)) {
+      state.prefixRefs.set(pfx, (state.prefixRefs.get(pfx) ?? 0) + 1);
+    }
+  };
+  const prefixRefDec = (state, key) => {
+    for (const pfx of ancestorPrefixes(key)) {
+      const next = (state.prefixRefs.get(pfx) ?? 1) - 1;
+      if (next <= 0) {
+        state.prefixRefs.delete(pfx);
+      } else {
+        state.prefixRefs.set(pfx, next);
+      }
+    }
+  };
+  const emitEvent = (state, key, fields) => {
+    state.rootEventLog.append(fields);
+    getKeyEventLog(state, key).append(fields);
+    for (const pfx of ancestorPrefixes(key)) {
+      getPrefixEventLog(state, pfx).append(fields);
+    }
+  };
+  const scheduleExpiry = (state, logicalKey, ttlMs) => {
+    const existing = state.ttlTimers.get(logicalKey);
+    if (existing)
+      clearTimeout(existing);
+    state.ttlTimers.set(logicalKey, setTimeout(() => {
+      const entry = state.entries.get(logicalKey);
+      if (!entry)
+        return;
+      state.entries.delete(logicalKey);
+      state.ttlTimers.delete(logicalKey);
+      prefixRefDec(state, logicalKey);
+      const version = String(++state.seq);
+      const tombstone = {
+        key: logicalKey,
+        version,
+        removedAt: Date.now()
+      };
+      state.tombstones.set(logicalKey, tombstone);
+      state.tombstoneTimers.set(logicalKey, setTimeout(() => {
+        state.tombstones.delete(logicalKey);
+        state.tombstoneTimers.delete(logicalKey);
+      }, tombstoneRetentionMs));
+      emitEvent(state, logicalKey, {
+        type: "expire",
+        key: logicalKey,
+        version,
+        removedAt: Date.now()
+      });
+    }, ttlMs));
+  };
+  const upsert = async (cfg) => {
+    assertLogicalKey(cfg.key);
+    const tenantId = resolveTenant(cfg.tenantId);
+    const state = getTenantState(tenantId);
+    const isNew = !state.entries.has(cfg.key);
+    if (isNew && state.entries.size >= maxEntries) {
+      throw new RegistryCapacityError(`maxEntries (${maxEntries}) reached`);
+    }
+    const parsed = config.schema.safeParse(cfg.value);
+    if (!parsed.success)
+      throw parsed.error;
+    const payloadRaw = JSON.stringify(parsed.data);
+    const payloadBytes = textEncoder.encode(payloadRaw).byteLength;
+    if (payloadBytes > maxPayloadBytes) {
+      throw new RegistryPayloadTooLargeError(`payload exceeds limit (${maxPayloadBytes} bytes)`);
+    }
+    const now = Date.now();
+    const version = String(++state.seq);
+    const existingEntry = state.entries.get(cfg.key);
+    const stored = {
+      key: cfg.key,
+      data: parsed.data,
+      version,
+      createdAt: existingEntry?.createdAt ?? now,
+      updatedAt: now,
+      ttlMs: cfg.ttlMs ?? null,
+      expiresAt: cfg.ttlMs != null ? now + cfg.ttlMs : null
+    };
+    if (isNew) {
+      prefixRefInc(state, cfg.key);
+    }
+    state.entries.set(cfg.key, stored);
+    const tombstoneTimer = state.tombstoneTimers.get(cfg.key);
+    if (tombstoneTimer) {
+      clearTimeout(tombstoneTimer);
+      state.tombstoneTimers.delete(cfg.key);
+    }
+    state.tombstones.delete(cfg.key);
+    if (stored.ttlMs != null) {
+      scheduleExpiry(state, cfg.key, stored.ttlMs);
+    } else {
+      const ttlTimer = state.ttlTimers.get(cfg.key);
+      if (ttlTimer) {
+        clearTimeout(ttlTimer);
+        state.ttlTimers.delete(cfg.key);
+      }
+    }
+    const result = {
+      key: cfg.key,
+      value: parsed.data,
+      version,
+      status: "active",
+      createdAt: stored.createdAt,
+      updatedAt: now,
+      ttlMs: stored.ttlMs,
+      expiresAt: stored.expiresAt
+    };
+    emitEvent(state, cfg.key, {
+      type: "upsert",
+      key: cfg.key,
+      version,
+      status: "active",
+      createdAt: stored.createdAt,
+      updatedAt: now,
+      ttlMs: stored.ttlMs,
+      expiresAt: stored.expiresAt,
+      payload: payloadRaw
+    });
+    return result;
+  };
+  const touch = async (cfg) => {
+    assertLogicalKey(cfg.key);
+    const tenantId = resolveTenant(cfg.tenantId);
+    const state = getTenantState(tenantId);
+    const existing = state.entries.get(cfg.key);
+    if (!existing)
+      return { ok: false };
+    let ttlMs = cfg.ttlMs;
+    if (ttlMs == null) {
+      if (existing.expiresAt == null)
+        return { ok: false };
+      ttlMs = existing.expiresAt - existing.updatedAt;
+      if (ttlMs <= 0)
+        ttlMs = 1;
+    }
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0)
+      throw new Error("ttlMs must be > 0");
+    const now = Date.now();
+    const expiresAt = now + ttlMs;
+    existing.updatedAt = now;
+    existing.expiresAt = expiresAt;
+    scheduleExpiry(state, cfg.key, ttlMs);
+    emitEvent(state, cfg.key, {
+      type: "touch",
+      key: cfg.key,
+      version: existing.version,
+      updatedAt: now,
+      expiresAt
+    });
+    return { ok: true, version: existing.version, expiresAt };
+  };
+  const remove = async (cfg) => {
+    assertLogicalKey(cfg.key);
+    const tenantId = resolveTenant(cfg.tenantId);
+    const state = getTenantState(tenantId);
+    const existing = state.entries.get(cfg.key);
+    if (!existing)
+      return false;
+    state.entries.delete(cfg.key);
+    prefixRefDec(state, cfg.key);
+    const ttlTimer = state.ttlTimers.get(cfg.key);
+    if (ttlTimer) {
+      clearTimeout(ttlTimer);
+      state.ttlTimers.delete(cfg.key);
+    }
+    const version = String(++state.seq);
+    const now = Date.now();
+    const tombstone = {
+      key: cfg.key,
+      version,
+      removedAt: now,
+      reason: cfg.reason
+    };
+    state.tombstones.set(cfg.key, tombstone);
+    state.tombstoneTimers.set(cfg.key, setTimeout(() => {
+      state.tombstones.delete(cfg.key);
+      state.tombstoneTimers.delete(cfg.key);
+    }, tombstoneRetentionMs));
+    const fields = {
+      type: "delete",
+      key: cfg.key,
+      version,
+      removedAt: now
+    };
+    if (cfg.reason)
+      fields.reason = cfg.reason;
+    emitEvent(state, cfg.key, fields);
+    return true;
+  };
+  const get = async (cfg) => {
+    assertLogicalKey(cfg.key);
+    const tenantId = resolveTenant(cfg.tenantId);
+    const state = getTenantState(tenantId);
+    const stored = state.entries.get(cfg.key);
+    if (stored) {
+      const parsed = config.schema.safeParse(stored.data);
+      if (!parsed.success)
+        return null;
+      return {
+        key: stored.key,
+        value: parsed.data,
+        version: stored.version,
+        status: "active",
+        createdAt: stored.createdAt,
+        updatedAt: stored.updatedAt,
+        ttlMs: stored.ttlMs,
+        expiresAt: stored.expiresAt
+      };
+    }
+    if (cfg.includeExpired) {
+      const tombstone = state.tombstones.get(cfg.key);
+      if (tombstone) {
+        return {
+          key: tombstone.key,
+          value: null,
+          version: tombstone.version,
+          status: "expired",
+          createdAt: tombstone.removedAt,
+          updatedAt: tombstone.removedAt,
+          ttlMs: null,
+          expiresAt: null
+        };
+      }
+    }
+    return null;
+  };
+  const list = async (cfg = {}) => {
+    const tenantId = resolveTenant(cfg.tenantId);
+    const state = getTenantState(tenantId);
+    const limit = cfg.limit ?? DEFAULT_LIST_LIMIT;
+    const status = cfg.status ?? "active";
+    const entries = [];
+    if (status === "active") {
+      for (const stored of state.entries.values()) {
+        if (cfg.prefix && !stored.key.startsWith(cfg.prefix))
+          continue;
+        const parsed = config.schema.safeParse(stored.data);
+        if (!parsed.success)
+          continue;
+        entries.push({
+          key: stored.key,
+          value: parsed.data,
+          version: stored.version,
+          status: "active",
+          createdAt: stored.createdAt,
+          updatedAt: stored.updatedAt,
+          ttlMs: stored.ttlMs,
+          expiresAt: stored.expiresAt
+        });
+      }
+    } else {
+      for (const tombstone of state.tombstones.values()) {
+        if (cfg.prefix && !tombstone.key.startsWith(cfg.prefix))
+          continue;
+        entries.push({
+          key: tombstone.key,
+          value: null,
+          version: tombstone.version,
+          status: "expired",
+          createdAt: tombstone.removedAt,
+          updatedAt: tombstone.removedAt,
+          ttlMs: null,
+          expiresAt: null
+        });
+      }
+    }
+    entries.sort((a, b) => a.key.localeCompare(b.key));
+    let start = 0;
+    if (cfg.afterKey) {
+      const idx = entries.findIndex((e) => e.key > cfg.afterKey);
+      start = idx >= 0 ? idx : entries.length;
+    }
+    const paginated = entries.slice(start, start + limit);
+    const hasMore = start + limit < entries.length;
+    return {
+      entries: paginated,
+      cursor: state.rootEventLog.latest(),
+      nextKey: hasMore ? entries[start + limit].key : undefined
+    };
+  };
+  const cas = async (cfg) => {
+    assertLogicalKey(cfg.key);
+    const tenantId = resolveTenant(cfg.tenantId);
+    const state = getTenantState(tenantId);
+    const existing = state.entries.get(cfg.key);
+    if (!existing)
+      return { ok: false };
+    if (existing.version !== cfg.version)
+      return { ok: false };
+    let preservedTtlMs;
+    if (existing.expiresAt != null) {
+      preservedTtlMs = Math.max(1, existing.expiresAt - Date.now());
+    }
+    const entry = await upsert({
+      key: cfg.key,
+      value: cfg.value,
+      ttlMs: preservedTtlMs,
+      tenantId: cfg.tenantId
+    });
+    return { ok: true, entry };
+  };
+  const reader = (readerCfg = {}) => {
+    const tenantId = resolveTenant(readerCfg.tenantId);
+    const state = getTenantState(tenantId);
+    let log;
+    if (readerCfg.key) {
+      log = getKeyEventLog(state, readerCfg.key);
+    } else if (readerCfg.prefix) {
+      log = getPrefixEventLog(state, readerCfg.prefix);
+    } else {
+      log = state.rootEventLog;
+    }
+    let cursor = readerCfg.after ?? log.latest();
+    const parseEvent = (entry) => {
+      const type = entry.fields.type;
+      if (type === "upsert") {
+        const rawPayload = entry.fields.payload;
+        if (!rawPayload)
+          return null;
+        try {
+          const payload = JSON.parse(rawPayload);
+          const parsed = config.schema.safeParse(payload);
+          if (!parsed.success)
+            return null;
+          return {
+            type: "upsert",
+            cursor: entry.id,
+            entry: {
+              key: entry.fields.key ?? "",
+              value: parsed.data,
+              version: String(entry.fields.version ?? ""),
+              status: "active",
+              createdAt: Number(entry.fields.createdAt ?? entry.fields.updatedAt),
+              updatedAt: Number(entry.fields.updatedAt),
+              ttlMs: entry.fields.ttlMs != null ? Number(entry.fields.ttlMs) : null,
+              expiresAt: entry.fields.expiresAt != null ? Number(entry.fields.expiresAt) : null
+            }
+          };
+        } catch {
+          return null;
+        }
+      }
+      if (type === "touch") {
+        return {
+          type: "touch",
+          cursor: entry.id,
+          key: entry.fields.key ?? "",
+          version: String(entry.fields.version ?? ""),
+          updatedAt: Number(entry.fields.updatedAt ?? entry.fields.expiresAt),
+          expiresAt: Number(entry.fields.expiresAt)
+        };
+      }
+      if (type === "delete") {
+        return {
+          type: "delete",
+          cursor: entry.id,
+          key: entry.fields.key ?? "",
+          version: String(entry.fields.version ?? ""),
+          removedAt: Number(entry.fields.removedAt ?? entry.fields.deletedAt),
+          reason: entry.fields.reason
+        };
+      }
+      if (type === "expire") {
+        return {
+          type: "expire",
+          cursor: entry.id,
+          key: entry.fields.key ?? "",
+          version: String(entry.fields.version ?? ""),
+          removedAt: Number(entry.fields.removedAt ?? entry.fields.expiredAt)
+        };
+      }
+      return null;
+    };
+    const recv = async (cfg = {}) => {
+      const wait = cfg.wait ?? true;
+      const timeoutMs = cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+      const entries = log.range(cursor, 1);
+      if (entries.length > 0) {
+        cursor = entries[0].id;
+        return parseEvent(entries[0]);
+      }
+      if (!wait)
+        return null;
+      const ac = new AbortController;
+      const timeout = setTimeout(() => ac.abort(), timeoutMs);
+      try {
+        for await (const entry of log.subscribe(cursor, cfg.signal ?? ac.signal)) {
+          clearTimeout(timeout);
+          cursor = entry.id;
+          const parsed = parseEvent(entry);
+          if (parsed)
+            return parsed;
+        }
+      } catch {} finally {
+        clearTimeout(timeout);
+      }
+      return null;
+    };
+    const stream = async function* (cfg = {}) {
+      const wait = cfg.wait ?? true;
+      while (!cfg.signal?.aborted) {
+        const event = await recv(cfg);
+        if (event) {
+          yield event;
+          continue;
+        }
+        if (!wait)
+          break;
+      }
+    };
+    return { recv, stream };
+  };
+  return { upsert, touch, remove, get, list, cas, reader };
+};
+export {
+  registry,
+  RegistryPayloadTooLargeError,
+  RegistryCapacityError
+};