@planet-matrix/mobius-model 0.6.0 → 0.10.1

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,36 @@
+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
+    }
+
+    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,40 @@
+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
+    }
+
+    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)
+})

package/tests/unit/cron/cron.spec.ts

@@ -0,0 +1,84 @@
+import { expect, test } from "vitest"
+
+import { Cron } from "#Source/cron/index.ts"
+
+const internalCreateFutureMinute = (minutesAhead: number): Date => {
+  const date = new Date(Date.now() + minutesAhead * 60_000)
+  date.setSeconds(0, 0)
+  return date
+}
+
+const internalCreatePastMinute = (minutesAgo: number): Date => {
+  const date = new Date(Date.now() - minutesAgo * 60_000)
+  date.setSeconds(0, 0)
+  return date
+}
+
+test("Cron creates schedule models from both cron expressions and one-shot dates", () => {
+  const expressionCron = new Cron({ pattern: "*/5 * * * *" })
+  const singleShotCron = new Cron({ pattern: internalCreateFutureMinute(5) })
+
+  expect(expressionCron).toBeInstanceOf(Cron)
+  expect(singleShotCron).toBeInstanceOf(Cron)
+})
+
+test("Cron.prevRun returns undefined before a one-shot schedule is reached", () => {
+  const scheduledAt = internalCreateFutureMinute(5)
+  const cron = new Cron({ pattern: scheduledAt })
+
+  expect(cron.prevRun()).toBeUndefined()
+})
+
+test("Cron.prevRuns returns historical one-shot runs that have already happened", () => {
+  const scheduledAt = internalCreatePastMinute(5)
+  const cron = new Cron({ pattern: scheduledAt })
+  const previousRuns = cron.prevRuns(2)
+
+  expect(previousRuns).toHaveLength(1)
+  expect(previousRuns[0]?.getTime()).toBe(scheduledAt.getTime())
+})
+
+test("Cron.currentRun stays undefined when the model is only queried and not executing a task", () => {
+  const cron = new Cron({ pattern: internalCreateFutureMinute(5) })
+
+  expect(cron.currentRun()).toBeUndefined()
+})
+
+test("Cron.nextRun returns the next upcoming one-shot run", () => {
+  const scheduledAt = internalCreateFutureMinute(5)
+  const cron = new Cron({ pattern: scheduledAt })
+
+  expect(cron.nextRun()?.getTime()).toBe(scheduledAt.getTime())
+})
+
+test("Cron.nextRuns returns upcoming expression runs in ascending order", () => {
+  const cron = new Cron({ pattern: "*/5 * * * *" })
+  const nextRuns = cron.nextRuns(2)
+
+  expect(nextRuns).toHaveLength(2)
+  expect(nextRuns[0]?.getTime()).toBeLessThan(nextRuns[1]?.getTime() ?? 0)
+  expect(cron.match(nextRuns[0]!)).toBe(true)
+  expect(cron.match(nextRuns[1]!)).toBe(true)
+})
+
+test("Cron.match reflects cron-expression semantics including domAndDow behavior", () => {
+  const yearlyCron = new Cron({ pattern: "0 0 1 1 *" })
+  const andCron = new Cron({ pattern: "0 0 1 * MON", domAndDow: true })
+  const orCron = new Cron({ pattern: "0 0 1 * MON", domAndDow: false })
+  const yearlyHit = new Date(2_026, 0, 1, 0, 0, 0, 0)
+  const yearlyMiss = new Date(2_026, 0, 1, 0, 1, 0, 0)
+  const mondayFirst = new Date(2_026, 5, 1, 0, 0, 0, 0)
+  const mondayNotFirst = new Date(2_026, 5, 8, 0, 0, 0, 0)
+  const firstNotMonday = new Date(2_026, 8, 1, 0, 0, 0, 0)
+
+  expect(yearlyCron.match(yearlyHit)).toBe(true)
+  expect(yearlyCron.match(yearlyMiss)).toBe(false)
+
+  expect(andCron.match(mondayFirst)).toBe(true)
+  expect(andCron.match(mondayNotFirst)).toBe(false)
+  expect(andCron.match(firstNotMonday)).toBe(false)
+
+  expect(orCron.match(mondayFirst)).toBe(true)
+  expect(orCron.match(mondayNotFirst)).toBe(true)
+  expect(orCron.match(firstNotMonday)).toBe(true)
+})

package/tests/unit/event/class-event-proxy.spec.ts

@@ -1,15 +1,15 @@
 import { expect, test, vi } from "vitest"
 
-import type { BaseEvents, ClassEventProxyOptions } from "#Source/event/index.ts"
+import type { BuildEvents, ClassEventProxyOptions } from "#Source/event/index.ts"
 import {
   ClassEventProxy,
   EventManager,
 } from "#Source/event/index.ts"
 
-interface TestEvents extends BaseEvents {
+type TestEvents = BuildEvents<{
   change: (value: number) => void
   close: (reason: string) => void
-}
+}>
 
 interface TestTarget {
   events: EventManager<TestEvents>

package/tests/unit/event/event-manager.spec.ts

@@ -1,12 +1,12 @@
 import { expect, test, vi } from "vitest"
 
-import type { BaseEvents } from "#Source/event/index.ts"
+import type { BuildEvents } from "#Source/event/index.ts"
 import { EventManager } from "#Source/event/index.ts"
 
-interface TestEvents extends BaseEvents {
+type TestEvents = BuildEvents<{
   ready: (value: number) => void | Promise<void>
   done: (label: string) => void | Promise<void>
-}
+}>
 const createEventManager = (): EventManager<TestEvents> => {
   return new EventManager<TestEvents>()
 }

package/tests/unit/event/instance-event-proxy.spec.ts

@@ -1,15 +1,15 @@
 import { expect, test, vi } from "vitest"
 
-import type { BaseEvents, InstanceEventProxyOptions } from "#Source/event/index.ts"
+import type { BuildEvents, InstanceEventProxyOptions } from "#Source/event/index.ts"
 import {
   EventManager,
   InstanceEventProxy,
 } from "#Source/event/index.ts"
 
-interface TestEvents extends BaseEvents {
+type TestEvents = BuildEvents<{
   change: (value: number) => void
   error: (message: string) => void
-}
+}>
 
 const createInstanceEventProxyHarness = (options?: {
   onSubscriberError?: (error: unknown) => void

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

@@ -0,0 +1,83 @@
+import { expect, test, vi } from "vitest"
+
+import {
+  createTaggedError,
+  isTaggedError,
+} from "#Source/exception/index.ts"
+
+test("createTaggedError creates tagged errors with inferred message, cause and serialization", () => {
+  const dateNowSpy = vi.spyOn(Date, "now").mockReturnValue(123)
+
+  try {
+    const ExampleError = createTaggedError("Example")<{
+      message: string
+      cause: Error
+      extra: number
+    }>()
+    const MessageOnlyError = createTaggedError("MessageOnly")<string>()
+    const cause = new Error("root")
+
+    cause.stack = "Error: root\n    at cause"
+
+    const example1 = new ExampleError({
+      message: "boom",
+      cause,
+      extra: 1,
+    })
+    const example2 = new MessageOnlyError("plain-message")
+    const example3 = ExampleError.is(example1)
+    const example4 = ExampleError.is(
+      new (createTaggedError("Example")<{ message: string }>())({
+        message: "compatible",
+      }),
+    )
+    const example5 = example1.toJSON()
+
+    expect(example1).toBeInstanceOf(Error)
+    expect(example1.name).toBe("Example")
+    expect(example1.tag).toBe("Example")
+    expect(example1.data.extra).toBe(1)
+    expect(example1.message).toBe("boom")
+    expect(example1.cause).toBe(cause)
+    expect(example1.stack).toContain("Caused by: Error: root")
+    expect(example2.message).toBe("plain-message")
+    expect(example3).toBe(true)
+    expect(example4).toBe(true)
+    expect(example5).toMatchObject({
+      version: "1",
+      tag: "Example",
+      data: {
+        message: "boom",
+        cause,
+        extra: 1,
+      },
+      name: "Example",
+      message: "boom",
+      cause: {
+        name: "Error",
+        message: "root",
+        stack: "Error: root\n    at cause",
+      },
+      timestamp: 123,
+    })
+  } finally {
+    dateNowSpy.mockRestore()
+  }
+})
+
+test("isTaggedError distinguishes tagged errors from plain values", () => {
+  const ExampleError = createTaggedError("Example")<{ message: string }>()
+
+  const example1 = new ExampleError({ message: "boom" })
+  const example2 = new Error("boom")
+  const example3 = {
+    tag: "Example",
+    data: { message: "boom" },
+    toJSON: () => ({ message: "boom" }),
+  }
+
+  expect(isTaggedError(example1)).toBe(true)
+  expect(isTaggedError(example2)).toBe(false)
+  expect(isTaggedError(example3)).toBe(false)
+  expect(isTaggedError(null)).toBe(false)
+})