@effected/lockfiles 0.6.2 → 0.7.0

package/Lockfile.js

@@ -128,6 +128,8 @@ var Lockfile = class Lockfile extends Schema.Class("Lockfile")({
 	#nameIndex;
 	/** Lazily built importer-path → importer index; deliberately outside the schema, never encodes. */
 	#importerIndex;
+	/** Lazily built instance-id → package index; deliberately outside the schema, never encodes. */
+	#instanceIndex;
 	/**
 	* Parse lockfile content of a known format into the unified model — the
 	* package's only fallible boundary.
@@ -253,6 +255,32 @@ var Lockfile = class Lockfile extends Schema.Class("Lockfile")({
 		}
 		return Option.fromUndefinedOr(this.#importerIndex.get(path));
 	}
+	/**
+	* The resolved package with the given instance id, or `Option.none()` when
+	* the lockfile records none. Backed by a lazily built index, so repeated
+	* lookups are O(1) and a consumer that never walks edges pays nothing.
+	*
+	* @remarks
+	* `ResolvedPackage.instanceId` is what a resolved edge points at, so peer and
+	* dependency resolution is a lookup through this index rather than a scan.
+	* Without it every consumer rebuilds the same map — `new Map(lockfile.packages.map((p) => [p.instanceId, p]))` —
+	* which is O(n) per walk and one more place for the key choice to drift.
+	*
+	* The index is a `Map`, so an instance id that collides with an `Object`
+	* member name (`__proto__`, `constructor`) neither pollutes nor
+	* false-matches, exactly as for {@link Lockfile.importer}.
+	*
+	* @param instanceId - The instance id to look up.
+	* @returns The matching {@link ResolvedPackage}, or `Option.none()`.
+	*/
+	packageByInstanceId(instanceId) {
+		if (this.#instanceIndex === void 0) {
+			const index = /* @__PURE__ */ new Map();
+			for (const pkg of this.packages) if (!index.has(pkg.instanceId)) index.set(pkg.instanceId, pkg);
+			this.#instanceIndex = index;
+		}
+		return Option.fromUndefinedOr(this.#instanceIndex.get(instanceId));
+	}
 	/** The workspace-local packages. */
 	get workspacePackages() {
 		return this.packages.filter((pkg) => pkg.isWorkspace);

package/README.md

@@ -135,19 +135,24 @@ A row in `lockfile.packages` is one package **instance**, not one package. A dep
 `resolved` maps each dependency name — and each peer name the lockfile records a resolution for — to the `instanceId` it actually resolved to, which is what lets a consumer walk the real graph rather than re-resolving ranges itself. `peerDependencies` and `peerDependenciesMeta` carry the declarations as written, defaulting to `{}`.
 
 ```ts
+import { Option } from "effect";
+
 const [instance] = lockfile.packagesNamed("react-dom");
 const reactId = instance?.resolved["react"];
-const react = lockfile.packages.find((p) => p.instanceId === reactId);
-// react?.version: the version this particular react-dom instance resolved to
+const react = reactId === undefined ? Option.none() : lockfile.packageByInstanceId(reactId);
+// Option.some(ResolvedPackage) — the version this particular react-dom instance resolved to
+// Option.none() when the lockfile records no row under that id
 ```
 
+`packageByInstanceId` is the lookup to reach for rather than a scan over `lockfile.packages`: it builds its index lazily on first call and reuses it, so walking a graph edge by edge stays linear instead of quadratic. A repeated id resolves to the first row, so a malformed lockfile gives a stable answer rather than an iteration-order one.
+
 `unresolvedEdges` names the edges the lockfile **records** but the model could not name. A name listed there is not absent — it is unanswered, so a missing `resolved` key must not be read as "nothing is there". A gate that cares about completeness checks that array before trusting an empty result.
 
 ## Features
 
 - `Lockfile.parse(content, { format })` — the package's only fallible boundary; fails with `LockfileParseError` or `LockfileFramingError`.
 - `Lockfile#withImporterNames(names)` — the pure second stage for pnpm: rewrites importer-path names and both ends of each dependency edge once the consumer has read the manifests.
-- `Lockfile#packagesNamed(name)` and `Lockfile#workspacePackages` — total lookups over the model.
+- `Lockfile#packagesNamed(name)`, `Lockfile#packageByInstanceId(id)` (`Option`-answering, over a lazily built index) and `Lockfile#workspacePackages` — total lookups over the model.
 - `LockfileFormat` with `filenameFor` / `fromFilename` — the format literal and its mapping to lockfile filenames.
 - `LockfileIntegrity.compare(lockfile, manifests)` — total, pure integrity checking with no error channel; the report carries `valid`, `missingWorkspaces`, `extraWorkspaces` and `unsatisfiedConstraints`. Constraint checking is best-effort by design: `workspace:` / `link:` / `file:` specifiers and rows whose range does not parse as SemVer are skipped.
 - `WorkspaceManifest` — the manifest input shape for integrity checking: a package name plus four optional dependency records. Deliberately a plain value rather than a strict manifest model, so consumers can derive it from anything.

package/index.d.ts

@@ -468,6 +468,25 @@ declare class Lockfile extends Lockfile_base {
    * @returns The matching {@link LockfileImporter}, or `Option.none()`.
    */
   importer(path: string): Option.Option<LockfileImporter>;
+  /**
+   * The resolved package with the given instance id, or `Option.none()` when
+   * the lockfile records none. Backed by a lazily built index, so repeated
+   * lookups are O(1) and a consumer that never walks edges pays nothing.
+   *
+   * @remarks
+   * `ResolvedPackage.instanceId` is what a resolved edge points at, so peer and
+   * dependency resolution is a lookup through this index rather than a scan.
+   * Without it every consumer rebuilds the same map — `new Map(lockfile.packages.map((p) => [p.instanceId, p]))` —
+   * which is O(n) per walk and one more place for the key choice to drift.
+   *
+   * The index is a `Map`, so an instance id that collides with an `Object`
+   * member name (`__proto__`, `constructor`) neither pollutes nor
+   * false-matches, exactly as for {@link Lockfile.importer}.
+   *
+   * @param instanceId - The instance id to look up.
+   * @returns The matching {@link ResolvedPackage}, or `Option.none()`.
+   */
+  packageByInstanceId(instanceId: string): Option.Option<ResolvedPackage>;
   /** The workspace-local packages. */
   get workspacePackages(): ReadonlyArray<ResolvedPackage>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/lockfiles",
-	"version": "0.6.2",
+	"version": "0.7.0",
 	"private": false,
 	"description": "Pure lockfile parsing for bun, npm, pnpm and yarn Berry into one unified Effect schema model, with pure integrity checking against workspace manifests.",
 	"keywords": [
@@ -41,9 +41,9 @@
 	},
 	"peerDependencies": {
 		"@effected/jsonc": "^0.7.0",
-		"@effected/npm": "^0.11.1",
+		"@effected/npm": "^0.12.0",
 		"@effected/semver": "^0.5.0",
-		"@effected/yaml": "^0.10.0",
+		"@effected/yaml": "^0.11.0",
 		"effect": "4.0.0-rc.109"
 	},
 	"engines": {

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.58.13"
+      "packageVersion": "7.59.0"
     }
   ]
 }