@planet-matrix/mobius-model 0.6.0 → 0.9.0

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

@@ -0,0 +1,147 @@
+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" }],
+          }
+        }
+
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+        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/schedule.spec.ts

@@ -0,0 +1,74 @@
+import { expect, test, vi } from "vitest"
+
+import {
+  scheduleMacroTask,
+  scheduleMacroTaskSimple,
+  scheduleMicroTask,
+  scheduleMicroTaskSimple,
+} from "#Source/basic/index.ts"
+
+test("scheduleMicroTaskSimple schedules a task in the microtask queue", async () => {
+  const values: string[] = []
+
+  scheduleMicroTaskSimple(() => {
+    values.push("micro")
+  })
+
+  expect(values).toEqual([])
+
+  await Promise.resolve()
+
+  expect(values).toEqual(["micro"])
+})
+
+test("scheduleMacroTaskSimple schedules a task in the macrotask queue", async () => {
+  vi.useFakeTimers()
+  const values: string[] = []
+
+  scheduleMacroTaskSimple(() => {
+    values.push("macro")
+  })
+
+  expect(values).toEqual([])
+
+  await vi.runAllTimersAsync()
+
+  expect(values).toEqual(["macro"])
+  vi.useRealTimers()
+})
+
+test("scheduleMicroTask schedules async-capable tasks in the microtask queue", async () => {
+  const values: string[] = []
+
+  scheduleMicroTask({
+    task: () => {
+      values.push("micro")
+    },
+  })
+
+  expect(values).toEqual([])
+
+  await Promise.resolve()
+  await Promise.resolve()
+
+  expect(values).toEqual(["micro"])
+})
+
+test("scheduleMacroTask schedules async-capable tasks with timeout", async () => {
+  vi.useFakeTimers()
+  const values: string[] = []
+
+  scheduleMacroTask({
+    timeout: 25,
+    task: () => {
+      values.push("macro")
+    },
+  })
+
+  await vi.advanceTimersByTimeAsync(24)
+  expect(values).toEqual([])
+
+  await vi.advanceTimersByTimeAsync(1)
+  expect(values).toEqual(["macro"])
+  vi.useRealTimers()
+})

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

@@ -1,17 +1,18 @@
 import { expect, test } from "vitest"
 
 import {
-  streamConsumeInAsyncMacroTask,
-  streamConsumeInSyncMacroTask,
-  streamFromArray,
-  streamTransformInAsyncMacroTask,
+  streamConsumeInMacroTask,
+  streamConsumeInMicroTask,
+  streamFromArrayEager,
+  streamFromArrayLazy,
+  streamTransformInMacroTask,
 } from "#Source/basic/index.ts"
 
-test("streamFromArray creates a readable stream from array values", async () => {
+test("streamFromArrayEager creates a readable stream from array values", async () => {
   const source = [1, 2, 3]
   const values: number[] = []
 
-  const stream = streamFromArray(source)
+  const stream = streamFromArrayEager(source)
   for await (const value of stream) {
     values.push(value)
   }
@@ -19,18 +20,38 @@ test("streamFromArray creates a readable stream from array values", async () =>
   expect(values).toEqual(source)
 })
 
-test("streamConsumeInSyncMacroTask consumes stream and handles callback errors", async () => {
+test("streamFromArrayLazy creates a lazily consumed readable stream", async () => {
+  const source = [1, 2, 3]
+  const stream = streamFromArrayLazy(source)
+  const reader = stream.getReader()
+
+  const firstChunk = await reader.read()
+  const secondChunk = await reader.read()
+  const thirdChunk = await reader.read()
+  const doneChunk = await reader.read()
+
+  expect(firstChunk).toEqual({ done: false, value: 1 })
+  expect(secondChunk).toEqual({ done: false, value: 2 })
+  expect(thirdChunk).toEqual({ done: false, value: 3 })
+  expect(doneChunk).toEqual({ done: true, value: undefined })
+})
+
+test("streamConsumeInMicroTask consumes stream and handles callback errors", async () => {
   const consumed: number[] = []
   let doneCalled = false
 
-  await streamConsumeInSyncMacroTask<number>({
-    readableStream: streamFromArray([1, 2, 3]),
-    onValue: (chunk) => {
-      consumed.push(chunk)
-    },
-    onDone: () => {
-      doneCalled = true
-    },
+  await new Promise<void>((resolve, reject) => {
+    streamConsumeInMicroTask<number>({
+      readableStream: streamFromArrayEager([1, 2, 3]),
+      onValue: (chunk) => {
+        consumed.push(chunk)
+      },
+      onDone: () => {
+        doneCalled = true
+        resolve()
+      },
+      onError: reject,
+    })
   })
 
   expect(consumed).toEqual([1, 2, 3])
@@ -38,30 +59,33 @@ test("streamConsumeInSyncMacroTask consumes stream and handles callback errors",
 
   let errorMessage = ""
   let doneCalledInErrorCase = false
-  await streamConsumeInSyncMacroTask<number>({
-    readableStream: streamFromArray([1, 2]),
-    onValue: (chunk) => {
-      if (chunk === 2) {
-        throw new Error("boom")
-      }
-    },
-    onDone: () => {
-      doneCalledInErrorCase = true
-    },
-    onError: (error) => {
-      errorMessage = error.message
-    },
+  await new Promise<void>((resolve) => {
+    streamConsumeInMicroTask<number>({
+      readableStream: streamFromArrayEager([1, 2]),
+      onValue: (chunk) => {
+        if (chunk === 2) {
+          throw new Error("boom")
+        }
+      },
+      onDone: () => {
+        doneCalledInErrorCase = true
+      },
+      onError: (error) => {
+        errorMessage = error.message
+        resolve()
+      },
+    })
   })
 
   expect(errorMessage).toContain("boom")
   expect(doneCalledInErrorCase).toBe(false)
 })
 
-test("streamConsumeInAsyncMacroTask consumes stream and forwards callback failures", async () => {
+test("streamConsumeInMacroTask consumes stream and forwards callback failures", async () => {
   const consumed: number[] = []
   await new Promise<void>((resolve, reject) => {
-    streamConsumeInAsyncMacroTask<number>({
-      readableStream: streamFromArray([1, 2, 3]),
+    streamConsumeInMacroTask<number>({
+      readableStream: streamFromArrayEager([1, 2, 3]),
       onValue: (chunk) => {
         consumed.push(chunk)
       },
@@ -78,8 +102,8 @@ test("streamConsumeInAsyncMacroTask consumes stream and forwards callback failur
 
   let errorMessage = ""
   await new Promise<void>((resolve, reject) => {
-    streamConsumeInAsyncMacroTask<number>({
-      readableStream: streamFromArray([1]),
+    streamConsumeInMacroTask<number>({
+      readableStream: streamFromArrayEager([1]),
       onValue: () => {
         throw new Error("async-boom")
       },
@@ -96,13 +120,13 @@ test("streamConsumeInAsyncMacroTask consumes stream and forwards callback failur
   expect(errorMessage).toContain("async-boom")
 })
 
-test("streamTransformInAsyncMacroTask transforms values and handles invalid inputs/errors", async () => {
+test("streamTransformInMacroTask transforms values and handles invalid inputs/errors", async () => {
   expect(() => {
-    streamTransformInAsyncMacroTask<number, number>({})
+    streamTransformInMacroTask<number, number>({})
   }).toThrow("Either readableStream or reader must be provided")
 
-  const transformed = streamTransformInAsyncMacroTask<number, number>({
-    readableStream: streamFromArray([1, 2, 3]),
+  const transformed = streamTransformInMacroTask<number, number>({
+    readableStream: streamFromArrayEager([1, 2, 3]),
     onChunk: (chunk, controller) => {
       if (chunk.done === true) {
         controller.close()
@@ -117,4 +141,33 @@ test("streamTransformInAsyncMacroTask transforms values and handles invalid inpu
     values.push(value)
   }
   expect(values).toEqual([10, 20, 30])
+
+  const reader = streamFromArrayEager([4]).getReader()
+  const transformedFromReader = streamTransformInMacroTask<number, number>({
+    reader,
+    onChunk: (chunk, controller) => {
+      if (chunk.done === true) {
+        controller.close()
+        return
+      }
+      controller.enqueue(chunk.value + 1)
+    },
+  })
+
+  expect(await Array.fromAsync(transformedFromReader)).toEqual([5])
+
+  let refinedError: Error | undefined
+  const errored = streamTransformInMacroTask<number, number>({
+    readableStream: streamFromArrayEager([1]),
+    onChunk: () => {
+      throw new Error("transform-boom")
+    },
+    onError: (error) => {
+      refinedError = new Error(`wrapped:${error.message}`)
+      return refinedError
+    },
+  })
+
+  await expect(Array.fromAsync(errored)).rejects.toThrow("wrapped:Error: transform-boom")
+  expect(refinedError?.message).toBe("wrapped:Error: transform-boom")
 })

package/tests/unit/credential/api-key.spec.ts

@@ -0,0 +1,37 @@
+import { expect, test, vi } from "vitest"
+
+import { generateApiKey, maskApiKey } from "#Source/credential/index.ts"
+
+test("generateApiKey creates a stable sk-prefixed key shape", () => {
+  vi.spyOn(crypto, "getRandomValues").mockImplementation(buffer => {
+    if (buffer === null) {
+      return buffer
+    }
+
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    const target = buffer as Uint8Array
+    target.forEach((_, index) => {
+      target[index] = index
+    })
+    return buffer
+  })
+
+  const apiKey = generateApiKey({})
+  const customApiKey = generateApiKey({ prefix: "pk_", alphabet: "ABC123", bodyLength: 6 })
+
+  expect(apiKey.startsWith("sk-")).toBe(true)
+  expect(apiKey).toHaveLength(51)
+  expect(apiKey).toMatch(/^sk-[0-9A-Za-z]{48}$/)
+  expect(customApiKey).toBe("pk_ABC123")
+  expect(() => generateApiKey({ alphabet: "", bodyLength: 6 })).toThrow("Expected alphabet to contain at least one character")
+})
+
+test("maskApiKey hides the middle of a valid key and rejects malformed input", () => {
+  const apiKey = `sk-${"ab"}${"0".repeat(44)}yz`
+  const customOptions = { prefix: "pk_", alphabet: "ABC123", bodyLength: 6 } as const
+
+  expect(maskApiKey(apiKey)).toBe("sk-ab********************************************yz")
+  expect(maskApiKey("pk_ABC123", customOptions)).toBe("pk_AB**23")
+  expect(() => maskApiKey("not-an-api-key")).toThrow("Invalid API key format")
+  expect(() => maskApiKey(`sk-${"#".repeat(48)}`)).toThrow("Invalid API key format")
+})

package/tests/unit/credential/bearer.spec.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "vitest"
+
+import { formatBearerCredential, isBearerCredential, parseBearerCredential } from "#Source/credential/index.ts"
+
+test("isBearerCredential recognizes bearer credential strings", () => {
+  expect(isBearerCredential("Bearer token-value")).toBe(true)
+  expect(isBearerCredential("bearer token-value")).toBe(true)
+  expect(isBearerCredential("Basic token-value")).toBe(false)
+  expect(isBearerCredential("token-value")).toBe(false)
+})
+
+test("formatBearerCredential prefixes a raw token with the Bearer scheme", () => {
+  expect(formatBearerCredential("token-value")).toBe("Bearer token-value")
+  expect(formatBearerCredential("  token-value  ")).toBe("Bearer token-value")
+  expect(() => formatBearerCredential("   ")).toThrow("Expected token to contain at least one non-whitespace character")
+})
+
+test("parseBearerCredential extracts the raw token only from bearer credentials", () => {
+  expect(parseBearerCredential("Bearer token-value")).toBe("token-value")
+  expect(parseBearerCredential("bearer token-value")).toBe("token-value")
+  expect(parseBearerCredential("Basic token-value")).toBeUndefined()
+  expect(parseBearerCredential(undefined)).toBeUndefined()
+})

package/tests/unit/credential/json-web-token.spec.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "vitest"
+
+import { formatBearerCredential, JsonWebToken } from "#Source/credential/index.ts"
+
+test("JsonWebToken.signToken creates a compact JWT string", async () => {
+  const jwt = new JsonWebToken({ secret: "credential-secret", expiresIn: 3_600 })
+
+  const token = await jwt.signToken("user-1")
+
+  expect(token.split(".")).toHaveLength(3)
+  expect(typeof token).toBe("string")
+})
+
+test("JsonWebToken.parseToken returns userId for valid tokens and undefined for invalid input", async () => {
+  const jwt = new JsonWebToken({ secret: "credential-secret", expiresIn: 3_600 })
+  const token = await jwt.signToken("user-1")
+
+  await expect(jwt.parseToken(token)).resolves.toBe("user-1")
+  await expect(jwt.parseToken(formatBearerCredential(token))).resolves.toBeUndefined()
+  await expect(jwt.parseToken(undefined)).resolves.toBeUndefined()
+  await expect(jwt.parseToken("broken.token.value")).resolves.toBeUndefined()
+  await expect(new JsonWebToken({ secret: "other-secret", expiresIn: 3_600 }).parseToken(token)).resolves.toBeUndefined()
+})

package/tests/unit/credential/password.spec.ts

@@ -0,0 +1,41 @@
+import { expect, test, vi } from "vitest"
+
+import { Password } from "#Source/credential/index.ts"
+
+test("Password.generateSalt returns a hexadecimal salt string of the requested byte length", () => {
+  vi.spyOn(crypto, "getRandomValues").mockImplementation(buffer => {
+    if (buffer === null) {
+      return buffer
+    }
+
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    const target = buffer as Uint8Array
+    target.fill(0xAB)
+    return buffer
+  })
+
+  const salt = Password.generateSalt(8)
+
+  expect(salt).toBe("abababababababab")
+  expect(salt).toHaveLength(16)
+})
+
+test("Password.hashPasswordWithSalt derives a stable PBKDF2-SHA-512 hash for the same input", async () => {
+  const salt = "00112233445566778899AABBCCDDEEFF"
+  const hash1 = await Password.hashPasswordWithSalt("secret", salt)
+  const hash2 = await Password.hashPasswordWithSalt("secret", salt)
+  const hash3 = await Password.hashPasswordWithSalt("other", salt)
+
+  expect(hash1).toHaveLength(128)
+  expect(hash1).toMatch(/^[0-9A-F]+$/i)
+  expect(hash1).toBe(hash2)
+  expect(hash1).not.toBe(hash3)
+})
+
+test("Password.comparePassword distinguishes matching and mismatching passwords", async () => {
+  const salt = "00112233445566778899AABBCCDDEEFF"
+  const hash = await Password.hashPasswordWithSalt("secret", salt)
+
+  await expect(Password.comparePassword("secret", hash, salt)).resolves.toBe(true)
+  await expect(Password.comparePassword("other", hash, salt)).resolves.toBe(false)
+})