temurin-jdk-downloader/README.md

Utilities for downloading, extracting, and finding Eclipse Adoptium (Temurin) OpenJDK binary releases for Windows.

# temurin-jdk-downloader

A Node.js utility library for **downloading, extracting, and auto-discovering Eclipse Adoptium Temurin (OpenJDK) binary releases** from GitHub.
Supports robust file downloading (with progress and timeouts), ZIP extraction, and Java executable detection for Windows systems.

---


## Features

- **Automatic download** of the latest matching Temurin (OpenJDK) Windows ZIP distribution (e.g., 8, 11, 17, 21, 25, and more).
- **Progress-aware file download** (with timeout, error handling, and redirect support).
- **In-memory ZIP extraction** with full folder structure preserved.
- **Auto-detects `java.exe` path** (for setting `JAVA_HOME` in CI or local setup).
- Simple async APIs and no binary dependencies.

---


## Installation

```sh
npm install temurin-jdk-downloader
```

> **Note:** This package is intended for use in Windows environments and downloads x64 Windows JDK zip archives.

---


## Usage

### Download and Install OpenJDK with Auto-Detection

```js
const { downloadTemurinJDK } = require('temurin-jdk-downloader');

(async () => {
  // Download and extract Temurin JDK 21 to the specified folder
  const { version, javaPath, binPath } = await downloadTemurinJDK({
    version: 21,
    targetExtractDir: 'C:/jdk-installs',
  });

  console.log(`JDK Version: ${version}`);
  console.log(`java.exe Path: ${javaPath}`);
  console.log(`bin Path: ${binPath}`);
})();
```

- Installs into: `C:/jdk-installs/temurin21-binaries`
- Finds `bin/java.exe` automatically.

---


### Download a File with Progress

```js
const { downloadFile } = require('temurin-jdk-downloader');

await downloadFile(
  'https://example.com/file.zip',
  'C:/temp/file.zip',
  {
    timeout: 60000,
    onProgress: (percent, downloadedBytes, totalBytes) =>
      console.log(percent + '%'),
  }
);
```

---


### Extract a ZIP Archive

```js
const { extractZip } = require('temurin-jdk-downloader');
await extractZip('C:/temp/openjdk.zip', 'C:/jdk-unpacked');
```

---


### Find a Java Executable

```js
const { findJavaExe } = require('temurin-jdk-downloader');
const javaPath = findJavaExe('C:/jdk-installs/temurin21-binaries');
```

---


### Lookup Direct Download URL for a JDK (Advanced)

```js
const { getTemurinBinaryURL } = require('temurin-jdk-downloader');
const url = await getTemurinBinaryURL('temurin17-binaries');
console.log(url);
// -> https://github.com/adoptium/temurin17-binaries/...
```

---


## API Reference

### `downloadTemurinJDK({ version, targetExtractDir })`

Download, extract, and auto-discover the JDK for the given version.

- `version` (`number`): Desired OpenJDK major version (defaults to `25` if omitted).
- `targetExtractDir` (`string`): Directory where the JDK archive will be extracted.

**Returns**: `Promise<{ version: string|null, javaPath: string, binPath: string }>`  
Throws on unsupported versions or failures.

---


### `downloadFile(url, destPath, [options])`

Robust downloader for HTTP/HTTPS files, with progress and timeout support.

- `url` (`string`): URL to download.
- `destPath` (`string`): Local file path to save.
- `options` (`object`):
    - `timeout` (`number`): Optional timeout in ms (default: 120000 = 2min).
    - `onProgress` (`function`): Optional callback: `(percent, downloadedBytes, totalBytes) => {}`

**Returns**: `Promise<void>`

---


### `extractZip(zipPath, extractTo)`

Extracts all files from a ZIP archive.

- `zipPath` (`string`): Path to ZIP file.
- `extractTo` (`string`): Output directory.

**Returns**: `Promise<void>`

---


### `findJavaExe(baseDir)`

Finds a `java.exe` inside the extracted JDK directory.

- `baseDir` (`string`): Path to the main JDK root folder.

**Returns**: `string|null` (absolute path to java.exe if found)

---


### `getTemurinBinaryURL(temurinBinary)`

Resolves the download URL of the latest Windows ZIP from GitHub.

- `temurinBinary` (`string`): e.g. `'temurin21-binaries'`

**Returns**: `Promise<string|undefined>`

---


## Supported JDK Versions

- 8, 11, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25

---


## Limitations

- **Windows only**: Downloads Windows x64 Hotspot OpenJDK binaries (`.zip`).
- Scrapes GitHub releases for latest builds (subject to website structure changes).
- Does **not** install system-wide or set environment variables—this is just extraction and discovery.
- Requires Node.js >= 14.

---


## License

MIT

---


## Credits

- [Eclipse Adoptium](https://adoptium.net/) for OpenJDK builds
- Inspired by CI/CD automation use cases

---


**Pull requests and improvements are welcome!**