@fncts/io 0.0.21 → 0.0.22

package/_src/Hub/definition.ts

@@ -1,108 +1,117 @@
-import type { HashedPair } from "../internal/HashedPair.js";
-import type { MutableQueue } from "../internal/MutableQueue.js";
-import type { UIO } from "../IO.js";
-import type { Dequeue, Enqueue } from "../Queue/definition.js";
-import type { Strategy } from "./internal.js";
-import type { HashSet } from "@fncts/base/collection/mutable/HashSet";
-import type { AtomicBoolean } from "@fncts/base/internal/AtomicBoolean";
-import type { Hub as HubInternal } from "@fncts/io/internal/Hub";
-
-import { QueueTypeId } from "../Queue/definition.js";
-import { makeSubscription } from "./internal.js";
+import type { IO } from "@fncts/io/IO";
+import type { PDequeue, PEnqueue, PEnqueueInternal } from "@fncts/io/Queue";
+
+import { EnqueueTypeId, QueueTypeId } from "@fncts/io/Queue";
 
 export const HubTypeId = Symbol.for("fncts.io.Hub");
 export type HubTypeId = typeof HubTypeId;
 
 /**
+ * A `Hub<RA, RB, EA, EB, A, B>` is an asynchronous message hub. Publishers
+ * can publish messages of type `A` to the hub and subscribers can subscribe to
+ * take messages of type `B` from the hub. Publishing messages can require an
+ * environment of type `RA` and fail with an error of type `EA`. Taking
+ * messages can require an environment of type `RB` and fail with an error of
+ * type `EB`.
+ *
  * @tsplus type fncts.io.Hub
- * @tsplus companion fncts.io.HubOps
  */
-export class Hub<A> implements Enqueue<A> {
-  readonly [QueueTypeId]: QueueTypeId = QueueTypeId;
-  readonly [HubTypeId]: HubTypeId     = HubTypeId;
-  declare _In: (_: A) => void;
-  constructor(
-    readonly hub: HubInternal<A>,
-    readonly subscribers: HashSet<HashedPair<HubInternal.Subscription<A>, MutableQueue<Future<never, A>>>>,
-    readonly scope: Scope.Closeable,
-    readonly shutdownHook: Future<never, void>,
-    readonly shutdownFlag: AtomicBoolean,
-    readonly strategy: Strategy<A>,
-  ) {}
-
-  awaitShutdown: UIO<void> = this.shutdownHook.await;
-
-  get capacity(): number {
-    return this.hub.capacity;
-  }
-
-  isShutdown: UIO<boolean> = IO(this.shutdownFlag.get);
-
-  publish(this: this, a: A, __tsplusTrace?: string): UIO<boolean> {
-    return IO.defer(() => {
-      if (this.shutdownFlag.get) {
-        return IO.interrupt;
-      }
-
-      if (this.hub.publish(a)) {
-        this.strategy.unsafeCompleteSubscribers(this.hub, this.subscribers);
-        return IO.succeedNow(true);
-      }
-
-      return this.strategy.handleSurplus(this.hub, this.subscribers, Conc.single(a), this.shutdownFlag);
-    });
-  }
-
-  publishAll(this: this, as: Iterable<A>, __tsplusTrace?: string): UIO<boolean> {
-    return IO.defer(() => {
-      if (this.shutdownFlag.get) {
-        return IO.interrupt;
-      }
-
-      const surplus = this.hub.publishAll(as);
-
-      this.strategy.unsafeCompleteSubscribers(this.hub, this.subscribers);
-
-      if (surplus.isEmpty) {
-        return IO.succeedNow(true);
-      }
-
-      return this.strategy.handleSurplus(this.hub, this.subscribers, surplus, this.shutdownFlag);
-    });
-  }
-
-  shutdown: UIO<void> = IO.deferWith((_, fiberId) => {
-    this.shutdownFlag.set(true);
-    return this.scope
-      .close(Exit.interrupt(fiberId))
-      .apSecond(this.strategy.shutdown)
-      .whenIO(this.shutdownHook.succeed(undefined));
-  }).uninterruptible;
-
-  size: UIO<number> = IO.defer(() => {
-    if (this.shutdownFlag.get) {
-      return IO.interrupt;
-    }
-
-    return IO.succeed(this.hub.size());
-  });
-
-  subscribe: IO<Scope, never, Dequeue<A>> = IO.acquireRelease(
-    makeSubscription(this.hub, this.subscribers, this.strategy).tap((dequeue) =>
-      this.scope.addFinalizer(dequeue.shutdown),
-    ),
-    (dequeue) => dequeue.shutdown,
-  );
-
-  isEmpty: UIO<boolean> = this.size.map((size) => size === 0);
+export interface PHub<RA, RB, EA, EB, A, B> extends PEnqueue<RA, RB, EA, EB, A, B> {
+  readonly _typeId: HubTypeId;
+  readonly _RA: () => RA;
+  readonly _RB: () => RB;
+  readonly _EA: () => EA;
+  readonly _EB: () => EB;
+  readonly _A: (_: A) => void;
+  readonly _B: () => B;
+}
 
-  isFull: UIO<boolean> = this.size.map((size) => size === this.capacity);
+/**
+ * @tsplus type fncts.io.Hub
+ */
+export interface Hub<A> extends PHub<never, never, never, never, A, A> {}
 
-  offer(this: this, a: A, __tsplusTrace?: string | undefined): UIO<boolean> {
+/**
+ * @tsplus type fncts.io.HubOps
+ */
+export interface HubOps {}
+
+export const Hub: HubOps = {};
+
+export declare namespace PHub {}
+export declare namespace Hub {}
+
+export abstract class PHubInternal<RA, RB, EA, EB, A, B>
+  implements PHub<RA, RB, EA, EB, A, B>, PEnqueueInternal<RA, RB, EA, EB, A, B>
+{
+  readonly [QueueTypeId]: QueueTypeId     = QueueTypeId;
+  readonly [EnqueueTypeId]: EnqueueTypeId = EnqueueTypeId;
+  _typeId: HubTypeId = HubTypeId;
+  readonly _RA!: () => RA;
+  readonly _RB!: () => RB;
+  readonly _EA!: () => EA;
+  readonly _EB!: () => EB;
+  readonly _A!: (_: A) => void;
+  readonly _B!: () => B;
+
+  /**
+   * Waits for the hub to be shut down.
+   */
+  abstract awaitShutdown: UIO<void>;
+
+  /**
+   * The maximum capacity of the hub.
+   */
+  abstract capacity: number;
+
+  /**
+   * Checks whether the hub is shut down.
+   */
+  abstract isShutdown: UIO<boolean>;
+
+  /**
+   * Publishes a message to the hub, returning whether the message was
+   * published to the hub.
+   */
+  abstract publish(a: A): IO<RA, EA, boolean>;
+
+  /**
+   * Publishes all of the specified messages to the hub, returning whether
+   * they were published to the hub.
+   */
+  abstract publishAll(as: Iterable<A>): IO<RA, EA, boolean>;
+
+  /**
+   * Shuts down the hub.
+   */
+  abstract shutdown: UIO<void>;
+
+  /**
+   * The current number of messages in the hub.
+   */
+  abstract size: UIO<number>;
+
+  /**
+   * Subscribes to receive messages from the hub. The resulting subscription
+   * can be evaluated multiple times within the scope of the managed to take a
+   * message from the hub each time.
+   */
+  abstract subscribe: IO<Scope, never, PDequeue<RA, RB, EA, EB, A, B>>;
+
+  offer(a: A, __tsplusTrace?: string): IO<RA, EA, boolean> {
     return this.publish(a);
   }
 
-  offerAll(this: this, as: Iterable<A>, __tsplusTrace?: string | undefined): UIO<boolean> {
+  offerAll(as: Iterable<A>, __tsplusTrace?: string): IO<RA, EA, boolean> {
     return this.publishAll(as);
   }
 }
+
+/**
+ * @tsplus macro remove
+ */
+export function concrete<RA, RB, EA, EB, A, B>(
+  _: PHub<RA, RB, EA, EB, A, B>,
+): asserts _ is PHubInternal<RA, RB, EA, EB, A, B> {
+  //
+}

package/_src/Hub/internal.ts

@@ -1,11 +1,11 @@
 import type { Hub as HubInternal } from "@fncts/io/internal/Hub";
-import type { Dequeue } from "@fncts/io/Queue";
 
 import { HashSet } from "@fncts/base/collection/mutable/HashSet";
 import { AtomicBoolean } from "@fncts/base/internal/AtomicBoolean";
+import { PHubInternal } from "@fncts/io/Hub/definition";
 import { HashedPair } from "@fncts/io/internal/HashedPair";
 import { MutableQueue } from "@fncts/io/internal/MutableQueue";
-import { QueueTypeId } from "@fncts/io/Queue";
+import { QueueInternal } from "@fncts/io/Queue";
 
 /**
  * A `Strategy<A>` describes the protocol for how publishers and subscribers
@@ -128,7 +128,7 @@ export class BackPressure<A> extends Strategy<A> {
     return Do((_) => {
       const fiberId    = _(IO.fiberId);
       const publishers = _(IO.succeed(self.publishers.unsafeDequeueAll));
-      _(publishers.traverseIOC(([_, future, last]) => (last ? future.interruptAs(fiberId) : IO.unit)));
+      _(publishers.traverseIOConcurrentDiscard(([_, future, last]) => (last ? future.interruptAs(fiberId) : IO.unit)));
     });
   }
 
@@ -254,9 +254,7 @@ export class Sliding<A> extends Strategy<A> {
   }
 }
 
-class UnsafeSubscription<A> implements Dequeue<A> {
-  readonly [QueueTypeId]: QueueTypeId = QueueTypeId;
-  declare _Out: (_: never) => A;
+class UnsafeSubscription<A> extends QueueInternal<never, never, never, never, A, A> {
   constructor(
     readonly hub: HubInternal<A>,
     readonly subscribers: HashSet<HashedPair<HubInternal.Subscription<A>, MutableQueue<Future<never, A>>>>,
@@ -265,92 +263,83 @@ class UnsafeSubscription<A> implements Dequeue<A> {
     readonly shutdownHook: Future<never, void>,
     readonly shutdownFlag: AtomicBoolean,
     readonly strategy: Strategy<A>,
-  ) {}
-
-  get awaitShutdown(): UIO<void> {
-    return this.shutdownHook.await;
+  ) {
+    super();
   }
 
-  get capacity(): number {
-    return this.hub.capacity;
-  }
+  awaitShutdown: UIO<void> = this.shutdownHook.await;
 
-  get isShutdown(): UIO<boolean> {
-    return IO.succeed(() => this.shutdownFlag.get);
-  }
+  capacity: number = this.hub.capacity;
 
-  get shutdown(): UIO<void> {
-    return IO.fiberId.flatMap((fiberId) =>
-      IO.defer(() => {
-        this.shutdownFlag.set(true);
-        return this.pollers.unsafeDequeueAll
-          .traverseIOC((fiber) => fiber.interruptAs(fiberId))
-          .apSecond(IO.succeed(this.subscription.unsubscribe()))
-          .whenIO(this.shutdownHook.succeed(undefined));
-      }),
-    );
-  }
+  isShutdown: UIO<boolean> = IO.succeed(() => this.shutdownFlag.get);
 
-  get size(): UIO<number> {
-    return IO.defer(() => {
-      if (this.shutdownFlag.get) {
-        return IO.interrupt;
-      }
+  shutdown: UIO<void> = IO.fiberId.flatMap((fiberId) =>
+    IO.defer(() => {
+      this.shutdownFlag.set(true);
+      return IO.foreachConcurrent(this.pollers.unsafeDequeueAll, (fiber) => fiber.interruptAs(fiberId))
+        .zipRight(IO.succeed(this.subscription.unsubscribe()))
+        .whenIO(this.shutdownHook.succeed(undefined));
+    }),
+  );
 
-      return IO.succeed(this.subscription.size());
-    });
-  }
+  size: UIO<number> = IO.defer(() => {
+    if (this.shutdownFlag.get) {
+      return IO.interrupt;
+    }
 
-  get take(): IO<never, never, A> {
-    return IO.fiberId.flatMap((fiberId) =>
-      IO.defer(() => {
-        if (this.shutdownFlag.get) {
-          return IO.interrupt;
-        }
+    return IO.succeed(this.subscription.size());
+  });
 
-        const empty   = null as unknown as A;
-        const message = this.pollers.isEmpty ? this.subscription.poll(empty) : empty;
-
-        if (message == null) {
-          const future = Future.unsafeMake<never, A>(fiberId);
-
-          return IO.defer(() => {
-            this.pollers.enqueue(future);
-            this.subscribers.add(new HashedPair(this.subscription, this.pollers));
-            this.strategy.unsafeCompletePollers(this.hub, this.subscribers, this.subscription, this.pollers);
-            if (this.shutdownFlag.get) {
-              return IO.interrupt;
-            } else {
-              return future.await;
-            }
-          }).onInterrupt(() =>
-            IO.succeed(() => {
-              this.pollers.unsafeRemove(future);
-            }),
-          );
-        } else {
-          this.strategy.unsafeOnHubEmptySpace(this.hub, this.subscribers);
-          return IO.succeedNow(message);
-        }
-      }),
-    );
-  }
+  offer = (_: never): IO<never, never, boolean> => IO.succeedNow(false);
 
-  get takeAll(): IO<never, never, Conc<A>> {
-    return IO.defer(() => {
+  offerAll = (_: Iterable<never>): IO<never, never, boolean> => IO.succeedNow(false);
+
+  take: IO<never, never, A> = IO.fiberId.flatMap((fiberId) =>
+    IO.defer(() => {
       if (this.shutdownFlag.get) {
         return IO.interrupt;
       }
 
-      const as = this.pollers.isEmpty ? this.subscription.unsafePollAll : Conc.empty<A>();
+      const empty   = null as unknown as A;
+      const message = this.pollers.isEmpty ? this.subscription.poll(empty) : empty;
 
-      this.strategy.unsafeOnHubEmptySpace(this.hub, this.subscribers);
+      if (message == null) {
+        const future = Future.unsafeMake<never, A>(fiberId);
 
-      return IO.succeedNow(as);
-    });
-  }
+        return IO.defer(() => {
+          this.pollers.enqueue(future);
+          this.subscribers.add(new HashedPair(this.subscription, this.pollers));
+          this.strategy.unsafeCompletePollers(this.hub, this.subscribers, this.subscription, this.pollers);
+          if (this.shutdownFlag.get) {
+            return IO.interrupt;
+          } else {
+            return future.await;
+          }
+        }).onInterrupt(() =>
+          IO.succeed(() => {
+            this.pollers.unsafeRemove(future);
+          }),
+        );
+      } else {
+        this.strategy.unsafeOnHubEmptySpace(this.hub, this.subscribers);
+        return IO.succeedNow(message);
+      }
+    }),
+  );
+
+  takeAll: IO<never, never, Conc<A>> = IO.defer(() => {
+    if (this.shutdownFlag.get) {
+      return IO.interrupt;
+    }
+
+    const as = this.pollers.isEmpty ? this.subscription.unsafePollAll : Conc.empty<A>();
+
+    this.strategy.unsafeOnHubEmptySpace(this.hub, this.subscribers);
+
+    return IO.succeedNow(as);
+  });
 
-  takeUpTo(this: this, n: number): IO<never, never, Conc<A>> {
+  takeUpTo = (n: number): IO<never, never, Conc<A>> => {
     return IO.defer(() => {
       if (this.shutdownFlag.get) {
         return IO.interrupt;
@@ -361,43 +350,7 @@ class UnsafeSubscription<A> implements Dequeue<A> {
       this.strategy.unsafeOnHubEmptySpace(this.hub, this.subscribers);
       return IO.succeedNow(as);
     });
-  }
-
-  private takeRemainder(min: number, max: number, acc: Conc<A>, __tsplusTrace?: string): UIO<Conc<A>> {
-    if (max < min) return IO.succeedNow(acc);
-    else {
-      return this.takeUpTo(max).flatMap((bs) => {
-        const remaining = min - bs.length;
-        if (remaining === 1) {
-          return this.take.map((b) => acc.concat(bs).append(b));
-        } else if (remaining > 1) {
-          return this.take.flatMap((b) => this.takeRemainder(remaining - 1, max - bs.length, acc.concat(bs).append(b)));
-        } else {
-          return IO.succeedNow(acc.concat(bs));
-        }
-      });
-    }
-  }
-
-  takeBetween(this: this, min: number, max: number, __tsplusTrace?: string): UIO<Conc<A>> {
-    return this.takeRemainder(min, max, Conc());
-  }
-
-  takeN(this: this, n: number, __tsplusTrace?: string): UIO<Conc<A>> {
-    return this.takeBetween(n, n);
-  }
-
-  get poll(): UIO<Maybe<A>> {
-    return this.takeUpTo(1).map((_) => _.head);
-  }
-
-  get isFull(): UIO<boolean> {
-    return this.size.map((size) => size === this.capacity);
-  }
-
-  get isEmpty(): UIO<boolean> {
-    return this.size.map((size) => size === 0);
-  }
+  };
 }
 
 /**
@@ -407,7 +360,7 @@ export function makeSubscription<A>(
   hub: HubInternal<A>,
   subscribers: HashSet<HashedPair<HubInternal.Subscription<A>, MutableQueue<Future<never, A>>>>,
   strategy: Strategy<A>,
-): UIO<Dequeue<A>> {
+): UIO<Queue.Dequeue<A>> {
   return Future.make<never, void>().map((future) => {
     return unsafeMakeSubscription(
       hub,
@@ -432,7 +385,7 @@ export function unsafeMakeSubscription<A>(
   shutdownHook: Future<never, void>,
   shutdownFlag: AtomicBoolean,
   strategy: Strategy<A>,
-): Dequeue<A> {
+): Queue.Dequeue<A> {
   return new UnsafeSubscription(hub, subscribers, subscription, pollers, shutdownHook, shutdownFlag, strategy);
 }
 
@@ -441,3 +394,100 @@ export function subscribersHashSet<A>(): HashSet<
 > {
   return HashSet.empty<HashedPair<HubInternal.Subscription<A>, MutableQueue<Future<never, A>>>>();
 }
+
+class UnsafeHub<A> extends PHubInternal<never, never, never, never, A, A> {
+  constructor(
+    readonly hub: HubInternal<A>,
+    readonly subscribers: HashSet<HashedPair<HubInternal.Subscription<A>, MutableQueue<Future<never, A>>>>,
+    readonly scope: Scope.Closeable,
+    readonly shutdownHook: Future<never, void>,
+    readonly shutdownFlag: AtomicBoolean,
+    readonly strategy: Strategy<A>,
+  ) {
+    super();
+  }
+
+  awaitShutdown = this.shutdownHook.await;
+
+  capacity = this.hub.capacity;
+
+  isShutdown = IO.succeed(this.shutdownFlag.get);
+
+  shutdown = IO.fiberId.flatMap((fiberId) =>
+    IO.defer(() => {
+      this.shutdownFlag.set(true);
+      return this.scope
+        .close(Exit.interrupt(fiberId))
+        .zipRight(this.strategy.shutdown)
+        .whenIO(this.shutdownHook.succeed(undefined));
+    }),
+  ).uninterruptible;
+
+  size = IO.defer(() => {
+    if (this.shutdownFlag.get) {
+      return IO.interrupt;
+    }
+
+    return IO.succeed(this.hub.size());
+  });
+
+  subscribe: IO<Scope, never, Queue.Dequeue<A>> = IO.acquireRelease(
+    makeSubscription(this.hub, this.subscribers, this.strategy).tap((dequeue) =>
+      this.scope.addFinalizer(dequeue.shutdown),
+    ),
+    (dequeue) => dequeue.shutdown,
+  );
+
+  publish = (a: A): IO<never, never, boolean> =>
+    IO.defer(() => {
+      if (this.shutdownFlag.get) {
+        return IO.interrupt;
+      }
+
+      if (this.hub.publish(a)) {
+        this.strategy.unsafeCompleteSubscribers(this.hub, this.subscribers);
+        return IO.succeedNow(true);
+      }
+
+      return this.strategy.handleSurplus(this.hub, this.subscribers, Conc.single(a), this.shutdownFlag);
+    });
+
+  publishAll = (as: Iterable<A>): IO<never, never, boolean> =>
+    IO.defer(() => {
+      if (this.shutdownFlag.get) {
+        return IO.interrupt;
+      }
+
+      const surplus = this.hub.publishAll(as);
+
+      this.strategy.unsafeCompleteSubscribers(this.hub, this.subscribers);
+
+      if (surplus.isEmpty) {
+        return IO.succeedNow(true);
+      }
+
+      return this.strategy.handleSurplus(this.hub, this.subscribers, surplus, this.shutdownFlag);
+    });
+}
+
+/**
+ * Unsafely creates a hub with the specified strategy.
+ */
+export function unsafeMakeHub<A>(
+  hub: HubInternal<A>,
+  subscribers: HashSet<HashedPair<HubInternal.Subscription<A>, MutableQueue<Future<never, A>>>>,
+  scope: Scope.Closeable,
+  shutdownHook: Future<never, void>,
+  shutdownFlag: AtomicBoolean,
+  strategy: Strategy<A>,
+): Hub<A> {
+  return new UnsafeHub(hub, subscribers, scope, shutdownHook, shutdownFlag, strategy).unsafeCoerce();
+}
+
+export function makeHubInternal<A>(hub: HubInternal<A>, strategy: Strategy<A>): UIO<Hub<A>> {
+  return Do((_) => {
+    const scope  = _(Scope.make);
+    const future = _(Future.make<never, void>());
+    return unsafeMakeHub(hub, subscribersHashSet(), scope, future, new AtomicBoolean(false), strategy);
+  });
+}

package/_src/Hub.ts

@@ -1,4 +1,4 @@
 // codegen:start { preset: barrel, include: ./Hub/*.ts, exclude: ./Hub/*internal.ts }
-export * from "./Hub/constructors.js";
+export * from "./Hub/api.js";
 export * from "./Hub/definition.js";
 // codegen:end

package/_src/IO/api/asyncInterrupt.ts

@@ -0,0 +1,77 @@
+/**
+ * Imports an asynchronous side-effect into an IO. The side-effect
+ * has the option of returning the value synchronously, which is useful in
+ * cases where it cannot be determined if the effect is synchronous or
+ * asynchronous until the side-effect is actually executed. The effect also
+ * has the option of returning a canceler, which will be used by the runtime
+ * to cancel the asynchronous effect if the fiber executing the effect is
+ * interrupted.
+ *
+ * If the register function returns a value synchronously, then the callback
+ * function must not be called. Otherwise the callback function must be called
+ * at most once.
+ *
+ * The list of fibers, that may complete the async callback, is used to
+ * provide better diagnostics.
+ *
+ * @tsplus static fncts.io.IOOps asyncInterrupt
+ */
+export function asyncInterrupt<R, E, A>(
+  register: (cb: (resolve: IO<R, E, A>) => void) => Either<URIO<R, any>, IO<R, E, A>>,
+  blockingOn: FiberId = FiberId.none,
+  __tsplusTrace?: string,
+): IO<R, E, A> {
+  return IO.defer(() => {
+    let cancelerRef: URIO<R, any> = IO.unit!;
+    return IO.async<R, E, A>((k) => {
+      const result = register(k);
+      result.match(
+        (canceler) => {
+          cancelerRef = canceler;
+        },
+        (done) => {
+          k(done);
+        },
+      );
+    }, blockingOn).onInterrupt(() => cancelerRef);
+  });
+}
+
+/**
+ * Imports an asynchronous effect into a pure `IO`, possibly returning the value synchronously.
+ *
+ * If the register function returns a value synchronously, then the callback
+ * function must not be called. Otherwise the callback function must be called at most once.
+ *
+ * @tsplus static fncts.io.IOOps asyncMaybe
+ */
+export function asyncMaybe<R, E, A>(
+  register: (resolve: (_: IO<R, E, A>) => void) => Maybe<IO<R, E, A>>,
+  blockingOn: FiberId = FiberId.none,
+  __tsplusTrace?: string,
+): IO<R, E, A> {
+  return asyncInterrupt(
+    (cb) => register(cb).match(() => Either.left(IO.unit), Either.right),
+    blockingOn,
+    __tsplusTrace,
+  );
+}
+
+/**
+ * Returns a `IO` that will never produce anything. The moral equivalent of
+ * `while(true) {}`, only without the wasted CPU cycles.
+ *
+ * @tsplus static fncts.io.IOOps never
+ */
+export const never: UIO<never> = IO.defer(() =>
+  asyncInterrupt<never, never, never>(() => {
+    const interval = setInterval(() => {
+      //
+    }, 60000);
+    return Either.left(
+      IO.succeed(() => {
+        clearInterval(interval);
+      }),
+    );
+  }),
+);