zstdify-cli 1.0.2 → 1.1.0

package/README.md

@@ -7,6 +7,14 @@
 
 Command-line tool for compressing and decompressing files with zstd. Built on the [zstdify](https://www.npmjs.com/package/zstdify) package (pure TypeScript, no native dependencies).
 
+## Features
+
+- **Pure JS/TS zstd CLI**: No native addon dependency, portable across Node.js environments.
+- **Compression + extraction workflows**: Simple file-to-file commands with level/checksum controls.
+- **Interop-focused**: Files produced by `zstdify` are decoded by the official `zstd` CLI, and `zstd` output is decoded by `zstdify`.
+- **Robust command UX**: Clear subcommands, aliases, and actionable error messages.
+- **Optional dictionary support**: Train dictionaries from samples and use them with `compress`/`extract` when needed.
+
 ## Installation
 
 ```sh
@@ -19,6 +27,7 @@ pnpm add -g zstdify-cli
 | ------- | ----------- |
 | `zstdify compress <input> <output>` | Compress a file with zstd |
 | `zstdify extract <input> <output>` | Decompress a zstd-compressed file |
+| `zstdify dict train <output> --input <path>...` | Train a dictionary from sample files/directories |
 
 Aliases: `compress` / `c`, `extract` / `x`.
 
@@ -26,6 +35,23 @@ Aliases: `compress` / `c`, `extract` / `x`.
 
 - `--level`, `-l` — Compression level (0=raw, 1+=RLE, 2+=compressed blocks)
 - `--checksum` — Add content checksum to the frame
+- `--dict` — Dictionary file path to use for compression
+- `--dictID` — Dictionary ID to store in the frame header
+- `--noDictId` — Do not write dictID in frame header
+
+### Options (extract)
+
+- `--dict` — Dictionary file path for dictionary-compressed input
+- `--dictID` — Expected dictionary ID for validation
+
+### Options (dict train)
+
+- `--recursive` — Recursively collect files from input directories
+- `--maxSamples` — Maximum number of sample files to load
+- `--algorithm` — `fastcover`, `cover`, or `legacy`
+- `--maxdict` — Maximum dictionary size in bytes
+- `--dictID` — Optional dictionary ID metadata setting
+- Advanced tuning knobs: `--k`, `--d`, `--steps`, `--split`, `--f`, `--accel`, `--selectivity`, `--shrink`
 
 ## Examples
 
@@ -33,8 +59,27 @@ Aliases: `compress` / `c`, `extract` / `x`.
 zstdify compress input.txt output.zst
 zstdify compress input.txt output.zst --level 2
 zstdify extract output.zst restored.txt
+zstdify dict train my.dict --input samples/ --recursive --maxdict 2048
+zstdify compress input.txt output.zst --dict my.dict --dictID 42
+zstdify extract output.zst restored.txt --dict my.dict --dictID 42
 ```
 
+## How we validate
+
+CLI behavior is covered by automated tests (`pnpm vitest`, including `packages/cli-tests`):
+
+- **CLI round-trip**: `zstdify compress` -> `zstdify extract` restores original file bytes.
+- **Core flags and aliases**: Compression levels, checksums, and command aliases are exercised.
+- **Differential interop with official zstd CLI**:
+  - `zstd` output is extracted by `zstdify-cli`.
+  - `zstdify-cli` output is decompressed by `zstd`.
+  - These checks run across standard (non-dictionary) workflows.
+- **Dictionary interop coverage**:
+  - `zstd -D dict` compressed streams are extracted by `zstdify-cli --dict`.
+  - `zstdify-cli --dict` compressed streams are decompressed by `zstd -D dict`.
+  - Coverage includes both zstd-trained and zstdify-trained dictionaries.
+- **Error paths**: Missing files and invalid inputs produce non-zero exits and actionable messages.
+
 # License
 
 MIT

package/dist/commands/compress.d.ts

@@ -6,4 +6,10 @@ export declare const command: import("yargs-file-commands").DefineCommandResult<
     level: number | undefined;
 } & {
     checksum: boolean;
+} & {
+    dict: string | undefined;
+} & {
+    dictID: number | undefined;
+} & {
+    noDictId: boolean;
 }>;

package/dist/commands/compress.js

@@ -26,16 +26,40 @@ export const command = defineCommand({
         describe: 'Add content checksum to the frame',
         type: 'boolean',
         default: false,
+    })
+        .option('dict', {
+        describe: 'Dictionary file path to use for compression',
+        type: 'string',
+    })
+        .option('dictID', {
+        describe: 'Dictionary ID to store in frame header',
+        type: 'number',
+    })
+        .option('noDictId', {
+        describe: "Don't write dictID into frame header",
+        type: 'boolean',
+        default: false,
     }),
     handler: async (argv) => {
-        const { input, output, level, checksum } = argv;
+        const { input, output, level, checksum, dict, dictID, noDictId } = argv;
         if (!fs.existsSync(input)) {
             console.error(`Error: Input file not found: ${input}`);
             process.exit(1);
         }
+        if (dict && !fs.existsSync(dict)) {
+            console.error(`Error: Dictionary file not found: ${dict}`);
+            process.exit(1);
+        }
         try {
             const inputBuf = fs.readFileSync(input);
             const data = new Uint8Array(inputBuf.buffer, inputBuf.byteOffset, inputBuf.byteLength);
+            const dictionary = dict
+                ? (() => {
+                    const dictBuf = fs.readFileSync(dict);
+                    const bytes = new Uint8Array(dictBuf.buffer, dictBuf.byteOffset, dictBuf.byteLength);
+                    return dictID !== undefined ? { bytes, id: dictID } : bytes;
+                })()
+                : undefined;
             const outDir = path.dirname(output);
             if (outDir) {
                 fs.mkdirSync(outDir, { recursive: true });
@@ -43,6 +67,8 @@ export const command = defineCommand({
             const result = compress(data, {
                 level,
                 checksum,
+                dictionary,
+                noDictId,
             });
             fs.writeFileSync(output, result);
             console.log(`Compressed ${input} -> ${output}`);

package/dist/commands/compress.js.map

@@ -1 +1 @@
-{"version":3,"file":"compress.js","sourceRoot":"","sources":["../../src/commands/compress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,MAAM,CAAC,MAAM,OAAO,GAAG,aAAa,CAAC;IACnC,OAAO,EAAE,2BAA2B;IACpC,QAAQ,EAAE,2BAA2B;IACrC,OAAO,EAAE,CAAC,GAAG,CAAC;IACd,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,KAAK;SACF,UAAU,CAAC,OAAO,EAAE;QACnB,QAAQ,EAAE,iBAAiB;QAC3B,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI;KACnB,CAAC;SACD,UAAU,CAAC,QAAQ,EAAE;QACpB,QAAQ,EAAE,gCAAgC;QAC1C,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI;KACnB,CAAC;SACD,MAAM,CAAC,OAAO,EAAE;QACf,QAAQ,EAAE,yDAAyD;QACnE,IAAI,EAAE,QAAQ;QACd,KAAK,EAAE,GAAG;KACX,CAAC;SACD,MAAM,CAAC,UAAU,EAAE;QAClB,QAAQ,EAAE,mCAAmC;QAC7C,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,KAAK;KACf,CAAC;IACN,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC;QACvB,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;QAEhD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,CAAC,KAAK,CAAC,gCAAgC,KAAK,EAAE,CAAC,CAAC;YACvD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;YACxC,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;YAEvF,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACpC,IAAI,MAAM,EAAE,CAAC;gBACX,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5C,CAAC;YAED,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE;gBAC5B,KAAK;gBACL,QAAQ;aACT,CAAC,CAAC;YACH,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACjC,OAAO,CAAC,GAAG,CAAC,cAAc,KAAK,OAAO,MAAM,EAAE,CAAC,CAAC;QAClD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,2BAA2B,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;YAC3F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IAAA,CACF;CACF,CAAC,CAAC"}
+{"version":3,"file":"compress.js","sourceRoot":"","sources":["../../src/commands/compress.ts"],"names":[],"mappings":"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"}

package/dist/commands/dict.d.ts

@@ -0,0 +1,31 @@
+export declare const command: import("yargs-file-commands").DefineCommandResult<{}, {
+    output: string;
+} & {
+    input: string[];
+} & {
+    recursive: boolean;
+} & {
+    maxSamples: number;
+} & {
+    algorithm: string;
+} & {
+    maxdict: number | undefined;
+} & {
+    dictID: number | undefined;
+} & {
+    k: number | undefined;
+} & {
+    d: number | undefined;
+} & {
+    steps: number | undefined;
+} & {
+    split: number | undefined;
+} & {
+    f: number | undefined;
+} & {
+    accel: number | undefined;
+} & {
+    selectivity: number | undefined;
+} & {
+    shrink: unknown;
+}>;

package/dist/commands/dict.js

@@ -0,0 +1,129 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { defineCommand } from 'yargs-file-commands';
+import { generateDictionary } from 'zstdify';
+function collectFiles(inputPath, recursive, out) {
+    const stat = fs.statSync(inputPath);
+    if (stat.isFile()) {
+        out.push(inputPath);
+        return;
+    }
+    if (!stat.isDirectory()) {
+        return;
+    }
+    const entries = fs.readdirSync(inputPath, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        const fullPath = path.join(inputPath, entry.name);
+        if (entry.isFile()) {
+            out.push(fullPath);
+        }
+        else if (entry.isDirectory() && recursive) {
+            collectFiles(fullPath, recursive, out);
+        }
+    }
+}
+export const command = defineCommand({
+    command: 'dict train <output>',
+    describe: 'Train and write a dictionary from sample files',
+    builder: (yargs) => yargs
+        .positional('output', {
+        describe: 'Output dictionary file path',
+        type: 'string',
+        demandOption: true,
+    })
+        .option('input', {
+        describe: 'Input sample file or directory path (repeat for multiple)',
+        type: 'string',
+        array: true,
+        alias: 'i',
+        demandOption: true,
+    })
+        .option('recursive', {
+        describe: 'Recursively read files inside input directories',
+        type: 'boolean',
+        default: false,
+    })
+        .option('maxSamples', {
+        describe: 'Maximum number of sample files to load',
+        type: 'number',
+        default: 10_000,
+    })
+        .option('algorithm', {
+        describe: 'Training algorithm style',
+        choices: ['fastcover', 'cover', 'legacy'],
+        default: 'fastcover',
+    })
+        .option('maxdict', {
+        describe: 'Maximum dictionary size in bytes',
+        type: 'number',
+    })
+        .option('dictID', {
+        describe: 'Dictionary ID value (for metadata parity with zstd)',
+        type: 'number',
+    })
+        .option('k', { type: 'number', describe: 'Candidate segment size' })
+        .option('d', { type: 'number', describe: 'Distance step between candidate probes' })
+        .option('steps', { type: 'number', describe: 'Score refinement passes' })
+        .option('split', { type: 'number', describe: 'Percent of each sample to use (1-100)' })
+        .option('f', { type: 'number', describe: 'fastcover-style score multiplier' })
+        .option('accel', { type: 'number', describe: 'Probe stride accelerator (1-10)' })
+        .option('selectivity', { type: 'number', describe: 'legacy-style density control (1-10)' })
+        .option('shrink', {
+        describe: 'Optional shrink pass, true or numeric factor',
+    }),
+    handler: async (argv) => {
+        const { output, input, recursive, maxSamples, algorithm, maxdict, dictID, k, d, steps, split, f, accel, selectivity, shrink, } = argv;
+        const inputPaths = input ?? [];
+        const files = [];
+        for (const inputPath of inputPaths) {
+            if (!fs.existsSync(inputPath)) {
+                console.error(`Error: Input path not found: ${inputPath}`);
+                process.exit(1);
+            }
+            collectFiles(inputPath, recursive, files);
+            if (files.length >= maxSamples)
+                break;
+        }
+        if (files.length === 0) {
+            console.error('Error: No sample files found for dictionary training');
+            process.exit(1);
+        }
+        const selectedFiles = files.slice(0, maxSamples);
+        try {
+            const samples = selectedFiles
+                .map((filePath) => {
+                const buf = fs.readFileSync(filePath);
+                return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+            })
+                .filter((sample) => sample.length > 0);
+            if (samples.length === 0) {
+                console.error('Error: No non-empty sample files found');
+                process.exit(1);
+            }
+            const dictionary = generateDictionary(samples, {
+                algorithm: algorithm,
+                maxDictSize: maxdict,
+                dictId: dictID,
+                k,
+                d,
+                steps,
+                split,
+                f,
+                accel,
+                selectivity,
+                shrink: typeof shrink === 'string' ? Number(shrink) : shrink,
+            });
+            const outDir = path.dirname(output);
+            if (outDir) {
+                fs.mkdirSync(outDir, { recursive: true });
+            }
+            fs.writeFileSync(output, dictionary);
+            console.log(`Trained dictionary (${dictionary.length} bytes) -> ${output}`);
+        }
+        catch (error) {
+            console.error(`Error during dictionary training:`, error instanceof Error ? error.message : error);
+            process.exit(1);
+        }
+    },
+});
+//# sourceMappingURL=dict.js.map

package/dist/commands/dict.js.map

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

package/dist/commands/extract.d.ts

@@ -2,4 +2,8 @@ export declare const command: import("yargs-file-commands").DefineCommandResult<
     input: string;
 } & {
     output: string;
+} & {
+    dict: string | undefined;
+} & {
+    dictID: number | undefined;
 }>;

package/dist/commands/extract.js

@@ -16,21 +16,40 @@ export const command = defineCommand({
         describe: 'Output file path',
         type: 'string',
         demandOption: true,
+    })
+        .option('dict', {
+        describe: 'Dictionary file path for dictionary-compressed input',
+        type: 'string',
+    })
+        .option('dictID', {
+        describe: 'Expected dictionary ID for validation',
+        type: 'number',
     }),
     handler: async (argv) => {
-        const { input, output } = argv;
+        const { input, output, dict, dictID } = argv;
         if (!fs.existsSync(input)) {
             console.error(`Error: Input file not found: ${input}`);
             process.exit(1);
         }
+        if (dict && !fs.existsSync(dict)) {
+            console.error(`Error: Dictionary file not found: ${dict}`);
+            process.exit(1);
+        }
         try {
             const inputBuf = fs.readFileSync(input);
             const data = new Uint8Array(inputBuf.buffer, inputBuf.byteOffset, inputBuf.byteLength);
+            const dictionary = dict
+                ? (() => {
+                    const dictBuf = fs.readFileSync(dict);
+                    const bytes = new Uint8Array(dictBuf.buffer, dictBuf.byteOffset, dictBuf.byteLength);
+                    return dictID !== undefined ? { bytes, id: dictID } : bytes;
+                })()
+                : undefined;
             const outDir = path.dirname(output);
             if (outDir) {
                 fs.mkdirSync(outDir, { recursive: true });
             }
-            const result = decompress(data);
+            const result = decompress(data, dictionary ? { dictionary } : undefined);
             fs.writeFileSync(output, result);
             console.log(`Decompressed ${input} -> ${output}`);
         }

package/dist/commands/extract.js.map

@@ -1 +1 @@
-{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/commands/extract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,MAAM,CAAC,MAAM,OAAO,GAAG,aAAa,CAAC;IACnC,OAAO,EAAE,0BAA0B;IACnC,QAAQ,EAAE,mCAAmC;IAC7C,OAAO,EAAE,CAAC,GAAG,CAAC;IACd,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CACjB,KAAK;SACF,UAAU,CAAC,OAAO,EAAE;QACnB,QAAQ,EAAE,4BAA4B;QACtC,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI;KACnB,CAAC;SACD,UAAU,CAAC,QAAQ,EAAE;QACpB,QAAQ,EAAE,kBAAkB;QAC5B,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE,IAAI;KACnB,CAAC;IACN,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC;QACvB,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAE/B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,CAAC,KAAK,CAAC,gCAAgC,KAAK,EAAE,CAAC,CAAC;YACvD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;YACxC,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;YAEvF,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACpC,IAAI,MAAM,EAAE,CAAC;gBACX,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5C,CAAC;YAED,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;YAChC,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACjC,OAAO,CAAC,GAAG,CAAC,gBAAgB,KAAK,OAAO,MAAM,EAAE,CAAC,CAAC;QACpD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,6BAA6B,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;YAC7F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IAAA,CACF;CACF,CAAC,CAAC"}
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/commands/extract.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zstdify-cli",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "type": "module",
   "description": "CLI for zstd compression and decompression using zstdify",
   "license": "MIT",
@@ -17,7 +17,7 @@
   "dependencies": {
     "yargs": "^17.7.2",
     "yargs-file-commands": "^1.2.2",
-    "zstdify": "^1.0.2"
+    "zstdify": "^1.1.0"
   },
   "devDependencies": {
     "@types/node": "^24",