@syndroo/sdk 0.4.0-rc.1 → 0.7.0

package/dist/wait.js

@@ -0,0 +1,192 @@
+/**
+ * Status-only polling for `@syndroo/sdk`.
+ *
+ * `wait` never publishes, never confirms and never resumes a credential step.
+ * It polls exactly one query shape, `status({ type: "operation" })`, until the
+ * current execution round is complete, and returns that round. A prepared
+ * operation is not an execution round, so it yields a static
+ * `CONFIRMATION_REQUIRED` / `CONFIRMATION_EXPIRED` error instead.
+ *
+ * Round completion is decided from delivery results, not from the aggregate
+ * `status` string. An aggregate `unknown` is required to survive alongside
+ * deliveries that are still unresolved (spec 6.4), so stopping on
+ * `status === "unknown"` would return a round that is still sending to other
+ * targets. The round is complete when every delivery has a resolved outcome.
+ *
+ * Timeout and cancellation end the local wait only. They never cancel server
+ * work and never start a new publish.
+ */
+import { SyndrooError } from "./errors.js";
+/** Documented wait bounds. Changing one is an API decision. */
+export const WAIT_LIMITS = Object.freeze({
+    /** Poll interval when the caller does not choose one. */
+    defaultIntervalMs: 2000,
+    minIntervalMs: 250,
+    maxIntervalMs: 30000,
+    /** Total wait when the caller does not choose one. */
+    defaultTimeoutMs: 120000,
+    minTimeoutMs: 1,
+    maxTimeoutMs: 3600000,
+});
+function assertIntegerInRange(value, min, max) {
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new SyndrooError("INVALID_ARGUMENT");
+    }
+    return value;
+}
+function resolveWaitOptions(options) {
+    const intervalMs = options.intervalMs === undefined
+        ? WAIT_LIMITS.defaultIntervalMs
+        : assertIntegerInRange(options.intervalMs, WAIT_LIMITS.minIntervalMs, WAIT_LIMITS.maxIntervalMs);
+    const timeoutMs = options.timeoutMs === undefined
+        ? WAIT_LIMITS.defaultTimeoutMs
+        : assertIntegerInRange(options.timeoutMs, WAIT_LIMITS.minTimeoutMs, WAIT_LIMITS.maxTimeoutMs);
+    return { intervalMs, timeoutMs, signal: options.signal };
+}
+/**
+ * A round is complete when every delivery has resolved.
+ *
+ * `outcome: null` means "this target is not resolved yet", which is exactly the
+ * case an aggregate `unknown` can hide. A round with no deliveries at all has
+ * nothing to resolve, so only an aggregate terminal status can end it.
+ */
+export function isExecutionRoundComplete(round) {
+    if (round.deliveries.length === 0) {
+        return round.status !== "pending" && round.status !== "running";
+    }
+    return round.deliveries.every((delivery) => delivery.outcome !== null);
+}
+/**
+ * The default injected sleep: timer-backed and cancellation-aware.
+ *
+ * The timer stays referenced. Between two polls this timer is often the only
+ * thing keeping the Node event loop alive, so unreferencing it would let a real
+ * process exit (13) before the wait completed or timed out.
+ */
+export function defaultSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted === true) {
+            reject(new SyndrooError("ABORTED"));
+            return;
+        }
+        if (!Number.isFinite(ms) || ms < 0) {
+            reject(new SyndrooError("INVALID_ARGUMENT"));
+            return;
+        }
+        let timer;
+        const onAbort = () => {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            reject(new SyndrooError("ABORTED"));
+        };
+        timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** Merge cancellation signals into one, so a single value guards the whole wait. */
+function combineSignals(signals) {
+    const present = signals.filter((signal) => signal !== undefined);
+    if (present.length === 0) {
+        return undefined;
+    }
+    if (present.length === 1) {
+        return present[0];
+    }
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    for (const signal of present) {
+        if (signal.aborted) {
+            controller.abort();
+            break;
+        }
+        signal.addEventListener("abort", abort, { once: true });
+    }
+    return controller.signal;
+}
+/**
+ * Poll until the current execution round completes, then return it.
+ *
+ * Throws `CONFIRMATION_REQUIRED` / `CONFIRMATION_EXPIRED` for a prepared
+ * operation, `WAIT_TIMEOUT` when the deadline elapses, and `ABORTED` when the
+ * caller cancels. Nothing here sends content.
+ */
+export async function waitForExecutionRound(deps, operationId, options = {}) {
+    if (typeof operationId !== "string" || operationId.length === 0) {
+        throw new SyndrooError("INVALID_ARGUMENT");
+    }
+    const { intervalMs, timeoutMs, signal } = resolveWaitOptions(options);
+    const injectedNow = deps.now;
+    const now = injectedNow ?? (() => Date.now());
+    const deadline = now() + timeoutMs;
+    /*
+     * One deadline, two effects: it is checked before every poll and before any
+     * result is returned, and it also aborts whatever is in flight - the status
+     * request or the sleep - so a slow poll cannot push the wait past its budget.
+     *
+     * A real clock gets a real abort timer. An injected clock is driven by the
+     * test through `now()`, so no wall-clock timer is left dangling behind it.
+     */
+    const deadlineController = new AbortController();
+    let deadlineElapsed = false;
+    const timer = injectedNow === undefined
+        ? setTimeout(() => {
+            deadlineElapsed = true;
+            deadlineController.abort();
+        }, timeoutMs)
+        : undefined;
+    const pollSignal = combineSignals([signal, deadlineController.signal]);
+    const deadlineReached = () => deadlineElapsed || now() >= deadline;
+    const timeoutError = () => new SyndrooError("WAIT_TIMEOUT");
+    try {
+        for (;;) {
+            if (signal?.aborted === true) {
+                throw new SyndrooError("ABORTED");
+            }
+            if (deadlineReached()) {
+                throw timeoutError();
+            }
+            let view;
+            try {
+                view = await deps.readOperation(operationId, pollSignal);
+            }
+            catch (error) {
+                if (deadlineElapsed) {
+                    throw timeoutError();
+                }
+                throw error;
+            }
+            if (deadlineReached()) {
+                throw timeoutError();
+            }
+            if (view.phase === "prepared") {
+                throw new SyndrooError(view.confirmation === "expired" ? "CONFIRMATION_EXPIRED" : "CONFIRMATION_REQUIRED");
+            }
+            if (isExecutionRoundComplete(view)) {
+                return view;
+            }
+            const remaining = deadline - now();
+            if (remaining <= 0) {
+                throw timeoutError();
+            }
+            try {
+                await deps.sleep(Math.min(intervalMs, remaining), pollSignal);
+            }
+            catch (error) {
+                if (deadlineElapsed) {
+                    throw timeoutError();
+                }
+                throw error;
+            }
+        }
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=wait.js.map

package/dist/wait.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.js","sourceRoot":"","sources":["../src/wait.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@syndroo/sdk",
-  "version": "0.4.0-rc.1",
+  "version": "0.7.0",
   "type": "module",
-  "description": "Lightweight TypeScript HTTP client for the Syndroo publishing API.",
+  "description": "Standalone TypeScript HTTP client for a Syndroo server. No Core or Provider imports.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -29,11 +29,14 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=24.19.0"
   },
   "publishConfig": {
     "access": "public"
   },
+  "devDependencies": {
+    "esbuild": "0.28.1"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "check": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",