stitchkit 0.70.1 → 0.70.3

package/dist/index.js

@@ -1089,6 +1089,597 @@ function createUrlBuilders(contracts, source, contractConfig) {
 function createScopedUrlBuilders(contracts, source, scopeConfigs) {
   return buildScopedRegistry(contracts, scopeConfigs, "URL builder", (contract, config) => createUrlBuilder(contract, source, config));
 }
+// src/browser/live-state.ts
+import { z as z3 } from "zod";
+
+// src/application/channel.ts
+import { z as z2 } from "zod";
+var PositiveSafeIntegerSchema = z2.number().int().positive().safe();
+var BoundedChannelPolicySchema = z2.enum(["ordered", "latest"]);
+var BoundedChannelStateSchema = z2.enum(["open", "draining", "closed", "failed"]);
+var BoundedChannelSnapshotSchema = z2.object({
+  state: BoundedChannelStateSchema,
+  policy: BoundedChannelPolicySchema,
+  queuedItems: z2.number().int().nonnegative(),
+  queuedBytes: z2.number().int().nonnegative(),
+  waitingReader: z2.boolean(),
+  offered: z2.number().int().nonnegative(),
+  delivered: z2.number().int().nonnegative(),
+  queued: z2.number().int().nonnegative(),
+  coalesced: z2.number().int().nonnegative(),
+  refused: z2.number().int().nonnegative(),
+  discarded: z2.number().int().nonnegative()
+}).strict().readonly();
+
+class BoundedChannelReaderError extends Error {
+  constructor() {
+    super("A bounded channel permits only one pending next() call");
+    this.name = "BoundedChannelReaderError";
+  }
+}
+function createBoundedChannel(config) {
+  const policy = BoundedChannelPolicySchema.parse(config.policy);
+  const maxItems = PositiveSafeIntegerSchema.parse(config.maxItems);
+  const maxBytes = PositiveSafeIntegerSchema.parse(config.maxBytes);
+  const queue = [];
+  let state = "open";
+  let queuedBytes = 0;
+  let waiting;
+  let failure;
+  let hasFailure = false;
+  let offered = 0;
+  let delivered = 0;
+  let queued = 0;
+  let coalesced = 0;
+  let refused = 0;
+  let discarded = 0;
+  const removeAbortListener = () => {
+    config.signal?.removeEventListener("abort", abortChannel);
+  };
+  const snapshot = () => BoundedChannelSnapshotSchema.parse({
+    state,
+    policy,
+    queuedItems: queue.length,
+    queuedBytes,
+    waitingReader: waiting !== undefined,
+    offered,
+    delivered,
+    queued,
+    coalesced,
+    refused,
+    discarded
+  });
+  const clearQueue = () => {
+    discarded += queue.length;
+    queue.length = 0;
+    queuedBytes = 0;
+  };
+  const settleClosed = () => {
+    if (state !== "draining" || queue.length > 0)
+      return;
+    state = "closed";
+    removeAbortListener();
+    const reader = waiting;
+    waiting = undefined;
+    reader?.resolve({ done: true, value: undefined });
+  };
+  const close = (options = {}) => {
+    if (state === "closed" || state === "failed")
+      return snapshot();
+    const mode = options.mode ?? "drain";
+    if (mode !== "drain" && mode !== "discard") {
+      throw new TypeError("Bounded channel close mode must be drain or discard");
+    }
+    if (mode === "discard") {
+      clearQueue();
+      state = "closed";
+      removeAbortListener();
+      const reader = waiting;
+      waiting = undefined;
+      reader?.resolve({ done: true, value: undefined });
+      return snapshot();
+    }
+    state = "draining";
+    settleClosed();
+    return snapshot();
+  };
+  function abortChannel() {
+    close({ mode: "discard" });
+  }
+  const channel = {
+    [Symbol.asyncIterator]() {
+      return channel;
+    },
+    offer(value) {
+      offered += 1;
+      if (state !== "open") {
+        refused += 1;
+        return { outcome: "refused", reason: "not-open" };
+      }
+      const bytes = config.sizeOf(value);
+      if (!Number.isSafeInteger(bytes) || bytes < 0) {
+        throw new TypeError("Bounded channel sizeOf() must return a non-negative safe integer");
+      }
+      if (bytes > maxBytes) {
+        refused += 1;
+        return { outcome: "refused", reason: "item-too-large" };
+      }
+      const reader = waiting;
+      if (reader) {
+        waiting = undefined;
+        delivered += 1;
+        reader.resolve({ done: false, value });
+        return { outcome: "delivered" };
+      }
+      if (policy === "latest" && queue.length > 0) {
+        const previous = queue[0];
+        if (!previous)
+          throw new Error("Bounded latest channel lost its pending value");
+        queue[0] = { value, bytes };
+        queuedBytes += bytes - previous.bytes;
+        coalesced += 1;
+        return { outcome: "coalesced", replaced: 1 };
+      }
+      if (queue.length >= maxItems) {
+        refused += 1;
+        return { outcome: "refused", reason: "item-capacity" };
+      }
+      if (queuedBytes + bytes > maxBytes) {
+        refused += 1;
+        return { outcome: "refused", reason: "byte-capacity" };
+      }
+      queue.push({ value, bytes });
+      queuedBytes += bytes;
+      queued += 1;
+      return { outcome: "queued" };
+    },
+    next() {
+      if (hasFailure)
+        return Promise.reject(failure);
+      const next = queue.shift();
+      if (next) {
+        queuedBytes -= next.bytes;
+        delivered += 1;
+        settleClosed();
+        return Promise.resolve({ done: false, value: next.value });
+      }
+      if (state === "closed" || state === "draining") {
+        settleClosed();
+        return Promise.resolve({ done: true, value: undefined });
+      }
+      if (waiting)
+        return Promise.reject(new BoundedChannelReaderError);
+      return new Promise((resolve, reject) => {
+        waiting = { resolve, reject };
+      });
+    },
+    return() {
+      close({ mode: "discard" });
+      return Promise.resolve({ done: true, value: undefined });
+    },
+    throw(error) {
+      channel.fail(error);
+      return Promise.reject(error);
+    },
+    close,
+    fail(error) {
+      if (state === "closed" || state === "failed")
+        return snapshot();
+      failure = error;
+      hasFailure = true;
+      state = "failed";
+      clearQueue();
+      removeAbortListener();
+      const reader = waiting;
+      waiting = undefined;
+      reader?.reject(error);
+      return snapshot();
+    },
+    getSnapshot: snapshot
+  };
+  if (config.signal?.aborted)
+    abortChannel();
+  else
+    config.signal?.addEventListener("abort", abortChannel, { once: true });
+  return channel;
+}
+var CreditWindowSnapshotSchema = z2.object({
+  state: z2.enum(["open", "closed"]),
+  capacityBytes: PositiveSafeIntegerSchema,
+  availableBytes: z2.number().int().nonnegative(),
+  leasedBytes: z2.number().int().nonnegative(),
+  acquired: z2.number().int().nonnegative(),
+  refused: z2.number().int().nonnegative(),
+  replenishedBytes: z2.number().int().nonnegative()
+}).strict().readonly();
+
+// src/browser/live-state.ts
+var PositiveSafeIntegerSchema2 = z3.number().int().positive().safe();
+var LiveStatePhaseSchema = z3.enum([
+  "idle",
+  "opening",
+  "live",
+  "resync-required",
+  "unavailable",
+  "closed"
+]);
+var LiveStateStopReasonSchema = z3.enum([
+  "gap",
+  "buffer-overflow",
+  "source-unavailable",
+  "source-error",
+  "controller-error",
+  "controller-capacity"
+]);
+var LiveStateControllerStatusSchema = z3.object({
+  phase: LiveStatePhaseSchema,
+  generation: z3.number().int().nonnegative(),
+  hasValue: z3.boolean(),
+  bufferedEvents: z3.number().int().nonnegative(),
+  bufferedBytes: z3.number().int().nonnegative(),
+  receivedEvents: z3.number().int().nonnegative(),
+  appliedEvents: z3.number().int().nonnegative(),
+  duplicateEvents: z3.number().int().nonnegative(),
+  gapEvents: z3.number().int().nonnegative(),
+  refusedEvents: z3.number().int().nonnegative(),
+  reason: LiveStateStopReasonSchema.optional()
+}).strict().readonly();
+function createLiveStateController(config) {
+  const maxBufferedEvents = PositiveSafeIntegerSchema2.parse(config.maxBufferedEvents);
+  const maxBufferedBytes = PositiveSafeIntegerSchema2.parse(config.maxBufferedBytes);
+  const subscribers = new Set;
+  let phase = "idle";
+  let reason;
+  let generation = 0;
+  let stored = { hasValue: false };
+  let receivedEvents = 0;
+  let appliedEvents = 0;
+  let duplicateEvents = 0;
+  let gapEvents = 0;
+  let refusedEvents = 0;
+  let current;
+  let opening;
+  let unsettledSourceOpens = 0;
+  let unsettledSourceCloses = 0;
+  let publishDepth = 0;
+  let controllerErrorObserverEnabled = true;
+  let subscriberErrorObserverEnabled = true;
+  const isPromiseLike = (value) => (typeof value === "object" || typeof value === "function") && value !== null && ("then" in value) && typeof value.then === "function";
+  const status = () => {
+    const buffered = current?.buffer.getSnapshot();
+    return LiveStateControllerStatusSchema.parse({
+      phase,
+      generation,
+      hasValue: stored.hasValue,
+      bufferedEvents: buffered?.queuedItems ?? 0,
+      bufferedBytes: buffered?.queuedBytes ?? 0,
+      receivedEvents,
+      appliedEvents,
+      duplicateEvents,
+      gapEvents,
+      refusedEvents,
+      ...reason && { reason }
+    });
+  };
+  const buildSnapshot = () => {
+    const metadata = status();
+    return stored.hasValue ? Object.freeze({ ...metadata, value: stored.value }) : metadata;
+  };
+  let published = buildSnapshot();
+  const reportControllerError = (error, at, atGeneration) => {
+    if (!config.onControllerError || !controllerErrorObserverEnabled)
+      return;
+    try {
+      const returned = config.onControllerError({
+        error,
+        generation: atGeneration,
+        phase: at
+      });
+      if (isPromiseLike(returned)) {
+        controllerErrorObserverEnabled = false;
+        Promise.resolve(returned).catch(() => {
+          return;
+        });
+      }
+    } catch {}
+  };
+  const reportSubscriberError = (error, snapshot) => {
+    if (!config.onSubscriberError || !subscriberErrorObserverEnabled)
+      return;
+    try {
+      const returned = config.onSubscriberError({ error, snapshot });
+      if (isPromiseLike(returned)) {
+        subscriberErrorObserverEnabled = false;
+        Promise.resolve(returned).catch(() => {
+          return;
+        });
+      }
+    } catch {}
+  };
+  const publish = () => {
+    const snapshot = buildSnapshot();
+    published = snapshot;
+    publishDepth += 1;
+    try {
+      for (const listener of subscribers) {
+        try {
+          const returned = listener(snapshot);
+          if (isPromiseLike(returned)) {
+            subscribers.delete(listener);
+            reportSubscriberError(new TypeError("Live-state subscribers must settle synchronously"), snapshot);
+            Promise.resolve(returned).catch(() => {
+              return;
+            });
+          }
+        } catch (error) {
+          reportSubscriberError(error, snapshot);
+        }
+      }
+    } finally {
+      publishDepth -= 1;
+    }
+    return published;
+  };
+  const publishAvailableCapacity = () => {
+    if (phase !== "unavailable" || reason !== "controller-capacity" || unsettledSourceOpens + unsettledSourceCloses >= 2)
+      return;
+    phase = "resync-required";
+    publish();
+  };
+  const closeSource = (active) => {
+    if (active.closePromise)
+      return active.closePromise;
+    if (!active.closeSource)
+      return Promise.resolve();
+    const at = phase;
+    unsettledSourceCloses += 1;
+    active.closePromise = Promise.resolve().then(() => active.closeSource?.()).then(() => {
+      return;
+    }).catch((error) => {
+      reportControllerError(error, at, active.id);
+    }).finally(() => {
+      unsettledSourceCloses -= 1;
+      publishAvailableCapacity();
+    });
+    return active.closePromise;
+  };
+  const retire = (active) => {
+    if (!active.retired) {
+      active.retired = true;
+      active.settleRetired();
+      active.abort.abort();
+      active.buffer.close({ mode: "discard" });
+    }
+    return closeSource(active);
+  };
+  const stopGeneration = (active, nextPhase, nextReason) => {
+    if (current !== active || active.retired || phase === "closed")
+      return;
+    phase = nextPhase;
+    reason = nextReason;
+    retire(active);
+    publish();
+  };
+  const apply = (active, event) => {
+    if (current !== active || active.retired || !stored.hasValue || phase !== "opening" && phase !== "live")
+      return;
+    let decision;
+    try {
+      decision = config.applyEvent(stored.value, event);
+    } catch (error) {
+      reportControllerError(error, phase, active.id);
+      stopGeneration(active, "unavailable", "controller-error");
+      return;
+    }
+    if (current !== active || active.retired || phase !== "opening" && phase !== "live")
+      return;
+    if (!decision || !["applied", "duplicate", "gap"].includes(decision.outcome) || decision.outcome === "applied" && !("state" in decision)) {
+      reportControllerError(new Error("applyEvent returned an invalid decision"), phase, active.id);
+      stopGeneration(active, "unavailable", "controller-error");
+      return;
+    }
+    if (decision.outcome === "duplicate") {
+      duplicateEvents += 1;
+      publish();
+      return;
+    }
+    if (decision.outcome === "gap") {
+      gapEvents += 1;
+      stopGeneration(active, "resync-required", "gap");
+      return;
+    }
+    stored = { hasValue: true, value: decision.state };
+    appliedEvents += 1;
+    publish();
+  };
+  const onEvent = (active, event) => {
+    if (current !== active || active.retired || phase === "closed")
+      return;
+    receivedEvents += 1;
+    if (phase === "opening") {
+      try {
+        const offered = active.buffer.offer(event);
+        if (offered.outcome === "refused") {
+          refusedEvents += 1;
+          stopGeneration(active, "resync-required", "buffer-overflow");
+        } else {
+          publish();
+        }
+      } catch (error) {
+        refusedEvents += 1;
+        reportControllerError(error, phase, active.id);
+        stopGeneration(active, "unavailable", "controller-error");
+      }
+      return;
+    }
+    if (phase === "live")
+      apply(active, event);
+  };
+  const openGeneration = async (active) => {
+    try {
+      if (active.retired || current !== active || phase === "closed")
+        return published;
+      unsettledSourceOpens += 1;
+      let sourceOpening;
+      try {
+        sourceOpening = config.source.open({
+          signal: active.abort.signal,
+          onEvent: (event) => onEvent(active, event),
+          onUnavailable: () => stopGeneration(active, "unavailable", "source-unavailable")
+        });
+      } catch (error) {
+        unsettledSourceOpens -= 1;
+        publishAvailableCapacity();
+        throw error;
+      }
+      sourceOpening = sourceOpening.then((opened2) => {
+        active.closeSource = () => opened2.close();
+        unsettledSourceOpens -= 1;
+        if (active.retired || current !== active || phase === "closed") {
+          closeSource(active);
+        }
+        publishAvailableCapacity();
+        return opened2;
+      }, (error) => {
+        unsettledSourceOpens -= 1;
+        publishAvailableCapacity();
+        throw error;
+      });
+      const outcome = await Promise.race([
+        sourceOpening.then((opened2) => ({ outcome: "opened", opened: opened2 })),
+        active.retiredPromise.then(() => ({ outcome: "retired" }))
+      ]);
+      if (outcome.outcome === "retired") {
+        return published;
+      }
+      const { opened } = outcome;
+      if (current !== active || active.retired || phase !== "opening") {
+        closeSource(active);
+        return published;
+      }
+      stored = { hasValue: true, value: opened.snapshot };
+      publish();
+      while (current === active && !active.retired && phase === "opening") {
+        if (active.buffer.getSnapshot().queuedItems === 0) {
+          active.buffer.close({ mode: "discard" });
+          phase = "live";
+          reason = undefined;
+          return publish();
+        }
+        const next = await active.buffer.next();
+        if (next.done)
+          break;
+        apply(active, next.value);
+      }
+      if (current && current !== active && opening)
+        return opening;
+      return published;
+    } catch (error) {
+      if (current === active && !active.retired && phase !== "closed") {
+        reportControllerError(error, phase, active.id);
+        stopGeneration(active, "unavailable", "source-error");
+      }
+      publishAvailableCapacity();
+      return published;
+    }
+  };
+  const begin = (startedByResync) => {
+    generation += 1;
+    phase = "opening";
+    reason = undefined;
+    let settleRetired = () => {
+      return;
+    };
+    const retiredPromise = new Promise((resolve) => {
+      settleRetired = resolve;
+    });
+    const active = {
+      id: generation,
+      startedByResync,
+      abort: new AbortController,
+      buffer: createBoundedChannel({
+        policy: "ordered",
+        maxItems: maxBufferedEvents,
+        maxBytes: maxBufferedBytes,
+        sizeOf: config.sizeOfEvent
+      }),
+      retiredPromise,
+      settleRetired,
+      retired: false,
+      sourceOpenStarted: false
+    };
+    current = active;
+    publish();
+    if (current !== active || active.retired || phase !== "opening") {
+      return opening ?? Promise.resolve(published);
+    }
+    active.sourceOpenStarted = true;
+    const operation = openGeneration(active);
+    opening = operation;
+    operation.finally(() => {
+      if (opening === operation)
+        opening = undefined;
+    });
+    return operation;
+  };
+  const close = () => {
+    if (phase === "closed")
+      return Promise.resolve(published);
+    const active = current;
+    current = undefined;
+    phase = "closed";
+    reason = undefined;
+    const snapshot = publish();
+    if (active)
+      retire(active);
+    config.signal?.removeEventListener("abort", abortFromConfig);
+    subscribers.clear();
+    return Promise.resolve(snapshot);
+  };
+  function abortFromConfig() {
+    close();
+  }
+  if (config.signal?.aborted) {
+    phase = "closed";
+    published = buildSnapshot();
+  } else {
+    config.signal?.addEventListener("abort", abortFromConfig, { once: true });
+  }
+  return {
+    start() {
+      if (phase === "idle")
+        return begin(false);
+      return opening ?? Promise.resolve(published);
+    },
+    resync() {
+      if (phase === "closed")
+        return Promise.resolve(published);
+      const active = current;
+      if (active?.startedByResync && !active.sourceOpenStarted && phase === "opening" && publishDepth > 0) {
+        return opening ?? Promise.resolve(published);
+      }
+      if (active) {
+        retire(active);
+        if (unsettledSourceOpens + unsettledSourceCloses >= 2) {
+          phase = "unavailable";
+          reason = "controller-capacity";
+          return Promise.resolve(publish());
+        }
+      }
+      return begin(true);
+    },
+    getSnapshot: () => published,
+    subscribe(listener) {
+      if (phase === "closed")
+        return () => {
+          return;
+        };
+      subscribers.add(listener);
+      return () => subscribers.delete(listener);
+    },
+    close
+  };
+}
 // src/internal/optional-peer.ts
 function isModuleNotFound(error) {
   if (typeof error !== "object" || error === null)
@@ -1099,19 +1690,19 @@ function isModuleNotFound(error) {
 }
 
 // src/realtime/request.ts
-import { z as z2 } from "zod";
-var RealtimeRequestPhaseSchema = z2.enum([
+import { z as z4 } from "zod";
+var RealtimeRequestPhaseSchema = z4.enum([
   "engine-handoff",
   "engine-ack-received",
   "settled",
   "timeout",
   "disconnected"
 ]);
-var RealtimeRequestPhaseEventSchema = z2.object({
-  requestId: z2.string().min(1),
-  event: z2.string().min(1),
+var RealtimeRequestPhaseEventSchema = z4.object({
+  requestId: z4.string().min(1),
+  event: z4.string().min(1),
   phase: RealtimeRequestPhaseSchema,
-  elapsedMs: z2.number().finite().nonnegative()
+  elapsedMs: z4.number().finite().nonnegative()
 }).strict();
 
 class RealtimeRequestTimeoutError extends Error {
@@ -1201,9 +1792,9 @@ function parseIssues(value) {
 }
 
 // src/realtime/rejection.ts
-import { z as z3 } from "zod";
+import { z as z5 } from "zod";
 function realtimeContractViolation(options) {
-  const issues = options.cause instanceof z3.ZodError ? zodIssues(options.cause) : undefined;
+  const issues = options.cause instanceof z5.ZodError ? zodIssues(options.cause) : undefined;
   const reason = options.reason.replaceAll("-", " ");
   const error = new AppError("REALTIME_CONTRACT_VIOLATION", `Realtime event "${options.event}" (${options.direction}, ${options.phase}): ${reason}`, 500, {
     event: options.event,
@@ -1939,57 +2530,77 @@ function createSocketIOClientInternal(config, onRequestPhase) {
   };
 }
 // src/realtime/contract.ts
+import { z as z6 } from "zod";
 function defineRealtimeContract(contract) {
   return contract;
 }
+var RealtimeRejectDirectionSchema = z6.enum([
+  "client-inbound",
+  "client-outbound",
+  "server-inbound",
+  "server-outbound"
+]);
+var RealtimeRejectPhaseSchema = z6.enum(["arguments", "acknowledgement"]);
+var RealtimeRejectReasonSchema = z6.enum([
+  "unknown-event",
+  "invalid-arguments",
+  "invalid-acknowledgement-value",
+  "missing-acknowledgement",
+  "rejected-by-peer"
+]);
+var RealtimeRejectFaultSchema = z6.enum(["peer", "local"]);
 export {
-  ALL_TRANSPORTS,
-  ApiError,
-  AppError,
-  ContractStreamFrameSchema,
-  DEFAULT_CONTRACT_STREAM_FRAME_BYTES,
-  ManagedFilePathSchema,
-  ManagedFileRefSchema,
-  REALTIME_REJECTION_KEY,
-  RealtimeRequestDisconnectedError,
-  RealtimeRequestInvalidAcknowledgementError,
-  RealtimeRequestPhaseEventSchema,
-  RealtimeRequestPhaseSchema,
-  RealtimeRequestRejectedError,
-  RealtimeRequestTimeoutError,
-  STITCH_ERROR_STATUS,
-  appError,
-  asRealtimeRejection,
-  badRequest,
-  bindRealtimeClient,
-  childSpan,
-  conflict,
-  contractEndpointMatchers,
-  createClient,
-  createClients,
-  createContractFactory,
-  createHttpClient,
-  createRealtimeClient,
-  createRetainedTopics,
-  createScopedClients,
-  createScopedUrlBuilders,
-  createSocketIOClient,
-  createTraceContext,
-  createUrlBuilder,
-  createUrlBuilders,
-  decodeCursor,
-  defineContract,
-  defineErrors,
-  defineRealtimeContract,
-  encodeCursor,
-  forbidden,
-  formatTraceparent,
-  isStitchErrorCode,
-  notFound,
-  paginatedSchema,
-  parseNDJSON,
-  parseSSE,
-  parseTraceparent,
+  unauthorized,
   rateLimited,
-  unauthorized
+  parseTraceparent,
+  parseSSE,
+  parseNDJSON,
+  paginatedSchema,
+  notFound,
+  isStitchErrorCode,
+  formatTraceparent,
+  forbidden,
+  encodeCursor,
+  defineRealtimeContract,
+  defineErrors,
+  defineContract,
+  decodeCursor,
+  createUrlBuilders,
+  createUrlBuilder,
+  createTraceContext,
+  createSocketIOClient,
+  createScopedUrlBuilders,
+  createScopedClients,
+  createRetainedTopics,
+  createRealtimeClient,
+  createLiveStateController,
+  createHttpClient,
+  createContractFactory,
+  createClients,
+  createClient,
+  contractEndpointMatchers,
+  conflict,
+  childSpan,
+  bindRealtimeClient,
+  badRequest,
+  asRealtimeRejection,
+  appError,
+  STITCH_ERROR_STATUS,
+  RealtimeRequestTimeoutError,
+  RealtimeRequestRejectedError,
+  RealtimeRequestPhaseSchema,
+  RealtimeRequestPhaseEventSchema,
+  RealtimeRequestInvalidAcknowledgementError,
+  RealtimeRequestDisconnectedError,
+  REALTIME_REJECTION_KEY,
+  ManagedFileRefSchema,
+  ManagedFilePathSchema,
+  LiveStateStopReasonSchema,
+  LiveStatePhaseSchema,
+  LiveStateControllerStatusSchema,
+  DEFAULT_CONTRACT_STREAM_FRAME_BYTES,
+  ContractStreamFrameSchema,
+  AppError,
+  ApiError,
+  ALL_TRANSPORTS
 };