stitchkit 0.93.0 → 0.94.1

package/dist/index-ensd0r74.js

@@ -0,0 +1,595 @@
+import {
+  ApplicationIdSchema
+} from "./index-3gye9wzb.js";
+import {
+  assertDrainBound,
+  withinBound
+} from "./index-h6eeys1v.js";
+import {
+  createBoundedChannel
+} from "./index-d9pk3td4.js";
+
+// src/application/latest-sink.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(),
+  delivered: z.number().int().nonnegative(),
+  coalesced: z.number().int().nonnegative(),
+  failed: z.number().int().nonnegative(),
+  inFlight: z.boolean(),
+  pending: z.boolean(),
+  lastAcceptedRevision: SnapshotRevisionSchema.optional(),
+  lastDeliveredRevision: SnapshotRevisionSchema.optional()
+}).strict().readonly();
+function createApplicationSnapshotSink(config) {
+  let accepting = true;
+  let received = 0;
+  let accepted = 0;
+  let rejected = 0;
+  let delivered = 0;
+  let coalesced = 0;
+  let failed = 0;
+  let lastAcceptedRevision;
+  let lastDeliveredRevision;
+  let inFlight;
+  let closePromise;
+  let resolveClose;
+  const pending = createBoundedChannel({
+    policy: "latest",
+    maxItems: 1,
+    maxBytes: 1,
+    sizeOf: () => 1
+  });
+  const getStatus = () => ApplicationSnapshotSinkStatusSchema.parse({
+    accepting,
+    received,
+    accepted,
+    rejected,
+    delivered,
+    coalesced,
+    failed,
+    inFlight: inFlight !== undefined,
+    pending: pending.getSnapshot().queuedItems > 0,
+    ...lastAcceptedRevision !== undefined && { lastAcceptedRevision },
+    ...lastDeliveredRevision !== undefined && { lastDeliveredRevision }
+  });
+  const reportFailure = (error, snapshot) => {
+    if (!config.onSinkError)
+      return;
+    Promise.resolve().then(() => config.onSinkError?.({ error, snapshot })).catch(() => {
+      return;
+    });
+  };
+  const settleCloseIfIdle = () => {
+    if (accepting || inFlight || pending.getSnapshot().queuedItems > 0 || !resolveClose)
+      return;
+    const resolve = resolveClose;
+    resolveClose = undefined;
+    resolve(getStatus());
+  };
+  const startWrite = (snapshot) => {
+    const write = Promise.resolve().then(() => config.write(snapshot)).then(() => {
+      delivered += 1;
+      lastDeliveredRevision = snapshot.revision;
+    }).catch((error) => {
+      failed += 1;
+      reportFailure(error, snapshot);
+    }).finally(() => {
+      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;
+  };
+  return {
+    publish(snapshot) {
+      received += 1;
+      const revision = SnapshotRevisionSchema.parse(snapshot.revision);
+      if (!accepting || lastAcceptedRevision !== undefined && revision <= lastAcceptedRevision) {
+        rejected += 1;
+        return false;
+      }
+      accepted += 1;
+      lastAcceptedRevision = revision;
+      if (!inFlight) {
+        startWrite(snapshot);
+      } else {
+        const offered = pending.offer(snapshot);
+        if (offered.outcome === "coalesced")
+          coalesced += offered.replaced;
+      }
+      return true;
+    },
+    getStatus,
+    close(bound) {
+      assertDrainBound(bound);
+      if (!closePromise) {
+        accepting = false;
+        pending.close({ mode: "drain" });
+        closePromise = new Promise((resolve) => {
+          resolveClose = resolve;
+          settleCloseIfIdle();
+        });
+      }
+      return withinBound(closePromise, bound).then(() => getStatus());
+    }
+  };
+}
+
+// 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();
+var ActivityIdSchema = BoundedOperationalIdSchema;
+var ActivityStageIdSchema = BoundedOperationalIdSchema;
+var ActivityStageSnapshotSchema = z2.object({
+  id: ActivityStageIdSchema,
+  active: NonNegativeIntegerSchema,
+  queued: NonNegativeIntegerSchema,
+  completed: NonNegativeIntegerSchema,
+  failed: NonNegativeIntegerSchema
+}).strict().readonly();
+var ActivityTotalsSchema = z2.object({
+  active: NonNegativeIntegerSchema,
+  queued: NonNegativeIntegerSchema,
+  completed: NonNegativeIntegerSchema,
+  failed: NonNegativeIntegerSchema
+}).strict().readonly();
+var ActivitySnapshotSchema = z2.object({
+  id: ActivityIdSchema,
+  epoch: z2.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(),
+  totals: ActivityTotalsSchema
+}).strict().readonly();
+var ActivityLiveStateSchema = z2.enum(["active", "queued"]);
+var ActivityTokenBrand = Symbol("stitchkit.application.activity");
+function emptyCounters() {
+  return { active: 0, queued: 0, completed: 0, failed: 0 };
+}
+function totalsOf(stages) {
+  return stages.reduce((totals, stage) => ({
+    active: totals.active + stage.active,
+    queued: totals.queued + stage.queued,
+    completed: totals.completed + stage.completed,
+    failed: totals.failed + stage.failed
+  }), emptyCounters());
+}
+function createActivityProjection(config) {
+  const id = ActivityIdSchema.parse(config.id);
+  const declaredStages = z2.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 now = config.now ?? (() => new Date);
+  const counters = new Map(declaredStages.map((stage) => [stage, emptyCounters()]));
+  const activities = new WeakMap;
+  const subscribers = new Set;
+  let revision = 0;
+  let changedAt = now().toISOString();
+  const countersFor = (stage) => {
+    const value = counters.get(stage);
+    if (!value) {
+      throw new Error(`[stitchkit] createActivityProjection: undeclared stage "${stage}"`);
+    }
+    return value;
+  };
+  const getSnapshot = () => {
+    const stages = declaredStages.map((stage) => ({ id: stage, ...countersFor(stage) }));
+    return ActivitySnapshotSchema.parse({
+      id,
+      epoch,
+      revision,
+      capturedAt: now().toISOString(),
+      changedAt,
+      stages,
+      totals: totalsOf(stages)
+    });
+  };
+  const publishChange = () => {
+    revision += 1;
+    changedAt = now().toISOString();
+    const snapshot = getSnapshot();
+    for (const subscriber of subscribers)
+      subscriber.publish(snapshot);
+  };
+  const requireActivity = (token) => {
+    const activity = activities.get(token);
+    if (!activity) {
+      throw new Error("[stitchkit] activity token belongs to another projection");
+    }
+    return activity;
+  };
+  const leaveLiveState = (activity) => {
+    if (activity.state === "active" || activity.state === "queued") {
+      countersFor(activity.stage)[activity.state] -= 1;
+    }
+  };
+  const settle = (token, terminal) => {
+    const activity = requireActivity(token);
+    if (activity.state === "completed" || activity.state === "failed")
+      return false;
+    leaveLiveState(activity);
+    countersFor(activity.stage)[terminal] += 1;
+    activity.state = terminal;
+    publishChange();
+    return true;
+  };
+  return {
+    open(stage, rawState = "active") {
+      const parsedStage = ActivityStageIdSchema.parse(stage);
+      const state = ActivityLiveStateSchema.parse(rawState);
+      countersFor(parsedStage)[state] += 1;
+      const token = Object.freeze({
+        get [ActivityTokenBrand]() {
+          return true;
+        }
+      });
+      activities.set(token, { stage: parsedStage, state });
+      publishChange();
+      return token;
+    },
+    transition(token, input) {
+      const activity = requireActivity(token);
+      if (activity.state === "completed" || activity.state === "failed") {
+        throw new Error("[stitchkit] cannot transition a terminal activity");
+      }
+      const stage = ActivityStageIdSchema.parse(input.stage);
+      const state = ActivityLiveStateSchema.parse(input.state);
+      countersFor(stage);
+      if (activity.stage === stage && activity.state === state)
+        return false;
+      leaveLiveState(activity);
+      countersFor(stage)[state] += 1;
+      activity.stage = stage;
+      activity.state = state;
+      publishChange();
+      return true;
+    },
+    complete: (token) => settle(token, "completed"),
+    fail: (token) => settle(token, "failed"),
+    getSnapshot,
+    subscribe(listener) {
+      const sink = createApplicationSnapshotSink({
+        write: listener,
+        ...config.onSubscriberError && { onSinkError: config.onSubscriberError }
+      });
+      subscribers.add(sink);
+      sink.publish(getSnapshot());
+      return () => {
+        subscribers.delete(sink);
+        sink.close();
+      };
+    }
+  };
+}
+
+// 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
+  }).readonly()
+]);
+var ManagedScheduleErrorPolicySchema = z3.enum(["continue", "stop-schedule"]);
+var ManagedScheduleDescriptorSchema = z3.object({
+  id: ApplicationIdSchema,
+  everyMs: PositiveSafeIntegerSchema,
+  startAfterMs: NonNegativeSafeIntegerSchema,
+  overlap: ManagedScheduleOverlapSchema,
+  errorPolicy: ManagedScheduleErrorPolicySchema
+}).readonly();
+var ManagedScheduleStatusSchema = z3.object({
+  descriptor: ManagedScheduleDescriptorSchema,
+  state: z3.enum(["inactive", "scheduled", "running", "draining", "stopped"]),
+  revision: NonNegativeSafeIntegerSchema,
+  capturedAt: z3.string().datetime({ offset: true }),
+  changedAt: z3.string().datetime({ offset: true }),
+  accepting: z3.boolean(),
+  active: NonNegativeSafeIntegerSchema,
+  queued: z3.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()
+}).readonly();
+var systemClock = {
+  now: () => performance.now(),
+  wallNow: () => new Date,
+  schedule(callback, delayMs) {
+    const timer = setTimeout(callback, delayMs);
+    return { cancel: () => clearTimeout(timer) };
+  }
+};
+var DEFAULT_OVERLAP = { mode: "skip" };
+function scheduleState(activated, stopped, accepting, active) {
+  if (!activated)
+    return stopped ? "stopped" : "inactive";
+  if (!accepting)
+    return active > 0 ? "draining" : "stopped";
+  return active > 0 ? "running" : "scheduled";
+}
+function wallAt(monotonicAt, anchor) {
+  if (monotonicAt === null)
+    return null;
+  return new Date(anchor.wallNow + monotonicAt - anchor.monotonicNow).toISOString();
+}
+function overlapDecision(overlap, active) {
+  if (overlap.mode === "skip")
+    return active > 0 ? "skip" : "start";
+  if (overlap.mode === "queue-one")
+    return active > 0 ? "queue" : "start";
+  return active >= overlap.maxConcurrent ? "skip" : "start";
+}
+function reportScheduleError(config, error, context) {
+  if (!config.onError)
+    return;
+  Promise.resolve().then(() => config.onError?.(error, context)).catch(() => {});
+}
+async function waitForSettled(active, clock, context, deadlineAt) {
+  if (active.size === 0 || context.signal.aborted)
+    return;
+  await new Promise((resolve) => {
+    let settled = false;
+    let deadlineTimer = null;
+    const finish = () => {
+      if (settled)
+        return;
+      settled = true;
+      deadlineTimer?.cancel();
+      context.signal.removeEventListener("abort", finish);
+      resolve();
+    };
+    context.signal.addEventListener("abort", finish, { once: true });
+    if (deadlineAt !== undefined) {
+      deadlineTimer = clock.schedule(finish, Math.max(0, deadlineAt - context.now()));
+    }
+    Promise.allSettled([...active]).then(finish);
+  });
+}
+async function executeRun(deps, scheduledAt) {
+  const { config, descriptor, clock, counts, resourceContext } = deps;
+  const startedAt = clock.now();
+  const wallStartedAt = clock.wallNow().getTime();
+  const runContext = {
+    applicationId: resourceContext.applicationId,
+    signal: resourceContext.signal,
+    scheduledAt,
+    startedAt,
+    now: () => clock.now()
+  };
+  counts.runsStarted += 1;
+  counts.lastScheduledAt = new Date(wallStartedAt + scheduledAt - startedAt).toISOString();
+  counts.lastStartedAt = new Date(wallStartedAt).toISOString();
+  deps.changed();
+  try {
+    await Promise.resolve();
+    await config.run(runContext);
+  } catch (error) {
+    counts.runsFailed += 1;
+    counts.lastFinishedAt = clock.wallNow().toISOString();
+    reportScheduleError(config, error, runContext);
+    if (descriptor.errorPolicy === "stop-schedule") {
+      resourceContext.reportHealth("unhealthy");
+      deps.stopAdmission();
+    } else {
+      resourceContext.reportHealth("degraded");
+    }
+    return;
+  }
+  counts.runsCompleted += 1;
+  counts.lastFinishedAt = clock.wallNow().toISOString();
+  if (descriptor.errorPolicy === "continue" && deps.isAccepting()) {
+    resourceContext.reportHealth("healthy");
+  }
+}
+function elapsedIntervals(scheduledAt, observedAt, everyMs) {
+  return Math.max(1, Math.floor((observedAt - scheduledAt) / everyMs) + 1);
+}
+function createManagedSchedule(config) {
+  const descriptor = ManagedScheduleDescriptorSchema.parse({
+    id: config.id,
+    everyMs: config.everyMs,
+    startAfterMs: config.startAfterMs ?? config.everyMs,
+    overlap: config.overlap ?? DEFAULT_OVERLAP,
+    errorPolicy: config.errorPolicy ?? "continue"
+  });
+  const dependsOn = config.dependsOn?.map((id) => ApplicationIdSchema.parse(id));
+  const clock = config.clock ?? systemClock;
+  let revision = 0;
+  let accepting = false;
+  let activated = false;
+  let stopped = false;
+  let timer = null;
+  let activationContext = null;
+  let nextRunAt = null;
+  let queuedAt = null;
+  const counts = {
+    runsStarted: 0,
+    runsCompleted: 0,
+    runsFailed: 0,
+    ticksSkipped: 0,
+    lastScheduledAt: null,
+    lastStartedAt: null,
+    lastFinishedAt: null
+  };
+  let changedAt = clock.wallNow().toISOString();
+  const active = new Set;
+  const changed = () => {
+    revision += 1;
+    changedAt = clock.wallNow().toISOString();
+  };
+  const cancelFuture = () => {
+    timer?.cancel();
+    timer = null;
+    nextRunAt = null;
+    queuedAt = null;
+  };
+  const stopAdmission = () => {
+    if (!accepting && stopped)
+      return;
+    accepting = false;
+    stopped = true;
+    cancelFuture();
+    changed();
+  };
+  const status = () => {
+    const captured = clock.wallNow();
+    const anchor = { monotonicNow: clock.now(), wallNow: captured.getTime() };
+    return ManagedScheduleStatusSchema.parse({
+      descriptor,
+      state: scheduleState(activated, stopped, accepting, active.size),
+      revision,
+      capturedAt: captured.toISOString(),
+      changedAt,
+      accepting,
+      active: active.size,
+      queued: queuedAt !== null,
+      ...counts,
+      nextRunAt: wallAt(nextRunAt, anchor)
+    });
+  };
+  let startExecution = () => {
+    return;
+  };
+  const settleExecution = () => {
+    if (!accepting || queuedAt === null || active.size !== 0)
+      return;
+    const successorAt = queuedAt;
+    queuedAt = null;
+    changed();
+    startExecution(successorAt);
+  };
+  startExecution = (scheduledAt) => {
+    const resourceContext = activationContext;
+    if (!accepting || !resourceContext)
+      return;
+    const tracked = executeRun({
+      config,
+      descriptor,
+      clock,
+      counts,
+      resourceContext,
+      changed,
+      stopAdmission,
+      isAccepting: () => accepting
+    }, scheduledAt).finally(() => {
+      active.delete(tracked);
+      changed();
+      settleExecution();
+    });
+    active.add(tracked);
+  };
+  const dispatchTick = (scheduledAt) => {
+    if (!accepting)
+      return;
+    const decision = overlapDecision(descriptor.overlap, active.size);
+    if (decision === "start") {
+      startExecution(scheduledAt);
+      return;
+    }
+    if (decision === "queue")
+      queuedAt = scheduledAt;
+    else
+      counts.ticksSkipped += 1;
+    changed();
+  };
+  const arm = () => {
+    if (!accepting || nextRunAt === null)
+      return;
+    const delayMs = Math.max(0, nextRunAt - clock.now());
+    timer = clock.schedule(() => {
+      timer = null;
+      if (!accepting || nextRunAt === null)
+        return;
+      const scheduledAt = nextRunAt;
+      const elapsed = elapsedIntervals(scheduledAt, clock.now(), descriptor.everyMs);
+      if (elapsed > 1) {
+        counts.ticksSkipped += elapsed - 1;
+        changed();
+      }
+      nextRunAt = scheduledAt + elapsed * descriptor.everyMs;
+      arm();
+      dispatchTick(scheduledAt);
+    }, delayMs);
+  };
+  const waitForActive = (context, deadlineAt) => waitForSettled(active, clock, context, deadlineAt);
+  const drain = async (context) => {
+    stopAdmission();
+    await waitForActive(context, context.deadlineAt);
+  };
+  return {
+    id: descriptor.id,
+    ...dependsOn && { dependsOn },
+    ...config.required !== undefined && { required: config.required },
+    get status() {
+      return status();
+    },
+    start() {
+      if (active.size > 0) {
+        throw new Error(`[stitchkit] schedule "${descriptor.id}" still has executions from its previous generation`);
+      }
+      cancelFuture();
+      stopped = false;
+      accepting = false;
+      activated = false;
+      activationContext = null;
+      queuedAt = null;
+      changed();
+    },
+    activate(context) {
+      if (activated || stopped)
+        return;
+      activated = true;
+      accepting = true;
+      activationContext = context;
+      nextRunAt = clock.now() + descriptor.startAfterMs;
+      context.reportHealth("healthy");
+      changed();
+      arm();
+    },
+    stopAdmission() {
+      stopAdmission();
+    },
+    drain,
+    close() {
+      stopAdmission();
+    },
+    async force(context) {
+      stopAdmission();
+      await waitForActive(context, context.forceDeadlineAt);
+      if (active.size > 0) {
+        throw new Error(`[stitchkit] schedule "${descriptor.id}" still has active executions`);
+      }
+    }
+  };
+}
+
+export { ApplicationSnapshotSinkStatusSchema, createApplicationSnapshotSink, ActivityIdSchema, ActivityStageIdSchema, ActivityStageSnapshotSchema, ActivitySnapshotSchema, ActivityLiveStateSchema, ActivityTokenBrand, createActivityProjection, ManagedScheduleOverlapSchema, ManagedScheduleErrorPolicySchema, ManagedScheduleDescriptorSchema, ManagedScheduleStatusSchema, createManagedSchedule };

package/dist/index-eqqvgdb3.js

@@ -0,0 +1,46 @@
+// src/json-schema/json-schema.ts
+import { z } from "zod";
+function toJsonSchema(schema, io, unrepresentable = "throw", target = "draft-2020-12") {
+  return z.toJSONSchema(schema, {
+    io,
+    target,
+    unrepresentable,
+    cycles: "ref"
+  });
+}
+function isObjectNode(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function jsonSchemaFields(jsonSchema) {
+  const properties = jsonSchema.properties;
+  if (!isObjectNode(properties)) {
+    const conjunctive = Array.isArray(jsonSchema.allOf);
+    const members = conjunctive ? jsonSchema.allOf : Array.isArray(jsonSchema.oneOf) ? jsonSchema.oneOf : Array.isArray(jsonSchema.anyOf) ? jsonSchema.anyOf : [];
+    const byName = new Map;
+    for (const member of Array.isArray(members) ? members : []) {
+      if (!isObjectNode(member))
+        continue;
+      for (const field of jsonSchemaFields(member)) {
+        const existing = byName.get(field.name);
+        const required2 = existing ? conjunctive ? existing.required || field.required : existing.required && field.required : field.required;
+        byName.set(field.name, existing ? { ...field, required: required2 } : field);
+      }
+    }
+    return [...byName.values()];
+  }
+  const required = new Set(Array.isArray(jsonSchema.required) ? jsonSchema.required.filter((k) => typeof k === "string") : []);
+  const fields = [];
+  for (const [name, raw] of Object.entries(properties)) {
+    const schema = isObjectNode(raw) ? raw : {};
+    const description = typeof schema.description === "string" ? schema.description : undefined;
+    fields.push({
+      name,
+      schema,
+      required: required.has(name),
+      ...description && { description }
+    });
+  }
+  return fields;
+}
+
+export { toJsonSchema, jsonSchemaFields };