Recipes
Runnable patterns built from the public API. They share a small run helper that forks an effect and resolves with its result:
import { assertEquals } from "@std/assert";
import type { Effect } from "@sekhmet/effect/effect";
import { type FiberResult, fork } from "@sekhmet/effect/fiber";
import { Runtime } from "@sekhmet/effect/runtime";
import { Scheduler, sync } from "@sekhmet/effect/scheduler";
import { Success } from "@sekhmet/effect/effect";
import { Ok } from "@sekhmet/enum/result/mini";
function run<T, E>(effect: Effect<void, T, E>): Promise<FiberResult<T, E>> {
const runtime = new Runtime({
input: undefined,
config: { scheduler: new Scheduler({ schedule: sync() }) },
});
return new Promise((resolve) => fork(runtime, effect).join(resolve));
}
assertEquals(await run(Success(1)), Ok(1));Each recipe below repeats the imports it needs so it runs on its own.
Wrap a promise
A promise-returning function becomes an effect whose rejection is a typed failure. Pass the function, not the promise, so the work starts only when a fiber runs the effect.
import { assertEquals } from "@std/assert";
import { Async, Ready } from "@sekhmet/effect/continuation";
import { Effect, Failed } from "@sekhmet/effect/effect";
import { type FiberResult, fork } from "@sekhmet/effect/fiber";
import { Failed as FiberFailed } from "@sekhmet/effect/fiber/mini";
import { Runtime } from "@sekhmet/effect/runtime";
import { Scheduler, sync } from "@sekhmet/effect/scheduler";
import { Err, Ok } from "@sekhmet/enum/result/mini";
function fromPromise<T>(start: () => Promise<T>): Effect<void, T, unknown> {
return new Effect(() =>
Async((resolve) => {
start().then(
(value) => resolve(Ready(Ok(value))),
(reason: unknown) => resolve(Ready(Err(Failed(reason)))),
);
}),
);
}
const runtime = new Runtime({
input: undefined,
config: { scheduler: new Scheduler({ schedule: sync() }) },
});
const run = <T>(effect: Effect<void, T, unknown>) =>
new Promise<FiberResult<T, unknown>>((resolve) =>
fork(runtime, effect).join(resolve),
);
assertEquals(
await run(fromPromise(() => Promise.resolve(3)).map((n) => n * 2)),
Ok(6),
);
// A rejection reaches the fiber as a typed failure
assertEquals(
await run(fromPromise(() => Promise.reject("offline"))),
Err(FiberFailed("offline")),
);Cancel after a timeout
cancel stops a fiber and runs the cleanup of the work it waits on.
import { assertEquals } from "@std/assert";
import { Async, Ready } from "@sekhmet/effect/continuation";
import { Effect } from "@sekhmet/effect/effect";
import { Cancelled } from "@sekhmet/effect/fiber/mini";
import { type FiberResult, fork } from "@sekhmet/effect/fiber";
import { Runtime } from "@sekhmet/effect/runtime";
import { Scheduler, sync } from "@sekhmet/effect/scheduler";
import { Err, Ok } from "@sekhmet/enum/result/mini";
let timersCleared = 0;
const sleep = (ms: number) =>
new Effect<void, string, never>(() =>
Async((resolve) => {
const timer = setTimeout(() => resolve(Ready(Ok("done"))), ms);
return () => {
timersCleared++;
clearTimeout(timer);
};
}),
);
const runtime = new Runtime({
input: undefined,
config: { scheduler: new Scheduler({ schedule: sync() }) },
});
const fiber = fork(runtime, sleep(10_000));
const result = new Promise<FiberResult<string, never>>((resolve) =>
fiber.join(resolve),
);
setTimeout(() => fiber.cancel(), 5);
assertEquals(await result, Err(Cancelled()));
assertEquals(timersCleared, 1);Run two effects concurrently
zip runs both on their own fibers and succeeds with both values. If one fails, the other is cancelled.
import { assertEquals } from "@std/assert";
import { Async, Ready } from "@sekhmet/effect/continuation";
import { Effect, Failure } from "@sekhmet/effect/effect";
import { type FiberResult, fork } from "@sekhmet/effect/fiber";
import { Failed } from "@sekhmet/effect/fiber/mini";
import { Runtime } from "@sekhmet/effect/runtime";
import { Scheduler, sync } from "@sekhmet/effect/scheduler";
import { Err, Ok } from "@sekhmet/enum/result/mini";
const after = <T>(ms: number, value: T) =>
new Effect<void, T, string>(() =>
Async((resolve) => {
const timer = setTimeout(() => resolve(Ready(Ok(value))), ms);
return () => clearTimeout(timer);
}),
);
const runtime = new Runtime({
input: undefined,
config: { scheduler: new Scheduler({ schedule: sync() }) },
});
const run = <T>(effect: Effect<void, T, string>) =>
new Promise<FiberResult<T, string>>((resolve) =>
fork(runtime, effect).join(resolve),
);
assertEquals(
await run(after(5, "user").zip(after(1, ["post"]))),
Ok(["user", ["post"]]),
);
// The slow side is cancelled (its timer cleared) when the other fails
assertEquals(
await run(after(10_000, "user").zip(Failure("posts unavailable"))),
Err(Failed("posts unavailable")),
);Pass dependencies as input
Effects read their input from the runtime, so the same effect can run against real or test dependencies.
import { assertEquals } from "@std/assert";
import { Ready } from "@sekhmet/effect/continuation";
import { Effect } from "@sekhmet/effect/effect";
import { fork } from "@sekhmet/effect/fiber";
import { Runtime } from "@sekhmet/effect/runtime";
import { Scheduler, sync } from "@sekhmet/effect/scheduler";
import { Ok } from "@sekhmet/enum/result/mini";
interface Deps {
now: () => number;
}
const timestamp = new Effect<Deps, string, never>((deps) =>
Ready(Ok(new Date(deps.now()).toISOString())),
);
const testRuntime = new Runtime<Deps>({
input: { now: () => 0 },
config: { scheduler: new Scheduler({ schedule: sync() }) },
});
const results: unknown[] = [];
fork(testRuntime, timestamp).join((result) => results.push(result));
assertEquals(results, [Ok("1970-01-01T00:00:00.000Z")]);Recover from a typed failure
orElse replaces a typed failure with another effect; mapOr with a value. Neither catches thrown exceptions, which reach the fiber as Panicked.
import { assertEquals } from "@std/assert";
import { type Effect, Failure, Success } from "@sekhmet/effect/effect";
import { fork } from "@sekhmet/effect/fiber";
import { Runtime } from "@sekhmet/effect/runtime";
import { Scheduler, sync } from "@sekhmet/effect/scheduler";
import { Ok } from "@sekhmet/enum/result/mini";
const runtime = new Runtime({
input: undefined,
config: { scheduler: new Scheduler({ schedule: sync() }) },
});
const results: unknown[] = [];
const fromCache: Effect<void, string, string> = Failure("cache miss");
const cached = fromCache.orElse((reason) => Success(`fetched (${reason})`));
fork(runtime, cached).join((result) => results.push(result));
assertEquals(results, [Ok("fetched (cache miss)")]);Keep a busy app responsive
With sync, a long chain of steps runs before fork returns. A yielding schedule spreads the work over event-loop turns instead; adaptive drains a deep queue in microtasks and yields macrotasks when it is shallow.
import { adaptive, Scheduler } from "@sekhmet/effect/scheduler";
import { Runtime } from "@sekhmet/effect/runtime";
const runtime = new Runtime({
input: undefined,
config: {
scheduler: new Scheduler({
schedule: adaptive({ busyThreshold: 32 }),
stepBudget: 64,
}),
fiberConfig: { stepBudget: 256 },
},
});