@noego/testing 0.1.0

package/dist/index.js

@@ -0,0 +1,676 @@
+// src/time/manual_clock.ts
+import { Clock, Instant } from "@noego/runtime";
+var ManualClock = class _ManualClock extends Clock {
+  static defaultStart = Instant.ofEpochMilliseconds(Date.UTC(2020, 0, 1));
+  current;
+  constructor(start = _ManualClock.defaultStart) {
+    super();
+    this.current = start;
+  }
+  now() {
+    return this.current;
+  }
+  set(instant) {
+    if (instant.isBefore(this.current)) {
+      throw new RangeError(`ManualClock cannot move backwards: ${this.current.toString()} -> ${instant.toString()}`);
+    }
+    this.current = instant;
+  }
+  advanceBy(duration) {
+    this.current = this.current.plus(duration);
+  }
+};
+
+// src/time/manual_scheduler.ts
+import { Scheduler, brandId } from "@noego/runtime";
+var ManualScheduler = class extends Scheduler {
+  constructor(clock) {
+    super();
+    this.clock = clock;
+  }
+  clock;
+  tasks = [];
+  nextSequence = 0;
+  nextId = 0;
+  schedule(input) {
+    const id = brandId(`task-${++this.nextId}`, "ScheduledTask");
+    const internal = {
+      id,
+      label: input.label,
+      deadline: this.clock.now().plus(input.delay),
+      sequence: this.nextSequence++,
+      task: input.task,
+      cancelled: false
+    };
+    this.tasks.push(internal);
+    return {
+      id,
+      cancel: () => {
+        internal.cancelled = true;
+      }
+    };
+  }
+  pending() {
+    return this.live().sort(compareTasks).map(({ id, label, deadline }) => ({ id, label, deadline }));
+  }
+  /** Advance the clock, running every task due inside the window in order. */
+  async advanceBy(duration) {
+    const target = this.clock.now().plus(duration);
+    for (; ; ) {
+      const next = this.nextDue(target);
+      if (next === null) break;
+      if (next.deadline.isAfter(this.clock.now())) {
+        this.clock.set(next.deadline);
+      }
+      await this.execute(next);
+    }
+    if (target.isAfter(this.clock.now())) {
+      this.clock.set(target);
+    }
+  }
+  /** Advance to the earliest pending deadline and run exactly that task. */
+  async runNext() {
+    const next = this.live().sort(compareTasks)[0];
+    if (next === void 0) {
+      throw new Error("ManualScheduler.runNext: no pending tasks");
+    }
+    if (next.deadline.isAfter(this.clock.now())) {
+      this.clock.set(next.deadline);
+    }
+    await this.execute(next);
+  }
+  /** Run tasks (advancing time as needed) until none remain. */
+  async runUntilIdle(options) {
+    const maxTasks = options?.maxTasks ?? 1e4;
+    let executed = 0;
+    while (this.live().length > 0) {
+      if (executed >= maxTasks) {
+        const labels = this.pending().slice(0, 5).map((t) => t.label).join(", ");
+        throw new Error(
+          `ManualScheduler.runUntilIdle: still not idle after ${maxTasks} tasks \u2014 probable infinite reschedule loop (next: ${labels})`
+        );
+      }
+      await this.runNext();
+      executed += 1;
+    }
+  }
+  /** Teardown assertion: fails when pending tasks remain, unless allowed. */
+  assertNoPendingTasks(options) {
+    if (options?.allow === true) return;
+    const remaining = this.pending();
+    if (remaining.length > 0) {
+      const labels = remaining.map((t) => `${t.label} @ ${t.deadline.toString()}`).join("; ");
+      throw new Error(`ManualScheduler: ${remaining.length} pending task(s) at teardown: ${labels}`);
+    }
+  }
+  live() {
+    return this.tasks.filter((t) => !t.cancelled);
+  }
+  nextDue(target) {
+    const candidates = this.live().filter((t) => !t.deadline.isAfter(target)).sort(compareTasks);
+    return candidates[0] ?? null;
+  }
+  async execute(task) {
+    this.remove(task);
+    await task.task();
+  }
+  remove(task) {
+    const index = this.tasks.indexOf(task);
+    this.tasks.splice(index, 1);
+  }
+};
+function compareTasks(a, b) {
+  const byDeadline = a.deadline.compareTo(b.deadline);
+  return byDeadline !== 0 ? byDeadline : a.sequence - b.sequence;
+}
+
+// src/identity/sequence_id_generator.ts
+import { IdGenerator, brandId as brandId2 } from "@noego/runtime";
+var SequenceIdGenerator = class extends IdGenerator {
+  counters = /* @__PURE__ */ new Map();
+  next(brand) {
+    const current = (this.counters.get(brand) ?? 0) + 1;
+    this.counters.set(brand, current);
+    return brandId2(`${brand.toLowerCase()}-${current}`, brand);
+  }
+};
+
+// src/identity/seeded_random_source.ts
+import { RandomSource } from "@noego/runtime";
+var SeededRandomSource = class extends RandomSource {
+  state;
+  constructor(seed = 1) {
+    super();
+    if (!Number.isInteger(seed)) {
+      throw new RangeError(`SeededRandomSource seed must be an integer, got ${seed}`);
+    }
+    this.state = seed >>> 0;
+  }
+  nextUint32() {
+    this.state = this.state + 1831565813 >>> 0;
+    let t = this.state;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return (t ^ t >>> 14) >>> 0;
+  }
+  bytes(length) {
+    if (!Number.isInteger(length) || length < 0) {
+      throw new RangeError(`bytes length must be a non-negative integer, got ${length}`);
+    }
+    const out = new Uint8Array(length);
+    for (let i = 0; i < length; i += 1) {
+      out[i] = this.nextUint32() & 255;
+    }
+    return out;
+  }
+  integer(minInclusive, maxExclusive) {
+    if (maxExclusive <= minInclusive) {
+      throw new RangeError(`integer range is empty: [${minInclusive}, ${maxExclusive})`);
+    }
+    const span = maxExclusive - minInclusive;
+    return minInclusive + this.nextUint32() % span;
+  }
+};
+
+// src/network/scripted_fetch_client.ts
+import { FetchClient, FetchError } from "@noego/runtime";
+var ScriptedFetchClient = class extends FetchClient {
+  script;
+  cursor = 0;
+  executed = [];
+  constructor(script) {
+    super();
+    this.script = [...script];
+  }
+  execute(request) {
+    const entry = this.script[this.cursor];
+    if (entry === void 0) {
+      return Promise.reject(
+        new Error(`ScriptedFetchClient: unexpected call #${this.cursor + 1} (${request.method} ${request.url}); script is exhausted`)
+      );
+    }
+    if (!entry.matches(request)) {
+      return Promise.reject(
+        new Error(`ScriptedFetchClient: call #${this.cursor + 1} (${request.method} ${request.url}) does not match script entry "${entry.describe}"`)
+      );
+    }
+    this.cursor += 1;
+    this.executed.push(request);
+    const outcome = entry.respond(request);
+    return outcome instanceof FetchError ? Promise.reject(outcome) : Promise.resolve(outcome);
+  }
+  /** Teardown assertion: every scripted call must have been consumed. */
+  assertScriptConsumed() {
+    if (this.cursor < this.script.length) {
+      const remaining = this.script.slice(this.cursor).map((e) => e.describe).join(", ");
+      throw new Error(`ScriptedFetchClient: ${this.script.length - this.cursor} unconsumed script entr(ies): ${remaining}`);
+    }
+  }
+};
+
+// src/process/scripted_process_runner.ts
+import { ProcessRunner } from "@noego/runtime";
+var ScriptedProcessRunner = class extends ProcessRunner {
+  script;
+  cursor = 0;
+  openHandles = /* @__PURE__ */ new Set();
+  constructor(script) {
+    super();
+    this.script = [...script];
+  }
+  consume(command, kind) {
+    const entry = this.script[this.cursor];
+    if (entry === void 0) {
+      throw new Error(`ScriptedProcessRunner: unexpected ${kind} of "${command.executable}"; script is exhausted`);
+    }
+    if (!entry.matches(command)) {
+      throw new Error(`ScriptedProcessRunner: ${kind} of "${command.executable}" does not match script entry "${entry.describe}"`);
+    }
+    this.cursor += 1;
+    return entry;
+  }
+  run(command) {
+    try {
+      const entry = this.consume(command, "run");
+      return Promise.resolve(foldEvents(entry.events));
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  }
+  spawn(command) {
+    const entry = this.consume(command, "spawn");
+    const handle = new ScriptedProcessHandle(command.label, entry.events, () => {
+      this.openHandles.delete(handle);
+    });
+    this.openHandles.add(handle);
+    return handle;
+  }
+  /** Teardown assertion: no spawned process may remain open. */
+  assertNoOpenHandles() {
+    if (this.openHandles.size > 0) {
+      const labels = [...this.openHandles].map((h) => h.label).join(", ");
+      throw new Error(`ScriptedProcessRunner: ${this.openHandles.size} open process handle(s) at teardown: ${labels}`);
+    }
+  }
+};
+var ScriptedProcessHandle = class {
+  constructor(label, events, onClosed) {
+    this.label = label;
+    this.events = events;
+    this.onClosed = onClosed;
+    this.resultPromise = new Promise((resolve) => {
+      this.resolveResult = resolve;
+    });
+  }
+  label;
+  events;
+  onClosed;
+  listeners = [];
+  resultPromise;
+  resolveResult;
+  flushed = false;
+  killed = false;
+  onEvent(listener) {
+    this.listeners.push(listener);
+  }
+  /** Deliver all scripted events now (deterministic, test-controlled). */
+  flush() {
+    if (this.flushed || this.killed) return;
+    this.flushed = true;
+    for (const event of this.events) {
+      for (const listener of this.listeners) listener(event);
+      if (event.kind === "exit") {
+        this.resolveResult(foldEvents(this.events));
+        this.onClosed();
+      }
+    }
+  }
+  kill(signal = "SIGTERM") {
+    if (this.flushed || this.killed) return;
+    this.killed = true;
+    const exit = { kind: "exit", exitCode: null, signal };
+    for (const listener of this.listeners) listener(exit);
+    this.resolveResult({ exitCode: null, signal, stdout: "", stderr: "" });
+    this.onClosed();
+  }
+  wait() {
+    return this.resultPromise;
+  }
+};
+function foldEvents(events) {
+  let stdout = "";
+  let stderr = "";
+  let exitCode = null;
+  let signal = null;
+  for (const event of events) {
+    if (event.kind === "stdout") stdout += event.chunk;
+    else if (event.kind === "stderr") stderr += event.chunk;
+    else {
+      exitCode = event.exitCode;
+      signal = event.signal;
+    }
+  }
+  return { exitCode, signal, stdout, stderr };
+}
+
+// src/storage/memory_key_value_store.ts
+import { KeyValueStore } from "@noego/runtime";
+var MemoryKeyValueStore = class extends KeyValueStore {
+  constructor(clock) {
+    super();
+    this.clock = clock;
+  }
+  clock;
+  entries = /* @__PURE__ */ new Map();
+  get(key, codec) {
+    const entry = this.entries.get(key);
+    if (entry === void 0) return Promise.resolve(null);
+    if (entry.expiresAt !== null && !this.clock.now().isBefore(entry.expiresAt)) {
+      this.entries.delete(key);
+      return Promise.resolve(null);
+    }
+    return Promise.resolve(codec.decode(entry.encoded));
+  }
+  put(key, value, codec, options) {
+    const expiresAt = options?.timeToLive !== void 0 ? this.clock.now().plus(options.timeToLive) : null;
+    this.entries.set(key, { encoded: codec.encode(value), expiresAt });
+    return Promise.resolve();
+  }
+  delete(key) {
+    this.entries.delete(key);
+    return Promise.resolve();
+  }
+};
+
+// src/storage/memory_object_store.ts
+import { ObjectStore, brandId as brandId3 } from "@noego/runtime";
+var MemoryObjectStore = class extends ObjectStore {
+  objects = /* @__PURE__ */ new Map();
+  nextVersion = 0;
+  read(key) {
+    return Promise.resolve(this.objects.get(key) ?? null);
+  }
+  write(key, object) {
+    const version = brandId3(`v${++this.nextVersion}`, "ObjectVersion");
+    this.objects.set(key, {
+      bytes: object.bytes.slice(),
+      contentType: object.contentType,
+      metadata: object.metadata !== void 0 ? new Map(object.metadata) : void 0,
+      version
+    });
+    return Promise.resolve(version);
+  }
+  delete(key) {
+    this.objects.delete(key);
+    return Promise.resolve();
+  }
+};
+
+// src/events/recording_event_bus.ts
+import { EventBus } from "@noego/runtime";
+var RecordingEventBus = class extends EventBus {
+  constructor(mode = "immediate") {
+    super();
+    this.mode = mode;
+  }
+  mode;
+  published = [];
+  handlers = /* @__PURE__ */ new Set();
+  queue = [];
+  async publish(event) {
+    this.published.push(event);
+    if (this.mode === "queued") {
+      this.queue.push(event);
+      return;
+    }
+    await this.deliver(event);
+  }
+  subscribe(handler) {
+    this.handlers.add(handler);
+    const bus = this;
+    const subscription = {
+      active: true,
+      unsubscribe() {
+        if (!subscription.active) return;
+        subscription.active = false;
+        bus.handlers.delete(handler);
+      }
+    };
+    return subscription;
+  }
+  /** Deliver buffered events (queued mode) in publication order. */
+  async deliverQueued() {
+    while (this.queue.length > 0) {
+      const event = this.queue.shift();
+      await this.deliver(event);
+    }
+  }
+  get activeSubscriptionCount() {
+    return this.handlers.size;
+  }
+  assertNoActiveSubscriptions() {
+    if (this.handlers.size > 0) {
+      throw new Error(`RecordingEventBus: ${this.handlers.size} active subscription(s) at teardown`);
+    }
+  }
+  async deliver(event) {
+    for (const handler of [...this.handlers]) {
+      await handler(event);
+    }
+  }
+};
+
+// src/observability/recording_sinks.ts
+import { LogSink, TelemetrySink, TraceSink } from "@noego/runtime";
+var RecordingLogSink = class extends LogSink {
+  envelopes = [];
+  emit(envelope) {
+    this.envelopes.push(envelope);
+  }
+};
+var RecordingTraceSink = class extends TraceSink {
+  envelopes = [];
+  emit(envelope) {
+    this.envelopes.push(envelope);
+  }
+};
+var RecordingTelemetrySink = class extends TelemetrySink {
+  envelopes = [];
+  emit(envelope) {
+    this.envelopes.push(envelope);
+  }
+};
+var NoopLogSink = class extends LogSink {
+  emit(_envelope) {
+  }
+};
+
+// src/contracts/clock.contract.ts
+function runClockContract(name, setup) {
+  describe(`Clock contract: ${name}`, () => {
+    it("returns a monotonically non-decreasing instant across consecutive reads", () => {
+      const { clock } = setup();
+      const first = clock.now();
+      const second = clock.now();
+      expect(second.isBefore(first)).toBe(false);
+    });
+    it("nowMs agrees with now()", () => {
+      const { clock } = setup();
+      const instant = clock.now();
+      const ms = clock.nowMs();
+      expect(ms).toBeGreaterThanOrEqual(instant.epochMilliseconds);
+    });
+  });
+}
+
+// src/contracts/key_value_store.contract.ts
+import { Duration as Duration3, jsonCodec, storageKey } from "@noego/runtime";
+function runKeyValueStoreContract(name, setup) {
+  const codec = jsonCodec();
+  describe(`KeyValueStore contract: ${name}`, () => {
+    it("returns null for a missing key", async () => {
+      const { store } = setup();
+      await expect(store.get(storageKey("missing"), codec)).resolves.toBeNull();
+    });
+    it("round-trips a stored value", async () => {
+      const { store } = setup();
+      const key = storageKey("k1");
+      await store.put(key, { n: 42 }, codec);
+      await expect(store.get(key, codec)).resolves.toEqual({ n: 42 });
+    });
+    it("overwrites an existing value", async () => {
+      const { store } = setup();
+      const key = storageKey("k1");
+      await store.put(key, { n: 1 }, codec);
+      await store.put(key, { n: 2 }, codec);
+      await expect(store.get(key, codec)).resolves.toEqual({ n: 2 });
+    });
+    it("deletes a value and tolerates deleting a missing key", async () => {
+      const { store } = setup();
+      const key = storageKey("k1");
+      await store.put(key, { n: 1 }, codec);
+      await store.delete(key);
+      await expect(store.get(key, codec)).resolves.toBeNull();
+      await expect(store.delete(storageKey("missing"))).resolves.toBeUndefined();
+    });
+    it("expires values after their TTL when TTL is supported", async () => {
+      const context = setup();
+      if (!context.supportsTtl) return;
+      const key = storageKey("expiring");
+      await context.store.put(key, { n: 7 }, codec, { timeToLive: Duration3.ofSeconds(30) });
+      await expect(context.store.get(key, codec)).resolves.toEqual({ n: 7 });
+      await context.advanceBy(Duration3.ofSeconds(31));
+      await expect(context.store.get(key, codec)).resolves.toBeNull();
+    });
+    it("keeps values without a TTL alive as time passes", async () => {
+      const context = setup();
+      const key = storageKey("durable");
+      await context.store.put(key, { n: 9 }, codec);
+      await context.advanceBy(Duration3.ofMinutes(60));
+      await expect(context.store.get(key, codec)).resolves.toEqual({ n: 9 });
+    });
+  });
+}
+
+// src/contracts/object_store.contract.ts
+import { objectKey } from "@noego/runtime";
+function runObjectStoreContract(name, setup) {
+  const bytes = (...values) => new Uint8Array(values);
+  describe(`ObjectStore contract: ${name}`, () => {
+    it("returns null for a missing object", async () => {
+      const { store } = setup();
+      await expect(store.read(objectKey("missing"))).resolves.toBeNull();
+    });
+    it("round-trips bytes, content type, and metadata", async () => {
+      const { store } = setup();
+      const key = objectKey("docs/a.bin");
+      await store.write(key, {
+        bytes: bytes(1, 2, 3),
+        contentType: "application/octet-stream",
+        metadata: /* @__PURE__ */ new Map([["owner", "alice"]])
+      });
+      const stored = await store.read(key);
+      expect(stored).not.toBeNull();
+      expect([...stored.bytes]).toEqual([1, 2, 3]);
+      expect(stored.contentType).toBe("application/octet-stream");
+      expect(stored.metadata?.get("owner")).toBe("alice");
+    });
+    it("issues a new version on every write", async () => {
+      const { store } = setup();
+      const key = objectKey("docs/a.bin");
+      const v1 = await store.write(key, { bytes: bytes(1), contentType: "text/plain" });
+      const v2 = await store.write(key, { bytes: bytes(2), contentType: "text/plain" });
+      expect(v1).not.toBe(v2);
+      const stored = await store.read(key);
+      expect(stored.version).toBe(v2);
+      expect([...stored.bytes]).toEqual([2]);
+    });
+    it("deletes an object and tolerates deleting a missing key", async () => {
+      const { store } = setup();
+      const key = objectKey("docs/a.bin");
+      await store.write(key, { bytes: bytes(1), contentType: "text/plain" });
+      await store.delete(key);
+      await expect(store.read(key)).resolves.toBeNull();
+      await expect(store.delete(objectKey("missing"))).resolves.toBeUndefined();
+    });
+    it("does not expose caller mutations of written bytes", async () => {
+      const { store } = setup();
+      const key = objectKey("docs/mutable.bin");
+      const input = bytes(9);
+      await store.write(key, { bytes: input, contentType: "text/plain" });
+      input[0] = 0;
+      const stored = await store.read(key);
+      expect([...stored.bytes]).toEqual([9]);
+    });
+  });
+}
+
+// src/contracts/event_bus.contract.ts
+var testEvent = (value) => ({ type: "test-event", value });
+function runEventBusContract(name, setup) {
+  describe(`EventBus contract: ${name}`, () => {
+    it("delivers published events to subscribers in order", async () => {
+      const { bus, deliver } = setup();
+      const seen = [];
+      const subscription = bus.subscribe((event) => {
+        seen.push(event.value);
+      });
+      await bus.publish(testEvent(1));
+      await bus.publish(testEvent(2));
+      await deliver();
+      expect(seen).toEqual([1, 2]);
+      subscription.unsubscribe();
+    });
+    it("stops delivering after unsubscribe", async () => {
+      const { bus, deliver } = setup();
+      const seen = [];
+      const subscription = bus.subscribe((event) => {
+        seen.push(event.value);
+      });
+      await bus.publish(testEvent(1));
+      await deliver();
+      subscription.unsubscribe();
+      await bus.publish(testEvent(2));
+      await deliver();
+      expect(seen).toEqual([1]);
+    });
+    it("supports multiple subscribers", async () => {
+      const { bus, deliver } = setup();
+      const a = [];
+      const b = [];
+      const sa = bus.subscribe((event) => {
+        a.push(event.value);
+      });
+      const sb = bus.subscribe((event) => {
+        b.push(event.value);
+      });
+      await bus.publish(testEvent(5));
+      await deliver();
+      expect(a).toEqual([5]);
+      expect(b).toEqual([5]);
+      sa.unsubscribe();
+      sb.unsubscribe();
+    });
+    it("marks subscriptions inactive after unsubscribe and tolerates double unsubscribe", async () => {
+      const { bus, deliver } = setup();
+      const seen = [];
+      const subscription = bus.subscribe((event) => {
+        seen.push(event.value);
+      });
+      await bus.publish(testEvent(1));
+      await deliver();
+      expect(seen).toEqual([1]);
+      expect(subscription.active).toBe(true);
+      subscription.unsubscribe();
+      expect(subscription.active).toBe(false);
+      subscription.unsubscribe();
+      expect(subscription.active).toBe(false);
+    });
+  });
+}
+
+// src/leak/leak_detector.ts
+var LeakDetector = class {
+  checks = [];
+  register(check) {
+    this.checks.push(check);
+  }
+  findLeaks() {
+    const leaks = [];
+    for (const { name, check } of this.checks) {
+      for (const description of check()) {
+        leaks.push(`[${name}] ${description}`);
+      }
+    }
+    return leaks;
+  }
+  assertNoLeaks() {
+    const leaks = this.findLeaks();
+    if (leaks.length > 0) {
+      throw new Error(`LeakDetector: ${leaks.length} leaked resource(s):
+${leaks.join("\n")}`);
+    }
+  }
+};
+export {
+  LeakDetector,
+  ManualClock,
+  ManualScheduler,
+  MemoryKeyValueStore,
+  MemoryObjectStore,
+  NoopLogSink,
+  RecordingEventBus,
+  RecordingLogSink,
+  RecordingTelemetrySink,
+  RecordingTraceSink,
+  ScriptedFetchClient,
+  ScriptedProcessRunner,
+  SeededRandomSource,
+  SequenceIdGenerator,
+  runClockContract,
+  runEventBusContract,
+  runKeyValueStoreContract,
+  runObjectStoreContract,
+  testEvent
+};
+//# sourceMappingURL=index.js.map