@valentinkolb/sync 2.1.2 → 3.0.0

package/browser/ephemeral.js

@@ -0,0 +1,472 @@
+// 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/ephemeral.ts
+var DEFAULT_MAX_ENTRIES = 1e4;
+var DEFAULT_MAX_PAYLOAD_BYTES = 4 * 1024;
+var DEFAULT_EVENT_RETENTION_MS = 5 * 60 * 1000;
+var DEFAULT_EVENT_MAXLEN = 50000;
+var DEFAULT_TIMEOUT_MS = 30000;
+var MAX_KEY_BYTES = 512;
+var textEncoder = new TextEncoder;
+
+class EphemeralCapacityError extends Error {
+  constructor(message = "ephemeral store capacity reached") {
+    super(message);
+    this.name = "EphemeralCapacityError";
+  }
+}
+
+class EphemeralPayloadTooLargeError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EphemeralPayloadTooLargeError";
+  }
+}
+var assertLogicalKey = (value) => {
+  if (value.length === 0)
+    throw new Error("key must be non-empty");
+  const bytes = textEncoder.encode(value).byteLength;
+  if (bytes > MAX_KEY_BYTES)
+    throw new Error(`key exceeds max length (${MAX_KEY_BYTES} bytes)`);
+};
+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 ephemeral = (config) => {
+  if (!Number.isFinite(config.ttlMs) || config.ttlMs <= 0) {
+    throw new Error("ttlMs must be > 0");
+  }
+  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 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,
+        timers: new Map,
+        eventLog: new EventLog({ maxLen: eventMaxLen, retentionMs: eventRetentionMs })
+      };
+      tenantStates.set(tenantId, state);
+    }
+    return state;
+  };
+  const scheduleExpiry = (state, logicalKey, ttlMs) => {
+    const existing = state.timers.get(logicalKey);
+    if (existing)
+      clearTimeout(existing);
+    state.timers.set(logicalKey, setTimeout(() => {
+      const entry = state.entries.get(logicalKey);
+      if (!entry)
+        return;
+      state.entries.delete(logicalKey);
+      state.timers.delete(logicalKey);
+      const version = String(++state.seq);
+      state.eventLog.append({
+        type: "expire",
+        key: logicalKey,
+        version,
+        expiredAt: Date.now()
+      });
+    }, ttlMs));
+  };
+  const upsert = async (cfg) => {
+    assertLogicalKey(cfg.key);
+    const tenantId = resolveTenant(cfg.tenantId);
+    const state = getTenantState(tenantId);
+    const ttlMs = cfg.ttlMs ?? config.ttlMs;
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+      throw new Error("ttlMs must be > 0");
+    }
+    if (!state.entries.has(cfg.key) && state.entries.size >= maxEntries) {
+      throw new EphemeralCapacityError(`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 EphemeralPayloadTooLargeError(`payload exceeds limit (${maxPayloadBytes} bytes)`);
+    }
+    const now = Date.now();
+    const version = String(++state.seq);
+    const expiresAt = now + ttlMs;
+    const stored = {
+      key: cfg.key,
+      data: parsed.data,
+      version,
+      updatedAt: now,
+      expiresAt
+    };
+    state.entries.set(cfg.key, stored);
+    scheduleExpiry(state, cfg.key, ttlMs);
+    state.eventLog.append({
+      type: "upsert",
+      key: cfg.key,
+      version,
+      updatedAt: now,
+      expiresAt,
+      payload: payloadRaw
+    });
+    return {
+      key: cfg.key,
+      value: parsed.data,
+      version,
+      updatedAt: now,
+      expiresAt
+    };
+  };
+  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 };
+    const ttlMs = cfg.ttlMs ?? config.ttlMs;
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+      throw new Error("ttlMs must be > 0");
+    }
+    const now = Date.now();
+    const version = String(++state.seq);
+    const expiresAt = now + ttlMs;
+    existing.version = version;
+    existing.updatedAt = now;
+    existing.expiresAt = expiresAt;
+    scheduleExpiry(state, cfg.key, ttlMs);
+    state.eventLog.append({
+      type: "touch",
+      key: cfg.key,
+      version,
+      expiresAt
+    });
+    return { ok: true, 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);
+    const timer = state.timers.get(cfg.key);
+    if (timer) {
+      clearTimeout(timer);
+      state.timers.delete(cfg.key);
+    }
+    const version = String(++state.seq);
+    const fields = {
+      type: "delete",
+      key: cfg.key,
+      version,
+      deletedAt: Date.now()
+    };
+    if (cfg.reason)
+      fields.reason = cfg.reason;
+    state.eventLog.append(fields);
+    return true;
+  };
+  const snapshot = async (cfg = {}) => {
+    const tenantId = resolveTenant(cfg.tenantId);
+    const state = getTenantState(tenantId);
+    const entries = [];
+    for (const stored of state.entries.values()) {
+      const parsed = config.schema.safeParse(stored.data);
+      if (!parsed.success)
+        continue;
+      entries.push({
+        key: stored.key,
+        value: parsed.data,
+        version: stored.version,
+        updatedAt: stored.updatedAt,
+        expiresAt: stored.expiresAt
+      });
+    }
+    entries.sort((a, b) => a.key.localeCompare(b.key));
+    return {
+      entries,
+      cursor: state.eventLog.latest()
+    };
+  };
+  const reader = (readerCfg = {}) => {
+    const tenantId = resolveTenant(readerCfg.tenantId);
+    const state = getTenantState(tenantId);
+    let cursor = readerCfg.after ?? state.eventLog.latest();
+    let overflowPending = null;
+    let replayChecked = false;
+    const checkReplayGap = () => {
+      if (replayChecked)
+        return;
+      replayChecked = true;
+      const after = readerCfg.after;
+      if (!after || after === "0")
+        return;
+      const earliest = state.eventLog.earliest();
+      if (!earliest)
+        return;
+      if (!state.eventLog.has(after) && Number(after) < Number(earliest)) {
+        const liveCursor = state.eventLog.latest();
+        overflowPending = {
+          type: "overflow",
+          cursor: liveCursor,
+          after,
+          firstAvailable: earliest
+        };
+        cursor = liveCursor;
+      }
+    };
+    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 ?? ""),
+              updatedAt: Number(entry.fields.updatedAt),
+              expiresAt: Number(entry.fields.expiresAt)
+            }
+          };
+        } catch {
+          return null;
+        }
+      }
+      if (type === "touch") {
+        return {
+          type: "touch",
+          cursor: entry.id,
+          key: entry.fields.key ?? "",
+          version: String(entry.fields.version ?? ""),
+          expiresAt: Number(entry.fields.expiresAt)
+        };
+      }
+      if (type === "delete") {
+        return {
+          type: "delete",
+          cursor: entry.id,
+          key: entry.fields.key ?? "",
+          version: String(entry.fields.version ?? ""),
+          deletedAt: Number(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 ?? ""),
+          expiredAt: Number(entry.fields.expiredAt)
+        };
+      }
+      return null;
+    };
+    const recv = async (cfg = {}) => {
+      checkReplayGap();
+      if (overflowPending) {
+        const event = overflowPending;
+        overflowPending = null;
+        return event;
+      }
+      const wait = cfg.wait ?? true;
+      const timeoutMs = cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+      const entries = state.eventLog.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);
+      const signal = cfg.signal;
+      try {
+        for await (const entry of state.eventLog.subscribe(cursor, 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, snapshot, reader };
+};
+export {
+  ephemeral,
+  EphemeralPayloadTooLargeError,
+  EphemeralCapacityError
+};

package/browser/index.js

@@ -0,0 +1,21 @@
+export {
+  topic,
+  scheduler,
+  retry,
+  registry,
+  ratelimit,
+  queue,
+  mutex,
+  job,
+  isRetryableTransportError,
+  ephemeral,
+  createMemoryStore,
+  RegistryPayloadTooLargeError,
+  RegistryCapacityError,
+  RateLimitError,
+  MemoryStore,
+  LockError,
+  EphemeralPayloadTooLargeError,
+  EphemeralCapacityError,
+  DEFAULT_RETRY_OPTIONS
+};