@publint/pack/src/index.d.ts

Utilities for packing and unpacking npm packages

export type PackageManager = 'npm' | 'yarn' | 'pnpm' | 'bun'

interface SharedPackOptions {
  /**
   * The package manager to use for packing.
   *
   * @default 'npm'
   */
  packageManager?: PackageManager
  /**
   * Whether to ignore lifecycle scripts during packing, i.e. `prepare`, `prepack`,
   * and `postpack`. (Does not work with yarn as it does not support ignoring scripts)
   *
   * @default false
   */
  ignoreScripts?: boolean
}

export interface PackOptions extends SharedPackOptions {
  /**
   * The destination directory of the packed tarball
   */
  destination?: string
}
/**
 * Packs the given directory and returns the packed tarball path.
 */
export function pack(dir: string, opts?: PackOptions): Promise<string>

export interface PackAsListOptions extends SharedPackOptions {}
/**
 * Packs the given directory and returns a list of relative file paths that were packed.
 *
 * The relative file paths should be resolved via `getPackDirectory()` if a different
 * packed directory was used.
 */
export function packAsList(dir: string, opts?: PackAsListOptions): Promise<string[]>

export interface PackAsJsonOptions extends SharedPackOptions {}
/**
 * Packs the given directory with the `--json` flag and returns its stdout as JSON.
 * You can run the `<pm> pack --json` command manually to inspect the output shape.
 *
 * Relative file paths in the output can be resolved via `getPackDirectory()` if a
 * different packed directory was used.
 *
 * NOTE: Does not work in pnpm <9.14.1 and bun as they don't support the `--json` flag.
 */
export function packAsJson(dir: string, opts?: PackAsJsonOptions): Promise<any>

/**
 * Gets the directory that is being packed by the package manager. Usually this is
 * the same as the input `dir`, but some package managers (like pnpm) allows changing
 * the packed directory via the `publishConfig.directory` field in `package.json`.
 *
 * @param packageManager The package manager to use for packing. Defaults to 'npm'.
 */
export function getPackDirectory(dir: string, packageManager?: PackageManager): Promise<string>

export interface TarballFile {
  name: string
  data: Uint8Array
}

export interface UnpackResult {
  /**
   * The packed files. Usually with names like "package/src/index.js".
   */
  files: TarballFile[]
  /**
   * The root/shared directory among all packed files, e.g. "package".
   *
   * Usually npm-packed tarball uses "package" as the root directory,
   * however some publishes, like from `@types/*` have different root
   * directories instead. This field helps to identify it.
   */
  rootDir: string
}
/**
 * Unpacks the given tarball buffer (gzip-decompress + untar). It accepts
 * either a `ReadableStream`, `ArrayBuffer`, or `Uint8Array`. In Node.js,
 * `ArrayBuffer` and `Uint8Array` are faster, while in browsers, `ReadableStream`
 * is faster.
 *
 * For example, when using `fetch()` in Node.js, use `response.arrayBuffer()` or
 * `response.bytes()`, while in browsers, use `response.body` directly.
 */
export function unpack(
  tarball: ReadableStream<Uint8Array> | ArrayBuffer | Uint8Array,
): Promise<UnpackResult>