Filer

Provides an API for accessing parsed file content in a collection-like file structure.

• Installation
• Usage
• Development
• License

Installation

npm i @cloudcannon/filer

Usage

JavaScript-based SSGs often have no standard approach to reading content from local files. This package aims to address this.

This package assumes a file structure where files are grouped into top-level folders called collections. This mimics the file structure seen in a number of SSGs with standard approaches to reading local files.

Here's an example file tree with three collections inside a content folder:

content
├── pages
│   ├── about.md
│   └── index.md
├── posts
│   ├── my-first-post.md
│   ├── another-post.md
│   └── my-last-post-ever.md
└── authors
    ├── jane.md
    └── john.md

At the moment, this is limited to Markdown files only.

Setup

Where these functions are called depends on the SSG you are using. This package simply wraps file reading and parsing into a consistent API.

import Filer from '@cloudcannon/filer';
const filer = new Filer({
  path: 'content' // The base path containing your collection folders
});

Getting all parsed items in collection

// Can be called with no options
await filer.getItems('posts');

await filer.getItems('posts', {
  excerpt: true, // Produces excerpts/summaries from the first paragraph of content for each item
  sortKey: 'date', // Sorts items from this parsed data
  sortReverse: true // Reverses the sorted items (defaults to false)
});

Getting filtered items in a collection

You can provide a filter function to the options object.

This function should return a boolean value. The item will be returned if filter returns true.

await filer.getItems('posts', {
  filter: (item) => { // checks each item in 'posts' before returning
    return item.data.tags.includes('category');
  }
});

Getting paginated items in collection

await filer.getPaginatedItems('posts', {
  sortKey: 'date', // Accepts all valid options for getItems()
  pagination: { // Requires a 'pagination' object in options
    size: 10, // Number of items per page
    page: 3 // The page number
  }
});

If the page requested is greater than the number of pages, will return the last page.

If the size requested is greater than the number of items, will return one page with all items.

This function returns data in the following format:

{
  data: [], // An array containing the paginated files (for this page).
  start: 20, // The index of the first item on this page (starting at 0)
  end: 29, // The index of the first item on this page (starting at 0)
  total: 42, // The total number of items in this collection
  currentPage: 3, // The page number being returned
  size: 10, // The number of items on this page
  lastPage: 5, // The number of the last page (equal to the number of pages)
  prevPage: 2, // The number of the previous page (undefined if current page is first page)
  nextPage: 4 // The number of the next page (undefined if current page is last page)
};

Getting one parsed item in collection

await filer.getItem('my-first-post.md', { folder: 'posts' });

await filer.getItem('my-first-post.md', {
  folder: 'posts', // Reads the file from this folder/collection
  excerpt: true // Produces excerpts/summaries from the first paragraph of content
});

Listing slugs for a collection

This is useful for providing Next.js with static paths.

await filer.listItemSlugs('posts');

Development

Install dependencies:

$ npm i

Run tests:

$ npm test
$ npm run test:watch
$ npm run test:coverage

Lint code:

$ npm run lint

License

MIT