@pnpm/store.index 1100.0.0 → 1100.2.0

package/lib/index.d.ts

@@ -1,3 +1,4 @@
+import type { DatabaseSync as DatabaseSyncType, StatementSync } from 'node:sqlite';
 /**
  * Pack data for storage using msgpackr.
  * Use this when data will be packed in one thread and stored by another,
@@ -13,24 +14,55 @@ export declare function storeIndexKey(integrity: string, pkgId: string): string;
 export declare function gitHostedStoreIndexKey(pkgId: string, opts: {
     built: boolean;
 }): string;
+/**
+ * Pick the store index key for a tarball-shaped resolution.
+ *
+ * Git-hosted tarballs (`resolution.gitHosted === true`) are addressed by
+ * `gitHostedStoreIndexKey(pkgId, { built })` — their cached content depends
+ * on whether build scripts ran during fetch (`preparePackage`), so the
+ * `built` dimension is part of the key. The integrity-only key would
+ * collapse the built/not-built variants into one slot.
+ *
+ * Tarballs with integrity that aren't git-hosted are addressed by
+ * `storeIndexKey(integrity, pkgId)`.
+ *
+ * Resolutions that have neither flag fall through to
+ * `gitHostedStoreIndexKey` — these are typically lockfile entries written
+ * by older pnpm versions that lacked integrity.
+ */
+export declare function pickStoreIndexKey(resolution: {
+    gitHosted?: boolean;
+    integrity?: string;
+}, pkgId: string, opts: {
+    built: boolean;
+}): string;
 /**
  * Close all open StoreIndex instances.
  * Useful in tests that need to remove the store directory.
  */
 export declare function closeAllStoreIndexes(): void;
 export declare class StoreIndex {
-    private db;
-    private closed;
+    protected db: DatabaseSyncType;
+    protected closed: boolean;
     private pendingWrites;
     private flushScheduled;
-    private stmtGet;
-    private stmtSet;
-    private stmtDel;
-    private stmtHas;
-    private stmtAll;
+    protected stmtGet: StatementSync;
+    protected stmtSet: StatementSync;
+    protected stmtDel: StatementSync;
+    protected stmtHas: StatementSync;
+    protected stmtAll: StatementSync;
+    protected stmtKeys: StatementSync;
     private readonly exitHandler;
     constructor(storeDir: string);
+    /** Open the SQLite connection. Overridden by {@link ReadOnlyStoreIndex}. */
+    protected openDatabase(storeDir: string): void;
+    /** Prepare the prepared statements. Overridden by {@link ReadOnlyStoreIndex} to skip the write statements. */
+    protected prepareStatements(): void;
     get(key: string): unknown | undefined;
+    /**
+     * Get the raw msgpack-encoded buffer for a key without decoding.
+     */
+    getRaw(key: string): Uint8Array | undefined;
     set(key: string, data: unknown): void;
     delete(key: string): boolean;
     has(key: string): boolean;
@@ -39,6 +71,11 @@ export declare class StoreIndex {
      * Yields [key, data] pairs where key is `integrity\tpkgId`.
      */
     entries(): IterableIterator<[string, unknown]>;
+    /**
+     * Iterate over all index keys without decoding values.
+     * Much faster than entries() when only keys are needed.
+     */
+    keys(): IterableIterator<string>;
     /**
      * Queue pre-packed writes to be flushed on the next tick.
      * Used by the fetch phase for throughput.
@@ -64,5 +101,37 @@ export declare class StoreIndex {
      * then VACUUM to reclaim disk space.
      */
     deleteMany(keys: string[]): void;
+    checkpoint(): void;
     close(): void;
+    /** Run `PRAGMA optimize` before closing. Overridden by {@link ReadOnlyStoreIndex} to skip it (the DB is immutable). */
+    protected optimizeBeforeClose(): void;
+}
+/**
+ * A {@link StoreIndex} opened read-only for installs against a store on a
+ * read-only filesystem (`frozenStore`). The index is a WAL-mode database, and a
+ * normal WAL read creates an `index.db-shm` sidecar in the store directory —
+ * which fails on a read-only directory and surfaces as "attempt to write a
+ * readonly database" on the first query. Opening via the SQLite `immutable=1`
+ * URI tells SQLite the file cannot change, so it bypasses the WAL/shm machinery
+ * and reads the file directly, creating no sidecars.
+ *
+ * The store is assumed complete; every write is a programming error and throws.
+ */
+export declare class ReadOnlyStoreIndex extends StoreIndex {
+    protected openDatabase(storeDir: string): void;
+    protected prepareStatements(): void;
+    protected optimizeBeforeClose(): void;
+    set(_key: string, _data: unknown): void;
+    delete(_key: string): boolean;
+    queueWrites(_writes: Array<{
+        key: string;
+        buffer: Uint8Array;
+    }>): void;
+    setRawMany(_entries: Array<{
+        key: string;
+        buffer: Uint8Array;
+    }>): void;
+    deleteMany(_keys: string[]): void;
+    checkpoint(): void;
+    private throwReadOnly;
 }

package/lib/index.js

@@ -1,6 +1,9 @@
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { PnpmError } from '@pnpm/error';
 import { Packr } from 'msgpackr';
+const FROZEN_STORE_WRITE_MESSAGE = 'Cannot write to the package store because frozenStore is enabled (the store is opened read-only). This indicates the store is missing content the install needs.';
 // Use createRequire to load node:sqlite because it is a prefix-only builtin
 // that Jest's ESM module resolver cannot handle.
 const req = createRequire(import.meta.url);
@@ -54,6 +57,28 @@ export function storeIndexKey(integrity, pkgId) {
 export function gitHostedStoreIndexKey(pkgId, opts) {
     return storeIndexKey(pkgId, opts.built ? 'built' : 'not-built');
 }
+/**
+ * Pick the store index key for a tarball-shaped resolution.
+ *
+ * Git-hosted tarballs (`resolution.gitHosted === true`) are addressed by
+ * `gitHostedStoreIndexKey(pkgId, { built })` — their cached content depends
+ * on whether build scripts ran during fetch (`preparePackage`), so the
+ * `built` dimension is part of the key. The integrity-only key would
+ * collapse the built/not-built variants into one slot.
+ *
+ * Tarballs with integrity that aren't git-hosted are addressed by
+ * `storeIndexKey(integrity, pkgId)`.
+ *
+ * Resolutions that have neither flag fall through to
+ * `gitHostedStoreIndexKey` — these are typically lockfile entries written
+ * by older pnpm versions that lacked integrity.
+ */
+export function pickStoreIndexKey(resolution, pkgId, opts) {
+    if (resolution.gitHosted || !resolution.integrity) {
+        return gitHostedStoreIndexKey(pkgId, opts);
+    }
+    return storeIndexKey(resolution.integrity, pkgId);
+}
 const openInstances = new Set();
 /**
  * Close all open StoreIndex instances.
@@ -74,11 +99,26 @@ export class StoreIndex {
     stmtDel;
     stmtHas;
     stmtAll;
+    stmtKeys;
     exitHandler;
     constructor(storeDir) {
-        const dbPath = `${storeDir}/index.db`;
+        this.openDatabase(storeDir);
+        this.prepareStatements();
+        this.exitHandler = () => this.close();
+        // Multiple StoreIndex instances may be created (e.g. in tests), each adding
+        // an exit listener. Raise the limit to avoid MaxListenersExceededWarning.
+        // Skip when maxListeners is 0 (unlimited).
+        const currentMax = process.getMaxListeners();
+        if (currentMax !== 0 && currentMax < openInstances.size + 11) {
+            process.setMaxListeners(Math.max(currentMax + 10, openInstances.size + 11));
+        }
+        process.on('exit', this.exitHandler);
+        openInstances.add(this);
+    }
+    /** Open the SQLite connection. Overridden by {@link ReadOnlyStoreIndex}. */
+    openDatabase(storeDir) {
         fs.mkdirSync(storeDir, { recursive: true });
-        this.db = new DatabaseSync(dbPath);
+        this.db = new DatabaseSync(`${storeDir}/index.db`);
         // Set busy_timeout FIRST so SQLite's internal busy handler is active
         // during all subsequent operations. On Windows, file locking is mandatory
         // and concurrent processes (e.g. parallel dlx calls) will contend.
@@ -100,21 +140,15 @@ export class StoreIndex {
         ) WITHOUT ROWID
       `);
         });
+    }
+    /** Prepare the prepared statements. Overridden by {@link ReadOnlyStoreIndex} to skip the write statements. */
+    prepareStatements() {
         this.stmtGet = this.db.prepare('SELECT data FROM package_index WHERE key = ?');
         this.stmtSet = this.db.prepare('INSERT OR REPLACE INTO package_index (key, data) VALUES (?, ?)');
         this.stmtDel = this.db.prepare('DELETE FROM package_index WHERE key = ?');
         this.stmtHas = this.db.prepare('SELECT 1 FROM package_index WHERE key = ?');
         this.stmtAll = this.db.prepare('SELECT key, data FROM package_index');
-        this.exitHandler = () => this.close();
-        // Multiple StoreIndex instances may be created (e.g. in tests), each adding
-        // an exit listener. Raise the limit to avoid MaxListenersExceededWarning.
-        // Skip when maxListeners is 0 (unlimited).
-        const currentMax = process.getMaxListeners();
-        if (currentMax !== 0 && currentMax < openInstances.size + 11) {
-            process.setMaxListeners(Math.max(currentMax + 10, openInstances.size + 11));
-        }
-        process.on('exit', this.exitHandler);
-        openInstances.add(this);
+        this.stmtKeys = this.db.prepare('SELECT key FROM package_index');
     }
     get(key) {
         const row = sqliteRetry(() => this.stmtGet.get(key));
@@ -123,6 +157,13 @@ export class StoreIndex {
         }
         return undefined;
     }
+    /**
+     * Get the raw msgpack-encoded buffer for a key without decoding.
+     */
+    getRaw(key) {
+        const row = sqliteRetry(() => this.stmtGet.get(key));
+        return row?.data;
+    }
     set(key, data) {
         const buffer = packr.pack(data);
         sqliteRetry(() => {
@@ -148,6 +189,15 @@ export class StoreIndex {
             yield [row.key, packr.unpack(row.data)];
         }
     }
+    /**
+     * Iterate over all index keys without decoding values.
+     * Much faster than entries() when only keys are needed.
+     */
+    *keys() {
+        for (const row of this.stmtKeys.iterate()) {
+            yield row.key;
+        }
+    }
     /**
      * Queue pre-packed writes to be flushed on the next tick.
      * Used by the fetch phase for throughput.
@@ -237,6 +287,14 @@ export class StoreIndex {
         });
         this.db.exec('VACUUM');
     }
+    checkpoint() {
+        this.flush();
+        // wal_checkpoint can hit SQLITE_BUSY if another process is reading the
+        // same index.db concurrently. Retry for consistency with other ops here.
+        sqliteRetry(() => {
+            this.db.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+        });
+    }
     close() {
         if (this.closed)
             return;
@@ -244,18 +302,103 @@ export class StoreIndex {
         this.closed = true;
         openInstances.delete(this);
         process.removeListener('exit', this.exitHandler);
+        this.optimizeBeforeClose();
         try {
-            this.db.exec('PRAGMA optimize');
+            this.db.close();
         }
         catch {
-            // PRAGMA optimize is a performance hint; safe to ignore if the DB is locked.
+            // The DB may be locked by another connection; the OS will reclaim it on process exit.
         }
+    }
+    /** Run `PRAGMA optimize` before closing. Overridden by {@link ReadOnlyStoreIndex} to skip it (the DB is immutable). */
+    optimizeBeforeClose() {
         try {
-            this.db.close();
+            this.db.exec('PRAGMA optimize');
         }
         catch {
-            // The DB may be locked by another connection; the OS will reclaim it on process exit.
+            // PRAGMA optimize is a performance hint; safe to ignore if the DB is locked.
+        }
+    }
+}
+/**
+ * A {@link StoreIndex} opened read-only for installs against a store on a
+ * read-only filesystem (`frozenStore`). The index is a WAL-mode database, and a
+ * normal WAL read creates an `index.db-shm` sidecar in the store directory —
+ * which fails on a read-only directory and surfaces as "attempt to write a
+ * readonly database" on the first query. Opening via the SQLite `immutable=1`
+ * URI tells SQLite the file cannot change, so it bypasses the WAL/shm machinery
+ * and reads the file directly, creating no sidecars.
+ *
+ * The store is assumed complete; every write is a programming error and throws.
+ */
+export class ReadOnlyStoreIndex extends StoreIndex {
+    openDatabase(storeDir) {
+        if (!nodeSupportsImmutableSqliteUri()) {
+            throw new PnpmError('FROZEN_STORE_UNSUPPORTED_NODE', `frozenStore opens the store index read-only via a SQLite "immutable" URI, which requires Node.js >=22.15.0, >=23.11.0, or >=24.0.0, but the current version is ${process.versions.node}. Upgrade Node.js, or run without frozenStore.`);
         }
+        this.db = new DatabaseSync(immutableSqliteUri(`${storeDir}/index.db`));
     }
+    prepareStatements() {
+        this.stmtGet = this.db.prepare('SELECT data FROM package_index WHERE key = ?');
+        this.stmtHas = this.db.prepare('SELECT 1 FROM package_index WHERE key = ?');
+        this.stmtAll = this.db.prepare('SELECT key, data FROM package_index');
+        this.stmtKeys = this.db.prepare('SELECT key FROM package_index');
+    }
+    optimizeBeforeClose() { }
+    set(_key, _data) {
+        this.throwReadOnly();
+    }
+    delete(_key) {
+        this.throwReadOnly();
+    }
+    queueWrites(_writes) {
+        this.throwReadOnly();
+    }
+    setRawMany(_entries) {
+        this.throwReadOnly();
+    }
+    deleteMany(_keys) {
+        this.throwReadOnly();
+    }
+    checkpoint() {
+        this.throwReadOnly();
+    }
+    throwReadOnly() {
+        throw new PnpmError('FROZEN_STORE_WRITE', FROZEN_STORE_WRITE_MESSAGE);
+    }
+}
+/**
+ * Build the `file://…?immutable=1` URI used to open `index.db` read-only (see
+ * the frozen-store rationale at the call site). `pathToFileURL` yields a
+ * canonical file URL on every platform: it percent-encodes the URI delimiters
+ * that could otherwise truncate the path or inject a query/fragment (`?`, `#`,
+ * `%`, spaces) and, on Windows, maps the drive letter and backslashes into a
+ * valid `file:///C:/…` form. A raw `file:${path}` concatenation would mis-parse
+ * those. See https://sqlite.org/uri.html.
+ */
+function immutableSqliteUri(dbPath) {
+    const url = pathToFileURL(dbPath);
+    url.searchParams.set('immutable', '1');
+    return url.href;
+}
+/**
+ * Whether the running Node.js can open a `file:…?immutable=1` SQLite URI.
+ *
+ * `node:sqlite` only passes `SQLITE_OPEN_URI` to SQLite — so the `immutable=1`
+ * query is honored rather than treated as part of a literal filename — starting
+ * in v22.15.0 (22.x line), v23.11.0 (23.x line), and every v24+. On older
+ * runtimes the URI is opened as a literal path and fails with a cryptic
+ * "unable to open database file"; we detect that up front to give actionable
+ * guidance instead.
+ */
+function nodeSupportsImmutableSqliteUri() {
+    const [major, minor] = process.versions.node.split('.', 2).map(Number);
+    if (major < 22)
+        return false;
+    if (major === 22)
+        return minor >= 15;
+    if (major === 23)
+        return minor >= 11;
+    return true;
 }
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pnpm/store.index",
-  "version": "1100.0.0",
+  "version": "1100.2.0",
   "description": "SQLite-backed index for the pnpm content-addressable store",
   "keywords": [
     "pnpm",
@@ -9,7 +9,10 @@
   ],
   "license": "MIT",
   "funding": "https://opencollective.com/pnpm",
-  "repository": "https://github.com/pnpm/pnpm/tree/main/store/index",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pnpm/pnpm/tree/main/store/index"
+  },
   "homepage": "https://github.com/pnpm/pnpm/tree/main/store/index#readme",
   "bugs": {
     "url": "https://github.com/pnpm/pnpm/issues"
@@ -25,12 +28,14 @@
     "!*.map"
   ],
   "dependencies": {
-    "msgpackr": "1.11.8"
+    "msgpackr": "2.0.4",
+    "@pnpm/error": "1100.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.19.15",
+    "@jest/globals": "30.4.1",
+    "@types/node": "^22.19.19",
     "tempy": "3.0.0",
-    "@pnpm/store.index": "1100.0.0"
+    "@pnpm/store.index": "1100.2.0"
   },
   "engines": {
     "node": ">=22.13"