cacache 12.0.4 → 15.0.0

package/CHANGELOG.md

@@ -2,9 +2,115 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
-### [12.0.4](https://github.com/npm/cacache/compare/v12.0.3...v12.0.4) (2020-03-24)
+## [15.0.0](https://github.com/npm/cacache/compare/v14.0.0...v15.0.0) (2020-02-18)
 
 
+### ⚠ BREAKING CHANGES
+
+* drop figgy-pudding and use canonical option names.
+
+### Features
+
+* remove figgy-pudding ([57d11bc](https://github.com/npm/cacache/commit/57d11bce34f979247d1057d258acc204c4944491))
+
+## [14.0.0](https://github.com/npm/cacache/compare/v13.0.1...v14.0.0) (2020-01-28)
+
+
+### ⚠ BREAKING CHANGES
+
+* **deps:** bumps engines to >= 10
+
+* **deps:** tar v6 and mkdirp v1 ([5a66e7a](https://github.com/npm/cacache/commit/5a66e7a))
+
+### [13.0.1](https://github.com/npm/cacache/compare/v13.0.0...v13.0.1) (2019-09-30)
+
+
+### Bug Fixes
+
+* **fix-owner:** chownr.sync quits on non-root uid ([08801be](https://github.com/npm/cacache/commit/08801be))
+
+## [13.0.0](https://github.com/npm/cacache/compare/v12.0.3...v13.0.0) (2019-09-25)
+
+
+### ⚠ BREAKING CHANGES
+
+* This subtly changes the streaming interface of
+everything in cacache that streams, which is, well, everything in
+cacache.  Most users will probably not notice, but any code that
+depended on stream behavior always being deferred until next tick will
+need to adjust.
+
+The mississippi methods 'to', 'from', 'through', and so on, have been
+replaced with their Minipass counterparts, and streaming interaction
+with the file system is done via fs-minipass.
+
+The following modules are of interest here:
+
+- [minipass](http://npm.im/minipass) The core stream library.
+
+- [fs-minipass](http://npm.im/fs-minipass)  Note that the 'WriteStream'
+  class from fs-minipass is _not_ a Minipass stream, but rather a plain
+  old EventEmitter that duck types as a Writable.
+
+- [minipass-collect](http://npm.im/minipass-collect) Gather up all the
+  data from a stream.  Cacache only uses Collect.PassThrough, which is a
+  basic Minipass passthrough stream which emits a 'collect' event with
+  the completed data just before the 'end' event.
+
+- [minipass-pipeline](http://npm.im/minipass-pipeline) Connect one or
+  more streams into a pipe chain.  Errors anywhere in the pipeline are
+  proxied down the chain and then up to the Pipeline object itself.
+  Writes go into the head, reads go to the tail.  Used in place of
+  pump() and pumpify().
+
+- [minipass-flush](http://npm.im/minipass-flush) A Minipass passthrough
+  stream that defers its 'end' event until after a flush() method has
+  completed (either calling the supplied callback, or returning a
+  promise.)  Use in place of flush-write-stream (aka mississippi.to).
+
+Streams from through2, concat-stream, and the behavior provided by
+end-of-stream are all implemented in Minipass itself.
+
+Features of interest to cacache, which make Minipass a particularly good
+fit:
+
+- All of the 'endish' events are normalized, so we can just listen on
+  'end' and know that finish, prefinish, and close will be handled as
+  well.
+- Minipass doesn't waste time [containing
+  zalgo](https://blog.izs.me/2013/08/designing-apis-for-asynchrony).
+- Minipass has built-in support for promises that indicate the end or
+  error: stream.promise(), stream.collect(), and stream.concat().
+- With reliable and consistent timing guarantees, much less
+  error-checking logic is required.  We can be more confident that an
+  error is being thrown or emitted in the correct place, rather than in
+  a callback which is deferred, resulting in a hung promise or
+  uncaughtException.
+
+The biggest downside of Minipass is that it lacks some of the internal
+characteristics of node-core streams, which many community modules use
+to identify streams.  They have no _writableState or _readableState
+objects, or _read or _write methods.  As a result, the is-stream module
+(at least, at the time of this commit) doesn't recognize Minipass
+streams as readable or writable streams.
+
+All in all, the changes required of downstream users should be minimal,
+but are unlikely to be zero.  Hence the semver major change.
+
+### Features
+
+* replace all streams with Minipass streams ([f4c0962](https://github.com/npm/cacache/commit/f4c0962))
+* **deps:** Add minipass and minipass-pipeline ([a6545a9](https://github.com/npm/cacache/commit/a6545a9))
+* **promise:** converted .resolve to native promise, converted .map and .reduce to native ([220c56d](https://github.com/npm/cacache/commit/220c56d))
+* **promise:** individually promisifing functions as needed ([74b939e](https://github.com/npm/cacache/commit/74b939e))
+* **promise:** moved .reject from bluebird to native promise ([1d56da1](https://github.com/npm/cacache/commit/1d56da1))
+* **promise:** removed .fromNode, removed .join ([9c457a0](https://github.com/npm/cacache/commit/9c457a0))
+* **promise:** removed .map, replaced with p-map. removed .try ([cc3ee05](https://github.com/npm/cacache/commit/cc3ee05))
+* **promise:** removed .tap ([0260f12](https://github.com/npm/cacache/commit/0260f12))
+* **promise:** removed .using/.disposer ([5d832f3](https://github.com/npm/cacache/commit/5d832f3))
+* **promise:** removed bluebird ([c21298c](https://github.com/npm/cacache/commit/c21298c))
+* **promise:** removed bluebird specific .catch calls ([28aeeac](https://github.com/npm/cacache/commit/28aeeac))
+* **promise:** replaced .reduce and .mapSeries ([478f5cb](https://github.com/npm/cacache/commit/478f5cb))
 
 ### [12.0.3](https://github.com/npm/cacache/compare/v12.0.2...v12.0.3) (2019-08-19)
 
@@ -69,7 +175,7 @@ chown everything to root.
 The solution is for the user to create a folder, make it user-owned, and
 use that, rather than relying on cacache to create the root cache folder.
 
-If we decide to restore the uid/gid opts, and use ownership inferrence
+If we decide to restore the uid/gid opts, and use ownership inference
 only when uid/gid are unset, then take care to also make rm take an
 option object, and pass it through to entry-index.js.
 

package/README.md

@@ -12,8 +12,6 @@ when running as `root`.
 It was written to be used as [npm](https://npm.im)'s local cache, but can
 just as easily be used on its own.
 
-_Translations: [español](README.es.md)_
-
 ## Install
 
 `$ npm install --save cacache`
@@ -35,12 +33,10 @@ _Translations: [español](README.es.md)_
   * Writing
     * [`put`](#put-data)
     * [`put.stream`](#put-stream)
-    * [`put*` opts](#put-options)
     * [`rm.all`](#rm-all)
     * [`rm.entry`](#rm-entry)
     * [`rm.content`](#rm-content)
   * Utilities
-    * [`setLocale`](#set-locale)
     * [`clearMemoized`](#clear-memoized)
     * [`tmp.mkdir`](#tmp-mkdir)
     * [`tmp.withTmp`](#with-tmp)
@@ -52,7 +48,7 @@ _Translations: [español](README.es.md)_
 ### Example
 
 ```javascript
-const cacache = require('cacache/en')
+const cacache = require('cacache')
 const fs = require('fs')
 
 const tarball = '/path/to/mytar.tgz'
@@ -95,7 +91,7 @@ cacache.get.byDigest(cachePath, integrityHash).then(data => {
 * Lockless, high-concurrency cache access
 * Streaming support
 * Promise support
-* Pretty darn fast -- sub-millisecond reads and writes including verification
+* Fast -- sub-millisecond reads and writes including verification
 * Arbitrary metadata storage
 * Garbage collection and additional offline verification
 * Thorough test coverage
@@ -113,21 +109,6 @@ Happy hacking!
 
 ### API
 
-#### <a name="localized-api"></a> Using localized APIs
-
-cacache includes a complete API in English, with the same features as other
-translations. To use the English API as documented in this README, use
-`require('cacache/en')`. This is also currently the default if you do
-`require('cacache')`, but may change in the future.
-
-cacache also supports other languages! You can find the list of currently
-supported ones by looking in `./locales` in the source directory. You can use
-the API in that language with `require('cacache/<lang>')`.
-
-Want to add support for a new language? Please go ahead! You should be able to
-copy `./locales/en.js` and `./locales/en.json` and fill them in. Translating the
-`README.md` is a bit more work, but also appreciated if you get around to it. 👍🏼
-
 #### <a name="ls"></a> `> cacache.ls(cache) -> Promise<Object>`
 
 Lists info for all entries currently in the cache as a single large object. Each
@@ -219,6 +200,8 @@ 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.
 
+See: [options](#get-options)
+
 ##### Note
 
 This function loads the entire cache entry into memory before returning it. If
@@ -260,6 +243,8 @@ 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.
 
+See: [options](#get-options)
+
 ##### Example
 
 ```javascript
@@ -346,12 +331,33 @@ cacache.get.hasContent(cachePath, 'sha521-NOT+IN/CACHE==').then(console.log)
 false
 ```
 
+##### <a name="get-options"></a> Options
+
+##### `opts.integrity`
+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.
+
+##### `opts.memoize`
+
+Default: null
+
+If explicitly truthy, cacache will read from memory and memoize data on bulk read. If `false`, cacache will read from disk data. Reader functions by default read from in-memory cache.
+
+##### `opts.size`
+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.
+
+
 #### <a name="put-data"></a> `> cacache.put(cache, key, data, [opts]) -> Promise`
 
 Inserts data passed to it into the cache. The returned Promise resolves with a
 digest (generated according to [`opts.algorithms`](#optsalgorithms)) after the
 cache entry has been successfully written.
 
+See: [options](#put-options)
+
 ##### Example
 
 ```javascript
@@ -371,6 +377,8 @@ Stream](https://nodejs.org/api/stream.html#stream_writable_streams) that inserts
 data written to it into the cache. Emits an `integrity` event with the digest of
 written contents when it succeeds.
 
+See: [options](#put-options)
+
 ##### Example
 
 ```javascript
@@ -383,9 +391,7 @@ request.get(
 )
 ```
 
-#### <a name="put-options"></a> `> cacache.put options`
-
-`cacache.put` functions have a number of options in common.
+##### <a name="put-options"></a> Options
 
 ##### `opts.metadata`
 
@@ -400,7 +406,7 @@ with an `EBADSIZE` error.
 ##### `opts.integrity`
 
 If present, the pre-calculated digest for the inserted content. If this option
-if provided and does not match the post-insertion digest, insertion will fail
+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.
@@ -433,6 +439,11 @@ 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.
 
+##### `opts.tmpPrefix`
+Default: null
+
+Prefix to append on the temporary directory name inside the cache's tmp dir. 
+
 #### <a name="rm-all"></a> `> cacache.rm.all(cache) -> Promise`
 
 Clears the entire cache. Mainly by blowing away the cache directory itself.
@@ -478,14 +489,6 @@ cacache.rm.content(cachePath, 'sha512-SoMeDIGest/IN+BaSE64==').then(() => {
 })
 ```
 
-#### <a name="set-locale"></a> `> cacache.setLocale(locale)`
-
-Configure the language/locale used for messages and errors coming from cacache.
-The list of available locales is in the `./locales` directory in the project
-root.
-
-_Interested in contributing more languages! [Submit a PR](CONTRIBUTING.md)!_
-
 #### <a name="clear-memoized"></a> `> cacache.clearMemoized()`
 
 Completely resets the in-memory entry cache.
@@ -504,6 +507,8 @@ permissions.
 If you want automatic cleanup of this directory, use
 [`tmp.withTmp()`](#with-tpm)
 
+See: [options](#tmp-options)
+
 ##### Example
 
 ```javascript
@@ -537,12 +542,14 @@ cacache.tmp.mkdir(cache).then(dir => {
 
 Creates a temporary directory with [`tmp.mkdir()`](#tmp-mkdir) and calls `cb`
 with it. The created temporary directory will be removed when the return value
-of `cb()` resolves -- that is, if you return a Promise from `cb()`, the tmp
-directory will be automatically deleted once that promise completes.
+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.
 
+See: [options](#tmp-options)
+
 ##### Example
 
 ```javascript
@@ -553,6 +560,13 @@ cacache.tmp.withTmp(cache, dir => {
 })
 ```
 
+##### <a name="tmp-options"></a> Options
+
+##### `opts.tmpPrefix`
+Default: null
+
+Prefix to append on the temporary directory name inside the cache's tmp dir. 
+
 #### <a name="integrity"></a> Subresource Integrity Digests
 
 For content verification and addressing, cacache uses strings following the
@@ -608,10 +622,24 @@ 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.
 
-##### Options
+##### <a name="verify-options"></a> Options
+
+##### `opts.concurrency`
 
-* `opts.filter` - receives a formatted entry. Return false to remove it.
-                  Note: might be called more than once on the same entry.
+Default: 20
+
+Number of concurrently read files in the filesystem while doing clean up.
+
+##### `opts.filter`
+Receives a formatted entry. Return false to remove it.
+Note: might be called more than once on the same entry.
+
+##### `opts.log`
+Custom logger function:
+```
+  log: { silly () {} }
+  log.silly('verify', 'verifying cache at', cache)
+```
 
 ##### Example