@planet-matrix/mobius-model 0.6.0 → 0.9.0

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/form/inputor-controller/base.spec.ts

@@ -0,0 +1,458 @@
+import { expect, test, vi } from "vitest"
+
+import type {
+  BaseInputorContext,
+  BaseInputorControllerOptions,
+  BaseInputorSchema,
+} from "#Source/form/index.ts"
+import { BaseInputorController } from "#Source/form/index.ts"
+
+const TEST_INPUTOR_TYPE_NAME = "test" as const
+
+type TestExternalValue = string | undefined
+type TestInternalValue = string | undefined
+
+interface TestInputorSchema extends BaseInputorSchema<TestExternalValue> {
+  inputorTypeName: typeof TEST_INPUTOR_TYPE_NAME
+}
+
+interface TestInputorContext extends BaseInputorContext<TestExternalValue, TestInternalValue> {
+}
+
+interface TestInputorControllerOptions extends BaseInputorControllerOptions<TestExternalValue, TestInputorSchema> {
+}
+
+class TestInputorController extends BaseInputorController<
+  TestExternalValue,
+  TestInternalValue,
+  TestInputorSchema,
+  TestInputorContext
+> {
+  declare schemaType: TestInputorSchema
+  declare optionsType: TestInputorControllerOptions
+  declare constructorType: typeof TestInputorController
+
+  static inputorTypeName = TEST_INPUTOR_TYPE_NAME
+
+  inputorTypeName = TEST_INPUTOR_TYPE_NAME
+  protected voidExternalValue = undefined
+  protected voidInternalValue = undefined
+
+  protected override async constrainExternalValue(value: TestExternalValue): Promise<TestExternalValue> {
+    if (value === undefined) {
+      return await Promise.resolve(undefined)
+    }
+    return await Promise.resolve(value.trim())
+  }
+
+  protected override async constrainInternalValue(value: TestInternalValue): Promise<TestInternalValue> {
+    if (value === undefined) {
+      return await Promise.resolve(undefined)
+    }
+    return await Promise.resolve(value.trim())
+  }
+}
+
+const createTestInputor = (
+  overrides: Partial<TestInputorControllerOptions> = {},
+): TestInputorController => {
+  return new TestInputorController({
+    id: "test-id",
+    name: "test-name",
+    placeholder: "test-placeholder",
+    value: " initial ",
+    ...overrides,
+  })
+}
+
+test("BaseInputorController.isReady and waitForReady initialize defaults and emit initial hooks", async () => {
+  const valueChanges: Array<{ newValue: TestExternalValue; oldValue: TestExternalValue }> = []
+  const schemaChanges: Array<{ newSchema: TestInputorSchema; oldSchema: TestInputorSchema }> = []
+  const controller = createTestInputor({
+    onValueChange: (context) => {
+      valueChanges.push(context)
+    },
+    onSchemaChange: (context) => {
+      schemaChanges.push(context)
+    },
+  })
+
+  expect(controller.isReady()).toBe(false)
+
+  await controller.waitForReady()
+
+  expect(controller.isReady()).toBe(true)
+  expect(await controller.getSchema()).toEqual({
+    inputorTypeName: TEST_INPUTOR_TYPE_NAME,
+    id: "test-id",
+    name: "test-name",
+    placeholder: "test-placeholder",
+    value: "initial",
+    isVoid: false,
+    isFocused: false,
+    isTouched: false,
+    isDirty: false,
+    isDisabled: false,
+    isDebugMode: false,
+  })
+  expect(valueChanges).toEqual([
+    {
+      newValue: "initial",
+      oldValue: "initial",
+    },
+  ])
+  expect(schemaChanges).toHaveLength(1)
+  expect(schemaChanges[0]!.newSchema).toEqual(schemaChanges[0]!.oldSchema)
+  expect(schemaChanges[0]!.newSchema.value).toBe("initial")
+})
+
+test("BaseInputorController.getInternalValue, getContext, and isEqualSchema expose current state", async () => {
+  const controller = createTestInputor({
+    value: " alpha ",
+  })
+
+  await controller.waitForReady()
+
+  expect(controller.getInternalValue()).toBe("alpha")
+  expect(await controller.getContext()).toEqual({
+    inputorTypeName: TEST_INPUTOR_TYPE_NAME,
+    id: "test-id",
+    name: "test-name",
+    placeholder: "test-placeholder",
+    value: "alpha",
+    isVoid: false,
+    isFocused: false,
+    isTouched: false,
+    isDirty: false,
+    isDisabled: false,
+    isDebugMode: false,
+    internalValue: "alpha",
+    isReady: true,
+  })
+  expect(await controller.isEqualSchema({ value: "alpha", placeholder: "test-placeholder" })).toBe(true)
+  expect(await controller.isEqualSchema({ value: "beta" })).toBe(false)
+  expect(await controller.isEqualSchema(null)).toBe(false)
+})
+
+test("BaseInputorController.subscribeInputChange and updateInputValue emit input updates after debounce", async () => {
+  vi.useFakeTimers()
+
+  try {
+    const controller = createTestInputor({
+      value: "start",
+      inputDebounce: 20,
+    })
+    const inputChanges: Array<{ newInput: TestExternalValue; oldInput: TestExternalValue; oldValue: TestExternalValue }> = []
+
+    await controller.waitForReady()
+    controller.subscribeInputChange((context) => {
+      inputChanges.push(context)
+    })
+
+    await controller.updateInputValue(" next ")
+
+    expect(inputChanges).toEqual([])
+
+    await vi.advanceTimersByTimeAsync(20)
+
+    expect(inputChanges).toEqual([
+      {
+        newInput: " next ",
+        oldInput: "start",
+        oldValue: "start",
+      },
+    ])
+  }
+  finally {
+    vi.useRealTimers()
+  }
+})
+
+test("BaseInputorController.unsubscribeInputChange removes one input subscriber", async () => {
+  vi.useFakeTimers()
+
+  try {
+    const controller = createTestInputor({ value: "start" })
+    let calls = 0
+    const subscriber = (): void => {
+      calls = calls + 1
+    }
+
+    await controller.waitForReady()
+    controller.subscribeInputChange(subscriber)
+    controller.unsubscribeInputChange(subscriber)
+
+    await controller.updateInputValue("next")
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(calls).toBe(0)
+  }
+  finally {
+    vi.useRealTimers()
+  }
+})
+
+test("BaseInputorController.clearInputChangeSubscribers removes all input subscribers", async () => {
+  vi.useFakeTimers()
+
+  try {
+    const controller = createTestInputor({ value: "start" })
+    let calls = 0
+
+    await controller.waitForReady()
+    controller.subscribeInputChange(() => {
+      calls = calls + 1
+    })
+    controller.subscribeInputChange(() => {
+      calls = calls + 1
+    })
+    controller.clearInputChangeSubscribers()
+
+    await controller.updateInputValue("next")
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(calls).toBe(0)
+  }
+  finally {
+    vi.useRealTimers()
+  }
+})
+
+test("BaseInputorController.subscribeValueChange, applyInputValue, and updateValue emit value changes", async () => {
+  const controller = createTestInputor({ value: "start" })
+  const valueChanges: Array<{ newValue: TestExternalValue; oldValue: TestExternalValue }> = []
+
+  await controller.waitForReady()
+  controller.subscribeValueChange((context) => {
+    valueChanges.push(context)
+  })
+
+  await controller.updateInputValue(" next ")
+  await controller.applyInputValue()
+  await controller.updateValue(" final ")
+
+  expect(valueChanges).toEqual([
+    {
+      newValue: "next",
+      oldValue: "start",
+    },
+    {
+      newValue: "final",
+      oldValue: "next",
+    },
+  ])
+})
+
+test("BaseInputorController.unsubscribeValueChange removes one value subscriber", async () => {
+  const controller = createTestInputor({ value: "start" })
+  let calls = 0
+  const subscriber = (): void => {
+    calls = calls + 1
+  }
+
+  await controller.waitForReady()
+  controller.subscribeValueChange(subscriber)
+  controller.unsubscribeValueChange(subscriber)
+  await controller.updateValue("next")
+
+  expect(calls).toBe(0)
+})
+
+test("BaseInputorController.clearValueChangeSubscribers removes all value subscribers", async () => {
+  const controller = createTestInputor({ value: "start" })
+  let calls = 0
+
+  await controller.waitForReady()
+  controller.subscribeValueChange(() => {
+    calls = calls + 1
+  })
+  controller.subscribeValueChange(() => {
+    calls = calls + 1
+  })
+  controller.clearValueChangeSubscribers()
+  await controller.updateValue("next")
+
+  expect(calls).toBe(0)
+})
+
+test("BaseInputorController.subscribeSchemaChange and updatePlaceholder emit schema changes", async () => {
+  const controller = createTestInputor({ value: "start" })
+  const schemaChanges: Array<{ newSchema: TestInputorSchema; oldSchema: TestInputorSchema }> = []
+
+  await controller.waitForReady()
+  await Promise.resolve()
+  controller.subscribeSchemaChange((context) => {
+    schemaChanges.push(context)
+  })
+  await controller.updatePlaceholder("next-placeholder")
+
+  expect(schemaChanges.length).toBeGreaterThanOrEqual(1)
+  expect(schemaChanges.at(-1)!.oldSchema.placeholder).toBe("test-placeholder")
+  expect(schemaChanges.at(-1)!.newSchema.placeholder).toBe("next-placeholder")
+})
+
+test("BaseInputorController.unsubscribeSchemaChange removes one schema subscriber", async () => {
+  const controller = createTestInputor({ value: "start" })
+  let calls = 0
+  const subscriber = (): void => {
+    calls = calls + 1
+  }
+
+  await controller.waitForReady()
+  controller.subscribeSchemaChange(subscriber)
+  controller.unsubscribeSchemaChange(subscriber)
+  await controller.updatePlaceholder("next-placeholder")
+
+  expect(calls).toBe(0)
+})
+
+test("BaseInputorController.clearSchemaChangeSubscribers removes all schema subscribers", async () => {
+  const controller = createTestInputor({ value: "start" })
+  let calls = 0
+
+  await controller.waitForReady()
+  controller.subscribeSchemaChange(() => {
+    calls = calls + 1
+  })
+  controller.subscribeSchemaChange(() => {
+    calls = calls + 1
+  })
+  controller.clearSchemaChangeSubscribers()
+  await controller.updatePlaceholder("next-placeholder")
+
+  expect(calls).toBe(0)
+})
+
+test("BaseInputorController.updateIsVoid resets the value to its void value", async () => {
+  const controller = createTestInputor({ value: "start" })
+
+  await controller.waitForReady()
+  await controller.updateIsVoid(true)
+
+  expect(await controller.getSchema()).toMatchObject({
+    value: undefined,
+    isVoid: true,
+    isDirty: true,
+  })
+})
+
+test("BaseInputorController.updateIsFocused also marks the controller as touched", async () => {
+  const controller = createTestInputor({ value: "start" })
+
+  await controller.waitForReady()
+  await controller.updateIsFocused(true)
+
+  expect(await controller.getSchema()).toMatchObject({
+    isFocused: true,
+    isTouched: true,
+  })
+})
+
+test("BaseInputorController.updateIsTouched updates touched state directly", async () => {
+  const controller = createTestInputor({ value: "start" })
+
+  await controller.waitForReady()
+  await controller.updateIsTouched(true)
+
+  expect(await controller.getSchema()).toMatchObject({
+    isTouched: true,
+  })
+})
+
+test("BaseInputorController.updateIsDirty updates dirty state directly", async () => {
+  const controller = createTestInputor({ value: "start" })
+
+  await controller.waitForReady()
+  await controller.updateIsDirty(true)
+
+  expect(await controller.getSchema()).toMatchObject({
+    isDirty: true,
+  })
+})
+
+test("BaseInputorController.updateIsDisabled updates disabled state directly", async () => {
+  const controller = createTestInputor({ value: "start" })
+
+  await controller.waitForReady()
+  await controller.updateIsDisabled(true)
+
+  expect(await controller.getSchema()).toMatchObject({
+    isDisabled: true,
+  })
+})
+
+test("BaseInputorController.updateIsDebugMode updates debug mode directly", async () => {
+  const controller = createTestInputor({ value: "start" })
+
+  await controller.waitForReady()
+  await controller.updateIsDebugMode(true)
+
+  expect(await controller.getSchema()).toMatchObject({
+    isDebugMode: true,
+  })
+})
+
+test("BaseInputorController.updateSchema applies multiple schema fields in one pass", async () => {
+  const controller = createTestInputor({ value: "start" })
+
+  await controller.waitForReady()
+  await controller.updateSchema({
+    ...(await controller.getSchema()),
+    placeholder: "schema-placeholder",
+    value: " schema-value ",
+    isFocused: true,
+    isTouched: true,
+    isDirty: true,
+    isDisabled: true,
+    isDebugMode: true,
+  })
+
+  expect(await controller.getSchema()).toEqual({
+    inputorTypeName: TEST_INPUTOR_TYPE_NAME,
+    id: "test-id",
+    name: "test-name",
+    placeholder: "schema-placeholder",
+    value: "schema-value",
+    isVoid: false,
+    isFocused: true,
+    isTouched: true,
+    isDirty: true,
+    isDisabled: true,
+    isDebugMode: true,
+  })
+})
+
+test("BaseInputorController.destroy clears every subscriber collection", async () => {
+  vi.useFakeTimers()
+
+  try {
+    const controller = createTestInputor({ value: "start" })
+    let inputCalls = 0
+    let valueCalls = 0
+    let schemaCalls = 0
+
+    await controller.waitForReady()
+    controller.subscribeInputChange(() => {
+      inputCalls = inputCalls + 1
+    })
+    controller.subscribeValueChange(() => {
+      valueCalls = valueCalls + 1
+    })
+    controller.subscribeSchemaChange(() => {
+      schemaCalls = schemaCalls + 1
+    })
+    controller.destroy()
+
+    await controller.updateInputValue("next")
+    await vi.advanceTimersByTimeAsync(0)
+    await controller.updateValue("final")
+    await controller.updatePlaceholder("after-destroy")
+
+    expect(inputCalls).toBe(0)
+    expect(valueCalls).toBe(0)
+    expect(schemaCalls).toBe(0)
+  }
+  finally {
+    vi.useRealTimers()
+  }
+})

package/tests/unit/form/inputor-controller/boolean.spec.ts

@@ -0,0 +1,30 @@
+import { expect, test } from "vitest"
+
+import {
+  BOOLEAN_INPUTOR_TYPE_NAME,
+  BooleanInputorController,
+} from "#Source/form/index.ts"
+
+test("BooleanInputorController.getSchema exposes boolean schema state and updateValue toggles it", async () => {
+  const controller = new BooleanInputorController({
+    id: "boolean-id",
+    value: false,
+  })
+
+  await controller.waitForReady()
+  await controller.updateValue(true)
+
+  expect(await controller.getSchema()).toEqual({
+    inputorTypeName: BOOLEAN_INPUTOR_TYPE_NAME,
+    id: "boolean-id",
+    name: `boolean-boolean-id`,
+    placeholder: "",
+    value: true,
+    isVoid: false,
+    isFocused: false,
+    isTouched: false,
+    isDirty: true,
+    isDisabled: false,
+    isDebugMode: false,
+  })
+})

package/tests/unit/form/inputor-controller/file.spec.ts

@@ -0,0 +1,27 @@
+import { expect, test } from "vitest"
+
+import {
+  FILE_INPUTOR_TYPE_NAME,
+  FileInputorController,
+} from "#Source/form/index.ts"
+
+test("FileInputorController.getSchema stores file values and reports file metadata", async () => {
+  const file = new File(["alpha"], "alpha.txt", {
+    type: "text/plain",
+  })
+  const controller = new FileInputorController({
+    id: "file-id",
+    value: file,
+  })
+
+  await controller.waitForReady()
+
+  const schema = await controller.getSchema()
+
+  expect(schema.inputorTypeName).toBe(FILE_INPUTOR_TYPE_NAME)
+  expect(schema.id).toBe("file-id")
+  expect(schema.name).toBe("file-file-id")
+  expect(schema.value?.name).toBe("alpha.txt")
+  expect(schema.value?.type).toBe("text/plain")
+  expect(schema.isDirty).toBe(false)
+})