tar pack, list and extract: working versions (tested 2026-10-17)

{
  "name": "tar-pack-extract",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node --import tsx --test test/*.test.ts"
  },
  "dependencies": {
    "tar": "7.5.22"
  },
  "devDependencies": {
    "@types/node": "26.6.5",
    "tsx": "4.23.15"
  }
}

import * as fs from "node:fs";
import * as path from "node:path";
import * as tar from "tar";

export type Tree = Record<string, string>;

export function writeTree(root: string, tree: Tree): void {
  for (const [rel, contents] of Object.entries(tree)) {
    const target = path.join(root, rel);
    fs.mkdirSync(path.dirname(target), { recursive: true });
    fs.writeFileSync(target, contents, "utf8");
  }
}

export function createTarball(sourceDir: string, tarball: string, entries: string[]): void {
  tar.create(
    {
      cwd: sourceDir,
      file: tarball,
      gzip: true,
      sync: true,
    },
    entries,
  );
}

export function listEntries(tarball: string): string[] {
  const names: string[] = [];
  tar.list({
    file: tarball,
    sync: true,
    onReadEntry: (entry) => {
      names.push(entry.path);
    },
  });
  return names;
}

export type ExtractOptions = {
  strip?: number;
  filter?: (entryPath: string) => boolean;
};

export function extractTarball(tarball: string, destDir: string, options: ExtractOptions = {}): void {
  fs.mkdirSync(destDir, { recursive: true });
  tar.extract({
    file: tarball,
    cwd: destDir,
    strip: options.strip,
    filter: options.filter,
    sync: true,
  });
}

import { test } from "node:test";
import assert from "node:assert/strict";
import * as fs from "node:fs";
import * as os from "node:os";
import * as path from "node:path";
import { createTarball, extractTarball, listEntries, writeTree } from "../src/pack.ts";

function makeSource(): string {
  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "tar-src-"));
  writeTree(dir, {
    "pkg/index.ts": "export const answer = 42;\n",
    "pkg/util/helper.ts": "export const greet = (name: string): string => `hi ${name}`;\n",
    "pkg/notes.md": "# notes\n",
    "pkg/secret/key.txt": "top-secret\n",
  });
  return dir;
}

test("creates a gzipped tarball and lists its file entries", () => {
  const source = makeSource();
  const tarball = path.join(fs.mkdtempSync(path.join(os.tmpdir(), "tar-out-")), "pkg.tgz");

  createTarball(source, tarball, ["pkg"]);

  assert.ok(fs.existsSync(tarball));

  const magic = fs.readFileSync(tarball).subarray(0, 2);
  assert.deepEqual([...magic], [0x1f, 0x8b]);

  const files = listEntries(tarball)
    .filter((name) => !name.endsWith("/"))
    .sort();

  assert.deepEqual(files, [
    "pkg/index.ts",
    "pkg/notes.md",
    "pkg/secret/key.txt",
    "pkg/util/helper.ts",
  ]);
});

test("extracts with a filter and strip, preserving contents", () => {
  const source = makeSource();
  const workdir = fs.mkdtempSync(path.join(os.tmpdir(), "tar-work-"));
  const tarball = path.join(workdir, "pkg.tgz");
  const dest = path.join(workdir, "out");

  createTarball(source, tarball, ["pkg"]);

  extractTarball(tarball, dest, {
    strip: 1,
    filter: (entryPath) => !entryPath.includes("secret"),
  });

  assert.equal(
    fs.readFileSync(path.join(dest, "index.ts"), "utf8"),
    "export const answer = 42;\n",
  );
  assert.equal(
    fs.readFileSync(path.join(dest, "util/helper.ts"), "utf8"),
    "export const greet = (name: string): string => `hi ${name}`;\n",
  );
  assert.equal(fs.readFileSync(path.join(dest, "notes.md"), "utf8"), "# notes\n");
  assert.equal(fs.existsSync(path.join(dest, "secret")), false);
});