ext-essentials

Replaces your repetitive read/write and serialize/deserialize boilerplate code with intuitive extension-based conventions. Treat files like data, and let ext-essentials handle the rest!

Usage

API

load(file[, options], callback)

• file <string>
• options (see options)
• callback <Function>
  • err <Error>
  • data (see data)

Use load to read a file from the file system, deserialize it according to its extensions, and return the data represented inside.

const ee = require('ext-essentials');
ee.load('data.json.gz', (err, data) => {
  // data has been read, unzipped, parsed, and ready for use
  console.log(data['hello']);
});

save(file, data[, options], callback)

• file <string>
• data (see data)
• options (see options)
• callback <Function>
  • err <Error>

Use save to serialize data according to given extensions, and write the serialized representation to the file system.

const ee = require('ext-essentials');
ee.save('data.json.gz', { hello: 'world' }, err => {
  // data has been stringified, g-zipped, and written to disk
});

edit(file, mutator[, options], callback)

• file <string>
• mutator <Function>
  • data (see data)
• options (see options)
• callback <Function>
  • err <Error>

Use edit to load a file from the file system, mutate the data it represents, the save that changed data back, all in one single step.

const ee = require('ext-essentials');
ee.edit(
  'data.json.gz',
  data => {
    data.hello += '!';
    return data;
  },
  err => {
    // assuming data had a `hello` property, we've updated that value
  }
);

deserialize(file, buffer[, options], callback)

• file <string>
• buffer <Buffer>
• options (see options)
• callback <Function>
  • err <Error>
  • data (see data)

Use deserialize to deserialize data according to given extensions, and return the data represented inside. Useful for when you have a buffer and file name, but the data doesn't live in the file system.

const ee = require('ext-essentials');
ee.deserialize('data.json.gz', buffer, (err, data) => {
  // data has been unzipped, parsed, and ready for use
  console.log(data['hello']);
});

serialize(file, data[, options], callback)

• file <string>
• data (see data)
• options (see options)
• callback <Function>
  • err <Error>
  • buffer <Buffer>

Use serialize to serialize data according to given extensions. Useful for when you want a buffer, but the data won't be immediately written to the file system.

const ee = require('ext-essentials');
ee.serialize('data.json.gz', { hello: 'world' }, (buffer, err) => {
  // data has been stringified and g-zipped
  console.log(buffer.toString('base64'));
});

alias(replace, as)

• replace <string> | <RegExp>
• as <string> | <Function>

Use alias to define your own extensions to use handlers for other known extensions. Any operation called after an alias is assigned will check the given extensions for applicable aliases.

NB: When passing in a RegExp to replace, make sure to capture a full extension or set of extensions, including the preceding dot. When passing in a function to alias as, make sure its return value includes the preceding dot. When passing in only strings, a preceding dot is added if missing.

const ee = require('ext-essentials');
ee.alias('.dat', '.json.gz');
// .dat will be treated as gzipped json

const ee = require('ext-essentials');
ee.alias(/\.gz\d+\b/i, match => {
  const n = parseInt(match.substring(3));
  return '.gz'.repeat(n);
});
// .gz3 will be treated as a file gzipped three times in a row,
// for when you want to make super-duper sure it's compressed

Data

The type of data these functions accept and return depends on which handlers are used and in which order. Handlers such as the JSON and YAML handlers accept most kinds of input. Serializing straight to the Gzip or Zip handlers, for example, have other restrictions and expectations. For more info, see the handlers section.

Options

• options <Object>
  • alias <string> Default: undefined
  • handler <Object>

const ee = require('ext-essentials');
const options = {
  alias: 'data.json.gz',
  json: { space: 2 },
  gz: { level: 9 }
};
ee.save('data.dat', { hello: 'world' }, options, err => {
  // data has been stringified, g-zipped, and written to disk
});

Handlers

text-handler

• Requires: n/a (native)
• Handles: .txt
• Serializer/Deserializer: Buffer

json-handler

• Requires: n/a (native)
• Handles: .json
• Serializer: JSON.stringify
  • Options: { replacer, space }
• Deserializer: JSON.parse
  • Options: { reviver }

gzip-handler

• Requires: n/a (native)
• Handles: .gz, .gzip
• Serializer: zlib.gzip (options)
• Deserializer: zlib.unzip (options)

yaml-handler

• Requires: js-yaml
• Handles: .yml, .yaml
• Serializer: jsYaml.safeDump
• Deserializer: jsYaml.safeLoad

zip-handler

• Requires: jszip
• Handles: .zip

This handler serializes and deserializes multi-file zip archives. It loads the files as an object, with each key being the path of an archived file, and its value being the data loaded and deserialized by its extensions. It saves in the opposite fashion.

TODO

• XML handler
• CSV handler
• Positional (array-based) options