live-directory

LiveDirectory: Dynamic File Content Manager

Motivation

Implementing your own template/file management system which consistently reads/updates file content can be tedious. LiveDirectory aims to solve that by acting as an automated file content store making a directory truly come alive. Powered by the efficient file watching library chokidar, LiveDirectory can be an efficient solution for fast and iterative web development.

Features

• Simple-to-use API
• Sub-Directory Support
• Asynchronous By Nature
• Instantaneous Hot Reloading
• Memory Efficient
• Supports Windows, Linux & MacOS

Installation

LiveDirectory can be installed using node package manager (npm)

npm i live-directory

Table Of Contents

• LiveDirectory: Dynamic File Content Manager
  • Motivation
  • Features
  • Installation
  • Table Of Contents
  • Examples
    • Serving a basic HTML page
    • Customized Dashboard User Page With Compiled Renderer
  • LiveDirectory
    • Constructor Options
    • LiveDirectory Properties
    • LiveDirectory Methods
  • LiveFile
    • LiveFile Properties
    • LiveFile Methods
  • License

Examples

Below are varios examples that make use of most classes and methods in LiveDirectory. The micromustache template renderer is used in the examples below but you can use any other renderer/framework.

Serving a basic HTML page

const LiveDirectory = require('live-directory');

// Create LiveDirectory instance
const live_templates = new LiveDirectory({
    root_path: './templates/html'
});

// Create server route for dashboard user page
some_server.get('/dashboard/user', (request, response) => {
    // Some processing done here which generates some user_options for rendering page uniquely

    // Retrieve template LiveFile instance
    // Below relative path is translated under the hood to './templates/html/dashboard/user.html'
    let template = live_templates.get('/dashboard/user.html');

    // Send rendered html code in response
    return response.send(template.content);
});

Customized Dashboard User Page With Compiled Renderer

const MicroMustache = require('micromustache');
const LiveDirectory = require('live-directory');

// Create LiveDirectory instance
const live_templates = new LiveDirectory({
    root_path: './templates/html'
});

// Handle 'reload' event from LiveDirectory so we can re-generate a new compiled micromustache instance on each file content update
live_templates.on('file_reload', (file) => {
    // We can attach our own properties to the LiveFile object
    // Using this, we can recompile a micromustache renderer and attach onto LiveFile
    const compiled = MicroMustache.compile(file.content);
    compiled_templates[file.path].render = compiled.render;
});

// Create server route for dashboard user page
some_server.get('/dashboard/user', (request, response) => {
    // Some processing done here which generates some user_options for rendering page uniquely

    // Retrieve template LiveFile instance
    // Below relative path is translated under the hood to './templates/html/dashboard/user.html'
    let template = live_templates.get('/dashboard/user.html');

    // Generate rendered template code
    let html = template.render(user_options);

    // Send rendered html code in response
    return response.send(html);
});

LiveDirectory

Below is a breakdown of the LiveDirectory class generated when creating a new LiveDirectory instance.

Constructor Options

• path [String]: Path to the directory.
  • Example: ./templates/
  • Required for a LiveDirectory Instance.
• ignore [Function]: Ignore/Filter function for deciding which files to load.
  • Example: (String: path) => path.includes('node_modules')
  • Usage: Return true through the function when ignoring a file and vice versa.
• retry [Object]: File content reading retry policy.
  • every [Number]: Delay between retries in milliseconds.
  • max [Number]: Maximum number of retries.

LiveDirectory Properties

Property	Type	Description
path	String	Root directory path.
watcher	FS.Watcher	Underlying Chokidar watcher instance.
tree	Object	Directory tree with heirarchy.
files	Object	All loaded files with their relative paths.

LiveDirectory Methods

• ready(): Returns a Promise which is then resolved once instance is fully ready.
• get(String: path): Returns LiveFile instance for file at specified path.
  • Returns a LiveFile instance or undefined
  • Supported Formats: When root path is /root/var/www/webserver/templates.
    • System Path: /root/var/www/webserver/templates/dashboard/index.html
    • Relative Path: /dashboard/index.html
    • Simple Path: dashboard/index.html
• on(String: type, Function: handler): Binds a handler for LiveDirectory events.
  • Event 'directory_create': Reports newly created directories.
    • handler: (String: path) => {}
  • Event 'directory_destroy': Reports when a directory is deleted.
    • handler: (String: path) => {}
  • Event 'file_reload': Reports when a file is created/is reloaded.
    • handler: (LiveFile: file) => {}
    • See LiveFile documentation for available properties and methods.
  • Event 'file_destroy': Reports when a file is destroyed.
    • handler: (LiveFile: file) => {}
    • See LiveFile documentation for available properties and methods.
  • Event 'file_error': Reports FileSystem errors for a file.
    • handler: (LiveFile: file, Error: error) => {}
    • See LiveFile documentation for available properties and methods.
  • Event 'error': Reports LiveDirectory instance errors.
    • handler: (Error: error) => {}

LiveFile

Below is a breakdown of the LiveFile instance class that represents all files.

LiveFile Properties

Property	Type	Description
path	String	System file path.
extension	String	File extension.
etag	String	Unique etag compatible file hash.
content	String	File text content.
buffer	Buffer	File raw content.
last_update	Number	Last file text content update timestamp in milliseconds

LiveFile Methods

• ready(): Returns a Promise which is resolved once file is ready with initial content.
• reload(): Returns a Promise which is resolved once the File's content is reloaded.

License

MIT