@thi.ng/fibers 0.6.35 → 1.0.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-03-27T09:53:45Z
+- **Last updated**: 2024-04-11T12:32:44Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,17 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+# [1.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/fibers@1.0.0) (2024-04-11)
+
+#### 🛑 Breaking changes
+
+- remove/migrate CSP buffer types, update readme ([d4a1d23](https://github.com/thi-ng/umbrella/commit/d4a1d23))
+- BREAKING CHANGE: remove obsolete CSP buffer types & impls, re-use from [@thi.ng/buffers](https://github.com/thi-ng/umbrella/tree/main/packages/buffers) (see [55ba21b50f](https://github.com/thi-ng/umbrella/commit/55ba21b50f))
+  - remove IReadBuffer & IReadWriteBuffer interfaces
+  - update deps (add [@thi.ng/buffers](https://github.com/thi-ng/umbrella/tree/main/packages/buffers))
+  - update docs
+  - update readme
+
 ## [0.6.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/fibers@0.6.0) (2023-11-09)
 
 #### 🚀 Features

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 190 standalone projects, maintained as part
+> This is one of 192 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -203,8 +203,9 @@ values are being read, essentially a memory management issue).
 
 #### Buffering behaviors
 
-The following channel buffer types/behaviors are included, all accepting a max.
-capacity and all implementing the
+The following channel buffer types/behaviors are included (from the
+[thi.ng/buffers](https://thi.ng/buffers) package), all accepting a max. capacity
+and all implementing the
 [IReadWriteBuffer](https://docs.thi.ng/umbrella/fibers/interfaces/IReadWriteBuffer.html)
 interface required by the channel:
 
@@ -214,17 +215,18 @@ interface required by the channel:
   channel reads are non-blocking whilst there're more buffered values available.
   Reads will only block if the buffer is empty.
 - [`lifo`](https://docs.thi.ng/umbrella/fibers/functions/lifo.html): Last in,
-  first out. Read/write behavior is mostly the same as with `fifo`, with the
-  important difference, that (as the name indicates), the last value written
-  will be the first value read (i.e. stack behavior).
+  first out. Write behavior is the same as with `fifo`, reads are in reverse
+  order (as the name indicates), i.e. the last value written will be the first
+  value read (i.e. stack behavior).
 - [`sliding`](https://docs.thi.ng/umbrella/fibers/functions/sliding.html):
-  Sliding window ring buffer. Writes to the channel are **never** blocking! Once
-  the buffer's capacity is reached, a new write will first expunge the oldest
-  buffered value (similar to LRU cache behavior). Read behavior is the same as
-  for `fifo`.
+  Sliding window ring buffer. Writes to the channel are **never** blocking!
+  Whilst the buffer is at full capacity, new writes will first expunge the
+  oldest buffered value (similar to [LRU
+  cache](https://github.com/thi-ng/umbrella/blob/develop/packages/cache/README.md#lru)
+  behavior). Read behavior is the same as for `fifo`.
 - [`dropping`](https://docs.thi.ng/umbrella/fibers/functions/dropping.html):
   Dropping value ring buffer. Writes to the channel are **never** blocking!
-  Whilst the buffer's capacity is reached, new writes will be silently ignored.
+  Whilst the buffer is at full capacity, new writes will be silently ignored.
   Read behavior is the same as for `fifo`.
 
 #### Channels
@@ -375,7 +377,13 @@ if (res !== undefined) {
 yarn add @thi.ng/fibers
 ```
 
-ES module import:
+ESM import:
+
+```ts
+import * as fib from "@thi.ng/fibers";
+```
+
+Browser ESM import:
 
 ```html
 <script type="module" src="https://cdn.skypack.dev/@thi.ng/fibers"></script>
@@ -386,16 +394,17 @@ ES module import:
 For Node.js REPL:
 
 ```js
-const fibers = await import("@thi.ng/fibers");
+const fib = await import("@thi.ng/fibers");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.64 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.45 KB
 
 ## Dependencies
 
 - [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
 - [@thi.ng/arrays](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays)
 - [@thi.ng/bench](https://github.com/thi-ng/umbrella/tree/develop/packages/bench)
+- [@thi.ng/buffers](https://github.com/thi-ng/umbrella/tree/develop/packages/buffers)
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
 - [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
 - [@thi.ng/idgen](https://github.com/thi-ng/umbrella/tree/develop/packages/idgen)

package/api.d.ts

@@ -1,4 +1,4 @@
-import type { Fn, Fn2, IClear, IIDGen } from "@thi.ng/api";
+import type { Fn, Fn2, IIDGen } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
 import type { Fiber } from "./fiber.js";
 export type FiberFactory<T = any> = (f: Fiber<T>) => Generator<unknown, T, unknown>;
@@ -68,27 +68,4 @@ export declare const EVENT_FIBER_CANCELED = "fiber-canceled";
  */
 export declare const EVENT_FIBER_ERROR = "fiber-error";
 export type FiberEventType = typeof EVENT_FIBER_DONE | typeof EVENT_FIBER_CANCELED | typeof EVENT_FIBER_ERROR | "*";
-export interface IReadBuffer<T> {
-    /**
-     * Returns true iff the buffer has at least one value available for reading.
-     */
-    readable(): boolean;
-    /**
-     * Unguarded read operation. Assumes the caller checked
-     * {@link IReadBuffer.readable} immediately before. Returns next value from
-     * buffer.
-     */
-    read(): T;
-}
-export interface IReadWriteBuffer<T> extends IReadBuffer<T>, IClear {
-    /**
-     * Returns true iff the buffer has at least one slot available for writing.
-     */
-    writable(): boolean;
-    /**
-     * Unguarded write operation. Assumes the caller checked
-     * {@link IReadWriteBuffer.writable} immediately before.
-     */
-    write(x: T): void;
-}
 //# sourceMappingURL=api.d.ts.map

package/csp.d.ts

@@ -1,4 +1,9 @@
-import type { FiberOpts, IReadWriteBuffer } from "./api.js";
+import type { IReadWriteBuffer } from "@thi.ng/buffers";
+import { DroppingBuffer } from "@thi.ng/buffers/dropping";
+import { FIFOBuffer } from "@thi.ng/buffers/fifo";
+import { LIFOBuffer } from "@thi.ng/buffers/lifo";
+import { SlidingBuffer } from "@thi.ng/buffers/sliding";
+import type { FiberOpts } from "./api.js";
 import { Fiber } from "./fiber.js";
 declare const STATE_OPEN = 0;
 declare const STATE_CLOSING = 1;
@@ -6,8 +11,9 @@ declare const STATE_CLOSED = 2;
 type CSPState = typeof STATE_OPEN | typeof STATE_CLOSING | typeof STATE_CLOSED;
 /**
  * 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.
+ * [IReadWriteBuffer](https://docs.thi.ng/umbrella/buffers/interfaces/IReadWriteBuffer.html)
+ * implementation to customize read/write behaviors (and ordering). By default
+ * uses a single value {@link fifo} buffer impl.
  */
 export declare class Channel<T> {
     opts?: Partial<FiberOpts> | undefined;
@@ -105,20 +111,6 @@ export declare class Channel<T> {
  * @param opts
  */
 export declare const channel: <T>(buffer?: IReadWriteBuffer<T> | number, opts?: Partial<FiberOpts>) => Channel<T>;
-/**
- * First-in, first-out ring buffer implementation for use with {@link Channel}.
- */
-export declare class FIFOBuffer<T> implements IReadWriteBuffer<T> {
-    protected buf: (T | undefined)[];
-    protected rpos: number;
-    protected wpos: number;
-    constructor(cap?: number);
-    clear(): void;
-    readable(): boolean;
-    read(): NonNullable<T>;
-    writable(): boolean;
-    write(x: T): void;
-}
 /**
  * Returns a {@link FIFOBuffer} ring buffer with given capacity for use with
  * {@link channel}.
@@ -134,57 +126,41 @@ export declare class FIFOBuffer<T> implements IReadWriteBuffer<T> {
  * @param cap
  */
 export declare const fifo: <T>(cap: number) => FIFOBuffer<T>;
-export declare class LIFOBuffer<T> implements IReadWriteBuffer<T> {
-    protected cap: number;
-    protected buf: T[];
-    constructor(cap?: number);
-    clear(): void;
-    readable(): boolean;
-    read(): NonNullable<T>;
-    writable(): boolean;
-    write(x: T): void;
-}
 /**
  *  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).
+ *  Write behavior is the same as with {@link fifo}, reads are in reverse order
+ *  (as the name indicates), i.e. the last value written will be the first value
+ *  read (i.e. stack behavior).
  *
  * @param cap
  */
 export declare const lifo: <T>(cap: number) => LIFOBuffer<T>;
-export declare class SlidingBuffer<T> extends FIFOBuffer<T> {
-    writable(): boolean;
-    write(x: T): void;
-}
 /**
  * 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}.
+ * With this implementation, writes to the channel are **never** blocking!
+ * Whilst the buffer is at full capacity, new writes will first expunge the
+ * oldest buffered value (similar to [LRU
+ * cache](https://github.com/thi-ng/umbrella/blob/develop/packages/cache/README.md#lru)
+ * behavior). Read behavior is the same as for {@link fifo}.
  *
  * Also see {@link dropping} for alternative behavior.
  *
  * @param cap
  */
 export declare const sliding: <T>(cap: number) => SlidingBuffer<T>;
-export declare class DroppingBuffer<T> extends FIFOBuffer<T> {
-    writable(): boolean;
-    write(x: T): void;
-}
 /**
  * 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.
+ * Whilst the buffer is at full capacity, new writes will be silently ignored.
  * Read behavior is the same as for {@link fifo}.
  *
  * Also see {@link sliding} for alternative behavior.

package/csp.js

@@ -1,5 +1,8 @@
-import { isNumber } from "@thi.ng/checks";
-import { assert } from "@thi.ng/errors/assert";
+import { DroppingBuffer } from "@thi.ng/buffers/dropping";
+import { FIFOBuffer } from "@thi.ng/buffers/fifo";
+import { LIFOBuffer } from "@thi.ng/buffers/lifo";
+import { SlidingBuffer } from "@thi.ng/buffers/sliding";
+import { isNumber } from "@thi.ng/checks/is-number";
 import { Fiber, fiber } from "./fiber.js";
 const STATE_OPEN = 0;
 const STATE_CLOSING = 1;
@@ -119,90 +122,12 @@ class Channel {
   }
 }
 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;
-  }
-}
 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);
-  }
-}
 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);
-  }
-}
 const sliding = (cap) => new SlidingBuffer(cap);
-class DroppingBuffer extends FIFOBuffer {
-  writable() {
-    return true;
-  }
-  write(x) {
-    if (super.writable())
-      super.write(x);
-  }
-}
 const dropping = (cap) => new DroppingBuffer(cap);
 export {
   Channel,
-  DroppingBuffer,
-  FIFOBuffer,
-  LIFOBuffer,
-  SlidingBuffer,
   channel,
   dropping,
   fifo,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/fibers",
-  "version": "0.6.35",
+  "version": "1.0.0",
   "description": "Process hierarchies & operators for cooperative multitasking",
   "type": "module",
   "module": "./index.js",
@@ -36,14 +36,15 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.31",
-    "@thi.ng/arrays": "^2.9.1",
-    "@thi.ng/bench": "^3.5.1",
-    "@thi.ng/checks": "^3.5.5",
-    "@thi.ng/errors": "^2.5.2",
-    "@thi.ng/idgen": "^2.2.36",
-    "@thi.ng/logger": "^3.0.7",
-    "@thi.ng/random": "^3.7.1"
+    "@thi.ng/api": "^8.10.1",
+    "@thi.ng/arrays": "^2.9.3",
+    "@thi.ng/bench": "^3.5.3",
+    "@thi.ng/buffers": "^0.1.0",
+    "@thi.ng/checks": "^3.6.1",
+    "@thi.ng/errors": "^2.5.4",
+    "@thi.ng/idgen": "^2.2.38",
+    "@thi.ng/logger": "^3.0.9",
+    "@thi.ng/random": "^3.7.3"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.43.0",
@@ -109,5 +110,5 @@
     "status": "alpha",
     "year": 2023
   },
-  "gitHead": "ce5ae2a322d50a7ce8ecccbd94fa55c496ba04fd\n"
+  "gitHead": "18a0c063a7b33d790e5bc2486c106f45f663ac28\n"
 }