🔒 lockparse

A lightweight zero-dependency lockfile parser for npm, Yarn, pnpm, and Bun.

Installation

npm install @siberiacancode/lockparse

Usage

import { parse } from '@siberiacancode/lockparse';
import { readFile } from 'node:fs/promises';

const content = await readFile('./package-lock.json', 'utf-8');
const lockfile = parse(content, 'package-lock.json');

console.log(lockfile.root.dependencies);

Supported lockfiles

The parser supports the most common JavaScript package manager lockfiles:

parse(npmLock, 'npm');
parse(npmLock, 'package-lock.json');

parse(yarnLock, 'yarn');
parse(yarnLock, 'yarn.lock', packageJson);

parse(pnpmLock, 'pnpm');
parse(pnpmLock, 'pnpm-lock.yaml');

parse(bunLock, 'bun');
parse(bunLock, 'bun.lock');

Dependency graph

Each parsed lockfile contains the lockfile type, a root dependency node, and a flat package list.

const lockfile = parse(content, 'pnpm-lock.yaml');

lockfile.type; // 'pnpm'
lockfile.root; // root ParsedDependency
lockfile.packages; // ParsedDependency[]

Dependency nodes include regular dependency arrays and a requires list with rich edges:

const [dependency] = lockfile.root.dependencies;

dependency.name;
dependency.version;
dependency.dependencies;
dependency.devDependencies;
dependency.peerDependencies;
dependency.optionalDependencies;
dependency.requires;

Version ranges

Every dependency edge preserves the original requested range where the lockfile contains it.

const [edge] = lockfile.root.requires;

edge.from; // parent dependency node
edge.node; // child dependency node
edge.type; // 'dependencies' | 'devDependencies' | 'peerDependencies' | 'optionalDependencies'
edge.range?.raw; // '^1.2.0'
edge.range?.operator; // '^'
edge.range?.version; // '1.2.0'
edge.range?.exact; // false

Serialization

Parsed dependency graphs contain shared references and circular edges. Use serializeLockFile or stringifyLockFile when you need JSON-safe output.

import { parse, stringifyLockFile } from '@siberiacancode/lockparse';

const lockfile = parse(content, 'package-lock.json');
const json = stringifyLockFile(lockfile, 2);

You can include dependency provenance with the via option:

const json = stringifyLockFile(lockfile, 2, { via: true });

Deserialization

Serialized lockfiles can be turned back into the in-memory dependency graph.

import { parseLockFileJson } from '@siberiacancode/lockparse';

const lockfile = parseLockFileJson(json);

Indexing

Use indexNodes to get every reachable node once and stable ids for graph references.

import { indexNodes, parse } from '@siberiacancode/lockparse';

const lockfile = parse(content, 'bun.lock');
const { nodes, ids } = indexNodes(lockfile);

nodes.length;
ids.get(lockfile.root);