@planet-matrix/mobius-model 0.5.0 → 0.9.0

package/tests/unit/http/api-adapter/node-http.spec.ts

@@ -0,0 +1,191 @@
+import type { AddressInfo } from "node:net"
+
+import { afterEach, expect, test } from "vitest"
+
+import { Http } from "#Source/index.ts"
+
+afterEach(async () => {
+  await Promise.resolve()
+})
+
+test("ApiHostNodeHttp exposes usable URLs and forwards request data to ApiCoreNodeHttp", async () => {
+  const apiHost = Http.createApiHostNodeHttp({ port: 0 })
+
+  apiHost.attachApiCoreHandler(async (apiCore) => {
+    const path = await apiCore.getRequestPath()
+    const method = await apiCore.getRequestMethod()
+    const search = await apiCore.getRequestSearch()
+    const bodyJson = await apiCore.getRequestBodyJson()
+
+    await apiCore.json({
+      path,
+      method,
+      search,
+      bodyJson,
+    })
+  })
+
+  const startResult = await apiHost.start()
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+  const address = apiHost.safeGetServer().address() as AddressInfo
+
+  expect(startResult.urlList).toContain(`http://127.0.0.1:${address.port}`)
+  expect(startResult.urlList).toContain(`http://localhost:${address.port}`)
+  expect(startResult.urlList).toContain(`http://[::1]:${address.port}`)
+
+  const response = await fetch(`http://127.0.0.1:${address.port}/users?page=2`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ name: "Mobius" }),
+  })
+
+  await expect(response.json()).resolves.toEqual({
+    path: "/users",
+    method: "POST",
+    search: "?page=2",
+    bodyJson: { name: "Mobius" },
+  })
+
+  await apiHost.close()
+
+  expect(apiHost.isRunning()).toBe(false)
+})
+
+test("ApiCoreNodeHttp returns a stable error response when the handler throws", async () => {
+  const apiHost = Http.createApiHostNodeHttp({ port: 0 })
+
+  apiHost.attachApiCoreHandler(() => {
+    throw new Error("boom")
+  })
+
+  await apiHost.start()
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+  const address = apiHost.safeGetServer().address() as AddressInfo
+
+  const response = await fetch(`http://127.0.0.1:${address.port}/error`, {
+    method: "GET",
+  })
+
+  expect(response.status).toBe(500)
+  await expect(response.json()).resolves.toEqual({
+    status: "error",
+    data: {
+      reason: "internal_server_error",
+    },
+  })
+
+  await apiHost.close()
+})
+
+test("ApiCoreNodeHttp treats an empty request body as an empty object", async () => {
+  const apiHost = Http.createApiHostNodeHttp({ port: 0 })
+
+  apiHost.attachApiCoreHandler(async (apiCore) => {
+    await apiCore.json({
+      bodyJson: await apiCore.getRequestBodyJson(),
+    })
+  })
+
+  await apiHost.start()
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+  const address = apiHost.safeGetServer().address() as AddressInfo
+
+  const response = await fetch(`http://127.0.0.1:${address.port}/empty`, {
+    method: "GET",
+  })
+
+  await expect(response.json()).resolves.toEqual({
+    bodyJson: {},
+  })
+
+  await apiHost.close()
+})
+
+test("ApiCoreNodeHttp exposes normalized headers and parses multipart form data", async () => {
+  const apiHost = Http.createApiHostNodeHttp({ port: 0 })
+
+  apiHost.attachApiCoreHandler(async (apiCore) => {
+    const headers = await apiCore.getRequestHeaders()
+    const formData = await apiCore.getRequestBodyFormData()
+    const files = await apiCore.getRequestFiles()
+
+    await apiCore.json({
+      contentType: headers["content-type"],
+      customHeader: await apiCore.getRequestHeader("X-Custom-Header"),
+      formData: formData.map((entry) => {
+        if (entry.value instanceof File) {
+          return {
+            name: entry.name,
+            value: {
+              kind: "file",
+              name: entry.value.name,
+              size: entry.value.size,
+              type: entry.value.type,
+            },
+          }
+        }
+
+        return {
+          name: entry.name,
+          value: entry.value,
+        }
+      }),
+      files: files.map((file) => {
+        return {
+          name: file.name,
+          fileName: file.value.name,
+          size: file.value.size,
+          type: file.value.type,
+        }
+      }),
+    })
+  })
+
+  await apiHost.start()
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+  const address = apiHost.safeGetServer().address() as AddressInfo
+
+  const formData = new FormData()
+  formData.append("user", "Mobius")
+  formData.append("avatar", new File(["hello"], "avatar.txt", { type: "text/plain" }))
+
+  const response = await fetch(`http://127.0.0.1:${address.port}/upload`, {
+    method: "POST",
+    headers: {
+      "X-Custom-Header": "alpha",
+    },
+    body: formData,
+  })
+
+  await expect(response.json()).resolves.toEqual({
+    contentType: [expect.stringContaining("multipart/form-data")],
+    customHeader: ["alpha"],
+    formData: [
+      {
+        name: "user",
+        value: "Mobius",
+      },
+      {
+        name: "avatar",
+        value: {
+          kind: "file",
+          name: "avatar.txt",
+          size: 5,
+          type: "text/plain",
+        },
+      },
+    ],
+    files: [
+      {
+        name: "avatar",
+        fileName: "avatar.txt",
+        size: 5,
+        type: "text/plain",
+      },
+    ],
+  })
+
+  await apiHost.close()
+})

package/tests/unit/identifier/id.spec.ts

@@ -0,0 +1,71 @@
+import { expect, test } from "vitest"
+
+import {
+  assertId,
+  generateId,
+  idToString,
+  isEqualId,
+  isId,
+  isSameId,
+} from "#Source/identifier/index.ts"
+
+test("generateId is seed-stable and no-seed calls are uncached", () => {
+  const first = generateId("user:42")
+  const second = generateId("user:42")
+  const third = generateId("user:43")
+  const withoutSeed1 = generateId()
+  const withoutSeed2 = generateId()
+  const undefinedSeed1 = generateId(undefined)
+  const undefinedSeed2 = generateId(undefined)
+
+  expect(first).toBe(second)
+  expect(first).not.toBe(third)
+  expect(withoutSeed1).not.toBe(withoutSeed2)
+  expect(undefinedSeed1).not.toBe(undefinedSeed2)
+  expect(withoutSeed1).not.toBe(undefinedSeed1)
+})
+
+test("isId validates generated Id values", () => {
+  const id = generateId(1)
+
+  expect(isId(id)).toBe(true)
+  expect(isId(null)).toBe(false)
+  expect(isId(undefined)).toBe(false)
+  expect(isId("plain-string")).toBe(false)
+  expect(isId({})).toBe(false)
+})
+
+test("assertId throws for non-Id inputs", () => {
+  const id = generateId(Symbol("seed"))
+
+  expect(() => assertId(id)).not.toThrow()
+  expect(() => assertId("plain-string")).toThrow(TypeError)
+  expect(() => assertId(1)).toThrow(TypeError)
+})
+
+test("isSameId compares by instance identity", () => {
+  const id = generateId("same")
+  const sameReference = id
+  const another = generateId("another")
+
+  expect(isSameId(id, sameReference)).toBe(true)
+  expect(isSameId(id, another)).toBe(false)
+})
+
+test("isEqualId compares internal ID value", () => {
+  const first = generateId("equal-seed")
+  const second = generateId("equal-seed")
+  const third = generateId("different-seed")
+
+  expect(isEqualId(first, second)).toBe(true)
+  expect(isEqualId(first, third)).toBe(false)
+})
+
+test("idToString serializes Id to readable label", () => {
+  const id = generateId("to-string")
+  const asString = idToString(id)
+
+  expect(asString.startsWith("Symbol-ID-")).toBe(true)
+  // oxlint-disable-next-line typescript/no-base-to-string
+  expect(asString).toBe(String(id))
+})

package/tests/unit/identifier/uuid.spec.ts

@@ -0,0 +1,85 @@
+import { afterEach, expect, test, vi } from "vitest"
+
+import { assertUuid, generateUuidV4, generateUuidV4FromUrl, generateUuidV7, getUuidVersion, isUuid } from "#Source/identifier/index.ts"
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+test("isUuid validates UUID input", () => {
+  expect(isUuid("550e8400-e29b-41d4-a716-446655440000")).toBe(true)
+  expect(isUuid("550E8400-E29B-41D4-A716-446655440000")).toBe(true)
+  expect(isUuid("123e4567-e89b-12d3-a456-426614174000")).toBe(true)
+
+  expect(isUuid("not-a-uuid")).toBe(false)
+  expect(isUuid("550e8400e29b41d4a716446655440000")).toBe(false)
+  expect(isUuid("550e8400-e29b-91d4-a716-446655440000")).toBe(false)
+  expect(isUuid("550e8400-e29b-41d4-c716-446655440000")).toBe(false)
+})
+
+test("assertUuid throws on malformed input", () => {
+  expect(() => assertUuid("550e8400-e29b-41d4-a716-446655440000")).not.toThrow()
+  expect(() => assertUuid("not-a-uuid")).toThrow(TypeError)
+  expect(() => assertUuid("550e8400e29b41d4a716446655440000")).toThrow(TypeError)
+})
+
+test("getUuidVersion returns UUID version and throws on malformed input", () => {
+  expect(getUuidVersion("550e8400-e29b-41d4-a716-446655440000")).toBe(4)
+  expect(getUuidVersion("123e4567-e89b-12d3-a456-426614174000")).toBe(1)
+
+  expect(() => getUuidVersion("not-a-uuid")).toThrow(TypeError)
+})
+
+test("generateUuid returns RFC 4122 version-4 UUID format", () => {
+  const UUID_V4_REGEXP = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+  const value1 = generateUuidV4()
+  const value2 = generateUuidV4()
+
+  expect(value1).toMatch(UUID_V4_REGEXP)
+  expect(value2).toMatch(UUID_V4_REGEXP)
+  expect(value1).not.toBe(value2)
+})
+
+test("generateUuidV4FromUrl extracts UUID from object URL and revokes URL", () => {
+  const mockedUuid = "1e34c01e-ab7c-4e60-b6f3-a6101e8c0d2d"
+  const mockedObjectUrl = `blob:https://www.cigaret.world/${mockedUuid}`
+  const createObjectUrlSpy = vi.spyOn(URL, "createObjectURL").mockReturnValue(mockedObjectUrl)
+  const revokeObjectUrlSpy = vi.spyOn(URL, "revokeObjectURL").mockImplementation(() => {
+    return undefined
+  })
+
+  const value = generateUuidV4FromUrl()
+
+  expect(value).toBe(mockedUuid)
+  expect(isUuid(value)).toBe(true)
+  expect(createObjectUrlSpy).toHaveBeenCalledTimes(1)
+  expect(revokeObjectUrlSpy).toHaveBeenCalledTimes(1)
+  expect(revokeObjectUrlSpy).toHaveBeenCalledWith(mockedObjectUrl)
+})
+
+test("generateUuidV7 returns UUIDv7 format and is monotonic within the same millisecond", () => {
+  const UUID_V7_REGEXP = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+  vi.spyOn(Date, "now").mockReturnValue(1_700_000_000_000)
+  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(0)
+    return buffer
+  })
+
+  const value1 = generateUuidV7()
+  const value2 = generateUuidV7()
+  const value3 = generateUuidV7()
+
+  expect(value1).toMatch(UUID_V7_REGEXP)
+  expect(value2).toMatch(UUID_V7_REGEXP)
+  expect(value3).toMatch(UUID_V7_REGEXP)
+
+  expect(value1 < value2).toBe(true)
+  expect(value2 < value3).toBe(true)
+})

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

@@ -0,0 +1,11 @@
+import { expect, test } from "vitest"
+
+import { repairJson } from "#Source/json/index.ts"
+
+test("repairJson repairs common JSON-like text issues and throws for unrecoverable input", () => {
+  expect(repairJson("{foo:1,}")).toBe('{"foo":1}')
+  expect(repairJson("{'name':'mobius',}")).toBe('{"name":"mobius"}')
+  expect(repairJson('{"items":[1,2,],}')).toBe('{"items":[1,2]}')
+
+  expect(() => repairJson('{"a":1,,"b":2}')).toThrow()
+})

package/tests/unit/log/log-emitter.spec.ts

@@ -0,0 +1,33 @@
+import { afterEach, expect, test, vi } from "vitest"
+
+import {
+  ConsoleDebugLogEmitter,
+  ConsoleErrorLogEmitter,
+  ConsoleInfoLogEmitter,
+  ConsoleLogLogEmitter,
+  ConsoleWarnLogEmitter,
+} from "#Source/log/index.ts"
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+test("console log emitters format tags and messages before output", () => {
+  const logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined)
+  const infoSpy = vi.spyOn(console, "info").mockImplementation(() => undefined)
+  const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => undefined)
+  const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
+  const debugSpy = vi.spyOn(console, "debug").mockImplementation(() => undefined)
+
+  new ConsoleLogLogEmitter({ tags: ["scope", "unit"], messages: ["hello", 1] }).emit()
+  new ConsoleInfoLogEmitter({ tags: ["scope"], messages: ["info"] }).emit()
+  new ConsoleWarnLogEmitter({ tags: ["scope"], messages: ["warn"] }).emit()
+  new ConsoleErrorLogEmitter({ tags: ["scope"], messages: ["error"] }).emit()
+  new ConsoleDebugLogEmitter({ tags: ["scope"], messages: ["debug"] }).emit()
+
+  expect(logSpy).toHaveBeenCalledWith("[scope][unit] hello 1")
+  expect(infoSpy).toHaveBeenCalledWith("[scope] info")
+  expect(warnSpy).toHaveBeenCalledWith("[scope] warn")
+  expect(errorSpy).toHaveBeenCalledWith("[scope] error")
+  expect(debugSpy).toHaveBeenCalledWith("[scope] debug")
+})

package/tests/unit/log/log-scheduler.spec.ts

@@ -0,0 +1,40 @@
+import { expect, test, vi } from "vitest"
+
+import { LogScheduler, getGlobalLogScheduler } from "#Source/log/index.ts"
+
+test("LogScheduler enqueue dispatches immediately in immediate strategy", () => {
+  const scheduler = new LogScheduler({ strategy: "immediate" })
+  const emit1 = vi.fn()
+  const emit2 = vi.fn()
+
+  scheduler.enqueue([
+    { record: { type: "log", tags: ["a"], messages: ["one"] }, emit: emit1 },
+    { record: { type: "info", tags: ["a"], messages: ["two"] }, emit: emit2 },
+  ])
+
+  expect(emit1).toHaveBeenCalledTimes(1)
+  expect(emit2).toHaveBeenCalledTimes(1)
+})
+
+test("LogScheduler run flushes queued tasks", () => {
+  const scheduler = new LogScheduler({ strategy: "immediate" })
+  const emit1 = vi.fn()
+  const emit2 = vi.fn()
+
+  scheduler.enqueue([
+    { record: { type: "log", tags: ["a"], messages: ["one"] }, emit: emit1 },
+    { record: { type: "info", tags: ["a"], messages: ["two"] }, emit: emit2 },
+  ])
+  scheduler.run()
+
+  expect(emit1).toHaveBeenCalledTimes(1)
+  expect(emit2).toHaveBeenCalledTimes(1)
+  expect(scheduler.hasTasks()).toEqual(false)
+})
+
+test("getGlobalLogScheduler returns singleton instance", () => {
+  const scheduler1 = getGlobalLogScheduler()
+  const scheduler2 = getGlobalLogScheduler()
+
+  expect(scheduler1).toBe(scheduler2)
+})

package/tests/unit/log/log-type.spec.ts

@@ -0,0 +1,7 @@
+import { expect, test } from "vitest"
+
+import { LOG_TYPES } from "#Source/log/index.ts"
+
+test("LOG_TYPES exposes supported log levels", () => {
+  expect(LOG_TYPES).toEqual(["log", "info", "warn", "error", "debug"])
+})

package/tests/unit/log/logger.spec.ts

@@ -0,0 +1,237 @@
+import { expect, test } from "vitest"
+
+import type { LogEmitter, LogEmitterItem } from "#Source/log/index.ts"
+import {
+  Logger,
+  getGlobalLogger,
+} from "#Source/log/index.ts"
+
+const makeMemoryEmitter = (sink: string[]): LogEmitterItem => {
+  class InternalMemoryEmitter implements LogEmitter {
+    readonly tags: string[]
+    readonly messages: unknown[]
+    readonly formattedMessages: string[]
+
+    constructor(options: { tags?: string[] | undefined, messages?: unknown[] | undefined }) {
+      this.tags = options.tags ?? []
+      this.messages = options.messages ?? []
+      this.formattedMessages = [
+        this.tags.map(tag => `[${tag}]`).join(""),
+        this.messages.map(message => String(message)).join(" "),
+      ]
+    }
+
+    emit(): void {
+      sink.push(this.formattedMessages.join(" "))
+    }
+  }
+
+  return {
+    logType: "info",
+    LogEmitter: InternalMemoryEmitter,
+  }
+}
+
+test("Logger.fromOptions returns provided logger and otherwise derives from global logger", () => {
+  const explicit = new Logger({ name: "Explicit" })
+  const resolvedExplicit = Logger.fromOptions({ logger: explicit })
+  const resolvedDerived = Logger.fromOptions({}).setDefaultName("Derived")
+
+  expect(resolvedExplicit).toBe(explicit)
+  expect(resolvedDerived.hasParent()).toBe(true)
+  expect(resolvedDerived.getNameTags()).toEqual([getGlobalLogger().getName(), "Derived"])
+})
+
+test("Logger.derive creates child logger with inherited configs", () => {
+  const parent = new Logger({ name: "Parent" })
+  const child = Logger.derive(parent).setDefaultName("Child")
+
+  expect(child.hasParent()).toBe(true)
+  expect(child.getNameTags()).toEqual(["Parent", "Child"])
+})
+
+test("Logger name APIs prefer explicit name and fall back to defaultName", () => {
+  const logger = new Logger({})
+
+  expect(logger.getName()).toBe("Unnamed")
+
+  logger.setDefaultName("DefaultLogger")
+  expect(logger.getName()).toBe("DefaultLogger")
+
+  logger.setName("ExplicitLogger")
+  expect(logger.getName()).toBe("ExplicitLogger")
+
+  logger.setName(undefined)
+  expect(logger.getName()).toBe("DefaultLogger")
+})
+
+test("Logger config APIs merge and apply parent configs", () => {
+  const parent = new Logger({
+    name: "Parent",
+    configs: {
+      enabled: true,
+      autoSend: true,
+      filter: (): boolean => true,
+      emitters: [],
+    },
+  })
+  const child = new Logger({
+    name: "Child",
+    parent,
+    configs: {
+      enabled: false,
+    },
+  })
+
+  expect(child.getConfigs().enabled).toBe(true)
+
+  child.setConfigs({ enabled: false })
+  expect(child.getConfigs().enabled).toBe(false)
+
+  child.useParentConfigs()
+  expect(child.getConfigs().enabled).toBe(true)
+})
+
+test("Logger emitter APIs add, deduplicate and remove emitters", () => {
+  const sink: string[] = []
+  const emitter = makeMemoryEmitter(sink)
+  const logger = new Logger({
+    name: "EmitterLogger",
+    configs: {
+      emitters: [],
+      enabled: true,
+      autoSend: true,
+      filter: (): boolean => true,
+    },
+  })
+
+  logger.addLogEmitters([emitter, emitter])
+  expect(logger.getAllLogEmitters()).toHaveLength(1)
+  expect(logger.getLogEmitters("info")).toHaveLength(1)
+
+  logger.info("hello")
+  expect(sink).toHaveLength(1)
+
+  logger.removeLogEmitters([emitter])
+  expect(logger.getAllLogEmitters()).toHaveLength(0)
+})
+
+test("Logger tags APIs manage instance, session and once tags", () => {
+  const sink: string[] = []
+  const logger = new Logger({
+    name: "TagLogger",
+    configs: {
+      emitters: [makeMemoryEmitter(sink)],
+      enabled: true,
+      autoSend: true,
+      filter: (): boolean => true,
+    },
+  })
+
+  logger.addInstanceTags(["instance"]).tagStart(["session"]).addOnceTags(["once"])
+  logger.info("first")
+  logger.info("second")
+
+  expect(sink[0]).toContain("[instance]")
+  expect(sink[0]).toContain("[session]")
+  expect(sink[0]).toContain("[once]")
+  expect(sink[1]).toContain("[instance]")
+  expect(sink[1]).toContain("[session]")
+  expect(sink[1]).not.toContain("[once]")
+
+  logger.removeInstanceTags(["instance"]).tagEnd()
+  expect(logger.getInstanceTags()).toEqual([])
+  expect(logger.getSessionTags()).toEqual([])
+})
+
+test("Logger.autoTag adds temporary tags during disposable scope", () => {
+  const sink: string[] = []
+  const logger = new Logger({
+    name: "AutoTagLogger",
+    configs: {
+      emitters: [makeMemoryEmitter(sink)],
+      enabled: true,
+      autoSend: true,
+      filter: (): boolean => true,
+    },
+  })
+
+  const disposable = logger.autoTag(["scoped"])
+  logger.info("within")
+  disposable[Symbol.dispose]()
+  logger.info("outside")
+
+  expect(sink[0]).toContain("[scoped]")
+  expect(sink[1]).not.toContain("[scoped]")
+})
+
+test("Logger logging APIs respect enabled and filter configs", () => {
+  const sink: string[] = []
+  const logger = new Logger({
+    name: "FilterLogger",
+    configs: {
+      emitters: [makeMemoryEmitter(sink)],
+      enabled: false,
+      autoSend: true,
+      filter: (): boolean => true,
+    },
+  })
+
+  logger.log("a").info("b").warn("c").error("d").debug("e")
+  expect(sink).toHaveLength(0)
+
+  logger.setConfigs({ enabled: true, filter: () => false })
+  logger.info("blocked")
+  expect(sink).toHaveLength(0)
+
+  logger.setConfigs({ filter: () => true })
+  logger.info("allowed")
+  expect(sink).toHaveLength(1)
+})
+
+test("Logger.send flushes queued logs when autoSend is disabled", () => {
+  const sink: string[] = []
+  const logger = new Logger({
+    name: "BatchLogger",
+    configs: {
+      emitters: [makeMemoryEmitter(sink)],
+      enabled: true,
+      autoSend: false,
+      filter: (): boolean => true,
+    },
+  })
+
+  logger.info("queued")
+  expect(sink).toHaveLength(0)
+
+  logger.send()
+  expect(sink).toHaveLength(1)
+})
+
+test("Logger.batch creates manual child logger and supports disposal send", () => {
+  const sink: string[] = []
+  const logger = new Logger({
+    name: "ParentLogger",
+    configs: {
+      emitters: [makeMemoryEmitter(sink)],
+      enabled: true,
+      autoSend: true,
+      filter: (): boolean => true,
+    },
+  })
+
+  const child = logger.batch("batch-id")
+  child.info("queued")
+  expect(sink).toHaveLength(0)
+
+  child[Symbol.dispose]()
+  expect(sink).toHaveLength(1)
+  expect(sink[0]).toContain("[batch-id]")
+})
+
+test("getGlobalLogger returns singleton instance", () => {
+  const logger1 = getGlobalLogger()
+  const logger2 = getGlobalLogger()
+
+  expect(logger1).toBe(logger2)
+})