concurrent-c-node 0.2.0__tar.gz

concurrent_c_node-0.2.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: concurrent-c-node
+Version: 0.2.0
+Summary: JavaScript and npm packages from Python over the Concurrent-C bridge: one spawned Node child per domain, host-controlled lifetime.
+License: MIT
+Project-URL: Repository, https://github.com/sreekotay/concurrent-c
+Project-URL: Documentation, https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/README.md
+Keywords: javascript,node,npm,interop,concurrent-c
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# concurrent-c-node
+
+JavaScript — and every npm package — from Python.
+
+Part of [Concurrent-C](https://github.com/sreekotay/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.)
+
+```python
+import cc_node
+
+js = cc_node.create()                # an Isolation Domain: one node child
+_ = js.require('lodash')             # resolved from YOUR cwd's node_modules
+_.chunk([1, 2, 3, 4, 5], 2)          # [[1, 2], [3, 4], [5]]
+_.sortBy([{'n': 3}, {'n': 1}], 'n')  # dicts cross as objects, and back
+
+semver = js.require('semver')
+semver.satisfies('1.2.3', '^1.0.0')  # True
+
+js.destroy()                         # or: with cc_node.create() as js: ...
+```
+
+The bridge is **pure Python, stdlib only** — no compiled code, no
+dependencies, nothing to build.  The domain **is** a spawned `node`
+child (~28ms to first call), so you get real Node: full stdlib, native
+addons, whatever npm installs.  Promise-based APIs look synchronous
+from Python, and bulk data crosses through **shared memory** — an 8MB
+array in **9ms** where the same values as a JSON list take 583ms.
+
+```
+pip install concurrent-c-node   # needs node on PATH (or point at one)
+```
+
+Import stays `import cc_node`. The mirror of
+[`concurrent-c-python`](https://github.com/sreekotay/concurrent-c/tree/main/npm/cc-python)
+— same domain model, same materialization rules, pointed the other way:
+
+- **Values**: plain data (finite numbers, strings, booleans, `None`,
+  lists/dicts of the same) crosses by value; everything else is a live
+  handle owned by the domain — attribute access is property lookup
+  (methods arrive bound), calls are calls, `str()` is `String()`.
+  Non-finite floats cross tagged, never silently nulled.
+- **The domain rules hold**: handles never cross bridges; `stats()` is
+  the handle ledger and `release()` drops one early; `destroy()` is
+  idempotent, every door answers `bridge is closed` after, and the
+  child dies with the bridge (and on host exit, via stdin EOF).
+
+## Async is free
+
+A thenable result is awaited **in the child** before the reply, so
+promise-based package APIs need nothing special — no event loop on the
+Python side, no `await`:
+
+```python
+fetchish = js.eval('async (x) => { return { doubled: x * 2 } }')
+fetchish(21)                         # {'doubled': 42} — just a call
+```
+
+Whatever an npm package's API returns — value or promise — the call
+site reads the same.
+
+## Callbacks: Python functions as JS functions
+
+A Python callable passed as an argument crosses as a JS function, and
+may be called back any number of times — including from inside async
+JS code:
+
+```python
+mapped = js.eval('(f) => [1, 2, 3].map(f)')(lambda x, *rest: x * 10)
+# [10, 20, 30] — JS conventions apply: map passes (value, index, array),
+# so a lambda takes *rest.  Exceptions cross both ways, messages intact.
+```
+
+Nested callbacks compose (the wire alternates strictly), and a Python
+exception inside one surfaces as the JS error at the call site — and
+vice versa.
+
+## Buffers: typed arrays, shared memory
+
+`bytes`, `array.array`, and 1-D numpy arrays cross as
+`Float64Array` / `Int32Array` / `Uint8Array` / … and come back as numpy
+arrays (or `array.array` without numpy):
+
+```python
+import array
+total = js.eval('(a) => a.reduce((s, x) => s + x, 0)')
+total(array.array('d', range(1_000_000)))   # crosses via shared memory
+```
+
+Small buffers inline; big ones spill through shared memory — one
+memcpy per side, the receiver consumes the spill file, and the sender
+sweeps it if the child died first.  Nothing strays, and nothing is
+silently truncated: an unsupported type is an articulate error.
+
+## Choosing the node
+
+Same ambient-first rule as the rest of the family: the domain runs
+whatever `node` your project runs.
+
+1. `create(node='/path/to/node')` from code — per-domain.
+2. `CC_NODE_BIN` in the environment.
+3. `node` on `PATH`.
+
+And *which packages* it sees is the working directory's
+`node_modules` — `require` resolves exactly as node itself would there.
+Run Python in your project, get your project's packages: `npm install`
+next to your program is the whole setup.
+
+## Measured
+
+From [`examples/bench_wire.py`](https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/examples/bench_wire.py)
+on a 4-vCPU x86-64 box, node 22 / python 3.11 (dated baselines under
+`perf/baselines/` in the repo):
+
+| what | result |
+|---|---|
+| spawn a domain (node child, first eval) | 28ms |
+| wire round trip (smallest call) | 116µs |
+| Python-callback round trip (JS → Python → JS) | 238µs |
+| 8MB `array('d')` argument, shm spill | **9.2ms** |
+| the same 8MB as a JSON list | 583ms — the spill is **63x** |
+
+The wire is strict request/response JSON over stdio with the
+shared-memory spill for bulk data — the same discipline concurrent-c-python's
+isolated domains speak, mirrored.  True pinned zero-copy leases remain
+future work.
+
+A worked tour (builtin Node modules, chains, callbacks, thenables,
+buffers — no npm install needed):
+[`examples/use_node.py`](https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/examples/use_node.py).
+
+And when the hot path is YOUR code rather than an npm package, skip the
+wire entirely: a page of Concurrent-C (or C) exports as a native module
+for Python and Node both — 40-90ns calls, stable-ABI artifacts.  See
+[Native modules for Node and Python](https://github.com/sreekotay/concurrent-c/blob/main/docs/js-py-modules.md).

concurrent_c_node-0.2.0/README.md

@@ -0,0 +1,135 @@
+# concurrent-c-node
+
+JavaScript — and every npm package — from Python.
+
+Part of [Concurrent-C](https://github.com/sreekotay/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.)
+
+```python
+import cc_node
+
+js = cc_node.create()                # an Isolation Domain: one node child
+_ = js.require('lodash')             # resolved from YOUR cwd's node_modules
+_.chunk([1, 2, 3, 4, 5], 2)          # [[1, 2], [3, 4], [5]]
+_.sortBy([{'n': 3}, {'n': 1}], 'n')  # dicts cross as objects, and back
+
+semver = js.require('semver')
+semver.satisfies('1.2.3', '^1.0.0')  # True
+
+js.destroy()                         # or: with cc_node.create() as js: ...
+```
+
+The bridge is **pure Python, stdlib only** — no compiled code, no
+dependencies, nothing to build.  The domain **is** a spawned `node`
+child (~28ms to first call), so you get real Node: full stdlib, native
+addons, whatever npm installs.  Promise-based APIs look synchronous
+from Python, and bulk data crosses through **shared memory** — an 8MB
+array in **9ms** where the same values as a JSON list take 583ms.
+
+```
+pip install concurrent-c-node   # needs node on PATH (or point at one)
+```
+
+Import stays `import cc_node`. The mirror of
+[`concurrent-c-python`](https://github.com/sreekotay/concurrent-c/tree/main/npm/cc-python)
+— same domain model, same materialization rules, pointed the other way:
+
+- **Values**: plain data (finite numbers, strings, booleans, `None`,
+  lists/dicts of the same) crosses by value; everything else is a live
+  handle owned by the domain — attribute access is property lookup
+  (methods arrive bound), calls are calls, `str()` is `String()`.
+  Non-finite floats cross tagged, never silently nulled.
+- **The domain rules hold**: handles never cross bridges; `stats()` is
+  the handle ledger and `release()` drops one early; `destroy()` is
+  idempotent, every door answers `bridge is closed` after, and the
+  child dies with the bridge (and on host exit, via stdin EOF).
+
+## Async is free
+
+A thenable result is awaited **in the child** before the reply, so
+promise-based package APIs need nothing special — no event loop on the
+Python side, no `await`:
+
+```python
+fetchish = js.eval('async (x) => { return { doubled: x * 2 } }')
+fetchish(21)                         # {'doubled': 42} — just a call
+```
+
+Whatever an npm package's API returns — value or promise — the call
+site reads the same.
+
+## Callbacks: Python functions as JS functions
+
+A Python callable passed as an argument crosses as a JS function, and
+may be called back any number of times — including from inside async
+JS code:
+
+```python
+mapped = js.eval('(f) => [1, 2, 3].map(f)')(lambda x, *rest: x * 10)
+# [10, 20, 30] — JS conventions apply: map passes (value, index, array),
+# so a lambda takes *rest.  Exceptions cross both ways, messages intact.
+```
+
+Nested callbacks compose (the wire alternates strictly), and a Python
+exception inside one surfaces as the JS error at the call site — and
+vice versa.
+
+## Buffers: typed arrays, shared memory
+
+`bytes`, `array.array`, and 1-D numpy arrays cross as
+`Float64Array` / `Int32Array` / `Uint8Array` / … and come back as numpy
+arrays (or `array.array` without numpy):
+
+```python
+import array
+total = js.eval('(a) => a.reduce((s, x) => s + x, 0)')
+total(array.array('d', range(1_000_000)))   # crosses via shared memory
+```
+
+Small buffers inline; big ones spill through shared memory — one
+memcpy per side, the receiver consumes the spill file, and the sender
+sweeps it if the child died first.  Nothing strays, and nothing is
+silently truncated: an unsupported type is an articulate error.
+
+## Choosing the node
+
+Same ambient-first rule as the rest of the family: the domain runs
+whatever `node` your project runs.
+
+1. `create(node='/path/to/node')` from code — per-domain.
+2. `CC_NODE_BIN` in the environment.
+3. `node` on `PATH`.
+
+And *which packages* it sees is the working directory's
+`node_modules` — `require` resolves exactly as node itself would there.
+Run Python in your project, get your project's packages: `npm install`
+next to your program is the whole setup.
+
+## Measured
+
+From [`examples/bench_wire.py`](https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/examples/bench_wire.py)
+on a 4-vCPU x86-64 box, node 22 / python 3.11 (dated baselines under
+`perf/baselines/` in the repo):
+
+| what | result |
+|---|---|
+| spawn a domain (node child, first eval) | 28ms |
+| wire round trip (smallest call) | 116µs |
+| Python-callback round trip (JS → Python → JS) | 238µs |
+| 8MB `array('d')` argument, shm spill | **9.2ms** |
+| the same 8MB as a JSON list | 583ms — the spill is **63x** |
+
+The wire is strict request/response JSON over stdio with the
+shared-memory spill for bulk data — the same discipline concurrent-c-python's
+isolated domains speak, mirrored.  True pinned zero-copy leases remain
+future work.
+
+A worked tour (builtin Node modules, chains, callbacks, thenables,
+buffers — no npm install needed):
+[`examples/use_node.py`](https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/examples/use_node.py).
+
+And when the hot path is YOUR code rather than an npm package, skip the
+wire entirely: a page of Concurrent-C (or C) exports as a native module
+for Python and Node both — 40-90ns calls, stable-ABI artifacts.  See
+[Native modules for Node and Python](https://github.com/sreekotay/concurrent-c/blob/main/docs/js-py-modules.md).

concurrent_c_node-0.2.0/cc_node/__init__.py

@@ -0,0 +1,341 @@
+"""cc-node: JavaScript (and every npm package) from Python.
+
+    import cc_node
+    js = cc_node.create()                 # an Isolation Domain: one node child
+    _ = js.require('lodash')              # resolved from YOUR cwd's node_modules
+    _.chunk([1, 2, 3, 4, 5], 2)           # [[1, 2], [3, 4], [5]]
+    js.destroy()
+
+The mirror of the cc-python bridge, same rules pointed the other way:
+attribute access is property lookup (methods arrive bound), a call is a
+call, plain data (finite numbers, strings, booleans, None, lists and
+dicts of the same) crosses by value and everything else stays a live
+handle owned by the domain.  A thenable result is awaited in the child
+before the reply, so async package APIs work with nothing extra.  A
+Python callable passed as an argument becomes a JS function; its
+exceptions cross back as JS errors and vice versa, messages intact.
+Handles never cross domains; every door after destroy() answers
+articulately; destroy is idempotent and `with cc_node.create() as js:`
+scopes it.
+"""
+import array
+import atexit
+import base64
+import json
+import math
+import os
+import subprocess
+
+__all__ = ["create", "JsError", "JsHandle", "__version__"]
+__version__ = "0.2.0"
+
+# Typed buffers cross as typed arrays; big ones spill through shared
+# memory (tmpfs where available) — one memcpy per side, receiver
+# consumes-and-unlinks, sender sweeps after the reply.
+_TA_TYPECODE = {"f64": "d", "f32": "f", "i32": "i", "i64": "q", "u8": "B"}
+_TA_DTYPE = {"f64": "float64", "f32": "float32", "i32": "int32",
+             "i64": "int64", "u8": "uint8"}
+_TA_BY_TYPECODE = {tc: k for k, tc in _TA_TYPECODE.items()}
+_TA_BY_DTYPE = {dt: k for k, dt in _TA_DTYPE.items()}
+_SHM_SPILL = 1 << 16
+_shm_seq = [0]
+
+
+def _numpy():
+    try:
+        import numpy
+        return numpy
+    except Exception:
+        return None
+
+
+def _shm_dir():
+    d = os.environ.get("CC_NODE_SHM_DIR")
+    if d:
+        return d
+    return "/dev/shm" if os.path.isdir("/dev/shm") else None
+
+
+def _shm_write(raw):
+    _shm_seq[0] += 1
+    path = os.path.join(_shm_dir(), "ccnode-%d-%d" % (os.getpid(),
+                                                      _shm_seq[0]))
+    with open(path, "wb") as f:
+        f.write(raw)
+    return path
+
+
+class JsError(RuntimeError):
+    """A JavaScript error, message intact."""
+
+
+_live = []
+
+
+def _atexit():
+    for b in list(_live):
+        try:
+            b.destroy()
+        except Exception:
+            pass
+
+
+atexit.register(_atexit)
+
+
+class JsHandle:
+    """A live JavaScript value owned by its domain."""
+
+    __slots__ = ("_d", "_h")
+
+    def __init__(self, domain, hid):
+        object.__setattr__(self, "_d", domain)
+        object.__setattr__(self, "_h", hid)
+
+    def __getattr__(self, name):
+        return self._d._req("get", h=self._h, name=name)
+
+    def __call__(self, *args):
+        return self._d._req("call", h=self._h,
+                            args=[self._d._encode(a) for a in args])
+
+    def __str__(self):
+        return self._d._req("str", h=self._h)
+
+    def __repr__(self):
+        return "<JsHandle #%d%s>" % (self._h,
+                                     " (closed)" if self._d.closed else "")
+
+    def __del__(self):
+        try:
+            if not self._d.closed:
+                self._d._req("release", h=self._h)
+        except Exception:
+            pass
+
+
+class Bridge:
+    """The domain: one spawned node child, one handle table, one wire."""
+
+    def __init__(self, node=None):
+        broker = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                              "broker.cjs")
+        node = node or os.environ.get("CC_NODE_BIN", "node")
+        try:
+            self._p = subprocess.Popen(
+                [node, broker],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                cwd=os.getcwd(),
+            )
+        except FileNotFoundError:
+            raise JsError(
+                "cc-node: no node executable (install Node, or set "
+                "CC_NODE_BIN)") from None
+        self.closed = False
+        self._nid = 1
+        self._cbs = {}
+        self._ncb = 1
+        self._shm_out = []
+        _live.append(self)
+
+    # ---- wire ----
+
+    def _send(self, obj):
+        line = json.dumps(obj, allow_nan=False) + "\n"
+        self._p.stdin.write(line.encode("utf-8"))
+        self._p.stdin.flush()
+
+    def _req(self, op, **kw):
+        if self.closed:
+            raise JsError("cc-node: bridge is closed")
+        rid = self._nid
+        self._nid += 1
+        kw["id"] = rid
+        kw["op"] = op
+        try:
+            self._send(kw)
+        except (BrokenPipeError, ValueError):
+            self.closed = True
+            raise JsError("cc-node: the node child exited") from None
+        try:
+            while True:
+                line = self._p.stdout.readline()
+                if not line:
+                    self.closed = True
+                    raise JsError("cc-node: the node child exited")
+                msg = json.loads(line)
+                if "cb" in msg:
+                    self._serve_callback(msg)
+                    continue
+                if msg.get("id") == rid:
+                    if "e" in msg:
+                        raise JsError(msg["e"])
+                    return self._decode_result(msg)
+                raise JsError("cc-node: protocol violation (unexpected reply)")
+        finally:
+            # The child unlinks spill files as it decodes; this sweep only
+            # matters when it died first (ENOENT is the normal case).
+            for path in self._shm_out:
+                try:
+                    os.unlink(path)
+                except OSError:
+                    pass
+            del self._shm_out[:]
+
+    def _serve_callback(self, msg):
+        fn = self._cbs.get(msg["cb"])
+        try:
+            if fn is None:
+                raise JsError("cc-node: unknown callback")
+            args = [self._decode_result(a) for a in msg["args"]]
+            self._send({"cbr": msg["cbid"], "v": self._encode(fn(*args))})
+        except Exception as e:  # crosses back as a JS error, message intact
+            self._send({"cbr": msg["cbid"], "e": str(e)})
+
+    # ---- values ----
+
+    def _encode(self, a):
+        if isinstance(a, JsHandle):
+            if a._d is not self:
+                raise JsError("cc-node: handle belongs to another bridge")
+            return {"$h": a._h}
+        if callable(a):
+            fid = self._ncb
+            self._ncb += 1
+            self._cbs[fid] = a
+            return {"$f": fid}
+        if a is None or isinstance(a, (bool, int, str)):
+            return a
+        if isinstance(a, float):
+            if math.isnan(a):
+                return {"$nf": "nan"}
+            if math.isinf(a):
+                return {"$nf": "inf" if a > 0 else "-inf"}
+            return a
+        if isinstance(a, (list, tuple)):
+            return [self._encode(x) for x in a]
+        if isinstance(a, dict):
+            out = {}
+            for k, v in a.items():
+                if not isinstance(k, str):
+                    raise JsError("cc-node: dict keys must be strings")
+                if k.startswith("$"):
+                    raise JsError("cc-node: dict keys starting with '$' are "
+                                  "reserved on the wire")
+                out[k] = self._encode(v)
+            return out
+        enc = self._encode_buffer(a)
+        if enc is not None:
+            return enc
+        raise JsError("cc-node: unsupported argument type: %r" % type(a))
+
+    def _encode_buffer(self, a):
+        # Typed buffers cross as typed arrays: bytes/array.array/1-D
+        # numpy — small inline as base64, big through the shared-memory
+        # spill (one memcpy per side; the receiver consumes-and-unlinks).
+        raw = None
+        kind = None
+        if isinstance(a, (bytes, bytearray, memoryview)):
+            raw, kind = bytes(a), "u8"
+        elif isinstance(a, array.array):
+            kind = _TA_BY_TYPECODE.get(a.typecode)
+            if kind is not None:
+                raw = a.tobytes()
+        else:
+            np = _numpy()
+            if np is not None and isinstance(a, np.ndarray) and a.ndim == 1:
+                kind = _TA_BY_DTYPE.get(str(a.dtype))
+                if kind is not None:
+                    raw = np.ascontiguousarray(a).tobytes()
+        if raw is None or kind is None:
+            return None
+        if len(raw) > _SHM_SPILL and _shm_dir():
+            path = _shm_write(raw)
+            self._shm_out.append(path)
+            return {"$shm": path, "t": kind}
+        return {"$ta": kind, "b64": base64.b64encode(raw).decode("ascii")}
+
+    def _decode_buffer(self, msg):
+        if "shm" in msg:
+            path = msg["shm"]
+            try:
+                with open(path, "rb") as f:
+                    raw = f.read()
+            finally:
+                try:
+                    os.unlink(path)
+                except OSError:
+                    pass
+        else:
+            raw = base64.b64decode(msg["b64"])
+        kind = msg.get("t") or msg.get("ta")
+        np = _numpy()
+        if np is not None:
+            return np.frombuffer(raw, dtype=_TA_DTYPE[kind]).copy()
+        a = array.array(_TA_TYPECODE[kind])
+        a.frombytes(raw)
+        return a
+
+    def _decode_result(self, msg):
+        if "u" in msg:
+            return None
+        if "h" in msg:
+            return JsHandle(self, msg["h"])
+        if "nf" in msg:
+            return {"nan": math.nan, "inf": math.inf,
+                    "-inf": -math.inf}[msg["nf"]]
+        if "ta" in msg or "shm" in msg:
+            return self._decode_buffer(msg)
+        return msg.get("v")
+
+    # ---- surface ----
+
+    def require(self, name):
+        return self._req("require", name=name)
+
+    def import_module(self, name):
+        return self._req("import", name=name)
+
+    def eval(self, src):
+        return self._req("eval", src=src)
+
+    def release(self, handle):
+        if not isinstance(handle, JsHandle) or handle._d is not self:
+            raise JsError("cc-node: handle belongs to another bridge")
+        return self._req("release", h=handle._h)
+
+    def stats(self):
+        return self._req("stats")
+
+    def destroy(self):
+        if self.closed:
+            return
+        try:
+            self._req("close")
+        except JsError:
+            pass
+        self.closed = True
+        try:
+            self._p.stdin.close()
+        except Exception:
+            pass
+        try:
+            self._p.wait(timeout=5)
+        except Exception:
+            self._p.kill()
+        if self in _live:
+            _live.remove(self)
+
+    close = destroy
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.destroy()
+        return False
+
+
+def create(node=None):
+    return Bridge(node=node)

concurrent_c_node-0.2.0/cc_node/broker.cjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+/* cc-node broker: the Node end of Python's JS bridge.
+ *
+ * Line-delimited JSON over stdio, strict request/response.  Handles are
+ * integers into one table; results follow the bridge materialization
+ * rule — plain data (finite numbers, strings, booleans, null, arrays
+ * and plain objects of the same) crosses as a value, everything else
+ * stays a handle.  A thenable result is awaited before the reply, so
+ * async package APIs need nothing special from the Python side.  A
+ * Python callable crosses as {$f: id}; invoking it sends a nested `cb`
+ * request and BLOCKS on a synchronous read for the answer — legal
+ * because the protocol is strictly alternating, so nothing else can be
+ * in flight.  stdin EOF is the host vanishing: exit. */
+'use strict';
+
+const fs = require('fs');
+const { createRequire } = require('module');
+
+/* Resolve packages from the HOST's cwd — `npm install lodash` next to
+ * your Python program is the point. */
+const requireCwd = createRequire(process.cwd() + '/');
+
+/* ---- one buffered reader over fd 0, sync and async ---- */
+const rbuf = { data: Buffer.alloc(0) };
+
+function takeLine() {
+  const i = rbuf.data.indexOf(10);
+  if (i < 0) return null;
+  const line = rbuf.data.subarray(0, i).toString('utf8');
+  rbuf.data = rbuf.data.subarray(i + 1);
+  return line;
+}
+
+function readLineSync() {
+  for (;;) {
+    const l = takeLine();
+    if (l !== null) return l;
+    const chunk = Buffer.alloc(65536);
+    let n = 0;
+    try {
+      n = fs.readSync(0, chunk, 0, chunk.length, null);
+    } catch (e) {
+      if (e.code === 'EAGAIN') continue;
+      if (e.code === 'EOF') return null;
+      throw e;
+    }
+    if (n === 0) return null;
+    rbuf.data = Buffer.concat([rbuf.data, chunk.subarray(0, n)]);
+  }
+}
+
+function readLineAsync() {
+  const l = takeLine();
+  if (l !== null) return Promise.resolve(l);
+  return new Promise((resolve, reject) => {
+    const chunk = Buffer.alloc(65536);
+    fs.read(0, chunk, 0, chunk.length, null, (err, n) => {
+      if (err) return err.code === 'EOF' ? resolve(null) : reject(err);
+      if (n === 0) return resolve(null);
+      rbuf.data = Buffer.concat([rbuf.data, chunk.subarray(0, n)]);
+      resolve(readLineAsync());
+    });
+  });
+}
+
+function send(obj) {
+  fs.writeSync(1, JSON.stringify(obj) + '\n');
+}
+
+/* ---- handles + materialization ---- */
+const handles = new Map();
+let nextH = 1;
+const put = (v) => {
+  const id = nextH++;
+  handles.set(id, v);
+  return id;
+};
+const getH = (id) => {
+  if (!handles.has(id)) throw new Error('cc-node: unknown or released handle');
+  return handles.get(id);
+};
+
+/* Plain data crosses by value; non-finite numbers are NOT plain (JSON
+ * would silently null them — they go as tagged scalars or handles). */
+function isPlain(v, depth) {
+  if (depth > 16) return false;
+  if (v === null) return true;
+  const t = typeof v;
+  if (t === 'number') return Number.isFinite(v);
+  if (t === 'string' || t === 'boolean') return true;
+  if (t !== 'object') return false;
+  const proto = Object.getPrototypeOf(v);
+  if (Array.isArray(v)) return v.every((x) => isPlain(x, depth + 1));
+  if (proto === Object.prototype || proto === null)
+    return Object.values(v).every((x) => isPlain(x, depth + 1));
+  return false;
+}
+
+/* Typed buffers cross as tagged bytes: small inline as base64, big
+ * through the shared-memory spill (one memcpy per side; the receiver
+ * consumes-and-unlinks).  Same discipline as cc-python's wire. */
+const TA_KIND = new Map([
+  [Float64Array, 'f64'], [Float32Array, 'f32'],
+  [Int32Array, 'i32'], [BigInt64Array, 'i64'], [Uint8Array, 'u8'],
+]);
+const TA_CTOR = {
+  f64: Float64Array, f32: Float32Array,
+  i32: Int32Array, i64: BigInt64Array, u8: Uint8Array,
+};
+const SHM_SPILL = 1 << 16;
+const SHM_DIR = process.env.CC_NODE_SHM_DIR ||
+                (fs.existsSync('/dev/shm') ? '/dev/shm'
+                                           : require('os').tmpdir());
+let shmSeq = 0;
+
+function encodeBuffer(kind, buf) {
+  if (buf.byteLength > SHM_SPILL) {
+    const p = require('path').join(
+        SHM_DIR, 'ccnode-' + process.pid + '-' + (++shmSeq));
+    fs.writeFileSync(p, buf);
+    return { shm: p, t: kind };
+  }
+  return { ta: kind, b64: buf.toString('base64') };
+}
+
+function encodeResult(v) {
+  if (v === undefined) return { u: 1 };
+  if (typeof v === 'number' && !Number.isFinite(v))
+    return { nf: Number.isNaN(v) ? 'nan' : v > 0 ? 'inf' : '-inf' };
+  if (v !== null && typeof v === 'object') {
+    const kind = TA_KIND.get(v.constructor);
+    if (kind)
+      return encodeBuffer(kind,
+                          Buffer.from(v.buffer, v.byteOffset, v.byteLength));
+    if (Buffer.isBuffer(v)) return encodeBuffer('u8', v);
+  }
+  if (v === null || isPlain(v, 0)) return { v };
+  return { h: put(v) };
+}
+
+/* ---- Python callables ---- */
+let nextCbId = 1;
+
+function makeCallback(fid) {
+  const f = (...args) => {
+    const cbid = nextCbId++;
+    send({ cb: fid, cbid, args: args.map(encodeResult) });
+    const line = readLineSync();
+    if (line === null) throw new Error('cc-node: host went away');
+    const m = JSON.parse(line);
+    if (m.cbr !== cbid)
+      throw new Error('cc-node: protocol violation during callback');
+    if (m.e !== undefined) throw new Error(m.e);
+    return decodeVal(m.v);
+  };
+  return f;
+}
+
+function decodeVal(a) {
+  if (a && typeof a === 'object') {
+    if (a.$h !== undefined) return getH(a.$h);
+    if (a.$f !== undefined) return makeCallback(a.$f);
+    if (a.$nf !== undefined)
+      return a.$nf === 'nan' ? NaN : a.$nf === 'inf' ? Infinity : -Infinity;
+    if (a.$ta !== undefined || a.$shm !== undefined) {
+      let buf;
+      if (a.$shm !== undefined) {
+        buf = fs.readFileSync(a.$shm);
+        try { fs.unlinkSync(a.$shm); } catch (e) { /* consumed */ }
+      } else {
+        buf = Buffer.from(a.b64, 'base64');
+      }
+      const C = TA_CTOR[a.t !== undefined ? a.t : a.$ta];
+      return new C(buf.buffer, buf.byteOffset,
+                   buf.byteLength / C.BYTES_PER_ELEMENT);
+    }
+    if (Array.isArray(a)) return a.map(decodeVal);
+    const o = {};
+    for (const k of Object.keys(a)) o[k] = decodeVal(a[k]);
+    return o;
+  }
+  return a;
+}
+
+/* ---- dispatch ---- */
+async function main() {
+  for (;;) {
+    const line = await readLineAsync();
+    if (line === null) process.exit(0);
+    let req;
+    try {
+      req = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const id = req.id;
+    try {
+      let r;
+      switch (req.op) {
+        case 'require': r = requireCwd(req.name); break;
+        case 'import': r = await import(req.name); break;
+        case 'eval': r = (0, eval)(req.src); break;
+        case 'get': {
+          const o = getH(req.h);
+          const v = o[req.name];
+          r = typeof v === 'function' ? v.bind(o) : v;
+          break;
+        }
+        case 'call': {
+          const f = getH(req.h);
+          if (typeof f !== 'function')
+            throw new Error('cc-node: handle is not callable');
+          r = f(...(req.args || []).map(decodeVal));
+          break;
+        }
+        case 'str': r = String(getH(req.h)); break;
+        case 'release': handles.delete(req.h); r = handles.size; break;
+        case 'stats': r = handles.size; break;
+        case 'close': send({ id, v: true }); process.exit(0); break;
+        default: throw new Error('cc-node: unknown op ' + req.op);
+      }
+      if (r && typeof r.then === 'function') r = await r; /* async is free */
+      send({ id, ...encodeResult(r) });
+    } catch (e) {
+      send({ id, e: String(e && e.message !== undefined ? e.message : e) });
+    }
+  }
+}
+
+main();

concurrent_c_node-0.2.0/concurrent_c_node.egg-info/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: concurrent-c-node
+Version: 0.2.0
+Summary: JavaScript and npm packages from Python over the Concurrent-C bridge: one spawned Node child per domain, host-controlled lifetime.
+License: MIT
+Project-URL: Repository, https://github.com/sreekotay/concurrent-c
+Project-URL: Documentation, https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/README.md
+Keywords: javascript,node,npm,interop,concurrent-c
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# concurrent-c-node
+
+JavaScript — and every npm package — from Python.
+
+Part of [Concurrent-C](https://github.com/sreekotay/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.)
+
+```python
+import cc_node
+
+js = cc_node.create()                # an Isolation Domain: one node child
+_ = js.require('lodash')             # resolved from YOUR cwd's node_modules
+_.chunk([1, 2, 3, 4, 5], 2)          # [[1, 2], [3, 4], [5]]
+_.sortBy([{'n': 3}, {'n': 1}], 'n')  # dicts cross as objects, and back
+
+semver = js.require('semver')
+semver.satisfies('1.2.3', '^1.0.0')  # True
+
+js.destroy()                         # or: with cc_node.create() as js: ...
+```
+
+The bridge is **pure Python, stdlib only** — no compiled code, no
+dependencies, nothing to build.  The domain **is** a spawned `node`
+child (~28ms to first call), so you get real Node: full stdlib, native
+addons, whatever npm installs.  Promise-based APIs look synchronous
+from Python, and bulk data crosses through **shared memory** — an 8MB
+array in **9ms** where the same values as a JSON list take 583ms.
+
+```
+pip install concurrent-c-node   # needs node on PATH (or point at one)
+```
+
+Import stays `import cc_node`. The mirror of
+[`concurrent-c-python`](https://github.com/sreekotay/concurrent-c/tree/main/npm/cc-python)
+— same domain model, same materialization rules, pointed the other way:
+
+- **Values**: plain data (finite numbers, strings, booleans, `None`,
+  lists/dicts of the same) crosses by value; everything else is a live
+  handle owned by the domain — attribute access is property lookup
+  (methods arrive bound), calls are calls, `str()` is `String()`.
+  Non-finite floats cross tagged, never silently nulled.
+- **The domain rules hold**: handles never cross bridges; `stats()` is
+  the handle ledger and `release()` drops one early; `destroy()` is
+  idempotent, every door answers `bridge is closed` after, and the
+  child dies with the bridge (and on host exit, via stdin EOF).
+
+## Async is free
+
+A thenable result is awaited **in the child** before the reply, so
+promise-based package APIs need nothing special — no event loop on the
+Python side, no `await`:
+
+```python
+fetchish = js.eval('async (x) => { return { doubled: x * 2 } }')
+fetchish(21)                         # {'doubled': 42} — just a call
+```
+
+Whatever an npm package's API returns — value or promise — the call
+site reads the same.
+
+## Callbacks: Python functions as JS functions
+
+A Python callable passed as an argument crosses as a JS function, and
+may be called back any number of times — including from inside async
+JS code:
+
+```python
+mapped = js.eval('(f) => [1, 2, 3].map(f)')(lambda x, *rest: x * 10)
+# [10, 20, 30] — JS conventions apply: map passes (value, index, array),
+# so a lambda takes *rest.  Exceptions cross both ways, messages intact.
+```
+
+Nested callbacks compose (the wire alternates strictly), and a Python
+exception inside one surfaces as the JS error at the call site — and
+vice versa.
+
+## Buffers: typed arrays, shared memory
+
+`bytes`, `array.array`, and 1-D numpy arrays cross as
+`Float64Array` / `Int32Array` / `Uint8Array` / … and come back as numpy
+arrays (or `array.array` without numpy):
+
+```python
+import array
+total = js.eval('(a) => a.reduce((s, x) => s + x, 0)')
+total(array.array('d', range(1_000_000)))   # crosses via shared memory
+```
+
+Small buffers inline; big ones spill through shared memory — one
+memcpy per side, the receiver consumes the spill file, and the sender
+sweeps it if the child died first.  Nothing strays, and nothing is
+silently truncated: an unsupported type is an articulate error.
+
+## Choosing the node
+
+Same ambient-first rule as the rest of the family: the domain runs
+whatever `node` your project runs.
+
+1. `create(node='/path/to/node')` from code — per-domain.
+2. `CC_NODE_BIN` in the environment.
+3. `node` on `PATH`.
+
+And *which packages* it sees is the working directory's
+`node_modules` — `require` resolves exactly as node itself would there.
+Run Python in your project, get your project's packages: `npm install`
+next to your program is the whole setup.
+
+## Measured
+
+From [`examples/bench_wire.py`](https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/examples/bench_wire.py)
+on a 4-vCPU x86-64 box, node 22 / python 3.11 (dated baselines under
+`perf/baselines/` in the repo):
+
+| what | result |
+|---|---|
+| spawn a domain (node child, first eval) | 28ms |
+| wire round trip (smallest call) | 116µs |
+| Python-callback round trip (JS → Python → JS) | 238µs |
+| 8MB `array('d')` argument, shm spill | **9.2ms** |
+| the same 8MB as a JSON list | 583ms — the spill is **63x** |
+
+The wire is strict request/response JSON over stdio with the
+shared-memory spill for bulk data — the same discipline concurrent-c-python's
+isolated domains speak, mirrored.  True pinned zero-copy leases remain
+future work.
+
+A worked tour (builtin Node modules, chains, callbacks, thenables,
+buffers — no npm install needed):
+[`examples/use_node.py`](https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/examples/use_node.py).
+
+And when the hot path is YOUR code rather than an npm package, skip the
+wire entirely: a page of Concurrent-C (or C) exports as a native module
+for Python and Node both — 40-90ns calls, stable-ABI artifacts.  See
+[Native modules for Node and Python](https://github.com/sreekotay/concurrent-c/blob/main/docs/js-py-modules.md).

concurrent_c_node-0.2.0/concurrent_c_node.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+pyproject.toml
+cc_node/__init__.py
+cc_node/broker.cjs
+concurrent_c_node.egg-info/PKG-INFO
+concurrent_c_node.egg-info/SOURCES.txt
+concurrent_c_node.egg-info/dependency_links.txt
+concurrent_c_node.egg-info/top_level.txt

concurrent_c_node-0.2.0/concurrent_c_node.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

concurrent_c_node-0.2.0/concurrent_c_node.egg-info/top_level.txt

@@ -0,0 +1 @@
+cc_node

concurrent_c_node-0.2.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "concurrent-c-node"
+version = "0.2.0"
+description = "JavaScript and npm packages from Python over the Concurrent-C bridge: one spawned Node child per domain, host-controlled lifetime."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+keywords = ["javascript", "node", "npm", "interop", "concurrent-c"]
+
+[project.urls]
+Repository = "https://github.com/sreekotay/concurrent-c"
+Documentation = "https://github.com/sreekotay/concurrent-c/blob/main/pypi/cc-node/README.md"
+
+[tool.setuptools]
+packages = ["cc_node"]
+
+[tool.setuptools.package-data]
+cc_node = ["broker.cjs"]

concurrent_c_node-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+