Skip to content

Commit

Permalink
Tweak README and CHANGELOG to note new pure ESM interface
Browse files Browse the repository at this point in the history
  • Loading branch information
rdmurphy committed Jun 12, 2021
1 parent 846d97b commit b1cabd9
Show file tree
Hide file tree
Showing 2 changed files with 21 additions and 16 deletions.
6 changes: 4 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]

### Added
- The `quaff` file processor is now available at `quaffFile`. This makes it possible to tap into all of `quaff`'s processors to load a single file. The (now) named `quaff` export works the same as before but uses the new `quaffFile` behind the scenes.
- The `quaff` file processor is now available at `parseFile`. This makes it possible to tap into all of `quaff`'s processors to load a single file. The (now) named `parse` export works the same as before and uses `parseFile` behind the scenes.
- It is now possible to pass in JavaScript files using the `.cjs` and `.mjs` extensions.

### Changed
- `quaff` no longer has a default export and now uses two named exports - `quaff` and `quaffFile`.
- `quaff` is now a [pure ESM package](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). It can no longer be `require()`'d from CommonJS. If this functionality is still needed please continue to use `quaff@^4`. It is also possible to [dynamically import ESM in CommonJS](https://nodejs.org/api/esm.html#esm_import_expressions) (`await import('quaff')`) if that is compatible with your use case.
- `quaff` no longer has a default export and now uses two named exports - `parse` and `parseFile`.

## [4.2.0] - 2020-07-16

Expand Down
31 changes: 17 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@
<a href="https://packagephobia.now.sh/result?p=quaff"><img src="https://packagephobia.now.sh/badge?p=quaff" alt="install size"></a>
</p>

## Important!

`quaff` is now a [pure ESM package](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). It can no longer be `require()`'d from CommonJS. If this functionality is still needed please continue to use `quaff@^4`.

## Key features

- 🚚 A **data pipeline helper** written in Node.js that works similar to [Middleman](https://middlemanapp.com/)'s [Data Files](https://middlemanapp.com/advanced/data_files/) collector
Expand All @@ -24,7 +28,7 @@
npm install quaff --save-dev
```

`quaff` requires **Node.js 10 or later**.
`quaff` requires **Node.js 12.20.0 or later**.

## Usage

Expand All @@ -41,13 +45,12 @@ data/
story.aml
```

After `require()`'ing `quaff`:
After `import`'ing `quaff`:

```js
const quaff = require('quaff');

const data = await quaff('./data/');
import { load } from 'quaff';

const data = await load('./data/');
console.log(data);
```

Expand Down Expand Up @@ -89,10 +92,10 @@ And the results...

One of the biggest features added in `quaff` 4.0 is the ability to load JavaScript files. But how exactly does that work?

JavaScript files that are consumed by `quaff` have to follow one simple rule - they must export a default function (or value) at `module.exports`. All three of these are valid and return the same value:
JavaScript files that are consumed by `quaff` have to follow one simple rule - they must `export default` a function, an async function or value. All three of these are valid and return the same value:

```js
module.exports = [
export default [
{
name: 'Pudge',
instagram: 'https://instagram.com/pudgethecorgi/',
Expand All @@ -101,7 +104,7 @@ module.exports = [
```

```js
module.exports = () => [
export default () => [
{
name: 'Pudge',
instagram: 'https://instagram.com/pudgethecorgi/',
Expand All @@ -110,20 +113,20 @@ module.exports = () => [
```

```js
module.exports = async () => [
export default async () => [
{
name: 'Pudge',
instagram: 'https://instagram.com/pudgethecorgi/',
},
];
```

The final example above is the most interesting one - `async` functions are supported! This means you can write code to hit API endpoints, or do other asynchronous work, and `quaff` will wait for those to resolve as it prepares the data object it returns.
The final example above is the most interesting one - `async` functions also work! This means you can write code to hit API endpoints, or do other asynchronous work, and `quaff` will wait for those to resolve.

```js
const fetch = require('node-fetch');
import fetch from 'node-fetch';

module.exports = async () => {
export default async () => {
const res = await fetch('https://my-cool-api/');
const data = await res.json();

Expand All @@ -135,9 +138,9 @@ module.exports = async () => {
Don't have a `Promise` to do async work with? Working with a callback interface? Just wrap it in one!

```js
const apiHelper = require('my-callback-api');
import {apiHelper } from 'my-callback-api';

module.exports = () => {
export default () => {
return new Promise((resolve, reject) => {
apiHelper('people', (err, data) => {
if (err) return reject(err);
Expand Down

0 comments on commit b1cabd9

Please sign in to comment.