@types/cacache - npm Package Compare versions

Comparing version 12.0.1 to 15.0.0

cacache/index.d.ts

@@ -1,7 +0,395 @@
-// Type definitions for cacache 12.0
+// Type definitions for cacache 15.0
 // Project: https://github.com/npm/cacache#readme
-// Definitions by: Florian Keller <https://github.com/ffflorian>
+// Definitions by: Florian Imdahl <https://github.com/ffflorian>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 // TypeScript Version: 2.1
 
-export * from './en';
+/// <reference types="node" />
+
+export interface CacheObject {
+    /** Subresource Integrity hash for the content this entry refers to. */
+    integrity: string;
+    /** Key the entry was looked up under. Matches the key argument. */
+    key: string;
+    /** User-assigned metadata associated with the entry/content. */
+    metadata?: any;
+    /** Filesystem path where content is stored, joined with cache argument. */
+    path: string;
+    /** Timestamp the entry was first added on. */
+    time: number;
+}
+
+export interface GetCacheObject {
+    metadata?: any;
+    integrity: string;
+    data: Buffer;
+    size: number;
+}
+
+export namespace get {
+    interface HasContentObject {
+        size: number;
+        sri: {
+            algorithm: string;
+            digest: string;
+            options: any[];
+            source: string;
+        };
+    }
+
+    interface Options {
+        /**
+         * If present, the pre-calculated digest for the inserted content. If
+         * this option is provided and does not match the post-insertion digest,
+         * insertion will fail with an `EINTEGRITY` error.
+         *
+         * `algorithms` has no effect if this option is present.
+         */
+        integrity?: string;
+
+        /**
+         * Default: `null`
+         *
+         * If provided, cacache will memoize the given cache insertion in
+         * memory, bypassing any filesystem checks for that key or digest in
+         * future cache fetches. Nothing will be written to the in-memory cache
+         * unless this option is explicitly truthy.
+         *
+         * If `opts.memoize` is an object or a `Map`-like (that is, an object
+         * with `get` and `set` methods), it will be written to instead of the
+         * global memoization cache.
+         *
+         * Reading from disk data can be forced by explicitly passing
+         * `memoize: false` to the reader functions, but their default will be
+         * to read from memory.
+         */
+        memoize?: null | boolean;
+
+        /**
+         * If provided, the data stream will be verified to check that enough
+         * data was passed through. If there's more or less data than expected,
+         * insertion will fail with an `EBADSIZE` error.
+         */
+        size?: number;
+    }
+
+    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): Promise<string>;
+    function copy(cachePath: string, key: string, dest: string, opts?: Options): Promise<CacheObject>;
+
+    /**
+     * Looks up a Subresource Integrity hash in the cache. If content exists
+     * for this `integrity`, it will return an object, with the specific single
+     * integrity hash that was found in sri key, and the size of the found
+     * content as size. If no content exists for this integrity, it will return
+     * `false`.
+     */
+    function hasContent(cachePath: string, hash: string): Promise<HasContentObject | false>;
+    function hasContentnc(cachePath: string, hash: string): HasContentObject | false;
+
+    /**
+     * Looks up `key` in the cache index, returning information about the entry
+     * if one exists.
+     */
+    function info(cachePath: string, key: string): Promise<CacheObject>;
+
+    /**
+     * Returns a Readable Stream of the cached data identified by `key`.
+     *
+     * If there is no content identified by `key`, or if the locally-stored data
+     * does not pass the validity checksum, an error will be emitted.
+     *
+     * `metadata` and `integrity` events will be emitted before the stream
+     * closes, if you need to collect that extra data about the cached entry.
+     *
+     * A sub-function, `get.stream.byDigest` may be used for identical behavior,
+     * except lookup will happen by integrity hash, bypassing the index
+     * entirely. This version does not emit the `metadata` and `integrity`
+     * events at all.
+     */
+    function stream(cachePath: string, key: string, opts?: Options): NodeJS.ReadableStream;
+    function sync(cachePath: string, key: string, opts?: Options): CacheObject;
+    function syncDigest(cachePath: string, key: string, opts?: Options): CacheObject;
+}
+
+export namespace ls {
+    type Cache = Record<string, CacheObject & { size: number }>;
+
+    /**
+     * Lists info for all entries currently in the cache as a single large
+     * object.
+     *
+     * This works just like `ls`, except `get.info` entries are returned as
+     * `'data'` events on the returned stream.
+     */
+    function stream(cachePath: string): NodeJS.ReadableStream;
+}
+
+export namespace put {
+    interface Options {
+        /**
+         * Default: `['sha512']`
+         *
+         * Hashing algorithms to use when calculating the subresource integrity
+         * digest for inserted data. Can use any algorithm listed in
+         * `crypto.getHashes()` or `'omakase'`/`'お任せします'` to pick a random
+         * hash algorithm on each insertion. You may also use any anagram of
+         * `'modnar'` to use this feature.
+         *
+         * 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[];
+
+        /**
+         * If present, the pre-calculated digest for the inserted content. If
+         * this option is provided and does not match the post-insertion digest,
+         * insertion will fail with an `EINTEGRITY` error.
+         *
+         * `algorithms` has no effect if this option is present.
+         */
+        integrity?: string;
+
+        /** Arbitrary metadata to be attached to the inserted key. */
+        metadata?: any;
+
+        /**
+         * Default: `null`
+         *
+         * If provided, cacache will memoize the given cache insertion in
+         * memory, bypassing any filesystem checks for that key or digest in
+         * future cache fetches. Nothing will be written to the in-memory cache
+         * unless this option is explicitly truthy.
+         *
+         * If `opts.memoize` is an object or a `Map`-like (that is, an object
+         * with `get` and `set` methods), it will be written to instead of the
+         * global memoization cache.
+         *
+         * Reading from disk data can be forced by explicitly passing
+         * `memoize: false` to the reader functions, but their default will be
+         * to read from memory.
+         */
+        memoize?: null | boolean;
+
+        /**
+         * If provided, the data stream will be verified to check that enough
+         * data was passed through. If there's more or less data than expected,
+         * insertion will fail with an `EBADSIZE` error.
+         */
+        size?: number;
+
+        /**
+         * Default: `null`
+         *
+         * Prefix to append on the temporary directory name inside the cache's tmp dir.
+         */
+        tmpPrefix?: null | string;
+    }
+
+    /**
+     * 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;
+}
+
+export namespace rm {
+    /**
+     * Clears the entire cache. Mainly by blowing away the cache directory
+     * itself.
+     */
+    function all(cachePath: string): Promise<void>;
+
+    /**
+     * Removes the index entry for `key`. Content will still be accessible if
+     * requested directly by content address (`get.stream.byDigest`).
+     *
+     * To remove the content itself (which might still be used by other
+     * entries), use `rm.content`. Or, to safely vacuum any unused content,
+     * use `verify`.
+     */
+    function entry(cachePath: string, key: string): Promise<CacheObject>;
+
+    /**
+     * Removes the content identified by `integrity`. Any index entries
+     * referring to it will not be usable again until the content is re-added
+     * to the cache with an identical digest.
+     */
+    function content(cachePath: string, hash: string): Promise<boolean>;
+}
+
+export namespace tmp {
+    type Callback = (dir: string) => void;
+
+    interface Options {
+        /**
+         * Default: 20
+         *
+         * Number of concurrently read files in the filesystem while doing clean up.
+         */
+        concurrency?: number;
+
+        /**
+         * Receives a formatted entry. Return `false` to remove it.
+         *
+         * Note: might be called more than once on the same entry.
+         */
+        filter?: string | false;
+
+        /**
+         * Custom logger function:
+         * ```
+         *   log: { silly () {} }
+         *   log.silly('verify', 'verifying cache at', cache)
+         * ```
+         */
+        log?: Record<string, (...args: any[]) => any>;
+
+        /**
+         * Default: `null`
+         *
+         * Prefix to append on the temporary directory name inside the cache's tmp dir.
+         */
+        tmpPrefix?: null | string;
+    }
+
+    /**
+     * Sets the `uid` and `gid` properties on all files and folders within the
+     * tmp folder to match the rest of the cache.
+     *
+     * Use this after manually writing files into `tmp.mkdir` or `tmp.withTmp`.
+     */
+    function fix(cachePath: string): Promise<void>;
+
+    /**
+     * Returns a unique temporary directory inside the cache's `tmp` dir. This
+     * directory will use the same safe user assignment that all the other stuff
+     * use.
+     *
+     * Once the directory is made, it's the user's responsibility that all files
+     * within are given the appropriate `gid`/`uid` ownership settings to match
+     * the rest of the cache. If not, you can ask cacache to do it for you by
+     * calling `tmp.fix()`, which will fix all tmp directory permissions.
+     *
+     * If you want automatic cleanup of this directory, use `tmp.withTmp()`
+     */
+    function mkdir(cachePath: string, opts?: Options): Promise<string>;
+
+    /**
+     * Creates a temporary directory with `tmp.mkdir()` and calls `cb` with it.
+     * The created temporary directory will be removed when the return value of
+     * `cb()` resolves, the tmp directory will be automatically deleted once that
+     * promise completes.
+     *
+     * The same caveats apply when it comes to managing permissions for the tmp dir's contents.
+     */
+    function withTmp(cachePath: string, opts: Options, cb: Callback): void;
+    function withTmp(cachePath: string, cb: Callback): void;
+}
+
+export namespace verify {
+    interface Options {
+        /**
+         * Default: 20
+         *
+         * Number of concurrently read files in the filesystem while doing clean up.
+         */
+        concurrency?: number;
+
+        /**
+         * Receives a formatted entry. Return `false` to remove it.
+         *
+         * Note: might be called more than once on the same entry.
+         */
+        filter?: string | false;
+
+        /**
+         * Custom logger function:
+         * ```
+         *   log: { silly () {} }
+         *   log.silly('verify', 'verifying cache at', cache)
+         * ```
+         */
+        log?: Record<string, (...args: any[]) => any>;
+    }
+
+    /**
+     * Returns a Date representing the last time `cacache.verify` was run on
+     * `cache`.
+     */
+    function lastRun(cachePath: string): Promise<Date>;
+}
+
+export function clearMemoized(): Record<string, CacheObject>;
+
+/**
+ * Returns an object with the cached data, digest, and metadata identified by
+ * `key`. The `data` property of this object will be a Buffer instance that
+ * presumably holds some data that means something to you. I'm sure you know
+ * what to do with it! cacache just won't care.
+ *
+ * `integrity` is a Subresource Integrity string. That is, a string that can be
+ * used to verify `data`, which looks like
+ * `<hash-algorithm>-<base64-integrity-hash>`.
+ *
+ * If there is no content identified by key, or if the locally-stored data does
+ * not pass the validity checksum, the promise will be rejected.
+ *
+ * A sub-function, `get.byDigest` may be used for identical behavior, except
+ * lookup will happen by integrity hash, bypassing the index entirely. This
+ * version of the function only returns data itself, without any wrapper.
+ *
+ * **Note**
+ *
+ * This function loads the entire cache entry into memory before returning it.
+ * If you're dealing with Very Large data, consider using `get.stream` instead.
+ */
+export function get(cachePath: string, key: string, options?: get.Options): Promise<GetCacheObject>;
+
+/**
+ * Lists info for all entries currently in the cache as a single large object.
+ * Each entry in the object will be keyed by the unique index key, with
+ * corresponding `get.info` objects as the values.
+ */
+export function ls(cachePath: string): Promise<ls.Cache>;
+
+/**
+ * Inserts data passed to it into the cache. The returned Promise resolves with
+ * a digest (generated according to `opts.algorithms`) after the cache entry has
+ * been successfully written.
+ */
+export function put(cachePath: string, key: string, data: any, opts?: put.Options): Promise<string>;
+
+/**
+ * Removes the index entry for `key`. Content will still be accessible if
+ * requested directly by content address (`get.stream.byDigest`).
+ *
+ * To remove the content itself (which might still be used by other
+ * entries), use `rm.content`. Or, to safely vacuum any unused content,
+ * use `verify`.
+ */
+export function rm(cachePath: string, key: string): Promise<any>;
+
+/**
+ * Checks out and fixes up your cache:
+ *
+ * - Cleans up corrupted or invalid index entries
+ * - Custom entry filtering options
+ * - Garbage collects any content entries not referenced by the index
+ * - Checks integrity for all content entries and removes invalid content
+ * - Fixes cache ownership
+ * - Removes the `tmp` directory in the cache and all its contents.
+ *
+ * When it's done, it'll return an object with various stats about the
+ * verification process, including amount of storage reclaimed, number of valid
+ * entries, number of entries removed, etc.
+ */
+export function verify(cachePath: string, opts?: verify.Options): Promise<any>;

cacache/package.json

 {
     "name": "@types/cacache",
-    "version": "12.0.1",
+    "version": "15.0.0",
     "description": "TypeScript definitions for cacache",
@@ -8,3 +8,3 @@ "license": "MIT",
         {
-            "name": "Florian Keller",
+            "name": "Florian Imdahl",
             "url": "https://github.com/ffflorian",
@@ -15,3 +15,3 @@ "githubUsername": "ffflorian"
     "main": "",
-    "types": "index",
+    "types": "index.d.ts",
     "repository": {
@@ -26,4 +26,4 @@ "type": "git",
     },
-    "typesPublisherContentHash": "d609de9826478d66368f3fff672396c87dc5ca49cd7b450a98e375ea04fa3263",
-    "typeScriptVersion": "2.1"
+    "typesPublisherContentHash": "ef8f81bbda8489d66422e19a09ad71b4dc0939cd2571ac95909034ef16b2084e",
+    "typeScriptVersion": "3.4"
 }

cacache/README.md

@@ -8,10 +8,10 @@ # Installation
 # Details
-Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/cacache
+Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/cacache.
 
-Additional Details
- * Last updated: Tue, 05 Nov 2019 01:05:38 GMT
- * Dependencies: @types/node
+### Additional Details
+ * Last updated: Thu, 04 Feb 2021 06:50:41 GMT
+ * Dependencies: [@types/node](https://npmjs.com/package/@types/node)
  * Global values: none
 
 # Credits
-These definitions were written by Florian Keller <https://github.com/ffflorian>.
+These definitions were written by [Florian Imdahl](https://github.com/ffflorian).

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

16929

increased by16.61%

Lines of code

352

increased by23.51%

Worsened metrics

Number of package files

4

decreased by-20%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes