hypha-rpc 0.21.35 → 0.21.37

package/README.md

@@ -24,4 +24,75 @@ hyphaWebsocketClient.connectToServer({
       }
   )
 })
-```
+```
+
+### Keyword Arguments (kwargs)
+
+Hypha RPC supports Python-style keyword arguments when calling JavaScript services. This works seamlessly across Python→JS and JS→JS calls.
+
+#### Calling from Python to JavaScript
+
+When a Python client calls a JS service using keyword arguments, they are automatically unpacked into the matching positional parameters:
+
+```python
+# Python caller
+svc = await server.get_service("my-js-service")
+result = await svc.greet(name="Alice", greeting="Hello")
+```
+
+```javascript
+// JavaScript service — params are matched by name
+await api.registerService({
+  id: "my-js-service",
+  greet(name, greeting) {
+    return `${greeting}, ${name}!`;  // "Hello, Alice!"
+  }
+});
+```
+
+#### Calling from JavaScript to JavaScript
+
+Use the `_rkwargs: true` flag to send keyword arguments from JS:
+
+```javascript
+const svc = await api.getService("my-js-service");
+
+// Positional (traditional)
+await svc.greet("Alice", "Hello");
+
+// Keyword arguments — params matched by name, order doesn't matter
+await svc.greet({ greeting: "Hello", name: "Alice", _rkwargs: true });
+```
+
+#### With `require_context`
+
+When a service uses `require_context: true`, the `context` parameter is automatically injected by the server and cannot be overridden via kwargs:
+
+```javascript
+await api.registerService({
+  id: "secure-svc",
+  config: { require_context: true },
+  greet(name, greeting, context) {
+    console.log("Called by:", context.user);
+    return `${greeting}, ${name}!`;
+  }
+});
+
+// Caller — context is injected automatically, not passed by the caller
+await svc.greet({ name: "Alice", greeting: "Hello", _rkwargs: true });
+```
+
+#### With `kwargs_expansion`
+
+For convenience when calling server APIs, connect with `kwargs_expansion: true` to automatically convert the last object argument to kwargs:
+
+```javascript
+const api = await connectToServer({
+  server_url: "https://ai.imjoy.io",
+  kwargs_expansion: true,
+});
+// The last object arg is automatically sent as kwargs
+const token = await api.generateToken({ config: { workspace: "my-ws" } });
+```
+
+> **Note:** Kwargs unpacking relies on parsing function parameter names from source code. This works with regular functions, arrow functions, and async functions, but will not work with minified/bundled code where parameter names are mangled.

package/coverage/html/index.html

@@ -86,7 +86,7 @@
             <div class='footer quiet pad2 space-top1 center small'>
                 Code coverage generated by
                 <a href="https://istanbul.js.org/" target="_blank" rel="noopener noreferrer">istanbul</a>
-                at 2026-03-10T23:48:04.149Z
+                at 2026-03-19T04:11:10.099Z
             </div>
         <script src="prettify.js"></script>
         <script>

package/dist/hypha-rpc-websocket.js

@@ -3439,7 +3439,8 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony export */ __webpack_require__.d(__webpack_exports__, {
 /* harmony export */   API_VERSION: () => (/* binding */ API_VERSION),
 /* harmony export */   RPC: () => (/* binding */ RPC),
-/* harmony export */   _applyEncryptionKeyToService: () => (/* binding */ _applyEncryptionKeyToService)
+/* harmony export */   _applyEncryptionKeyToService: () => (/* binding */ _applyEncryptionKeyToService),
+/* harmony export */   getParamNames: () => (/* binding */ getParamNames)
 /* harmony export */ });
 /* harmony import */ var _utils_index_js__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(/*! ./utils/index.js */ "./src/utils/index.js");
 /* harmony import */ var _utils_schema_js__WEBPACK_IMPORTED_MODULE_1__ = __webpack_require__(/*! ./utils/schema.js */ "./src/utils/schema.js");
@@ -3456,6 +3457,44 @@ __webpack_require__.r(__webpack_exports__);
 
 
 
+/**
+ * Extract parameter names from a function's source text.
+ * Works with regular functions, arrow functions, async functions,
+ * destructured params, default values, and rest params.
+ * Note: will not work with minified/bundled code where param names are mangled.
+ * @param {Function} fn - The function to inspect.
+ * @returns {string[]} Array of parameter names.
+ */
+function getParamNames(fn) {
+  const src = fn.toString();
+  // Match these forms (with optional leading async):
+  //   function(a, b)           – anonymous function
+  //   function name(a, b)      – named function
+  //   (a, b) =>                – arrow function
+  //   a =>                     – single-param arrow (no parens)
+  //   name(a, b) {             – shorthand method (object literal / class)
+  const match = src.match(
+    /^(?:async\s+)?(?:function\s*\w*)?\s*\(([^)]*)\)|^(?:async\s+)?(\w+)\s*=>|^(?:async\s+)?\w+\s*\(([^)]*)\)/,
+  );
+  if (!match) return [];
+  const paramStr =
+    match[1] !== undefined
+      ? match[1]
+      : match[2] !== undefined
+        ? match[2]
+        : match[3];
+  if (!paramStr || !paramStr.trim()) return [];
+  return paramStr
+    .split(",")
+    .map((p) =>
+      p
+        .trim()
+        .replace(/\s*=.*$/, "") // strip default values
+        .replace(/^\.\.\.\s*/, ""), // strip rest operator
+    )
+    .filter(Boolean);
+}
+
 /**
  * Apply an out-of-band encryption public key to all remote methods in a service.
  * @param {Object} svc - The decoded service object.
@@ -6404,6 +6443,24 @@ class RPC extends _utils_index_js__WEBPACK_IMPORTED_MODULE_0__.MessageEmitter {
       } else {
         args = [];
       }
+
+      // Unpack kwargs into positional arguments when with_kwargs is set.
+      // This mirrors Python's _handle_method which pops the last arg as
+      // a kwargs dict and passes it via **kwargs. Since JS doesn't have
+      // **kwargs, we map the dict keys to the function's parameter names.
+      if (data.with_kwargs && args.length > 0) {
+        const kwargs = args.pop();
+        if (typeof kwargs === "object" && kwargs !== null) {
+          const paramNames = getParamNames(method);
+          // Filter out 'context' — it's handled separately by require_context
+          const mappableParams = paramNames.filter((n) => n !== "context");
+          args = mappableParams.map((name) => kwargs[name]);
+        } else {
+          // Not a dict — push it back (shouldn't happen, but be safe)
+          args.push(kwargs);
+        }
+      }
+
       if (
         this._method_annotations.has(method) &&
         this._method_annotations.get(method).require_context