tar-vern 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Kouji Matsui (@kekyo@mi.kekyo.net)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# tar-vern
+
+Streaming tape archiver (tar) library for TypeScript/JavaScript.
+
+[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/tar-vern.svg)](https://www.npmjs.com/package/tar-vern)
+
+----
+
+## What is this?
+
+A modern TypeScript library for creating tape archives (tar/ustar format) using streaming API. Supports both files and directories with metadata preservation, GZip compression, readable streaming, and flexible content sources.
+
+```mermaid
+graph LR
+  A[Content Items<br/>* Files<br/>* Directories<br/>* String content<br/>* Buffer content<br/>* Async generators] -->|Stream pipe| B[Writer Stream<br/>'createWriteStream']
+  B --> C[TAR File<br/>'foobar.tar']
+```
+
+## Features
+
+- Streaming API: Memory-efficient processing of large files
+- Multiple content sources: String, Buffer, ReadableStream, file paths and async generators
+- Metadata preservation: File permissions, ownership, timestamps
+- Built-in compression: GZip compression support (`tar.gz` format)
+- No any other dependencies.
+
+## Installation
+
+```bash
+npm install tar-vern
+```
+
+----
+
+## Usage for tar packing
+
+### Basic example
+
+```typescript
+import { createTarPacker, storeReaderToFile } from 'tar-vern';
+
+// Create an async generator for tar entries
+const generator = async function*() {
+  // Add a simple text file
+  yield {
+    kind: 'file',
+    path: 'hello.txt',
+    mode: 0o644,
+    uname: 'user',
+    gname: 'group',
+    uid: 1000,
+    gid: 1000,
+    date: new Date(),
+    content: 'Hello, world!'   // text contents
+  };
+  
+  // Add a directory
+  yield {
+    kind: 'directory',
+    path: 'mydir',
+    mode: 0o755,
+    uname: 'user',
+    gname: 'group',
+    uid: 1000,
+    gid: 1000,
+    date: new Date()
+  };
+};
+
+// Create tar stream and write to file
+const packer = createTarPacker(generator());
+await storeReaderToFile(packer, 'archive.tar');   // Use helper to awaitable
+```
+
+### With GZip compression
+
+Supported `CompressionTypes`:
+
+|`CompressionTypes`|Details|
+|:----|:----|
+|`none`|Uncompression (default)|
+|`gzip`|Combined GZip compression stream|
+
+```typescript
+import { createTarPacker, storeReaderToFile, CompressionTypes } from 'tar-vern';
+
+const generator = async function*() {
+  yield {
+    kind: 'file',
+    path: 'data.txt',
+    mode: 0o644,
+    uname: 'user',
+    gname: 'group',
+    uid: 1000,
+    gid: 1000,
+    date: new Date(),
+    content: 'Large amount of data...'
+  };
+};
+
+// Create compressed tar stream
+const packer = createTarPacker(generator(), 'gzip');
+await storeReaderToFile(packer, 'archive.tar.gz');
+```
+
+### Helper functions
+
+```typescript
+import { 
+  createReadFileItem, 
+  createDirectoryItem,
+  createReadableItem,
+  storeReaderToFile
+} from 'tar-vern';
+import { createReadStream } from 'fs';
+
+// Configuration easier with item creation functions
+const generator = async function*() {
+  // Add file from filesystem (auto-detects metadata)
+  yield await createReadFileItem('archived-name.txt', '/path/to/real/source.txt');
+
+  // Add directory from filesystem
+  yield await createDirectoryItem('dir/sub/name', 'exceptName', { 
+    directoryPath: '/path/to/real/dir' 
+  });
+
+  // Add from readable stream
+  const stream = createReadStream('/path/to/large-file.bin');
+  yield await createReadableItem('large-file.bin', stream);
+};
+
+// The `packer` generally `stream.Readable`
+const packer = createTarPacker(generator());
+
+// Safer awaitable store file from `stream.Readable`
+await storeReaderToFile(packer, 'output.tar');
+```
+
+### Content types
+
+```typescript
+const generator = async function*() {
+  // String content
+  yield {
+    kind: 'file',
+    path: 'text.txt',
+    content: 'Text content'    // Store with utf8 encoding
+    // ... other properties
+  };
+
+  // Buffer content
+  yield {
+    kind: 'file',
+    path: 'binary.bin',
+    content: Buffer.from([0x48, 0x65, 0x6c, 0x6c, 0x6f])
+    // ... other properties
+  };
+
+  // Readable stream content
+  yield {
+    kind: 'file',
+    path: 'stream.dat',
+    content: {
+      kind: 'readable',
+      length: 1024,
+      readable: myReadableStream
+    }
+    // ... other properties
+  };
+
+  // Async generator content
+  yield {
+    kind: 'file',
+    path: 'generated.dat',
+    content: {
+      kind: 'generator',
+      length: 2048,
+      generator: myAsyncGenerator   // (each yielding `Buffer` instance)
+    }
+    // ... other properties
+  };
+};
+```
+
+### Stat reflection options
+
+```typescript
+import { createReadFileItem, ReflectStats } from 'tar-vern';
+
+// Don't reflect any file stats (use provided options only)
+yield await createReadFileItem('file.txt', '/source.txt',
+  'none', {    // Don't reflect
+    mode: 0o644,
+    uid: 1000,
+    gid: 1000
+  });
+
+// Reflect all stats except username/groupname
+yield await createReadFileItem('file.txt', '/source.txt',
+  'exceptName');   // except names
+
+// Reflect all stats including numeric uid/gid as names
+yield await createReadFileItem('file.txt', '/source.txt',
+  'all');   // reflect all stats
+```
+
+----
+
+## Usage for tar unpacking
+
+TODO:
+
+----
+
+## License
+
+Under MIT.

package/README_pack.md

@@ -0,0 +1,79 @@
+# Tape archiver library for Typescript
+
+Tape archiver (tar) library for Typescript implementation.
+
+[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+----
+
+## What is this?
+
+A modern TypeScript library for creating tape archives (tar/ustar format) using streaming API. Supports both files and directories with metadata preservation, GZip compression, readable streaming, and flexible content sources.
+
+## Features
+
+- Streaming API: Memory-efficient processing of large files
+- Multiple content sources: String, Buffer, ReadableStream, file paths and async generators
+- Metadata preservation: File permissions, ownership, timestamps
+- Built-in compression: GZip compression support (`tar.gz` format)
+- No any other dependencies.
+
+## Installation
+
+```bash
+npm install tar-vern
+```
+
+----
+
+## Usage for tar packing
+
+### Basic example
+
+```typescript
+import { createTarPacker, storeReaderToFile } from 'tar-vern';
+import { createWriteStream } from 'fs';
+
+// Create an async generator for tar entries
+const generator = async function*() {
+  // Add a simple text file
+  yield {
+    kind: 'file',
+    path: 'hello.txt',
+    mode: 0o644,
+    uname: 'user',
+    gname: 'group',
+    uid: 1000,
+    gid: 1000,
+    date: new Date(),
+    content: 'Hello, world!'   // text contents
+  };
+  
+  // Add a directory
+  yield {
+    kind: 'directory',
+    path: 'mydir',
+    mode: 0o755,
+    uname: 'user',
+    gname: 'group',
+    uid: 1000,
+    gid: 1000,
+    date: new Date()
+  };
+};
+
+// Create tar stream and write to file
+const packer = createTarPacker(generator());
+await storeReaderToFile(packer, 'archive.tar');   // Use helper to awaitable
+```
+
+----
+
+For more information, [see repository documents](http://github.com/kekyo/tar-vern/).
+
+----
+
+## License
+
+Under MIT.

package/dist/generated/packageMetadata.d.ts

@@ -0,0 +1,16 @@
+/*!
+ * name: tar-vern
+ * version: 0.1.0
+ * description: Tape archiver library for Typescript
+ * author: Kouji Matsui (@kekyo@mi.kekyo.net)
+ * license: MIT
+ * repository.url: https://github.com/kekyo/tar-vern.git
+ */
+
+export declare const name = "tar-vern";
+export declare const version = "0.1.0";
+export declare const description = "Tape archiver library for Typescript";
+export declare const author = "Kouji Matsui (@kekyo@mi.kekyo.net)";
+export declare const license = "MIT";
+export declare const repository_url = "https://github.com/kekyo/tar-vern.git";
+//# sourceMappingURL=packageMetadata.d.ts.map

package/dist/generated/packageMetadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packageMetadata.d.ts","sourceRoot":"","sources":["../../src/generated/packageMetadata.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,IAAI,aAAa,CAAC;AAC/B,eAAO,MAAM,OAAO,UAAU,CAAC;AAC/B,eAAO,MAAM,WAAW,yCAAyC,CAAC;AAClE,eAAO,MAAM,MAAM,uCAAuC,CAAC;AAC3D,eAAO,MAAM,OAAO,QAAQ,CAAC;AAC7B,eAAO,MAAM,cAAc,0CAA0C,CAAC"}

package/dist/index.cjs

@@ -0,0 +1,324 @@
+/*!
+ * name: tar-vern
+ * version: 0.1.0
+ * description: Tape archiver library for Typescript
+ * author: Kouji Matsui (@kekyo@mi.kekyo.net)
+ * license: MIT
+ * repository.url: https://github.com/kekyo/tar-vern.git
+ */
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const stream = require("stream");
+const zlib = require("zlib");
+const fs = require("fs");
+const promises = require("fs/promises");
+const utf8ByteLength = (str) => {
+  return Buffer.byteLength(str, "utf8");
+};
+const truncateUtf8Safe = (str, maxBytes) => {
+  let total = 0;
+  let i = 0;
+  while (i < str.length) {
+    const codePoint = str.codePointAt(i);
+    const char = String.fromCodePoint(codePoint);
+    const charBytes = Buffer.byteLength(char, "utf8");
+    if (total + charBytes > maxBytes) break;
+    total += charBytes;
+    i += char.length;
+  }
+  return str.slice(0, i);
+};
+const MAX_NAME = 100;
+const MAX_PREFIX = 155;
+const splitPath = (path) => {
+  if (utf8ByteLength(path) <= MAX_NAME) {
+    return { prefix: "", name: path };
+  }
+  const parts = path.split("/");
+  let name = parts.pop() ?? "";
+  let prefix = parts.join("/");
+  if (utf8ByteLength(name) > MAX_NAME) {
+    name = truncateUtf8Safe(name, MAX_NAME);
+  }
+  while (utf8ByteLength(prefix) > MAX_PREFIX) {
+    prefix = truncateUtf8Safe(prefix, MAX_PREFIX);
+  }
+  return { prefix, name };
+};
+const getOctalBytes = (value, length) => {
+  const str = value.toString(8).padStart(length - 1, "0") + "\0";
+  return Buffer.from(str, "ascii");
+};
+const getPaddedBytes = (buffer) => {
+  const extra = buffer.length % 512;
+  if (extra === 0) {
+    return buffer;
+  } else {
+    return Buffer.concat([buffer, Buffer.alloc(512 - extra, 0)]);
+  }
+};
+const terminatorBytes = Buffer.alloc(1024, 0);
+const createTarHeader = (type, path, size, mode, uname, gname, uid, gid, date) => {
+  const buffer = Buffer.alloc(512, 0);
+  const { name, prefix } = splitPath(path);
+  buffer.write(name, 0, 100, "utf8");
+  getOctalBytes(mode & 4095, 8).copy(buffer, 100);
+  getOctalBytes(uid, 8).copy(buffer, 108);
+  getOctalBytes(gid, 8).copy(buffer, 116);
+  getOctalBytes(size, 12).copy(buffer, 124);
+  getOctalBytes(Math.floor(date.getTime() / 1e3), 12).copy(buffer, 136);
+  Buffer.from("        ", "ascii").copy(buffer, 148);
+  if (type === "file") {
+    buffer.write("0", 156, 1, "ascii");
+  } else {
+    buffer.write("5", 156, 1, "ascii");
+  }
+  buffer.write("ustar\0", 257, 6, "ascii");
+  buffer.write("00", 263, 2, "ascii");
+  buffer.write(uname, 265, 32, "utf8");
+  buffer.write(gname, 297, 32, "utf8");
+  buffer.write(prefix, 345, 155, "utf8");
+  let sum = 0;
+  for (let i = 0; i < 512; i++) {
+    sum += buffer[i];
+  }
+  getOctalBytes(sum, 8).copy(buffer, 148);
+  return buffer;
+};
+const createTarPacker = (entryItemGenerator, compressionType, signal) => {
+  const entryItemIterator = async function* () {
+    for await (const entryItem of entryItemGenerator) {
+      signal?.throwIfAborted();
+      switch (entryItem.kind) {
+        // Entry is a file
+        case "file": {
+          const entryItemContent = entryItem.content;
+          if (typeof entryItemContent === "string") {
+            const contentBytes = Buffer.from(entryItemContent, "utf8");
+            const tarHeaderBytes = createTarHeader(
+              "file",
+              entryItem.path,
+              contentBytes.length,
+              entryItem.mode,
+              entryItem.uname,
+              entryItem.gname,
+              entryItem.uid,
+              entryItem.gid,
+              entryItem.date
+            );
+            yield tarHeaderBytes;
+            const paddedContentBytes = getPaddedBytes(contentBytes);
+            yield paddedContentBytes;
+          } else if (Buffer.isBuffer(entryItemContent)) {
+            const tarHeaderBytes = createTarHeader(
+              "file",
+              entryItem.path,
+              entryItemContent.length,
+              entryItem.mode,
+              entryItem.uname,
+              entryItem.gname,
+              entryItem.uid,
+              entryItem.gid,
+              entryItem.date
+            );
+            yield tarHeaderBytes;
+            const paddedContentBytes = getPaddedBytes(entryItemContent);
+            yield paddedContentBytes;
+          } else {
+            const tarHeaderBytes = createTarHeader(
+              "file",
+              entryItem.path,
+              entryItemContent.length,
+              entryItem.mode,
+              entryItem.uname,
+              entryItem.gname,
+              entryItem.uid,
+              entryItem.gid,
+              entryItem.date
+            );
+            yield tarHeaderBytes;
+            switch (entryItemContent.kind) {
+              // Content is a generator
+              case "generator": {
+                let position = 0;
+                for await (const contentFragmentBytes of entryItemContent.generator) {
+                  signal?.throwIfAborted();
+                  yield contentFragmentBytes;
+                  position += contentFragmentBytes.length;
+                }
+                if (position % 512 !== 0) {
+                  signal?.throwIfAborted();
+                  yield Buffer.alloc(512 - position % 512, 0);
+                }
+                break;
+              }
+              // Content is a readable stream
+              case "readable": {
+                let position = 0;
+                for await (const content of entryItemContent.readable) {
+                  signal?.throwIfAborted();
+                  if (typeof content === "string") {
+                    const stringBytes = Buffer.from(content, "utf8");
+                    yield stringBytes;
+                    position += stringBytes.length;
+                  } else if (Buffer.isBuffer(content)) {
+                    yield content;
+                    position += content.length;
+                  }
+                }
+                if (position % 512 !== 0) {
+                  signal?.throwIfAborted();
+                  yield Buffer.alloc(512 - position % 512, 0);
+                }
+                break;
+              }
+            }
+          }
+          break;
+        }
+        // Entry is a directory
+        case "directory": {
+          const tarHeaderBytes = createTarHeader(
+            "directory",
+            entryItem.path,
+            0,
+            entryItem.mode,
+            entryItem.uname,
+            entryItem.gname,
+            entryItem.uid,
+            entryItem.gid,
+            entryItem.date
+          );
+          yield tarHeaderBytes;
+          break;
+        }
+      }
+    }
+    yield terminatorBytes;
+  };
+  const ct = compressionType ?? "none";
+  switch (ct) {
+    // No compression
+    case "none": {
+      return stream.Readable.from(entryItemIterator());
+    }
+    // Gzip compression
+    case "gzip": {
+      const gzipStream = zlib.createGzip({ level: 9 });
+      const entryItemStream = stream.Readable.from(entryItemIterator());
+      entryItemStream.pipe(gzipStream);
+      return gzipStream;
+    }
+  }
+};
+const getUName = (candidateName, candidateId, reflectStat) => {
+  return candidateName ?? (reflectStat === "all" ? candidateId.toString() : "root");
+};
+const createDirectoryItem = async (path, reflectStat, options) => {
+  const rs = reflectStat ?? "none";
+  if (rs !== "none" && options?.directoryPath) {
+    const stats = await promises.stat(options.directoryPath);
+    const mode = options?.mode ?? stats.mode;
+    const uid = options?.uid ?? stats.uid;
+    const gid = options?.gid ?? stats.gid;
+    const date = options?.date ?? stats.mtime;
+    const uname = getUName(options?.uname, stats.uid, rs);
+    const gname = getUName(options?.gname, stats.gid, rs);
+    return {
+      kind: "directory",
+      path,
+      mode,
+      uname,
+      gname,
+      uid,
+      gid,
+      date
+    };
+  } else {
+    const mode = options?.mode ?? 493;
+    const uid = options?.uid ?? 0;
+    const gid = options?.gid ?? 0;
+    const date = options?.date ?? /* @__PURE__ */ new Date();
+    const uname = getUName(options?.uname, void 0, rs);
+    const gname = getUName(options?.gname, void 0, rs);
+    return {
+      kind: "directory",
+      path,
+      mode,
+      uname,
+      gname,
+      uid,
+      gid,
+      date
+    };
+  }
+};
+const createReadableItem = async (path, reader, options) => {
+  let readable = reader;
+  let length = options?.length;
+  if (!length) {
+    const chunks = [];
+    length = 0;
+    for await (const chunk of reader) {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf8");
+      chunks.push(buffer);
+      length += buffer.length;
+    }
+    readable = stream.Readable.from(chunks);
+  }
+  const mode = options?.mode ?? 420;
+  const uid = options?.uid ?? 0;
+  const gid = options?.gid ?? 0;
+  const date = options?.date ?? /* @__PURE__ */ new Date();
+  const uname = options?.uname ?? "root";
+  const gname = options?.gname ?? "root";
+  return {
+    kind: "file",
+    path,
+    mode,
+    uname,
+    gname,
+    uid,
+    gid,
+    date,
+    content: {
+      kind: "readable",
+      length,
+      readable
+    }
+  };
+};
+const createReadFileItem = async (path, filePath, reflectStat, options) => {
+  const rs = reflectStat ?? "exceptName";
+  const stats = await promises.stat(filePath);
+  const reader = fs.createReadStream(filePath);
+  const mode = options?.mode ?? (rs !== "none" ? stats.mode : void 0);
+  const uid = options?.uid ?? (rs !== "none" ? stats.uid : void 0);
+  const gid = options?.gid ?? (rs !== "none" ? stats.gid : void 0);
+  const date = options?.date ?? (rs !== "none" ? stats.mtime : void 0);
+  const uname = getUName(options?.uname, stats.uid, rs);
+  const gname = getUName(options?.gname, stats.gid, rs);
+  return await createReadableItem(path, reader, {
+    length: stats.size,
+    mode,
+    uname,
+    gname,
+    uid,
+    gid,
+    date
+  });
+};
+const storeReaderToFile = (reader, path) => {
+  const writer = fs.createWriteStream(path);
+  reader.pipe(writer);
+  return new Promise((res, rej) => {
+    writer.on("finish", res);
+    writer.on("error", rej);
+  });
+};
+exports.createDirectoryItem = createDirectoryItem;
+exports.createReadFileItem = createReadFileItem;
+exports.createReadableItem = createReadableItem;
+exports.createTarPacker = createTarPacker;
+exports.storeReaderToFile = storeReaderToFile;
+//# sourceMappingURL=index.cjs.map