Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(glob-cache): streaming API, use async iterables under the hood #124

Merged
merged 3 commits into from
Mar 5, 2020

Conversation

tunnckoCore
Copy link
Owner

@tunnckoCore tunnckoCore commented Mar 4, 2020

"Streaming" / async iterables API

Uses fastGlob.stream by default, plus for await ... of.

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).

const globCache = require('glob-cache');

async function main() {
  const iterable = globCache('src/**/*.js');
  // or like so, both are equivalent
  const iter = globCache.stream({ include: 'src/**/*.js' });

  for await (const ctx of iterable) {
    console.log(ctx);
  }
}

main().catch(console.error);

Promise API

There is also exported globCache.promise API, which is async function and so returns a Promise.

const globCache = require('glob-cache');

const promise = globCache.promise({ include: 'src/**/*.js' });

promise
  .then((results) => {
    console.log(results); // []
  })
  .catch(console.error);

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 it. 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.

const globCache = require('glob-cache');

async function main() {
  const results = await globCache.promise({
    include: 'src/**/*.js',
    buffered: true,
  });

  console.log(results);
  // => [Context, Context, Context, ...]
}

main().catch(console.error);

Hooks API

It's not recommended to use the Hooks API when using the Stream API.

Previously we had just a single options.hook function, now it is options.hooks. And we needed to determine based on ctx.valid and ctx.missing booleans.

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.

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.

1. on very first hit
  -> ctx.changed === true
  -> ctx.notFound === true
2. on second hit (without changes to files)
  -> ctx.changed === false
  -> ctx.notFound === false
3. on third hit (with changes)
  -> ctx.changed === true
  -> ctx.notFound === false

Same as above applies for the hooks calls.

const globCache = require('glob-cache');

(async () => {

await globCache.promise({
  include: 'src/*.js',
  hooks: {
    changed(ctx) {
      if (ctx.notFound) {
        console.log(ctx.file.path, 'first hit');
      } else {
        console.log(ctx.file.path, 'changed');
      }
    },
    always() {
      console.log('file', ctx.file.path);
    },
  },
});

})()

Notice that changed hook is also called when "not found" (i.e. first hit).

Signed-off-by: Charlike Mike Reagent <opensource@tunnckocore.com>
Signed-off-by: Charlike Mike Reagent <opensource@tunnckocore.com>
@codecov
Copy link

codecov bot commented Mar 4, 2020

Codecov Report

Merging #124 into master will increase coverage by 0.83%.
The diff coverage is n/a.

Impacted file tree graph

@@            Coverage Diff             @@
##           master     #124      +/-   ##
==========================================
+ Coverage   53.83%   54.67%   +0.83%     
==========================================
  Files          37       37              
  Lines        1198     1220      +22     
  Branches      343      351       +8     
==========================================
+ Hits          645      667      +22     
  Misses        439      439              
  Partials      114      114              

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 98b82d5...0828e3b. Read the comment docs.

Signed-off-by: Charlike Mike Reagent <opensource@tunnckocore.com>
@tunnckoCore tunnckoCore merged commit a77e7f7 into master Mar 5, 2020
@pr-triage pr-triage bot removed the PR: unreviewed label Mar 5, 2020
@tunnckoCore tunnckoCore deleted the glob-cache-streaming-api branch March 5, 2020 02:04
@pr-triage pr-triage bot added the PR: merged label Mar 5, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant