node-liblzma 2.0.3 → 2.2.0

package/README.md

@@ -3,8 +3,12 @@ Node-liblzma
 
 [![NPM Version](https://img.shields.io/npm/v/node-liblzma.svg)](https://npmjs.org/package/node-liblzma)
 [![NPM Downloads](https://img.shields.io/npm/dm/node-liblzma.svg)](https://npmjs.org/package/node-liblzma)
-[![CI Status](https://github.com/oorabona/node-liblzma/actions/workflows/ci-unified.yml/badge.svg)](https://github.com/oorabona/node-liblzma/actions/workflows/ci-unified.yml)
-[![Code Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](#testing)
+[![CI Status](https://github.com/oorabona/node-liblzma/actions/workflows/ci.yml/badge.svg)](https://github.com/oorabona/node-liblzma/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/badge/docs-TypeDoc-blue.svg)](https://oorabona.github.io/node-liblzma/)
+[![License](https://img.shields.io/npm/l/node-liblzma.svg)](https://github.com/oorabona/node-liblzma/blob/master/LICENSE)
+[![Node Version](https://img.shields.io/node/v/node-liblzma.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![npm provenance](https://img.shields.io/badge/npm-provenance-green.svg)](https://docs.npmjs.com/generating-provenance-statements)
 
 # What is liblzma/XZ ?
 
@@ -30,8 +34,180 @@ See [installation](#installation) below.
 > Only LZMA2 is supported for compression output.
 But the library can open and read any LZMA1 or LZMA2 compressed file.
 
+# Quick Start
+
+```bash
+npm install node-liblzma
+```
+
+```typescript
+import { xzAsync, unxzAsync, createXz, createUnxz } from 'node-liblzma';
+
+// Simple: Compress a buffer
+const compressed = await xzAsync(Buffer.from('Hello, World!'));
+const decompressed = await unxzAsync(compressed);
+
+// Streaming: Compress a file
+import { createReadStream, createWriteStream } from 'fs';
+
+createReadStream('input.txt')
+  .pipe(createXz())
+  .pipe(createWriteStream('output.xz'));
+
+// With progress monitoring
+const compressor = createXz();
+compressor.on('progress', ({ bytesRead, bytesWritten }) => {
+  console.log(`${bytesRead} bytes in → ${bytesWritten} bytes out`);
+});
+```
+
+**Promise style (with `.then()`):**
+
+```typescript
+import { xzAsync, unxzAsync } from 'node-liblzma';
+
+xzAsync(Buffer.from('Hello, World!'))
+  .then(compressed => {
+    console.log('Compressed size:', compressed.length);
+    return unxzAsync(compressed);
+  })
+  .then(decompressed => {
+    console.log('Decompressed:', decompressed.toString());
+  })
+  .catch(err => {
+    console.error('Compression failed:', err);
+  });
+```
+
+**Callback style (Node.js traditional):**
+
+```typescript
+import { xz, unxz } from 'node-liblzma';
+
+xz(Buffer.from('Hello, World!'), (err, compressed) => {
+  if (err) throw err;
+  unxz(compressed, (err, decompressed) => {
+    if (err) throw err;
+    console.log('Decompressed:', decompressed.toString());
+  });
+});
+```
+
+📖 **Full API documentation**: [oorabona.github.io/node-liblzma](https://oorabona.github.io/node-liblzma/)
+
+# Command Line Interface (nxz)
+
+This package includes `nxz`, a portable xz-like CLI tool that works on any platform with Node.js.
+
+## Installation
+
+```bash
+# Global installation (recommended for CLI usage)
+npm install -g node-liblzma
+# or
+pnpm add -g node-liblzma
+
+# Then use directly
+nxz --help
+```
+
+## Quick Examples
+
+```bash
+# Compress a file (creates file.txt.xz, deletes original)
+nxz file.txt
+
+# Decompress (auto-detected from .xz extension)
+nxz file.txt.xz
+
+# Keep original file (-k)
+nxz -k file.txt
+
+# Decompress explicitly (-d)
+nxz -d archive.xz
+
+# Maximum compression (-9) with extreme mode (-e)
+nxz -9e large-file.bin
+
+# Compress to stdout (-c) for piping
+nxz -c file.txt > file.txt.xz
+
+# Decompress to stdout
+nxz -dc file.txt.xz | grep "pattern"
+
+# Custom output file (-o)
+nxz -d archive.xz -o /tmp/output.bin
+
+# List archive info (-l)
+nxz -l file.txt.xz
+
+# Verbose info (-lv)
+nxz -lv file.txt.xz
+
+# Compress from stdin
+cat file.txt | nxz -c > file.txt.xz
+
+# Quiet mode - suppress warnings (-q)
+nxz -q file.txt
+```
+
+## All Options
+
+| Option | Long | Description |
+|--------|------|-------------|
+| `-z` | `--compress` | Force compression mode |
+| `-d` | `--decompress` | Force decompression mode |
+| `-l` | `--list` | List archive information |
+| `-k` | `--keep` | Keep original file (don't delete) |
+| `-f` | `--force` | Overwrite existing output file |
+| `-c` | `--stdout` | Write to stdout, keep original file |
+| `-o` | `--output=FILE` | Write output to specified file |
+| `-v` | `--verbose` | Show progress for large files |
+| `-q` | `--quiet` | Suppress warning messages |
+| `-0`..`-9` | | Compression level (default: 6) |
+| `-e` | `--extreme` | Extreme compression (slower) |
+| `-h` | `--help` | Show help |
+| `-V` | `--version` | Show version |
+
+## One-shot Usage (without global install)
+
+```bash
+# npm/npx
+npx --package node-liblzma nxz --help
+npx -p node-liblzma nxz file.txt
+
+# pnpm
+pnpm dlx --package node-liblzma nxz --help
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error (file not found, format error, etc.) |
+| 130 | Interrupted (SIGINT/Ctrl+C) |
+
 # What's new ?
 
+## Latest Updates (2026)
+
+* **CLI Tool (nxz)**: Portable xz-like command line tool included in the package
+  - Full xz compatibility: `-z`, `-d`, `-l`, `-k`, `-f`, `-c`, `-o`, `-v`, `-q`
+  - Compression presets 0-9 with extreme mode (`-e`)
+  - Progress display for large files, stdin/stdout piping
+  - Works on any platform with Node.js
+  - See [Command Line Interface](#command-line-interface-nxz) section
+* **Progress Events**: Monitor compression/decompression progress with real-time events
+  ```typescript
+  const compressor = createXz();
+  compressor.on('progress', ({ bytesRead, bytesWritten }) => {
+    console.log(`Read: ${bytesRead}, Written: ${bytesWritten}`);
+  });
+  ```
+* **API Documentation**: Full TypeDoc documentation with Material theme at [oorabona.github.io/node-liblzma](https://oorabona.github.io/node-liblzma/)
+* **XZ Utils 5.8.2**: Updated to latest stable version
+
 ## Version 2.0 (2025) - Complete Modernization
 
 This major release brings the library into 2025 with modern tooling and TypeScript support:
@@ -39,7 +215,7 @@ This major release brings the library into 2025 with modern tooling and TypeScri
 * **Full TypeScript migration**: Complete rewrite from CoffeeScript to TypeScript for better type safety and developer experience
 * **Promise-based APIs**: New async functions `xzAsync()` and `unxzAsync()` with Promise support
 * **Modern testing**: Migrated from Mocha to Vitest with improved performance and better TypeScript integration
-* **Enhanced tooling**: 
+* **Enhanced tooling**:
   - [Biome](https://biomejs.dev/) for fast linting and formatting
   - Pre-commit hooks with nano-staged and simple-git-hooks
   - pnpm as package manager for better dependency management
@@ -75,11 +251,11 @@ Several prebuilt versions are bundled within the package.
 
 If your OS/architecture matches, you will use this version which has been compiled using the following default flags:
 
-Flag | Description | Default value | Possible values
------|-------------|---------------|----------------
-USE_GLOBAL | Should the library use the system provided DLL/.so library ? | `yes` (`no` if OS is Windows) | `yes` or `no`
-RUNTIME_LINK | Should the library be linked statically or use the shared LZMA library ? | `shared` | `static` or `shared`
-ENABLE_THREAD_SUPPORT | Does the LZMA library support threads ? | `yes` | `yes` or `no`
+| Flag | Description | Default | Values |
+|------|-------------|---------|--------|
+| `USE_GLOBAL` | Use system liblzma library | `yes` (`no` on Windows) | `yes`, `no` |
+| `RUNTIME_LINK` | Static or shared linking | `shared` | `static`, `shared` |
+| `ENABLE_THREAD_SUPPORT` | Enable thread support | `yes` | `yes`, `no` |
 
 If not `node-gyp` will automagically start compiling stuff according to the environment variables set, or the default values above.
 
@@ -107,44 +283,33 @@ var lzma = require('node-liblzma');
 import * as lzma from 'node-liblzma';
 ```
 
-Zlib            | XZlib                   | Arguments
-----------------|-------------------------|---------------
-createGzip      | createXz                | ([lzma_options, [options]])
-createGunzip    | createUnxz              | ([lzma_options, [options]])
-gzip            | xz                      | (buf, [options], callback)
-gunzip          | unxz                    | (buf, [options], callback)
-gzipSync        | xzSync                  | (buf, [options])
-gunzipSync      | unxzSync                | (buf, [options])
--               | xzAsync                 | (buf, [options]) ⇒ Promise\<Buffer>
--               | unxzAsync               | (buf, [options]) ⇒ Promise\<Buffer>
-
-## Constants
-
-`options` is an `Object` with the following possible attributes:
-
-Attribute            | Type     | Available options
----------------------|----------|------------
-check                | Uint32   | NONE
- | |CRC32
- | |CRC64
- | |SHA256
-preset | Uint32 | DEFAULT
- | |EXTREME
-flag | Uint32 | TELL_NO_CHECK
- | |TELL_UNSUPPORTED_CHECK
- | |TELL_ANY_CHECK
- | |CONCATENATED
-mode | Uint32 | FAST
- | |NORMAL
-filters | Array | LZMA2 (added by default)
- | |X86
- | |POWERPC
- | |IA64
- | |ARM
- | |ARMTHUMB
- | |SPARC
-
-For further information about each of these flags, you will find reference at [XZ SDK](http://7-zip.org/sdk.html).
+| Zlib | node-liblzma | Arguments |
+|------|--------------|-----------|
+| `createGzip` | `createXz` | `([options])` |
+| `createGunzip` | `createUnxz` | `([options])` |
+| `gzip` | `xz` | `(buf, [options], callback)` |
+| `gunzip` | `unxz` | `(buf, [options], callback)` |
+| `gzipSync` | `xzSync` | `(buf, [options])` |
+| `gunzipSync` | `unxzSync` | `(buf, [options])` |
+| - | `xzAsync` | `(buf, [options])` → `Promise<Buffer>` |
+| - | `unxzAsync` | `(buf, [options])` → `Promise<Buffer>` |
+| - | `xzFile` | `(input, output, [options])` → `Promise<void>` |
+| - | `unxzFile` | `(input, output, [options])` → `Promise<void>` |
+
+## Options
+
+The `options` object accepts the following attributes:
+
+| Attribute | Type | Description | Values |
+|-----------|------|-------------|--------|
+| `check` | number | Integrity check | `check.NONE`, `check.CRC32`, `check.CRC64`, `check.SHA256` |
+| `preset` | number | Compression level (0-9) | `preset.DEFAULT` (6), `preset.EXTREME` |
+| `mode` | number | Compression mode | `mode.FAST`, `mode.NORMAL` |
+| `threads` | number | Thread count | `0` = auto (all cores), `1` = single-threaded, `N` = N threads |
+| `filters` | array | Filter chain | `filter.LZMA2`, `filter.X86`, `filter.ARM`, etc. |
+| `chunkSize` | number | Processing chunk size | Default: 64KB |
+
+For further information about each of these flags, see the [XZ SDK documentation](http://7-zip.org/sdk.html).
 
 ## Advanced Configuration
 
@@ -152,32 +317,63 @@ For further information about each of these flags, you will find reference at [X
 
 The library supports multi-threaded compression when built with `ENABLE_THREAD_SUPPORT=yes` (default). Thread support allows parallel compression on multi-core systems, significantly improving performance for large files.
 
-**Using threads in compression:**
+**Thread values:**
+
+| Value | Behavior |
+|-------|----------|
+| `0` | **Auto-detect**: use all available CPU cores |
+| `1` | Single-threaded (default) |
+| `N` | Use exactly N threads |
+
+**Example:**
 
 ```typescript
-import { xz, createXz } from 'node-liblzma';
+import { createXz, hasThreads } from 'node-liblzma';
 
-// Specify number of threads (1-N, where N is CPU core count)
-const options = {
-  preset: lzma.preset.DEFAULT,
-  threads: 4  // Use 4 threads for compression
-};
+// Check if threading is available
+if (hasThreads()) {
+  // Auto-detect: use all CPU cores
+  const compressor = createXz({ threads: 0 });
+
+  // Or specify exact thread count
+  const compressor4 = createXz({ threads: 4 });
+}
+```
+
+**Important notes:**
+- Thread support only applies to **compression**, not decompression
+- Requires LZMA library built with pthread support (`ENABLE_THREAD_SUPPORT=yes`)
+- Default is `threads: 1` (single-threaded) for predictable behavior
+- Check availability: `hasThreads()` returns `true` if multi-threading is supported
+
+### Progress Monitoring
 
-// With buffer compression
-xz(buffer, options, (err, compressed) => {
-  // ...
+Track compression and decompression progress in real-time:
+
+```typescript
+import { createXz, createUnxz } from 'node-liblzma';
+
+const compressor = createXz({ preset: 6 });
+
+compressor.on('progress', ({ bytesRead, bytesWritten }) => {
+  const ratio = bytesWritten / bytesRead;
+  console.log(`Progress: ${bytesRead} bytes in, ${bytesWritten} bytes out (ratio: ${ratio.toFixed(2)})`);
+});
+
+// Works with both compression and decompression
+const decompressor = createUnxz();
+decompressor.on('progress', ({ bytesRead, bytesWritten }) => {
+  console.log(`Decompressing: ${bytesRead} → ${bytesWritten} bytes`);
 });
 
-// With streams
-const compressor = createXz(options);
 inputStream.pipe(compressor).pipe(outputStream);
 ```
 
-**Important notes:**
-- Thread support only applies to **compression**, not decompression
-- Requires LZMA library built with pthread support
-- `threads: 1` disables multi-threading (falls back to single-threaded encoder)
-- Check if threads are available: `import { hasThreads } from 'node-liblzma';`
+**Notes:**
+- Progress events fire after each chunk is processed
+- `bytesRead`: Total input bytes processed so far
+- `bytesWritten`: Total output bytes produced so far
+- Works with streams, not buffer APIs (`xz`/`unxz`)
 
 ### Buffer Size Optimization
 
@@ -434,7 +630,7 @@ npm test
 pnpm test
 ```
 
-It will build and launch the test suite (51 tests) with [Vitest](https://vitest.dev/) with TypeScript support and coverage reporting.
+It will build and launch the test suite (325+ tests) with [Vitest](https://vitest.dev/) with TypeScript support and coverage reporting.
 
 Additional testing commands:
 
@@ -837,9 +1033,9 @@ We follow [Conventional Commits](https://www.conventionalcommits.org/):
 
 **Examples**:
 ```bash
-git commit -m "feat(pool): add LZMAPool for concurrency control"
-git commit -m "fix(bindings): resolve memory leak in FunctionReference"
-git commit -m "docs(readme): add migration guide for v2.0"
+git commit -m "feat: add LZMAPool for concurrency control"
+git commit -m "fix: resolve memory leak in FunctionReference"
+git commit -m "docs: add migration guide for v2.0"
 ```
 
 ## Pull Request Process

package/index.d.ts

@@ -67,19 +67,42 @@ export type FlagType = 'TELL_NO_CHECK' | 'TELL_UNSUPPORTED_CHECK' | 'TELL_ANY_CH
 
 export type CompressionCallback = (error: Error | null, result?: Buffer) => void;
 
+/**
+ * Progress event data emitted during compression/decompression
+ */
+export interface ProgressInfo {
+  /** Total bytes read from input so far */
+  bytesRead: number;
+  /** Total bytes written to output so far */
+  bytesWritten: number;
+}
+
 export declare abstract class XzStream extends Transform {
   constructor(streamMode: number, opts?: LZMAOptions, options?: TransformOptions);
-  
+
+  /** Total bytes read from input so far */
+  readonly bytesRead: number;
+
+  /** Total bytes written to output so far */
+  readonly bytesWritten: number;
+
   /** Flush the stream with specified flush type */
   flush(callback?: () => void): void;
   flush(kind: number, callback?: () => void): void;
-  
+
   /** Close the stream */
   close(callback?: () => void): void;
-  
+
   _transform(chunk: Buffer | null, encoding: string, callback: (error?: Error) => void): void;
   _flush(callback: () => void): void;
   protected _processChunk(chunk: Buffer | null, flushFlag: number, callback?: (error?: Error) => void): Buffer | undefined;
+
+  /**
+   * Listen for progress events
+   * @event progress Emitted when data is written to output
+   */
+  on(event: 'progress', listener: (info: ProgressInfo) => void): this;
+  on(event: string | symbol, listener: (...args: unknown[]) => void): this;
 }
 
 export declare class Xz extends XzStream {
@@ -93,6 +116,40 @@ export declare class Unxz extends XzStream {
 /** Check if threading support is available */
 export declare function hasThreads(): boolean;
 
+/** Check if a buffer starts with XZ magic bytes */
+export declare function isXZ(buffer: Buffer): boolean;
+
+/** Get the runtime liblzma version string (e.g., "5.4.1") */
+export declare function versionString(): string;
+
+/** Get the runtime liblzma version number (e.g., 50040010 for 5.4.1) */
+export declare function versionNumber(): number;
+
+/** Get memory usage estimate for encoding with given preset */
+export declare function easyEncoderMemusage(presetLevel: number): number;
+
+/** Get memory usage estimate for decoding */
+export declare function easyDecoderMemusage(): number;
+
+/** Metadata extracted from an XZ file index */
+export interface XZFileIndex {
+  /** Uncompressed size in bytes */
+  uncompressedSize: number;
+  /** Compressed size in bytes (excluding headers) */
+  compressedSize: number;
+  /** Number of streams in the file */
+  streamCount: number;
+  /** Number of blocks in the file */
+  blockCount: number;
+  /** Integrity check type */
+  check: number;
+  /** Memory usage of the index structure */
+  memoryUsage: number;
+}
+
+/** Parse the index from a complete XZ file to get metadata */
+export declare function parseFileIndex(buffer: Buffer): XZFileIndex;
+
 /** Create a compression stream */
 export declare function createXz(lzmaOptions?: LZMAOptions, options?: TransformOptions): Xz;
 

package/lib/cli/nxz.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * nxz - Node.js XZ compression CLI
+ * A portable xz-like command line tool using node-liblzma
+ */
+export {};
+//# sourceMappingURL=nxz.d.ts.map

package/lib/cli/nxz.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nxz.d.ts","sourceRoot":"","sources":["../../src/cli/nxz.ts"],"names":[],"mappings":";AACA;;;GAGG"}