@planet-matrix/mobius-model 0.5.0 → 0.6.0

package/tests/unit/environment/runtime.spec.ts

@@ -0,0 +1,364 @@
+import { expect, test, vi } from "vitest"
+import {
+  getRuntime,
+  getRuntimeContextBrowser,
+  getRuntimeContextBun,
+  getRuntimeContextDeno,
+  getRuntimeContextNodejs,
+  getRuntimeContextUnknown,
+  getRuntimeContextWebWorker,
+  getRuntimeFlags,
+  getRuntimeRegistryItem,
+  getServiceWorkerContext,
+  isBrowser,
+  isBun,
+  isDeno,
+  isNodejs,
+  isRuntimeRegistered,
+  isSatisfiesRuntime,
+  isSatisfiesRuntimes,
+  isServiceWorker,
+  isUnknown,
+  isWebWorker,
+  listRuntimes,
+  registerRuntime,
+  unregisterRuntime,
+  useBrowser,
+  useBun,
+  useDeno,
+  useNodejs,
+  useRuntimes,
+  useServiceWorker,
+  useUnknown,
+  useWebWorker,
+} from "#Source/environment/runtime.ts"
+
+test("isRuntimeRegistered detects built-in and missing runtime", () => {
+  expect(isRuntimeRegistered("nodejs")).toBe(true)
+  expect(isRuntimeRegistered("custom-runtime")).toBe(false)
+})
+
+test("registerRuntime stores custom runtime", () => {
+  registerRuntime({
+    runtime: "custom-register",
+    detect: () => false,
+    getGlobalContext: () => ({ ok: true }),
+    use: (_use, otherwise) => otherwise(),
+  })
+
+  expect(isRuntimeRegistered("custom-register")).toBe(true)
+  unregisterRuntime("custom-register")
+})
+
+test("unregisterRuntime removes custom runtime", () => {
+  registerRuntime({
+    runtime: "custom-remove",
+    detect: () => false,
+    getGlobalContext: () => ({ ok: true }),
+    use: (_use, otherwise) => otherwise(),
+  })
+  unregisterRuntime("custom-remove")
+
+  expect(isRuntimeRegistered("custom-remove")).toBe(false)
+})
+
+test("listRuntimes returns runtime keys", () => {
+  const runtimes = listRuntimes()
+
+  expect(runtimes).toContain("nodejs")
+  expect(runtimes).toContain("unknown")
+})
+
+test("isBrowser detects browser context", () => {
+  const browserWindow = { document: { title: "mock" } }
+  vi.stubGlobal("window", browserWindow)
+  vi.stubGlobal("self", browserWindow)
+
+  expect(isBrowser()).toBe(true)
+  vi.unstubAllGlobals()
+})
+
+test("getRuntimeContextBrowser returns browser globals", () => {
+  const browserWindow = { document: { title: "mock" } }
+  vi.stubGlobal("window", browserWindow)
+  vi.stubGlobal("self", browserWindow)
+
+  const context = getRuntimeContextBrowser()
+
+  expect(context.window).toBe(browserWindow)
+  expect(context.self).toBe(browserWindow)
+  vi.unstubAllGlobals()
+})
+
+test("useBrowser executes matched handler", { skip: false }, () => {
+  const browserWindow = { document: { title: "mock" } }
+  vi.stubGlobal("window", browserWindow)
+  vi.stubGlobal("self", browserWindow)
+
+  const browserResult = useBrowser(
+    (context) => context.window.document.title,
+    () => "fallback",
+  )
+
+  expect(browserResult).toBe("mock")
+  vi.unstubAllGlobals()
+})
+
+test("isNodejs detects Node.js runtime", () => {
+  expect(isNodejs()).toBe(true)
+})
+
+test("getRuntimeContextNodejs returns node globals", () => {
+  const context = getRuntimeContextNodejs()
+
+  expect(context.global).toBe(globalThis)
+  expect(context.globalThis).toBe(globalThis)
+})
+
+test("useNodejs executes node handler", () => {
+  const nodeResult = useNodejs(
+    (context) => context.globalThis === globalThis,
+    () => false,
+  )
+
+  expect(nodeResult).toBe(true)
+})
+
+test("isDeno detects deno runtime", () => {
+  vi.stubGlobal("Deno", { version: { deno: "2.0.0" } })
+
+  expect(isDeno()).toBe(true)
+  vi.unstubAllGlobals()
+})
+
+test("getRuntimeContextDeno returns deno context", () => {
+  vi.stubGlobal("Deno", { version: { deno: "2.0.0" } })
+  const context = getRuntimeContextDeno()
+
+  expect(context.global).toBe(globalThis)
+  vi.unstubAllGlobals()
+})
+
+test("useDeno executes deno handler", () => {
+  vi.stubGlobal("Deno", { version: { deno: "2.0.0" } })
+  const denoResult = useDeno(
+    (context) => context.globalThis === globalThis,
+    () => false,
+  )
+
+  expect(denoResult).toBe(true)
+  vi.unstubAllGlobals()
+})
+
+test("isBun detects bun runtime", () => {
+  vi.stubGlobal("Bun", { version: "1.0.0" })
+
+  expect(isBun()).toBe(true)
+  vi.unstubAllGlobals()
+})
+
+test("getRuntimeContextBun returns bun context", () => {
+  const bunGlobal = { version: "1.0.0" }
+  vi.stubGlobal("Bun", bunGlobal)
+  const context = getRuntimeContextBun()
+
+  expect(context.Bun).toBe(bunGlobal)
+  vi.unstubAllGlobals()
+})
+
+test("useBun executes bun handler", () => {
+  vi.stubGlobal("Bun", { version: "1.0.0" })
+  const bunResult = useBun(
+    (context) => typeof context.Bun.version,
+    () => "fallback",
+  )
+
+  expect(bunResult).toBe("string")
+  vi.unstubAllGlobals()
+})
+
+test("isWebWorker detects web worker runtime", () => {
+  class WorkerGlobalScopeMock {
+    readonly internalType = "worker"
+  }
+  class ServiceWorkerGlobalScopeMock extends WorkerGlobalScopeMock {
+    readonly internalTypeService = "service-worker"
+  }
+
+  vi.stubGlobal("WorkerGlobalScope", WorkerGlobalScopeMock)
+  vi.stubGlobal("ServiceWorkerGlobalScope", ServiceWorkerGlobalScopeMock)
+  vi.stubGlobal("self", new WorkerGlobalScopeMock())
+  vi.stubGlobal("process", undefined)
+  vi.stubGlobal("window", undefined)
+
+  expect(isWebWorker()).toBe(true)
+  vi.unstubAllGlobals()
+})
+
+test("getRuntimeContextWebWorker returns worker context", () => {
+  class WorkerGlobalScopeMock {
+    readonly internalType = "worker"
+  }
+
+  const selfWorker = new WorkerGlobalScopeMock()
+  vi.stubGlobal("WorkerGlobalScope", WorkerGlobalScopeMock)
+  vi.stubGlobal("ServiceWorkerGlobalScope", undefined)
+  vi.stubGlobal("self", selfWorker)
+
+  const context = getRuntimeContextWebWorker()
+
+  expect(context.self).toBe(selfWorker)
+  vi.unstubAllGlobals()
+})
+
+test("useWebWorker executes worker handler", () => {
+  class WorkerGlobalScopeMock {
+    readonly internalType = "worker"
+  }
+
+  const selfWorker = new WorkerGlobalScopeMock()
+  vi.stubGlobal("WorkerGlobalScope", WorkerGlobalScopeMock)
+  vi.stubGlobal("ServiceWorkerGlobalScope", undefined)
+  vi.stubGlobal("self", selfWorker)
+  vi.stubGlobal("process", undefined)
+  vi.stubGlobal("window", undefined)
+
+  const workerResult = useWebWorker(
+    (context) => typeof context.self === "object",
+    () => false,
+  )
+
+  expect(workerResult).toBe(true)
+  vi.unstubAllGlobals()
+})
+
+test("isServiceWorker detects service worker runtime", () => {
+  class WorkerGlobalScopeMock {
+    readonly internalType = "worker"
+  }
+  class ServiceWorkerGlobalScopeMock extends WorkerGlobalScopeMock {
+    readonly internalTypeService = "service-worker"
+  }
+
+  vi.stubGlobal("WorkerGlobalScope", WorkerGlobalScopeMock)
+  vi.stubGlobal("ServiceWorkerGlobalScope", ServiceWorkerGlobalScopeMock)
+  vi.stubGlobal("self", new ServiceWorkerGlobalScopeMock())
+  vi.stubGlobal("process", undefined)
+  vi.stubGlobal("window", undefined)
+
+  expect(isServiceWorker()).toBe(true)
+  vi.unstubAllGlobals()
+})
+
+test("getServiceWorkerContext returns service worker context", () => {
+  class WorkerGlobalScopeMock {
+    readonly internalType = "worker"
+  }
+  class ServiceWorkerGlobalScopeMock extends WorkerGlobalScopeMock {
+    readonly internalTypeService = "service-worker"
+  }
+
+  const selfServiceWorker = new ServiceWorkerGlobalScopeMock()
+  vi.stubGlobal("WorkerGlobalScope", WorkerGlobalScopeMock)
+  vi.stubGlobal("ServiceWorkerGlobalScope", ServiceWorkerGlobalScopeMock)
+  vi.stubGlobal("self", selfServiceWorker)
+
+  const context = getServiceWorkerContext()
+
+  expect(context.self).toBe(selfServiceWorker)
+  vi.unstubAllGlobals()
+})
+
+test("useServiceWorker executes service worker handler", () => {
+  class WorkerGlobalScopeMock {
+    readonly internalType = "worker"
+  }
+  class ServiceWorkerGlobalScopeMock extends WorkerGlobalScopeMock {
+    readonly internalTypeService = "service-worker"
+  }
+
+  const selfServiceWorker = new ServiceWorkerGlobalScopeMock()
+  vi.stubGlobal("WorkerGlobalScope", WorkerGlobalScopeMock)
+  vi.stubGlobal("ServiceWorkerGlobalScope", ServiceWorkerGlobalScopeMock)
+  vi.stubGlobal("self", selfServiceWorker)
+  vi.stubGlobal("process", undefined)
+  vi.stubGlobal("window", undefined)
+
+  const serviceWorkerResult = useServiceWorker(
+    (context) => typeof context.self === "object",
+    () => false,
+  )
+
+  expect(serviceWorkerResult).toBe(true)
+  vi.unstubAllGlobals()
+})
+
+test("isUnknown detects non-unknown runtime in current process", () => {
+  expect(isUnknown()).toBe(false)
+})
+
+test("getRuntimeContextUnknown returns unknown context", () => {
+  const context = getRuntimeContextUnknown()
+
+  expect(context.global).toBeUndefined()
+})
+
+test("useUnknown executes fallback in current process", () => {
+  const fallbackResult = useUnknown(
+    (context) => context.global,
+    () => "fallback",
+  )
+
+  expect(fallbackResult).toBe("fallback")
+})
+
+test("getRuntimeRegistryItem returns matched runtime registry item", () => {
+  const item = getRuntimeRegistryItem()
+
+  expect(item.runtime).toBe("nodejs")
+  expect(typeof item.detect).toBe("function")
+})
+
+test("getRuntime resolves current runtime key", () => {
+  expect(getRuntime()).toBe("nodejs")
+})
+
+test("getRuntimeFlags resolves runtime detector outputs", () => {
+  const flags = getRuntimeFlags()
+
+  expect(flags.browser).toBe(false)
+  expect(flags.nodejs).toBe(true)
+  expect(flags.unknown).toBe(false)
+})
+
+test("isSatisfiesRuntime checks runtime and throws for missing", () => {
+  expect(isSatisfiesRuntime("nodejs")).toBe(true)
+  expect(() => isSatisfiesRuntime("runtime-not-found")).toThrow(
+    "is not registered",
+  )
+})
+
+test("isSatisfiesRuntimes checks runtime conditions and throws for missing", () => {
+  expect(isSatisfiesRuntimes({ nodejs: true })).toBe(true)
+  expect(isSatisfiesRuntimes({ nodejs: false })).toBe(false)
+  expect(() => isSatisfiesRuntimes({ "runtime-not-found": true })).toThrow(
+    "is not registered",
+  )
+})
+
+test("useRuntimes executes runtime specific handler, default handler, and throws without handlers", () => {
+  const nodeResult = useRuntimes({
+    nodejs: () => "node",
+    default: () => "default",
+  })
+  const defaultResult = useRuntimes({
+    browser: () => "browser",
+    default: () => "default",
+  })
+
+  expect(nodeResult).toBe("node")
+  expect(defaultResult).toBe("default")
+  expect(() => useRuntimes({ browser: () => "browser" })).toThrow(
+    "Neither runtime-specific nor default handler provided",
+  )
+})

package/tests/unit/environment/snapshot.spec.ts

@@ -0,0 +1,4 @@
+import { test } from "vitest"
+
+test.todo("getSnapshot does not need to be tested in detail")
+test.todo("printSnapshot does not need to be tested in detail")

package/tests/unit/environment/variable.spec.ts

@@ -0,0 +1,190 @@
+import { expect, test } from "vitest"
+
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+import {
+  VariableManager,
+  getVariable,
+  getVariableHost,
+  getVariableHosted,
+  loadVariable,
+  parseVariable,
+  verifyVariable,
+} from "#Source/environment/variable.ts"
+
+interface TestVariable {
+  APP_REQUIRED: string
+  APP_OPTIONAL?: string | undefined
+}
+const createSyncSchema = (): StandardSchemaV1<Record<string, string>, TestVariable> => {
+  const isRecord = (value: unknown): value is Record<string, unknown> => {
+    return typeof value === "object" && value !== null
+  }
+
+  return {
+    "~standard": {
+      version: 1 as const,
+      vendor: "mobius-variable-spec",
+      validate: (value: unknown): StandardSchemaV1.Result<TestVariable> => {
+        if (isRecord(value) === false) {
+          return {
+            issues: [{ message: "APP_REQUIRED is required" }],
+          }
+        }
+
+        const appRequired = value["APP_REQUIRED"]
+        const appOptional = value["APP_OPTIONAL"]
+
+        if (typeof appRequired !== "string") {
+          return {
+            issues: [{ message: "APP_REQUIRED is required" }],
+          }
+        }
+
+        const variable: TestVariable = {
+          APP_REQUIRED: appRequired,
+        }
+
+        if (typeof appOptional === "string") {
+          variable.APP_OPTIONAL = appOptional
+        }
+
+        return {
+          value: variable,
+        }
+      },
+    },
+  }
+}
+const createAsyncSchema = (): StandardSchemaV1<Record<string, string>, TestVariable> => {
+  return {
+    "~standard": {
+      version: 1 as const,
+      vendor: "mobius-variable-spec-async",
+      validate: async (_value: unknown): Promise<StandardSchemaV1.Result<TestVariable>> => {
+        await Promise.resolve()
+        return {
+          value: {
+            APP_REQUIRED: "ok",
+          },
+        }
+      },
+    },
+  }
+}
+
+test("parseVariable parses dotenv style content", () => {
+  const result = parseVariable({
+    variableContent: "APP_REQUIRED=enabled\nAPP_OPTIONAL=maybe\n",
+  })
+
+  expect(result["APP_REQUIRED"]).toBe("enabled")
+  expect(result["APP_OPTIONAL"]).toBe("maybe")
+})
+
+test("getVariableHost resolves runtime variable host", () => {
+  const variableHost = getVariableHost()
+
+  expect(variableHost).toBeTypeOf("object")
+})
+
+test("loadVariable loads prefixed variables and keeps inline host priority", () => {
+  const variableHost = {
+    APP_REQUIRED: "inline",
+    APP_OLD: "legacy",
+    OTHER_KEY: "ignore",
+  }
+  const result = loadVariable({
+    variable: {
+      APP_REQUIRED: "from-file",
+      APP_OPTIONAL: "file-only",
+      OTHER_KEY: "other",
+    },
+    variablePrefixs: ["APP_"],
+    variableHost,
+  })
+
+  expect(result.variableLoaded["APP_REQUIRED"]).toBe("from-file")
+  expect(result.variableLoaded["APP_OPTIONAL"]).toBe("file-only")
+  expect(result.variableLoaded["APP_OLD"]).toBe("legacy")
+  expect(result.variableLoaded["OTHER_KEY"]).toBeUndefined()
+})
+
+test("verifyVariable validates sync schema and throws on async or invalid results", () => {
+  const validSchema = createSyncSchema()
+  const validResult = verifyVariable({
+    variable: { APP_REQUIRED: "ok" },
+    variableSchema: validSchema,
+  })
+  expect(validResult.APP_REQUIRED).toBe("ok")
+
+  const invalidSchema = createSyncSchema()
+  expect(() =>
+    verifyVariable({
+      variable: { APP_OPTIONAL: "missing-required" },
+      variableSchema: invalidSchema,
+    }),
+  ).toThrow("Variable validation failed")
+
+  const asyncSchema = createAsyncSchema()
+  expect(() =>
+    verifyVariable({
+      variable: { APP_REQUIRED: "ok" },
+      variableSchema: asyncSchema,
+    }),
+  ).toThrow("expected synchronous validation")
+})
+
+test("getVariableHosted returns host variables as key-value map", () => {
+  const hosted = getVariableHosted()
+
+  expect(hosted).toBeTypeOf("object")
+})
+
+test("getVariable resolves from content path and host path", () => {
+  const schema = createSyncSchema()
+  const fromContent = getVariable({
+    variableContent: "APP_REQUIRED=file\nAPP_OPTIONAL=extra\n",
+    variablePrefixs: ["APP_"],
+    variableHost: {},
+    variableSchema: schema,
+  })
+  const fromHost = getVariable({
+    variableHost: { APP_REQUIRED: "host" },
+    variableSchema: schema,
+  })
+
+  expect(fromContent.APP_REQUIRED).toBe("file")
+  expect(fromHost.APP_REQUIRED).toBe("host")
+})
+
+test("VariableManager.getFreshVariable refreshes current variables", () => {
+  const schema = createSyncSchema()
+  const manager = new VariableManager({
+    variableHost: { APP_REQUIRED: "fresh" },
+    variableSchema: schema,
+  })
+  const freshVariable = manager.getFreshVariable()
+
+  expect(freshVariable.APP_REQUIRED).toBe("fresh")
+})
+
+test("VariableManager.getSchema returns schema instance", () => {
+  const schema = createSyncSchema()
+  const manager = new VariableManager({
+    variableHost: { APP_REQUIRED: "schema" },
+    variableSchema: schema,
+  })
+
+  expect(manager.getSchema()).toBe(schema)
+})
+
+test("VariableManager.getVariable returns cached variable snapshot", () => {
+  const schema = createSyncSchema()
+  const manager = new VariableManager({
+    variableHost: { APP_REQUIRED: "cached" },
+    variableSchema: schema,
+  })
+  const cachedVariable = manager.getVariable()
+
+  expect(cachedVariable.APP_REQUIRED).toBe("cached")
+})