stitchkit 0.74.1 → 0.75.0

package/dist/index-35z5h2ty.js

@@ -0,0 +1,594 @@
+// src/browser/live-state.ts
+import { z as z2 } from "zod";
+
+// src/application/channel.ts
+import { z } from "zod";
+var PositiveSafeIntegerSchema = z.number().int().positive().safe();
+var BoundedChannelPolicySchema = z.enum(["ordered", "latest"]);
+var BoundedChannelStateSchema = z.enum(["open", "draining", "closed", "failed"]);
+var BoundedChannelSnapshotSchema = z.object({
+  state: BoundedChannelStateSchema,
+  policy: BoundedChannelPolicySchema,
+  queuedItems: z.number().int().nonnegative(),
+  queuedBytes: z.number().int().nonnegative(),
+  waitingReader: z.boolean(),
+  offered: z.number().int().nonnegative(),
+  delivered: z.number().int().nonnegative(),
+  queued: z.number().int().nonnegative(),
+  coalesced: z.number().int().nonnegative(),
+  refused: z.number().int().nonnegative(),
+  discarded: z.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 = z.object({
+  state: z.enum(["open", "closed"]),
+  capacityBytes: PositiveSafeIntegerSchema,
+  availableBytes: z.number().int().nonnegative(),
+  leasedBytes: z.number().int().nonnegative(),
+  acquired: z.number().int().nonnegative(),
+  refused: z.number().int().nonnegative(),
+  replenishedBytes: z.number().int().nonnegative(),
+  waiting: z.number().int().nonnegative()
+}).strict().readonly();
+
+// src/browser/live-state.ts
+var PositiveSafeIntegerSchema2 = z2.number().int().positive().safe();
+var LiveStatePhaseSchema = z2.enum([
+  "idle",
+  "opening",
+  "live",
+  "resync-required",
+  "unavailable",
+  "closed"
+]);
+var LiveStateStopReasonSchema = z2.enum([
+  "gap",
+  "buffer-overflow",
+  "source-unavailable",
+  "source-error",
+  "controller-error",
+  "controller-capacity"
+]);
+var LiveStateControllerStatusSchema = z2.object({
+  phase: LiveStatePhaseSchema,
+  generation: z2.number().int().nonnegative(),
+  hasValue: z2.boolean(),
+  bufferedEvents: z2.number().int().nonnegative(),
+  bufferedBytes: z2.number().int().nonnegative(),
+  receivedEvents: z2.number().int().nonnegative(),
+  appliedEvents: z2.number().int().nonnegative(),
+  duplicateEvents: z2.number().int().nonnegative(),
+  gapEvents: z2.number().int().nonnegative(),
+  refusedEvents: z2.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
+  };
+}
+
+export { LiveStatePhaseSchema, LiveStateStopReasonSchema, LiveStateControllerStatusSchema, createLiveStateController };

package/dist/{index-f6n5n7nz.js → index-4kp4fxvp.js}

@@ -1,3 +1,7 @@
+import {
+  base64UrlToBytes,
+  bytesToBase64Url
+} from "./index-rxfy4cq7.js";
 import {
   mapObjectTypeBoundary
 } from "./index-ksp6e2ye.js";
@@ -431,24 +435,6 @@ var ManagedFileRefSchema = z3.object({
 });
 // src/contract/pagination.ts
 import { z as z4 } from "zod";
-
-// src/internal/base64url.ts
-function bytesToBase64Url(bytes) {
-  let binary = "";
-  for (const byte of bytes)
-    binary += String.fromCharCode(byte);
-  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-function base64UrlToBytes(segment) {
-  if (!/^[A-Za-z0-9_-]*$/.test(segment) || segment.length % 4 === 1) {
-    throw new Error("invalid base64url segment");
-  }
-  const b64 = segment.replace(/-/g, "+").replace(/_/g, "/");
-  const padded = b64.padEnd(Math.ceil(b64.length / 4) * 4, "=");
-  return Uint8Array.from(atob(padded), (c) => c.charCodeAt(0));
-}
-
-// src/contract/pagination.ts
 function paginatedSchema(itemSchema) {
   return z4.object({
     items: z4.array(itemSchema),

package/dist/{index-118v0z41.js → index-52400rdd.js}

@@ -7,7 +7,7 @@ import {
   defaultSignalSource,
   guardSignalCallback,
   reportSignalError
-} from "./index-vbf2p6me.js";
+} from "./index-endzd8sj.js";
 import {
   extractIp,
   getClientInfo,
@@ -18,7 +18,7 @@ import {
   runWithRequestContext,
   setRequestEndpoint,
   setRequestError
-} from "./index-nemjkxjp.js";
+} from "./index-e0a57ymn.js";
 import {
   ShutdownOptionsSchema,
   isStreamCancellation,
@@ -39,7 +39,7 @@ import {
   joinRoutePath,
   parseTrailingWildcard,
   safeJsonParse
-} from "./index-vj3vvpaa.js";
+} from "./index-hsz2mmk0.js";
 import {
   AppError,
   badRequest
@@ -1563,6 +1563,11 @@ function createHandler(config) {
       return fallback ?? resolveTraceId(req);
     }
   };
+  for (const group of config.groups ?? []) {
+    if (group.hooks && "onRequest" in group.hooks) {
+      throw new Error("[stitchkit] a route group cannot declare `onRequest` — it runs before routing, so the group it belongs to is not known yet and the hook would never be dispatched. Refuse before dispatch with the server-level `hooks.onRequest`, or gate the group with its `authorize`, which runs once the endpoint is known.");
+    }
+  }
   const routeMap = buildRouteMap(normalizeGroups(config));
   validateRoutes(routeMap);
   validateRawRoutes(config.rawRoutes);

package/dist/{index-da1aqnhb.js → index-65kathdm.js}

@@ -2,13 +2,15 @@ import {
   contextContributionDelta,
   mergeContextContribution,
   prepareContextContribution
-} from "./index-vbf2p6me.js";
+} from "./index-endzd8sj.js";
 import {
-  base64UrlToBytes,
-  bytesToBase64Url,
   isUnsafeKey,
   safeJsonParse
-} from "./index-vj3vvpaa.js";
+} from "./index-hsz2mmk0.js";
+import {
+  base64UrlToBytes,
+  bytesToBase64Url
+} from "./index-rxfy4cq7.js";
 import {
   forbidden,
   unauthorized

package/dist/{index-jqtsc9mj.js → index-6wr9f6qm.js}

@@ -1,10 +1,10 @@
 import {
   collectTools,
   createToolRunner
-} from "./index-7qy2ex0m.js";
+} from "./index-885chjxq.js";
 import {
   toolErrorFromResult
-} from "./index-s4c8wy8m.js";
+} from "./index-k68e5jz0.js";
 import {
   assertUniqueToolName
 } from "./index-22by16v6.js";

package/dist/{index-7qy2ex0m.js → index-885chjxq.js}

@@ -1,6 +1,6 @@
 import {
   executeToolMethod
-} from "./index-s4c8wy8m.js";
+} from "./index-k68e5jz0.js";
 import {
   assertToolExtensionCompatible,
   mergeSchemas,