or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-pnpm--lockfile-filtering

Utilities for filtering pnpm lockfile dependencies and workspace packages.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@pnpm/lockfile.filtering@1001.0.x

To install, run

npx @tessl/cli install tessl/npm-pnpm--lockfile-filtering@1001.0.0

index.mddocs/

@pnpm/lockfile.filtering

Overview

@pnpm/lockfile.filtering is an internal pnpm utility package that provides functions for filtering pnpm lockfile dependencies and workspace packages. This package enables selective filtering of lockfile entries based on importers (workspace projects), dependency types, and engine compatibility, allowing for optimized installations and dependency management in pnpm workspaces.

This package is primarily designed for internal use within the pnpm ecosystem, including pnpm core, plugins, and extensions that need to manipulate lockfile data.

Package Information

  • Name: @pnpm/lockfile.filtering
  • Type: npm package (internal pnpm workspace package)
  • Language: TypeScript
  • Installation: This is an internal pnpm package. Install via pnpm itself or use in pnpm plugins/extensions

Core Imports

// ESM
import { 
  filterLockfile, 
  filterLockfileByImporters, 
  filterLockfileByImportersAndEngine, 
  filterLockfileByEngine
} from "@pnpm/lockfile.filtering";

// Note: Type imports need to be imported from the specific module
import type { FilterLockfileResult, FilterLockfileOptions } from "@pnpm/lockfile.filtering/lib/filterLockfileByImportersAndEngine";

// CommonJS
const { 
  filterLockfile, 
  filterLockfileByImporters, 
  filterLockfileByImportersAndEngine, 
  filterLockfileByEngine 
} = require("@pnpm/lockfile.filtering");

Basic Usage

import { filterLockfile } from "@pnpm/lockfile.filtering";
import type { LockfileObject, DepPath } from "@pnpm/lockfile.types";
import type { DependenciesField } from "@pnpm/types";

// Filter lockfile to include only production dependencies
const filteredLockfile = filterLockfile(lockfile, {
  include: {
    dependencies: true,
    devDependencies: false,
    optionalDependencies: false
  },
  skipped: new Set<DepPath>()
});

Architecture

The package provides a layered filtering approach:

  • Basic Filtering (filterLockfile): Filters all importers with dependency type selection
  • Importer-Specific Filtering (filterLockfileByImporters): Filters specific workspace projects with error handling options
  • Engine-Aware Filtering (filterLockfileByEngine, filterLockfileByImportersAndEngine): Advanced filtering with Node.js version compatibility, platform architecture support, and package installability validation

The engine-aware functions utilize @pnpm/package-is-installable to validate packages against the current environment, ensuring only compatible packages are included in the filtered lockfile. All filtering functions use @pnpm/lockfile.walker internally to traverse the dependency graph efficiently.

Capabilities

Basic Lockfile Filtering

Filters a lockfile for all importers with specified dependency types.

/**
 * Filters a lockfile for all importers with specified dependency types
 * @param lockfile - The lockfile object to filter
 * @param opts - Filtering options
 * @param opts.include - Specifies which dependency types to include
 * @param opts.skipped - Set of dependency paths to skip
 * @returns Filtered lockfile object
 */
function filterLockfile(
  lockfile: LockfileObject,
  opts: {
    include: { [dependenciesField in DependenciesField]: boolean }
    skipped: Set<DepPath>
  }
): LockfileObject;

Importer-Specific Filtering

Filters a lockfile for specific importers (workspace projects) with dependency type filtering and optional error handling for missing dependencies.

/**
 * Filters a lockfile for specific importers with dependency type filtering
 * @param lockfile - The lockfile object to filter
 * @param importerIds - Array of project IDs to include in filtering
 * @param opts - Filtering options
 * @param opts.include - Specifies which dependency types to include
 * @param opts.skipped - Set of dependency paths to skip
 * @param opts.failOnMissingDependencies - Whether to throw error for missing dependencies
 * @returns Filtered lockfile object
 */
function filterLockfileByImporters(
  lockfile: LockfileObject,
  importerIds: ProjectId[],
  opts: {
    include: { [dependenciesField in DependenciesField]: boolean }
    skipped: Set<DepPath>
    failOnMissingDependencies: boolean
  }
): LockfileObject;

Engine-Compatible Filtering for All Importers

Filters a lockfile for all importers with engine compatibility checking, including Node.js version and platform architecture support.

/**
 * Filters a lockfile for all importers with engine compatibility checking
 * @param lockfile - The lockfile object to filter
 * @param opts - Engine filtering options
 * @returns Object containing filtered lockfile and selected importer IDs
 */
function filterLockfileByEngine(
  lockfile: LockfileObject,
  opts: FilterLockfileOptions
): FilterLockfileResult;

Engine-Compatible Filtering for Specific Importers

Filters a lockfile by specific importers with comprehensive engine compatibility checking, platform support, and package installability validation.

/**
 * Filters a lockfile by importers with engine compatibility checking
 * @param lockfile - The lockfile object to filter
 * @param importerIds - Array of project IDs to include in filtering
 * @param opts - Engine filtering options
 * @returns Object containing filtered lockfile and selected importer IDs
 */
function filterLockfileByImportersAndEngine(
  lockfile: LockfileObject,
  importerIds: ProjectId[],
  opts: FilterLockfileOptions
): FilterLockfileResult;

Types

FilterLockfileResult

Result object returned by engine-aware filtering functions containing the filtered lockfile and metadata about selected importers.

interface FilterLockfileResult {
  /** The filtered lockfile object */
  lockfile: LockfileObject;
  /** Array of project IDs that were selected during filtering */
  selectedImporterIds: ProjectId[];
}

FilterLockfileOptions

Comprehensive options for engine-aware lockfile filtering, including Node.js compatibility, platform architecture support, and error handling preferences.

interface FilterLockfileOptions {
  /** Current engine configuration */
  currentEngine: {
    /** Node.js version for compatibility checking */
    nodeVersion?: string;
    /** pnpm version for compatibility checking */
    pnpmVersion: string;
  };
  /** Whether to strictly enforce engine compatibility */
  engineStrict: boolean;
  /** Specifies which dependency types to include */
  include: { [dependenciesField in DependenciesField]: boolean };
  /** Whether to include packages that are incompatible with current platform */
  includeIncompatiblePackages?: boolean;
  /** Whether to throw error for missing dependencies */
  failOnMissingDependencies: boolean;
  /** Directory path of the lockfile for resolving relative paths */
  lockfileDir: string;
  /** Set of dependency paths to skip during filtering */
  skipped: Set<string>;
  /** Platform architecture configurations for compatibility checking */
  supportedArchitectures?: SupportedArchitectures;
}

Core Type Dependencies

The following types are imported from @pnpm/types and @pnpm/lockfile.types:

/** Union type for dependency field names */
type DependenciesField = 'optionalDependencies' | 'dependencies' | 'devDependencies';

/** Branded string type for dependency paths */
type DepPath = string & { __brand: 'DepPath' };

/** Branded string type for project identifiers */
type ProjectId = string & { __brand: 'ProjectId' };

/** Lockfile object structure containing importers and package snapshots */
interface LockfileObject {
  /** Project configurations indexed by project ID */
  importers: Record<ProjectId, ProjectSnapshot>;
  /** Package snapshots indexed by dependency path */
  packages?: PackageSnapshots;
  /** Additional lockfile metadata */
  [key: string]: any;
}

/** Project snapshot containing dependency specifications and metadata */
interface ProjectSnapshot {
  /** Package version specifiers (required) */
  specifiers: Record<string, string>;
  /** Production dependencies */
  dependencies?: Record<string, string>;
  /** Development dependencies */
  devDependencies?: Record<string, string>;
  /** Optional dependencies */
  optionalDependencies?: Record<string, string>;
  /** Dependencies metadata for installation behavior */
  dependenciesMeta?: DependenciesMeta;
  /** Publish directory override */
  publishDirectory?: string;
}

/** Collection of package snapshots */
type PackageSnapshots = Record<DepPath, PackageSnapshot>;

/** Individual package snapshot with metadata and resolution */
interface PackageSnapshot {
  /** Package ID identifier */
  id?: string;
  /** Package resolution information */
  resolution: LockfileResolution;
  /** Whether package is optional */
  optional?: true;
  /** Package dependencies */
  dependencies?: Record<string, string>;
  /** Package optional dependencies */
  optionalDependencies?: Record<string, string>;
  /** Transitive peer dependencies */
  transitivePeerDependencies?: string[];
  /** Peer dependencies specification */
  peerDependencies?: Record<string, string>;
  /** Node.js engines specification */
  engines?: Record<string, string> & { node: string };
  /** Supported operating systems */
  os?: string[];
  /** Supported CPU architectures */
  cpu?: string[];
  /** Supported libc implementations */
  libc?: string[];
  /** Whether package has binaries */
  hasBin?: true;
  /** Package deprecation message */
  deprecated?: string;
}

/** Platform architecture configurations */
interface SupportedArchitectures {
  /** Supported CPU architectures */
  cpu?: string[];
  /** Supported operating systems */
  os?: string[];
  /** Supported libc implementations */
  libc?: string[];
}

/** Lockfile resolution types for different package sources */
type LockfileResolution = {
  /** Package integrity hash */
  integrity: string;
} | {
  /** Tarball resolution */
  tarball: string;
  integrity?: string;
} | {
  /** Git repository resolution */
  type: 'git';
  repo: string;
  commit: string;
  path?: string;
} | {
  /** Directory resolution */
  type: 'directory';
  directory: string;
};

/** Dependencies metadata for controlling installation behavior */
interface DependenciesMeta {
  [dependencyName: string]: {
    /** Mark dependency as optional */
    optional?: boolean;
    /** Mark dependency as injected */
    injected?: boolean;
  };
}