@types/cacache

  • Version 15.0.1
  • Published
  • 17.2 kB
  • 1 dependency
  • MIT license

Install

npm i @types/cacache
yarn add @types/cacache
pnpm add @types/cacache

Overview

TypeScript definitions for cacache

Index

Functions

function clearMemoized

clearMemoized: () => Record<string, CacheObject>;

    function get

    get: typeof get;
    • 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.

    function ls

    ls: typeof ls;
    • 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.

    function put

    put: typeof put;
    • 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.

    function rm

    rm: typeof rm;
    • 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 verify

    verify: typeof verify;
    • 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.

    Interfaces

    interface CacheObject

    interface CacheObject {}

      property integrity

      integrity: string;
      • Subresource Integrity hash for the content this entry refers to.

      property key

      key: string;
      • Key the entry was looked up under. Matches the key argument.

      property metadata

      metadata?: any;
      • User-assigned metadata associated with the entry/content.

      property path

      path: string;
      • Filesystem path where content is stored, joined with cache argument.

      property time

      time: number;
      • Timestamp the entry was first added on.

      interface GetCacheObject

      interface GetCacheObject {}

        property data

        data: Buffer;

          property integrity

          integrity: string;

            property metadata

            metadata?: any;

              property size

              size: number;

                Namespaces

                namespace get

                namespace get {}

                  function byDigest

                  byDigest: (cachePath: string, hash: string, opts?: Options) => Promise<string>;

                    function copy

                    copy: typeof copy;

                      function hasContent

                      hasContent: (
                      cachePath: string,
                      hash: string
                      ) => Promise<HasContentObject | false>;
                      • 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 hasContentnc

                      hasContentnc: (cachePath: string, hash: string) => HasContentObject | false;

                        function info

                        info: (cachePath: string, key: string) => Promise<CacheObject>;
                        • Looks up key in the cache index, returning information about the entry if one exists.

                        function stream

                        stream: typeof stream;
                        • 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 sync

                        sync: (cachePath: string, key: string, opts?: Options) => CacheObject;

                          function syncDigest

                          syncDigest: (cachePath: string, key: string, opts?: Options) => CacheObject;

                            interface HasContentObject

                            interface HasContentObject {}

                              property size

                              size: number;

                                property sri

                                sri: {
                                algorithm: string;
                                digest: string;
                                options: any[];
                                source: string;
                                };

                                  interface Options

                                  interface Options {}

                                    property integrity

                                    integrity?: string | undefined;
                                    • 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.

                                    property memoize

                                    memoize?: null | boolean | undefined;
                                    • 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.

                                    property size

                                    size?: number | undefined;
                                    • 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.

                                    namespace get.copy

                                    namespace get.copy {}

                                      function byDigest

                                      byDigest: (
                                      cachePath: string,
                                      hash: string,
                                      dest: string,
                                      opts?: Options
                                      ) => Promise<string>;

                                        namespace get.stream

                                        namespace get.stream {}

                                          function byDigest

                                          byDigest: (cachePath: string, hash: string, opts?: Options) => any;

                                            namespace ls

                                            namespace ls {}

                                              function stream

                                              stream: (cachePath: string) => any;
                                              • 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.

                                              type Cache

                                              type Cache = Record<string, CacheObject & { size: number }>;

                                                namespace put

                                                namespace put {}

                                                  function stream

                                                  stream: (cachePath: string, key: string, opts?: Options) => any;
                                                  • 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.

                                                  interface Options

                                                  interface Options {}

                                                    property algorithms

                                                    algorithms?: string[] | undefined;
                                                    • 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.

                                                    property integrity

                                                    integrity?: string | undefined;
                                                    • 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.

                                                    property memoize

                                                    memoize?: null | boolean | undefined;
                                                    • 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.

                                                    property metadata

                                                    metadata?: any;
                                                    • Arbitrary metadata to be attached to the inserted key.

                                                    property size

                                                    size?: number | undefined;
                                                    • 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.

                                                    property tmpPrefix

                                                    tmpPrefix?: null | string | undefined;
                                                    • Default: null

                                                      Prefix to append on the temporary directory name inside the cache's tmp dir.

                                                    namespace rm

                                                    namespace rm {}

                                                      function all

                                                      all: (cachePath: string) => Promise<void>;
                                                      • Clears the entire cache. Mainly by blowing away the cache directory itself.

                                                      function content

                                                      content: (cachePath: string, hash: string) => Promise<boolean>;
                                                      • 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 entry

                                                      entry: (cachePath: string, key: string) => Promise<CacheObject>;
                                                      • 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.

                                                      namespace tmp

                                                      namespace tmp {}

                                                        function fix

                                                        fix: (cachePath: string) => Promise<void>;
                                                        • 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 mkdir

                                                        mkdir: (cachePath: string, opts?: Options) => Promise<string>;
                                                        • 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 withTmp

                                                        withTmp: {
                                                        (cachePath: string, opts: Options, cb: Callback): void;
                                                        (cachePath: string, cb: Callback): void;
                                                        };
                                                        • 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.

                                                        interface Options

                                                        interface Options {}

                                                          property concurrency

                                                          concurrency?: number | undefined;
                                                          • Default: 20

                                                            Number of concurrently read files in the filesystem while doing clean up.

                                                          property filter

                                                          filter?: string | false | undefined;
                                                          • Receives a formatted entry. Return false to remove it.

                                                            Note: might be called more than once on the same entry.

                                                          property log

                                                          log?: Record<string, (...args: any[]) => any> | undefined;
                                                          • Custom logger function:

                                                            log: { silly () {} }
                                                            log.silly('verify', 'verifying cache at', cache)

                                                          property tmpPrefix

                                                          tmpPrefix?: null | string | undefined;
                                                          • Default: null

                                                            Prefix to append on the temporary directory name inside the cache's tmp dir.

                                                          type Callback

                                                          type Callback = (dir: string) => void;

                                                            namespace verify

                                                            namespace verify {}

                                                              function lastRun

                                                              lastRun: (cachePath: string) => Promise<Date>;
                                                              • Returns a Date representing the last time cacache.verify was run on cache.

                                                              interface Options

                                                              interface Options {}

                                                                property concurrency

                                                                concurrency?: number | undefined;
                                                                • Default: 20

                                                                  Number of concurrently read files in the filesystem while doing clean up.

                                                                property filter

                                                                filter?: string | false | undefined;
                                                                • Receives a formatted entry. Return false to remove it.

                                                                  Note: might be called more than once on the same entry.

                                                                property log

                                                                log?: Record<string, (...args: any[]) => any> | undefined;
                                                                • Custom logger function:

                                                                  log: { silly () {} }
                                                                  log.silly('verify', 'verifying cache at', cache)

                                                                Package Files (1)

                                                                Dependencies (1)

                                                                Dev Dependencies (0)

                                                                No dev dependencies.

                                                                Peer Dependencies (0)

                                                                No peer dependencies.

                                                                Badge

                                                                To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                                                You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@types/cacache.

                                                                • Markdown
                                                                  [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@types/cacache)
                                                                • HTML
                                                                  <a href="https://www.jsdocs.io/package/@types/cacache"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>