Goblin Philosophy

  • Coding is fun, so databases must be fun too.

  • Data is the king.

  • Data should be stored in the system as a file when a change happend.

  • Data storage in the system must be hackable.

  • The database can lead or connect your server component

  • Events are great... because we are asynchronous

  • We prefer facts over promises: facts are there, promises maybe yes or not. In fact, we're talking about callbacks.

  • Data is not the only stuff that can be store in a database.

  • We prefer ambush functions over lambda functions. As you know... we're talking about anonymous functions.

Demo

You can run a demo in 4 steps!

  1. Clone this repository
    git clone https://github.com/UlisesGascon/GoblinDB
  2. Enter in the folder
    cd GoblinDB
  3. Install the dependencies
    npm install
  4. Run fear_the_goblin.js
    node fear_the_goblin.js

Documentation

Add it to your Node.js project

  • In your terminal...

    npm install goblindb --save
  • In your file..

    var GDB = require("goblindb");
    
    var goblinDB = GDB();

Reitrieving data

By default Goblin will create an empty json file as database storage, if the file exist it will added to Goblin.

Just for the example, current database status... as you can see is a JSON file:

  • goblin_bd.json:

    {"hello":"world!","array":["aaaa",true,5],"objectData":{"property": 1}}
  • get. Return the information from a key or the whole database

    var GDB = require("goblindb");
    
    var goblinDB = GDB();
    
    console.log(goblinDB.get())
    // {"hello":"world!","array":["aaaa",true,5],"objectData":{"property": 1}}
    
    console.log(goblinDB.get("hello"))
    // {"hello":"world!"}

Saving data

You have many options to save data. As Goblin is a key/value database you need to know what is the key that you want to use/create.

You can storage all the data that you want except functions. Until the next release.

  • set(key, data). Write or replace data to a defined key (optional)

    var GDB = require("goblindb");
    
    var goblinDB = GDB();
    
    // set data in db.admin
    goblinDB.set({"name": "Ulises", "role": "developer"}, "admin");
    
    // set data in root
    goblinDB.set({"hello": "Human...!"});
  • push(data). Write data in a new key (random name added, like MewhnDIutVhm3hulgTaAJj6Utb47GOwe)

    var GDB = require("goblindb");
    
    var goblinDB = GDB();
    
    goblinDB.push({"name": "Ulises", "role": "developer"})
    goblinDB.push(["other-data", true, 123])
    
    console.log(goblinDB.get());
    /* Console:
    { MewhnDIutVhm3hulgTaAJj6Utb47GOwe: { name: 'Ulises', role: 'developer' },
      j3zKjX7WpdTDpRPNVWGE1jPMHEtUPWq6: [ 'other-data', true, 123 ] }
    */
  • update(data, key). Add and modify data to a defined key

    var GDB = require("goblindb");
    
    var goblinDB = GDB();
    
    goblinDB.update({"name": "CodingCarlos", "friends": ["Ulises", "Jose"]}, "admin");

Fun with Events

You can use events in order to react to changes in the database. All the events are managed internally by Goblin inside as hooks.

You can specify the trigger event:

  • add
  • update
  • delete
  • reconfigure
  • change, in any case it will be triggered.

The event will return an object that contains previous data and current data. At the moment the the listeners can be added to the database root, but in the next release it will possible to focus in on or more specific paths

  • on(), Add a new function to be triggered on a specific change.

    var GDB = require("goblindb");
    
    var goblinDB = GDB();
    
    goblinDB.on('change', function(changes){
        console.log("cambio:", changes)
        console.log("====================")
    });
  • off(), Remove a previous record event

    var GDB = require("goblindb");
    
    var goblinDB = GDB();
    
    goblinDB.on('change', function(changes){
        console.log("cambio:", changes)
        console.log("====================")
    });
    
    // more code...
    
    goblinDB.off('change', function(changes){
        console.log("cambio:", changes)
        console.log("====================")
    });

Extra features

Some extra features that maybe can help you.

  • getConfig() & updateConfig, modify/replace/extend configuration.

    var GDB = require("goblindb");
    
    var goblinDB = GDB();
    
    console.log(goblinDB.getConfig())
    // { logPrefix: '[GoblinDB]', file: './goblin_bd.json', recordChanges: true }
    
    goblinDB.updateConfig({ logPrefix: '[GoblinDB-modify]'})
    
    console.log(goblinDB.getConfig())
    // { logPrefix: '[GoblinDB-modify]', file: './goblin_bd.json', recordChanges: true }
  • stopStorage() & startStorage(), enable/disable the storage in disk.

    var GDB = require("goblindb");
    
    var goblinDB = GDB();
    
    goblinDB.stopStorage();
    
    // more code that will not touch be stored in the disk...
    
    goblinDB.startStorage();
    // Now the current GoblinDB will be stored in disk and it will keep doing it

Ambush Functions (Lambda Functions)

You can store also anonymous functions in GoblinDB, we call this functions Ambush.

Once you add Ambush functions to GoblinDB... the system will save them under a .goblin file.

This feature will allow you to bring your functions togther with your data to a new projects.

You can perform few basic operations to ambush functions through Goblin specific methods. They are very similar to regular data manipulation methods.

  • add
  • update
  • remove
  • run
  • details
  • list

All the ambush functions has an specific setup. Internally they are objects with specific methods ans properties.

  • id, this reference must be unique and also a string.
  • description, this will add additional information about the current ambush function, it is an optional property and must be a string.
  • category, this array will help us to filter our ambush functions in the future.
  • action, this is the key feature. This method can be executed from GoblinDB on demand. Only two optional parameters are acepted: arguments (no specific data type) and callback (function).
  • Add a simple ambush function.

    var GDB = require("goblindb");
    
    var goblinDB = GDB();
    
    goblinDB.ambush.add({
    	id: "simple-function",
    	category: ["documentation"],
    	description: "This is a simple function",
    	action: function(){
    		console.log("Hello World");
    	}
    });
    
    goblinDB.ambush.run("simple-function"); //Console -> Hello World
  • Add an ambush function with arguments.

    Note: Only one argument can bre provided by run method. In case that you need more than one argument, please use an array or an object.

    var GDB = require("goblindb");
    
    var goblinDB = GDB();
    
    goblinDB.ambush.add({
    	id: "argument-function",
    	category: ["documentation"],
    	description: "This is an ambush function with arguments",
    	action: function(argument){
    		console.log("Hello", argument);
    	}
    });
    
    goblinDB.ambush.run("argument-function", "World"); //Console -> Hello World
  • Add an ambush function with arguments and callback.

    var GDB = require("goblindb");
    
    var goblinDB = GDB();
    
    goblinDB.ambush.add({
    	id: "callback-function",
    	category: ["documentation"],
    	description: "This is an ambush function with arguments and callback",
    	action: function(argument cb){
    		cb("Hello " + argument);
    	}
    });
    
    goblinDB.ambush.run("callback-function", "World", function(data){
    	console.log("The Callback data:", data);
    }); //Console -> The Callback data: Hello World
  • Remove an ambush function.

    var GDB = require("goblindb");
    
    var goblinDB = GDB();
    
    goblinDB.ambush.add({
    	id: "simple-function",
    	category: ["documentation"],
    	description: "This is a simple function",
    	action: function(){
    		console.log("Hello World");
    	}
    });
    
    goblinDB.ambush.remove("simple-function");
  • Update an ambush function.

    var GDB = require("goblindb");
    
    var goblinDB = GDB();
    
    goblinDB.ambush.add({
    	id: "simple-function",
    	category: ["documentation"],
    	description: "This is a simple function",
    	action: function(){
    		console.log("Hello World");
    	}
    });
    
    goblinDB.ambush.update("simple-function", {"category": ["updated-documentation"]});
  • Get the details about an ambush function.

    var GDB = require("goblindb");
    
    var goblinDB = GDB();
    
    goblinDB.ambush.add({
    	id: "simple-function",
    	category: ["documentation"],
    	description: "This is a simple function",
    	action: function(){
    		console.log("Hello World");
    	}
    });
    
    var copy = goblinDB.ambush.details("simple-function");
    copy.action() //Console -> Hello World
  • Get a list of all the ambush function available in the database.

    Note: You can filter by categories too.

    var GDB = require("goblindb");
    
    var goblinDB = GDB();
    
    console.log("All the Ambush functions:", goblinDB.ambush.details());
    console.log("All the Ambush functions related to documentation:", goblinDB.ambush.details("documentation"));

Testing

You can test your changes in the GoblinDB Core...

npm test