@livestore/utils 0.4.0-dev.3 → 0.4.0-dev.6

package/src/effect/SubscriptionRef.ts

@@ -1,5 +1,4 @@
-import type { SubscriptionRef } from 'effect'
-import { Chunk, Effect, pipe, Stream } from 'effect'
+import { Chunk, Effect, pipe, Stream, SubscriptionRef } from 'effect'
 import { dual } from 'effect/Function'
 import type { Predicate, Refinement } from 'effect/Predicate'
 
@@ -20,3 +19,16 @@ export const waitUntil: {
 } = dual(2, <A>(sref: SubscriptionRef.SubscriptionRef<A>, predicate: (a: A) => boolean) =>
   pipe(sref.changes, Stream.filter(predicate), Stream.take(1), Stream.runCollect, Effect.map(Chunk.unsafeHead)),
 )
+
+export const fromStream = <A>(stream: Stream.Stream<A>, initialValue: A) =>
+  Effect.gen(function* () {
+    const sref = yield* SubscriptionRef.make(initialValue)
+
+    yield* stream.pipe(
+      Stream.tap((a) => SubscriptionRef.set(sref, a)),
+      Stream.runDrain,
+      Effect.forkScoped,
+    )
+
+    return sref
+  })

package/src/effect/WebSocket.ts

@@ -88,7 +88,7 @@ export const makeWebSocket = ({
             socket.close(1000)
           }
         } catch (error) {
-          yield* Effect.die(new WebSocketError({ cause: error }))
+          return yield* Effect.die(new WebSocketError({ cause: error }))
         }
       }),
     )

package/src/effect/index.ts

@@ -1,6 +1,7 @@
 import '../global.ts'
 
-export * as OtelTracer from '@effect/opentelemetry/Tracer'
+export { AiError, AiLanguageModel, AiModel, AiTool, AiToolkit, McpSchema, McpServer } from '@effect/ai'
+export * as Otlp from '@effect/opentelemetry/Otlp'
 export {
   Command,
   CommandExecutor,
@@ -8,6 +9,11 @@ export {
   FetchHttpClient,
   FileSystem,
   Headers,
+  HttpApi,
+  HttpApiClient,
+  HttpApiEndpoint,
+  HttpApiGroup,
+  HttpApp,
   HttpClient,
   HttpClientError,
   HttpClientRequest,
@@ -18,6 +24,7 @@ export {
   HttpServerRequest,
   HttpServerResponse,
   KeyValueStore,
+  MsgPack,
   Socket,
   Terminal,
   Transferable,
@@ -29,7 +36,8 @@ export {
 export { BrowserWorker, BrowserWorkerRunner } from '@effect/platform-browser'
 export {
   Rpc,
-  RpcClient,
+  // RpcClient, // TODO bring back "original" RpcClient from effect/rpc
+  RpcClientError,
   RpcGroup,
   RpcMessage,
   RpcMiddleware,
@@ -47,8 +55,8 @@ export {
   Cause,
   Channel,
   Chunk,
-  // Logger,
   Config,
+  ConfigError,
   Console,
   Context,
   Data,
@@ -58,6 +66,7 @@ export {
   Equal,
   ExecutionStrategy,
   Exit,
+  FastCheck,
   Fiber,
   FiberHandle,
   FiberId,
@@ -107,13 +116,15 @@ export {
   Tracer,
   Types,
 } from 'effect'
-export { dual } from 'effect/Function'
+export type { NonEmptyArray } from 'effect/Array'
+export { constVoid, dual } from 'effect/Function'
 export { TreeFormatter } from 'effect/ParseResult'
 export type { Serializable, SerializableWithResult } from 'effect/Schema'
-
 export * as SchemaAST from 'effect/SchemaAST'
 export * as BucketQueue from './BucketQueue.ts'
 export * as Logger from './Logger.ts'
+export * as OtelTracer from './OtelTracer.ts'
+export * as RpcClient from './RpcClient.ts'
 export * as Schema from './Schema/index.ts'
 export * as Stream from './Stream.ts'
 export * as Subscribable from './Subscribable.ts'

package/src/global.ts

@@ -1,5 +1,6 @@
 declare global {
   export type TODO<_Reason extends string = 'unknown'> = any
+  export type UNUSED<_Reason extends string = 'unknown'> = any
 }
 
 export {}

package/src/mod.ts

@@ -234,4 +234,13 @@ export const isPromise = (value: any): value is Promise<unknown> => typeof value
 
 export const isIterable = <T>(value: any): value is Iterable<T> => typeof value?.[Symbol.iterator] === 'function'
 
+/** This utility "lies" as a means of compat with libs that don't explicitly type optionals as unioned with `undefined`. */
+export const omitUndefineds = <T extends Record<keyof any, unknown>>(
+  rec: T,
+): {
+  [K in keyof T]: Exclude<T[K], undefined>
+} => {
+  return rec as never
+}
+
 export { objectToString as errorToString } from './misc.ts'

package/src/node/ChildProcessRunner/ChildProcessRunner.ts

@@ -13,6 +13,43 @@ import * as Layer from 'effect/Layer'
 import * as Runtime from 'effect/Runtime'
 import * as Scope from 'effect/Scope'
 
+// Parent death monitoring setup
+let parentDeathDetectionEnabled = false
+
+const setupParentDeathMonitoring = (parentPid: number) => {
+  if (parentDeathDetectionEnabled) return
+  parentDeathDetectionEnabled = true
+
+  let consecutiveFailures = 0
+  const maxFailures = 3 // Require 3 consecutive failures before self-terminating
+
+  // Check if parent is still alive every 2 seconds (more conservative)
+  const checkParentAlive = () => {
+    try {
+      // Send signal 0 to check if process exists (doesn't actually send signal)
+      process.kill(parentPid, 0)
+      // If we reach here, parent is still alive, reset failure counter and check again later
+      consecutiveFailures = 0
+      setTimeout(checkParentAlive, 2000)
+    } catch {
+      consecutiveFailures++
+      console.warn(`[Worker ${process.pid}] Parent check failed (${consecutiveFailures}/${maxFailures})`)
+
+      if (consecutiveFailures >= maxFailures) {
+        // Parent process has been gone for multiple checks, self-terminate
+        console.error(`[Worker ${process.pid}] Parent process ${parentPid} confirmed dead, self-terminating`)
+        process.exit(0)
+      } else {
+        // Try again sooner on failure
+        setTimeout(checkParentAlive, 1000)
+      }
+    }
+  }
+
+  // Start monitoring after a longer initial delay to let things settle
+  setTimeout(checkParentAlive, 5000)
+}
+
 const platformRunnerImpl = Runner.PlatformRunner.of({
   [Runner.PlatformRunnerTypeId]: Runner.PlatformRunnerTypeId,
   start<I, O>(closeLatch: typeof CloseLatch.Service) {
@@ -43,18 +80,30 @@ const platformRunnerImpl = Runner.PlatformRunner.of({
             Deferred.unsafeDone(closeLatch, Exit.die(exit.cause))
           }
         }
-        port.on('message', (message: Runner.BackingRunner.Message<I>) => {
+        port.on('message', (message: Runner.BackingRunner.Message<I> | any) => {
           // console.log('message', message)
-          if (message[0] === 0) {
-            const result = handler(0, message[1])
-            if (Effect.isEffect(result)) {
-              const fiber = runFork(result)
-              fiber.addObserver(onExit)
-              FiberSet.unsafeAdd(fiberSet, fiber)
+
+          // Handle parent death detection setup messages
+          if (Array.isArray(message) && message[0] === 'setup-parent-death-detection' && message[1]?.parentPid) {
+            const parentPid = message[1].parentPid
+            // console.log(`[Worker ${process.pid}] Setting up parent death detection for parent ${parentPid}`)
+            setupParentDeathMonitoring(parentPid)
+            return
+          }
+
+          // Handle normal Effect worker messages
+          if (Array.isArray(message) && typeof message[0] === 'number') {
+            if (message[0] === 0) {
+              const result = handler(0, message[1])
+              if (Effect.isEffect(result)) {
+                const fiber = runFork(result)
+                fiber.addObserver(onExit)
+                FiberSet.unsafeAdd(fiberSet, fiber)
+              }
+            } else {
+              Deferred.unsafeDone(closeLatch, Exit.void)
+              port.close()
             }
-          } else {
-            Deferred.unsafeDone(closeLatch, Exit.void)
-            port.close()
           }
         })
         port.on('messageerror', (cause) => {

package/src/node/ChildProcessRunner/ChildProcessRunnerTest/ChildProcessRunner.test.ts

@@ -1,13 +1,12 @@
-// import * as WorkerThreads from 'node:worker_threads'
 import * as ChildProcess from 'node:child_process'
 
 import * as EffectWorker from '@effect/platform/Worker'
 import { assert, describe, it } from '@effect/vitest'
-import { Chunk, Effect, Stream } from 'effect'
+import { Chunk, Effect, Exit, Fiber, Scope, Stream } from 'effect'
 
 import * as ChildProcessWorker from '../ChildProcessWorker.ts'
 import type { WorkerMessage } from './schema.ts'
-import { GetPersonById, GetUserById, InitialMessage, Person, User } from './schema.ts'
+import { GetPersonById, GetUserById, InitialMessage, Person, StartStubbornWorker, User } from './schema.ts'
 
 const WorkerLive = ChildProcessWorker.layer(() =>
   ChildProcess.fork(
@@ -49,4 +48,255 @@ describe('ChildProcessRunner', { timeout: 10_000 }, () => {
         new Person({ id: 123, name: 'ing', data: new Uint8Array([4, 5, 6]) }),
       ])
     }).pipe(Effect.scoped, Effect.provide(WorkerLive), Effect.runPromise))
+
+  describe('Process Cleanup', { timeout: 15_000 }, () => {
+    const isProcessRunning = (pid: number) => {
+      try {
+        process.kill(pid, 0) // Signal 0 checks if process exists
+        return true
+      } catch {
+        return false
+      }
+    }
+
+    it('should clean up child processes when Effect is interrupted', () =>
+      Effect.gen(function* () {
+        let workerPid: number | undefined
+
+        const testEffect = Effect.gen(function* () {
+          const pool = yield* EffectWorker.makePoolSerialized<WorkerMessage>({
+            size: 1,
+            initialMessage: () => new InitialMessage({ name: 'test', data: new Uint8Array([1, 2, 3]) }),
+          })
+          const result = yield* pool.executeEffect(new StartStubbornWorker({ blockDuration: 30_000 }))
+          workerPid = result.pid
+
+          // Verify the worker process is running
+          assert.strictEqual(isProcessRunning(workerPid), true, 'Worker process should be running')
+
+          // Start a long-running operation that we'll interrupt
+          yield* Effect.sleep('60 seconds')
+        }).pipe(Effect.scoped, Effect.provide(WorkerLive))
+
+        // Run the test effect but interrupt it after 2 seconds
+        const fiber = yield* Effect.fork(testEffect)
+        yield* Effect.sleep('2 seconds')
+        yield* Fiber.interrupt(fiber)
+
+        // Wait a moment for cleanup to complete
+        yield* Effect.sleep('1 second')
+
+        // Verify the child process was cleaned up
+        if (workerPid) {
+          assert.strictEqual(
+            isProcessRunning(workerPid),
+            false,
+            `Worker process ${workerPid} should be terminated after Effect interruption`,
+          )
+        } else {
+          assert.fail('Worker PID was not captured')
+        }
+      }).pipe(Effect.runPromise))
+
+    it('should clean up child processes when scope is closed abruptly', () =>
+      Effect.gen(function* () {
+        let workerPid: number | undefined
+
+        // Create a scope that we can close manually
+        const scope = yield* Scope.make()
+
+        try {
+          const pool = yield* EffectWorker.makePoolSerialized<WorkerMessage>({
+            size: 1,
+            initialMessage: () => new InitialMessage({ name: 'test', data: new Uint8Array([1, 2, 3]) }),
+          }).pipe(Scope.extend(scope), Effect.provide(WorkerLive))
+
+          const result = yield* pool.executeEffect(new StartStubbornWorker({ blockDuration: 30_000 }))
+          workerPid = result.pid
+
+          // Verify the worker is running
+          assert.strictEqual(isProcessRunning(workerPid!), true, 'Worker process should be running')
+        } finally {
+          // Abruptly close the scope (simulating test abortion)
+          yield* Scope.close(scope, Exit.void)
+        }
+
+        // Wait for cleanup
+        yield* Effect.sleep('1 second')
+
+        // This should pass but will initially fail due to zombie process issue
+        if (workerPid) {
+          assert.strictEqual(
+            isProcessRunning(workerPid),
+            false,
+            `Worker process ${workerPid} should be terminated after scope closure`,
+          )
+        } else {
+          assert.fail('Worker PID was not captured')
+        }
+      }).pipe(Effect.runPromise))
+
+    it('should clean up child processes when parent receives SIGINT', () =>
+      Effect.gen(function* () {
+        let workerPid: number | undefined
+
+        const pool = yield* EffectWorker.makePoolSerialized<WorkerMessage>({
+          size: 1,
+          initialMessage: () => new InitialMessage({ name: 'test', data: new Uint8Array([1, 2, 3]) }),
+        })
+
+        const result = yield* pool.executeEffect(new StartStubbornWorker({ blockDuration: 60_000 }))
+        workerPid = result.pid
+
+        // Verify the worker is running
+        assert.strictEqual(isProcessRunning(workerPid), true, 'Worker process should be running')
+
+        // Simulate SIGINT being sent to current process (like Ctrl+C in vitest)
+        // This should trigger cleanup of child processes
+        yield* Effect.async<void>((resume) => {
+          // Store current listeners before we manipulate them
+          const currentSIGINTListeners = process.listeners('SIGINT').slice()
+
+          // Set up our test handler
+          const testHandler = () => {
+            // Emit SIGINT to all current listeners to trigger cleanup
+            currentSIGINTListeners.forEach((listener) => {
+              try {
+                ;(listener as Function)()
+              } catch {
+                // Ignore errors
+              }
+            })
+            resume(Effect.void)
+          }
+
+          // Remove all current SIGINT listeners and add our test handler
+          process.removeAllListeners('SIGINT')
+          process.once('SIGINT', testHandler)
+
+          // Send SIGINT after a short delay
+          setTimeout(() => {
+            process.kill(process.pid, 'SIGINT')
+          }, 1000)
+        })
+
+        // Wait for cleanup to complete
+        yield* Effect.sleep('2 seconds')
+
+        // This test should initially fail - child process will still be running
+        if (workerPid) {
+          assert.strictEqual(
+            isProcessRunning(workerPid),
+            false,
+            `Worker process ${workerPid} should be terminated after SIGINT`,
+          )
+        } else {
+          assert.fail('Worker PID was not captured')
+        }
+      }).pipe(Effect.scoped, Effect.provide(WorkerLive), Effect.runPromise))
+
+    it('should clean up multiple concurrent child processes', () =>
+      Effect.gen(function* () {
+        let workerPids: number[] = []
+
+        const testEffect = Effect.gen(function* () {
+          const pool = yield* EffectWorker.makePoolSerialized<WorkerMessage>({
+            size: 3, // Multiple workers
+            initialMessage: () => new InitialMessage({ name: 'test', data: new Uint8Array([1, 2, 3]) }),
+          })
+
+          // Start multiple stubborn workers
+          const workers = yield* Effect.all(
+            [
+              pool.executeEffect(new StartStubbornWorker({ blockDuration: 30_000 })),
+              pool.executeEffect(new StartStubbornWorker({ blockDuration: 30_000 })),
+              pool.executeEffect(new StartStubbornWorker({ blockDuration: 30_000 })),
+            ],
+            { concurrency: 'unbounded' },
+          )
+
+          workerPids = workers.map((w) => w.pid)
+
+          // Verify all workers are running
+          for (const pid of workerPids) {
+            assert.strictEqual(isProcessRunning(pid), true, `Worker process ${pid} should be running`)
+          }
+
+          yield* Effect.sleep('30 seconds') // Keep running until interrupted
+        }).pipe(Effect.scoped, Effect.provide(WorkerLive))
+
+        // Run with timeout to force termination
+        const fiber = yield* Effect.fork(testEffect)
+        yield* Effect.sleep('2 seconds')
+        yield* Fiber.interrupt(fiber)
+
+        // Wait for cleanup
+        yield* Effect.sleep('2 seconds')
+
+        // All worker processes should be cleaned up
+        for (const pid of workerPids) {
+          assert.strictEqual(
+            isProcessRunning(pid),
+            false,
+            `Worker process ${pid} should be terminated after pool cleanup`,
+          )
+        }
+      }).pipe(Effect.runPromise))
+
+    it('should handle direct ChildProcess.fork cleanup (node-sync pattern)', () =>
+      Effect.gen(function* () {
+        let childPid: number | undefined
+
+        // This mimics the exact pattern used in node-sync tests
+        const nodeChildProcess = ChildProcess.fork(
+          new URL(
+            '../../../../dist/node/ChildProcessRunner/ChildProcessRunnerTest/serializedWorker.js',
+            import.meta.url,
+          ),
+          ['test-client'],
+        )
+
+        childPid = nodeChildProcess.pid
+
+        const testEffect = Effect.gen(function* () {
+          const worker = yield* EffectWorker.makePoolSerialized<WorkerMessage>({
+            size: 1,
+            concurrency: 100,
+            initialMessage: () => new InitialMessage({ name: 'test', data: new Uint8Array([1, 2, 3]) }),
+          }).pipe(Effect.provide(ChildProcessWorker.layer(() => nodeChildProcess)))
+
+          // Start stubborn worker
+          yield* worker.executeEffect(new StartStubbornWorker({ blockDuration: 60_000 }))
+
+          // Verify process is running
+          if (childPid) {
+            assert.strictEqual(isProcessRunning(childPid), true, 'Child process should be running')
+          }
+
+          // Keep running until interrupted
+          yield* Effect.sleep('30 seconds')
+        }).pipe(Effect.scoped)
+
+        // Simulate the exact abortion pattern from node-sync
+        const fiber = yield* Effect.fork(testEffect)
+        yield* Effect.sleep('2 seconds')
+
+        // Force kill the fiber without proper cleanup (simulates Ctrl+C)
+        yield* Fiber.interrupt(fiber)
+
+        // Wait for cleanup
+        yield* Effect.sleep('3 seconds')
+
+        // This test should initially fail - demonstrating the zombie process issue
+        if (childPid) {
+          assert.strictEqual(
+            isProcessRunning(childPid),
+            false,
+            `Child process ${childPid} should be terminated after forced interruption`,
+          )
+        } else {
+          assert.fail('Child PID was not captured')
+        }
+      }).pipe(Effect.runPromise))
+  })
 })

package/src/node/ChildProcessRunner/ChildProcessRunnerTest/schema.ts

@@ -35,6 +35,12 @@ export class RunnerInterrupt extends Schema.TaggedRequest<RunnerInterrupt>()('Ru
   payload: {},
 }) {}
 
+export class StartStubbornWorker extends Schema.TaggedRequest<StartStubbornWorker>()('StartStubbornWorker', {
+  failure: Schema.Never,
+  success: Schema.Struct({ pid: Schema.Number }),
+  payload: { blockDuration: Schema.Number },
+}) {}
+
 export class InitialMessage extends Schema.TaggedRequest<InitialMessage>()('InitialMessage', {
   failure: Schema.Never,
   success: Schema.Void,
@@ -61,5 +67,12 @@ export class GetSpan extends Schema.TaggedRequest<GetSpan>()('GetSpan', {
   payload: {},
 }) {}
 
-export const WorkerMessage = Schema.Union(GetUserById, GetPersonById, InitialMessage, GetSpan, RunnerInterrupt)
+export const WorkerMessage = Schema.Union(
+  GetUserById,
+  GetPersonById,
+  InitialMessage,
+  GetSpan,
+  RunnerInterrupt,
+  StartStubbornWorker,
+)
 export type WorkerMessage = Schema.Schema.Type<typeof WorkerMessage>

package/src/node/ChildProcessRunner/ChildProcessRunnerTest/serializedWorker.ts

@@ -22,7 +22,7 @@ const WorkerLive = Runner.layerSerialized(WorkerMessage, {
   // InitialMessage: (req) => Layer.succeed(Name, req.name),
   InitialMessage: (req) =>
     Effect.gen(function* () {
-      yield* Effect.addFinalizer(() => Effect.log('closing worker scope'))
+      // yield* Effect.addFinalizer(() => Effect.log('closing worker scope'))
       return Layer.succeed(Name, req.name)
     }).pipe(Layer.unwrapScoped),
   // InitialMessage: (req) =>
@@ -47,6 +47,19 @@ const WorkerLive = Runner.layerSerialized(WorkerMessage, {
       }
     }).pipe(Effect.withSpan('GetSpan')),
   RunnerInterrupt: () => Effect.interrupt,
+  StartStubbornWorker: ({ blockDuration }) =>
+    Effect.gen(function* () {
+      // Start a blocking operation that won't respond to normal shutdown signals
+      const pid = process.pid
+      yield* Effect.fork(
+        Effect.gen(function* () {
+          // Block for the specified duration, ignoring shutdown attempts
+          yield* Effect.sleep(`${blockDuration} millis`)
+          yield* Effect.log('Stubborn worker finished blocking')
+        }).pipe(Effect.uninterruptible),
+      )
+      return { pid }
+    }),
 }).pipe(Layer.provide(ChildProcessRunner.layer))
 // }).pipe(Layer.provide(PlatformNode.NodeWorkerRunner.layer))
 

package/src/node/ChildProcessRunner/ChildProcessWorker.ts

@@ -7,22 +7,114 @@ import * as Exit from 'effect/Exit'
 import * as Layer from 'effect/Layer'
 import * as Scope from 'effect/Scope'
 
+// Track child processes for cleanup on process signals
+const childProcesses = new Set<ChildProcess.ChildProcess>()
+
+// Force cleanup all tracked child processes
+const forceCleanupChildren = (signal: NodeJS.Signals = 'SIGKILL') => {
+  for (const child of childProcesses) {
+    try {
+      if (!child.killed) {
+        child.kill(signal)
+      }
+    } catch {
+      // Ignore errors during cleanup
+    }
+  }
+  childProcesses.clear()
+}
+
+// Install signal handlers once to clean up all child processes
+let signalHandlersInstalled = false
+
+const installSignalHandlers = () => {
+  if (signalHandlersInstalled) return
+  signalHandlersInstalled = true
+
+  // Use 'beforeExit' instead of signal handlers since tests may interfere with signals
+  process.on('beforeExit', () => {
+    forceCleanupChildren('SIGKILL')
+  })
+
+  // Also try to cleanup on uncaught exceptions
+  process.on('uncaughtException', () => {
+    forceCleanupChildren('SIGKILL')
+  })
+
+  // Install signal handlers but make them more robust
+  const sigintHandler = () => {
+    forceCleanupChildren('SIGINT')
+  }
+
+  const sigtermHandler = () => {
+    forceCleanupChildren('SIGTERM')
+  }
+
+  const exitHandler = () => {
+    forceCleanupChildren('SIGKILL')
+  }
+
+  // Add handlers that will persist even if tests remove/add other handlers
+  process.prependListener('SIGINT', sigintHandler)
+  process.prependListener('SIGTERM', sigtermHandler)
+  process.prependListener('exit', exitHandler)
+}
+
 const platformWorkerImpl = Worker.makePlatform<ChildProcess.ChildProcess>()({
   setup({ scope, worker: childProcess }) {
     return Effect.flatMap(Deferred.make<void, WorkerError>(), (exitDeferred) => {
+      // Install signal handlers for process-wide cleanup
+      installSignalHandlers()
+
+      // Track this child process for cleanup
+      childProcesses.add(childProcess)
+
       childProcess.on('exit', () => {
+        // Remove from tracking when process exits
+        childProcesses.delete(childProcess)
         Deferred.unsafeDone(exitDeferred, Exit.void)
       })
+
+      childProcess.send(['setup-parent-death-detection', { parentPid: process.pid }])
+
       return Effect.as(
         Scope.addFinalizer(
           scope,
           Effect.suspend(() => {
-            childProcess.send([1])
+            // Try graceful shutdown first
+            try {
+              childProcess.send([1])
+            } catch {
+              // IPC channel might be closed, proceed to forceful termination
+            }
+
             return Deferred.await(exitDeferred)
           }).pipe(
-            Effect.timeout(5000),
+            Effect.timeout(3000), // Reduced timeout for faster cleanup
             Effect.interruptible,
-            Effect.catchAllCause(() => Effect.sync(() => childProcess.kill())),
+            Effect.catchAllCause(() =>
+              Effect.sync(() => {
+                // Enhanced cleanup with escalating signals
+                if (!childProcess.killed) {
+                  try {
+                    // First try SIGTERM
+                    childProcess.kill('SIGTERM')
+
+                    // If still running after a short delay, use SIGKILL
+                    setTimeout(() => {
+                      if (!childProcess.killed) {
+                        childProcess.kill('SIGKILL')
+                      }
+                    }, 1000)
+                  } catch {
+                    // Process might already be dead
+                  } finally {
+                    // Ensure it's removed from tracking
+                    childProcesses.delete(childProcess)
+                  }
+                }
+              }),
+            ),
           ),
         ),
         {
@@ -56,5 +148,21 @@ export const layerWorker = Layer.succeed(Worker.PlatformWorker, platformWorkerIm
 
 export const layerManager = Layer.provide(Worker.layerManager, layerWorker)
 
+/**
+ * @example
+ * ```ts
+ * import * as ChildProcess from 'node:child_process'
+ * import { Effect, Worker } from '@effect/platform/Worker'
+ * import { ChildProcessWorker } from '@livestore/utils/node'
+ *
+ * Worker.makePoolSerialized<WorkerMessage>({
+ *   size: 1,
+ *   initialMessage: () => new InitialMessage({ name: 'test', data: new Uint8Array([1, 2, 3]) }),
+ * }).pipe(
+ *   Effect.provide(ChildProcessWorker.layer(() => ChildProcess.fork(new URL('worker.ts', import.meta.url)))),
+ * )
+ * ```
+ *
+ */
 export const layer = (spawn: (id: number) => ChildProcess.ChildProcess) =>
   Layer.merge(layerManager, Worker.layerSpawner(spawn))