tar-xz 0.1.0

package/LICENSE

@@ -0,0 +1,165 @@
+GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/README.md

@@ -0,0 +1,201 @@
+# tar-xz
+
+Create and extract tar.xz archives with streaming support for Node.js and buffer-based API for browsers.
+
+## Features
+
+- **Node.js streaming API** - Memory-efficient processing of large archives
+- **Browser support** - WASM-powered XZ compression works in any browser
+- **Full TAR support** - POSIX ustar format with PAX extensions for long filenames
+- **TypeScript** - Full type definitions included
+- **Zero dependencies** - Only requires `node-liblzma` (workspace dependency)
+
+## Installation
+
+```bash
+npm install tar-xz
+# or
+pnpm add tar-xz
+# or
+yarn add tar-xz
+```
+
+## Usage
+
+### Node.js
+
+```typescript
+import { create, extract, list } from 'tar-xz';
+
+// Create an archive
+await create({
+  file: 'archive.tar.xz',
+  cwd: '/source/directory',
+  files: ['file1.txt', 'subdir/'],
+  preset: 6 // compression level (0-9)
+});
+
+// List contents
+const entries = await list({ file: 'archive.tar.xz' });
+for (const entry of entries) {
+  console.log(entry.name, entry.size);
+}
+
+// Extract to disk
+await extract({
+  file: 'archive.tar.xz',
+  cwd: '/destination',
+  strip: 1, // remove leading path component
+  filter: (entry) => !entry.name.startsWith('.') // skip hidden files
+});
+
+// Extract to memory
+import { extractToMemory } from 'tar-xz';
+const files = await extractToMemory('archive.tar.xz');
+for (const file of files) {
+  console.log(file.name, file.content.toString());
+}
+```
+
+### Browser
+
+```typescript
+import { createTarXz, extractTarXz, listTarXz } from 'tar-xz';
+
+// Create from files (e.g., from file input or drag & drop)
+const archive = await createTarXz({
+  files: [
+    { name: 'hello.txt', content: 'Hello, World!' },
+    { name: 'data.json', content: JSON.stringify({ foo: 'bar' }) }
+  ],
+  preset: 3 // lower preset for browser performance
+});
+
+// Download the archive
+const blob = new Blob([archive], { type: 'application/x-xz' });
+const url = URL.createObjectURL(blob);
+// ... trigger download
+
+// Extract an archive
+const response = await fetch('archive.tar.xz');
+const data = await response.arrayBuffer();
+const files = await extractTarXz(data);
+
+for (const file of files) {
+  console.log(file.name, file.data.length);
+}
+
+// List contents only (no extraction)
+const entries = await listTarXz(data);
+```
+
+## API Reference
+
+### Node.js API
+
+#### `create(options: CreateOptions): Promise<void>`
+
+Create a tar.xz archive from files on disk.
+
+Options:
+- `file` - Output archive path
+- `cwd` - Base directory for file paths (default: `process.cwd()`)
+- `files` - Array of file/directory paths to include
+- `preset` - XZ compression preset 0-9 (default: 6)
+- `follow` - Follow symbolic links (default: false)
+
+#### `extract(options: ExtractOptions): Promise<TarEntry[]>`
+
+Extract a tar.xz archive to disk.
+
+Options:
+- `file` - Input archive path
+- `cwd` - Output directory (default: `process.cwd()`)
+- `strip` - Number of leading path components to strip (default: 0)
+- `filter` - Function to filter entries
+- `preserveOwner` - Preserve file ownership (requires root)
+
+#### `list(options: ListOptions): Promise<TarEntry[]>`
+
+List contents of a tar.xz archive.
+
+#### `extractToMemory(file: string, options?): Promise<Array<TarEntry & { content: Buffer }>>`
+
+Extract archive to memory without writing to disk.
+
+### Browser API
+
+#### `createTarXz(options: BrowserCreateOptions): Promise<Uint8Array>`
+
+Create a tar.xz archive from in-memory files.
+
+Options:
+- `files` - Array of `{ name, content, mode?, mtime? }`
+- `preset` - XZ compression preset 0-9 (default: 3)
+
+#### `extractTarXz(archive: ArrayBuffer | Uint8Array, options?): Promise<ExtractedFile[]>`
+
+Extract a tar.xz archive to memory.
+
+Options:
+- `strip` - Number of leading path components to strip
+- `filter` - Function to filter entries
+
+#### `listTarXz(archive: ArrayBuffer | Uint8Array): Promise<TarEntry[]>`
+
+List contents of a tar.xz archive.
+
+## Low-level API
+
+For advanced usage, the package also exports low-level TAR utilities:
+
+```typescript
+import {
+  BLOCK_SIZE,
+  createHeader,
+  parseHeader,
+  calculatePadding,
+  createEndOfArchive,
+  needsPaxHeaders,
+  createPaxHeaderBlocks,
+} from 'tar-xz';
+```
+
+## Compression Presets
+
+| Preset | Memory Usage | Speed | Ratio |
+|--------|-------------|-------|-------|
+| 1 | ~10 MB | Fastest | Lowest |
+| 3 | ~20 MB | Fast | Good (browser default) |
+| 6 | ~100 MB | Medium | Very Good (Node default) |
+| 9 | ~700 MB | Slowest | Best |
+
+For browser usage, presets 1-6 are recommended to avoid memory issues.
+
+## Compatibility
+
+Archives created with `tar-xz` are fully compatible with standard tools:
+
+```bash
+# Extract with system tar
+tar -xJf archive.tar.xz
+
+# List contents
+tar -tJf archive.tar.xz
+
+# Create (for reference)
+tar -cJf archive.tar.xz files/
+```
+
+## Why tar-xz?
+
+The popular `node-tar` package (226M downloads/month) does not support `.tar.xz` files.
+While there are open issues requesting this feature, the maintainer prefers external libraries handle it.
+
+`tar-xz` fills this gap by combining:
+- **node-liblzma** for XZ compression (native + WASM)
+- A minimal TAR implementation (no external dependencies)
+
+## License
+
+LGPL-3.0 - Same as node-liblzma

package/lib/browser/create.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Browser-based TAR creation with XZ compression
+ */
+import { type BrowserCreateOptions } from '../types.js';
+/**
+ * Create a tar.xz archive in browser
+ *
+ * @param options - Creation options
+ * @returns Compressed archive as Uint8Array
+ *
+ * @example
+ * ```ts
+ * const archive = await createTarXz({
+ *   files: [
+ *     { name: 'hello.txt', content: 'Hello, World!' },
+ *     { name: 'data.json', content: JSON.stringify({ foo: 'bar' }) }
+ *   ],
+ *   preset: 3
+ * });
+ *
+ * // Download the archive
+ * const blob = new Blob([archive], { type: 'application/x-xz' });
+ * const url = URL.createObjectURL(blob);
+ * ```
+ */
+export declare function createTarXz(options: BrowserCreateOptions): Promise<Uint8Array>;
+//# sourceMappingURL=create.d.ts.map

package/lib/browser/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/browser/create.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,OAAO,EAAE,KAAK,oBAAoB,EAAgB,MAAM,aAAa,CAAC;AAsCtE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,CAiEpF"}

package/lib/browser/create.js

@@ -0,0 +1,113 @@
+/**
+ * Browser-based TAR creation with XZ compression
+ */
+import { xzAsync } from 'node-liblzma';
+import { calculatePadding, createEndOfArchive, createHeader, createPaxHeaderBlocks, needsPaxHeaders, } from '../tar/index.js';
+import { TarEntryType } from '../types.js';
+/**
+ * Convert input content to Uint8Array
+ */
+async function toUint8Array(content) {
+    if (typeof content === 'string') {
+        return new TextEncoder().encode(content);
+    }
+    if (content instanceof Uint8Array) {
+        return content;
+    }
+    if (content instanceof ArrayBuffer) {
+        return new Uint8Array(content);
+    }
+    if (content instanceof Blob) {
+        const buffer = await content.arrayBuffer();
+        return new Uint8Array(buffer);
+    }
+    throw new Error('Unsupported content type');
+}
+/**
+ * Concatenate multiple Uint8Arrays
+ */
+function concatArrays(arrays) {
+    const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const arr of arrays) {
+        result.set(arr, offset);
+        offset += arr.length;
+    }
+    return result;
+}
+/**
+ * Create a tar.xz archive in browser
+ *
+ * @param options - Creation options
+ * @returns Compressed archive as Uint8Array
+ *
+ * @example
+ * ```ts
+ * const archive = await createTarXz({
+ *   files: [
+ *     { name: 'hello.txt', content: 'Hello, World!' },
+ *     { name: 'data.json', content: JSON.stringify({ foo: 'bar' }) }
+ *   ],
+ *   preset: 3
+ * });
+ *
+ * // Download the archive
+ * const blob = new Blob([archive], { type: 'application/x-xz' });
+ * const url = URL.createObjectURL(blob);
+ * ```
+ */
+export async function createTarXz(options) {
+    const { files, preset = 3 } = options;
+    const blocks = [];
+    for (const file of files) {
+        const content = await toUint8Array(file.content);
+        const size = content.length;
+        // Normalize name
+        let name = file.name.replace(/\\/g, '/');
+        // Determine if it's a directory (ends with / and has no content)
+        const isDir = name.endsWith('/') && size === 0;
+        const type = isDir ? TarEntryType.DIRECTORY : TarEntryType.FILE;
+        // Check if PAX headers are needed
+        if (needsPaxHeaders({ name, size })) {
+            const paxBlocks = createPaxHeaderBlocks(name, {
+                path: name,
+                size,
+            });
+            blocks.push(...paxBlocks);
+            // Truncate name for the regular header
+            name = name.slice(-100);
+        }
+        // Create header
+        const mtime = file.mtime
+            ? typeof file.mtime === 'number'
+                ? file.mtime
+                : Math.floor(file.mtime.getTime() / 1000)
+            : Math.floor(Date.now() / 1000);
+        const header = createHeader({
+            name,
+            type,
+            size,
+            mode: file.mode ?? (isDir ? 0o755 : 0o644),
+            mtime,
+        });
+        blocks.push(header);
+        // Add content
+        if (size > 0) {
+            blocks.push(content);
+            // Add padding
+            const padding = calculatePadding(size);
+            if (padding > 0) {
+                blocks.push(new Uint8Array(padding));
+            }
+        }
+    }
+    // Add end-of-archive marker
+    blocks.push(createEndOfArchive());
+    // Concatenate all blocks into TAR
+    const tarData = concatArrays(blocks);
+    // Compress with XZ
+    // Cast to any because WASM accepts Uint8Array but types are defined for Node.js Buffer
+    return xzAsync(tarData, { preset });
+}
+//# sourceMappingURL=create.js.map

package/lib/browser/create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../src/browser/create.ts"],"names":[],"mappings":"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"}

package/lib/browser/extract.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Browser-based TAR extraction with XZ decompression
+ */
+import { type BrowserExtractOptions, type ExtractedFile } from '../types.js';
+/**
+ * Extract a tar.xz archive in browser
+ *
+ * @param archive - Compressed archive data (ArrayBuffer or Uint8Array)
+ * @param options - Extraction options
+ * @returns Array of extracted files
+ *
+ * @example
+ * ```ts
+ * const response = await fetch('archive.tar.xz');
+ * const data = await response.arrayBuffer();
+ * const files = await extractTarXz(data);
+ *
+ * for (const file of files) {
+ *   console.log(file.name, file.data.length);
+ * }
+ * ```
+ */
+export declare function extractTarXz(archive: ArrayBuffer | Uint8Array, options?: BrowserExtractOptions): Promise<ExtractedFile[]>;
+//# sourceMappingURL=extract.d.ts.map

package/lib/browser/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/browser/extract.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAGnB,MAAM,aAAa,CAAC;AA4ErB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,WAAW,GAAG,UAAU,EACjC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,aAAa,EAAE,CAAC,CAoC1B"}

package/lib/browser/extract.js

@@ -0,0 +1,112 @@
+/**
+ * Browser-based TAR extraction with XZ decompression
+ */
+import { unxzAsync } from 'node-liblzma';
+import { applyPaxAttributes, BLOCK_SIZE, calculatePadding, isEmptyBlock, parseHeader, parsePaxData, } from '../tar/index.js';
+import { TarEntryType, } from '../types.js';
+/**
+ * Parse TAR data into entries
+ */
+function parseTar(data) {
+    const entries = [];
+    let offset = 0;
+    let paxAttrs = null;
+    let emptyBlockCount = 0;
+    while (offset + BLOCK_SIZE <= data.length) {
+        const headerBlock = data.subarray(offset, offset + BLOCK_SIZE);
+        offset += BLOCK_SIZE;
+        // Check for end-of-archive
+        if (isEmptyBlock(headerBlock)) {
+            emptyBlockCount++;
+            if (emptyBlockCount >= 2) {
+                break;
+            }
+            continue;
+        }
+        emptyBlockCount = 0;
+        // Parse header
+        let entry = parseHeader(headerBlock);
+        if (!entry) {
+            continue;
+        }
+        // Handle PAX headers
+        if (entry.type === TarEntryType.PAX_HEADER) {
+            const paxSize = entry.size;
+            const paxData = data.subarray(offset, offset + paxSize);
+            offset += paxSize + calculatePadding(paxSize);
+            paxAttrs = parsePaxData(paxData);
+            continue;
+        }
+        if (entry.type === TarEntryType.PAX_GLOBAL) {
+            offset += entry.size + calculatePadding(entry.size);
+            continue;
+        }
+        // Apply PAX attributes if present
+        if (paxAttrs) {
+            entry = applyPaxAttributes(entry, paxAttrs);
+            paxAttrs = null;
+        }
+        // Extract content
+        const contentData = entry.size > 0 ? data.subarray(offset, offset + entry.size) : new Uint8Array(0);
+        offset += entry.size + calculatePadding(entry.size);
+        entries.push({ ...entry, data: contentData });
+    }
+    return entries;
+}
+/**
+ * Strip leading path components from a path
+ */
+function stripPath(filePath, strip) {
+    if (strip <= 0) {
+        return filePath;
+    }
+    const parts = filePath.split('/');
+    return parts.slice(strip).join('/');
+}
+/**
+ * Extract a tar.xz archive in browser
+ *
+ * @param archive - Compressed archive data (ArrayBuffer or Uint8Array)
+ * @param options - Extraction options
+ * @returns Array of extracted files
+ *
+ * @example
+ * ```ts
+ * const response = await fetch('archive.tar.xz');
+ * const data = await response.arrayBuffer();
+ * const files = await extractTarXz(data);
+ *
+ * for (const file of files) {
+ *   console.log(file.name, file.data.length);
+ * }
+ * ```
+ */
+export async function extractTarXz(archive, options = {}) {
+    const { strip = 0, filter } = options;
+    // Convert to Uint8Array if needed
+    const archiveData = archive instanceof Uint8Array ? archive : new Uint8Array(archive);
+    // Decompress XZ
+    // Cast to any because WASM accepts Uint8Array but types are defined for Node.js Buffer
+    const tarData = await unxzAsync(archiveData);
+    // Parse TAR
+    const entries = parseTar(tarData);
+    // Apply strip and filter
+    const results = [];
+    for (const entry of entries) {
+        const strippedName = stripPath(entry.name, strip);
+        if (!strippedName) {
+            continue;
+        }
+        const strippedEntry = { ...entry, name: strippedName };
+        if (filter && !filter(strippedEntry)) {
+            continue;
+        }
+        results.push({
+            name: strippedName,
+            data: entry.data,
+            entry: strippedEntry,
+        });
+    }
+    return results;
+}
+//# sourceMappingURL=extract.js.map

package/lib/browser/extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/browser/extract.ts"],"names":[],"mappings":"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"}

package/lib/browser/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Browser API for tar.xz archives
+ */
+export { createTarXz } from './create.js';
+export { extractTarXz } from './extract.js';
+export { listTarXz } from './list.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/browser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/lib/browser/index.js

@@ -0,0 +1,7 @@
+/**
+ * Browser API for tar.xz archives
+ */
+export { createTarXz } from './create.js';
+export { extractTarXz } from './extract.js';
+export { listTarXz } from './list.js';
+//# sourceMappingURL=index.js.map