@metalsmith/collections 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+### Changelog
+
+All notable changes to this project will be documented in this file. Dates are displayed in UTC.
+
+Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
+
+#### [v1.1.0](https://github.com/metalsmith/collections/compare/v1.0.0...v1.1.0)
+
+- Added standardised code formatting and QA [`#86`](https://github.com/metalsmith/collections/pull/86)
+- Updated History with v1 PRs [`#85`](https://github.com/metalsmith/collections/pull/85)
+- Added better JSDoc types, return named plugin function [`3aa3443`](https://github.com/metalsmith/collections/commit/3aa3443802c2f814c90cf39c7b43de8fc3d3ff13)
+- Updated multimatch to 4.0.0, debug to 4.3.3 [`71d6f65`](https://github.com/metalsmith/collections/commit/71d6f65b9ec5572196e17dfebf5cff2361853f9d)
+
+<!-- auto-changelog-above -->
+
+# [1.0.0][] / 2018-10-17
+
+- Fixed API and merged many PRs
+- Allow metadata-based filtering with `filterBy` option
+- removed unused module
+- Add documentation: `sortBy` can be a function
+- display only matching files when debugging
+- assign data.path where undefined
+- Clear collections
+- Added multiple collections syntax to Readme.md
+
+#### [0.7.0][] / 2015-02-07
+
+- Allow front matter and pattern collections.
+- Added the ability to limit the size of a collection
+- Allow collections through metadata alone
+- add ability to disable next/previous references
+
+#### [0.6.0][] / 2014-08-12
+
+- Added the ability to set multiple collections
+
+#### [0.5.1][] / 2014-08-05
+
+- Fixed bug with require statement
+
+#### [0.5.0][] / 2014-08-04
+
+- Added the ability to add metadata to collections
+
+#### [0.4.1][] - May 4, 2014
+
+- fix empty collections
+
+#### [0.4.0][] - March 25, 2014
+
+- add option for `sortBy` to be a sorting function
+
+#### [0.3.0][] - March 24, 2014
+
+- add `collection` property to each file for pattern matches
+
+#### [0.2.0][] - March 20, 2014
+
+- add collections dictionary to global metadata
+
+#### [0.1.0][] - March 6, 2014
+
+- add matching by pattern
+- add shorthand for pattern matching
+- add previous and next references
+
+#### [0.0.3][] - February 6, 2014
+
+- add debug statements
+- swap to `extend` from `defaults` to avoid cloning
+
+#### [0.0.2][] - February 6, 2014
+
+- swap to `merge` to not act on clones
+
+#### [0.0.1][] - February 5, 2014
+
+:sparkles:

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2021 webketje
+Copyright (c) 2014-2021 Segment
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# @metalsmith/collections
+
+A [Metalsmith](https://github.com/metalsmith/metalsmith) plugin that lets you group files together into an ordered collection, like blog posts. That way you can loop over them to generate an index, or add 'next' and 'previous' links between them.
+
+[![metalsmith: core plugin][metalsmith-badge]][metalsmith-url]
+[![npm version][npm-badge]][npm-url]
+[![ci: build][ci-badge]][ci-url]
+[![code coverage][codecov-badge]][codecov-url]
+[![license: MIT][license-badge]][license-url]
+
+## Features
+
+- can match files by `collection` metadata
+- can match files by pattern
+- can limit the number of files in a collection
+- can filter files in a collection based on metadata
+- adds collections to global metadata
+- adds `next` and `previous` references to each file in the collection
+
+## Installation
+
+NPM:
+
+```
+npm install @metalsmith/collections
+```
+
+Yarn:
+
+```
+yarn add @metalsmith/collections
+```
+
+## Usage
+
+There are two ways to create collections (they can be used together):
+
+- **by pattern** - this is just passing a globbing pattern that will group any files that match into the same collection. The passed pattern can be a single pattern (as a string) or an array of globing patterns. For more information read the [multimatch patterns documentation](https://www.npmjs.com/package/multimatch#how-multiple-patterns-work).
+- **by metadata** - this is adding a specific `collection` metadata field to each item that you want to add to a collection.
+
+The simplest way to create a collection is to use a pattern to match the files you want to group together:
+
+```js
+const collections = require('@metalsmith/collections')
+
+metalsmith.use(
+  collections({
+    articles: '*.md'
+  })
+)
+```
+
+Which is just a shorthand. You could also add additional options:
+
+```js
+metalsmith.use(
+  collections({
+    articles: {
+      pattern: '*.md',
+      sortBy: 'date',
+      reverse: true
+    }
+  })
+)
+```
+
+But you can also match based on a `collection` property in each file's metadata by omitting a pattern, and adding the property to your files:
+
+```js
+metalsmith.use(
+  collections({
+    articles: {
+      sortBy: 'date',
+      reverse: true
+    }
+  })
+)
+```
+
+```markdown
+---
+title: My Article
+collection: articles
+date: 2021-12-01
+---
+
+My article contents...
+```
+
+Multiple collections can also be assigned per file:
+
+```markdown
+---
+title: My Article
+collection:
+  - articles
+  - news
+date: 2021-12-01
+---
+
+My article contents...
+```
+
+All of the files with a matching `collection` will be added to an array that is exposed as a key of the same name on the global Metalsmith `metadata`.
+You can omit passing any options to the plugin when matching based on a `collection` property.
+
+Adds a `path` property to the collection item's data which contains the file path of the generated file. For example, this can be used in mustache templates to create links:
+
+```html
+<h1><a href="/{{ path }}">{{ title }}</a></h1>
+```
+
+The sorting method can be overridden with a custom function in order to sort the files in any order you prefer. For instance, this function sorts the "subpages" collection by a numerical "index" property but places unindexed items last.
+
+```js
+metalsmith.use(
+  collections({
+    subpages: {
+      sortBy: function(a, b) {
+        let aNum, bNum
+
+        aNum = +a.index
+        bNum = +b.index
+
+        // Test for NaN
+        if (aNum != aNum && bNum != bNum) return 0
+        if (aNum != aNum) return 1
+        if (bNum != bNum) return -1
+
+        // Normal comparison, want lower numbers first
+        if (aNum > bNum) return 1
+        if (bNum > aNum) return -1
+        return 0
+      }
+    }
+  })
+)
+```
+
+The `filterBy` function is passed a single argument which corresponds to each file's metadata. You can use the metadata to perform comparisons or carry out other decision-making logic. If the function you supply evaluates to `true`, the file will be added to the collection. If it evaluates to `false`, the file will not be added.
+
+### Collection Metadata
+
+Additional metadata can be added to the collection object.
+
+```js
+metalsmith.use(
+  collections({
+    articles: {
+      sortBy: 'date',
+      reverse: true,
+      metadata: {
+        name: 'Articles',
+        description: 'The Articles listed here...'
+      }
+    }
+  })
+)
+```
+
+Collection metadata can also be assigned from a `json` or `yaml` file.
+
+```js
+metalsmith.use(
+  collections({
+    articles: {
+      sortBy: 'date',
+      reverse: true,
+      metadata: 'path/to/file.json'
+    }
+  })
+)
+```
+
+On each collection definition, it's possible to add a `limit` option so that the
+collection length is not higher than the given limit:
+
+```js
+metalsmith.use(
+  collections({
+    lastArticles: {
+      sortBy: 'date',
+      limit: 10
+    }
+  })
+)
+```
+
+By adding `refer: false` to your options, it will skip adding the "next" and
+"previous" links to your articles.
+
+```js
+metalsmith.use(
+  collections({
+    articles: {
+      refer: false
+    }
+  })
+)
+```
+
+### Debug
+
+To log debug output, set the `DEBUG` environment variable to `@metalsmith/collections`:
+
+Linux/Mac:
+
+```sh
+DEBUG=@metalsmith/collections
+```
+
+Windows:
+
+```cmd
+set "DEBUG=@metalsmith/collections"
+```
+
+## CLI Usage
+
+Add the `@metalsmith/collections` key to your `metalsmith.json` `plugins` key:
+
+```json
+{
+  "plugins": [
+    {
+      "@metalsmith/collections": {
+        "articles": {
+          "sortBy": "date",
+          "reverse": true
+        }
+      }
+    }
+  ]
+}
+```
+
+## License
+
+[MIT](LICENSE)
+
+[npm-badge]: https://img.shields.io/npm/v/@metalsmith/collections.svg
+[npm-url]: https://www.npmjs.com/package/@metalsmith/collections
+[ci-badge]: https://app.travis-ci.com/github/metalsmith/collections.svg?branch=master
+[ci-url]: https://app.travis-ci.com/github/metalsmith/collections
+[metalsmith-badge]: https://img.shields.io/badge/metalsmith-plugin-green.svg?longCache=true
+[metalsmith-url]: http://metalsmith.io
+[codecov-badge]: https://img.shields.io/coveralls/github/metalsmith/collections
+[codecov-url]: https://coveralls.io/github/metalsmith/collections
+[license-badge]: https://img.shields.io/github/license/metalsmith/collections
+[license-url]: LICENSE

package/lib/index.js

@@ -0,0 +1,236 @@
+var debug = require('debug')('@metalsmith/collections')
+var multimatch = require('multimatch')
+var unique = require('uniq')
+var loadMetadata = require('read-metadata').sync
+
+/**
+ * Expose `plugin`.
+ */
+
+module.exports = plugin
+
+/**
+ * @typedef {Object} CollectionConfig
+ * @property {String|String[]} pattern - One or more glob patterns to match files to a collection
+ * @property {'date'|Function} sortBy
+ * @property {Boolean} reverse - Whether to invert the sorting function results (asc/descending)
+ * @property {Function} filterBy - A function that gets a `Metalsmith.File` as first argument and returns `true` for every file to include in the collection
+ * @property {Object} metadata - An object with metadata to attach to the collection
+ */
+
+/**
+ * Metalsmith plugin that adds `collections` of files to the global
+ * metadata as a sorted array.
+ *
+ * @param {Object.<String,CollectionConfig|String>} opts
+ * @return {import('metalsmith').Plugin}
+ */
+
+function plugin(opts) {
+  opts = normalize(opts)
+  var keys = Object.keys(opts)
+  var match = matcher(opts)
+
+  return function collections(files, metalsmith, done) {
+    var metadata = metalsmith.metadata()
+
+    /**
+     * Clear collections (to prevent multiple additions of the same file)
+     */
+
+    keys.forEach(function(key) {
+      metadata[key] = []
+    })
+
+    /**
+     * Clear collections (to prevent multiple additions of the same file when running via metalsmith-browser-sync)
+     */
+
+    keys.forEach(function(key) {
+      metadata[key] = []
+    })
+
+    /**
+     * Find the files in each collection.
+     */
+
+    Object.keys(files).forEach(function(file) {
+      var data = files[file]
+
+      data.path = data.path || file
+
+      const matches = match(file, data)
+      if (matches.length) {
+        debug('processing file: %s', file)
+
+        matches.forEach(function(key) {
+          if (key && keys.indexOf(key) < 0) {
+            opts[key] = {}
+            keys.push(key)
+          }
+
+          metadata[key] = metadata[key] || []
+          // Check if the user supplied a filter function. If so, pass the file metadata to it and
+          // only add files that pass the filter test.
+          if (typeof opts[key].filterBy == 'function') {
+            var filterFunc = opts[key].filterBy
+            if (filterFunc(data)) {
+              metadata[key].push(data)
+            }
+          } else {
+            // If no filter function is provided, add every file to the collection.
+            metadata[key].push(data)
+          }
+        })
+      }
+    })
+
+    /**
+     * Ensure that a default empty collection exists.
+     */
+
+    keys.forEach(function(key) {
+      metadata[key] = metadata[key] || []
+    })
+
+    /**
+     * Sort the collections.
+     */
+
+    keys.forEach(function(key) {
+      debug('sorting collection: %s', key)
+      var settings = opts[key]
+      var sort = settings.sortBy || 'date'
+      var col = metadata[key]
+
+      if ('function' == typeof sort) {
+        col.sort(sort)
+      } else {
+        col.sort(function(a, b) {
+          a = a[sort]
+          b = b[sort]
+          if (!a && !b) return 0
+          if (!a) return -1
+          if (!b) return 1
+          if (b > a) return -1
+          if (a > b) return 1
+          return 0
+        })
+      }
+
+      if (settings.reverse) col.reverse()
+    })
+
+    /**
+     * Add `next` and `previous` references and apply the `limit` option
+     */
+
+    keys.forEach(function(key) {
+      debug('referencing collection: %s', key)
+      var settings = opts[key]
+      var col = metadata[key]
+      var last = col.length - 1
+      if (opts[key].limit && opts[key].limit < col.length) {
+        col = metadata[key] = col.slice(0, opts[key].limit)
+        last = opts[key].limit - 1
+      }
+      if (settings.refer === false) return
+      col.forEach(function(file, i) {
+        if (0 != i) file.previous = col[i - 1]
+        if (last != i) file.next = col[i + 1]
+      })
+    })
+
+    /**
+     * Add collection metadata
+     */
+
+    keys.forEach(function(key) {
+      debug('adding metadata: %s', key)
+      var settings = opts[key]
+      var col = metadata[key]
+      col.metadata = typeof settings.metadata === 'string' ? loadMetadata(settings.metadata) : settings.metadata
+    })
+
+    /**
+     * Add them grouped together to the global metadata.
+     */
+
+    metadata.collections = {}
+    keys.forEach(function(key) {
+      return (metadata.collections[key] = metadata[key])
+    })
+
+    done()
+  }
+}
+
+/**
+ * Normalize an `options` dictionary.
+ *
+ * @param {Object.<string,CollectionConfig>} options
+ */
+
+function normalize(options) {
+  options = options || {}
+
+  for (var key in options) {
+    var val = options[key]
+    if ('string' == typeof val) options[key] = { pattern: val }
+    if (val instanceof Array) options[key] = { pattern: val }
+  }
+
+  return options
+}
+
+/**
+ * Generate a matching function for a given set of `collections`.
+ *
+ * @param {Object.<String, CollectionConfig>} collections
+ * @return {Function}
+ */
+
+function matcher(cols) {
+  var keys = Object.keys(cols)
+  var matchers = {}
+
+  keys.forEach(function(key) {
+    var opts = cols[key]
+    if (!opts.pattern) {
+      return
+    }
+    matchers[key] = {
+      match: function(file) {
+        return multimatch(file, opts.pattern)
+      }
+    }
+  })
+
+  return function(file, data) {
+    var matches = []
+
+    if (data.collection) {
+      var collection = data.collection
+      if (!Array.isArray(collection)) {
+        collection = [collection]
+      }
+      collection.forEach(function(key) {
+        matches.push(key)
+
+        if (key && keys.indexOf(key) < 0) {
+          debug('adding new collection through metadata: %s', key)
+        }
+      })
+    }
+
+    for (var key in matchers) {
+      var m = matchers[key]
+      if (m.match(file).length) {
+        matches.push(key)
+      }
+    }
+
+    data.collection = unique(matches)
+    return data.collection
+  }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@metalsmith/collections",
+  "description": "A Metalsmith plugin that adds collections of files to the global metadata.",
+  "keywords": [
+    "collections",
+    "metalsmith",
+    "metalsmith-plugin",
+    "static-site"
+  ],
+  "homepage": "https://github.com/metalsmith/collections#readme",
+  "bugs": {
+    "url": "https://github.com/metalsmith/collections/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/metalsmith/collections.git"
+  },
+  "version": "1.1.0",
+  "license": "MIT",
+  "main": "lib/index.js",
+  "dependencies": {
+    "debug": "^4.3.3",
+    "extend": "^3.0.0",
+    "multimatch": "^4.0.0",
+    "read-metadata": "^1.0.0",
+    "uniq": "^1.0.1"
+  },
+  "devDependencies": {
+    "auto-changelog": "^2.3.0",
+    "coveralls": "^3.1.1",
+    "eslint": "^8.4.1",
+    "eslint-config-prettier": "^8.3.0",
+    "metalsmith": "^2.3.0",
+    "mocha": "^7.2.0",
+    "nodemon": "^1.18.4",
+    "nyc": "^15.1.0",
+    "prettier": "^1.19.1",
+    "release-it": "^14.11.8"
+  },
+  "directories": {
+    "lib": "lib",
+    "test": "test"
+  },
+  "files": [
+    "lib/*"
+  ],
+  "scripts": {
+    "changelog": "auto-changelog -u --starting-date 2021-12-01 --sort-commits date-desc --commit-limit false --ignore-commit-pattern '(dev|Release|Merge)'",
+    "test": "nyc mocha",
+    "coverage": "nyc report --reporter=text-lcov > ./coverage.info",
+    "coveralls": "npm run coverage && cat ./coverage.info | coveralls",
+    "format": "prettier --write \"**/*.{yml,md,js,json}\"",
+    "lint": "eslint --cache --fix-dry-run .",
+    "dev": "nodemon --exec 'npm test'",
+    "release": "release-it ."
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "metalsmith": "^2.3.0"
+  },
+  "engines": {
+    "node": ">=8"
+  }
+}