js4j 0.1.0 → 0.1.1

package/README.md

@@ -33,6 +33,7 @@ A Node.js implementation of [py4j](https://www.py4j.org/) — a bridge between J
     - [createJavaProxy](#createjavaproxy)
     - [CallbackServer](#callbackserver)
     - [ProxyPool](#proxypool)
+  - [launchGateway](#launchgateway)
   - [Errors](#errors)
 - [TypeScript](#typescript)
 - [Credits](#credits)
@@ -668,6 +669,46 @@ const items: any[] = await list.toArray();
 
 ---
 
+### launchGateway
+
+Spawn a Java process that runs a `GatewayServer` and connect a `JavaGateway` to it automatically. Useful when Node.js is responsible for starting the JVM rather than the other way around.
+
+```js
+const { launchGateway } = require('js4j');
+
+const { gateway, kill } = await launchGateway({
+  classpath: '/usr/share/py4j/py4j.jar:java/build',
+  mainClass: 'com.example.MyApp',
+});
+
+const result = await gateway.entry_point.doSomething();
+await kill();
+```
+
+#### Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `classpath` | `string` | *required* | Java classpath string (e.g. `'py4j.jar:.'`). |
+| `mainClass` | `string` | *required* | Fully-qualified main class to launch. |
+| `host` | `string` | `'127.0.0.1'` | Host to connect to after the process starts. |
+| `port` | `number` | `25333` | Port to connect to. |
+| `jvmArgs` | `string[]` | `[]` | Extra JVM flags (e.g. `['-Xmx512m', '-ea']`). |
+| `args` | `string[]` | `[]` | Arguments passed to the main class. |
+| `readyPattern` | `RegExp \| string \| null` | `/GATEWAY_STARTED/` | Pattern matched against stdout to detect when the server is ready. Set to `null` to skip stdout checking and rely only on port polling. |
+| `timeout` | `number` | `30000` | Maximum milliseconds to wait for the server to become ready. |
+| `gatewayOptions` | `GatewayParametersOptions` | `{}` | Extra options forwarded to `GatewayParameters` (e.g. `authToken`). |
+
+#### Return value
+
+| Property | Type | Description |
+|---|---|---|
+| `gateway` | `JavaGateway` | A connected `JavaGateway` instance. |
+| `process` | `ChildProcess` | The spawned Java child process. |
+| `kill` | `() => Promise<void>` | Shuts down the gateway and kills the Java process. |
+
+---
+
 ## Running Tests
 
 ```bash

package/index.d.ts

@@ -372,6 +372,62 @@ export declare class CallbackServer {
   readonly proxyPool: ProxyPool;
 }
 
+// ---------------------------------------------------------------------------
+// Launcher
+// ---------------------------------------------------------------------------
+
+import { ChildProcess } from 'child_process';
+
+export interface LaunchGatewayOptions {
+  /** Java classpath (e.g. '/path/to/py4j.jar:.') */
+  classpath: string;
+  /** Fully-qualified main class to launch (e.g. 'com.example.MyApp') */
+  mainClass: string;
+  /** Gateway host. Default: '127.0.0.1' */
+  host?: string;
+  /** Gateway port. Default: 25333 */
+  port?: number;
+  /** Extra JVM flags (e.g. ['-Xmx512m']). Default: [] */
+  jvmArgs?: string[];
+  /** Extra arguments passed to the main class. Default: [] */
+  args?: string[];
+  /**
+   * Pattern to match in process stdout that signals the server is ready.
+   * Set to null to skip stdout checking and rely only on port polling.
+   * Default: /GATEWAY_STARTED/
+   */
+  readyPattern?: RegExp | string | null;
+  /** Maximum milliseconds to wait for the server to become ready. Default: 30000 */
+  timeout?: number;
+  /** Extra options forwarded to GatewayParameters. */
+  gatewayOptions?: GatewayParametersOptions;
+}
+
+export interface LaunchGatewayResult {
+  /** The spawned Java child process. */
+  process: ChildProcess;
+  /** A connected JavaGateway instance. */
+  gateway: JavaGateway;
+  /**
+   * Shut down the gateway and kill the Java process.
+   * Equivalent to calling `gateway.shutdown()` then `process.kill()`.
+   */
+  kill: () => Promise<void>;
+}
+
+/**
+ * Spawn a Java GatewayServer process and connect a JavaGateway to it.
+ *
+ * @example
+ * const { gateway, kill } = await launchGateway({
+ *   classpath: '/usr/share/py4j/py4j.jar:java/build',
+ *   mainClass: 'com.example.MyApp',
+ * });
+ * const result = await gateway.entry_point.doSomething();
+ * await kill();
+ */
+export declare function launchGateway(options: LaunchGatewayOptions): Promise<LaunchGatewayResult>;
+
 // ---------------------------------------------------------------------------
 // Factory functions
 // ---------------------------------------------------------------------------

package/index.js

@@ -40,6 +40,7 @@ const {
   Js4JAuthenticationError,
 } = require('./src/exceptions');
 const protocol = require('./src/protocol');
+const { launchGateway } = require('./src/launcher');
 
 module.exports = {
   // Main gateway classes
@@ -73,6 +74,9 @@ module.exports = {
   Js4JNetworkError,
   Js4JAuthenticationError,
 
+  // Launcher
+  launchGateway,
+
   // Low-level protocol (for advanced use)
   protocol,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js4j",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A Node.js implementation of py4j — bridge between JavaScript and Java via the Py4J gateway protocol",
   "main": "index.js",
   "types": "index.d.ts",