@planet-matrix/mobius-model 0.5.0 → 0.9.0

package/tests/unit/tube/tube.spec.ts

@@ -0,0 +1,501 @@
+import { afterEach, expect, test, vi } from "vitest"
+
+import { Tube } from "#Source/tube/index.ts"
+
+const createTube = (options: Partial<ConstructorParameters<typeof Tube<number, string | Error>>[0]> = {}): Tube<number, string | Error> => {
+  return new Tube<number, string | Error>({
+    historyCount: 3,
+    replayHistory: false,
+    ...options,
+  })
+}
+
+const runAllTubeTasks = async (): Promise<void> => {
+  await vi.runAllTimersAsync()
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+test("Tube.safeGetLatestData returns the latest data and throws before any data arrives", async () => {
+  const tube = createTube()
+
+  expect(() => tube.safeGetLatestData()).toThrow("latestData is undefined")
+
+  await tube.pushData(1)
+  await tube.pushData(2)
+
+  expect(tube.safeGetLatestData()).toBe(2)
+})
+
+test("Tube.safeGetLatestError returns the latest error and throws before any error arrives", async () => {
+  const tube = createTube()
+
+  expect(() => tube.safeGetLatestError()).toThrow("latestError is undefined")
+
+  await tube.pushError("first")
+  await tube.pushError("second")
+
+  expect(tube.safeGetLatestError()).toBe("second")
+})
+
+test("Tube.isOpen reflects whether the tube is currently open", async () => {
+  const tube = createTube({ autoStartOnOpen: false })
+
+  expect(tube.isOpen()).toBe(false)
+
+  await tube.open()
+
+  expect(tube.isOpen()).toBe(true)
+})
+
+test("Tube.hasOpened reflects whether the tube has ever been opened", async () => {
+  const tube = createTube({ autoStartOnOpen: false })
+
+  expect(tube.hasOpened()).toBe(false)
+
+  await tube.open()
+
+  expect(tube.hasOpened()).toBe(true)
+})
+
+test("Tube.open opens only once and emits the open event", async () => {
+  vi.useFakeTimers()
+  const tube = createTube({ autoStartOnOpen: false })
+  const events: string[] = []
+
+  tube.subscribeOpenEvent({
+    subscriber: () => {
+      events.push("open")
+    },
+  })
+
+  await tube.open()
+  await tube.open()
+  await runAllTubeTasks()
+
+  expect(tube.isOpen()).toBe(true)
+  expect(events).toEqual(["open"])
+})
+
+test("Tube.isClose reflects whether the tube is currently closed", async () => {
+  const tube = createTube({ autoStartOnOpen: false })
+
+  expect(tube.isClose()).toBe(true)
+
+  await tube.open()
+
+  expect(tube.isClose()).toBe(false)
+})
+
+test("Tube.hasClosed reflects whether the tube has ever been closed", async () => {
+  const tube = createTube({ autoStartOnOpen: false, autoEndOnClose: false })
+
+  expect(tube.hasClosed()).toBe(false)
+
+  await tube.open()
+  await tube.close()
+
+  expect(tube.hasClosed()).toBe(true)
+})
+
+test("Tube.close closes only once and emits the close event", async () => {
+  vi.useFakeTimers()
+  const tube = createTube({ autoStartOnOpen: false, autoEndOnClose: false })
+  const events: string[] = []
+
+  tube.subscribeCloseEvent({
+    subscriber: () => {
+      events.push("close")
+    },
+  })
+
+  await tube.open()
+  await tube.close()
+  await tube.close()
+  await runAllTubeTasks()
+
+  expect(tube.isClose()).toBe(true)
+  expect(events).toEqual(["close"])
+})
+
+test("Tube.isStart reflects whether the tube is currently started", async () => {
+  const tube = createTube({ autoStartOnOpen: false })
+
+  expect(tube.isStart()).toBe(false)
+
+  await tube.start()
+
+  expect(tube.isStart()).toBe(true)
+})
+
+test("Tube.hasStarted reflects whether the tube has ever started", async () => {
+  const tube = createTube({ autoStartOnOpen: false })
+
+  expect(tube.hasStarted()).toBe(false)
+
+  await tube.start()
+
+  expect(tube.hasStarted()).toBe(true)
+})
+
+test("Tube.start starts only once and auto-opens when needed", async () => {
+  vi.useFakeTimers()
+  const tube = createTube({ autoStartOnOpen: false })
+  const events: string[] = []
+
+  tube.subscribeStartEvent({
+    subscriber: () => {
+      events.push("start")
+    },
+  })
+
+  await tube.start()
+  await tube.start()
+  await runAllTubeTasks()
+
+  expect(tube.isOpen()).toBe(true)
+  expect(tube.isStart()).toBe(true)
+  expect(events).toEqual(["start"])
+})
+
+test("Tube.isEnd reflects whether the tube is currently ended", async () => {
+  const tube = createTube({ autoStartOnOpen: false })
+
+  expect(tube.isEnd()).toBe(true)
+
+  await tube.start()
+
+  expect(tube.isEnd()).toBe(false)
+})
+
+test("Tube.hasEnded reflects whether the tube has ever ended", async () => {
+  const tube = createTube({ autoStartOnOpen: false, autoCloseOnEnd: false })
+
+  expect(tube.hasEnded()).toBe(false)
+
+  await tube.start()
+  await tube.end()
+
+  expect(tube.hasEnded()).toBe(true)
+})
+
+test("Tube.end ends only once and closes when configured", async () => {
+  vi.useFakeTimers()
+  const tube = createTube({ autoStartOnOpen: false })
+  const events: string[] = []
+
+  tube.subscribeEndEvent({
+    subscriber: () => {
+      events.push("end")
+    },
+  })
+
+  await tube.start()
+  await tube.end()
+  await tube.end()
+  await runAllTubeTasks()
+
+  expect(tube.isEnd()).toBe(true)
+  expect(tube.hasClosed()).toBe(true)
+  expect(events).toEqual(["end"])
+})
+
+test("Tube.isError reflects whether the tube has seen an error", async () => {
+  const tube = createTube()
+
+  expect(tube.isError()).toBe(false)
+
+  await tube.pushError("boom")
+
+  expect(tube.isError()).toBe(true)
+})
+
+test("Tube.isWet reflects whether the tube has received any data", async () => {
+  const tube = createTube()
+
+  expect(tube.isWet()).toBe(false)
+
+  await tube.pushData(1)
+
+  expect(tube.isWet()).toBe(true)
+})
+
+test("Tube.subscribeOpenEvent returns a stable unsubscribe function and delivers open notifications", async () => {
+  vi.useFakeTimers()
+  const tube = createTube({ autoStartOnOpen: false })
+  const subscriber = vi.fn<() => void>(() => undefined)
+
+  const firstUnsubscribe = tube.subscribeOpenEvent({ subscriber })
+  const secondUnsubscribe = tube.subscribeOpenEvent({ subscriber })
+
+  await tube.open()
+  await runAllTubeTasks()
+
+  expect(secondUnsubscribe).toBe(firstUnsubscribe)
+  expect(subscriber).toHaveBeenCalledTimes(1)
+})
+
+test("Tube.unsubscribeOpenEvent removes only the specified open subscriber", async () => {
+  vi.useFakeTimers()
+  const tube = createTube({ autoStartOnOpen: false })
+  const keptSubscriber = vi.fn<() => void>(() => undefined)
+  const removedSubscriber = vi.fn<() => void>(() => undefined)
+
+  tube.subscribeOpenEvent({ subscriber: keptSubscriber })
+  tube.subscribeOpenEvent({ subscriber: removedSubscriber })
+  tube.unsubscribeOpenEvent(removedSubscriber)
+
+  await tube.open()
+  await runAllTubeTasks()
+
+  expect(keptSubscriber).toHaveBeenCalledTimes(1)
+  expect(removedSubscriber).not.toHaveBeenCalled()
+})
+
+test("Tube.subscribeCloseEvent returns a stable unsubscribe function and delivers close notifications", async () => {
+  vi.useFakeTimers()
+  const tube = createTube({ autoStartOnOpen: false, autoEndOnClose: false })
+  const subscriber = vi.fn<() => void>(() => undefined)
+
+  const firstUnsubscribe = tube.subscribeCloseEvent({ subscriber })
+  const secondUnsubscribe = tube.subscribeCloseEvent({ subscriber })
+
+  await tube.open()
+  await tube.close()
+  await runAllTubeTasks()
+
+  expect(secondUnsubscribe).toBe(firstUnsubscribe)
+  expect(subscriber).toHaveBeenCalledTimes(1)
+})
+
+test("Tube.unsubscribeCloseEvent removes only the specified close subscriber", async () => {
+  vi.useFakeTimers()
+  const tube = createTube({ autoStartOnOpen: false, autoEndOnClose: false })
+  const keptSubscriber = vi.fn<() => void>(() => undefined)
+  const removedSubscriber = vi.fn<() => void>(() => undefined)
+
+  tube.subscribeCloseEvent({ subscriber: keptSubscriber })
+  tube.subscribeCloseEvent({ subscriber: removedSubscriber })
+  tube.unsubscribeCloseEvent(removedSubscriber)
+
+  await tube.open()
+  await tube.close()
+  await runAllTubeTasks()
+
+  expect(keptSubscriber).toHaveBeenCalledTimes(1)
+  expect(removedSubscriber).not.toHaveBeenCalled()
+})
+
+test("Tube.subscribeStartEvent returns a stable unsubscribe function and delivers start notifications", async () => {
+  vi.useFakeTimers()
+  const tube = createTube({ autoStartOnOpen: false })
+  const subscriber = vi.fn<() => void>(() => undefined)
+
+  const firstUnsubscribe = tube.subscribeStartEvent({ subscriber })
+  const secondUnsubscribe = tube.subscribeStartEvent({ subscriber })
+
+  await tube.start()
+  await runAllTubeTasks()
+
+  expect(secondUnsubscribe).toBe(firstUnsubscribe)
+  expect(subscriber).toHaveBeenCalledTimes(1)
+})
+
+test("Tube.unsubscribeStartEvent removes only the specified start subscriber", async () => {
+  vi.useFakeTimers()
+  const tube = createTube({ autoStartOnOpen: false })
+  const keptSubscriber = vi.fn<() => void>(() => undefined)
+  const removedSubscriber = vi.fn<() => void>(() => undefined)
+
+  tube.subscribeStartEvent({ subscriber: keptSubscriber })
+  tube.subscribeStartEvent({ subscriber: removedSubscriber })
+  tube.unsubscribeStartEvent(removedSubscriber)
+
+  await tube.start()
+  await runAllTubeTasks()
+
+  expect(keptSubscriber).toHaveBeenCalledTimes(1)
+  expect(removedSubscriber).not.toHaveBeenCalled()
+})
+
+test("Tube.subscribeEndEvent returns a stable unsubscribe function and delivers end notifications", async () => {
+  vi.useFakeTimers()
+  const tube = createTube({ autoStartOnOpen: false, autoCloseOnEnd: false })
+  const subscriber = vi.fn<() => void>(() => undefined)
+
+  const firstUnsubscribe = tube.subscribeEndEvent({ subscriber })
+  const secondUnsubscribe = tube.subscribeEndEvent({ subscriber })
+
+  await tube.start()
+  await tube.end()
+  await runAllTubeTasks()
+
+  expect(secondUnsubscribe).toBe(firstUnsubscribe)
+  expect(subscriber).toHaveBeenCalledTimes(1)
+})
+
+test("Tube.unsubscribeEndEvent removes only the specified end subscriber", async () => {
+  vi.useFakeTimers()
+  const tube = createTube({ autoStartOnOpen: false, autoCloseOnEnd: false })
+  const keptSubscriber = vi.fn<() => void>(() => undefined)
+  const removedSubscriber = vi.fn<() => void>(() => undefined)
+
+  tube.subscribeEndEvent({ subscriber: keptSubscriber })
+  tube.subscribeEndEvent({ subscriber: removedSubscriber })
+  tube.unsubscribeEndEvent(removedSubscriber)
+
+  await tube.start()
+  await tube.end()
+  await runAllTubeTasks()
+
+  expect(keptSubscriber).toHaveBeenCalledTimes(1)
+  expect(removedSubscriber).not.toHaveBeenCalled()
+})
+
+test("Tube.subscribeWetEvent returns a stable unsubscribe function and delivers the first wet notification", async () => {
+  vi.useFakeTimers()
+  const tube = createTube()
+  const subscriber = vi.fn<() => void>(() => undefined)
+
+  const firstUnsubscribe = tube.subscribeWetEvent({ subscriber })
+  const secondUnsubscribe = tube.subscribeWetEvent({ subscriber })
+
+  await tube.pushData(1)
+  await tube.pushData(2)
+  await runAllTubeTasks()
+
+  expect(secondUnsubscribe).toBe(firstUnsubscribe)
+  expect(subscriber).toHaveBeenCalledTimes(1)
+})
+
+test("Tube.unsubscribeWetEvent removes only the specified wet subscriber", async () => {
+  vi.useFakeTimers()
+  const tube = createTube()
+  const keptSubscriber = vi.fn<() => void>(() => undefined)
+  const removedSubscriber = vi.fn<() => void>(() => undefined)
+
+  tube.subscribeWetEvent({ subscriber: keptSubscriber })
+  tube.subscribeWetEvent({ subscriber: removedSubscriber })
+  tube.unsubscribeWetEvent(removedSubscriber)
+
+  await tube.pushData(1)
+  await runAllTubeTasks()
+
+  expect(keptSubscriber).toHaveBeenCalledTimes(1)
+  expect(removedSubscriber).not.toHaveBeenCalled()
+})
+
+test("Tube.pushError records the error, opens the tube when needed and emits error notifications", async () => {
+  vi.useFakeTimers()
+  const tube = createTube({ autoEndOnError: false, autoCloseOnError: false })
+  const errors: Array<string | Error> = []
+
+  tube.subscribeErrorEvent({
+    subscriber: (error) => {
+      errors.push(error)
+    },
+  })
+
+  await tube.pushError("boom")
+  await runAllTubeTasks()
+
+  expect(tube.isOpen()).toBe(true)
+  expect(tube.isError()).toBe(true)
+  expect(errors).toEqual(["boom"])
+})
+
+test("Tube.subscribeErrorEvent returns a stable unsubscribe function and delivers error notifications", async () => {
+  vi.useFakeTimers()
+  const tube = createTube({ autoEndOnError: false, autoCloseOnError: false })
+  const subscriber = vi.fn<(error: string | Error) => void>(() => undefined)
+
+  const firstUnsubscribe = tube.subscribeErrorEvent({ subscriber })
+  const secondUnsubscribe = tube.subscribeErrorEvent({ subscriber })
+
+  await tube.pushError("boom")
+  await runAllTubeTasks()
+
+  expect(secondUnsubscribe).toBe(firstUnsubscribe)
+  expect(subscriber).toHaveBeenCalledTimes(1)
+  expect(subscriber).toHaveBeenCalledWith("boom")
+})
+
+test("Tube.unsubscribeErrorEvent removes only the specified error subscriber", async () => {
+  vi.useFakeTimers()
+  const tube = createTube({ autoEndOnError: false, autoCloseOnError: false })
+  const keptSubscriber = vi.fn<(error: string | Error) => void>(() => undefined)
+  const removedSubscriber = vi.fn<(error: string | Error) => void>(() => undefined)
+
+  tube.subscribeErrorEvent({ subscriber: keptSubscriber })
+  tube.subscribeErrorEvent({ subscriber: removedSubscriber })
+  tube.unsubscribeErrorEvent(removedSubscriber)
+
+  await tube.pushError("boom")
+  await runAllTubeTasks()
+
+  expect(keptSubscriber).toHaveBeenCalledTimes(1)
+  expect(removedSubscriber).not.toHaveBeenCalled()
+})
+
+test("Tube.pushData records data, auto-starts the tube and trims history by historyCount", async () => {
+  vi.useFakeTimers()
+  const tube = createTube({ historyCount: 1 })
+  const values: number[] = []
+
+  tube.subscribeData({
+    subscriber: (value) => {
+      values.push(value)
+    },
+  })
+
+  await tube.pushData(1)
+  await tube.pushData(2)
+  await runAllTubeTasks()
+
+  expect(tube.isOpen()).toBe(true)
+  expect(tube.isStart()).toBe(true)
+  expect(tube.isWet()).toBe(true)
+  expect(tube.safeGetLatestData()).toBe(2)
+  expect(values).toEqual([1, 2])
+})
+
+test("Tube.subscribeData returns a stable unsubscribe function and can replay history", async () => {
+  vi.useFakeTimers()
+  const tube = createTube()
+  const values: number[] = []
+  const subscriber = vi.fn<(value: number) => void>((value) => {
+    values.push(value)
+  })
+
+  await tube.pushData(1)
+  await tube.pushData(2)
+
+  const firstUnsubscribe = tube.subscribeData({ subscriber, replayHistory: true })
+  const secondUnsubscribe = tube.subscribeData({ subscriber, replayHistory: true })
+
+  await tube.pushData(3)
+  await runAllTubeTasks()
+
+  expect(secondUnsubscribe).toBe(firstUnsubscribe)
+  expect(values).toEqual([1, 2, 3])
+  expect(subscriber).toHaveBeenCalledTimes(3)
+})
+
+test("Tube.unsubscribeData removes only the specified data subscriber", async () => {
+  vi.useFakeTimers()
+  const tube = createTube()
+  const keptSubscriber = vi.fn<(value: number) => void>(() => undefined)
+  const removedSubscriber = vi.fn<(value: number) => void>(() => undefined)
+
+  tube.subscribeData({ subscriber: keptSubscriber })
+  tube.subscribeData({ subscriber: removedSubscriber })
+  tube.unsubscribeData(removedSubscriber)
+
+  await tube.pushData(1)
+  await runAllTubeTasks()
+
+  expect(keptSubscriber).toHaveBeenCalledTimes(1)
+  expect(removedSubscriber).not.toHaveBeenCalled()
+})

package/.oxlintrc.json

@@ -1,5 +0,0 @@
-{
-  "extends": [
-    "./node_modules/@planet-matrix/mobius-mono/src/internals/lint/oxlintrc.json"
-  ],
-}

package/src/random/uuid.ts

@@ -1,103 +0,0 @@
-
-const internalUUID_REGEXP = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
-/**
- * Check whether input is a valid UUID string.
- *
- * @example
- * ```
- * // Expect: true
- * const example1 = isUuid("550e8400-e29b-41d4-a716-446655440000")
- * // Expect: false
- * const example2 = isUuid("not-a-uuid")
- * ```
- */
-export const isUuid = (input: string): boolean => {
-  return internalUUID_REGEXP.test(input)
-}
-
-/**
- * Assert input is a valid UUID string.
- *
- * @example
- * ```
- * // Expect: no throw
- * const example1 = assertUuid("550e8400-e29b-41d4-a716-446655440000")
- * // Expect: throws TypeError
- * const example2 = () => assertUuid("not-a-uuid")
- * ```
- *
- * @throws {TypeError} when input is not a valid UUID
- */
-export const assertUuid = (input: string): void => {
-  if (isUuid(input) === false) {
-    throw new TypeError(`Expected a valid UUID string, got: ${input}`)
-  }
-}
-
-/**
- * Get the version number from a valid UUID string.
- *
- * @example
- * ```
- * // Expect: 4
- * const example1 = getUuidVersion("550e8400-e29b-41d4-a716-446655440000")
- * // Expect: 1
- * const example2 = getUuidVersion("123e4567-e89b-12d3-a456-426614174000")
- * ```
- *
- * @throws {TypeError} when input is not a valid UUID
- */
-export const getUuidVersion = (input: string): number => {
-  // 1) Ensure the input is a syntactically valid UUID string.
-  //    If invalid, assertUuid throws TypeError and prevents unsafe parsing.
-  assertUuid(input)
-
-  // 2) Per UUID canonical format xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx,
-  //    the version nibble is the first hex digit of the 3rd group.
-  //    In a 36-char UUID string, that position is index 14.
-
-  // 3) Convert the single hex character (for example "4") to a base-10 number.
-  //    parseInt("4", 16) -> 4, parseInt("a", 16) -> 10.
-  return Number.parseInt(input[14]!, 16)
-}
-
-/**
- * Generate a RFC 4122 version-4 UUID string.
- *
- * @example
- * ```
- * const example1 = generateUuid()
- * // Expect: true
- * const example2 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(example1)
- * ```
- */
-export const generateUuid = (): string => {
-  if (typeof crypto === "object") {
-    if (typeof crypto.randomUUID === "function") {
-      return crypto.randomUUID()
-    }
-
-    if (typeof crypto.getRandomValues === "function" && typeof Uint8Array === "function") {
-      const buffer = new Uint8Array(16)
-      crypto.getRandomValues(buffer)
-
-      // Per RFC 4122, set bits for version and `clock_seq_hi_and_reserved`
-      buffer[6] = (buffer[6]! & 0x0F) | 0x40 // version 4
-      buffer[8] = (buffer[8]! & 0x3F) | 0x80 // variant 1
-
-      // Convert buffer to UUID string format
-      const hex = [...buffer].map(b => b.toString(16).padStart(2, "0")).join("")
-      return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
-    }
-  }
-
-  // Fallback for environments without crypto support
-  const fallbackUUID = (): string => {
-    const random = (a: number): string => {
-      return ((a ^ ((Math.random() * 16) >> (a / 4))) & 15).toString(16)
-    }
-    return "10000000-1000-4000-8000-100000000000".replaceAll(/[018]/g, (char: string) => random(Number(char)))
-  }
-
-  return fallbackUUID()
-}

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

@@ -1,37 +0,0 @@
-import { expect, test } from "vitest"
-
-import { assertUuid, generateUuid, getUuidVersion, isUuid } from "#Source/random/index.ts"
-
-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 = generateUuid()
-  const value2 = generateUuid()
-
-  expect(value1).toMatch(UUID_V4_REGEXP)
-  expect(value2).toMatch(UUID_V4_REGEXP)
-  expect(value1).not.toBe(value2)
-})