@fncts/io 0.0.1

package/_src/IO/api/interrupt.ts

@@ -0,0 +1,169 @@
+import { SetInterrupt } from "../definition.js";
+
+/**
+ * Returns an effect that is interrupted as if by the specified fiber.
+ *
+ * @tsplus static fncts.io.IOOps interruptAs
+ */
+export function interruptAs(fiberId: FiberId, __tsplusTrace?: string): FIO<never, never> {
+  return IO.failCauseNow(Cause.interrupt(fiberId));
+}
+
+/**
+ * Returns an effect that is interrupted as if by the fiber calling this
+ * method.
+ *
+ * @tsplus static fncts.io.IOOps interrupt
+ */
+export const interrupt: IO<unknown, never, never> = IO.fiberId.flatMap(IO.interruptAs);
+
+/**
+ * Switches the interrupt status for this effect. If `true` is used, then the
+ * effect becomes interruptible (the default), while if `false` is used, then
+ * the effect becomes uninterruptible. These changes are compositional, so
+ * they only affect regions of the effect.
+ *
+ * @tsplus fluent fncts.io.IO setInterruptStatus
+ */
+export function setInterruptStatus_<R, E, A>(
+  self: IO<R, E, A>,
+  flag: InterruptStatus,
+  __tsplusTrace?: string,
+): IO<R, E, A> {
+  return new SetInterrupt(self, flag, __tsplusTrace);
+}
+
+/**
+ * Returns a new effect that performs the same operations as this effect, but
+ * interruptibly, even if composed inside of an uninterruptible region.
+ *
+ * Note that effects are interruptible by default, so this function only has
+ * meaning if used within an uninterruptible region.
+ *
+ * WARNING: This operator "punches holes" into effects, allowing them to be
+ * interrupted in unexpected places. Do not use this operator unless you know
+ * exactly what you are doing. Instead, you should use `uninterruptibleMask`.
+ *
+ * @tsplus getter fncts.io.IO interruptible
+ * @tsplus static fncts.io.IOOps interruptible
+ */
+export function interruptible<R, E, A>(self: IO<R, E, A>, __tsplusTrace?: string): IO<R, E, A> {
+  return self.setInterruptStatus(InterruptStatus.interruptible);
+}
+
+/**
+ * Performs this effect uninterruptibly. This will prevent the effect from
+ * being terminated externally, but the effect may fail for internal reasons
+ * (e.g. an uncaught error) or terminate due to defect.
+ *
+ * Uninterruptible effects may recover from all failure causes (including
+ * interruption of an inner effect that has been made interruptible).
+ *
+ * @tsplus getter fncts.io.IO uninterruptible
+ * @tsplus static fncts.io.IOOps uninterruptible
+ */
+export function uninterruptible<R, E, A>(self: IO<R, E, A>, __tsplusTrace?: string): IO<R, E, A> {
+  return self.setInterruptStatus(InterruptStatus.uninterruptible);
+}
+
+/**
+ * Makes the effect uninterruptible, but passes it a restore function that
+ * can be used to restore the inherited interruptibility from whatever region
+ * the effect is composed into.
+ *
+ * @tsplus static fncts.io.IOOps uninterruptibleMask
+ */
+export function uninterruptibleMask<R, E, A>(f: (restore: InterruptStatusRestore) => IO<R, E, A>): IO<R, E, A> {
+  return IO.checkInterruptible((flag) => f(new InterruptStatusRestore(flag)).uninterruptible);
+}
+
+/**
+ * Makes the effect interruptible, but passes it a restore function that can
+ * be used to restore the inherited interruptibility from whatever region the
+ * effect is composed into.
+ *
+ * @tsplus static fncts.io.IOOps interruptibleMask
+ */
+export function interruptibleMask<R, E, A>(k: (restore: InterruptStatusRestore) => IO<R, E, A>): IO<R, E, A> {
+  return IO.checkInterruptible((flag) => k(new InterruptStatusRestore(flag)).interruptible);
+}
+
+/**
+ * Calls the specified function, and runs the effect it returns, if this
+ * effect is interrupted.
+ *
+ * @tsplus fluent fncts.io.IO onInterrupt
+ */
+export function onInterrupt_<R, E, A, R1>(
+  ma: IO<R, E, A>,
+  cleanup: (interruptors: ReadonlySet<FiberId>) => IO<R1, never, any>,
+): IO<R & R1, E, A> {
+  return uninterruptibleMask(({ restore }) =>
+    restore(ma).matchCauseIO(
+      (cause) => (cause.interrupted ? cleanup(cause.interruptors) : IO.failCauseNow(cause)),
+      IO.succeedNow,
+    ),
+  );
+}
+
+/**
+ * Calls the specified function, and runs the effect it returns, if this
+ * effect is interrupted (allows for expanding error).
+ *
+ * @tsplus fluent fncts.io.IO onInterruptExtended
+ */
+export function onInterruptExtended_<R, E, A, R2, E2>(
+  self: IO<R, E, A>,
+  cleanup: Lazy<IO<R2, E2, any>>,
+): IO<R & R2, E | E2, A> {
+  return uninterruptibleMask(({ restore }) =>
+    restore(self).matchCauseIO(
+      (cause) =>
+        cause.interrupted
+          ? cleanup().matchCauseIO(IO.failCauseNow, () => IO.failCauseNow(cause))
+          : IO.failCauseNow(cause),
+      IO.succeedNow,
+    ),
+  );
+}
+
+/**
+ * Returns an IO whose interruption will be disconnected from the
+ * fiber's own interruption, being performed in the background without
+ * slowing down the fiber's interruption.
+ *
+ * This method is useful to create "fast interrupting" effects. For
+ * example, if you call this on a bracketed effect, then even if the
+ * effect is "stuck" in acquire or release, its interruption will return
+ * immediately, while the acquire / release are performed in the
+ * background.
+ *
+ * See timeout and race for other applications.
+ *
+ * @tsplus getter fncts.io.IO disconnect
+ */
+export function disconnect<R, E, A>(self: IO<R, E, A>, __tsplusTrace?: string): IO<R, E, A> {
+  return uninterruptibleMask(({ restore }) =>
+    IO.fiberId.flatMap((id) =>
+      restore(self).forkDaemon.flatMap((fiber) =>
+        restore(fiber.join).onInterrupt(() => fiber.interruptAs(id).forkDaemon),
+      ),
+    ),
+  );
+}
+
+/**
+ * Used to restore the inherited interruptibility
+ */
+export class InterruptStatusRestore {
+  constructor(readonly flag: InterruptStatus) {}
+
+  restore = <R, E, A>(io: IO<R, E, A>): IO<R, E, A> => io.setInterruptStatus(this.flag);
+
+  force = <R, E, A>(io: IO<R, E, A>): IO<R, E, A> => {
+    if (this.flag.isUninteruptible) {
+      return io.uninterruptible.disconnect.interruptible;
+    }
+    return io.setInterruptStatus(this.flag);
+  };
+}

package/_src/IO/api/memoize.ts

@@ -0,0 +1,10 @@
+/**
+ * @tsplus getter fncts.io.IO memoize
+ */
+export function memoize<R, E, A>(self: IO<R, E, A>, __tsplusTrace?: string): UIO<IO<R, E, A>> {
+  return IO.gen(function* (_) {
+    const future   = yield* _(Future.make<E, A>());
+    const complete = yield* _(future.fulfill(self).once);
+    return complete > future.await;
+  });
+}

package/_src/IO/api/onExit.ts

@@ -0,0 +1,12 @@
+/**
+ * @tsplus fluent fncts.io.IO onExit
+ */
+export function onExit_<R, E, A, R1, E1>(
+  self: IO<R, E, A>,
+  cleanup: (exit: Exit<E, A>) => IO<R1, E1, any>,
+): IO<R & R1, E | E1, A> {
+  return IO.unit.bracketExit(
+    () => self,
+    (_, exit) => cleanup(exit),
+  );
+}

package/_src/IO/api/once.ts

@@ -0,0 +1,6 @@
+/**
+ * @tsplus getter fncts.io.IO once
+ */
+export function once<R, E, A>(self: IO<R, E, A>, __tsplusTrace?: string): UIO<IO<R, E, void>> {
+  return Ref.make(true).map((ref) => self.whenIO(ref.getAndSet(false)));
+}

package/_src/IO/api/provideLayer.ts

@@ -0,0 +1,12 @@
+/**
+ * @tsplus fluent fncts.io.IO provideLayer
+ */
+export function provideLayer_<RIn, E, ROut, E1, A>(
+  self: IO<ROut, E1, A>,
+  layer: Layer<RIn, E, ROut>,
+): IO<RIn, E | E1, A> {
+  return Scope.make.bracketExit(
+    (scope) => layer.build(scope).flatMap((r) => self.provideEnvironment(r)),
+    (scope, exit) => scope.close(exit),
+  );
+}

package/_src/IO/api/provideSomeLayer.ts

@@ -0,0 +1,23 @@
+import type { Spreadable } from "@fncts/base/types";
+import type { Erase } from "@fncts/typelevel/Intersection";
+
+/**
+ * @tsplus fluent fncts.io.IO provideSomeLayer
+ */
+export function provideSomeLayer_<R, E, A, RIn, E1, ROut>(
+  self: IO<R, E, A>,
+  layer: Layer<RIn, E1, ROut>,
+  __tsplusTrace?: string,
+): IO<RIn & Erase<R, ROut>, E | E1, A> {
+  // @ts-expect-error
+  return self.provideLayer(Layer.environment<RIn>().and(layer));
+}
+
+/**
+ * @tsplus static fncts.io.IOAspects provideSomeLayer
+ */
+export function provideSomeLayer<RIn, E1, ROut>(layer: Layer<RIn, E1, ROut>, __tsplusTrace?: string) {
+  return <R, E, A>(self: IO<R & ROut, E, A>): IO<R & RIn, E | E1, A> =>
+    // @ts-expect-error
+    self.provideSomeLayer(layer);
+}

package/_src/IO/api/race.ts

@@ -0,0 +1,32 @@
+function maybeDisconnect<R, E, A>(io: IO<R, E, A>): IO<R, E, A> {
+  return IO.uninterruptibleMask((restore) => restore.force(io));
+}
+
+/**
+ * Returns an IO that races this effect with the specified effect,
+ * returning the first successful `A` from the faster side. If one effect
+ * succeeds, the other will be interrupted. If neither succeeds, then the
+ * effect will fail with some error.
+ *
+ * WARNING: The raced effect will safely interrupt the "loser", but will not
+ * resume until the loser has been cleanly terminated.
+ *
+ * @tsplus fluent fncts.io.IO race
+ */
+export function race_<R, E, A, R1, E1, A1>(io: IO<R, E, A>, that: IO<R1, E1, A1>): IO<R & R1, E | E1, A | A1> {
+  return IO.descriptorWith((descriptor) =>
+    maybeDisconnect(io).raceWith(
+      maybeDisconnect(that),
+      (exit, right) =>
+        exit.match(
+          (cause) => right.join.mapErrorCause((c) => Cause.both(cause, c)),
+          (a) => right.interruptAs(descriptor.id).as(a),
+        ),
+      (exit, left) =>
+        exit.match(
+          (cause) => left.join.mapErrorCause((c) => Cause.both(cause, c)),
+          (a1) => left.interruptAs(descriptor.id).as(a1),
+        ),
+    ),
+  );
+}

package/_src/IO/api/raceFirst.ts

@@ -0,0 +1,17 @@
+/**
+ * Returns an IO that races this effect with the specified effect,
+ * yielding the first result to complete, whether by success or failure. If
+ * neither effect completes, then the composed effect will not complete.
+ *
+ * WARNING: The raced effect will safely interrupt the "loser", but will not
+ * resume until the loser has been cleanly terminated. If early return is
+ * desired, then instead of performing `l.raceFirst(r)`, perform
+ * `l.disconnect raceFirst r.disconnect`, which disconnects left and right
+ * interrupt signal, allowing a fast return, with interruption performed
+ * in the background.
+ *
+ * @tsplus fluent fncts.io.IO raceFirst
+ */
+export function raceFirst_<R, E, A, R1, E1, A1>(ma: IO<R, E, A>, that: IO<R1, E1, A1>): IO<R & R1, E | E1, A | A1> {
+  return ma.result.race(that.result).flatMap(IO.fromExitNow);
+}

package/_src/IO/api/randomWith.ts

@@ -0,0 +1,11 @@
+/**
+ * @tsplus static fncts.io.IOOps randomWith
+ */
+export function randomWith<R, E, A>(f: (random: Random) => IO<R, E, A>): IO<R, E, A> {
+  return IOEnv.services.getWith((services) => f(services.get(Random.Tag)));
+}
+
+/**
+ * @tsplus static fncts.io.IOOps random
+ */
+export const random = IO.randomWith(IO.succeedNow);

package/_src/IO/api/repeat.ts

@@ -0,0 +1,49 @@
+/**
+ * @tsplus getter fncts.io.IO repeat
+ */
+export function repeat_<R, E, A>(self: IO<R, E, A>) {
+  return <R1, B>(schedule0: Lazy<Schedule<R1, A, B>>, __tsplusTrace?: string): IO<R & R1, E, B> =>
+    self.repeatOrElse(schedule0, (e, _) => IO.fail(e));
+}
+
+/**
+ * @tsplus getter fncts.io.IO repeatOrElse
+ */
+export function repeatOrElse_<R, E, A>(self: IO<R, E, A>) {
+  return <R1, B, R2, E2>(
+    schedule0: Lazy<Schedule<R1, A, B>>,
+    orElse: (e: E, out: Maybe<B>) => IO<R2, E2, B>,
+    __tsplusTrace?: string,
+  ): IO<R & R1 & R2, E2, B> => self.repeatOrElseEither(schedule0, orElse).map((_) => _.value);
+}
+
+/**
+ * @tsplus getter fncts.io.IO repeatOrElseEither
+ */
+export function repeatOrElseEither_<R, E, A>(self: IO<R, E, A>) {
+  return <R1, B, R2, E2, C>(
+    schedule0: Lazy<Schedule<R1, A, B>>,
+    orElse: (e: E, out: Maybe<B>) => IO<R2, E2, C>,
+    __tsplusTrace?: string,
+  ): IO<R & R1 & R2, E2, Either<C, B>> =>
+    IO.defer(() => {
+      const schedule = schedule0();
+
+      return schedule.driver.flatMap((driver) => {
+        const loop = (a: A): IO<R & R1 & R2, E2, Either<C, B>> =>
+          driver.next(a).matchIO(
+            () => driver.last.orHalt.map(Either.right),
+            (b) =>
+              self.matchIO(
+                (e) => orElse(e, Just(b)).map(Either.left),
+                (a) => loop(a),
+              ),
+          );
+
+        return self.matchIO(
+          (e) => orElse(e, Nothing()).map(Either.left),
+          (a) => loop(a),
+        );
+      });
+    });
+}

package/_src/IO/api/retry.ts

@@ -0,0 +1,42 @@
+/**
+ * @tsplus getter fncts.io.IO retry
+ */
+export function retry<R, E, A>(self: IO<R, E, A>) {
+  return <R1, O>(schedule0: Lazy<Schedule<R1, E, O>>, __tsplusTrace?: string): IO<R & R1, E, A> =>
+    self.retryOrElse(schedule0, (e, _) => IO.fail(e));
+}
+
+/**
+ * @tsplus getter fncts.io.IO retryOrElse
+ */
+export function retryOrElse<R, E, A>(self: IO<R, E, A>) {
+  return <R1, O, R2, E2>(
+    schedule0: Lazy<Schedule<R1, E, O>>,
+    orElse: (e: E, out: O) => IO<R2, E2, A>,
+    __tsplusTrace?: string,
+  ): IO<R & R1 & R2, E2, A> => self.retryOrElseEither(schedule0, orElse).map((_) => _.value);
+}
+
+/**
+ * @tsplus getter fncts.io.IO retryOrElseEither
+ */
+export function retryOrElseEither_<R, E, A>(self: IO<R, E, A>) {
+  return <R1, O, R2, E2, B>(
+    schedule0: Lazy<Schedule<R1, E, O>>,
+    orElse: (e: E, out: O) => IO<R2, E2, B>,
+    __tsplusTrace?: string,
+  ): IO<R & R1 & R2, E2, Either<B, A>> =>
+    IO.defer(() => {
+      const schedule = schedule0();
+
+      const loop = (driver: Schedule.Driver<unknown, R1, E, O>): IO<R & R1 & R2, E2, Either<B, A>> =>
+        self.map(Either.right).catchAll((e) =>
+          driver.next(e).matchIO(
+            () => driver.last.orHalt.flatMap((out) => orElse(e, out).map(Either.left)),
+            () => loop(driver),
+          ),
+        );
+
+      return schedule.driver.flatMap(loop);
+    });
+}

package/_src/IO/api/schedule.ts

@@ -0,0 +1,31 @@
+/**
+ * @tsplus fluent fncts.io.IO scheduleFrom
+ */
+export function scheduleFrom<R, E, A extends A1, R1, A1, B>(
+  self: IO<R, E, A>,
+  a: Lazy<A>,
+  schedule0: Lazy<Schedule<R1, A1, B>>,
+): IO<R & R1, E, B> {
+  return IO.defer(() => {
+    const schedule = schedule0();
+    return schedule.driver.flatMap((driver) => {
+      const loop = (a: A1): IO<R & R1, E, B> =>
+        driver.next(a).matchIO(
+          () => driver.last.orHalt,
+          () => self.flatMap(loop),
+        );
+      return loop(a());
+    });
+  });
+}
+
+/**
+ * @tsplus fluent fncts.io.IO schedule
+ */
+export function schedule<R, E, A, R1, B>(
+  io: IO<R, E, A>,
+  schedule: Lazy<Schedule<R1, any, B>>,
+  __tsplusTrace?: string,
+): IO<R & R1, E, B> {
+  return io.scheduleFrom(undefined, schedule);
+}

package/_src/IO/api/scope.ts

@@ -0,0 +1,4 @@
+/**
+ * @tsplus static fncts.io.IOOps scope
+ */
+export const scope: IO<Has<Scope>, never, Scope> = IO.service(Scope.Tag);

package/_src/IO/api/scopeWith.ts

@@ -0,0 +1,6 @@
+/**
+ * @tsplus static fncts.io.IOOps scopeWith
+ */
+export function scopeWith<R, E, A>(f: (scope: Scope) => IO<R, E, A>): IO<R & Has<Scope>, E, A> {
+  return IO.serviceWithIO(f, Scope.Tag);
+}

package/_src/IO/api/scoped.ts

@@ -0,0 +1,13 @@
+/**
+ * @tsplus static fncts.io.IOOps scoped
+ */
+export function scoped<R, E, A>(io: Lazy<IO<R & Has<Scope>, E, A>>): IO<R, E, A> {
+  return Scope.make.flatMap((scope) => scope.use(io));
+}
+
+/**
+ * @tsplus getter fncts.io.IO scoped
+ */
+export function scoped_<R, E, A>(io: IO<R & Has<Scope>, E, A>): IO<R, E, A> {
+  return IO.scoped(io);
+}

package/_src/IO/api/sequenceT.ts

@@ -0,0 +1,12 @@
+import type { _A, _E, _R } from "@fncts/base/types";
+
+import { identity, unsafeCoerce } from "@fncts/base/data/function";
+
+/**
+ * @tsplus static fncts.io.IOOps sequenceT
+ */
+export function sequenceT<T extends ReadonlyNonEmptyArray<IO<any, any, any>>>(
+  ...ios: T
+): IO<_R<T[number]>, _E<T[number]>, { [K in keyof T]: _A<T[K]> }> {
+  return unsafeCoerce(IO.foreach(ios, identity));
+}

package/_src/IO/api/sleep.ts

@@ -0,0 +1,6 @@
+/**
+ * @tsplus static fncts.io.IOOps sleep
+ */
+export function sleep(duration: number, __tsplusTrace?: string): UIO<void> {
+  return Clock.sleep(duration);
+}

package/_src/IO/api/stateful.ts

@@ -0,0 +1,15 @@
+import type { Spreadable } from "@fncts/base/types";
+
+import { State } from "../../State.js";
+
+/**
+ * @tsplus static fncts.io.IOOps stateful
+ */
+export function stateful<S, R, E, A>(
+  s: S,
+  io: Lazy<IO<Has<State<S>> & R, E, A>>,
+  tag: Tag<State<S>>,
+  __tsplusTrace?: string,
+): IO<R, E, A> {
+  return IO.defer(io)(IO.$.provideSomeLayer(State.initial(s, tag)));
+}

package/_src/IO/api/withChildren.ts

@@ -0,0 +1,13 @@
+/**
+ * @tsplus static fncts.io.IOOps withChildren
+ */
+export function withChildren<R, E, A>(
+  get: (_: UIO<Conc<Fiber.Runtime<any, any>>>) => IO<R, E, A>,
+  __tsplusTrace?: string,
+): IO<R, E, A> {
+  return Supervisor.track.flatMap((supervisor) =>
+    get(
+      supervisor.value.flatMap((children) => IO.descriptor.map((d) => children.filter((_) => _.id != d.id))),
+    ).supervised(supervisor),
+  );
+}

package/_src/IO/api/withFinalizer.ts

@@ -0,0 +1,9 @@
+/**
+ * @tsplus fluent fncts.io.IO withFinalizer
+ */
+export function withFinalizer_<R, E, A, R1>(
+  self: IO<R, E, A>,
+  finalizer: (a: A) => URIO<R1, any>,
+): IO<R & R1 & Has<Scope>, E, A> {
+  return IO.acquireRelease(self, finalizer);
+}

package/_src/IO/api/withFinalizerExit.ts

@@ -0,0 +1,9 @@
+/**
+ * @tsplus fluent fncts.io.IO withFinalizerExit
+ */
+export function withFinalizerExit_<R, E, A, R1>(
+  self: IO<R, E, A>,
+  finalizer: (a: A, exit: Exit<any, any>) => URIO<R1, any>,
+): IO<R & R1 & Has<Scope>, E, A> {
+  return IO.acquireReleaseExit(self, finalizer);
+}

package/_src/IO/api/withRuntimeConfig.ts

@@ -0,0 +1,16 @@
+/**
+ * Runs the specified effect on the specified runtime configuration, restoring
+ * the old runtime configuration when it completes execution.
+ *
+ * @tsplus fluent fncts.io.IO withRuntimeConfig
+ */
+export function withRuntimeConfig_<R, E, A>(self: IO<R, E, A>, runtimeConfig: Lazy<RuntimeConfig>): IO<R, E, A> {
+  return IO.runtimeConfig.flatMap((currentRuntimeConfig) =>
+    IO.setRuntimeConfig(runtimeConfig)
+      .apSecond(IO.yieldNow)
+      .bracket(
+        () => self,
+        () => IO.setRuntimeConfig(currentRuntimeConfig),
+      ),
+  );
+}

package/_src/IO/api/zipC.ts

@@ -0,0 +1,8 @@
+import { tuple } from "@fncts/base/data/function";
+
+/**
+ * @tsplus fluent fncts.io.IO zipC
+ */
+export function zipC_<R, E, A, R1, E1, B>(self: IO<R, E, A>, that: IO<R1, E1, B>): IO<R & R1, E | E1, readonly [A, B]> {
+  return self.zipWithC(that, tuple);
+}

package/_src/IO/api/zipWithC.ts

@@ -0,0 +1,41 @@
+/**
+ * @tsplus fluent fncts.io.IO zipWithC
+ */
+export function zipWithC_<R, E, A, R1, E1, B, C>(
+  self: IO<R, E, A>,
+  that: IO<R1, E1, B>,
+  f: (a: A, b: B) => C,
+): IO<R & R1, E | E1, C> {
+  const g = (b: B, a: A) => f(a, b);
+
+  return IO.transplant((graft) =>
+    IO.descriptorWith((d) =>
+      graft(self).raceWith(
+        graft(that),
+        (exit, fiber) => coordinateZipWithC<E, E1>()(d.id, f, true, exit, fiber),
+        (exit, fiber) => coordinateZipWithC<E, E1>()(d.id, g, false, exit, fiber),
+      ),
+    ),
+  );
+}
+
+function coordinateZipWithC<E, E2>() {
+  return <B, X, Y>(
+    fiberId: FiberId,
+    f: (a: X, b: Y) => B,
+    leftWinner: boolean,
+    winner: Exit<E | E2, X>,
+    loser: Fiber<E | E2, Y>,
+  ) => {
+    return winner.match(
+      (cw) =>
+        loser.interruptAs(fiberId).flatMap((exit) =>
+          exit.match(
+            (cl) => (leftWinner ? IO.failCauseNow(Cause.both(cw, cl)) : IO.failCauseNow(Cause.both(cl, cw))),
+            () => IO.failCauseNow(cw),
+          ),
+        ),
+      (x) => loser.join.map((y) => f(x, y)),
+    );
+  };
+}