Git Product home page Git Product logo

configuration's Introduction

Configuration

Performant and feature rich library for managing configurations/settings.

Features

This library has been modeled after VSCode's settings system, and it can be used for implementing a similarly powerful system in your app.

  • Performant: it's designed to be extremely fast.
  • Providers: a provider reads and writes the actual data, many are built-in (memory, json, local storage etc.) and others can be written easily.
  • Universal: it works in the browser too, just use a suitable provider.
  • Scopes: a single configuration instance can have multiple providers, so for example a global + local setup can be implemented easily.
  • Filtering: an arbitrary filter function can be provided, for example to make sure the settings are filtered by a schema.
  • Path props: path props (e.g. foo.bar) are supported for retrieving/setting/deleting entries.
  • Flat objects: flat objects (e.g. { 'foo.bar': true, 'foo.baz': false }) are supported transparently too.

Install

npm install --save configuration

Usage

The following providers are built-in:

import ProviderAbstract from 'configuration/abstract'; // The most basic abstract provider
import ProviderAbstractFile from 'configuration/abstract-file'; // The most basic abstract file provider
import ProviderAbstractJSON from 'configuration/abstract-json'; // The most basic abstract JSON-backed file provider
import ProviderFile from 'configuration/file'; // A provider that reads/writes to a file
import ProviderJSON from 'configuration/json'; // A provider that reads/writes to a JSON file
import ProviderMemory from 'configuration/memory'; // A provider that reads/writes to memory
import ProviderStorage from 'configuration/storage'; // A provider that reads/writes to a general web storage object
import ProviderLocalStorage from 'configuration/local-storage'; // A provider that reads/writes to localStorage
import ProviderSessionStorage from 'configuration/session-storage'; // A provider that reads/writes to sessionStorage

This is how you'd create a multi-tier settings sytem:

import Configuration from 'configuration';
import ProviderMemory from 'configuration/memory';
import ProviderJSON from 'configuration/json';

// Let's initiate the configuration instance

const Window = new ProviderMemory ({ // A window-level tier, that overrides every other tier
  scope: 'window', // The name of the scope for this provider
  defaults: {}, // The default settings object for this provider
  defaultsRaw: '{\n\t// Write window-level settings here\n}' // The default settings object for this provider as a string
});

const Local = new ProviderJSON ({ // A local-level tier, that overrides every other tier except for "window"
  scope: 'local', // The name of the scope for this provider
  path: './myapp/local.json', // Path where to persist data
  watching: true, // Whether to watch the file for changes too or not
  defaults: {}, // The default settings object for this provider
  defaultsRaw: '{\n\t// Write local-level settings here\n}' // The default settings object for this provider as a string
});

const Global = new ProviderJSON ({ // A global-level tier, that overrides only the "defaults" tier
  scope: 'global', // The name of the scope for this provider
  path: '/Users/fabio/.config/myapp/global.json', // Path where to persist data
  watching: true, // Whether to watch the file for changes too or not
  defaults: {}, // The default settings object for this provider
  defaultsRaw: '{\n\t// Write global-level settings here\n}' // The default settings object for this provider as a string
});

const configuration = new Configuration ({
  providers: [Window, Local, Global], // List of custom providers used, ordered by priority
  defaults: { // The default settings object for the implicit "defaults" scope
    some: {
      default: {
        settings: true
      }
    }
  },
  filter: settings => { // Custom optional function for manipulating the raw settings object
    // Optionally filter down the passed "settings" object...
    return settings;
  }
});

// Using the #get method

configuration.get (); // Get the entire merged object
configuration.get ( '*' ); // Get the entire object for each scope
configuration.get ( '*', 'some.path' ); // Get the value at "some.path" for all scopes
configuration.get ( 'local', 'some.path' ); // Get the value at "some.path" from the "local" scope
configuration.get ( 'some.path' ); // Get the value at "some.path" from the first scope that has a value for it

// Using the #has method

configuration.has ( '*', 'some.path' ); // Check if a value exists at "some.path" in all scopes
configuration.has ( 'local', 'some.path' ); // Check if a value exists at "some.path" in the "local" scope
configuration.has ( 'some.path' ); // Check if a value exists at "some.path" in at least one scope

// Using the #remove method

configuration.remove ( '*', 'some.path' ); // Remove the "some.path" key from all scopes
configuration.remove ( 'local', 'some.path' ); // Remove the "some.path" key from the "local" scope
configuration.remove ( 'some.path' ); // Remove the "some.path" key from any scope that has a value for it

// Using the #reset method

configuration.reset (); // Reset the value of every scope to its default one
configuration.reset ( 'local' ); // Reset the value of the "local" scope

// Using the #set method

configuration.set ( '*', 'some.path', 123 ); // Set "123" as the value at "some.path" for every scope
configuration.set ( 'local', 'some.path', 123 ); // Set "123" as the value at "some.path" for the "local" scope
configuration.set ( 'some.path', 123 ); // Set "123" as the value at "some.path" in the first scope that has a value for that key

// Using the #update method

configuration.update ( '*', { something: {} } ); // Replacing the entire settings object for every scope
configuration.update ( 'local', { something: {} } ); // Replacing the entire settings object for the "local" scope

// Listening for changes

configuration.onChange ( () => {
  // Something changed anywhere in the object, but we don't know exactly where, but this makes this callback the cheapest
});

configuration.onChange ( 'local', 'some.path', ( value, valuePrev ) => {
  // The value of "some.path" in the "local" scope changed
});

configuration.onChange ( 'some.path', ( value, valuePrev ) => {
  // The value of "some.path" in the first scope that provides a value for it changed
});

// Let's dispose of the configuration object, stopping filesystem watching for example

configuration.dispose ();

License

MIT © Fabio Spampinato

configuration's People

Contributors

fabiospampinato avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

Forkers

odnodn

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.