@serfab/cadre-core 0.12.0 → 1.0.0

package/src/timed-step.ts

@@ -0,0 +1,28 @@
+import debug from 'debug';
+
+const timing = debug('sereus:cadre:timing');
+
+/**
+ * Await one step of a longer operation between two `sereus:cadre:timing` lines:
+ * `[<scope>:<id>] <step>: start` before it, then `<step>: <n>ms` — or
+ * `<step>: failed after <n>ms` — once it settles. The start line is what matters on a
+ * device: a step that never settles leaves a start with no matching end, so a trace
+ * names the step that hung rather than only the last one that finished.
+ *
+ * The text is built here rather than passed as `%s`/`%d` arguments: `debug`'s browser
+ * build, which React Native bundles, leaves placeholders for the console to fill, and
+ * RN's console prints them unfilled, so a device trace would read `[%s:%s] %s: start`.
+ */
+export async function timedStep<T>(scope: string, id: string, step: string, op: () => Promise<T>): Promise<T> {
+	const label = `[${scope}:${id}] ${step}`;
+	timing(`${label}: start`);
+	const t0 = performance.now();
+	try {
+		const result = await op();
+		timing(`${label}: ${Math.round(performance.now() - t0)}ms`);
+		return result;
+	} catch (error) {
+		timing(`${label}: failed after ${Math.round(performance.now() - t0)}ms`);
+		throw error;
+	}
+}

package/src/timeout-scheduler.ts

@@ -0,0 +1,28 @@
+/**
+ * The timer seam shared by the strand bring-up loops that re-arm themselves one step at a
+ * time — the first-sync write gate's probe loop (`strand-first-sync-gate.ts`) and the
+ * membership reconciler's retry ladder (`strand-membership-reconciler.ts`). `setTimeout`
+ * rather than a repeating interval because the next step is armed only once the previous
+ * one settles, so a slow network read never stacks steps behind it, and because the delay
+ * can differ per step.
+ *
+ * Tests inject a hand-cranked clock; production omits it and gets real timers, `unref`'d so
+ * a loop that is only waiting never holds a Node process open (the call is optional —
+ * browsers and React Native return a plain handle with no `unref`).
+ */
+
+/** Timer seam for a self-rescheduling loop; omit for real (unref'd) timeouts. */
+export interface TimeoutScheduler {
+  setTimeout(fn: () => void, ms: number): unknown;
+  clearTimeout(handle: unknown): void;
+}
+
+/** Real timers, `unref`'d where the runtime supports it. */
+export const defaultTimeoutScheduler: TimeoutScheduler = {
+  setTimeout: (fn, ms) => {
+    const handle = setTimeout(fn, ms);
+    (handle as { unref?: () => void }).unref?.();
+    return handle;
+  },
+  clearTimeout: (handle) => clearTimeout(handle as Parameters<typeof clearTimeout>[0])
+};