|
3 | 3 | All notable changes to this project will be documented in this file. |
4 | 4 | See [Conventional Commits](https://conventionalcommits.org) for commit guidelines. |
5 | 5 |
|
| 6 | +# [1.0.0](https://github.com/tunnckoCore/opensource/compare/[email protected]@1.0.0) (2020-03-05) |
| 7 | + |
| 8 | + |
| 9 | +### Bug Fixes |
| 10 | + |
| 11 | +* **glob-cache:** include mpl-2.0 license file ([90f1e4e](https://github.com/tunnckoCore/opensource/commit/90f1e4e20ef2660db8e7c6036c2305e20531b50f)) |
| 12 | + |
| 13 | + |
| 14 | +### Features |
| 15 | + |
| 16 | +* **glob-cache:** streaming API, use async iterables under the h… ([#124](https://github.com/tunnckoCore/opensource/issues/124)) ([a77e7f7](https://github.com/tunnckoCore/opensource/commit/a77e7f7a1bd1478500cad9ae36dd5efda528a47a)) |
| 17 | + |
| 18 | + |
| 19 | +### BREAKING CHANGES |
| 20 | + |
| 21 | +* **glob-cache:** use async iterables + expose Stream, Promise, and Hooks APIs |
| 22 | + |
| 23 | +## "Streaming" / async iterables API |
| 24 | +Uses `fastGlob.stream` by default, plus `for await ... of`. |
| 25 | + |
| 26 | +The main default export is async generator `async function * () {}` and it returns async iterable, so you need to call `iterable.next()` or to use `for await` loop (which requires `async` function). |
| 27 | + |
| 28 | +```js |
| 29 | +const globCache = require('glob-cache'); |
| 30 | + |
| 31 | +async function main() { |
| 32 | + const iterable = globCache('src/**/*.js'); |
| 33 | + // or like so, both are equivalent |
| 34 | + const iter = globCache.stream({ include: 'src/**/*.js' }); |
| 35 | + |
| 36 | + for await (const ctx of iterable) { |
| 37 | + console.log(ctx); |
| 38 | + } |
| 39 | +} |
| 40 | + |
| 41 | +main().catch(console.error); |
| 42 | +``` |
| 43 | + |
| 44 | +## Promise API |
| 45 | + |
| 46 | +There is also exported `globCache.promise` API, which is `async function` and so returns a Promise. |
| 47 | + |
| 48 | +```js |
| 49 | +const globCache = require('glob-cache'); |
| 50 | + |
| 51 | +const promise = globCache.promise({ include: 'src/**/*.js' }); |
| 52 | + |
| 53 | +promise |
| 54 | + .then((results) => { |
| 55 | + console.log(results); // [] |
| 56 | + }) |
| 57 | + .catch(console.error); |
| 58 | +``` |
| 59 | + |
| 60 | +Important to note. By default the Promise API resolves to an empty array. That's intentional since we also have the so-called Hooks API and so it's unnecessary to pollute the memory when you are using this api. If you don't use the Hooks API, but just want the results then pass `buffered: true` and the promise will resolve to an array of Context objects. You can later filter this `results` array of contexts by `ctx.changed` or `ctx.notFound`, or whatever. |
| 61 | + |
| 62 | +```js |
| 63 | +const globCache = require('glob-cache'); |
| 64 | + |
| 65 | +async function main() { |
| 66 | + const results = await globCache.promise({ |
| 67 | + include: 'src/**/*.js', |
| 68 | + buffered: true, |
| 69 | + }); |
| 70 | + |
| 71 | + console.log(results); |
| 72 | + // => [Context, Context, Context, ...] |
| 73 | +} |
| 74 | + |
| 75 | +main().catch(console.error); |
| 76 | +``` |
| 77 | + |
| 78 | +## Hooks API |
| 79 | + |
| 80 | +**It's not recommended to use the Hooks API when using the Stream API.** |
| 81 | + |
| 82 | +Previously we had just a single `options.hook` function, now it is `options.hooks` object. And we needed to determine based on `ctx.valid` and `ctx.missing` booleans. |
| 83 | + |
| 84 | +Now we just have hooks for everything - `hooks.changed`, `hooks.notChanged`, `hooks.found`, `hooks.notFound` and `hooks.always`. It's pretty obvious by their names. Hooks can also be async functions - using async/await or regular function returning a promise. |
| 85 | + |
| 86 | +The `ctx.valid` and `ctx.missing` are replaced by `ctx.changed` and `ctx.notFound` - both has almost the same meaning as previously. Both are available through all the hooks. In combination with hooks it becomes great. |
| 87 | + |
| 88 | +``` |
| 89 | +1. on very first hit |
| 90 | + -> ctx.changed === true |
| 91 | + -> ctx.notFound === true |
| 92 | +2. on second hit (without changes to files) |
| 93 | + -> ctx.changed === false |
| 94 | + -> ctx.notFound === false |
| 95 | +3. on third hit (with changes) |
| 96 | + -> ctx.changed === true |
| 97 | + -> ctx.notFound === false |
| 98 | +``` |
| 99 | + |
| 100 | +Same as above applies for the hooks calls. |
| 101 | + |
| 102 | +```js |
| 103 | +const globCache = require('glob-cache'); |
| 104 | + |
| 105 | +(async () => { |
| 106 | + |
| 107 | +await globCache.promise({ |
| 108 | + include: 'src/*.js', |
| 109 | + hooks: { |
| 110 | + changed(ctx) { |
| 111 | + if (ctx.notFound) { |
| 112 | + console.log(ctx.file.path, 'first hit'); |
| 113 | + } else { |
| 114 | + console.log(ctx.file.path, 'changed'); |
| 115 | + } |
| 116 | + }, |
| 117 | + always() { |
| 118 | + console.log('file', ctx.file.path); |
| 119 | + }, |
| 120 | + }, |
| 121 | +}); |
| 122 | + |
| 123 | +})() |
| 124 | +``` |
| 125 | + |
| 126 | +Notice that `changed` hook is also called when "not found" (i.e. first hit). |
| 127 | + |
| 128 | +Signed-off-by: Charlike Mike Reagent <[email protected]> |
| 129 | + |
| 130 | + |
| 131 | + |
| 132 | + |
| 133 | + |
6 | 134 | ## [0.3.5](https://github.com/tunnckoCore/opensource/compare/[email protected]@0.3.5) (2020-02-29) |
7 | 135 |
|
8 | 136 |
|
|
0 commit comments