What it solves

The Node On Disk library is a very simple abstraction layer that allows for files to exist on disk for storage of data but used as a data object within Node. This is meant mostly for configuration files and simple look ups, but adds in nicety to ensure caching of data as needed. Because this data is stored in memory (unless )

How it works (let's make some sausage)

Ondisk first reads the file and changes it to JSON. Once it is a JavaScript usable object, it will return an object with access to that data. It is possible, of course, to use require("my.json") to get access to the object version of the JSON, but this gives further possibilities. Much like requiring a json object, ondisk is smart enough to change it's behavior based on the JSON object being an array or simple object.

All data presented is saved in the global namespace.

Usage

ondisk (source:(String|Function), options: Object)

• source
  • string: Assumes a file path. When the string does not include an extension, ondisk will assume .json. If the string is only a filename (no directory separators), ondisk will search each directory listed in the ONDISK_DIRECTORY (semicolon delimited) and ONDISK_STORE environment variables in order. Full or relative paths are respected as-provided.
  • function: Allows for use of a function to receive the file. Assumes the function will return a string which can be converted to JSON. Mostly useful if the resource is remote and there is a desire for live data.
• options
  • direct (default:false)- The object that is created will allow for access to the keys.
    • For single JSON objects, the keys will be available as at object.key
    • For arrays the object returned will be parseable as an array with all of the typical array functions.
  • lookup (default:true) - Adds the find function to the object. Only usable for lists of repeating objects.
  • mutable - Allows the system to read and write to the object. This makes it a very weak database. Not recommended for the faint of heart.
  • cache (default:static)
    • "static" - The file is loaded only once, and can only be reloaded by calling ondisk again.
    • "never" - The file will always be parsed when a get operation is called. Does not work with direct variable access.
    • 0-9999 This is the length of time in minutes (fractions allowed) you wish the cache to live for. Set to zero is the same as setting to never. When provided, ondisk refreshes the cached object on that cadence so existing references reflect file changes automatically.
  • parseFunction (default:null) - Allows for passing of a function that will change the file contents into a json object.

Examples

For a simple set of key / value pairs such as currency conversion to USD

// ./.data/currencies.json
{
  USD: 1,
  GBP: 1.33
}

const ondisk = require("ondisk");
const currencies = ondisk("./.data/currencies.json", {
  cache: 60,
  direct: true,
});
currencies.get("USD"); // Returns 1
currencies.get("GBP"); // Returns 1.33
currencies.USD; // Returns 1
currencies["GBP"]; // Returns 1.33

This can also be used for settings in a node application.

// ./.data/setting.json
{
  "MAX_TTL":400,
  "SYSTEM_PASSWORD":"awsdhnq239q129812802"
}

const ondisk = require("ondisk");
const settings = ondisk("./.data/setting.json", { cache: 0 });
settings.MAX_TTL; // This comes from {..., MAX_TTL:4, ...}

For an array of objects such a a list of united states and simple data about each

[
  // us-states.json
  {"code":"WI","name":"Wisconsin", "joined":1848},
  {"code":"IL","name":"Illinois", "joined":1818},
  {"code":"MI","name":"Michigan", "joined":1837},
]

const ondisk = require("ondisk");

const usStates = ondisk("us-states.json", { lookup: true });

usStates.getName("MI"); // returns "Michigan";

usStates.getCode("Michigan"); // returns "MI";

usStates.get("IL"); // returns {"code":"IL","name":"Illinois", "joined":1818}.

usStates.find("Winsconsin"); // Returns {"code":"WI","name":"Wisconsin", "joined":1848}

Add your own parser. As long as it returns an array of JSON objects, or a single JSON object, the system should function.

const ondisk = require("ondisk");
const data = ondisk("office_locations.csv", { parseFunction: myCSVParser });
data.get("something");

Errors

Ondisk throws an ONDISK_ERROR when it cannot resolve a source. The message File Not Found indicates the loader exhausted the provided path along with any directories configured via ONDISK_DIRECTORY or ONDISK_STORE.