concurrent-c-node 0.12.0__tar.gz → 0.14.0__tar.gz

{concurrent_c_node-0.12.0 → concurrent_c_node-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: concurrent-c-node
-Version: 0.12.0
+Version: 0.14.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
@@ -99,10 +99,12 @@ Examples ship in the wheel. Same domain model and materialization
 rules as the npm sibling, 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.
+  lists and non-empty dicts/objects of the same) crosses by value; an
+  empty `{}` stays a live handle (so bags you mint in JS keep property
+  access). 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
@@ -161,6 +163,35 @@ 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.
 
+## Common issues
+
+**`Cannot find module '…'`.** `require` / `import` resolve from the
+**Python process cwd** (`node_modules` next to your program), not from
+the site-packages install of this wheel. `npm install lodash` in the
+project directory is the fix; or pass `create(node='/path/to/node')` /
+`CC_NODE_BIN` when the wrong Node is on `PATH`. Missing-module errors
+name that cwd rule.
+
+**Empty `{}` is a live handle.** `js.eval('({})')` stays a `JsHandle`
+so later property use matches Node. Non-empty plain objects still cross
+as Python `dict`s (data returns). Same-domain handles chain
+(`h.update(…).digest(…)`); foreign-domain handles do not.
+
+**Thenables are awaited in the child.** Promise-based npm APIs need no
+`async`/`await` on the Python side — the call blocks until settle (or
+raises `JsError` on reject). That is the opposite of
+`concurrent-c-python`'s isolated surface, where every call is already a
+JS Promise you must await.
+
+**Wire cost vs tiny work.** Round trip is ~100µs class; 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 (crypto, parsers, large buffers via shm).
+
+**Crash isolation, not a sandbox.** The child inherits your environment
+and privileges — do not evaluate untrusted JavaScript. `destroy()` is
+cooperative; CPU-bound JS is not preemptible (wait or kill + new domain).
+
 ## Choosing the node
 
 Same ambient-first rule as the rest of the family: the domain runs

{concurrent_c_node-0.12.0 → concurrent_c_node-0.14.0}/README.md

@@ -88,10 +88,12 @@ Examples ship in the wheel. Same domain model and materialization
 rules as the npm sibling, 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.
+  lists and non-empty dicts/objects of the same) crosses by value; an
+  empty `{}` stays a live handle (so bags you mint in JS keep property
+  access). 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
@@ -150,6 +152,35 @@ 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.
 
+## Common issues
+
+**`Cannot find module '…'`.** `require` / `import` resolve from the
+**Python process cwd** (`node_modules` next to your program), not from
+the site-packages install of this wheel. `npm install lodash` in the
+project directory is the fix; or pass `create(node='/path/to/node')` /
+`CC_NODE_BIN` when the wrong Node is on `PATH`. Missing-module errors
+name that cwd rule.
+
+**Empty `{}` is a live handle.** `js.eval('({})')` stays a `JsHandle`
+so later property use matches Node. Non-empty plain objects still cross
+as Python `dict`s (data returns). Same-domain handles chain
+(`h.update(…).digest(…)`); foreign-domain handles do not.
+
+**Thenables are awaited in the child.** Promise-based npm APIs need no
+`async`/`await` on the Python side — the call blocks until settle (or
+raises `JsError` on reject). That is the opposite of
+`concurrent-c-python`'s isolated surface, where every call is already a
+JS Promise you must await.
+
+**Wire cost vs tiny work.** Round trip is ~100µs class; 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 (crypto, parsers, large buffers via shm).
+
+**Crash isolation, not a sandbox.** The child inherits your environment
+and privileges — do not evaluate untrusted JavaScript. `destroy()` is
+cooperative; CPU-bound JS is not preemptible (wait or kill + new domain).
+
 ## Choosing the node
 
 Same ambient-first rule as the rest of the family: the domain runs

{concurrent_c_node-0.12.0 → concurrent_c_node-0.14.0}/cc_node/__init__.py

@@ -9,10 +9,11 @@
 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
+non-empty dicts of the same) crosses by value; an empty dict/object
+stays a live handle (bags keep property access).  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:`
@@ -29,7 +30,7 @@ import subprocess
 import tempfile
 
 __all__ = ["create", "JsError", "JsHandle", "__version__"]
-__version__ = "0.4.0"
+__version__ = "0.12.1"
 
 # Typed buffers cross as typed arrays; big ones spill through shared
 # memory (tmpfs where available) — one memcpy per side, receiver
@@ -304,7 +305,12 @@ class Bridge:
         enc = self._encode_buffer(a)
         if enc is not None:
             return enc
-        raise JsError("cc-node: unsupported argument type: %r" % type(a))
+        raise JsError(
+            "cc-node: unsupported argument type: %r "
+            "(numbers, str, bool, None, list/tuple, dict with str keys, "
+            "bytes/array.array/1-D numpy, callables, or this domain's "
+            "JsHandle — same-domain handles chain)"
+            % (type(a),))
 
     def _encode_buffer(self, a):
         # Typed buffers cross as typed arrays: bytes/array.array/1-D

{concurrent_c_node-0.12.0 → concurrent_c_node-0.14.0}/cc_node/broker.cjs

@@ -9,13 +9,15 @@
  * numbering) says which via CC_WIRE_IN / CC_WIRE_OUT.  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.  EOF on the request fd is the host vanishing: exit.
+ * and non-empty plain objects of the same) crosses as a value; an
+ * empty plain object stays a handle (so `eval('({})')` remains a live
+ * JS object — materializing it to Python `{}` dropped property access).
+ * 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.  EOF on the
+ * request fd is the host vanishing: exit.
  *
  * cc/include/ccc/script/js.cch embeds this file verbatim (the CC
  * isolated tier speaks the same wire); js_iso_smoke pins the two
@@ -151,6 +153,14 @@ function encodeResult(v) {
       return encodeBuffer(kind,
                           Buffer.from(v.buffer, v.byteOffset, v.byteLength));
     if (Buffer.isBuffer(v)) return encodeBuffer('u8', v);
+    // Empty plain {} / Object.create(null) stay handles — callers mint
+    // bags for later property use.  Non-empty plain objects still cross
+    // by value (data returns).
+    const proto = Object.getPrototypeOf(v);
+    if (!Array.isArray(v) &&
+        (proto === Object.prototype || proto === null) &&
+        Object.keys(v).length === 0)
+      return { h: put(v) };
   }
   if (v === null || isPlain(v, 0)) return { v };
   return { h: put(v) };
@@ -215,8 +225,34 @@ async function main() {
     try {
       let r;
       switch (req.op) {
-        case 'require': r = requireCwd(req.name); break;
-        case 'import': r = await import(req.name); break;
+        case 'require':
+          try {
+            r = requireCwd(req.name);
+          } catch (e) {
+            if (e && e.code === 'MODULE_NOT_FOUND') {
+              throw new Error(
+                  String(e.message) +
+                  ' — npm install into this working directory\'s ' +
+                  'node_modules (require resolves from cwd), or pass ' +
+                  'create(node=...) for a different Node');
+            }
+            throw e;
+          }
+          break;
+        case 'import':
+          try {
+            r = await import(req.name);
+          } catch (e) {
+            const msg = String(e && e.message !== undefined ? e.message : e);
+            if (/Cannot find module|ERR_MODULE_NOT_FOUND/i.test(msg)) {
+              throw new Error(
+                  msg +
+                  ' — install the package for this Node (cwd node_modules ' +
+                  'or a path import), or pass create(node=...)');
+            }
+            throw e;
+          }
+          break;
         case 'eval': r = (0, eval)(req.src); break;
         case 'get': {
           const o = getH(req.h);

{concurrent_c_node-0.12.0 → concurrent_c_node-0.14.0}/concurrent_c_node.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: concurrent-c-node
-Version: 0.12.0
+Version: 0.14.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
@@ -99,10 +99,12 @@ Examples ship in the wheel. Same domain model and materialization
 rules as the npm sibling, 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.
+  lists and non-empty dicts/objects of the same) crosses by value; an
+  empty `{}` stays a live handle (so bags you mint in JS keep property
+  access). 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
@@ -161,6 +163,35 @@ 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.
 
+## Common issues
+
+**`Cannot find module '…'`.** `require` / `import` resolve from the
+**Python process cwd** (`node_modules` next to your program), not from
+the site-packages install of this wheel. `npm install lodash` in the
+project directory is the fix; or pass `create(node='/path/to/node')` /
+`CC_NODE_BIN` when the wrong Node is on `PATH`. Missing-module errors
+name that cwd rule.
+
+**Empty `{}` is a live handle.** `js.eval('({})')` stays a `JsHandle`
+so later property use matches Node. Non-empty plain objects still cross
+as Python `dict`s (data returns). Same-domain handles chain
+(`h.update(…).digest(…)`); foreign-domain handles do not.
+
+**Thenables are awaited in the child.** Promise-based npm APIs need no
+`async`/`await` on the Python side — the call blocks until settle (or
+raises `JsError` on reject). That is the opposite of
+`concurrent-c-python`'s isolated surface, where every call is already a
+JS Promise you must await.
+
+**Wire cost vs tiny work.** Round trip is ~100µs class; 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 (crypto, parsers, large buffers via shm).
+
+**Crash isolation, not a sandbox.** The child inherits your environment
+and privileges — do not evaluate untrusted JavaScript. `destroy()` is
+cooperative; CPU-bound JS is not preemptible (wait or kill + new domain).
+
 ## Choosing the node
 
 Same ambient-first rule as the rest of the family: the domain runs

{concurrent_c_node-0.12.0 → concurrent_c_node-0.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "concurrent-c-node"
-version = "0.12.0"
+version = "0.14.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"