@static-pages/fs
v3.0.1
Published
Provides helpers for the static pages generator to read from and write to an arbitary filesystem.
Downloads
9
Readme
Static Pages / FS
This package provides utilities for reading and writing documents from an abstract filesystem.
Use read() to create an async iterable collection of documents, and write() to handle rendering and storing.
This project is structured as a toolkit split to many packages, published under the @static-pages namespace on NPM. In most cases you should not use this core package directly, but the @static-pages/starter is a good point to begin with.
Usage
import staticPages from '@static-pages/core';
import { read, write } from '@static-pages/fs/node';
staticPages({
from: read({
cwd: 'pages',
pattern: '**/*.md',
}),
controller(data) {
data.now = new Date().toJSON();
return data;
},
to: write({
render({ title, content, now }) {
return `<html><body><h1>${title}</h1><p>${content}</p><p>generated: ${now}</p></body></html>`;
},
})
})
.catch(error => {
console.error('Error:', error);
console.error(error.stack);
});Documentation
For detailed information, visit the project page.
read(options: ReadOptions<T>): AsyncIterable<T>
interface ReadOptions<T> {
// Filesystem implementation that handles reads and writes.
fs: Filesystem;
// Current working directory.
cwd?: string;
// File patterns to include.
pattern?: string | string[];
// File patterns to exclude.
ignore?: string | string[];
// Callback to parse raw contents into an object.
// default: see About the default `parse` function
parse?(content: Uint8Array | string, filename: string): T | Promise<T>;
// Handler function called on error.
// default: (err) => { throw err; }
onError?(error: unknown): void | Promise<void>;
}write(options: WriteOptions<T>): void
interface WriteOptions<T> {
// Filesystem implementation that handles reads and writes.
fs: Filesystem;
// Current working directory.
cwd?: string;
// Callback that retrieves the filename (URL) of a page.
// default: (d) => d.url + '.html'
name?(data: T): string | Promise<string>;
// Callback that renders the document into a page.
// default: (d) => d.content
render?(data: T): Uint8Array | string | Promise<Uint8Array | string>;
// Handler function called on error.
// default: (err) => { throw err; }
onError?(error: unknown): void | Promise<void>;
}Filesystem interface
You can provide a Filesystem implementation for both read() and write()
helpers. This interface is a minimal subset of the NodeJS FS API
so you can simply plug the node:fs package in.
interface Filesystem {
stat(
path: string | URL,
callback: (err: Error | null, stats: { isFile(): boolean; isDirectory(): boolean; }) => void
): void;
readdir(
path: string | URL,
options: {
encoding: 'utf8';
withFileTypes: false;
recursive: boolean;
},
callback: (err: Error | null, files: string[]) => void,
): void;
mkdir(
path: string | URL,
options: {
recursive: true;
},
callback: (err: Error | null, path?: string) => void
): void;
readFile(
path: string | URL,
callback: (err: Error | null, data: Uint8Array) => void
): void;
writeFile(
path: string | URL,
data: string | Uint8Array,
callback: (err: Error | null) => void
): void;
}createFilesystem(files: Record<string, FileContent>): Filesystem
This helper is designed to easily create in-memory unix-like filesystems. The
files parameter is an object whose keys are the full paths of the files and
whose values are the file contents (see the FileContent type below).
type FileContent = string | {
encoding?: 'text' | 'base64';
content: string;
};When FileContent is a string, it should be a plain text file. When it's an
object, it can also contain binary files by setting encoding to base64
(defaults to text).
Paths are always normalized to begin with a forward slash. Every slashes are normalized to forward slashes.
About the default parse function
When using the default parser, a file type will be guessed by the file extension.
These could be json, yaml, yml, md or markdown.
jsonwill be parsed withJSON.parseyamlandymlwill be parsed with theyamlpackagemdandmarkdownwill be parsed with thegray-matterpackage
When the document is missing an url property this function will assign the
filename without extension to it.
Importing @static-pages/fs/node
The @static-pages/fs/node export provides the same functions as the
@static-pages/fs with the added benefit of setting the default value of the
fs property to the node:fs package.
This way it is easier to use these utility functions from a node script and also easier to bundle them for browsers.
Missing a feature?
Create an issue describing your needs! If it fits the scope of the project I will implement it.