@planet-matrix/mobius-model 0.5.0 → 0.9.0

package/tests/unit/orchestration/coordination/semaphore.spec.ts

@@ -0,0 +1,135 @@
+import { afterEach, expect, test, vi } from "vitest"
+
+import { CoordinationAbortError, CoordinationTimeoutError, Semaphore } from "#Source/orchestration/index.ts"
+
+afterEach(() => {
+  vi.clearAllTimers()
+  vi.useRealTimers()
+  vi.restoreAllMocks()
+})
+
+test("Semaphore tracks capacity and grants permits in FIFO order", async () => {
+  const semaphore = new Semaphore(2)
+
+  expect(semaphore.getMaxConcurrency()).toBe(2)
+  expect(semaphore.getActiveCount()).toBe(0)
+  expect(semaphore.getAvailableCount()).toBe(2)
+  expect(semaphore.isSaturated()).toBe(false)
+
+  const firstPermit = semaphore.tryAcquire()
+  const secondPermit = semaphore.tryAcquire()
+
+  expect(firstPermit).toBeDefined()
+  expect(secondPermit).toBeDefined()
+  expect(semaphore.isSaturated()).toBe(true)
+  expect(semaphore.getActiveCount()).toBe(2)
+  expect(semaphore.getAvailableCount()).toBe(0)
+
+  const thirdPermitPromise = semaphore.acquire()
+  const fourthPermitPromise = semaphore.acquire()
+
+  expect(semaphore.getPendingCount()).toBe(2)
+  expect(semaphore.tryAcquire()).toBeUndefined()
+
+  firstPermit?.release()
+
+  const thirdPermit = await thirdPermitPromise
+  let fourthResolved = false
+  void fourthPermitPromise.then(() => {
+    fourthResolved = true
+  })
+
+  await Promise.resolve()
+
+  expect(semaphore.getPendingCount()).toBe(1)
+  expect(fourthResolved).toBe(false)
+
+  secondPermit?.release()
+  const fourthPermit = await fourthPermitPromise
+
+  expect(semaphore.getPendingCount()).toBe(0)
+
+  thirdPermit.release()
+  fourthPermit.release()
+
+  expect(semaphore.getActiveCount()).toBe(0)
+  expect(semaphore.getAvailableCount()).toBe(2)
+  expect(semaphore.isSaturated()).toBe(false)
+})
+
+test("Semaphore acquire rejects on timeout and abort without leaking queue entries", async () => {
+  vi.useFakeTimers()
+
+  const semaphore = new Semaphore(1)
+  const blockingPermit = semaphore.tryAcquire()
+
+  expect(blockingPermit).toBeDefined()
+
+  const timeoutPromise = semaphore.acquire({ timeout: 15 })
+
+  expect(semaphore.getPendingCount()).toBe(1)
+
+  await vi.advanceTimersByTimeAsync(15)
+
+  await expect(timeoutPromise).rejects.toBeInstanceOf(CoordinationTimeoutError)
+  expect(semaphore.getPendingCount()).toBe(0)
+
+  const abortController = new AbortController()
+  const abortPromise = semaphore.acquire({ abortSignal: abortController.signal })
+
+  expect(semaphore.getPendingCount()).toBe(1)
+
+  abortController.abort("stopped")
+
+  await expect(abortPromise).rejects.toBeInstanceOf(CoordinationAbortError)
+  expect(semaphore.getPendingCount()).toBe(0)
+
+  blockingPermit?.release()
+})
+
+test("Semaphore runExclusive releases capacity after callback failure", async () => {
+  const semaphore = new Semaphore(1)
+  const error = new Error("boom")
+
+  await expect(semaphore.runExclusive(() => 1)).resolves.toBe(1)
+  expect(semaphore.getActiveCount()).toBe(0)
+
+  await expect(semaphore.runExclusive(() => {
+    throw error
+  })).rejects.toThrow(error)
+
+  expect(semaphore.getActiveCount()).toBe(0)
+  expect(semaphore.isSaturated()).toBe(false)
+})
+
+test("Semaphore duplicate release stays silent by default and uses custom handler when provided", () => {
+  const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {
+    // no-op to silence warnings during test
+  })
+  const silentSemaphore = new Semaphore(1)
+  const silentPermit = silentSemaphore.tryAcquire()
+
+  expect(silentPermit).toBeDefined()
+
+  silentPermit?.release()
+  silentPermit?.release()
+  silentPermit?.release()
+
+  expect(silentSemaphore.getActiveCount()).toBe(0)
+  expect(warnSpy).not.toHaveBeenCalled()
+
+  const onDuplicateRelease = vi.fn()
+  const customSemaphore = new Semaphore(1, { onDuplicateRelease })
+  const customPermit = customSemaphore.tryAcquire()
+
+  expect(customPermit).toBeDefined()
+
+  customPermit?.release()
+  customPermit?.release()
+  customPermit?.release()
+
+  expect(customSemaphore.getActiveCount()).toBe(0)
+  expect(onDuplicateRelease).toHaveBeenCalledTimes(2)
+  expect(onDuplicateRelease).toHaveBeenCalledWith("Semaphore permit release was called more than once.")
+  expect(warnSpy).not.toHaveBeenCalled()
+})

package/tests/unit/orchestration/dispatching/dispatcher.spec.ts

@@ -0,0 +1,41 @@
+import { expect, test } from "vitest"
+
+import { Dispatcher, DownCountSelector } from "#Source/orchestration/index.ts"
+
+test("Dispatcher getSelector reuses selectors by id and applies filter on first creation", async () => {
+  const dispatcher = new Dispatcher({
+    itemList: ["alpha", "beta", "gamma"],
+  })
+
+  const firstResult = dispatcher.getSelector({
+    id: "shared",
+    filter: (item) => item !== "alpha",
+  })
+  const secondResult = dispatcher.getSelector({
+    id: "shared",
+    filter: () => true,
+  })
+
+  expect(firstResult.selector).toBeInstanceOf(DownCountSelector)
+  expect(secondResult.selector).toBe(firstResult.selector)
+
+  const firstItem = await firstResult.selector.getItem()
+
+  expect(firstItem.isRight()).toBe(true)
+  expect(firstItem.assertRight().getRight().item).toBe("beta")
+})
+
+test("Dispatcher destroySelector discards an existing selector and allows recreation", () => {
+  const dispatcher = new Dispatcher({
+    itemList: ["alpha", "beta"],
+  })
+
+  const firstSelector = dispatcher.getSelector({ id: "shared" }).selector
+
+  dispatcher.destroySelector("missing")
+  dispatcher.destroySelector("shared")
+
+  const recreatedSelector = dispatcher.getSelector({ id: "shared" }).selector
+
+  expect(recreatedSelector).not.toBe(firstSelector)
+})

package/tests/unit/orchestration/dispatching/selector/down-count-selector.spec.ts

@@ -0,0 +1,81 @@
+import { expect, test } from "vitest"
+
+import { DownCountSelector } from "#Source/orchestration/index.ts"
+
+test("DownCountSelector getId returns the configured selector id", () => {
+  const selector = new DownCountSelector({
+    id: "selector-1",
+    itemList: ["alpha"],
+  })
+
+  expect(selector.getId()).toBe("selector-1")
+})
+
+test("DownCountSelector getItem distinguishes no choice, no available, and reset-driven reuse", async () => {
+  const emptySelector = new DownCountSelector<string>({
+    id: "empty",
+    itemList: [],
+  })
+
+  const emptyResult = await emptySelector.getItem()
+
+  expect(emptyResult.isLeft()).toBe(true)
+  expect(emptyResult.assertLeft().getLeft()).toEqual({
+    code: "NO_CHOICE",
+  })
+
+  const noAvailableSelector = new DownCountSelector({
+    id: "no-available",
+    itemList: ["alpha", "beta"],
+    resetAllWhenNoAvailable: false,
+  })
+
+  const firstResult = await noAvailableSelector.getItem()
+
+  expect(firstResult.isRight()).toBe(true)
+
+  firstResult.assertRight().getRight().markUnavailable()
+
+  const secondResult = await noAvailableSelector.getItem()
+
+  expect(secondResult.isRight()).toBe(true)
+  expect(secondResult.assertRight().getRight().item).toBe("beta")
+
+  secondResult.assertRight().getRight().markUnavailable()
+
+  const noAvailableResult = await noAvailableSelector.getItem()
+
+  expect(noAvailableResult.isLeft()).toBe(true)
+  expect(noAvailableResult.assertLeft().getLeft()).toEqual({
+    code: "NO_AVAILABLE",
+  })
+
+  const resetSelector = new DownCountSelector({
+    id: "reset",
+    itemList: ["only"],
+  })
+
+  const resetFirstResult = await resetSelector.getItem()
+
+  expect(resetFirstResult.isRight()).toBe(true)
+
+  resetFirstResult.assertRight().getRight().markUnavailable()
+
+  const resetSecondResult = await resetSelector.getItem()
+
+  expect(resetSecondResult.isRight()).toBe(true)
+  expect(resetSecondResult.assertRight().getRight().item).toBe("only")
+
+  resetSecondResult.assertRight().getRight().markUnavailable()
+
+  const recoveredResult = await resetSelector.getItem()
+
+  expect(recoveredResult.isRight()).toBe(true)
+
+  recoveredResult.assertRight().getRight().markAvailable()
+
+  const availableAgainResult = await resetSelector.getItem()
+
+  expect(availableAgainResult.isRight()).toBe(true)
+  expect(availableAgainResult.assertRight().getRight().item).toBe("only")
+})

package/tests/unit/orchestration/scheduling/scheduler.spec.ts

@@ -0,0 +1,103 @@
+import { expect, test, vi } from "vitest"
+
+import { Scheduler, Task } from "#Source/orchestration/index.ts"
+
+test("Scheduler runs one-shot tasks and records run logs", async () => {
+  vi.useFakeTimers()
+  vi.setSystemTime(new Date(2_026, 0, 1, 0, 0, 0, 0))
+
+  try {
+    const run = vi.fn(() => undefined)
+    const runAt = new Date(Date.now() + 1_000)
+    const scheduler = new Scheduler({
+      tasks: [
+        new Task({
+          name: "alpha",
+          cron: runAt,
+          run,
+        }),
+      ],
+    })
+
+    scheduler.run()
+
+    await vi.advanceTimersByTimeAsync(999)
+    expect(run).toHaveBeenCalledTimes(0)
+
+    await vi.advanceTimersByTimeAsync(1)
+
+    expect(run).toHaveBeenCalledTimes(1)
+    expect(scheduler.getErrLog()).toEqual([])
+    expect(scheduler.getRunLog()).toHaveLength(1)
+    expect(scheduler.getRunLog()[0]).toEqual({
+      name: "alpha",
+      time: runAt,
+    })
+  }
+  finally {
+    vi.clearAllTimers()
+    vi.useRealTimers()
+  }
+})
+
+test("Scheduler records both run and error logs when a task fails", async () => {
+  vi.useFakeTimers()
+  vi.setSystemTime(new Date(2_026, 0, 1, 0, 0, 0, 0))
+
+  try {
+    const error = new Error("boom")
+    const run = vi.fn(async () => await Promise.reject(error))
+    const runAt = new Date(Date.now() + 1_000)
+    const scheduler = new Scheduler({
+      tasks: [
+        new Task({
+          name: "beta",
+          cron: runAt,
+          run,
+        }),
+      ],
+    })
+
+    scheduler.run()
+    await vi.advanceTimersByTimeAsync(1_000)
+
+    expect(run).toHaveBeenCalledTimes(1)
+    expect(scheduler.getRunLog()).toHaveLength(1)
+    expect(scheduler.getErrLog()).toEqual([
+      {
+        name: "beta",
+        time: runAt,
+        reason: "Error: boom",
+      },
+    ])
+  }
+  finally {
+    vi.clearAllTimers()
+    vi.useRealTimers()
+  }
+})
+
+test("Scheduler.run rejects duplicate starts", () => {
+  vi.useFakeTimers()
+  vi.setSystemTime(new Date(2_026, 0, 1, 0, 0, 0, 0))
+
+  try {
+    const scheduler = new Scheduler({
+      tasks: [
+        new Task({
+          name: "gamma",
+          cron: new Date(Date.now() + 1_000),
+          run: () => undefined,
+        }),
+      ],
+    })
+
+    scheduler.run()
+
+    expect(() => scheduler.run()).toThrow("Scheduler is already running")
+  }
+  finally {
+    vi.clearAllTimers()
+    vi.useRealTimers()
+  }
+})

package/tests/unit/random/base.spec.ts

@@ -0,0 +1,58 @@
+import { expect, test, vi } from "vitest"
+
+import { getRandomIndex, getRandomUint32, getRandomUnitValue } from "#Source/random/index.ts"
+
+test("getRandomUint32 returns an integer within uint32 range across available random sources", () => {
+  const cryptoBackedValue = getRandomUint32()
+  expect(Number.isInteger(cryptoBackedValue)).toBe(true)
+  expect(cryptoBackedValue).toBeGreaterThanOrEqual(0)
+  expect(cryptoBackedValue).toBeLessThan(0x1_0000_0000)
+
+  vi.stubGlobal("crypto", undefined)
+
+  try {
+    const fallbackValue = getRandomUint32()
+    expect(Number.isInteger(fallbackValue)).toBe(true)
+    expect(fallbackValue).toBeGreaterThanOrEqual(0)
+    expect(fallbackValue).toBeLessThan(0x1_0000_0000)
+  }
+  finally {
+    vi.unstubAllGlobals()
+  }
+})
+
+test("getRandomUnitValue returns a unit-interval float across available random sources", () => {
+  const cryptoBackedValue = getRandomUnitValue()
+  expect(cryptoBackedValue).toBeGreaterThanOrEqual(0)
+  expect(cryptoBackedValue).toBeLessThan(1)
+
+  vi.stubGlobal("crypto", undefined)
+
+  try {
+    const fallbackValue = getRandomUnitValue()
+    expect(fallbackValue).toBeGreaterThanOrEqual(0)
+    expect(fallbackValue).toBeLessThan(1)
+  }
+  finally {
+    vi.unstubAllGlobals()
+  }
+})
+
+test("getRandomIndex returns an integer index within alphabet bounds across available random sources", () => {
+  const cryptoBackedValue = getRandomIndex(3)
+  expect(Number.isInteger(cryptoBackedValue)).toBe(true)
+  expect(cryptoBackedValue).toBeGreaterThanOrEqual(0)
+  expect(cryptoBackedValue).toBeLessThan(3)
+
+  vi.stubGlobal("crypto", undefined)
+
+  try {
+    const fallbackValue = getRandomIndex(3)
+    expect(Number.isInteger(fallbackValue)).toBe(true)
+    expect(fallbackValue).toBeGreaterThanOrEqual(0)
+    expect(fallbackValue).toBeLessThan(3)
+  }
+  finally {
+    vi.unstubAllGlobals()
+  }
+})

package/tests/unit/random/random-boolean.spec.ts

@@ -0,0 +1,25 @@
+import { expect, test, vi } from "vitest"
+
+import { randomBoolean } from "#Source/random/index.ts"
+
+test("randomBoolean returns expected output across probabilities and available random sources", () => {
+  const defaultValue = randomBoolean()
+  expect(typeof defaultValue).toBe("boolean")
+
+  expect(randomBoolean(0)).toBe(false)
+  expect(randomBoolean(1)).toBe(true)
+  expect(() => randomBoolean(Number.NaN)).toThrow(TypeError)
+  expect(() => randomBoolean(Number.POSITIVE_INFINITY)).toThrow(TypeError)
+  expect(() => randomBoolean(-0.1)).toThrow(RangeError)
+  expect(() => randomBoolean(1.1)).toThrow(RangeError)
+
+  vi.stubGlobal("crypto", undefined)
+
+  try {
+    const fallbackValue = randomBoolean(0.5)
+    expect(typeof fallbackValue).toBe("boolean")
+  }
+  finally {
+    vi.unstubAllGlobals()
+  }
+})

package/tests/unit/random/random-integer.spec.ts

@@ -0,0 +1,32 @@
+import { expect, test, vi } from "vitest"
+
+import { randomInteger } from "#Source/random/index.ts"
+
+test("randomInteger returns expected output across ranges and available random sources", () => {
+  const singleBoundValue = randomInteger(5)
+  expect(singleBoundValue).toBeGreaterThanOrEqual(0)
+  expect(singleBoundValue).toBeLessThanOrEqual(5)
+  expect(Number.isInteger(singleBoundValue)).toBe(true)
+
+  const reversedRangeValue = randomInteger(8, 3)
+  expect(reversedRangeValue).toBeGreaterThanOrEqual(3)
+  expect(reversedRangeValue).toBeLessThanOrEqual(8)
+  expect(Number.isInteger(reversedRangeValue)).toBe(true)
+
+  expect(randomInteger(4, 4)).toBe(4)
+  expect(() => randomInteger(1.5)).toThrow(TypeError)
+  expect(() => randomInteger(Number.NaN)).toThrow(TypeError)
+  expect(() => randomInteger(1, Number.POSITIVE_INFINITY)).toThrow(TypeError)
+
+  vi.stubGlobal("crypto", undefined)
+
+  try {
+    const fallbackValue = randomInteger(-2, 2)
+    expect(fallbackValue).toBeGreaterThanOrEqual(-2)
+    expect(fallbackValue).toBeLessThanOrEqual(2)
+    expect(Number.isInteger(fallbackValue)).toBe(true)
+  }
+  finally {
+    vi.unstubAllGlobals()
+  }
+})

package/tests/unit/random/random-number.spec.ts

@@ -0,0 +1,33 @@
+import { expect, test, vi } from "vitest"
+
+import { randomNumber } from "#Source/random/index.ts"
+
+test("randomNumber returns expected output across ranges and available random sources", () => {
+  const defaultValue = randomNumber()
+  expect(defaultValue).toBeGreaterThanOrEqual(0)
+  expect(defaultValue).toBeLessThan(1)
+
+  const singleBoundValue = randomNumber(5)
+  expect(singleBoundValue).toBeGreaterThanOrEqual(0)
+  expect(singleBoundValue).toBeLessThan(5)
+
+  const reversedRangeValue = randomNumber(10, 3)
+  expect(reversedRangeValue).toBeGreaterThanOrEqual(3)
+  expect(reversedRangeValue).toBeLessThan(10)
+
+  expect(randomNumber(4, 4)).toBe(4)
+  expect(() => randomNumber(Number.NaN)).toThrow(TypeError)
+  expect(() => randomNumber(Number.POSITIVE_INFINITY)).toThrow(TypeError)
+  expect(() => randomNumber(1, Number.NEGATIVE_INFINITY)).toThrow(TypeError)
+
+  vi.stubGlobal("crypto", undefined)
+
+  try {
+    const fallbackValue = randomNumber(-2, 2)
+    expect(fallbackValue).toBeGreaterThanOrEqual(-2)
+    expect(fallbackValue).toBeLessThan(2)
+  }
+  finally {
+    vi.unstubAllGlobals()
+  }
+})

package/tests/unit/random/random-string.spec.ts

@@ -0,0 +1,22 @@
+import { expect, test, vi } from "vitest"
+
+import { randomString } from "#Source/random/index.ts"
+
+test("randomString returns expected output across available random sources", () => {
+  const cryptoBackedValue = randomString(12)
+  expect(cryptoBackedValue).toHaveLength(12)
+
+  const constrainedValue = randomString(10, "ab")
+  expect(constrainedValue.split("").every(char => char === "a" || char === "b")).toBe(true)
+
+  vi.stubGlobal("crypto", undefined)
+
+  try {
+    const fallbackValue = randomString(10, "ab")
+    expect(fallbackValue).toHaveLength(10)
+    expect(fallbackValue.split("").every(char => char === "a" || char === "b")).toBe(true)
+  }
+  finally {
+    vi.unstubAllGlobals()
+  }
+})

package/tests/unit/reactor/alien-signals-effect.spec.ts

@@ -49,16 +49,17 @@ test('should not run untracked inner effect', () => {
   let outerEffectTruthyBranchRunTimes = 0;
   const a = signal(() => 3);
   const b = computed(() => a.get() > 0);
-  const _outerEffect = effect(() => {
+  // outer effect
+  effect(() => {
     if (b.get() === true) {
       outerEffectTruthyBranchRunTimes = outerEffectTruthyBranchRunTimes + 1;
-      const _innerEffect = effect(() => {
+      effect(() => {
         if (a.get() === 0) {
           throw new Error("bad");
         }
-      });
+      }, { name: "inner effect" });
     }
-  });
+  }, { name: "outer effect" });
 
   expect(outerEffectTruthyBranchRunTimes).toBe(1);
   a.set(2);
@@ -226,7 +227,7 @@ test('should duplicate subscribers do not affect the notify order', () => {
   const srcB = signal(() => 0, { name: "srcB" });
   const order: string[] = [];
 
-  const _effectA = effect(() => {
+  effect(() => {
     order.push('a');
     reactiveSystem.setNoActiveNodeAsSub();
     const isOne = srcB.get() === 1;
@@ -237,7 +238,7 @@ test('should duplicate subscribers do not affect the notify order', () => {
     srcB.get();
     srcA.get();
   }, { name: "effect-a" });
-  const _effectB = effect(() => {
+  effect(() => {
     order.push('b');
     srcA.get();
   }, { name: "effect-b" });
@@ -357,20 +358,20 @@ test('should not execute skipped effects from previous failed flush when updatin
 
   let effect3Executed = false;
 
-  const _effect1 = effect(() => {
+  effect(() => {
     a.get();
   }, { name: "effect1" });
-  const _effect2 = effect(() => {
+  effect(() => {
     if (a.get() === 2) {
       throw new Error('Error in effect 2');
     }
   }, { name: "effect2" });
-  const _effect3 = effect(() => {
+  effect(() => {
     a.get();
     d.get();
     effect3Executed = true;
   }, { name: "effect3" });
-  const _effect4 = effect(() => {
+  effect(() => {
     b.get();
   }, { name: "effect4" });
 

package/tests/unit/reactor/preact-signal.spec.ts

@@ -1,7 +1,6 @@
 import { describe, it, vi, expect } from "vitest";
 
-import type { Effect } from '#Source/index.ts';
-import { Signal, computed, effect, effectScope, endBatch, reactiveSystem, signal, startBatch } from '#Source/reactor/index.ts';
+import { Signal, effect, signal } from "#Source/reactor/index.ts"
 
 /**
  * 这个测试文件应该与 https://github.com/preactjs/signals/blob/main/packages/core/test/signal.test.tsx 保持同步。