+1

.gitignore

reviewed

··· 36 36 37 37 # Local documentation (not committed) 38 38 *.local.md 39 39 + .rnd

+97

src/effect/combinators.ts

reviewed

··· 84 84 ), 85 85 ) 86 86 87 87 + // === TapEffect - effectful success tap === 88 88 + 89 89 + /** 90 90 + * Observe a success value with an effectful side-effect, then return the original value. 91 91 + * The side-effect's result is discarded; only its error channel can influence the outcome. 92 92 + * Named `tapEffect` to distinguish from the plain-value `tap` in prelude/compose. 93 93 + * 94 94 + * @example 95 95 + * ```typescript 96 96 + * pipe( 97 97 + * loadUser(id), 98 98 + * tapEffect((u) => logEvent("user_loaded", { id: u.id })), 99 99 + * mapEff((u) => u.name), 100 100 + * ) 101 101 + * ``` 102 102 + */ 103 103 + export const tapEffect = 104 104 + <A, E2, R2>(f: (a: A) => Eff<unknown, E2, R2>) => 105 105 + <E, R>(eff: Eff<A, E, R>): Eff<A, E | E2, R | R2> => 106 106 + pipe( 107 107 + eff as Eff<A, E | E2, R | R2>, 108 108 + flatMap((a: A) => 109 109 + pipe( 110 110 + f(a) as Eff<unknown, E | E2, R | R2>, 111 111 + mapEff(() => a), 112 112 + ), 113 113 + ), 114 114 + ) 115 115 + 116 116 + // === TapError - effectful error tap === 117 117 + 118 118 + /** 119 119 + * Observe an error with an effectful side-effect, then re-propagate the original error. 120 120 + * The side-effect's result is discarded; a failure in it adds to the error union. 121 121 + * 122 122 + * @example 123 123 + * ```typescript 124 124 + * pipe( 125 125 + * loadUser(id), 126 126 + * tapError((e) => logEvent("load_failed", { error: e })), 127 127 + * ) 128 128 + * ``` 129 129 + */ 130 130 + export const tapError = 131 131 + <E, E2, R2>(f: (e: E) => Eff<unknown, E2, R2>) => 132 132 + <A, R>(eff: Eff<A, E, R>): Eff<A, E | E2, R | R2> => 133 133 + pipe( 134 134 + eff as Eff<A, E | E2, R | R2>, 135 135 + foldEff( 136 136 + (e: E | E2) => 137 137 + pipe( 138 138 + f(e as E) as Eff<unknown, E | E2, R | R2>, 139 139 + flatMap(() => fail(e) as Eff<A, E | E2, R | R2>), 140 140 + ), 141 141 + (a: A) => succeed(a) as Eff<A, E | E2, R | R2>, 142 142 + ), 143 143 + ) 144 144 + 145 145 + // === TapBoth - effectful tap on both success and failure === 146 146 + 147 147 + /** 148 148 + * Observe both success and failure with effectful side-effects. 149 149 + * The original value or error is always preserved after the side-effect runs. 150 150 + * 151 151 + * @example 152 152 + * ```typescript 153 153 + * pipe( 154 154 + * loadUser(id), 155 155 + * tapBoth({ 156 156 + * onSuccess: (u) => logEvent("loaded", { id: u.id }), 157 157 + * onFailure: (e) => logEvent("failed", { error: e }), 158 158 + * }), 159 159 + * ) 160 160 + * ``` 161 161 + */ 162 162 + export const tapBoth = 163 163 + <A, E, E2, R2>(handlers: { 164 164 + readonly onSuccess: (a: A) => Eff<unknown, E2, R2> 165 165 + readonly onFailure: (e: E) => Eff<unknown, E2, R2> 166 166 + }) => 167 167 + <R>(eff: Eff<A, E, R>): Eff<A, E | E2, R | R2> => 168 168 + pipe( 169 169 + eff as Eff<A, E | E2, R | R2>, 170 170 + foldEff( 171 171 + (e: E | E2) => 172 172 + pipe( 173 173 + handlers.onFailure(e as E) as Eff<unknown, E | E2, R | R2>, 174 174 + flatMap(() => fail(e) as Eff<A, E | E2, R | R2>), 175 175 + ), 176 176 + (a: A) => 177 177 + pipe( 178 178 + handlers.onSuccess(a) as Eff<unknown, E | E2, R | R2>, 179 179 + mapEff(() => a), 180 180 + ), 181 181 + ), 182 182 + ) 183 183 + 87 184 // === Join === 88 185 89 186 export const join = <A, E>(fiber: Fiber<A, E>): Eff<A, E, unknown> =>

+287

tests/effect-basic.test.ts

reviewed

··· 18 18 runPromiseExit, 19 19 succeed, 20 20 sync, 21 21 + tapBoth, 22 22 + tapEffect, 21 23 tapErr, 24 24 + tapError, 22 25 } from "../src/index" 23 26 24 27 describe("Effect - Basic Operations", () => { ··· 310 313 expect(Exit.isFailure(exit)).toBe(true) 311 314 if (Exit.isFailure(exit)) expect(exit.error).toBe("acquire-fail") 312 315 expect(log).toEqual([]) 316 316 + }) 317 317 + }) 318 318 + 319 319 + describe("tapEffect (effectful)", () => { 320 320 + it("on success, side-effect Eff runs and original value is returned", async () => { 321 321 + let observed: number | null = null 322 322 + const result = await runPromise( 323 323 + pipe( 324 324 + succeed(42), 325 325 + tapEffect((a: number) => 326 326 + sync(() => { 327 327 + observed = a 328 328 + }), 329 329 + ), 330 330 + ), 331 331 + ) 332 332 + expect(result).toBe(42) 333 333 + expect(observed as unknown as number).toBe(42) 334 334 + }) 335 335 + 336 336 + it("on failure, side-effect Eff does NOT run and error propagates unchanged", async () => { 337 337 + let called = false 338 338 + const exit = await runPromiseExit( 339 339 + pipe( 340 340 + fail("boom") as Eff<number, string, unknown>, 341 341 + tapEffect((_a: number) => 342 342 + sync(() => { 343 343 + called = true 344 344 + }), 345 345 + ), 346 346 + ), 347 347 + ) 348 348 + expect(Exit.isFailure(exit)).toBe(true) 349 349 + if (Exit.isFailure(exit)) expect(exit.error).toBe("boom") 350 350 + expect(called).toBe(false) 351 351 + }) 352 352 + 353 353 + it("when side-effect Eff fails, that error propagates", async () => { 354 354 + const exit = await runPromiseExit( 355 355 + pipe( 356 356 + succeed(42), 357 357 + tapEffect((_a: number) => fail("side-effect-error")), 358 358 + ), 359 359 + ) 360 360 + expect(Exit.isFailure(exit)).toBe(true) 361 361 + if (Exit.isFailure(exit)) expect(exit.error).toBe("side-effect-error") 362 362 + }) 363 363 + 364 364 + it("works with pipe() in a multi-step chain", async () => { 365 365 + const log: string[] = [] 366 366 + const result = await runPromise( 367 367 + pipe( 368 368 + succeed(10), 369 369 + tapEffect((n: number) => 370 370 + sync(() => { 371 371 + log.push(`first:${n}`) 372 372 + }), 373 373 + ), 374 374 + mapEff((n: number) => n * 2), 375 375 + tapEffect((n: number) => 376 376 + sync(() => { 377 377 + log.push(`second:${n}`) 378 378 + }), 379 379 + ), 380 380 + ), 381 381 + ) 382 382 + expect(result).toBe(20) 383 383 + expect(log).toEqual(["first:10", "second:20"]) 384 384 + }) 385 385 + }) 386 386 + 387 387 + describe("tapError (effectful)", () => { 388 388 + it("on failure, side-effect Eff runs and original error re-propagates", async () => { 389 389 + let observed: string | null = null 390 390 + const exit = await runPromiseExit( 391 391 + pipe( 392 392 + fail("original-error") as Eff<number, string, unknown>, 393 393 + tapError((e: string) => 394 394 + sync(() => { 395 395 + observed = e 396 396 + }), 397 397 + ), 398 398 + ), 399 399 + ) 400 400 + expect(Exit.isFailure(exit)).toBe(true) 401 401 + if (Exit.isFailure(exit)) expect(exit.error).toBe("original-error") 402 402 + expect(observed as unknown as string).toBe("original-error") 403 403 + }) 404 404 + 405 405 + it("on success, side-effect Eff does NOT run and value passes through", async () => { 406 406 + let called = false 407 407 + const result = await runPromise( 408 408 + pipe( 409 409 + succeed(99), 410 410 + tapError((_e: string) => 411 411 + sync(() => { 412 412 + called = true 413 413 + }), 414 414 + ), 415 415 + ), 416 416 + ) 417 417 + expect(result).toBe(99) 418 418 + expect(called).toBe(false) 419 419 + }) 420 420 + 421 421 + it("when side-effect Eff fails, that error propagates", async () => { 422 422 + const exit = await runPromiseExit( 423 423 + pipe( 424 424 + fail("original") as Eff<number, string, unknown>, 425 425 + tapError((_e: string) => fail("side-effect-error")), 426 426 + ), 427 427 + ) 428 428 + expect(Exit.isFailure(exit)).toBe(true) 429 429 + if (Exit.isFailure(exit)) expect(exit.error).toBe("side-effect-error") 430 430 + }) 431 431 + }) 432 432 + 433 433 + describe("tapBoth", () => { 434 434 + it("on success, onSuccess runs and onFailure does NOT run", async () => { 435 435 + let successCalled = false 436 436 + let failureCalled = false 437 437 + const result = await runPromise( 438 438 + pipe( 439 439 + succeed(7), 440 440 + tapBoth({ 441 441 + onSuccess: (_a: number) => 442 442 + sync(() => { 443 443 + successCalled = true 444 444 + }), 445 445 + onFailure: (_e: string) => 446 446 + sync(() => { 447 447 + failureCalled = true 448 448 + }), 449 449 + }), 450 450 + ), 451 451 + ) 452 452 + expect(result).toBe(7) 453 453 + expect(successCalled).toBe(true) 454 454 + expect(failureCalled).toBe(false) 455 455 + }) 456 456 + 457 457 + it("on failure, onFailure runs and onSuccess does NOT run", async () => { 458 458 + let successCalled = false 459 459 + let failureCalled = false 460 460 + const exit = await runPromiseExit( 461 461 + pipe( 462 462 + fail("err") as Eff<number, string, unknown>, 463 463 + tapBoth({ 464 464 + onSuccess: (_a: number) => 465 465 + sync(() => { 466 466 + successCalled = true 467 467 + }), 468 468 + onFailure: (_e: string) => 469 469 + sync(() => { 470 470 + failureCalled = true 471 471 + }), 472 472 + }), 473 473 + ), 474 474 + ) 475 475 + expect(Exit.isFailure(exit)).toBe(true) 476 476 + expect(successCalled).toBe(false) 477 477 + expect(failureCalled).toBe(true) 478 478 + }) 479 479 + 480 480 + it("original value is preserved through onSuccess tap", async () => { 481 481 + const result = await runPromise( 482 482 + pipe( 483 483 + succeed(55), 484 484 + tapBoth({ 485 485 + onSuccess: (_a: number) => succeed("discarded"), 486 486 + onFailure: (_e: string) => succeed("discarded"), 487 487 + }), 488 488 + ), 489 489 + ) 490 490 + expect(result).toBe(55) 491 491 + }) 492 492 + 493 493 + it("original error is preserved through onFailure tap", async () => { 494 494 + const exit = await runPromiseExit( 495 495 + pipe( 496 496 + fail("original-err") as Eff<number, string, unknown>, 497 497 + tapBoth({ 498 498 + onSuccess: (_a: number) => succeed("discarded"), 499 499 + onFailure: (_e: string) => succeed("discarded"), 500 500 + }), 501 501 + ), 502 502 + ) 503 503 + expect(Exit.isFailure(exit)).toBe(true) 504 504 + if (Exit.isFailure(exit)) expect(exit.error).toBe("original-err") 505 505 + }) 506 506 + }) 507 507 + 508 508 + describe("effectful tap - composability", () => { 509 509 + it("pipe with tapEffect, tapError, and mapEff works end-to-end on success", async () => { 510 510 + const log: string[] = [] 511 511 + const result = await runPromise( 512 512 + pipe( 513 513 + succeed(5), 514 514 + tapEffect((n: number) => 515 515 + sync(() => { 516 516 + log.push(`tap:${n}`) 517 517 + }), 518 518 + ), 519 519 + tapError((_e: string) => 520 520 + sync(() => { 521 521 + log.push("tapError:called") 522 522 + }), 523 523 + ), 524 524 + mapEff((n: number) => n * 3), 525 525 + ), 526 526 + ) 527 527 + expect(result).toBe(15) 528 528 + expect(log).toEqual(["tap:5"]) 529 529 + }) 530 530 + 531 531 + it("pipe with tapEffect, tapError, and mapEff works end-to-end on failure", async () => { 532 532 + const log: string[] = [] 533 533 + const exit = await runPromiseExit( 534 534 + pipe( 535 535 + fail("err") as Eff<number, string, unknown>, 536 536 + tapEffect((n: number) => 537 537 + sync(() => { 538 538 + log.push(`tap:${n}`) 539 539 + }), 540 540 + ), 541 541 + tapError((e: string) => 542 542 + sync(() => { 543 543 + log.push(`tapError:${e}`) 544 544 + }), 545 545 + ), 546 546 + mapEff((n: number) => n * 3), 547 547 + ), 548 548 + ) 549 549 + expect(Exit.isFailure(exit)).toBe(true) 550 550 + if (Exit.isFailure(exit)) expect(exit.error).toBe("err") 551 551 + expect(log).toEqual(["tapError:err"]) 552 552 + }) 553 553 + 554 554 + it("tapEffect with access() and provide() demonstrates requirement widening", async () => { 555 555 + type Logger = { log: (msg: string) => void } 556 556 + const messages: string[] = [] 557 557 + const logger: Logger = { log: (msg) => messages.push(msg) } 558 558 + 559 559 + const result = await runPromise( 560 560 + pipe( 561 561 + succeed(42), 562 562 + tapEffect((n: number) => 563 563 + access((env: Logger) => env.log(`value:${n}`)), 564 564 + ), 565 565 + provide<Logger>(logger), 566 566 + ), 567 567 + ) 568 568 + expect(result).toBe(42) 569 569 + expect(messages).toEqual(["value:42"]) 570 570 + }) 571 571 + 572 572 + it("tapBoth in a pipeline preserves value through multiple taps", async () => { 573 573 + const log: string[] = [] 574 574 + const result = await runPromise( 575 575 + pipe( 576 576 + succeed(3), 577 577 + tapBoth({ 578 578 + onSuccess: (n: number) => 579 579 + sync(() => { 580 580 + log.push(`both1:${n}`) 581 581 + }), 582 582 + onFailure: (_e: string) => sync(() => {}), 583 583 + }), 584 584 + tapEffect((n: number) => 585 585 + sync(() => { 586 586 + log.push(`tap:${n}`) 587 587 + }), 588 588 + ), 589 589 + tapBoth({ 590 590 + onSuccess: (n: number) => 591 591 + sync(() => { 592 592 + log.push(`both2:${n}`) 593 593 + }), 594 594 + onFailure: (_e: string) => sync(() => {}), 595 595 + }), 596 596 + ), 597 597 + ) 598 598 + expect(result).toBe(3) 599 599 + expect(log).toEqual(["both1:3", "tap:3", "both2:3"]) 313 600 }) 314 601 }) 315 602 })