Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Crane04/esem/llms.txt

Use this file to discover all available pages before exploring further.

ensureWorker() is a lower-level utility that guarantees the Python worker subprocess is running and ready to accept requests. python() calls it automatically before returning any module proxy, so most application code never needs to call it directly. The main use-case for calling it explicitly is pre-warming — starting the worker at server startup so the first python() call has no cold-start latency.

​
Signature

ensureWorker(): Promise<void>

​
Parameters

ensureWorker() takes no parameters.

​
What it does

  • If the worker is already running, returns the existing ready Promise immediately — there is no extra spawn attempt and no race condition.
  • If no worker is running, spawns the bundled worker.py script using python3 (or the binary specified by $ESEM_PYTHON) as a child process with stdio fully piped. The worker’s current working directory is set to process.cwd() so that relative module imports resolve correctly.
  • Resolves when the worker sends {"type": "ready"} on its stdout, signalling that it has finished initialising and is ready to process requests.

​
Pre-warming the worker

The most common reason to call ensureWorker() directly is to eliminate the cold-start delay that would otherwise occur on the first python() call: 
import { ensureWorker } from "esem-bridge";

// Pre-warm at server startup
await ensureWorker();

// Later calls to python() resolve immediately — no spawn overhead
python() calls ensureWorker() automatically before returning the module proxy. You never need to call ensureWorker() before python() — doing so is harmless and simply returns the already-resolved ready promise.
In a Next.js or Express application, call await ensureWorker() inside your server startup code (e.g. in instrumentation.ts for Next.js, or just before app.listen() for Express). This starts the Python worker in the background while the HTTP server initialises, so the very first incoming request that calls python() experiences no additional latency.

Build docs developers (and LLMs) love

Get started for freeTalk to us