glob-cache - npm Package Compare versions

Comparing version 0.1.1 to 0.1.2

CHANGELOG.md

@@ -6,2 +6,15 @@ # Change Log
 
+## [0.1.2](https://github.com/tunnckoCore/opensource/compare/glob-cache@0.1.1...glob-cache@0.1.2) (2020-01-19)
+
+
+### Bug Fixes
+
+* **glob-cache:** docs + 100% coverage :kiss: ([fde5f5f](https://github.com/tunnckoCore/opensource/commit/fde5f5fe6d707426f90041682eb1e7bbc75a682f))
+* badges, regenerate readmes ([ccf3b73](https://github.com/tunnckoCore/opensource/commit/ccf3b73c123dc66f2b1964bb263ab9e331449d3c))
+* **docks:** use html entities for < and >, regen readmes ([cd11b11](https://github.com/tunnckoCore/opensource/commit/cd11b1154edb8011495a979a96fbe6b5822bc05c))
+
+
+
+
+
 ## [0.1.1](https://github.com/tunnckoCore/opensource/compare/glob-cache@0.1.0...glob-cache@0.1.1) (2020-01-19)
@@ -8,0 +21,0 @@

package.json

 {
   "name": "glob-cache",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Caching layer (using `cacache`) for any file globbing solution (`glob`, `fast-glob`, `tiny-glob`). Makes you Instant Fast™ and allows you to hook into very specific & important part of the process",
@@ -57,4 +57,4 @@ "repository": {
   "cov": {
-    "value": 6.93,
-    "color": "red"
+    "value": 100,
+    "color": "green"
   },
@@ -87,3 +87,3 @@ "licenseStart": 2020,
   },
-  "gitHead": "2c533adbdb9674b5f2a88e8ef08ef2beda80385a"
+  "gitHead": "b5eed58a5fbba071047b5e032792f4953f9f450d"
 }

README.md

@@ -0,1 +1,8 @@
+<p align="center">
+  <img
+    align="center"
+    src="./logo.png"
+  />
+</p>
+
 # glob-cache [![npm version][npmv-img]][npmv-url] [![License][license-img]][license-url]
@@ -62,2 +69,3 @@
   - [globCache](#globcache)
+- [Context and how it works](#context-and-how-it-works)
 - [Contributing](#contributing)
@@ -86,8 +94,8 @@ - [Guides and Community](#guides-and-community)
 
-_Generated using [jest-runner-docs](https://npmjs.com/package/jest-runner-docs)._
+_Generated using [jest-runner-docs](https://ghub.now.sh/jest-runner-docs)._
 
-### [globCache](./src/index.js#L49)
+### [globCache](./src/index.js#L46)
 
 Match files and folders using glob patterns. Returns a resolved Promise containing
-a `{ results, cacache }` object - where `results` is an array of [Context](#context) objects
+a `{ results, cacache }` object - where `results` is an array of [Context](#context-and-how-it-works) objects
 and `cacache` is the [cacache][] package.
@@ -103,6 +111,6 @@
 
-- `options.include` **{Array<string>}** - string or array of string glob patterns
+- `options.include` **{Array&lt;string&gt;}** - string or array of string glob patterns
 - `options.exclude` **{string}** - ignore patterns
-- `options.hook` **{Function}** - a hook function passed with [Context](#context)
 - `options.always` **{boolean}** - a boolean that makes `options.hook` to always be called
+- `options.hook` **{Function}** - a hook function passed with [Context](#context-and-how-it-works)
 - `options.glob` **{Function}** - a globbing library like [glob][], [fast-glob][], [tiny-glob][], defaults to `fast-glob`
@@ -119,6 +127,3 @@ - `options.globOptions` **{object}** - options passed to the `options.glob` library
 
-glob({
-  include: 'src/*.js',
-  glob: tinyGlob,
-}).then(({ results, cacache }) => {
+glob({ include: 'src/*.js', glob: tinyGlob }).then(({ results }) => {
   console.log(results);
@@ -130,2 +135,71 @@ });
 
+## Context and how it works
+
+Each context contains a `{ file, cacheFile, cacheLocation, cacache }` and more properties.
+The `file` one represents the fresh file loaded from the system, the `cacheFile` represents the
+file from the cache. Both has `path`, `size` and `integrity` properties, plus more.
+
+The `cacheFile` can be `null` if it's the first hit (not found in cache),
+in such case the `ctx.missing` will be `true` and on next runs this will be `false`.
+
+Important to note is that `cacheFile` don't have a `contents` property, but has `path`
+which points to the place of the cache file on the disk.
+
+The interesting one is the `ctx.valid`. This one is the reason for the whole existance
+of this module. If both the "source" file and cache file are the same,
+e.g. same size and integrity (which means the contents/shasum are equal),
+then `ctx.valid: true`, otherwise this will be `false`. Simply said, when you change your file(s)
+matched by a the given glob pattern(s), then it will be `valid: false` and the `options.hook` will
+be called.
+
+There is also one more key point, and it's in the `options`. We have `options.hook` and
+`options.always`. By default we only call the `options.hook` when `valid: false` which is
+important and intentional, because most of the time you only want to do or run something
+when there are actual changes in the files, right? But there are also a cases when you want
+more control, that's why we have `options.always` option which bypass the previous validation
+and so the `options.hook` will always be called and so you can decide what to do or
+make more additional checks - for example, listen the `mtime` - or track the dependencies
+of the file. Tracking dependencies is something that some test runner may benefit.
+
+Because all that, we also expose `cacache` to that `options.hook`,
+so you can update or clean the cache - it's up to you.
+
+Example `results` array with context (which is also passed to `options.hook`):
+
+```
+[
+  {
+    file: {
+      path: '/home/charlike/github/tunnckoCore/opensource/packages/glob-cache/test/index.js',
+      contents: <Buffer 27 75 73 65 20 73 74 72 69 63 74 27 3b 0a 0a 63 6f 6e 73 74 20 70 61 74 68 20 3d 20 72 65 71 75 69 72 65 28 27 70 61 74 68 27 29 3b 0a 63 6f 6e 73 74 ... 350 more bytes>,
+      size: 400,
+      integrity: 'sha512-p5daDYwu9vhNNjT9vfRrWHXIwwlPxeqeub4gs3qMZ88J//ONUH7Je2Muu9o+MxjA1Fv3xwbgkBdjcHgdj7ar4A=='
+    },
+    cacheFile: null,
+    cacheLocation: '/home/charlike/github/tunnckoCore/opensource/packages/glob-cache/test/fixture-cache',
+    cacache: { /* cacache instance */ },
+    valid: true,
+    missing: true
+  },
+  {
+    file: {
+      path: '/home/charlike/github/tunnckoCore/opensource/packages/glob-cache/src/index.js',
+      contents: <Buffer 2f 2a 20 65 73 6c 69 6e 74 2d 64 69 73 61 62 6c 65 20 6e 6f 2d 70 61 72 61 6d 2d 72 65 61 73 73 69 67 6e 20 2a 2f 0a 0a 27 75 73 65 20 73 74 72 69 63 ... 5268 more bytes>,
+      size: 5318,
+      integrity: 'sha512-946V9t8jWq6oGdAVnrl206b077+Ejl0VFn/MK1axZdsFyvzGrT+MfzH2aVQOUPMcp8jm5tZvES7A1XXEsRvZ9w=='
+    },
+    cacheFile: null,
+    cacheLocation: '/home/charlike/github/tunnckoCore/opensource/packages/glob-cache/test/fixture-cache',
+    cacache: { /* cacache instance */ },
+    valid: true,
+    missing: true
+  }
+]
+```
+
+One more thing to clarify. When there is no cache, e.g. the state is "missing",
+and if you look over the code you'll see that the `valid` is
+hard-coded/forced to be `true`. You may expect the hook to be called in the first run
+but it will not. For that behavior you should use the `always: true`.
+
 **[back to top](#readme)**
@@ -193,4 +267,4 @@
 [npmv-url]: https://www.npmjs.com/package/glob-cache
-[npmv-img]: https://badgen.net/npm/v/glob-cache?icon=npm
-[nodejs-img]: https://badgen.net/badge/node/>=12.13/green
+[npmv-img]: https://badgen.net/npm/v/glob-cache?icon=npm?cache=1
+[nodejs-img]: https://badgen.net/badge/node/>=12.13/green?cache=1
 
@@ -203,3 +277,3 @@ <!--
 [license-url]: https://github.com/tunnckoCore/opensource/blob/master/packages/glob-cache/LICENSE
-[license-img]: https://badgen.net/npm/license/glob-cache
+[license-img]: https://badgen.net/npm/license/glob-cache?cache=1
 
@@ -209,23 +283,23 @@ <!-- Front line badges -->
 [codestyle-url]: https://github.com/airbnb/javascript
-[codestyle-img]: https://badgen.net/badge/code%20style/airbnb/ff5a5f?icon=airbnb
+[codestyle-img]: https://badgen.net/badge/code%20style/airbnb/ff5a5f?icon=airbnb&cache=1
 [linuxbuild-url]: https://github.com/tunnckocore/opensource/actions
-[linuxbuild-img]: https://badgennet.charlike-oss.now.sh/github/checks/tunnckoCore/opensource/master?label=build&icon=github
+[linuxbuild-img]: https://badgen.net/github/checks/tunnckoCore/opensource/master?cache=1&label=build&icon=github
 [codecoverage-url]: https://codecov.io/gh/tunnckoCore/opensource
-[codecoverage-img]: https://badgen.net/badge/coverage/6.93%25/red?icon=codecov
+[codecoverage-img]: https://badgen.net/badge/coverage/100%25/green?icon=codecov&cache=1
 [dependencies-url]: https://david-dm.org/tunnckoCore/opensource
-[dependencies-img]: https://badgen.net/david/dep/tunnckoCore/opensource?label=deps
+[dependencies-img]: https://badgen.net/david/dep/tunnckoCore/opensource?label=deps&cache=1
 [ccommits-url]: https://conventionalcommits.org/
-[ccommits-img]: https://badgen.net/badge/conventional%20commits/v1.0.0/green
+[ccommits-img]: https://badgen.net/badge/conventional%20commits/v1.0.0/green?cache=1
 [standard-release-url]: https://github.com/standard-release/standard-release
-[standard-release-img]: https://badgen.net/badge/semantically/released/05c5ff
-[community-img]: https://badgen.net/badge/join/community/7b16ff
+[standard-release-img]: https://badgen.net/badge/semantically/released/05c5ff?cache=1
+[community-img]: https://badgen.net/badge/join/community/7b16ff?cache=1
 [community-url]: https://github.com/tunnckocorehq/community
-[last-commit-img]: https://badgen.net/github/last-commit/tunnckoCore/opensource/master
+[last-commit-img]: https://badgen.net/github/last-commit/tunnckoCore/opensource/master?cache=1
 [last-commit-url]: https://github.com/tunnckoCore/opensource/commits/master
-[downloads-weekly-img]: https://badgen.net/npm/dw/glob-cache?icon=npm
-[downloads-monthly-img]: https://badgen.net/npm/dm/glob-cache?icon=npm
-[downloads-total-img]: https://badgen.net/npm/dt/glob-cache?icon=npm
+[downloads-weekly-img]: https://badgen.net/npm/dw/glob-cache?icon=npm&cache=1
+[downloads-monthly-img]: https://badgen.net/npm/dm/glob-cache?icon=npm&cache=1
+[downloads-total-img]: https://badgen.net/npm/dt/glob-cache?icon=npm&cache=1
 [renovateapp-url]: https://renovatebot.com
-[renovateapp-img]: https://badgen.net/badge/renovate/enabled/green
-[prs-welcome-img]: https://badgen.net/badge/PRs/welcome/green
+[renovateapp-img]: https://badgen.net/badge/renovate/enabled/green?cache=1
+[prs-welcome-img]: https://badgen.net/badge/PRs/welcome/green?cache=1
 [prs-welcome-url]: http://makeapullrequest.com
@@ -236,3 +310,3 @@
 [paypal-url]: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=HYJJEZNSGAPGC&source=url
-[paypal-img]: https://badgen.net/badge/PayPal/donate/003087?icon=https://simpleicons.now.sh/paypal/fff
+[paypal-img]: https://badgen.net/badge/PayPal/donate/003087?cache=1&icon=https://simpleicons.now.sh/paypal/fff
 
@@ -242,3 +316,3 @@ <!-- TODO: update icon -->
 [kofi-url]: https://ko-fi.com/tunnckoCore
-[kofi-img]: https://badgen.net/badge/Buy%20me/a%20coffee/29abe0c2?icon=https://rawcdn.githack.com/tunnckoCore/badgen-icons/f8264c6414e0bec449dd86f2241d50a9b89a1203/icons/kofi.svg
+[kofi-img]: https://badgen.net/badge/Buy%20me/a%20coffee/29abe0c2?cache=1&icon=https://rawcdn.githack.com/tunnckoCore/badgen-icons/f8264c6414e0bec449dd86f2241d50a9b89a1203/icons/kofi.svg
 
@@ -248,7 +322,7 @@ <!-- TODO: update icon -->
 [bitcoin-url]: https://www.blockchain.com/btc/payment_request?address=3QNHKun1K1SUui1b4Z3KEGPPsWC1TgtnqA&message=Open+Source+Software&amount_local=10&currency=USD
-[bitcoin-img]: https://badgen.net/badge/Bitcoin%20tip/3QNHKun...b4Z3KEGPPsWC1TgtnqA/yellow?icon=https://simpleicons.now.sh/bitcoin/fff
+[bitcoin-img]: https://badgen.net/badge/Bitcoin%20tip/3QNHKun...b4Z3KEGPPsWC1TgtnqA/yellow?cache=1&icon=https://simpleicons.now.sh/bitcoin/fff
 [keybase-url]: https://keybase.io/tunnckoCore
-[keybase-img]: https://badgen.net/keybase/pgp/tunnckoCore
+[keybase-img]: https://badgen.net/keybase/pgp/tunnckoCore?cache=1
 [twitter-url]: https://twitter.com/tunnckoCore
-[twitter-img]: https://badgen.net/twitter/follow/tunnckoCore?icon=twitter&color=1da1f2
+[twitter-img]: https://badgen.net/twitter/follow/tunnckoCore?icon=twitter&color=1da1f2&cache=1
 [patreon-url]: https://www.patreon.com/bePatron?u=5579781
@@ -255,0 +329,0 @@ [patreon-img]: https://badgen.net/badge/Become/a%20patron/F96854?icon=patreon

src/index.js

@@ -23,3 +23,3 @@ /* eslint-disable no-param-reassign */
  * Match files and folders using glob patterns. Returns a resolved Promise containing
- * a `{ results, cacache }` object - where `results` is an array of [Context](#context) objects
+ * a `{ results, cacache }` object - where `results` is an array of [Context](#context-and-how-it-works) objects
  * and `cacache` is the [cacache][] package.
@@ -31,6 +31,3 @@ *
  *
- * glob({
- *   include: 'src/*.js',
- *   glob: tinyGlob,
- * }).then(({ results, cacache }) => {
+ * glob({ include: 'src/*.js', glob: tinyGlob }).then(({ results }) => {
  *   console.log(results);
@@ -43,4 +40,4 @@ * });
  * @param {string} options.exclude - ignore patterns
- * @param {Function} options.hook - a hook function passed with [Context](#context)
  * @param {boolean} options.always - a boolean that makes `options.hook` to always be called
+ * @param {Function} options.hook - a hook function passed with [Context](#context-and-how-it-works)
  * @param {Function} options.glob - a globbing library like [glob][], [fast-glob][], [tiny-glob][], defaults to `fast-glob`
@@ -54,2 +51,4 @@ * @param {object} options.globOptions - options passed to the `options.glob` library
   const opts = { ...defaultOptions, ...options };
+
+  /* istanbul ignore next */
   if (typeof opts.glob !== 'function') {
@@ -77,3 +76,3 @@ opts.glob = fastGlob;
 
-  const results = [];
+  /* istanbul ignore next */
   const hook = typeof opts.hook !== 'function' ? () => {} : opts.hook;
@@ -83,2 +82,3 @@ const cacheLoc = opts.cacheLocation;
   const cacheFiles = Object.keys(cached);
+  const results = [];
 
@@ -136,2 +136,3 @@ const missingFilesInCache = arrayDiff(
         // most probably the source file was deleted
+        /* istanbul ignore next */
         if (!fs.existsSync(fp)) {
@@ -165,3 +166,3 @@ // console.log('delete from cache:', fp);
 
-        if (opts.always === true || valid === true) {
+        if (opts.always === true || valid === false) {
           await hook(ctx);
@@ -168,0 +169,0 @@ }

No alert changes

Improved metrics

Total package byte prevSize

26093

increased by21.18%

Number of lines in readme file

335

increased by28.35%

No dependency changes