stitchkit 0.67.0 → 0.68.0

package/dist/{index-x8v8b7rc.js → index-zpyj7hsv.js}

@@ -2,19 +2,279 @@ import {
   ApplicationIdSchema
 } from "./index-8eywc9zv.js";
 
-// src/application/latest-sink.ts
+// src/application/channel.ts
 import { z } from "zod";
-var SnapshotRevisionSchema = z.number().int().nonnegative();
-var ApplicationSnapshotSinkStatusSchema = z.object({
-  accepting: z.boolean(),
-  received: z.number().int().nonnegative(),
-  accepted: z.number().int().nonnegative(),
-  rejected: z.number().int().nonnegative(),
+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(),
-  failed: z.number().int().nonnegative(),
-  inFlight: z.boolean(),
-  pending: z.boolean(),
+  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()
+}).strict().readonly();
+function createCreditWindow(config) {
+  const capacityBytes = PositiveSafeIntegerSchema.parse(config.capacityBytes);
+  let availableBytes = capacityBytes;
+  let state = "open";
+  let acquired = 0;
+  let refused = 0;
+  let replenishedBytes = 0;
+  const snapshot = () => CreditWindowSnapshotSchema.parse({
+    state,
+    capacityBytes,
+    availableBytes,
+    leasedBytes: capacityBytes - availableBytes,
+    acquired,
+    refused,
+    replenishedBytes
+  });
+  return {
+    acquire(bytes) {
+      const requested = PositiveSafeIntegerSchema.parse(bytes);
+      if (state === "closed") {
+        refused += 1;
+        return { outcome: "refused", reason: "closed" };
+      }
+      if (requested > capacityBytes) {
+        refused += 1;
+        return { outcome: "refused", reason: "larger-than-window" };
+      }
+      if (requested > availableBytes) {
+        refused += 1;
+        return { outcome: "refused", reason: "insufficient-credit" };
+      }
+      availableBytes -= requested;
+      acquired += 1;
+      let leaseReleased = false;
+      const lease = {
+        bytes: requested,
+        get released() {
+          return leaseReleased;
+        },
+        release() {
+          if (leaseReleased)
+            return;
+          leaseReleased = true;
+          availableBytes += requested;
+          replenishedBytes += requested;
+          if (availableBytes > capacityBytes) {
+            throw new Error("Credit window accounting exceeded its capacity");
+          }
+        }
+      };
+      return { outcome: "leased", lease };
+    },
+    close() {
+      state = "closed";
+      return snapshot();
+    },
+    getSnapshot: snapshot
+  };
+}
+
+// src/application/latest-sink.ts
+import { z as z2 } from "zod";
+var SnapshotRevisionSchema = z2.number().int().nonnegative();
+var ApplicationSnapshotSinkStatusSchema = z2.object({
+  accepting: z2.boolean(),
+  received: z2.number().int().nonnegative(),
+  accepted: z2.number().int().nonnegative(),
+  rejected: z2.number().int().nonnegative(),
+  delivered: z2.number().int().nonnegative(),
+  coalesced: z2.number().int().nonnegative(),
+  failed: z2.number().int().nonnegative(),
+  inFlight: z2.boolean(),
+  pending: z2.boolean(),
   lastAcceptedRevision: SnapshotRevisionSchema.optional(),
   lastDeliveredRevision: SnapshotRevisionSchema.optional()
 }).strict().readonly();
@@ -29,9 +289,14 @@ function createApplicationSnapshotSink(config) {
   let lastAcceptedRevision;
   let lastDeliveredRevision;
   let inFlight;
-  let pending;
   let closePromise;
   let resolveClose;
+  const pending = createBoundedChannel({
+    policy: "latest",
+    maxItems: 1,
+    maxBytes: 1,
+    sizeOf: () => 1
+  });
   const getStatus = () => ApplicationSnapshotSinkStatusSchema.parse({
     accepting,
     received,
@@ -41,7 +306,7 @@ function createApplicationSnapshotSink(config) {
     coalesced,
     failed,
     inFlight: inFlight !== undefined,
-    pending: pending !== undefined,
+    pending: pending.getSnapshot().queuedItems > 0,
     ...lastAcceptedRevision !== undefined && { lastAcceptedRevision },
     ...lastDeliveredRevision !== undefined && { lastDeliveredRevision }
   });
@@ -53,7 +318,7 @@ function createApplicationSnapshotSink(config) {
     });
   };
   const settleCloseIfIdle = () => {
-    if (accepting || inFlight || pending || !resolveClose)
+    if (accepting || inFlight || pending.getSnapshot().queuedItems > 0 || !resolveClose)
       return;
     const resolve = resolveClose;
     resolveClose = undefined;
@@ -67,13 +332,19 @@ function createApplicationSnapshotSink(config) {
       failed += 1;
       reportFailure(error, snapshot);
     }).finally(() => {
-      inFlight = undefined;
-      const next = pending;
-      pending = undefined;
-      if (next)
-        startWrite(next);
-      else
+      if (pending.getSnapshot().queuedItems > 0) {
+        pending.next().then((next) => {
+          if (next.done) {
+            inFlight = undefined;
+            settleCloseIfIdle();
+          } else {
+            startWrite(next.value);
+          }
+        });
+      } else {
+        inFlight = undefined;
         settleCloseIfIdle();
+      }
     });
     inFlight = write;
   };
@@ -90,9 +361,9 @@ function createApplicationSnapshotSink(config) {
       if (!inFlight) {
         startWrite(snapshot);
       } else {
-        if (pending)
-          coalesced += 1;
-        pending = snapshot;
+        const offered = pending.offer(snapshot);
+        if (offered.outcome === "coalesced")
+          coalesced += offered.replaced;
       }
       return true;
     },
@@ -101,6 +372,7 @@ function createApplicationSnapshotSink(config) {
       if (closePromise)
         return closePromise;
       accepting = false;
+      pending.close({ mode: "drain" });
       closePromise = new Promise((resolve) => {
         resolveClose = resolve;
         settleCloseIfIdle();
@@ -111,34 +383,34 @@ function createApplicationSnapshotSink(config) {
 }
 
 // src/application/activity.ts
-import { z as z2 } from "zod";
-var BoundedOperationalIdSchema = z2.string().min(1).max(64).regex(/^[a-zA-Z0-9][a-zA-Z0-9._:-]*$/);
-var NonNegativeIntegerSchema = z2.number().int().nonnegative();
+import { z as z3 } from "zod";
+var BoundedOperationalIdSchema = z3.string().min(1).max(64).regex(/^[a-zA-Z0-9][a-zA-Z0-9._:-]*$/);
+var NonNegativeIntegerSchema = z3.number().int().nonnegative();
 var ActivityIdSchema = BoundedOperationalIdSchema;
 var ActivityStageIdSchema = BoundedOperationalIdSchema;
-var ActivityStageSnapshotSchema = z2.object({
+var ActivityStageSnapshotSchema = z3.object({
   id: ActivityStageIdSchema,
   active: NonNegativeIntegerSchema,
   queued: NonNegativeIntegerSchema,
   completed: NonNegativeIntegerSchema,
   failed: NonNegativeIntegerSchema
 }).strict().readonly();
-var ActivityTotalsSchema = z2.object({
+var ActivityTotalsSchema = z3.object({
   active: NonNegativeIntegerSchema,
   queued: NonNegativeIntegerSchema,
   completed: NonNegativeIntegerSchema,
   failed: NonNegativeIntegerSchema
 }).strict().readonly();
-var ActivitySnapshotSchema = z2.object({
+var ActivitySnapshotSchema = z3.object({
   id: ActivityIdSchema,
-  epoch: z2.string().uuid(),
+  epoch: z3.string().uuid(),
   revision: NonNegativeIntegerSchema,
-  capturedAt: z2.string().datetime({ offset: true }),
-  changedAt: z2.string().datetime({ offset: true }),
-  stages: z2.array(ActivityStageSnapshotSchema).min(1).max(64).readonly(),
+  capturedAt: z3.string().datetime({ offset: true }),
+  changedAt: z3.string().datetime({ offset: true }),
+  stages: z3.array(ActivityStageSnapshotSchema).min(1).max(64).readonly(),
   totals: ActivityTotalsSchema
 }).strict().readonly();
-var ActivityLiveStateSchema = z2.enum(["active", "queued"]);
+var ActivityLiveStateSchema = z3.enum(["active", "queued"]);
 var ActivityTokenBrand = Symbol("stitchkit.application.activity");
 function emptyCounters() {
   return { active: 0, queued: 0, completed: 0, failed: 0 };
@@ -153,12 +425,12 @@ function totalsOf(stages) {
 }
 function createActivityProjection(config) {
   const id = ActivityIdSchema.parse(config.id);
-  const declaredStages = z2.array(ActivityStageIdSchema).min(1).max(64).parse(config.stages);
+  const declaredStages = z3.array(ActivityStageIdSchema).min(1).max(64).parse(config.stages);
   const uniqueStages = new Set(declaredStages);
   if (uniqueStages.size !== declaredStages.length) {
     throw new Error("[stitchkit] createActivityProjection: stage ids must be unique");
   }
-  const epoch = z2.string().uuid().parse(config.epoch ?? crypto.randomUUID());
+  const epoch = z3.string().uuid().parse(config.epoch ?? crypto.randomUUID());
   const now = config.now ?? (() => new Date);
   const counters = new Map(declaredStages.map((stage) => [stage, emptyCounters()]));
   const activities = new WeakMap;
@@ -263,42 +535,42 @@ function createActivityProjection(config) {
 }
 
 // src/application/schedule.ts
-import { z as z3 } from "zod";
-var NonNegativeSafeIntegerSchema = z3.number().int().nonnegative().refine(Number.isSafeInteger, "Expected a safe integer");
-var PositiveSafeIntegerSchema = NonNegativeSafeIntegerSchema.refine((value) => value > 0, "Expected a positive integer");
-var ManagedScheduleOverlapSchema = z3.discriminatedUnion("mode", [
-  z3.object({ mode: z3.literal("skip") }).readonly(),
-  z3.object({ mode: z3.literal("queue-one") }).readonly(),
-  z3.object({
-    mode: z3.literal("parallel"),
-    maxConcurrent: PositiveSafeIntegerSchema
+import { z as z4 } from "zod";
+var NonNegativeSafeIntegerSchema = z4.number().int().nonnegative().refine(Number.isSafeInteger, "Expected a safe integer");
+var PositiveSafeIntegerSchema2 = NonNegativeSafeIntegerSchema.refine((value) => value > 0, "Expected a positive integer");
+var ManagedScheduleOverlapSchema = z4.discriminatedUnion("mode", [
+  z4.object({ mode: z4.literal("skip") }).readonly(),
+  z4.object({ mode: z4.literal("queue-one") }).readonly(),
+  z4.object({
+    mode: z4.literal("parallel"),
+    maxConcurrent: PositiveSafeIntegerSchema2
   }).readonly()
 ]);
-var ManagedScheduleErrorPolicySchema = z3.enum(["continue", "stop-schedule"]);
-var ManagedScheduleDescriptorSchema = z3.object({
+var ManagedScheduleErrorPolicySchema = z4.enum(["continue", "stop-schedule"]);
+var ManagedScheduleDescriptorSchema = z4.object({
   id: ApplicationIdSchema,
-  everyMs: PositiveSafeIntegerSchema,
+  everyMs: PositiveSafeIntegerSchema2,
   startAfterMs: NonNegativeSafeIntegerSchema,
   overlap: ManagedScheduleOverlapSchema,
   errorPolicy: ManagedScheduleErrorPolicySchema
 }).readonly();
-var ManagedScheduleStatusSchema = z3.object({
+var ManagedScheduleStatusSchema = z4.object({
   descriptor: ManagedScheduleDescriptorSchema,
-  state: z3.enum(["inactive", "scheduled", "running", "draining", "stopped"]),
+  state: z4.enum(["inactive", "scheduled", "running", "draining", "stopped"]),
   revision: NonNegativeSafeIntegerSchema,
-  capturedAt: z3.string().datetime({ offset: true }),
-  changedAt: z3.string().datetime({ offset: true }),
-  accepting: z3.boolean(),
+  capturedAt: z4.string().datetime({ offset: true }),
+  changedAt: z4.string().datetime({ offset: true }),
+  accepting: z4.boolean(),
   active: NonNegativeSafeIntegerSchema,
-  queued: z3.boolean(),
+  queued: z4.boolean(),
   runsStarted: NonNegativeSafeIntegerSchema,
   runsCompleted: NonNegativeSafeIntegerSchema,
   runsFailed: NonNegativeSafeIntegerSchema,
   ticksSkipped: NonNegativeSafeIntegerSchema,
-  nextRunAt: z3.string().datetime({ offset: true }).nullable(),
-  lastScheduledAt: z3.string().datetime({ offset: true }).nullable(),
-  lastStartedAt: z3.string().datetime({ offset: true }).nullable(),
-  lastFinishedAt: z3.string().datetime({ offset: true }).nullable()
+  nextRunAt: z4.string().datetime({ offset: true }).nullable(),
+  lastScheduledAt: z4.string().datetime({ offset: true }).nullable(),
+  lastStartedAt: z4.string().datetime({ offset: true }).nullable(),
+  lastFinishedAt: z4.string().datetime({ offset: true }).nullable()
 }).readonly();
 var systemClock = {
   now: () => performance.now(),
@@ -557,4 +829,4 @@ function createManagedSchedule(config) {
   };
 }
 
-export { ApplicationSnapshotSinkStatusSchema, createApplicationSnapshotSink, ActivityIdSchema, ActivityStageIdSchema, ActivityStageSnapshotSchema, ActivitySnapshotSchema, ActivityLiveStateSchema, ActivityTokenBrand, createActivityProjection, ManagedScheduleOverlapSchema, ManagedScheduleErrorPolicySchema, ManagedScheduleDescriptorSchema, ManagedScheduleStatusSchema, createManagedSchedule };
+export { BoundedChannelPolicySchema, BoundedChannelStateSchema, BoundedChannelSnapshotSchema, BoundedChannelReaderError, createBoundedChannel, CreditWindowSnapshotSchema, createCreditWindow, ApplicationSnapshotSinkStatusSchema, createApplicationSnapshotSink, ActivityIdSchema, ActivityStageIdSchema, ActivityStageSnapshotSchema, ActivitySnapshotSchema, ActivityLiveStateSchema, ActivityTokenBrand, createActivityProjection, ManagedScheduleOverlapSchema, ManagedScheduleErrorPolicySchema, ManagedScheduleDescriptorSchema, ManagedScheduleStatusSchema, createManagedSchedule };