vsix-utils/dist/zip.d.cts

utilities for working with VSIX packages

import { Buffer } from 'node:buffer';
import { V as VsixFile } from './files-BaC4caRh.cjs';
import './types.cjs';
import './manifest.cjs';

/**
 * @module zip
 *
 * This module contains utility functions for creating and reading vsix files.
 *
 *  @example
 * ```ts
 * import { writeVsix } from "vsix-utils/zip";
 *
 * const success = await writeVsix({
 *   files: [
 *     {
 *       "type": "local",
 *       "localPath": "path/to/file.txt",
 *       "path": "file.txt"
 *     },
 *     {
 *       "type": "in-memory",
 *       "contents": "file contents", // or use a buffer
 *       "path": "file.txt"
 *     }
 *   ],
 * });
 *
 * console.log(sucesss) // true
 * ```
 *
 * @example
 * ```ts
 * import { readVsix } from "vsix-utils/zip";
 *
 * const { files, manifest } = await readVsix({
 *   packagePath: "path/to/package.vsix"
 * });
 *
 * console.log(files) // Map { 'file.txt' => <Buffer 66 69 6c 65 20 63 6f 6e 74 65 6e 74 73> }
 * ```
 */

interface WriteVsixOptions {
    /**
     * The files that should be included in the Vsix package.
     */
    files: VsixFile[];
    /**
     * The path to write the Vsix package to.
     */
    packagePath: string;
    /**
     * Force the package to be written even if it a file already exists.
     * @default false
     */
    force?: boolean;
    /**
     * The source date epoch to use for the package.
     */
    epoch?: number;
}
/**
 * Writes files to a VSIX package.
 *
 * @param {WriteVsixOptions} options - Configuration options for writing the VSIX package
 * @param {VsixFile[]} options.files - Array of files to include in the package. Can be either in-memory files or files from disk
 * @param {string} options.packagePath - File path where the VSIX package should be written
 * @param {boolean?} options.force - If true, overwrites existing package at packagePath. If false, throws error if package exists
 * @param {number?} options.epoch - Optional timestamp (in seconds) to use for all files in the package. Files will be sorted alphabetically
 *
 * @returns {Promise<boolean>} Promise that resolves to true when package is successfully written
 * @throws {Error} if no files specified, no package path specified, or if package exists and force is false
 *
 * @example
 * ```ts
 * import { writeVsix } from "vsix-utils/zip";
 *
 * const success = await writeVsix({
 *   files: [
 *     {
 *       "type": "local",
 *       "localPath": "path/to/file.txt",
 *       "path": "file.txt"
 *     },
 *     {
 *       "type": "in-memory",
 *       "contents": "file contents", // or use a buffer
 *       "path": "file.txt"
 *     }
 *   ],
 * });
 * ```
 */
declare function writeVsix(options: WriteVsixOptions): Promise<boolean>;
interface ReadVsixOptions {
    /**
     * The path to the Vsix package to read.
     */
    packagePath: string;
}
interface RawVsixPackage {
    /**
     * Files of the VSIX package.
     */
    files: Map<string, Buffer>;
    /**
     * The manifest of the VSIX package.
     */
    manifest: Record<string, unknown>;
}
/**
 * Reads and extracts the contents of a VSIX package.
 *
 * @param {ReadVsixOptions} options - The options for reading the VSIX package
 * @param {string} options.packagePath - The file path to the VSIX package
 *
 * @returns {Promise<RawVsixPackage>} A promise that resolves to a {@link RawVsixPackage} containing:
 * - files: A Map of filenames to their contents as Buffers
 * - manifest: The parsed extension.vsixmanifest file as an object
 *
 * @throws Will throw an error if:
 * - The VSIX file cannot be opened
 * - There are errors reading the zip entries
 * - The manifest file is missing or invalid JSON
 */
declare function readVsix(options: ReadVsixOptions): Promise<RawVsixPackage>;

export { type RawVsixPackage, type ReadVsixOptions, type WriteVsixOptions, readVsix, writeVsix };