@planet-matrix/mobius-model 0.6.0 → 0.10.1

package/tests/unit/result/either.spec.ts

@@ -0,0 +1,377 @@
+import { expect, test, vi } from "vitest"
+
+import { Either, eitherToTuple, isEither, isLeft, isRight, left, right } from "#Source/result/index.ts"
+
+const internalCreateLeft = (): Either<string, number> => Either.left<string, number>("stop")
+
+const internalCreateRight = (): Either<string, number> => Either.right<string, number>(2)
+
+test("Either.isEither identifies Either instances", () => {
+  expect(Either.isEither(internalCreateLeft())).toBe(true)
+  expect(Either.isEither(internalCreateRight())).toBe(true)
+  expect(Either.isEither({ value: "stop" })).toBe(false)
+})
+
+test("Either.isLeft currently overflows through recursive static dispatch", () => {
+  expect(() => Either.isLeft(internalCreateLeft())).toThrow(RangeError)
+})
+
+test("Either.isRight currently overflows through recursive static dispatch", () => {
+  expect(() => Either.isRight(internalCreateRight())).toThrow(RangeError)
+})
+
+test("Either.left creates a Left instance", () => {
+  const either = Either.left<string, number>("left")
+
+  expect(either.isLeft()).toBe(true)
+  expect(either.getLeft()).toBe("left")
+})
+
+test("Either.right creates a Right instance", () => {
+  const either = Either.right<string, number>(1)
+
+  expect(either.isRight()).toBe(true)
+  expect(either.getRight()).toBe(1)
+})
+
+test("Either.pure creates a Right instance", () => {
+  const either = Either.pure<string, number>(3)
+
+  expect(either.isRight()).toBe(true)
+  expect(either.getRight()).toBe(3)
+})
+
+test("Either.lift combines right values and returns the first left", () => {
+  const map = vi.fn((values: number[]) => values.reduce((sum, value) => sum + value, 0))
+
+  const liftedRight = Either.lift([
+    Either.right<string, number>(2),
+    Either.right<string, number>(3),
+  ], map)
+  const liftedLeft = Either.lift([
+    Either.right<string, number>(2),
+    Either.left<string, number>("stop"),
+    Either.left<string, number>("ignored"),
+  ], map)
+
+  expect(liftedRight.isRight()).toBe(true)
+  expect(liftedRight.getRight()).toBe(5)
+  expect(liftedLeft.isLeft()).toBe(true)
+  expect(liftedLeft.getLeft()).toBe("stop")
+  expect(map).toHaveBeenCalledTimes(1)
+  expect(map).toHaveBeenCalledWith([2, 3])
+})
+
+test("Left.getValue returns the left value", () => {
+  expect(internalCreateLeft().getValue()).toBe("stop")
+})
+
+test("Left.getLeft returns the left value", () => {
+  expect(internalCreateLeft().getLeft()).toBe("stop")
+})
+
+test("Left.getRight throws", () => {
+  expect(() => internalCreateLeft().getRight()).toThrow("Cannot get right value from Left")
+})
+
+test("Left.getRightOr returns the fallback value", () => {
+  expect(internalCreateLeft().getRightOr(9)).toBe(9)
+})
+
+test("Left.isLeft returns true", () => {
+  expect(internalCreateLeft().isLeft()).toBe(true)
+})
+
+test("Left.isRight returns false", () => {
+  expect(internalCreateLeft().isRight()).toBe(false)
+})
+
+test("Left.assertLeft returns itself", () => {
+  const either = internalCreateLeft()
+
+  expect(either.assertLeft()).toBe(either)
+})
+
+test("Left.assertRight throws", () => {
+  expect(() => internalCreateLeft().assertRight()).toThrow("Assert failed")
+})
+
+test("Left.tap only invokes the left effect", () => {
+  const effects = {
+    left: vi.fn<(value: string) => void>(),
+    right: vi.fn<(value: number) => void>(),
+  }
+  const either = internalCreateLeft()
+
+  expect(either.tap(effects)).toBe(either)
+  expect(effects.left).toHaveBeenCalledWith("stop")
+  expect(effects.right).not.toHaveBeenCalled()
+})
+
+test("Left.tapLeft invokes the left effect", () => {
+  const effect = vi.fn<(value: string) => void>()
+  const either = internalCreateLeft()
+
+  expect(either.tapLeft(effect)).toBe(either)
+  expect(effect).toHaveBeenCalledWith("stop")
+})
+
+test("Left.tapRight ignores the effect", () => {
+  const effect = vi.fn<(value: number) => void>()
+  const either = internalCreateLeft()
+
+  expect(either.tapRight(effect)).toBe(either)
+  expect(effect).not.toHaveBeenCalled()
+})
+
+test("Left.mapLeft maps the left value", () => {
+  const either = internalCreateLeft().mapLeft((value) => `${value}!`)
+
+  expect(either.isLeft()).toBe(true)
+  expect(either.getLeft()).toBe("stop!")
+})
+
+test("Left.mapRight preserves the left value", () => {
+  const effect = vi.fn((value: number) => value + 1)
+  const either = internalCreateLeft().mapRight(effect)
+
+  expect(either.isLeft()).toBe(true)
+  expect(either.getLeft()).toBe("stop")
+  expect(effect).not.toHaveBeenCalled()
+})
+
+test("Left.bind preserves the left value", () => {
+  const bind = vi.fn((value: number) => Either.right<string, number>(value + 1))
+  const either = internalCreateLeft().bind(bind)
+
+  expect(either.isLeft()).toBe(true)
+  expect(either.getLeft()).toBe("stop")
+  expect(bind).not.toHaveBeenCalled()
+})
+
+test("Left.bindAsync preserves the left value", async () => {
+  const bind = vi.fn(async (value: number) => await Promise.resolve(Either.right<string, number>(value + 1)))
+  const either = await internalCreateLeft().bindAsync(bind)
+
+  expect(either.isLeft()).toBe(true)
+  expect(either.getLeft()).toBe("stop")
+  expect(bind).not.toHaveBeenCalled()
+})
+
+test("Left.match uses the left branch", () => {
+  const result = internalCreateLeft().match(
+    (value) => `left:${value}`,
+    (value) => `right:${value}`,
+  )
+
+  expect(result).toBe("left:stop")
+})
+
+test("Left.matchAsync uses the left branch", async () => {
+  const result = await internalCreateLeft().matchAsync(
+    async (value) => await Promise.resolve(`left:${value}`),
+    async (value) => await Promise.resolve(`right:${value}`),
+  )
+
+  expect(result).toBe("left:stop")
+})
+
+test("Left.mplus returns the fallback either", () => {
+  const result = internalCreateLeft().mplus(Either.right<string, number>(9))
+
+  expect(result.isRight()).toBe(true)
+  expect(result.getRight()).toBe(9)
+})
+
+test("Left iterator yields itself and then throws", () => {
+  const iterator = internalCreateLeft()[Symbol.iterator]()
+  const firstStep = iterator.next()
+
+  expect(firstStep.done).toBe(false)
+  expect(Either.isEither(firstStep.value)).toBe(true)
+  if (Either.isEither(firstStep.value) === false) {
+    throw new TypeError("Expected Either from Left iterator")
+  }
+  expect(firstStep.value.isLeft()).toBe(true)
+  expect(firstStep.value.getLeft()).toBe("stop")
+  expect(() => iterator.next(1)).toThrow("Cannot extract right value from Left")
+})
+
+test("Left async iterator yields itself and then throws", async () => {
+  const iterator = internalCreateLeft()[Symbol.asyncIterator]()
+  const firstStep = await iterator.next()
+
+  expect(firstStep.done).toBe(false)
+  expect(Either.isEither(firstStep.value)).toBe(true)
+  if (Either.isEither(firstStep.value) === false) {
+    throw new TypeError("Expected Either from Left async iterator")
+  }
+  expect(firstStep.value.isLeft()).toBe(true)
+  expect(firstStep.value.getLeft()).toBe("stop")
+  await expect(iterator.next(1)).rejects.toThrow("Cannot extract right value from Left")
+})
+
+test("Right.getValue returns the right value", () => {
+  expect(internalCreateRight().getValue()).toBe(2)
+})
+
+test("Right.getLeft throws", () => {
+  expect(() => internalCreateRight().getLeft()).toThrow("Cannot get left value from Right")
+})
+
+test("Right.getRight returns the right value", () => {
+  expect(internalCreateRight().getRight()).toBe(2)
+})
+
+test("Right.getRightOr returns the right value", () => {
+  expect(internalCreateRight().getRightOr(9)).toBe(2)
+})
+
+test("Right.isLeft returns false", () => {
+  expect(internalCreateRight().isLeft()).toBe(false)
+})
+
+test("Right.isRight returns true", () => {
+  expect(internalCreateRight().isRight()).toBe(true)
+})
+
+test("Right.assertLeft throws", () => {
+  expect(() => internalCreateRight().assertLeft()).toThrow("Assert failed")
+})
+
+test("Right.assertRight returns itself", () => {
+  const either = internalCreateRight()
+
+  expect(either.assertRight()).toBe(either)
+})
+
+test("Right.tap only invokes the right effect", () => {
+  const effects = {
+    left: vi.fn<(value: string) => void>(),
+    right: vi.fn<(value: number) => void>(),
+  }
+  const either = internalCreateRight()
+
+  expect(either.tap(effects)).toBe(either)
+  expect(effects.left).not.toHaveBeenCalled()
+  expect(effects.right).toHaveBeenCalledWith(2)
+})
+
+test("Right.tapLeft ignores the effect", () => {
+  const effect = vi.fn<(value: string) => void>()
+  const either = internalCreateRight()
+
+  expect(either.tapLeft(effect)).toBe(either)
+  expect(effect).not.toHaveBeenCalled()
+})
+
+test("Right.tapRight invokes the effect", () => {
+  const effect = vi.fn<(value: number) => void>()
+  const either = internalCreateRight()
+
+  expect(either.tapRight(effect)).toBe(either)
+  expect(effect).toHaveBeenCalledWith(2)
+})
+
+test("Right.mapLeft preserves the right value", () => {
+  const effect = vi.fn((value: string) => value.length)
+  const either = internalCreateRight().mapLeft(effect)
+
+  expect(either.isRight()).toBe(true)
+  expect(either.getRight()).toBe(2)
+  expect(effect).not.toHaveBeenCalled()
+})
+
+test("Right.mapRight maps the right value", () => {
+  const either = internalCreateRight().mapRight((value) => value + 1)
+
+  expect(either.isRight()).toBe(true)
+  expect(either.getRight()).toBe(3)
+})
+
+test("Right.bind uses the bind result", () => {
+  const bind = vi.fn((value: number) => Either.right<string, number>(value + 3))
+  const either = internalCreateRight().bind(bind)
+
+  expect(either.isRight()).toBe(true)
+  expect(either.getRight()).toBe(5)
+  expect(bind).toHaveBeenCalledWith(2)
+})
+
+test("Right.bindAsync uses the bind result", async () => {
+  const bind = vi.fn(async (value: number) => await Promise.resolve(Either.right<string, number>(value + 4)))
+  const either = await internalCreateRight().bindAsync(bind)
+
+  expect(either.isRight()).toBe(true)
+  expect(either.getRight()).toBe(6)
+  expect(bind).toHaveBeenCalledWith(2)
+})
+
+test("Right.match uses the right branch", () => {
+  const result = internalCreateRight().match(
+    (value) => `left:${value}`,
+    (value) => `right:${value}`,
+  )
+
+  expect(result).toBe("right:2")
+})
+
+test("Right.matchAsync uses the right branch", async () => {
+  const result = await internalCreateRight().matchAsync(
+    async (value) => await Promise.resolve(`left:${value}`),
+    async (value) => await Promise.resolve(`right:${value}`),
+  )
+
+  expect(result).toBe("right:2")
+})
+
+test("Right.mplus keeps the current either", () => {
+  const result = internalCreateRight().mplus(Either.left<string, number>("fallback"))
+
+  expect(result.isRight()).toBe(true)
+  expect(result.getRight()).toBe(2)
+})
+
+test("Right iterator returns the right value immediately", () => {
+  expect(internalCreateRight()[Symbol.iterator]().next()).toEqual({ done: true, value: 2 })
+})
+
+test("Right async iterator returns the right value immediately", async () => {
+  await expect(internalCreateRight()[Symbol.asyncIterator]().next()).resolves.toEqual({ done: true, value: 2 })
+})
+
+test("Right iterator returns the right value immediately", () => {
+  expect(internalCreateRight()[Symbol.iterator]().next()).toEqual({ done: true, value: 2 })
+})
+
+test("isEither delegates to Either.isEither", () => {
+  expect(isEither(internalCreateLeft())).toBe(true)
+  expect(isEither(null)).toBe(false)
+})
+
+test("isLeft currently overflows through recursive static dispatch", () => {
+  expect(() => isLeft(internalCreateLeft())).toThrow(RangeError)
+})
+
+test("isRight currently overflows through recursive static dispatch", () => {
+  expect(() => isRight(internalCreateRight())).toThrow(RangeError)
+})
+
+test("left delegates to Either.left", () => {
+  const either = left<string, number>("helper-left")
+
+  expect(either.isLeft()).toBe(true)
+  expect(either.getLeft()).toBe("helper-left")
+})
+
+test("right delegates to Either.right", () => {
+  const either = right<string, number>(7)
+
+  expect(either.isRight()).toBe(true)
+  expect(either.getRight()).toBe(7)
+})
+
+test("eitherToTuple converts Left and Right values into tuples", () => {
+  expect(eitherToTuple(Either.left<string, number>("left"))).toEqual(["left", undefined])
+  expect(eitherToTuple(Either.right<string, number>(7))).toEqual([undefined, 7])
+})

package/tests/unit/result/generator.spec.ts

@@ -0,0 +1,273 @@
+import { expect, test } from "vitest"
+
+import { Either, gen, genAsync, genAwait, genSync, runAsyncGenerator, runSyncGenerator } from "#Source/result/index.ts"
+
+const throwCleanupError = (): never => {
+  throw new Error("cleanup")
+}
+
+test("runSyncGenerator returns the first yielded Left, the final Right, and wraps sync failures", () => {
+  let internalFinallyCalled = false
+
+  const success = runSyncGenerator((function* () {
+    const value = yield* Either.right<string, number>(1)
+    return Either.right<string, number>(value + 1)
+  })())
+
+  const failure = runSyncGenerator((function* () {
+    try {
+      yield* Either.right<string, number>(1)
+      yield* Either.left<string, number>("stop")
+      return Either.right<string, number>(999)
+    } finally {
+      internalFinallyCalled = true
+    }
+  })())
+
+  expect(success.isRight()).toBe(true)
+  expect(success.getRight()).toBe(2)
+  expect(failure.isLeft()).toBe(true)
+  expect(failure.getLeft()).toBe("stop")
+  expect(internalFinallyCalled).toBe(true)
+  expect(() => runSyncGenerator((function* () {
+    throw new Error("boom")
+  })())).toThrow("Generator threw an exception")
+  expect(() => runSyncGenerator((function* () {
+    yield "invalid" as unknown as Either<never, never>
+    return Either.right(1)
+  })())).toThrow("Generator yielded a non-Either value")
+  expect(() => runSyncGenerator((function* () {
+    try {
+      yield Either.left<string, number>("stop")
+      return Either.right(1)
+    } finally {
+      throwCleanupError()
+    }
+  })())).toThrow("Generator threw an exception during cleanup")
+})
+
+test("runAsyncGenerator returns the first yielded Left, the final Right, and wraps async failures", async () => {
+  let internalFinallyCalled = false
+
+  const success = await runAsyncGenerator((async function* () {
+    const value = yield* Either.right<string, number>(1)
+    return await Promise.resolve(Either.right<string, number>(value + 1))
+  })())
+
+  const failure = await runAsyncGenerator((async function* () {
+    try {
+      yield* Either.right<string, number>(1)
+      yield* Either.left<string, number>("stop")
+      return await Promise.resolve(Either.right<string, number>(999))
+    } finally {
+      internalFinallyCalled = true
+    }
+  })())
+
+  expect(success.isRight()).toBe(true)
+  expect(success.getRight()).toBe(2)
+  expect(failure.isLeft()).toBe(true)
+  expect(failure.getLeft()).toBe("stop")
+  expect(internalFinallyCalled).toBe(true)
+  await expect(runAsyncGenerator((async function* () {
+    await Promise.resolve()
+    throw new Error("boom")
+  })())).rejects.toThrow("Generator threw an exception")
+  await expect(runAsyncGenerator((async function* () {
+    await Promise.resolve()
+    yield "invalid" as unknown as Either<never, never>
+    return Either.right(1)
+  })())).rejects.toThrow("Generator yielded a non-Either value")
+  await expect(runAsyncGenerator((async function* () {
+    try {
+      await Promise.resolve()
+      yield Either.left<string, number>("stop")
+      return Either.right(1)
+    } finally {
+      throwCleanupError()
+    }
+  })())).rejects.toThrow("Generator threw an exception during cleanup")
+})
+
+test("genSync composes Either values with sync generators and keeps yielded Left unions", () => {
+  const getA = (): Either<"a", number> => Either.right(1)
+  const getB = (value: number): Either<"b", number> => Either.right(value + 1)
+  const getC = (value: number): Either<"c", number> => Either.right(value + 1)
+  const context = {
+    offset: 4,
+    *build(this: { offset: number }) {
+      const value = yield* Either.right<"ctx", number>(this.offset)
+      return Either.right(value + 1)
+    },
+  }
+
+  const success = genSync(function* () {
+    const a = yield* getA()
+    const b = yield* getB(a)
+    const c = yield* getC(b)
+    return Either.right(c)
+  })
+  const thisBound = genSync(context.build, context)
+
+  const failure = genSync(function* () {
+    yield* getA()
+    yield* Either.left<"stop", number>("stop")
+    return Either.right(999)
+  })
+
+  const expected: Either<"a" | "b" | "c", number> = success
+  const actual: typeof success = expected
+  const thisExpected: Either<"ctx", number> = thisBound
+  const thisActual: typeof thisBound = thisExpected
+
+  expect(actual).toBe(success)
+  expect(thisActual).toBe(thisBound)
+  expect(success.isRight()).toBe(true)
+  expect(success.getRight()).toBe(3)
+  expect(thisBound.isRight()).toBe(true)
+  expect(thisBound.getRight()).toBe(5)
+  expect(failure.isLeft()).toBe(true)
+  expect(failure.getLeft()).toBe("stop")
+})
+
+test("genAsync composes Either values with async generators and keeps yielded Left unions", async () => {
+  const getA = (): Either<"a", number> => Either.right(1)
+  const getB = (value: number): Either<"b", number> => Either.right(value + 1)
+  const getC = (value: number): Either<"c", number> => Either.right(value + 1)
+  const context = {
+    offset: 5,
+    async *build(this: { offset: number }) {
+      const value = yield* Either.right<"ctx", number>(this.offset)
+      return await Promise.resolve(Either.right(value + 1))
+    },
+  }
+
+  const success = genAsync(async function* () {
+    const a = yield* getA()
+    const b = yield* getB(a)
+    const c = yield* getC(b)
+    return await Promise.resolve(Either.right(c))
+  })
+  const thisBound = genAsync(context.build, context)
+
+  const failure = genAsync(async function* () {
+    yield* getA()
+    yield* Either.left<"stop", number>("stop")
+    return await Promise.resolve(Either.right(999))
+  })
+
+  const expected: Promise<Either<"a" | "b" | "c", number>> = success
+  const actual: typeof success = expected
+  const thisExpected: Promise<Either<"ctx", number>> = thisBound
+  const thisActual: typeof thisBound = thisExpected
+  const resolvedSuccess = await success
+  const resolvedThisBound = await thisBound
+  const resolvedFailure = await failure
+
+  expect(actual).toBe(success)
+  expect(thisActual).toBe(thisBound)
+  expect(resolvedSuccess.isRight()).toBe(true)
+  expect(resolvedSuccess.getRight()).toBe(3)
+  expect(resolvedThisBound.isRight()).toBe(true)
+  expect(resolvedThisBound.getRight()).toBe(6)
+  expect(resolvedFailure.isLeft()).toBe(true)
+  expect(resolvedFailure.getLeft()).toBe("stop")
+})
+
+test("gen dispatches sync and async generators while preserving inferred Left unions", async () => {
+  const getA = (): Either<"a", number> => Either.right(1)
+  const getB = (value: number): Either<"b", number> => Either.right(value + 1)
+  const syncContext = {
+    offset: 7,
+    *build(this: { offset: number }) {
+      const value = yield* Either.right<"ctx-sync", number>(this.offset)
+      return Either.right(value + 1)
+    },
+  }
+  const asyncContext = {
+    offset: 8,
+    async *build(this: { offset: number }) {
+      const value = yield* Either.right<"ctx-async", number>(this.offset)
+      return await Promise.resolve(Either.right(value + 1))
+    },
+  }
+
+  const sync = gen(function* () {
+    const a = yield* getA()
+    const b = yield* getB(a)
+    return Either.right(b)
+  })
+  const syncWithThis = gen(syncContext.build, syncContext)
+
+  const asyncResult = gen(async function* () {
+    const a = yield* getA()
+    const b = yield* getB(a)
+    return await Promise.resolve(Either.right(b))
+  })
+  const asyncWithThis = gen(asyncContext.build, asyncContext)
+
+  const syncExpected: Either<"a" | "b", number> = sync
+  const syncActual: typeof sync = syncExpected
+  const syncWithThisExpected: Either<"ctx-sync", number> = syncWithThis
+  const syncWithThisActual: typeof syncWithThis = syncWithThisExpected
+  const asyncExpected: Promise<Either<"a" | "b", number>> = asyncResult
+  const asyncActual: typeof asyncResult = asyncExpected
+  const asyncWithThisExpected: Promise<Either<"ctx-async", number>> = asyncWithThis
+  const asyncWithThisActual: typeof asyncWithThis = asyncWithThisExpected
+  const resolvedAsyncResult = await asyncResult
+  const resolvedAsyncWithThis = await asyncWithThis
+
+  expect(syncActual).toBe(sync)
+  expect(syncWithThisActual).toBe(syncWithThis)
+  expect(asyncActual).toBe(asyncResult)
+  expect(asyncWithThisActual).toBe(asyncWithThis)
+  expect(sync.isRight()).toBe(true)
+  expect(sync.getRight()).toBe(2)
+  expect(syncWithThis.isRight()).toBe(true)
+  expect(syncWithThis.getRight()).toBe(8)
+  expect(asyncResult).toBeInstanceOf(Promise)
+  expect(asyncWithThis).toBeInstanceOf(Promise)
+  expect(resolvedAsyncResult.isRight()).toBe(true)
+  expect(resolvedAsyncResult.getRight()).toBe(2)
+  expect(resolvedAsyncWithThis.isRight()).toBe(true)
+  expect(resolvedAsyncWithThis.getRight()).toBe(9)
+})
+
+test("genAwait composes promised Either values inside async generators", async () => {
+  const fetchUser = async (id: string): Promise<Either<"not-found", { id: string }>> => {
+    return await Promise.resolve(Either.right({ id }))
+  }
+  const fetchMissingProfile = async (_id: string): Promise<Either<"profile-missing", { id: string; role: string }>> => {
+    return await Promise.resolve(Either.left("profile-missing"))
+  }
+  const enrichUserData = (user: { id: string }): Either<"enrich-failed", { id: string; kind: "enriched" }> => {
+    return Either.right({ id: user.id, kind: "enriched" })
+  }
+
+  const success = gen(async function* () {
+    const validated = yield* Either.right<"invalid", { id: string }>({ id: "123" })
+    const user = yield* genAwait(fetchUser(validated.id))
+    const enriched = yield* enrichUserData(user)
+    return Either.right(enriched)
+  })
+
+  const failure = gen(async function* () {
+    const validated = yield* Either.right<"invalid", { id: string }>({ id: "123" })
+    yield* genAwait(fetchMissingProfile(validated.id))
+    return Either.right("unreachable")
+  })
+
+  const successExpected: Promise<Either<"invalid" | "not-found" | "enrich-failed", { id: string; kind: "enriched" }>> = success
+  const successActual: typeof success = successExpected
+  const failureExpected: Promise<Either<"invalid" | "profile-missing", string>> = failure
+  const failureActual: typeof failure = failureExpected
+  const resolvedSuccess = await success
+  const resolvedFailure = await failure
+
+  expect(successActual).toBe(success)
+  expect(failureActual).toBe(failure)
+  expect(resolvedSuccess.isRight()).toBe(true)
+  expect(resolvedSuccess.getRight()).toEqual({ id: "123", kind: "enriched" })
+  expect(resolvedFailure.isLeft()).toBe(true)
+  expect(resolvedFailure.getLeft()).toBe("profile-missing")
+})