concurrent-c-node

Call Node (and npm packages) from Python. Native types, exceptions, callbacks, and async all cross the boundary.

Part of Concurrent-C — a strict C11-superset preprocessor: .ccs lowers to plain C and compiles with your host C compiler. (This bridge itself is pure Python stdlib — no native build.)

Map of the three boundaries (CC hosts JS, native modules, this package bridge): JS / Python interop.

import cc_node

js = cc_node.create()                # always a child `node` process
_ = js.require('lodash')             # cwd node_modules
_.chunk([1, 2, 3, 4, 5], 2)          # [[1, 2], [3, 4], [5]]

semver = js.require('semver')
semver.satisfies('1.2.3', '^1.0.0')  # True

js.destroy()                         # or: with cc_node.create() as js:

Unlike concurrent-c-python (in-process by default), every create() here is a separate Node — real addons, crash isolation, measurable wire. N domains = N processes.

pip install concurrent-c-node          # needs node on PATH
python -m cc_node.examples.use_node
python -m cc_node.examples.bench_wire
python -m cc_node.benchmarks.multi_domain

Measured

bench_wire · cc_node_bridge_py_20260810.txt:

Wire: line-JSON on dedicated fds (stdio stays yours). Bulk spill: private 0700 dir, 0600 files, removed with the bridge. Crash isolation, not a sandbox — don’t eval untrusted JS.

Surface

• Plain data (numbers, str, bool, None, lists, non-empty dicts) by value. Empty {} stays a live handle. Else: domain-owned handle (attrs, calls, str() → String()). Non-finite floats are tagged.
• Handles stay in one domain. stats() / release() / idempotent destroy(); after close: bridge is closed. Teardown is cooperative; CPU-bound JS isn’t cancelable — wait or kill (bridge_stress.md).

Promises

Awaited in the child before the reply — no async/await on the Python side:

fetchish = js.eval('async (x) => { return { doubled: x * 2 } }')
fetchish(21)   # {'doubled': 42}

Callbacks

mapped = js.eval('(f) => [1, 2, 3].map(f)')(lambda x, *rest: x * 10)
# map passes (value, index, array) — take *rest

Exceptions cross both ways with messages intact.

Buffers

bytes / array.array / 1-D numpy → typed arrays (and back). Small inline; large via shm.

import array
total = js.eval('(a) => a.reduce((s, x) => s + x, 0)')
total(array.array('d', range(1_000_000)))

Common issues

Cannot find module. require / import resolve from the Python process cwd (node_modules next to your program), not from this wheel’s site-packages. npm install lodash in the project directory is the fix; or create(node=…) / CC_NODE_BIN when the wrong Node is on PATH. Missing-module errors name that cwd rule.

Empty {} stays a handle

An empty object has to stay on the Node side — a materialized Python {}/dict would lose later property use that matches Node. So js.eval('({})') returns a live handle:

o = js.eval('({})')                    # JsHandle, not {}
js.eval('(o) => { o.x = 1; return o.x }')(o)   # 1
js.eval('({a: 1})')                    # {'a': 1} — data return

Non-empty plain objects still cross as Python dicts. Same-domain handles chain (h.update(…).digest(…)); foreign-domain handles do not.

Thenables settle in the child. Promise-based npm APIs need no async/await on the Python side — the call blocks until settle (or raises on reject). Opposite of concurrent-c-python isolated, where every call is already a JS Promise you must await.

Wire cost vs tiny work. Round trip is ~100µs; a one-line JS helper on three numbers loses to pure Python. Prefer Python (or a native CC module) for small/hot work; use the bridge when Node/npm owns the kernel. Multi-core: python -m cc_node.benchmarks.multi_domain (~2.8× on 3 domains here).

Crash isolation, not a sandbox. The child inherits your environment — don’t eval untrusted JS. destroy() is cooperative; CPU-bound JS is not preemptible (wait or kill + new domain).

Choosing node

1. create(node='/path/to/node')
2. CC_NODE_BIN
3. node on PATH

Packages: cwd node_modules, same as Node itself.

From Concurrent-C (not Python): cc_js_new(false, &a) hosted (libnode), or cc_js_new(true, &a) for this wire — jsdemo.shcc.

Publishing

PyPI Trusted Publishing (OIDC) — no API token:

1. Publishing settings: owner sreekotay, repo concurrent-c, workflow publish-cc-node.yml, environment pypi
2. GitHub Environment pypi
3. Bump pyproject.toml, push, then:

gh workflow run publish-cc-node.yml

Local / npm sibling:

./scripts/publish_bridges.sh --publish --minor
gh workflow run publish-cc-node.yml
# twine fallback: … --pypi-twine

Examples: use_node, bench_wire, benchmarks.multi_domain.
Stress: stress/bridge/.
Own hot path in C/CC → native module (40–90ns) instead of the wire — JS / Python interop.