@lsdsoftware/utils 2.1.1 → 2.3.0

package/README.md

@@ -29,32 +29,6 @@ const result = await semaphore.runTask(async () => {
 Observable wrapper for net.connect (see connect-socket.test.ts for usage)
 
 
-### Worker Rotator
-Rotate worker instances over a request stream.
-
-```typescript
-import { makeWorkerRotator } from "@lsdsoftware/utils"
-
-const subscription = makeWorkerRotator({
-  makeWorker,
-  workerTtlMs: 60_000,
-  request$,
-  maxPendingRequests: 100,
-  onEvent: event => console.debug('[worker-rotator]', event)
-}).subscribe()
-```
-
-Contract:
-
-- The returned observable is cold and does not emit values. Each subscription creates its own rotator engine and subscribes to `request$`; share the returned observable if you want one engine with multiple observers.
-- `onEvent` receives optional lifecycle events for logging, tracing, or diagnostics.
-- Requests emitted before the first worker is ready, or between workers, are buffered and handed to the next worker.
-- `maxPendingRequests` caps the no-worker buffer and errors the rotator when exceeded. The default is `Infinity`.
-- Pending requests are considered handed off once they are passed to `worker.process`. Delivery retries, acknowledgements, and exactly-once guarantees belong in the worker or an upstream queue.
-- Completing `request$` means no more input, but it does not define the rotator lifecycle. The engine runs until the returned observable is unsubscribed or errors.
-- `worker.relieve()` is called during worker teardown. Implementations should make it safe to call more than once.
-
-
 ### CLI Worker Rotator
 Rotate child processes that communicate over stdin/stdout using a line-oriented request/response protocol, such as JSONL.
 
@@ -75,6 +49,14 @@ const subscription = makeCLIWorkerRotator({
 
 Each request writes exactly one stdin line. Each stdout line is paired with the next pending request in order. Child processes should write logs to stderr.
 
-For custom framing or multiplexed protocols, implement `Worker<R>` directly and use `makeWorkerRotator`.
+Contract:
+
+- The returned observable is cold and does not emit values. Each subscription creates its own rotator engine and subscribes to `request$`; share the returned observable if you want one engine with multiple observers.
+- `onEvent` receives optional lifecycle events for logging, tracing, or diagnostics.
+- Requests emitted before the first child process is ready, or between child processes, are buffered and handed to the next child process.
+- `maxPendingRequests` caps the no-worker buffer and errors the rotator when exceeded. The default is `Infinity`.
+- Pending requests are considered handed off once they are written to a worker process. Delivery retries, acknowledgements, and exactly-once guarantees belong in the worker or an upstream queue.
+- Completing `request$` means no more input, but it does not define the rotator lifecycle. The engine runs until the returned observable is unsubscribed or errors.
+- Worker stdin is ended during teardown. Child processes should exit cleanly when stdin closes.
 
 If a worker exits before producing a matching stdout line for a written request, that request's `output$` is not resolved by this adapter. Apply timeout or cancellation around each request if the caller needs bounded waits.

package/dist/cli-worker-rotator.d.ts

@@ -1,9 +1,15 @@
 import type { ChildProcessByStdio } from "child_process";
 import * as rxjs from "rxjs";
 import type { Readable, Writable } from "stream";
-import { WorkerRotatorEvent } from "./worker-rotator.js";
 export type CLIWorker = ChildProcessByStdio<Writable, Readable, null>;
-export type CLIWorkerRotatorEvent = WorkerRotatorEvent<CLIWorker>;
+export type CLIWorkerRotatorEvent = {
+    type: 'hired' | 'relieved';
+    worker: CLIWorker;
+} | {
+    type: 'quit';
+    worker: CLIWorker;
+    reason: unknown;
+};
 export interface CLIRequest {
     input: string;
     output$: rxjs.SubjectLike<string>;

package/dist/cli-worker-rotator.js

@@ -1,18 +1,21 @@
 import * as rxjs from "rxjs";
 import { makeLineReader } from "./line-reader.js";
-import { makeWorkerRotator } from "./worker-rotator.js";
 /**
  * Rotates child processes that communicate over stdin/stdout using a
  * line-oriented request/response protocol, such as JSONL.
  * See the README for the protocol and lifecycle contract.
  */
-export function makeCLIWorkerRotator({ spawnWorkerProcess, workerTtlMs, request$, maxPendingRequests, onEvent }) {
-    return makeWorkerRotator({
-        makeWorker: () => makeWorker(spawnWorkerProcess),
-        workerTtlMs,
-        request$,
-        maxPendingRequests,
-        onEvent: event => onEvent?.({ ...event, worker: event.worker.child })
+export function makeCLIWorkerRotator({ spawnWorkerProcess, workerTtlMs, request$, maxPendingRequests = Infinity, onEvent }) {
+    return rxjs.defer(() => {
+        if (maxPendingRequests !== Infinity && (!Number.isInteger(maxPendingRequests) || maxPendingRequests < 0)) {
+            throw new RangeError('maxPendingRequests must be a non-negative integer or Infinity');
+        }
+        return rxjs.defer(() => makeWorker(spawnWorkerProcess)).pipe(rxjs.tap(worker => onEvent?.({ type: 'hired', worker: worker.child })), rxjs.exhaustMap(worker => rxjs.NEVER.pipe(rxjs.startWith(worker), rxjs.takeUntil(rxjs.race(worker.quit$, rxjs.timer(workerTtlMs).pipe(rxjs.map(() => 'Worker TTL expired'))).pipe(rxjs.tap(reason => onEvent?.({ type: 'quit', worker: worker.child, reason })))), rxjs.endWith(null), rxjs.finalize(() => {
+            worker.relieve();
+            onEvent?.({ type: 'relieved', worker: worker.child });
+        }))), rxjs.repeat(), rxjs.share(), worker$ => request$.pipe(rxjs.window(worker$), rxjs.zipWith(worker$.pipe(rxjs.startWith(null))), rxjs.mergeScan((pending, [window$, worker]) => rxjs.concat(pending, window$).pipe(worker
+            ? request$ => worker.process(request$).pipe(rxjs.startWith([]))
+            : request$ => request$.pipe(bufferRequests(maxPendingRequests))), []), rxjs.ignoreElements()));
     });
 }
 async function makeWorker(spawn) {
@@ -68,3 +71,12 @@ function writeLn(stream, line) {
         }
     });
 }
+function bufferRequests(maxPendingRequests) {
+    return request$ => request$.pipe(rxjs.reduce((pending, request) => {
+        if (pending.length >= maxPendingRequests) {
+            throw new Error(`Worker rotator exceeded max pending requests (${maxPendingRequests})`);
+        }
+        pending.push(request);
+        return pending;
+    }, []));
+}

package/dist/cli-worker-rotator.test.js

@@ -6,6 +6,29 @@ import { PassThrough, Writable } from "stream";
 import { makeCLIWorkerRotator } from "./cli-worker-rotator.js";
 describe('cli-worker-rotator', ({ test }) => {
     test('pairs stdout lines with requests in order', async () => {
+        const request$ = new rxjs.Subject;
+        const child = makeEchoChild({ autoSpawn: true });
+        const firstOutput$ = new rxjs.Subject;
+        const secondOutput$ = new rxjs.Subject;
+        const subscription = makeCLIWorkerRotator({
+            spawnWorkerProcess: () => child,
+            workerTtlMs: 1000,
+            request$
+        }).subscribe();
+        try {
+            request$.next({ input: 'one', output$: firstOutput$ });
+            request$.next({ input: 'two', output$: secondOutput$ });
+            const outputs = await Promise.all([
+                rxjs.firstValueFrom(firstOutput$),
+                rxjs.firstValueFrom(secondOutput$)
+            ]);
+            assert.deepStrictEqual(outputs, ['ONE', 'TWO']);
+        }
+        finally {
+            subscription.unsubscribe();
+        }
+    });
+    test('buffers requests before the first worker is ready', async () => {
         const request$ = new rxjs.Subject;
         const child = makeEchoChild();
         const firstOutput$ = new rxjs.Subject;
@@ -18,6 +41,7 @@ describe('cli-worker-rotator', ({ test }) => {
         try {
             request$.next({ input: 'one', output$: firstOutput$ });
             request$.next({ input: 'two', output$: secondOutput$ });
+            child.spawn();
             const outputs = await Promise.all([
                 rxjs.firstValueFrom(firstOutput$),
                 rxjs.firstValueFrom(secondOutput$)
@@ -28,11 +52,76 @@ describe('cli-worker-rotator', ({ test }) => {
             subscription.unsubscribe();
         }
     });
+    test('buffers requests between workers', async () => {
+        const request$ = new rxjs.Subject;
+        const firstChild = makeEchoChild({ autoSpawn: true });
+        const secondChild = makeEchoChild();
+        const children = [firstChild, secondChild];
+        const firstOutput$ = new rxjs.Subject;
+        const secondOutput$ = new rxjs.Subject;
+        const subscription = makeCLIWorkerRotator({
+            spawnWorkerProcess: () => children.shift(),
+            workerTtlMs: 1000,
+            request$
+        }).subscribe();
+        try {
+            request$.next({ input: 'one', output$: firstOutput$ });
+            assert.equal(await rxjs.firstValueFrom(firstOutput$), 'ONE');
+            firstChild.emit('close', 0, null);
+            request$.next({ input: 'two', output$: secondOutput$ });
+            secondChild.spawn();
+            assert.equal(await rxjs.firstValueFrom(secondOutput$), 'TWO');
+            assert(firstChild.stdinEnded);
+        }
+        finally {
+            subscription.unsubscribe();
+        }
+    });
+    test('errors when pending request cap is exceeded', async () => {
+        const request$ = new rxjs.Subject;
+        const child = makeEchoChild();
+        const error = defer();
+        makeCLIWorkerRotator({
+            spawnWorkerProcess: () => child,
+            workerTtlMs: 1000,
+            request$,
+            maxPendingRequests: 1
+        }).subscribe({
+            error: err => error.resolve(err)
+        });
+        request$.next({ input: 'one', output$: new rxjs.Subject });
+        request$.next({ input: 'two', output$: new rxjs.Subject });
+        const err = await error.promise;
+        assert(err instanceof Error);
+        assert.equal(err.message, 'Worker rotator exceeded max pending requests (1)');
+    });
+    test('reports lifecycle events', async () => {
+        const request$ = new rxjs.Subject;
+        const child = makeEchoChild({ autoSpawn: true });
+        const events = [];
+        const subscription = makeCLIWorkerRotator({
+            spawnWorkerProcess: () => child,
+            workerTtlMs: 1000,
+            request$,
+            onEvent: event => events.push(event)
+        }).subscribe();
+        try {
+            await waitFor(() => events.length >= 1);
+            child.emit('close', 0, null);
+            await waitFor(() => events.length >= 3);
+            assert.deepStrictEqual(events.slice(0, 3).map(event => event.type), ['hired', 'quit', 'relieved']);
+            assert.equal(events[1].type == 'quit' && events[1].reason, 'Worker exit 0');
+        }
+        finally {
+            subscription.unsubscribe();
+        }
+    });
 });
-function makeEchoChild() {
+function makeEchoChild({ autoSpawn = false } = {}) {
     const child = new EventEmitter();
     const stdout = new PassThrough();
     let remainder = '';
+    let stdinEnded = false;
     child.stdin = new Writable({
         write(chunk, _encoding, callback) {
             remainder += chunk.toString();
@@ -42,10 +131,37 @@ function makeEchoChild() {
                 stdout.write(line.toUpperCase() + '\n');
             }
             callback();
+        },
+        final(callback) {
+            stdinEnded = true;
+            callback();
         }
     });
     child.stdout = stdout;
     child.stderr = null;
-    setTimeout(() => child.emit('spawn'), 0);
+    child.spawn = () => child.emit('spawn');
+    Object.defineProperty(child, 'stdinEnded', {
+        get: () => stdinEnded
+    });
+    if (autoSpawn) {
+        setTimeout(() => child.spawn(), 0);
+    }
     return child;
 }
+function defer() {
+    let resolve;
+    let reject;
+    const promise = new Promise((resolvePromise, rejectPromise) => {
+        resolve = resolvePromise;
+        reject = rejectPromise;
+    });
+    return { promise, resolve, reject };
+}
+async function waitFor(condition) {
+    for (let i = 0; i < 100; i++) {
+        if (condition())
+            return;
+        await new Promise(resolve => setTimeout(resolve, 1));
+    }
+    assert(condition());
+}

package/dist/index.d.ts

@@ -2,4 +2,3 @@ export * from './connect-socket.js';
 export * from './cli-worker-rotator.js';
 export * from './line-reader.js';
 export * from './semaphore.js';
-export * from './worker-rotator.js';

package/dist/index.js

@@ -2,4 +2,3 @@ export * from './connect-socket.js';
 export * from './cli-worker-rotator.js';
 export * from './line-reader.js';
 export * from './semaphore.js';
-export * from './worker-rotator.js';

package/dist/index.test.d.ts

@@ -2,4 +2,3 @@ import './cli-worker-rotator.test.js';
 import './connect-socket.test.js';
 import './line-reader.test.js';
 import './semaphore.test.js';
-import './worker-rotator.test.js';

package/dist/index.test.js

@@ -2,4 +2,3 @@ import './cli-worker-rotator.test.js';
 import './connect-socket.test.js';
 import './line-reader.test.js';
 import './semaphore.test.js';
-import './worker-rotator.test.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lsdsoftware/utils",
   "type": "module",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "Useful JavaScript utilities",
   "main": "dist/index.js",
   "files": [

package/dist/worker-rotator.d.ts

@@ -1,26 +0,0 @@
-import * as rxjs from "rxjs";
-export interface Worker<R> {
-    process(request$: rxjs.Observable<R>): rxjs.Observable<never>;
-    relieve(): void;
-    quit$: rxjs.Observable<unknown>;
-}
-export type WorkerRotatorEvent<W> = {
-    type: 'hired' | 'expired' | 'relieved';
-    worker: W;
-} | {
-    type: 'quit';
-    worker: W;
-    reason: unknown;
-};
-export interface WorkerRotatorOptions<R, W extends Worker<R>> {
-    makeWorker: () => Promise<W>;
-    workerTtlMs: number;
-    request$: rxjs.Observable<R>;
-    maxPendingRequests?: number;
-    onEvent?: (event: WorkerRotatorEvent<W>) => void;
-}
-/**
- * Rotates workers over a request stream.
- * See the README for the lifecycle and buffering contract.
- */
-export declare function makeWorkerRotator<R, W extends Worker<R>>({ makeWorker, workerTtlMs, request$, maxPendingRequests, onEvent }: WorkerRotatorOptions<R, W>): rxjs.Observable<never>;

package/dist/worker-rotator.js

@@ -1,27 +0,0 @@
-import * as rxjs from "rxjs";
-/**
- * Rotates workers over a request stream.
- * See the README for the lifecycle and buffering contract.
- */
-export function makeWorkerRotator({ makeWorker, workerTtlMs, request$, maxPendingRequests = Infinity, onEvent }) {
-    return rxjs.defer(() => {
-        if (maxPendingRequests !== Infinity && (!Number.isInteger(maxPendingRequests) || maxPendingRequests < 0)) {
-            throw new RangeError('maxPendingRequests must be a non-negative integer or Infinity');
-        }
-        return rxjs.defer(() => makeWorker()).pipe(rxjs.tap(worker => onEvent?.({ type: 'hired', worker })), rxjs.exhaustMap(worker => rxjs.NEVER.pipe(rxjs.startWith(worker), rxjs.takeUntil(rxjs.race(worker.quit$.pipe(rxjs.tap(reason => onEvent?.({ type: 'quit', worker, reason }))), rxjs.timer(workerTtlMs).pipe(rxjs.tap(() => onEvent?.({ type: 'expired', worker }))))), rxjs.endWith(null), rxjs.finalize(() => {
-            worker.relieve();
-            onEvent?.({ type: 'relieved', worker });
-        }))), rxjs.repeat(), rxjs.share(), worker$ => request$.pipe(rxjs.window(worker$), rxjs.zipWith(worker$.pipe(rxjs.startWith(null))), rxjs.mergeScan((pending, [window$, worker]) => rxjs.concat(pending, window$).pipe(worker
-            ? request$ => worker.process(request$).pipe(rxjs.startWith([]))
-            : request$ => request$.pipe(bufferRequests(maxPendingRequests))), []), rxjs.ignoreElements()));
-    });
-}
-function bufferRequests(maxPendingRequests) {
-    return request$ => request$.pipe(rxjs.reduce((pending, request) => {
-        if (pending.length >= maxPendingRequests) {
-            throw new Error(`Worker rotator exceeded max pending requests (${maxPendingRequests})`);
-        }
-        pending.push(request);
-        return pending;
-    }, []));
-}

package/dist/worker-rotator.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/worker-rotator.test.js

@@ -1,149 +0,0 @@
-import { describe } from "@service-broker/test-utils";
-import assert from "assert";
-import * as rxjs from "rxjs";
-import { makeWorkerRotator } from "./worker-rotator.js";
-describe('worker-rotator', ({ test }) => {
-    test('buffers requests before the first worker is ready', async () => {
-        const request$ = new rxjs.Subject;
-        const worker = makeTestWorker();
-        const workerReady = defer();
-        const processed = [];
-        worker.processRequests$.subscribe(request => processed.push(request));
-        const subscription = makeWorkerRotator({
-            makeWorker: () => workerReady.promise,
-            workerTtlMs: 1000,
-            request$
-        }).subscribe();
-        try {
-            request$.next(1);
-            request$.next(2);
-            workerReady.resolve(worker);
-            await waitFor(() => processed.length == 2);
-            assert.deepStrictEqual(processed, [1, 2]);
-        }
-        finally {
-            subscription.unsubscribe();
-        }
-    });
-    test('buffers requests between workers', async () => {
-        const request$ = new rxjs.Subject;
-        const firstWorker = makeTestWorker();
-        const secondWorker = makeTestWorker();
-        const firstWorkerReady = defer();
-        const secondWorkerReady = defer();
-        const workersReady = [firstWorkerReady, secondWorkerReady];
-        const processed = [];
-        firstWorker.processRequests$.subscribe(request => processed.push(request));
-        secondWorker.processRequests$.subscribe(request => processed.push(request));
-        const subscription = makeWorkerRotator({
-            makeWorker: () => workersReady.shift().promise,
-            workerTtlMs: 1000,
-            request$
-        }).subscribe();
-        try {
-            firstWorkerReady.resolve(firstWorker);
-            await waitFor(() => firstWorker.processCalls == 1);
-            request$.next(1);
-            firstWorker.quit$.next('done');
-            request$.next(2);
-            secondWorkerReady.resolve(secondWorker);
-            await waitFor(() => processed.length == 2);
-            assert.deepStrictEqual(processed, [1, 2]);
-            assert(firstWorker.relieved);
-        }
-        finally {
-            subscription.unsubscribe();
-        }
-    });
-    test('errors when pending request cap is exceeded', async () => {
-        const request$ = new rxjs.Subject;
-        const workerReady = defer();
-        const error = defer();
-        makeWorkerRotator({
-            makeWorker: () => workerReady.promise,
-            workerTtlMs: 1000,
-            request$,
-            maxPendingRequests: 1
-        }).subscribe({
-            error: err => error.resolve(err)
-        });
-        request$.next(1);
-        request$.next(2);
-        const err = await error.promise;
-        assert(err instanceof Error);
-        assert.equal(err.message, 'Worker rotator exceeded max pending requests (1)');
-    });
-    test('reports lifecycle events', async () => {
-        const request$ = new rxjs.Subject;
-        const worker = makeTestWorker();
-        const events = [];
-        const subscription = makeWorkerRotator({
-            makeWorker: async () => worker,
-            workerTtlMs: 1000,
-            request$,
-            onEvent: event => events.push(event)
-        }).subscribe();
-        try {
-            await waitFor(() => events.length >= 1);
-            worker.quit$.next('done');
-            await waitFor(() => events.length >= 3);
-            assert.deepStrictEqual(events.slice(0, 3).map(event => event.type), ['hired', 'quit', 'relieved']);
-            assert.equal(events[1].type == 'quit' && events[1].reason, 'done');
-        }
-        finally {
-            subscription.unsubscribe();
-        }
-    });
-    test('reports expiration before relieving workers', async () => {
-        const request$ = new rxjs.Subject;
-        const worker = makeTestWorker();
-        const events = [];
-        const subscription = makeWorkerRotator({
-            makeWorker: async () => worker,
-            workerTtlMs: 1,
-            request$,
-            onEvent: event => events.push(event)
-        }).subscribe();
-        try {
-            await waitFor(() => events.some(event => event.type == 'expired'));
-            await waitFor(() => events.some(event => event.type == 'relieved'));
-            assert.deepStrictEqual(events.slice(0, 3).map(event => event.type), ['hired', 'expired', 'relieved']);
-        }
-        finally {
-            subscription.unsubscribe();
-        }
-    });
-});
-function makeTestWorker() {
-    const processRequests$ = new rxjs.Subject;
-    return {
-        processCalls: 0,
-        processRequests$,
-        quit$: new rxjs.Subject(),
-        relieved: false,
-        process(request$) {
-            this.processCalls++;
-            return request$.pipe(rxjs.tap(request => processRequests$.next(request)), rxjs.ignoreElements());
-        },
-        relieve() {
-            this.relieved = true;
-        }
-    };
-}
-function defer() {
-    let resolve;
-    let reject;
-    const promise = new Promise((resolvePromise, rejectPromise) => {
-        resolve = resolvePromise;
-        reject = rejectPromise;
-    });
-    return { promise, resolve, reject };
-}
-async function waitFor(condition) {
-    for (let i = 0; i < 100; i++) {
-        if (condition())
-            return;
-        await new Promise(resolve => setTimeout(resolve, 1));
-    }
-    assert(condition());
-}