@planet-matrix/mobius-model 0.6.0 → 0.10.1

package/tests/unit/aio/json.spec.ts

@@ -0,0 +1,146 @@
+import { expect, test, vi } from "vitest"
+
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+import { Logger } from "#Source/log/index.ts"
+import {
+  JsonModeResponseParser,
+  extractJsonBlock,
+} from "#Source/aio/index.ts"
+
+interface TestJsonOutput {
+  value: number
+  label?: string | undefined
+}
+
+const createSyncSchema = (
+  options: { validateCount?: { current: number } | undefined } = {}
+): StandardSchemaV1<unknown, TestJsonOutput> => {
+  const validateCount = options.validateCount
+
+  return {
+    "~standard": {
+      version: 1 as const,
+      vendor: "mobius-aio-json-sync-spec",
+      validate: (value: unknown): StandardSchemaV1.Result<TestJsonOutput> => {
+        if (validateCount !== undefined) {
+          validateCount.current = validateCount.current + 1
+        }
+
+        if (typeof value !== "object" || value === null) {
+          return {
+            issues: [{ message: "value must be an object" }],
+          }
+        }
+
+        const record = value as Record<string, unknown>
+        if (typeof record["value"] !== "number") {
+          return {
+            issues: [{ message: "value must be a number" }],
+          }
+        }
+
+        const output: TestJsonOutput = {
+          value: record["value"],
+        }
+
+        if (typeof record["label"] === "string") {
+          output.label = record["label"]
+        }
+
+        return {
+          value: output,
+        }
+      },
+    },
+  }
+}
+
+const createAsyncSchema = (): StandardSchemaV1<unknown, TestJsonOutput> => {
+  return {
+    "~standard": {
+      version: 1 as const,
+      vendor: "mobius-aio-json-async-spec",
+      validate: async (_value: unknown): Promise<StandardSchemaV1.Result<TestJsonOutput>> => {
+        await Promise.resolve()
+
+        return {
+          value: {
+            value: 1,
+          },
+        }
+      },
+    },
+  }
+}
+
+test("extractJsonBlock returns the first fenced json block and throws when none exists", () => {
+  const response = [
+    "before",
+    "```json",
+    "{\"value\":1}",
+    "```",
+    "```json",
+    "{\"value\":2}",
+    "```",
+  ].join("\n")
+
+  expect(extractJsonBlock(response)).toBe(["```json", "{\"value\":1}", "```"].join("\n"))
+  expect(() => extractJsonBlock("plain text only")).toThrow("Failed to extract json block from response")
+})
+
+test("JsonModeResponseParser.extractJsonContent strips fences, repairs json-like content and falls back to raw text", () => {
+  const parser = new JsonModeResponseParser({
+    outputSchema: createSyncSchema(),
+  })
+
+  const repairedFromFence = parser.extractJsonContent(["header", "```json", "{value:1,}", "```"].join("\n"))
+  const repairedFromRawText = parser.extractJsonContent("{label:'mobius',value:2,}")
+
+  expect(repairedFromFence).toBe('\n{"value":1}\n')
+  expect(repairedFromRawText).toBe('{"label":"mobius","value":2}')
+})
+
+test("JsonModeResponseParser.parse validates sync output, caches by source text and throws for invalid or async schemas", () => {
+  const validateCount = { current: 0 }
+  const parser = new JsonModeResponseParser({
+    outputSchema: createSyncSchema({ validateCount }),
+  })
+
+  const first = parser.parse('{"value":1,"label":"ok"}')
+  const second = parser.parse('{"value":1,"label":"ok"}')
+
+  expect(first).toEqual({ value: 1, label: "ok" })
+  expect(second).toBe(first)
+  expect(validateCount.current).toBe(1)
+
+  const invalidParser = new JsonModeResponseParser({
+    outputSchema: createSyncSchema(),
+  })
+  expect(() => invalidParser.parse('{"label":"missing-value"}')).toThrow("Variable validation failed")
+
+  const asyncParser = new JsonModeResponseParser({
+    outputSchema: createAsyncSchema(),
+  })
+  expect(() => asyncParser.parse('{"value":1}')).toThrow("Validation result is a promise")
+})
+
+test("JsonModeResponseParser.check returns false and logs the failure context when parsing fails", () => {
+  const logger = new Logger({
+    name: "AioJsonTest",
+    configs: {
+      enabled: false,
+    },
+  })
+  const logSpy = vi.spyOn(logger, "log")
+  const parser = new JsonModeResponseParser({
+    logger,
+    outputSchema: createSyncSchema(),
+  })
+
+  expect(parser.check('{"value":3}')).toBe(true)
+  expect(parser.check('{"label":"missing-value"}')).toBe(false)
+
+  expect(logSpy).toHaveBeenCalledTimes(2)
+  expect(logSpy.mock.calls[0]?.[0]).toBe("check error:")
+  expect(logSpy.mock.calls[1]).toEqual(["error response:", '{"label":"missing-value"}'])
+})

package/tests/unit/aio/prompt.spec.ts

@@ -0,0 +1,111 @@
+import { expect, test } from "vitest"
+
+import {
+  Prompt,
+  emptyLine,
+  orderedListItem,
+  scopeContent,
+  text,
+  unorderedListItem,
+} from "#Source/aio/index.ts"
+
+test("text creates a plain text prompt block", () => {
+  expect(text("hello")).toEqual({
+    type: "text",
+    content: "hello",
+  })
+})
+
+test("emptyLine creates an empty-line prompt block", () => {
+  expect(emptyLine()).toEqual({
+    type: "empty-line",
+  })
+})
+
+test("scopeContent wraps content with triple-quote boundaries", () => {
+  expect(scopeContent("context")).toEqual({
+    type: "scope-content",
+    content: '"""\ncontext\n"""',
+  })
+})
+
+test("orderedListItem creates an ordered-list prompt block", () => {
+  expect(orderedListItem("first")).toEqual({
+    type: "ordered-list-item",
+    content: "first",
+  })
+})
+
+test("unorderedListItem creates an unordered-list prompt block", () => {
+  expect(unorderedListItem("first")).toEqual({
+    type: "unordered-list-item",
+    content: "first",
+  })
+})
+
+test("Prompt.addBlock appends a block produced by helpers and returns the same instance", async () => {
+  const prompt = new Prompt({})
+
+  expect(prompt.addBlock(helpers => helpers.text("from-helper"))).toBe(prompt)
+  await expect(prompt.getPromptInString()).resolves.toBe("from-helper")
+})
+
+test("Prompt.addText appends a text block", async () => {
+  const prompt = new Prompt({})
+
+  expect(prompt.addText("alpha")).toBe(prompt)
+  await expect(prompt.getPromptInString()).resolves.toBe("alpha")
+})
+
+test("Prompt.addEmptyLine appends an empty line block", async () => {
+  const prompt = new Prompt({})
+
+  expect(prompt.addEmptyLine()).toBe(prompt)
+  await expect(prompt.getPromptInString()).resolves.toBe("\r\n")
+})
+
+test("Prompt.addScopeContent appends a scoped content block", async () => {
+  const prompt = new Prompt({})
+
+  expect(prompt.addScopeContent("body")).toBe(prompt)
+  await expect(prompt.getPromptInString()).resolves.toBe('"""\nbody\n"""')
+})
+
+test("Prompt.addOrderedListItem appends an ordered list block", async () => {
+  const prompt = new Prompt({})
+
+  expect(prompt.addOrderedListItem("step")).toBe(prompt)
+  await expect(prompt.getPromptInString()).resolves.toBe("1. step")
+})
+
+test("Prompt.addUnorderedListItem appends an unordered list block", async () => {
+  const prompt = new Prompt({})
+
+  expect(prompt.addUnorderedListItem("item")).toBe(prompt)
+  await expect(prompt.getPromptInString()).resolves.toBe("- item")
+})
+
+test("Prompt.getPromptInString renders prompt blocks with list numbering and resets between block groups", async () => {
+  const prompt = new Prompt({})
+
+  prompt
+    .addText("Intro")
+    .addOrderedListItem("First")
+    .addOrderedListItem("Second")
+    .addText("Break")
+    .addOrderedListItem("Reset")
+    .addUnorderedListItem("One")
+    .addUnorderedListItem("Two")
+    .addScopeContent("body")
+
+  await expect(prompt.getPromptInString()).resolves.toBe([
+    "Intro",
+    "1. First",
+    "2. Second",
+    "Break",
+    "1. Reset",
+    "- One",
+    "- Two",
+    '"""\nbody\n"""',
+  ].join("\r\n"))
+})

package/tests/unit/basic/error.spec.ts

@@ -2,7 +2,8 @@ import { expect, test } from "vitest"
 
 import {
   errorIsNetworkError,
-  errorStringifyException,
+  errorStringify,
+  toError,
 } from "#Source/basic/index.ts"
 
 test("errorIsNetworkError returns expected values", () => {
@@ -26,7 +27,18 @@ test("errorIsNetworkError returns expected values", () => {
   expect(errorIsNetworkError(safariWithStack)).toBe(false)
 })
 
-test("errorStringifyException returns readable output", () => {
-  expect(errorStringifyException(new Error("boom"))).toBe("Error: boom")
-  expect(errorStringifyException(123)).toBe("123")
+test("errorStringify returns readable output", () => {
+  expect(errorStringify(new Error("boom"))).toBe("Error: boom")
+  expect(errorStringify(123)).toBe("123")
+})
+
+test("toError returns expected values", () => {
+  const error = new Error("boom")
+
+  expect(toError(error)).toBe(error)
+
+  const wrappedError = toError(123)
+
+  expect(wrappedError).toBeInstanceOf(Error)
+  expect(wrappedError.message).toBe("123")
 })

package/tests/unit/basic/promise.spec.ts

@@ -2,9 +2,10 @@
 import { expect, test, vi } from "vitest"
 
 import {
-  isPromiseFailResult,
+  promiseIsFailResult,
   promiseCatch,
-  promiseConstructFailResult,
+  promiseCreateFailResult,
+  promiseDeferred,
   promiseFilterFailResults,
   promiseFilterSuccessResults,
   promiseFinally,
@@ -17,16 +18,16 @@ import {
 } from "#Source/basic/index.ts"
 
 test("promiseThen chains and transforms resolved values", async () => {
-  const example1 = await promiseThen((value: number) => value * 2, Promise.resolve(3))
-  const example2 = await promiseThen((value: string) => `${value}!`, Promise.resolve("ok"))
+  const example1 = await promiseThen(Promise.resolve(3), (value: number) => value * 2)
+  const example2 = await promiseThen(Promise.resolve("ok"), (value: string) => `${value}!`)
 
   expect(example1).toBe(6)
   expect(example2).toBe("ok!")
 })
 
 test("promiseCatch handles rejected and resolved promises", async () => {
-  const example1 = await promiseCatch(() => "fallback", Promise.reject(new Error("x")))
-  const example2 = await promiseCatch(() => 0, Promise.resolve(3))
+  const example1 = await promiseCatch(Promise.reject(new Error("x")), () => "fallback")
+  const example2 = await promiseCatch(Promise.resolve(3), () => 0)
 
   expect(example1).toBe("fallback")
   expect(example2).toBe(3)
@@ -35,32 +36,49 @@ test("promiseCatch handles rejected and resolved promises", async () => {
 test("promiseFinally runs finalizer and preserves resolution", async () => {
   let cleaned = false
 
-  const example1 = await promiseFinally(() => {
+  const example1 = await promiseFinally(Promise.resolve(10), () => {
     cleaned = true
-  }, Promise.resolve(10))
+  })
 
   expect(example1).toBe(10)
   expect(cleaned).toBe(true)
 })
 
-test("promiseConstructFailResult creates standardized failure objects", () => {
+test("promiseDeferred exposes external resolve and reject for the created promise", async () => {
+  const resolvedDeferred = promiseDeferred<number>()
+
+  resolvedDeferred.resolve(42)
+
+  await expect(resolvedDeferred.promise).resolves.toBe(42)
+  expect(typeof resolvedDeferred.resolve).toBe("function")
+  expect(typeof resolvedDeferred.reject).toBe("function")
+
+  const rejectedDeferred = promiseDeferred<number>()
+  const reason = new Error("deferred failure")
+
+  rejectedDeferred.reject(reason)
+
+  await expect(rejectedDeferred.promise).rejects.toBe(reason)
+})
+
+test("promiseCreateFailResult creates standardized failure objects", () => {
   const reason = new Error("x")
-  const failResult = promiseConstructFailResult(reason)
+  const failResult = promiseCreateFailResult(reason)
 
-  expect(isPromiseFailResult(failResult)).toBe(true)
+  expect(promiseIsFailResult(failResult)).toBe(true)
   expect(failResult.reason).toBe(reason)
 })
 
-test("isPromiseFailResult identifies standardized failure objects", () => {
-  const failResult = promiseConstructFailResult(new Error("x"))
+test("promiseIsFailResult identifies standardized failure objects", () => {
+  const failResult = promiseCreateFailResult(new Error("x"))
 
-  expect(isPromiseFailResult(failResult)).toBe(true)
-  expect(isPromiseFailResult({ reason: "x" })).toBe(false)
-  expect(isPromiseFailResult(null)).toBe(false)
+  expect(promiseIsFailResult(failResult)).toBe(true)
+  expect(promiseIsFailResult({ reason: "x" })).toBe(false)
+  expect(promiseIsFailResult(null)).toBe(false)
 })
 
 test("promiseFilterSuccessResults keeps only successful values", () => {
-  const failResult = promiseConstructFailResult(new Error("x"))
+  const failResult = promiseCreateFailResult(new Error("x"))
 
   const filtered = promiseFilterSuccessResults([1, failResult, 2])
 
@@ -83,93 +101,119 @@ test("promiseFilterFailResults keeps failure values with original indices", asyn
   expect(filtered).toHaveLength(2)
   expect(filtered[0]?.index).toBe(1)
   expect(filtered[1]?.index).toBe(2)
-  expect(isPromiseFailResult(filtered[0])).toBe(true)
-  expect(isPromiseFailResult(filtered[1])).toBe(true)
+  expect(promiseIsFailResult(filtered[0])).toBe(true)
+  expect(promiseIsFailResult(filtered[1])).toBe(true)
 })
 
 test("promiseQueue executes makers in sequence and keeps failed results", async () => {
   const results = await promiseQueue<number>([
     async (): Promise<number> => 1,
     async ({ previousResult, index }): Promise<number> => {
-      return isPromiseFailResult(previousResult) ? -1 : previousResult + index + 1
+      return promiseIsFailResult(previousResult) ? -1 : previousResult + index + 1
     },
     async ({ previousResult }): Promise<number> => {
-      if (isPromiseFailResult(previousResult)) {
+      if (promiseIsFailResult(previousResult)) {
         return -1
       }
       throw new Error(String(previousResult))
     },
     async ({ previousResult }): Promise<number> => {
-      return isPromiseFailResult(previousResult) ? -1 : previousResult + 1
+      return promiseIsFailResult(previousResult) ? -1 : previousResult + 1
     },
   ])
 
   expect(results[0]).toBe(1)
   expect(results[1]).toBe(3)
-  expect(isPromiseFailResult(results[2])).toBe(true)
+  expect(promiseIsFailResult(results[2])).toBe(true)
   expect(results[3]).toBe(-1)
 })
 
 test("promiseRetryWhile retries while predicate is true", async () => {
-  let attempts = 0
+  let successAttempts = 0
 
   const success = await promiseRetryWhile(
     (value) => value < 3,
     async () => {
-      attempts = attempts + 1
-      return attempts
+      successAttempts = successAttempts + 1
+      return successAttempts
     },
-    { maxTryTimes: 5 },
+    { maxTryIndex: 5 },
   )
 
-  attempts = 0
+  let failedAttempts = 0
   const failed = await promiseRetryWhile(
     () => true,
     async () => {
-      attempts = attempts + 1
+      failedAttempts = failedAttempts + 1
       throw new Error("x")
     },
-    { maxTryTimes: 2 },
+    { maxTryIndex: 2 },
   )
 
-  await expect(promiseRetryWhile(async () => false, async () => 1, { maxTryTimes: 0 })).rejects.toThrow(
-    "`maxTryTimes` must be greater than 0.",
+  let singleAttemptCount = 0
+  const singleAttempt = await promiseRetryWhile(
+    () => true,
+    async () => {
+      singleAttemptCount = singleAttemptCount + 1
+      return singleAttemptCount
+    },
+    { maxTryIndex: 0 },
+  )
+
+  await expect(promiseRetryWhile(async () => false, async () => 1, { maxTryIndex: -1 })).rejects.toThrow(
+    "`maxTryIndex` must be greater than or equal to 0.",
   )
 
   expect(success).toBe(3)
-  expect(attempts).toBe(2)
-  expect(isPromiseFailResult(failed)).toBe(true)
+  expect(successAttempts).toBe(3)
+  expect(promiseIsFailResult(failed)).toBe(true)
+  expect(failedAttempts).toBe(3)
+  expect(singleAttempt).toBe(1)
+  expect(singleAttemptCount).toBe(1)
 })
 
 test("promiseRetryUntil retries until predicate becomes true", async () => {
-  let attempts = 0
+  let successAttempts = 0
 
   const success = await promiseRetryUntil(
-    (value, time) => value >= 2 && time >= 2,
+    (value, index) => value >= 2 && index >= 1,
     async () => {
-      attempts = attempts + 1
-      return attempts
+      successAttempts = successAttempts + 1
+      return successAttempts
     },
-    { maxTryTimes: 5 },
+    { maxTryIndex: 5 },
   )
 
-  attempts = 0
+  let failedAttempts = 0
   const failed = await promiseRetryUntil(
     () => false,
     async () => {
-      attempts = attempts + 1
+      failedAttempts = failedAttempts + 1
       throw new Error("x")
     },
-    { maxTryTimes: 2 },
+    { maxTryIndex: 2 },
   )
 
-  await expect(promiseRetryUntil(async () => true, async () => 1, { maxTryTimes: 0 })).rejects.toThrow(
-    "`maxTryTimes` must be greater than 0.",
+  let singleAttemptCount = 0
+  const singleAttempt = await promiseRetryUntil(
+    () => false,
+    async () => {
+      singleAttemptCount = singleAttemptCount + 1
+      return singleAttemptCount
+    },
+    { maxTryIndex: 0 },
+  )
+
+  await expect(promiseRetryUntil(async () => true, async () => 1, { maxTryIndex: -1 })).rejects.toThrow(
+    "`maxTryIndex` must be greater than or equal to 0.",
   )
 
   expect(success).toBe(2)
-  expect(attempts).toBe(2)
-  expect(isPromiseFailResult(failed)).toBe(true)
+  expect(successAttempts).toBe(2)
+  expect(promiseIsFailResult(failed)).toBe(true)
+  expect(failedAttempts).toBe(3)
+  expect(singleAttempt).toBe(1)
+  expect(singleAttemptCount).toBe(1)
 })
 
 test("promiseInterval runs by interval and returns a stopper", async () => {
@@ -188,7 +232,7 @@ test("promiseInterval runs by interval and returns a stopper", async () => {
     stop()
     vi.advanceTimersByTime(50)
 
-    expect(calls).toEqual([1, 2, 3])
+    expect(calls).toEqual([0, 1, 2])
     expect(typeof stop).toBe("function")
   }
   finally {
@@ -196,6 +240,31 @@ test("promiseInterval runs by interval and returns a stopper", async () => {
   }
 })
 
+test("promiseInterval logs rejected runs instead of leaving them unhandled", async () => {
+  vi.useFakeTimers()
+
+  const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
+
+  try {
+    promiseInterval(10, async () => {
+      throw new Error("interval failure")
+    })
+
+    vi.advanceTimersByTime(10)
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(errorSpy).toHaveBeenCalledTimes(1)
+    expect(errorSpy.mock.calls[0]?.[0]).toBe("[promiseInterval] unexpected error occurred:")
+    expect(errorSpy.mock.calls[0]?.[1]).toBeInstanceOf(Error)
+  }
+  finally {
+    vi.clearAllTimers()
+    errorSpy.mockRestore()
+    vi.useRealTimers()
+  }
+})
+
 test("promiseForever loops continuously and reports rejections", async () => {
   vi.useFakeTimers()
 
@@ -210,20 +279,59 @@ test("promiseForever loops continuously and reports rejections", async () => {
       return value
     })
 
-    promiseForever(promiseMaker, { breakTime: 5, onRejected })
+    const result = promiseForever(promiseMaker, { breakTime: 5, onRejected })
     await Promise.resolve()
     await Promise.resolve()
 
     expect(promiseMaker).toHaveBeenCalledTimes(1)
     expect(onRejected).toHaveBeenCalledTimes(1)
-    expect(onRejected.mock.calls[0]?.[0]).toBe(1)
-    expect(isPromiseFailResult(onRejected.mock.calls[0]?.[1])).toBe(true)
+    expect(onRejected.mock.calls[0]?.[0]).toBe(0)
+    expect(promiseIsFailResult(onRejected.mock.calls[0]?.[1])).toBe(true)
+    expect(result.index).toBe(0)
+    expect(result.isStopped).toBe(false)
 
     vi.advanceTimersByTime(16)
     await Promise.resolve()
     await Promise.resolve()
 
     expect(promiseMaker.mock.calls.length).toBeGreaterThanOrEqual(2)
+
+    result.stop()
+    expect(result.isStopped).toBe(true)
+  }
+  finally {
+    vi.clearAllTimers()
+    vi.useRealTimers()
+  }
+})
+
+test("promiseForever stop prevents scheduling the next run when current run has not settled", async () => {
+  vi.useFakeTimers()
+
+  try {
+    const resolvers: Array<(value: number) => void> = []
+    const promiseMaker = vi.fn(async () => {
+      return await new Promise<number>((resolve) => {
+        resolvers.push(resolve)
+      })
+    })
+
+    const result = promiseForever(promiseMaker, { breakTime: 5 })
+
+    expect(promiseMaker).toHaveBeenCalledTimes(1)
+
+    result.stop()
+    expect(result.isStopped).toBe(true)
+
+    resolvers[0]?.(1)
+    await Promise.resolve()
+    await Promise.resolve()
+
+    vi.advanceTimersByTime(20)
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(promiseMaker).toHaveBeenCalledTimes(1)
   }
   finally {
     vi.clearAllTimers()