java-caller 4.3.2 → 4.4.0

package/README.md

@@ -4,7 +4,7 @@
 [![Version](https://img.shields.io/npm/v/java-caller.svg)](https://www.npmjs.com/package/java-caller)
 [![Downloads/week](https://img.shields.io/npm/dw/java-caller.svg)](https://npmjs.org/package/java-caller)
 [![Downloads/total](https://img.shields.io/npm/dt/java-caller.svg)](https://npmjs.org/package/java-caller)<!-- gh-dependents-info-used-by-start -->
-[![Generated by github-dependents-info](https://img.shields.io/static/v1?label=Used%20by&message=159&color=informational&logo=slickpic)](https://github.com/nvuillam/node-java-caller/blob/main/docs/github-dependents-info.md)<!-- gh-dependents-info-used-by-end -->
+[![Generated by github-dependents-info](https://img.shields.io/static/v1?label=Used%20by&message=162&color=informational&logo=slickpic)](https://github.com/nvuillam/node-java-caller/blob/main/docs/github-dependents-info.md)<!-- gh-dependents-info-used-by-end -->
 [![Mega-Linter](https://github.com/nvuillam/node-java-caller/workflows/Mega-Linter/badge.svg)](https://github.com/nvuillam/mega-linter#readme)
 [![codecov](https://codecov.io/gh/nvuillam/node-java-caller/branch/master/graph/badge.svg)](https://codecov.io/gh/nvuillam/node-java-caller)
 [![GitHub contributors](https://img.shields.io/github/contributors/nvuillam/node-java-caller.svg)](https://gitHub.com/nvuillam/node-java-caller/graphs/contributors/)
@@ -65,13 +65,16 @@ Example: `["-Xms256m", "--someflagwithvalue myVal", "-c"]`
 
 | Parameter | Description | Default | Example |
 |-----------|-------------|---------|---------|
-| [detached](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | If set to true, node will node wait for the java command to be completed.<br/>In that case, `childJavaProcess` property will be returned, but `stdout` and `stderr` may be empty, except if an error is triggered at command execution | `false` | `true`
+| [detached](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | If set to true, node will not wait for the java command to be completed.<br/>In that case, `childJavaProcess` property will be returned, but `stdout` and `stderr` may be empty, except if an error is triggered at command execution | `false` | `true`
 | [stdoutEncoding](https://nodejs.org/api/stream.html#readablesetencodingencoding) | Adds control on spawn process stdout | `utf8` | `ucs2` |
 | waitForErrorMs | If detached is true, number of milliseconds to wait to detect an error before exiting JavaCaller run   | `500` | `2000` |
 | [cwd](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | You can override cwd of spawn called by JavaCaller runner | `process.cwd()` | `some/other/cwd/folder` |
 | javaArgs | List of arguments for JVM only, not the JAR or the class | `[]` | `['--add-opens=java.base/java.lang=ALL-UNNAMED']` |
 | [windowsVerbatimArguments](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | No quoting or escaping of arguments is done on Windows. Ignored on Unix. This is set to true automatically when shell is specified and is CMD. | `true` | `false` |
 | [windowless](https://docs.oracle.com/en/java/javase/17/docs/specs/man/java.html#:~:text=main()%20method.-,javaw,information%20if%20a%20launch%20fails.) | If windowless is true, JavaCaller calls javaw instead of java to not create any windows, useful when using detached on Windows. Ignored on Unix. | false | true
+| [windowsHide](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | On Windows, hide the subprocess console window that would normally be created. Set to `false` if you need Java UI dialogs to be visible (e.g., print dialogs). Ignored on Unix. | `true` | `false`
+| [timeout](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | In milliseconds the maximum amount of time the process is allowed to run. | `undefined` | `1000`
+| [killSignal](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) | The signal value to be used when the spawned process will be killed by timeout or abort signal. | `SIGTERM` | `SIGINT`
 
 ## Examples
 
@@ -147,6 +150,23 @@ const java = new JavaCaller({
 const { status, stdout, stderr } = await java.run(['--sleep'], { windowless: true });
 ```
 
+Call java process with visible windows (e.g., for print dialogs)
+
+```javascript
+const java = new JavaCaller({
+    classPath: 'test/java/dist',
+    mainClass: 'com.nvuillam.javacaller.JavaCallerTester'
+});
+// Set windowsHide to false to allow Java UI dialogs to be visible
+const { status, stdout, stderr } = await java.run([], { windowsHide: false });
+```
+
+When using CLI mode with `--no-windows-hide` flag:
+
+```bash
+node index.js --no-windows-hide
+```
+
 You can see **more examples in** [**test methods**](https://github.com/nvuillam/node-java-caller/blob/master/test/java-caller.test.js)
 
 ## TROUBLESHOOTING

package/lib/cli.js

@@ -26,7 +26,18 @@ class JavaCallerCli {
         const java = new JavaCaller(this.javaCallerOptions);
         const args = [...process.argv];
         args.splice(0, 2);
-        const { status } = await java.run(args);
+        
+        // Parse --no-windows-hide flag (remove all occurrences)
+        const runOptions = {};
+        const filteredArgs = args.filter(arg => {
+            if (arg === '--no-windows-hide') {
+                runOptions.windowsHide = false;
+                return false; // Remove from args
+            }
+            return true; // Keep in args
+        });
+        
+        const { status } = await java.run(filteredArgs, runOptions);
         process.exitCode = status;
     }
 }

package/lib/index.d.ts

@@ -0,0 +1,224 @@
+
+/* eslint-disable no-unused-vars */
+/// <reference types="node" />
+
+/**
+ * Options for JavaCaller constructor
+ */
+export interface JavaCallerOptions {
+    /**
+     * Path to executable jar file
+     */
+    jar?: string;
+    
+    /**
+     * If jar parameter is not set, classpath to use.
+     * Use : as separator (it will be converted if run on Windows), or use a string array.
+     */
+    classPath?: string | string[];
+    
+    /**
+     * Set to true if classpaths should not be based on the rootPath
+     */
+    useAbsoluteClassPaths?: boolean;
+    
+    /**
+     * If classPath set, main class to call
+     */
+    mainClass?: string;
+    
+    /**
+     * Minimum java version to be used to call java command.
+     * If the java version found on machine is lower, java-caller will try to install and use the appropriate one
+     * @default 8 (11 on macOS)
+     */
+    minimumJavaVersion?: number;
+    
+    /**
+     * Maximum java version to be used to call java command.
+     * If the java version found on machine is upper, java-caller will try to install and use the appropriate one
+     */
+    maximumJavaVersion?: number;
+    
+    /**
+     * jre or jdk (if not defined and installation is required, jre will be installed)
+     */
+    javaType?: "jre" | "jdk";
+    
+    /**
+     * If classPath elements are not relative to the current folder, you can define a root path.
+     * You may use __dirname if you classes / jars are in your module folder
+     * @default "." (current folder)
+     */
+    rootPath?: string;
+    
+    /**
+     * You can force to use a defined java executable, instead of letting java-caller find/install one.
+     * Can also be defined with env var JAVA_CALLER_JAVA_EXECUTABLE
+     */
+    javaExecutable?: string;
+    
+    /**
+     * Additional parameters for JVM that will be added in every JavaCaller instance runs
+     */
+    additionalJavaArgs?: string[];
+    
+    /**
+     * Output mode: "none" or "console"
+     * @default "none"
+     */
+    output?: "none" | "console";
+}
+
+/**
+ * Options for JavaCaller run method
+ */
+export interface JavaCallerRunOptions {
+    /**
+     * If set to true, node will not wait for the java command to be completed.
+     * In that case, childJavaProcess property will be returned, but stdout and stderr may be empty
+     * @default false
+     */
+    detached?: boolean;
+    
+    /**
+     * Adds control on spawn process stdout
+     * @default "utf8"
+     */
+    stdoutEncoding?: string;
+    
+    /**
+     * If detached is true, number of milliseconds to wait to detect an error before exiting JavaCaller run
+     * @default 500
+     */
+    waitForErrorMs?: number;
+    
+    /**
+     * You can override cwd of spawn called by JavaCaller runner
+     * @default process.cwd()
+     */
+    cwd?: string;
+    
+    /**
+     * List of arguments for JVM only, not the JAR or the class
+     */
+    javaArgs?: string[];
+    
+    /**
+     * No quoting or escaping of arguments is done on Windows. Ignored on Unix.
+     * This is set to true automatically when shell is specified and is CMD.
+     * @default true
+     */
+    windowsVerbatimArguments?: boolean;
+    
+    /**
+     * If windowless is true, JavaCaller calls javaw instead of java to not create any windows,
+     * useful when using detached on Windows. Ignored on Unix.
+     * @default false
+     */
+    windowless?: boolean;
+
+    /**
+     * The number of milliseconds to wait before the Java process will time out. When this occurs,
+     * killSignal will ben
+     * @default undefined
+     */
+    timeout?: number;
+
+    /**
+     * If windowless is true, JavaCaller calls javaw instead of java to not create any windows,
+     * useful when using detached on Windows. Ignored on Unix.
+     * @default "SIGTERM"
+     */
+    killSignal?: number | NodeJS.Signals;
+    
+    /**
+     * On Windows, hide the subprocess console window that would normally be created.
+     * This option is ignored on Unix.
+     * @default true
+     */
+    windowsHide?: boolean;
+}
+
+/**
+ * Result returned by JavaCaller run method
+ */
+export interface JavaCallerResult {
+    /**
+     * Exit status code of the java command
+     */
+    status: number | null;
+    
+    /**
+     * Standard output of the java command
+     */
+    stdout: string;
+    
+    /**
+     * Standard error output of the java command
+     */
+    stderr: string;
+    
+    /**
+     * Child process object (useful when detached is true)
+     */
+    childJavaProcess?: import('child_process').ChildProcess;
+}
+
+/**
+ * JavaCaller class for calling Java commands from Node.js
+ */
+export class JavaCaller {
+    minimumJavaVersion: number;
+    maximumJavaVersion?: number;
+    javaType?: "jre" | "jdk";
+    rootPath: string;
+    jar?: string;
+    classPath: string | string[];
+    useAbsoluteClassPaths: boolean;
+    mainClass?: string;
+    output: string;
+    status: number | null;
+    javaSupportDir?: string;
+    javaExecutable: string;
+    javaExecutableWindowless: string;
+    additionalJavaArgs: string[];
+    commandJavaArgs: string[];
+    javaHome?: string;
+    javaBin?: string;
+    javaExecutableFromNodeJavaCaller?: string | null;
+    prevPath?: string;
+    prevJavaHome?: string;
+    
+    /**
+     * Creates a JavaCaller instance
+     * @param opts - Run options
+     */
+    constructor(opts: JavaCallerOptions);
+    
+    /**
+     * Runs java command of a JavaCaller instance
+     * @param userArguments - Java command line arguments
+     * @param runOptions - Run options
+     * @returns Command result (status, stdout, stderr, childJavaProcess)
+     */
+    run(userArguments?: string[], runOptions?: JavaCallerRunOptions): Promise<JavaCallerResult>;
+}
+
+/**
+ * JavaCallerCli class for using java-caller from command line
+ */
+export class JavaCallerCli {
+    javaCallerOptions: JavaCallerOptions;
+    
+    /**
+     * Creates a JavaCallerCli instance
+     * @param baseDir - Base directory containing java-caller-config.json
+     */
+    constructor(baseDir: string);
+    
+    /**
+     * Process command line arguments and run java command
+     */
+    process(): Promise<void>;
+}

package/lib/java-caller.js

@@ -69,12 +69,14 @@ class JavaCaller {
      * Runs java command of a JavaCaller instance
      * @param {string[]} [userArguments] - Java command line arguments
      * @param {object} [runOptions] - Run options
-     * @param {boolean} [runOptions.detached = false] - If set to true, node will node wait for the java command to be completed. In that case, childJavaProcess property will be returned, but stdout and stderr may be empty
+     * @param {boolean} [runOptions.detached = false] - If set to true, node will not wait for the java command to be completed. In that case, childJavaProcess property will be returned, but stdout and stderr may be empty
      * @param {string} [runOptions.stdoutEncoding = 'utf8'] - Adds control on spawn process stdout
      * @param {number} [runOptions.waitForErrorMs = 500] - If detached is true, number of milliseconds to wait to detect an error before exiting JavaCaller run
      * @param {string} [runOptions.cwd = .] - You can override cwd of spawn called by JavaCaller runner
      * @param {string} [runOptions.javaArgs = []] - You can override cwd of spawn called by JavaCaller runner
      * @param {string} [runOptions.windowsVerbatimArguments = true] - No quoting or escaping of arguments is done on Windows. Ignored on Unix. This is set to true automatically when shell is specified and is CMD.
+     * @param {number} [runOptions.timeout] - In milliseconds the maximum amount of time the process is allowed to run
+     * @param {NodeJS.Signals | number} [runOptions.killSignal = "SIGTERM"] - The signal value to be used when the spawned process will be killed by timeout or abort signal.
      * @return {Promise<{status:number, stdout:string, stderr:string, childJavaProcess:ChildProcess}>} - Command result (status, stdout, stderr, childJavaProcess)
      */
     async run(userArguments, runOptions = {}) {
@@ -84,6 +86,7 @@ class JavaCaller {
         runOptions.stdoutEncoding = typeof runOptions.stdoutEncoding === "undefined" ? "utf8" : runOptions.stdoutEncoding;
         runOptions.windowsVerbatimArguments = typeof runOptions.windowsVerbatimArguments === "undefined" ? true : runOptions.windowsVerbatimArguments;
         runOptions.windowless = typeof runOptions.windowless === "undefined" ? false : os.platform() !== "win32" ? false : runOptions.windowless;
+        runOptions.killSignal = typeof runOptions.killSignal === "undefined" ? "SIGTERM" : runOptions.killSignal;
         this.commandJavaArgs = (runOptions.javaArgs || []).concat(this.additionalJavaArgs);
 
         let javaExe = runOptions.windowless ? this.javaExecutableWindowless : this.javaExecutable;
@@ -97,10 +100,13 @@ class JavaCaller {
 
         const javaExeToUse = this.javaExecutableFromNodeJavaCaller ?? javaExe;
         const classPathStr = this.buildClasspathStr();
-        const javaArgs = this.buildArguments(classPathStr, (userArguments || []).concat(this.commandJavaArgs));
+        const javaArgs = this.buildArguments(classPathStr, (userArguments || []).concat(this.commandJavaArgs), runOptions.windowsVerbatimArguments);
         let stdout = "";
         let stderr = "";
         let child;
+        let timeoutId;
+        let killedByTimeout = false;
+
         const prom = new Promise((resolve) => {
             // Spawn java command line
             debug(`Java command: ${javaExeToUse} ${javaArgs.join(" ")}`);
@@ -109,7 +115,7 @@ class JavaCaller {
                 cwd: javaExeToUse === "java" || javaExeToUse === "javaw" ? runOptions.cwd : undefined,
                 env: Object.assign({}, process.env),
                 stdio: this.output === "console" ? "inherit" : runOptions.detached ? "ignore" : "pipe",
-                windowsHide: true,
+                windowsHide: runOptions.windowsHide !== undefined ? runOptions.windowsHide : true,
                 windowsVerbatimArguments: runOptions.windowsVerbatimArguments,
             };
             if (javaExeToUse.includes(" ")) {
@@ -117,6 +123,19 @@ class JavaCaller {
             }
             child = spawn(javaExeToUse, javaArgs, spawnOptions);
 
+            if (runOptions.timeout) {
+                timeoutId = setTimeout(() => {
+                    if (!child.killed) {
+                        try {
+                            child.kill(runOptions.killSignal);
+                            killedByTimeout = true;
+                        } catch (err) {
+                            stderr += `Failed to kill process after ${runOptions.timeout}ms: ${err.message}`;
+                        }
+                    }
+                }, runOptions.timeout);
+            }
+
             // Gather stdout and stderr if they must be returned
             if (spawnOptions.stdio === "pipe") {
                 child.stdout.setEncoding(`${runOptions.stdoutEncoding}`);
@@ -132,12 +151,28 @@ class JavaCaller {
             child.on("error", (data) => {
                 this.status = 666;
                 stderr += "Java spawn error: " + data;
+
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+
                 resolve();
             });
 
             // Catch status code
             child.on("close", (code) => {
-                this.status = code;
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+
+                if (killedByTimeout) {
+                    // Process was terminated because of the timeout
+                    this.status = 666;
+                    stderr += `Process timed out with ${runOptions.killSignal} after ${runOptions.timeout}ms.`;
+                } else {
+                    this.status = code;
+                }
+
                 resolve();
             });
 

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "java-caller",
-  "version": "4.3.2",
+  "version": "4.4.0",
   "description": "Library to easily call java from node sources. Automatically installs java if not present",
   "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
   "files": [
     "lib/"
   ],
   "scripts": {
     "lint:fix": "eslint **/*.js --fix && prettier --write \"./lib/**/*.{js,jsx,json}\" --tab-width 4 --print-width 150",
-    "java:compile": "javac -d test/java/dist -source 8 -target 1.8 test/java/src/com/nvuillam/javacaller/JavaCallerTester.java",
+    "java:compile": "javac -d test/java/dist --release 8 test/java/src/com/nvuillam/javacaller/JavaCallerTester.java",
     "java:jar": "cd test/java/dist && jar -cvfm ./../jar/JavaCallerTester.jar ./../jar/manifest/Manifest.txt com/nvuillam/javacaller/*.class && jar -cvfm ./../jar/JavaCallerTesterRunnable.jar ./../jar/manifest-runnable/Manifest.txt com/nvuillam/javacaller/*.class",
     "test": "mocha \"test/**/*.test.js\"",
     "test:coverage": "nyc npm run test",
@@ -26,6 +27,7 @@
     "node",
     "npm",
     "javascript",
+    "typescript",
     "class"
   ],
   "author": "Nicolas Vuillamy",
@@ -42,10 +44,12 @@
   },
   "devDependencies": {
     "@babel/eslint-parser": "^7.22.15",
+    "@types/node": "^25.2.0",
     "eslint": "^9.0.0",
     "mocha": "^11.0.0",
     "nyc": "^17.0.0",
     "prettier": "^3.1.0",
+    "typescript": "^5.9.3",
     "which": "^6.0.0"
   },
   "engines": {