@overlook/plugin-fs

Overlook framework file system plugin

Usage no npm install needed!

<script type="module">
  import overlookPluginFs from 'https://cdn.skypack.dev/@overlook/plugin-fs';
</script>

README

NPM version Build Status Dependency Status Dev dependency Status Greenkeeper badge Coverage Status

Overlook framework file system plugin

Part of the Overlook framework.

Usage

Plugin for access to file system and virtual file system.

File class

Represents a file (either on real file system or virtual file system).

Has properties .path and .content.

For files on real filesystem:

  • .path contains absolute path to the file (using system's path separators i.e. / on POSIX, \ on Windows)
  • .content is undefined.

For virtual files created with [WRITE_FILE]():

  • .path is a pseudo-path - guaranteed to be unique (always using POSIX-style path separators)
  • .content is content of the virtual file (string)

Methods

[GET_FILE_PATH]( file )

Get absolute path for a file.

Method can be extended in Route classes/plugins.

[READ_FILE]( file )

Read contents of a file (either real or virtual) as a string.

[WRITE_FILE]( ext, content )

Write a virual file.

File is recorded in virtual file system. The file's .path is an opaque pseudo-path, guaranteed to be unique. It will have the extension ext.

Returns a File object. The contents of the file can be read with [READ_FILE]().

[CREATE_VIRTUAL_PATH](ext)

Used internally by [WRITE_FILE]() to create pseudo-paths for virtual files.

Can be extended by sub-classes/plugins to alter pseudo-paths created by [WRITE_FILE]().

Properties

[FS_FILES]

The uppermost route using this plugin will have an [FS_FILES] property which is an object holding details of all virtual files. The object is keyed by path, and values are the corresponding File objects.

All nested routes using this plugin will reference this same [FS_FILES] object as held on the uppermost route.

Versioning

This module follows semver. Breaking changes will only be made in major version updates.

All active NodeJS release lines are supported (v10+ at time of writing). After a release line of NodeJS reaches end of life according to Node's LTS schedule, support for that version of Node may be dropped at any time, and this will not be considered a breaking change. Dropping support for a Node version will be made in a minor version update (e.g. 1.2.0 to 1.3.0). If you are using a Node version which is approaching end of life, pin your dependency of this module to patch updates only using tilde (~) e.g. ~1.2.3 to avoid breakages.

Tests

Use npm test to run the tests. Use npm run cover to check coverage.

Changelog

See changelog.md

Issues

If you discover a bug, please raise an issue on Github. https://github.com/overlookjs/plugin-fs/issues

Contribution

Pull requests are very welcome. Please:

  • ensure all tests pass before submitting PR
  • add tests for new features
  • document new functionality/API additions in README
  • do not add an entry to Changelog (Changelog is created when cutting releases)