@thi.ng/fibers 0.6.4 → 0.6.6

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-12-09T19:12:03Z
+- **Last updated**: 2023-12-18T13:41:19Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.

package/README.md

@@ -378,7 +378,7 @@ For Node.js REPL:
 const fibers = await import("@thi.ng/fibers");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.60 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.64 KB
 
 ## Dependencies
 

package/api.js

@@ -1,19 +1,18 @@
-export const STATE_NEW = 0;
-export const STATE_ACTIVE = 1;
-export const STATE_DONE = 2;
-export const STATE_CANCELED = 3;
-export const STATE_ERROR = 4;
-/**
- * Event ID for completed fiber. The event `value` will be the one given to
- * {@link Fiber.done} (if any).
- */
-export const EVENT_FIBER_DONE = "fiber-done";
-/**
- * Event ID for fiber cancellation.
- */
-export const EVENT_FIBER_CANCELED = "fiber-canceled";
-/**
- * Event ID for notifying about an error which occurred whilst executing a
- * fiber. The event `value` will be the error passed to {@link Fiber.catch}.
- */
-export const EVENT_FIBER_ERROR = "fiber-error";
+const STATE_NEW = 0;
+const STATE_ACTIVE = 1;
+const STATE_DONE = 2;
+const STATE_CANCELED = 3;
+const STATE_ERROR = 4;
+const EVENT_FIBER_DONE = "fiber-done";
+const EVENT_FIBER_CANCELED = "fiber-canceled";
+const EVENT_FIBER_ERROR = "fiber-error";
+export {
+  EVENT_FIBER_CANCELED,
+  EVENT_FIBER_DONE,
+  EVENT_FIBER_ERROR,
+  STATE_ACTIVE,
+  STATE_CANCELED,
+  STATE_DONE,
+  STATE_ERROR,
+  STATE_NEW
+};

package/csp.js

@@ -4,287 +4,208 @@ import { Fiber, fiber } from "./fiber.js";
 const STATE_OPEN = 0;
 const STATE_CLOSING = 1;
 const STATE_CLOSED = 2;
-/**
- * Fiber-based CSP channel implementation, supporting any
- * {@link IReadWriteBuffer} implementation to customize read/write behaviors
- * (and ordering). By default uses a single value {@link fifo} buffer impl.
- */
-export class Channel {
-    opts;
-    buffer;
-    state = STATE_OPEN;
-    constructor(buffer = 1, opts) {
-        this.opts = opts;
-        this.buffer = isNumber(buffer) ? new FIFOBuffer(buffer) : buffer;
-    }
-    /**
-     * Returns a new fiber which attempts to read a value from the channel and
-     * "blocks" until that value is available. Unless the channel has meanwhile
-     * been closed, the fiber returns the read value (otherwise: `undefined`).
-     *
-     * @remarks
-     * Depending on chosen back buffer behavior/implementation and
-     * {@link Channel.close}, read requests might still be successful whilst the
-     * channel is closing and there're still buffered values.
-     *
-     * @example
-     * ```ts
-     * const val = yield* chan.read();
-     * ```
-     */
-    read() {
-        const $this = this;
-        return fiber(function* (ctx) {
-            while ($this.readable()) {
-                // wait until channel is readable
-                if ($this.buffer.readable()) {
-                    const val = $this.buffer.read();
-                    ctx.logger?.debug("read", val);
-                    return val;
-                }
-                else if ($this.state === STATE_CLOSING) {
-                    return;
-                }
-                yield;
-            }
-        }, this.opts);
-    }
-    /**
-     * Returns a new fiber which attempts to write the given `value` to the
-     * channel and "blocks" until channel is writable (which depends on the
-     * channel's buffer implementation).
-     *
-     * @remarks
-     * Once the channel has been closed (or still is closing, see
-     * {@link Channel.close}), all write requests will be silently ignored.
-     *
-     * @example
-     * ```ts
-     * yield* chan.write(23);
-     * ```
-     */
-    write(val) {
-        const $this = this;
-        return fiber(function* (ctx) {
-            while ($this.writable()) {
-                // wait until channel is writable
-                if ($this.buffer.writable()) {
-                    ctx.logger?.debug("write", val);
-                    $this.buffer.write(val);
-                    return;
-                }
-                yield;
-            }
-        }, this.opts);
-    }
-    /**
-     * Returns new fiber which closes the channel. By default this op will defer
-     * the full closing until all buffered values have been read (by another
-     * fiber), however any writes will already become unavailable/ignored even
-     * at this stage (also see {@link Channel.write}). If `wait=false`, the
-     * channel will be closed immediately, the backing buffered cleared and any
-     * in-flight reads or writes will be canceled.
-     *
-     * @param wait
-     */
-    close(wait = true) {
-        const $this = this;
-        return fiber(function* (ctx) {
-            if ($this.state >= STATE_CLOSING)
-                return;
-            if (wait) {
-                ctx.logger?.debug("waiting to close...");
-                $this.state = STATE_CLOSING;
-                while ($this.buffer.readable())
-                    yield;
-            }
-            $this.state = STATE_CLOSED;
-            $this.buffer.clear();
-            ctx.logger?.debug("channel closed");
-        }, this.opts);
-    }
-    /**
-     * Returns true if the channel is principally readable (i.e. not yet
-     * closed), however there might not be any values available yet and reads
-     * might block.
-     */
-    readable() {
-        return this.state <= STATE_CLOSING;
-    }
-    /**
-     * Returns true if the channel is principally writable (i.e. not closing or
-     * closed), however depending on buffer behavior the channel might not yet
-     * accept new values and writes might block.
-     */
-    writable() {
-        return this.state === STATE_OPEN;
-    }
-    /**
-     * Returns true if the channel is fully closed and no further reads or
-     * writes are possible.
-     */
-    closed() {
-        return this.state === STATE_CLOSED;
-    }
+class Channel {
+  constructor(buffer = 1, opts) {
+    this.opts = opts;
+    this.buffer = isNumber(buffer) ? new FIFOBuffer(buffer) : buffer;
+  }
+  buffer;
+  state = STATE_OPEN;
+  /**
+   * Returns a new fiber which attempts to read a value from the channel and
+   * "blocks" until that value is available. Unless the channel has meanwhile
+   * been closed, the fiber returns the read value (otherwise: `undefined`).
+   *
+   * @remarks
+   * Depending on chosen back buffer behavior/implementation and
+   * {@link Channel.close}, read requests might still be successful whilst the
+   * channel is closing and there're still buffered values.
+   *
+   * @example
+   * ```ts
+   * const val = yield* chan.read();
+   * ```
+   */
+  read() {
+    const $this = this;
+    return fiber(function* (ctx) {
+      while ($this.readable()) {
+        if ($this.buffer.readable()) {
+          const val = $this.buffer.read();
+          ctx.logger?.debug("read", val);
+          return val;
+        } else if ($this.state === STATE_CLOSING) {
+          return;
+        }
+        yield;
+      }
+    }, this.opts);
+  }
+  /**
+   * Returns a new fiber which attempts to write the given `value` to the
+   * channel and "blocks" until channel is writable (which depends on the
+   * channel's buffer implementation).
+   *
+   * @remarks
+   * Once the channel has been closed (or still is closing, see
+   * {@link Channel.close}), all write requests will be silently ignored.
+   *
+   * @example
+   * ```ts
+   * yield* chan.write(23);
+   * ```
+   */
+  write(val) {
+    const $this = this;
+    return fiber(function* (ctx) {
+      while ($this.writable()) {
+        if ($this.buffer.writable()) {
+          ctx.logger?.debug("write", val);
+          $this.buffer.write(val);
+          return;
+        }
+        yield;
+      }
+    }, this.opts);
+  }
+  /**
+   * Returns new fiber which closes the channel. By default this op will defer
+   * the full closing until all buffered values have been read (by another
+   * fiber), however any writes will already become unavailable/ignored even
+   * at this stage (also see {@link Channel.write}). If `wait=false`, the
+   * channel will be closed immediately, the backing buffered cleared and any
+   * in-flight reads or writes will be canceled.
+   *
+   * @param wait
+   */
+  close(wait = true) {
+    const $this = this;
+    return fiber(function* (ctx) {
+      if ($this.state >= STATE_CLOSING)
+        return;
+      if (wait) {
+        ctx.logger?.debug("waiting to close...");
+        $this.state = STATE_CLOSING;
+        while ($this.buffer.readable())
+          yield;
+      }
+      $this.state = STATE_CLOSED;
+      $this.buffer.clear();
+      ctx.logger?.debug("channel closed");
+    }, this.opts);
+  }
+  /**
+   * Returns true if the channel is principally readable (i.e. not yet
+   * closed), however there might not be any values available yet and reads
+   * might block.
+   */
+  readable() {
+    return this.state <= STATE_CLOSING;
+  }
+  /**
+   * Returns true if the channel is principally writable (i.e. not closing or
+   * closed), however depending on buffer behavior the channel might not yet
+   * accept new values and writes might block.
+   */
+  writable() {
+    return this.state === STATE_OPEN;
+  }
+  /**
+   * Returns true if the channel is fully closed and no further reads or
+   * writes are possible.
+   */
+  closed() {
+    return this.state === STATE_CLOSED;
+  }
 }
-/**
- * Functional syntax sugar for {@link Channel} ctor, using provided backing
- * buffer and shared options for all fibers returned by the channel for its
- * various operations.
- *
- * @remarks
- * If `buffer` is given as number, a {@link fifo} buffer of given capacity will
- * be used.
- *
- * @example
- * ```ts
- * // create unbuffered channel with single value capacity
- * const chan = channel();
- *
- * // create channel with a fixed buffer capacity of 3 values
- * const chan2 = channel(3);
- *
- * // create channel with a sliding window buffer and custom ID & logger
- * const chan3 = channel(
- *   sliding(3),
- *   { id: "main", logger: new ConsoleLogger("chan") }
- * );
- * ```
- *
- * @param buffer
- * @param opts
- */
-export const channel = (buffer, opts) => new Channel(buffer, opts);
-/**
- * First-in, first-out ring buffer implementation for use with {@link Channel}.
- */
-export class FIFOBuffer {
-    buf;
-    rpos = 0;
-    wpos = 0;
-    constructor(cap = 1) {
-        assert(cap >= 1, `capacity must be >= 1`);
-        this.buf = new Array(cap + 1);
-    }
-    clear() {
-        this.buf.fill(undefined);
-    }
-    readable() {
-        return this.rpos !== this.wpos;
-    }
-    read() {
-        const { buf, rpos } = this;
-        const val = buf[rpos];
-        buf[rpos] = undefined;
-        this.rpos = (rpos + 1) % buf.length;
-        return val;
-    }
-    writable() {
-        return (this.wpos + 1) % this.buf.length !== this.rpos;
-    }
-    write(x) {
-        const { buf, wpos } = this;
-        buf[wpos] = x;
-        this.wpos = (wpos + 1) % buf.length;
-    }
+const channel = (buffer, opts) => new Channel(buffer, opts);
+class FIFOBuffer {
+  buf;
+  rpos = 0;
+  wpos = 0;
+  constructor(cap = 1) {
+    assert(cap >= 1, `capacity must be >= 1`);
+    this.buf = new Array(cap + 1);
+  }
+  clear() {
+    this.buf.fill(void 0);
+  }
+  readable() {
+    return this.rpos !== this.wpos;
+  }
+  read() {
+    const { buf, rpos } = this;
+    const val = buf[rpos];
+    buf[rpos] = void 0;
+    this.rpos = (rpos + 1) % buf.length;
+    return val;
+  }
+  writable() {
+    return (this.wpos + 1) % this.buf.length !== this.rpos;
+  }
+  write(x) {
+    const { buf, wpos } = this;
+    buf[wpos] = x;
+    this.wpos = (wpos + 1) % buf.length;
+  }
 }
-/**
- * Returns a {@link FIFOBuffer} ring buffer with given capacity for use with
- * {@link channel}.
- *
- * @remarks
- * With this implementation, writes to the channel will only start blocking once
- * the buffer's capacity is reached, otherwise complete immediately. Likewise,
- * channel reads are non-blocking whilst there're more buffered values
- * available. Reads will only block if the buffer is empty.
- *
- * Also see {@link lifo}.
- *
- * @param cap
- */
-export const fifo = (cap) => new FIFOBuffer(cap);
-export class LIFOBuffer {
-    cap;
-    buf = [];
-    constructor(cap = 1) {
-        this.cap = cap;
-        assert(cap >= 1, `capacity must be >= 1`);
-    }
-    clear() {
-        this.buf.length = 0;
-    }
-    readable() {
-        return this.buf.length > 0;
-    }
-    read() {
-        return this.buf.pop();
-    }
-    writable() {
-        return this.buf.length < this.cap;
-    }
-    write(x) {
-        this.buf.push(x);
-    }
+const fifo = (cap) => new FIFOBuffer(cap);
+class LIFOBuffer {
+  constructor(cap = 1) {
+    this.cap = cap;
+    assert(cap >= 1, `capacity must be >= 1`);
+  }
+  buf = [];
+  clear() {
+    this.buf.length = 0;
+  }
+  readable() {
+    return this.buf.length > 0;
+  }
+  read() {
+    return this.buf.pop();
+  }
+  writable() {
+    return this.buf.length < this.cap;
+  }
+  write(x) {
+    this.buf.push(x);
+  }
 }
-/**
- *  Returns a {@link LIFOBuffer} with given capacity for use with
- * {@link channel}.
- *
- * @remarks
- * Read/write behavior is mostly the same as with {@link fifo}, with the
- * important difference, that (as the name indicates), the last value written
- * will be the first value read (i.e. stack behavior).
- *
- * @param cap
- */
-export const lifo = (cap) => new LIFOBuffer(cap);
-export class SlidingBuffer extends FIFOBuffer {
-    writable() {
-        return true;
-    }
-    write(x) {
-        if (!super.writable()) {
-            const { buf, rpos } = this;
-            buf[rpos] = undefined;
-            this.rpos = (rpos + 1) % buf.length;
-        }
-        super.write(x);
-    }
+const lifo = (cap) => new LIFOBuffer(cap);
+class SlidingBuffer extends FIFOBuffer {
+  writable() {
+    return true;
+  }
+  write(x) {
+    if (!super.writable()) {
+      const { buf, rpos } = this;
+      buf[rpos] = void 0;
+      this.rpos = (rpos + 1) % buf.length;
+    }
+    super.write(x);
+  }
 }
-/**
- * Returns a {@link SlidingBuffer} with given capacity for use with
- * {@link channel}.
- *
- * @remarks
- * With this implementation, writes to the channel are **never** blocking! Once
- * the buffer's capacity is reached, a new write will first expunge the oldest
- * buffered value. Read behavior is the same as for {@link fifo}.
- *
- * Also see {@link dropping} for alternative behavior.
- *
- * @param cap
- */
-export const sliding = (cap) => new SlidingBuffer(cap);
-export class DroppingBuffer extends FIFOBuffer {
-    writable() {
-        return true;
-    }
-    write(x) {
-        if (super.writable())
-            super.write(x);
-    }
+const sliding = (cap) => new SlidingBuffer(cap);
+class DroppingBuffer extends FIFOBuffer {
+  writable() {
+    return true;
+  }
+  write(x) {
+    if (super.writable())
+      super.write(x);
+  }
 }
-/**
- * Returns a {@link DroppingBuffer} with given capacity for use with
- * {@link channel}.
- *
- * @remarks
- * With this implementation, writes to the channel are **never** blocking!
- * Whilst the buffer's capacity is reached, new writes will be silently ignored.
- * Read behavior is the same as for {@link fifo}.
- *
- * Also see {@link sliding} for alternative behavior.
- *
- * @param cap
- */
-export const dropping = (cap) => new DroppingBuffer(cap);
+const dropping = (cap) => new DroppingBuffer(cap);
+export {
+  Channel,
+  DroppingBuffer,
+  FIFOBuffer,
+  LIFOBuffer,
+  SlidingBuffer,
+  channel,
+  dropping,
+  fifo,
+  lifo,
+  sliding
+};