@lsdsoftware/utils 2.1.0 → 2.1.1

package/README.md

@@ -30,22 +30,24 @@ Observable wrapper for net.connect (see connect-socket.test.ts for usage)
 
 
 ### Worker Rotator
-Rotate worker instances over a request stream and emit worker lifecycle events.
+Rotate worker instances over a request stream.
 
 ```typescript
 import { makeWorkerRotator } from "@lsdsoftware/utils"
 
-const events$ = makeWorkerRotator({
+const subscription = makeWorkerRotator({
   makeWorker,
   workerTtlMs: 60_000,
   request$,
-  maxPendingRequests: 100
-})
+  maxPendingRequests: 100,
+  onEvent: event => console.debug('[worker-rotator]', event)
+}).subscribe()
 ```
 
 Contract:
 
-- The returned observable is cold. Each subscription creates its own rotator engine and subscribes to `request$`; share the returned observable if you want one engine with multiple observers.
+- 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.
@@ -60,14 +62,15 @@ Rotate child processes that communicate over stdin/stdout using a line-oriented
 import { spawn } from "node:child_process"
 import { makeCLIWorkerRotator } from "@lsdsoftware/utils"
 
-const events$ = makeCLIWorkerRotator({
+const subscription = makeCLIWorkerRotator({
   spawnWorkerProcess: () => spawn("my-jsonl-worker", {
     stdio: ["pipe", "pipe", "inherit"]
   }),
   workerTtlMs: 60_000,
   request$,
-  maxPendingRequests: 100
-})
+  maxPendingRequests: 100,
+  onEvent: event => console.debug('[cli-worker-rotator]', event)
+}).subscribe()
 ```
 
 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.

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

@@ -13,10 +13,11 @@ export interface CLIWorkerRotatorOptions {
     workerTtlMs: number;
     request$: rxjs.Observable<CLIRequest>;
     maxPendingRequests?: number;
+    onEvent?: (event: CLIWorkerRotatorEvent) => void;
 }
 /**
  * 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 declare function makeCLIWorkerRotator({ spawnWorkerProcess, workerTtlMs, request$, maxPendingRequests }: CLIWorkerRotatorOptions): rxjs.Observable<CLIWorkerRotatorEvent>;
+export declare function makeCLIWorkerRotator({ spawnWorkerProcess, workerTtlMs, request$, maxPendingRequests, onEvent }: CLIWorkerRotatorOptions): rxjs.Observable<never>;

package/dist/cli-worker-rotator.js

@@ -6,13 +6,14 @@ import { makeWorkerRotator } from "./worker-rotator.js";
  * line-oriented request/response protocol, such as JSONL.
  * See the README for the protocol and lifecycle contract.
  */
-export function makeCLIWorkerRotator({ spawnWorkerProcess, workerTtlMs, request$, maxPendingRequests }) {
+export function makeCLIWorkerRotator({ spawnWorkerProcess, workerTtlMs, request$, maxPendingRequests, onEvent }) {
     return makeWorkerRotator({
         makeWorker: () => makeWorker(spawnWorkerProcess),
         workerTtlMs,
         request$,
-        maxPendingRequests
-    }).pipe(rxjs.map(event => ({ ...event, worker: event.worker.child })));
+        maxPendingRequests,
+        onEvent: event => onEvent?.({ ...event, worker: event.worker.child })
+    });
 }
 async function makeWorker(spawn) {
     const child = spawn();

package/dist/worker-rotator.d.ts

@@ -5,7 +5,7 @@ export interface Worker<R> {
     quit$: rxjs.Observable<unknown>;
 }
 export type WorkerRotatorEvent<W> = {
-    type: 'hired' | 'relieved';
+    type: 'hired' | 'expired' | 'relieved';
     worker: W;
 } | {
     type: 'quit';
@@ -17,9 +17,10 @@ export interface WorkerRotatorOptions<R, W extends Worker<R>> {
     workerTtlMs: number;
     request$: rxjs.Observable<R>;
     maxPendingRequests?: number;
+    onEvent?: (event: WorkerRotatorEvent<W>) => void;
 }
 /**
- * Rotates workers over a request stream and emits worker lifecycle events.
+ * 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 }: WorkerRotatorOptions<R, W>): rxjs.Observable<WorkerRotatorEvent<W>>;
+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,20 +1,19 @@
 import * as rxjs from "rxjs";
 /**
- * Rotates workers over a request stream and emits worker lifecycle events.
+ * Rotates workers over a request stream.
  * See the README for the lifecycle and buffering contract.
  */
-export function makeWorkerRotator({ makeWorker, workerTtlMs, request$, maxPendingRequests = Infinity }) {
+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');
         }
-        const eventSubject = new rxjs.ReplaySubject(1);
-        return rxjs.defer(() => makeWorker()).pipe(rxjs.tap(worker => eventSubject?.next({ type: 'hired', worker })), 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 => eventSubject?.next({ type: 'quit', worker, reason })))), rxjs.endWith(null), rxjs.finalize(() => {
+        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();
-            eventSubject?.next({ type: 'relieved', worker });
+            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()), rxjs.mergeWith(eventSubject));
+            : request$ => request$.pipe(bufferRequests(maxPendingRequests))), []), rxjs.ignoreElements()));
     });
 }
 function bufferRequests(maxPendingRequests) {

package/dist/worker-rotator.test.js

@@ -73,15 +73,16 @@ describe('worker-rotator', ({ test }) => {
         assert(err instanceof Error);
         assert.equal(err.message, 'Worker rotator exceeded max pending requests (1)');
     });
-    test('emits lifecycle events', async () => {
+    test('reports lifecycle events', async () => {
         const request$ = new rxjs.Subject;
         const worker = makeTestWorker();
         const events = [];
         const subscription = makeWorkerRotator({
             makeWorker: async () => worker,
             workerTtlMs: 1000,
-            request$
-        }).subscribe(event => events.push(event));
+            request$,
+            onEvent: event => events.push(event)
+        }).subscribe();
         try {
             await waitFor(() => events.length >= 1);
             worker.quit$.next('done');
@@ -93,6 +94,25 @@ describe('worker-rotator', ({ test }) => {
             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;

package/package.json

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