feat: implement createArchive and CLI support + update workflow with yarn and release-it test hook

Author: teneplaysofficial

.github/workflows/weekly-release.yml

@@ -38,9 +38,10 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 20
+          cache: 'yarn'
 
       - name: Install dependencies
-        run: npm ci
+        run: yarn install --frozen-lockfile
 
       - name: Configure Git user
         run: |

.release-it.json

@@ -21,7 +21,7 @@
     }
   },
   "hooks": {
-    "before:init": "yarn build",
+    "before:init": "yarn test && yarn build",
     "before:commit": "git add .",
     "after:release": "git tag -f v${version.major} && git push -f origin v${version.major}"
   }

bin/index.ts

@@ -1,5 +1,7 @@
 import fs from 'fs';
+import ora from 'ora';
 import { Command } from 'commander';
+import { createArchive } from '../src';
 
 const pkg = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
 
@@ -11,4 +13,33 @@ program
   .version(pkg.version)
   .enablePositionalOptions();
 
+program
+  .command('createArchive')
+  .description('Creates a archive from a specified directory')
+  .requiredOption('-f, --format <format>', 'Archive format (zip or tar)')
+  .requiredOption('-s, --source <source>', 'Source directory path')
+  .requiredOption('-d, --destination <destination>', 'Destination archive file')
+  .action(async (options) => {
+    const spinner = ora('Creating archive...').start();
+    try {
+      await createArchive({
+        format: options.format,
+        source: options.source,
+        destination: options.destination,
+        log: false,
+        onSuccess: (totalBytes) => {
+          spinner.succeed(
+            `Archive created successfully at ${options.destination} (${totalBytes} bytes).`,
+          );
+        },
+      });
+    } catch (err) {
+      spinner.fail(
+        'Failed to create archive: ' +
+          (err instanceof Error ? err.message : 'Unknown error'),
+      );
+      process.exit(1);
+    }
+  });
+
 program.parse();

package.json

@@ -67,15 +67,18 @@
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.1.3",
+    "@types/archiver": "^6.0.3",
     "@types/jest": "^30.0.0",
     "@types/node": "^24.0.4",
+    "archiver": "^7.0.1",
     "commander": "^14.0.0",
     "eslint": "^9.29.0",
     "globals": "^16.2.0",
     "husky": "^9.1.7",
     "jest": "^30.0.3",
     "jest-environment-node": "^30.0.2",
     "lint-staged": "^16.1.2",
+    "ora": "^8.2.0",
     "prettier": "^3.6.0",
     "release-it": "^19.0.3",
     "rollup": "^4.44.0",

rollup.config.js

@@ -49,9 +49,12 @@ export default [
       peerDepsExternal(),
       resolve(),
       commonjs(),
-      typescript({ tsconfig: './tsconfig.json', declaration: false }),
+      typescript({
+        tsconfig: './tsconfig.json',
+        declaration: false,
+      }),
       terser(),
     ],
-    external: ['commander'],
+    external: ['commander', 'ora'],
   },
 ];

src/file/createArchive.ts

@@ -0,0 +1,132 @@
+import fs from 'fs';
+import path from 'path';
+import archiver, { Archiver, ArchiverOptions } from 'archiver';
+export type { ArchiverOptions } from 'archiver';
+
+/**
+ * Supported archive formats.
+ */
+export type ArchiveFormat = 'zip' | 'tar';
+
+/**
+ * Configuration options.
+ */
+export interface CreateArchiveOptions {
+  /**
+   * Archive format to use {@link ArchiveFormat}.
+   */
+  format: ArchiveFormat;
+
+  /**
+   * Path to the source directory that should be archived.
+   */
+  source: string;
+
+  /**
+   * Destination file path where the archive will be written
+   * @example
+   *  - For `zip` format: `dist.zip`
+   *  - For `tar` format: `dist.tar`
+   */
+  destination: string;
+
+  /**
+   * Additional options passed directly to the archiver library. See {@link ArchiverOptions}.
+   */
+  options?: ArchiverOptions;
+
+  /**
+   * Optional flag to enable internal logging. Useful for CLI mode.
+   */
+  log?: boolean;
+
+  /**
+   * Called after archiving is complete — receives total size in bytes.
+   */
+  onSuccess?: (bytes: number) => void;
+}
+
+/**
+ * Creates a {@link ArchiveFormat } archive from a specified directory.
+ *
+ * This function uses the `archiver` library to package a directory into an archive file.
+ * It supports optional compression for `zip` and returns a Promise that resolves
+ * when the archive is successfully created.
+ *
+ * @example
+ *
+ * Function usage:
+ *
+ * ```ts
+ * await createArchive({
+ *   format: "zip",
+ *   source: "dist/",
+ *   destination: "dist.zip",
+ * });
+ * ```
+ *
+ *  CLI usage:
+ * ```sh
+ * npx js-utils-kit createArchive -f zip -s dist -d dist.zip
+ * ```
+ *
+ * @param options - Archive creation options
+ * @returns A Promise that resolves when the archive is created
+ * @throws If an error occurs during the archiving process
+ */
+export function createArchive({
+  format,
+  source,
+  destination,
+  options = {},
+  log = true,
+  onSuccess,
+}: CreateArchiveOptions): Promise<void> {
+  const resolvedSource = path.resolve(source);
+
+  if (
+    !fs.existsSync(resolvedSource) ||
+    !fs.statSync(resolvedSource).isDirectory()
+  ) {
+    throw new Error(
+      `Source directory "${source}" does not exist or is not a directory.`,
+    );
+  }
+
+  const output = fs.createWriteStream(destination);
+
+  if (format === 'zip') {
+    options = {
+      ...options,
+      /**
+       * Maximum compression level for zip is 9.
+       */
+      zlib: { level: 9 },
+    };
+  }
+
+  const archive: Archiver = archiver(format, options);
+
+  return new Promise((resolve, reject) => {
+    output.on('close', () => {
+      const size = archive.pointer();
+
+      if (log) {
+        console.log(`${destination} created: ${size} total bytes`);
+      }
+      if (onSuccess) {
+        onSuccess(size);
+      }
+
+      resolve();
+    });
+
+    archive.on('error', (err: Error) => {
+      reject(err);
+    });
+
+    archive.pipe(output);
+    archive.directory(source, false);
+    archive.finalize();
+  });
+}

src/file/index.ts

@@ -0,0 +1 @@
+export * from './createArchive';

src/index.ts

@@ -0,0 +1 @@
+export * from './file/index';

tests/createArchive.test.ts

@@ -0,0 +1,73 @@
+import fs from 'fs';
+import archiver from 'archiver';
+import { createArchive } from '../src/file/createArchive';
+
+jest.mock('fs');
+jest.mock('archiver');
+
+describe('createArchive', () => {
+  const mockOutput = {
+    on: jest.fn(),
+    once: jest.fn(),
+    emit: jest.fn(),
+    end: jest.fn(),
+  };
+
+  const mockArchive = {
+    pipe: jest.fn(),
+    directory: jest.fn(),
+    finalize: jest.fn(),
+    pointer: jest.fn().mockReturnValue(1024),
+    on: jest.fn(),
+  };
+
+  beforeEach(() => {
+    (fs.createWriteStream as jest.Mock).mockReturnValue(mockOutput);
+    (archiver as unknown as jest.Mock).mockReturnValue(mockArchive);
+    jest.clearAllMocks();
+  });
+
+  it('creates a zip archive and resolves on success', async () => {
+    const promise = createArchive({
+      format: 'zip',
+      source: 'src',
+      destination: 'out.zip',
+    });
+
+    // Simulate close event
+    const closeCallback = mockOutput.on.mock.calls.find(
+      (call) => call[0] === 'close',
+    )?.[1];
+    closeCallback?.();
+
+    await expect(promise).resolves.toBeUndefined();
+
+    expect(fs.createWriteStream).toHaveBeenCalledWith('out.zip');
+    expect(archiver).toHaveBeenCalledWith(
+      'zip',
+      expect.objectContaining({
+        zlib: { level: 9 },
+      }),
+    );
+    expect(mockArchive.pipe).toHaveBeenCalledWith(mockOutput);
+    expect(mockArchive.directory).toHaveBeenCalledWith('src', false);
+    expect(mockArchive.finalize).toHaveBeenCalled();
+  });
+
+  it('rejects if archiver emits an error', async () => {
+    const promise = createArchive({
+      format: 'zip',
+      source: 'src',
+      destination: 'out.zip',
+    });
+
+    // Simulate error event
+    const errorCallback = mockArchive.on.mock.calls.find(
+      (call) => call[0] === 'error',
+    )?.[1];
+    const error = new Error('Archiver failed');
+    errorCallback?.(error);
+
+    await expect(promise).rejects.toThrow('Archiver failed');
+  });
+});

typedoc.json

@@ -3,13 +3,16 @@
   "out": "docs",
   "includeVersion": true,
   "excludePrivate": true,
-  "excludeProtected": true,
+  "excludeProtected": false,
   "excludeInternal": true,
-  "excludeExternals": true,
+  "excludeExternals": false,
   "readme": "README.md",
   "tsconfig": "tsconfig.json",
   "name": "JS Utils Kit",
   "categorizeByGroup": true,
   "sort": ["source-order"],
-  "plugin": []
+  "plugin": [],
+  "gitRemote": "origin",
+  "gitRevision": "main",
+  "githubPages": true
 }