@grafema/rfdb-client 0.2.5-beta → 0.2.7

package/ts/stream-queue.test.ts

@@ -0,0 +1,114 @@
+/**
+ * StreamQueue Unit Tests
+ *
+ * Tests for the push-pull adapter that bridges socket events
+ * to async generator iteration. Pure data structure tests — no server dependency.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { StreamQueue } from '../dist/stream-queue.js';
+
+describe('StreamQueue', () => {
+  it('push then pull — items available immediately', async () => {
+    const q = new StreamQueue<number>();
+    q.push(1);
+    q.push(2);
+
+    const r1 = await q.next();
+    assert.deepStrictEqual(r1, { value: 1, done: false });
+    const r2 = await q.next();
+    assert.deepStrictEqual(r2, { value: 2, done: false });
+  });
+
+  it('pull then push — Promise resolves when item arrives', async () => {
+    const q = new StreamQueue<number>();
+
+    // Start waiting before any items
+    const promise = q.next();
+
+    // Push resolves the waiting consumer
+    q.push(42);
+
+    const result = await promise;
+    assert.deepStrictEqual(result, { value: 42, done: false });
+  });
+
+  it('end() terminates iteration', async () => {
+    const q = new StreamQueue<number>();
+    q.push(1);
+    q.end();
+
+    const r1 = await q.next();
+    assert.deepStrictEqual(r1, { value: 1, done: false });
+
+    const r2 = await q.next();
+    assert.strictEqual(r2.done, true);
+  });
+
+  it('fail() rejects waiting consumers', async () => {
+    const q = new StreamQueue<number>();
+
+    const promise = q.next();
+    q.fail(new Error('test error'));
+
+    await assert.rejects(promise, { message: 'test error' });
+  });
+
+  it('return() aborts stream', async () => {
+    const q = new StreamQueue<number>();
+    q.push(1);
+    q.push(2);
+
+    const r = await q.return();
+    assert.strictEqual(r.done, true);
+
+    // After return, next() returns done
+    const r2 = await q.next();
+    assert.strictEqual(r2.done, true);
+  });
+
+  it('for-await-of integration', async () => {
+    const q = new StreamQueue<number>();
+    q.push(1);
+    q.push(2);
+    q.push(3);
+    q.end();
+
+    const collected: number[] = [];
+    for await (const item of q) {
+      collected.push(item);
+    }
+
+    assert.deepStrictEqual(collected, [1, 2, 3]);
+  });
+
+  it('end() resolves pending waiters with done', async () => {
+    const q = new StreamQueue<number>();
+
+    const promise = q.next();
+    q.end();
+
+    const result = await promise;
+    assert.strictEqual(result.done, true);
+  });
+
+  it('push after end is ignored', async () => {
+    const q = new StreamQueue<number>();
+    q.push(1);
+    q.end();
+    q.push(2); // Should be ignored
+
+    const r1 = await q.next();
+    assert.deepStrictEqual(r1, { value: 1, done: false });
+    const r2 = await q.next();
+    assert.strictEqual(r2.done, true);
+  });
+
+  it('fail() then next() rejects immediately', async () => {
+    const q = new StreamQueue<number>();
+    q.fail(new Error('broken'));
+
+    await assert.rejects(q.next(), { message: 'broken' });
+  });
+});

package/ts/stream-queue.ts

@@ -0,0 +1,83 @@
+/**
+ * StreamQueue<T> — Push-pull adapter for bridging event-driven data
+ * arrival (socket responses) to pull-based async iteration (for...await).
+ *
+ * Used by RFDBClient to bridge _handleResponse (push) to
+ * queryNodesStream() (pull via async generator).
+ *
+ * Backpressure model:
+ * - Producer is faster: items buffer in `queue` (unbounded for V1 —
+ *   TCP flow control on Unix socket provides natural backpressure)
+ * - Consumer is faster: consumer waits on a pending Promise
+ */
+export class StreamQueue<T> {
+  private _queue: T[] = [];
+  private _waiters: Array<{
+    resolve: (result: IteratorResult<T, undefined>) => void;
+    reject: (error: Error) => void;
+  }> = [];
+  private _done: boolean = false;
+  private _error: Error | null = null;
+
+  /** Push an item into the queue. If a consumer is waiting, resolves immediately. */
+  push(item: T): void {
+    if (this._done) return;
+    if (this._waiters.length > 0) {
+      const waiter = this._waiters.shift()!;
+      waiter.resolve({ value: item, done: false });
+    } else {
+      this._queue.push(item);
+    }
+  }
+
+  /** Signal that no more items will be pushed. Resolves all waiting consumers. */
+  end(): void {
+    this._done = true;
+    while (this._waiters.length > 0) {
+      const waiter = this._waiters.shift()!;
+      waiter.resolve({ value: undefined, done: true });
+    }
+  }
+
+  /** Signal an error. Rejects all waiting consumers. */
+  fail(error: Error): void {
+    this._error = error;
+    this._done = true;
+    while (this._waiters.length > 0) {
+      const waiter = this._waiters.shift()!;
+      waiter.reject(error);
+    }
+  }
+
+  /** Pull the next item. Returns immediately if buffered, otherwise waits. */
+  next(): Promise<IteratorResult<T, undefined>> {
+    if (this._error) {
+      return Promise.reject(this._error);
+    }
+
+    if (this._queue.length > 0) {
+      const item = this._queue.shift()!;
+      return Promise.resolve({ value: item, done: false as const });
+    }
+
+    if (this._done) {
+      return Promise.resolve({ value: undefined, done: true as const });
+    }
+
+    return new Promise((resolve, reject) => {
+      this._waiters.push({ resolve, reject });
+    });
+  }
+
+  /** Consumer abort. Clears buffer and marks stream as done. */
+  return(): Promise<IteratorResult<T, undefined>> {
+    this._done = true;
+    this._queue = [];
+    this._waiters = [];
+    return Promise.resolve({ value: undefined, done: true as const });
+  }
+
+  [Symbol.asyncIterator](): AsyncIterableIterator<T> {
+    return this;
+  }
+}