{"id":35196193,"url":"https://github.com/indexzero/flatlock","last_synced_at":"2026-04-14T19:00:56.013Z","repository":{"id":329003418,"uuid":"1114034350","full_name":"indexzero/flatlock","owner":"indexzero","description":"the Matlock of lockfile parsers","archived":false,"fork":false,"pushed_at":"2026-04-14T15:43:16.000Z","size":2544,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-14T16:14:57.784Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/indexzero.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-10T20:03:40.000Z","updated_at":"2026-04-14T15:43:22.000Z","dependencies_parsed_at":"2026-01-18T07:05:08.041Z","dependency_job_id":null,"html_url":"https://github.com/indexzero/flatlock","commit_stats":null,"previous_names":["indexzero/flatlock"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/indexzero/flatlock","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexzero%2Fflatlock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexzero%2Fflatlock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexzero%2Fflatlock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexzero%2Fflatlock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/indexzero","download_url":"https://codeload.github.com/indexzero/flatlock/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexzero%2Fflatlock/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31810741,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-29T07:18:59.382Z","updated_at":"2026-04-14T19:00:56.006Z","avatar_url":"https://github.com/indexzero.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `flatlock`\n\nThe Matlock of lockfile parsers - cuts through the complexity to get just the facts. Flat lockfile parser that extracts packages without building dependency graphs.\n\n## What makes `flatlock` different?\n\n![matlockish](https://github.com/indexzero/flatlock/raw/main/doc/img/matlockish.png)\n\nMost lockfile parsers (like `@npmcli/arborist` or `snyk-nodejs-lockfile-parser`) build the full dependency graph with edges representing relationships between packages. This is necessary for dependency resolution but overkill for many use cases.\n\n**flatlock** takes a different approach: it extracts a flat stream of packages from any lockfile format. No trees, no graphs, no edges - just packages.\n\n```javascript\nimport * as flatlock from 'flatlock';\n\n// Stream packages from any lockfile\nfor await (const pkg of flatlock.fromPath('./package-lock.json')) {\n  console.log(pkg.name, pkg.version, pkg.integrity);\n}\n```\n\n## When to use flatlock\n\n| Use Case               | Needs Graph? | Use flatlock?    |\n|------------------------|--------------|------------------|\n| SBOM generation        | No           | Yes              |\n| Vulnerability scanning | No           | Yes              |\n| License compliance     | No           | Yes              |\n| Integrity verification | No           | Yes              |\n| Package enumeration    | No           | Yes              |\n| Dependency resolution  | Yes          | No, use Arborist |\n| \"Why is X installed?\"  | Yes          | No, use Arborist |\n\n## Supported Formats\n\n- **npm**: package-lock.json (v1, v2, v3)\n- **pnpm**: pnpm-lock.yaml (v5.4, v6, v9)\n- **yarn classic**: yarn.lock v1\n- **yarn berry**: yarn.lock v2+\n\n## CLI Tools\n\nThree command-line tools are included for common workflows:\n\n```bash\n# Extract dependencies from any lockfile\nnpx flatlock package-lock.json --specs --json\n\n# Verify parser accuracy against official tools\nnpx flatlock-cmp --dir ./fixtures --glob \"**/*lock*\"\n\n# Check registry availability of all dependencies\nnpx flatcover package-lock.json --summary\n```\n\n| Command | Purpose |\n|---------|---------|\n| `flatlock` | Extract dependencies as plain text, JSON, or NDJSON |\n| `flatlock-cmp` | Compare output against @npmcli/arborist, @yarnpkg/lockfile, @pnpm/lockfile.fs |\n| `flatcover` | Verify packages exist on registry (useful for private registry migrations) |\n\nRun any command with `--help` for full options.\n\n## API\n\n```javascript\nimport * as flatlock from 'flatlock';\n\n// Auto-detect format from file\nfor await (const pkg of flatlock.fromPath('./pnpm-lock.yaml')) { }\n\n// Parse string content (sync generator)\nfor (const pkg of flatlock.fromString(content, { path: 'yarn.lock' })) { }\n\n// Format-specific parsers\nfor (const pkg of flatlock.fromPackageLock(content)) { }\nfor (const pkg of flatlock.fromPnpmLock(content)) { }\nfor (const pkg of flatlock.fromYarnLock(content)) { }  // auto-detects v1 vs v2+\nfor (const pkg of flatlock.fromYarnClassicLock(content)) { }\nfor (const pkg of flatlock.fromYarnBerryLock(content)) { }\n\n// Error handling with Result type\nconst result = flatlock.tryFromPath('./package-lock.json');\nif (result.ok) {\n  for await (const pkg of result.value) { }\n}\n\n// Collect all packages into array\nconst packages = await flatlock.collect('./package-lock.json');\n\n// Type detection\nconst type = flatlock.detectType({ path: 'yarn.lock', content });\nconsole.log(type); // 'yarn-classic' or 'yarn-berry'\n\n// Content-only detection (path is optional)\nflatlock.detectType({ content }); // auto-detect from content alone\n\n// Type constants\nconsole.log(flatlock.Type.NPM); // 'npm'\n```\n\n## Output Format\n\nEach yielded package has:\n\n```typescript\n{\n  name: string;      // Package name (e.g., \"@babel/core\")\n  version: string;   // Resolved version (e.g., \"7.23.0\")\n  integrity?: string; // Integrity hash (sha512, sha384, sha256, sha1)\n  resolved?: string;  // Download URL (registry or private)\n  link?: boolean;     // True if this is a workspace symlink\n}\n```\n\n## FlatlockSet\n\nFor more advanced use cases, `FlatlockSet` provides Set-like operations on lockfile dependencies:\n\n```javascript\nimport { FlatlockSet } from 'flatlock';\n\n// Create from lockfile\nconst set = await FlatlockSet.fromPath('./package-lock.json');\nconsole.log(set.size); // 1234\nconsole.log(set.has('lodash@4.17.21')); // true\n\n// Set operations (immutable - return new sets)\nconst other = await FlatlockSet.fromPath('./other-lock.json');\nconst common = set.intersection(other);  // packages in both\nconst added = other.difference(set);     // packages only in other\nconst all = set.union(other);            // packages in either\n\n// Predicates\nset.isSubsetOf(other);    // true if all packages in set are in other\nset.isSupersetOf(other);  // true if set contains all packages in other\nset.isDisjointFrom(other); // true if no packages in common\n\n// Iterate like a Set\nfor (const dep of set) {\n  console.log(dep.name, dep.version);\n}\n```\n\n### Workspace-Specific SBOMs\n\nFor monorepos, use `dependenciesOf()` to get only the dependencies of a specific workspace:\n\n```javascript\nimport { readFile } from 'node:fs/promises';\nimport { FlatlockSet } from 'flatlock';\n\nconst lockfile = await FlatlockSet.fromPath('./package-lock.json');\nconst pkg = JSON.parse(await readFile('./packages/api/package.json', 'utf8'));\n\n// Get only dependencies reachable from this workspace\nconst subset = await lockfile.dependenciesOf(pkg, {\n  workspacePath: 'packages/api',  // for correct resolution in monorepos\n  repoDir: '.',                    // reads workspace package.json files for accurate traversal\n  dev: false,                      // exclude devDependencies\n  optional: true,                  // include optionalDependencies\n  peer: false                      // exclude peerDependencies\n});\n\nconsole.log(`${pkg.name} has ${subset.size} production dependencies`);\n```\n\n**Note:** Sets created via `union()`, `intersection()`, or `difference()` cannot use `dependenciesOf()` because they lack the raw lockfile data needed for traversal. Check `set.canTraverse` before calling.\n\n## Compare API\n\nVerify flatlock output against official package manager parsers:\n\n```javascript\n// Both import styles work - use whichever you prefer\nimport { compare } from 'flatlock';\nimport { compare } from 'flatlock/compare';\n\nconst result = await compare('./package-lock.json');\nconsole.log(result.equinumerous);  // true if counts match\nconsole.log(result.flatlockCount); // packages found by flatlock\nconsole.log(result.comparisonCount); // packages found by official parser\n```\n\nThe dedicated `flatlock/compare` entry point exists for tools that want explicit imports, but the main export works identically.\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findexzero%2Fflatlock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Findexzero%2Fflatlock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findexzero%2Fflatlock/lists"}