🤖 Merge PR DefinitelyTyped#74241 [cacache] fix types and update version by @hexchain

Author: hexchain

types/cacache/cacache-tests.ts

@@ -6,7 +6,7 @@ const cachePath = "";
 cacache.ls(cachePath).then(() => {});
 
 cacache.ls.stream(cachePath).on("data", data => {
-    data; // $ExpectType any
+    data; // $ExpectType Cache
 });
 
 cacache.get(cachePath, "my-thing", { memoize: true }).then(() => {});
@@ -21,15 +21,20 @@ cacache.get
         metadata; // $ExpectType any
     })
     .on("integrity", integrity => {
-        integrity; // $ExpectType any
+        integrity; // $ExpectType string
+    })
+    .on("size", size => {
+        size; // $ExpectType number
     })
     .pipe(fs.createWriteStream("./x.tgz"));
 
 cacache.get.stream.byDigest(cachePath, "sha512-SoMeDIGest+64==").pipe(fs.createWriteStream("./x.tgz"));
 
 cacache.get.info(cachePath, "my-thing").then(() => {});
 
-cacache.get.hasContent(cachePath, "sha521-NOT+IN/CACHE==").then(() => {});
+cacache.get.hasContent(cachePath, "sha521-NOT+IN/CACHE==").then((res) => {
+    res; // $ExpectType HasContentObject | false
+});
 
 cacache
     .put(cachePath, "registry.npmjs.org|[email protected]", Buffer.from([]), {
@@ -43,7 +48,12 @@ cacache
 fs.createReadStream("").pipe(
     cacache.put
         .stream(cachePath, "registry.npmjs.org|[email protected]")
-        .on("integrity", d => console.log(`integrity digest is ${d}`)),
+        .on("integrity", integrity => {
+            integrity; // $ExpectType string
+        })
+        .on("size", size => {
+            size; // $ExpectType number
+        }),
 );
 
 cacache.rm.all(cachePath).then(() => {

types/cacache/index.d.ts

@@ -1,5 +1,9 @@
 /// <reference types="node" />
 
+import { Minipass } from "minipass";
+import * as fs from "node:fs";
+import { EventEmitter } from "node:stream";
+
 export interface CacheObject {
     /** Subresource Integrity hash for the content this entry refers to. */
     integrity: string;
@@ -36,6 +40,7 @@ export namespace get {
             options: any[];
             source: string;
         };
+        stat: fs.Stats;
     }
 
     interface Options {
@@ -74,16 +79,29 @@ export namespace get {
         size?: number | undefined;
     }
 
+    interface GetStreamEvents extends Minipass.Events<Buffer> {
+        // eslint-disable-next-line @definitelytyped/no-single-element-tuple-type
+        integrity: [integrity: string];
+
+        // eslint-disable-next-line @definitelytyped/no-single-element-tuple-type
+        size: [size: number];
+
+        // eslint-disable-next-line @definitelytyped/no-single-element-tuple-type
+        metadata: [metadata: any];
+    }
+
+    type CopyResultObject = Pick<CacheObject, "metadata" | "integrity" | "size">;
+
     namespace copy {
         function byDigest(cachePath: string, hash: string, dest: string, opts?: Options): Promise<string>;
     }
 
     namespace stream {
-        function byDigest(cachePath: string, hash: string, opts?: Options): NodeJS.ReadableStream;
+        function byDigest(cachePath: string, hash: string, opts?: Options): Minipass<Buffer, never>;
     }
 
-    function byDigest(cachePath: string, hash: string, opts?: Options): Promise<string>;
-    function copy(cachePath: string, key: string, dest: string, opts?: Options): Promise<CacheObject>;
+    function byDigest(cachePath: string, hash: string, opts?: Options): Promise<Buffer>;
+    function copy(cachePath: string, key: string, dest: string, opts?: Options): Promise<CopyResultObject>;
 
     /**
      * Looks up a Subresource Integrity hash in the cache. If content exists
@@ -114,7 +132,7 @@ export namespace get {
      * entirely. This version does not emit the `metadata` and `integrity`
      * events at all.
      */
-    function stream(cachePath: string, key: string, opts?: Options): NodeJS.ReadableStream;
+    function stream(cachePath: string, key: string, opts?: Options): Minipass<Buffer, never, GetStreamEvents>;
 }
 
 export namespace ls {
@@ -127,10 +145,21 @@ export namespace ls {
      * This works just like `ls`, except `get.info` entries are returned as
      * `'data'` events on the returned stream.
      */
-    function stream(cachePath: string): NodeJS.ReadableStream;
+    function stream(cachePath: string): Minipass<Cache, never>;
 }
 
 export namespace put {
+    interface IntegrityEmitterEvents {
+        // eslint-disable-next-line @definitelytyped/no-single-element-tuple-type
+        integrity: [integrity: string];
+
+        // eslint-disable-next-line @definitelytyped/no-single-element-tuple-type
+        size: [size: number];
+
+        // eslint-disable-next-line @definitelytyped/no-single-element-tuple-type
+        error: [err: unknown];
+    }
+
     interface Options {
         /**
          * Default: `['sha512']`
@@ -144,7 +173,8 @@ export namespace put {
          * Currently only supports one algorithm at a time (i.e., an array
          * length of exactly `1`). Has no effect if `opts.integrity` is present.
          */
-        algorithms?: string[] | undefined;
+        // eslint-disable-next-line @definitelytyped/no-single-element-tuple-type
+        algorithms?: [string] | undefined;
 
         /**
          * If present, the pre-calculated digest for the inserted content. If
@@ -189,14 +219,43 @@ export namespace put {
          * Prefix to append on the temporary directory name inside the cache's tmp dir.
          */
         tmpPrefix?: null | string | undefined;
+
+        /**
+         * Default: `undefined`
+         *
+         * (Streaming only) If present, uses the provided event emitter as a
+         * source of truth for both integrity and size. This allows use cases
+         * where integrity is already being calculated outside of cacache to
+         * reuse that data instead of calculating it a second time.
+         *
+         * The emitter must emit both the 'integrity' and 'size' events.
+         *
+         * NOTE: If this option is provided, you must verify that you receive
+         * the correct integrity value yourself and emit an 'error' event if
+         * there is a mismatch. ssri Integrity Streams do this for you when
+         * given an expected integrity.
+         */
+        integrityEmitter?: EventEmitter<IntegrityEmitterEvents> | undefined;
+    }
+
+    interface PutStreamEvents extends Minipass.Events<never> {
+        // eslint-disable-next-line @definitelytyped/no-single-element-tuple-type
+        integrity: [integrity: string];
+
+        // eslint-disable-next-line @definitelytyped/no-single-element-tuple-type
+        size: [size: number];
     }
 
     /**
      * Returns a Writable Stream that inserts data written to it into the cache.
      * Emits an `integrity` event with the digest of written contents when it
      * succeeds.
      */
-    function stream(cachePath: string, key: string, opts?: Options): NodeJS.WritableStream;
+    function stream(
+        cachePath: string,
+        key: string,
+        opts?: Options,
+    ): Minipass<never, Minipass.ContiguousData, PutStreamEvents>;
 }
 
 export namespace rm {

types/cacache/package.json

@@ -1,12 +1,13 @@
 {
     "private": true,
     "name": "@types/cacache",
-    "version": "19.0.9999",
+    "version": "20.0.9999",
     "projects": [
         "https://github.com/npm/cacache#readme"
     ],
     "dependencies": {
-        "@types/node": "*"
+        "@types/node": "*",
+        "minipass": "*"
     },
     "devDependencies": {
         "@types/cacache": "workspace:."