shelfdb

is a Node.JS database library that allows for JSON and YAML (but you can easily extend the serializer options by implementing the abstract class DatabaseSerializer - see below for abstract classes!).

Its capabilities include serializing most objects, including primitive types, arrays and even objects that are serialized in a custom way (check the class DBSerializable for more!)

An example of its usage:

$ node
> var { YAMLSerializer } = require('shelfdb')
undefined
> YAMLSerializer
{ [Function: YAMLSerializer] database: [Function] }
> var db = YAMLSerializer.database('test.yml')
undefined
> db.put("test.2.thanks", {"Hello": "World!"})
'test.2.thanks'
> db.get("test.2.thanks.hello") // Hey, path strings are case-sensitive!
null
> db.get("test.2.thanks.Hello") // Now it's right. :)
'World!'
> db.get("test.2.thanks")
{ Hello: 'World!' }

This chain of commands results in a test.yml file with the following contents:

spec:
    serialization: null
    type: object
    primitive: false
obj:
    test:
        spec:
            serialization: null
            type: object
            primitive: false
        obj:
            '2':
                spec:
                    serialization: null
                    type: object
                    primitive: false
                obj:
                    thanks:
                        spec:
                            serialization: null
                            type: object
                            primitive: false
                        obj:
                            Hello:
                                spec:
                                    serialization: null
                                    type: string
                                    primitive: true
                                obj: World!

In case you don't require advanced specification structures for accurately flexible representations, please don't use this! It'll make your file way larger and isn't suitable for large files.

API

Databases

Database(String filename, [Class<? implements DBSerializable> or DBSerializable] serializer)

The Spotlight of this Library

This is a concrete class (i.e. non-abstract) which has common database functions like put, get and save; those functions automatically sync it with a filename given in the constructor (or in the serializer's ). Extending it can be made by inheriting it (using CoffeeScript or maybe ES6).

This class has the following functions:

• put(String path, Object value)

Function Scope: instance - Function Return Type: String

Puts a value object of any supported kind in the path specified (which is basically a path that includes keys separated by a . dot) of this database.

Returns path for further concatenation with subpathes etc.

Does NOT support ..!

• get(String path)

Function Scope: instance - Function Return Type: [Object or null]

Gets an object at the specified path of this database, or null if none was found. Pathes are formed like the ones in the call to put.

• serialize(Object in)

Function Scope: instance - Function Return Type: String

Serializes an object to a string as if it were part of the database.

• objectFrom(Object in)

Function Scope: instance - Function Return Type: Object (serialized)

Returns an object containing spec that can be deserialized using unfreeze. All objects returned by objectFrom must be composed by primitive types, arrays and objects only; but they must represent accurately the in object when passed to unfreeze.

• unfreeze(Object in)

Function Scope: instance - Function Return Type: Object (deserialized)

The antonym of objectFrom.

DBSerializable()

Objects of Custom Serialization

This is an abstract class for which implementing classes contain information on how custom objects should be transformed into and obtained from serializable Objects. Every implementing class must have the following functions:

• toObject()

Function Scope: instance - Function Return Type: Object

Returns any object (containing only objects, arrays or primitives) that represents this structure

• fromObject(Object from)

Function Scope: static - Function Return Type: declaring class

Returns the object with the unfrozen object, ready to be converted to an instance of the same class.

DatabaseSerialize()

Serialization into Other Languages

This is an abstract class for which implementing classes can parse and stringify basic object kinds into basic (or not) languages, such as for example INI or NBT. Every implementing class must have the following functions:

• serialize(String data)

Function Scope: instance - Function Return Type: String

Returns a String representing the data accurately.

• deserialize(Object data)

Function Scope: instance - Function Return Type: Object

Returns an Object containing the data represented by the string.

Additionally, all objects implementing DatabaseSerializer have the following default functions:

• database(String filename)

Function Scope: static - Function Return Type: Database

Returns a database with the serializer set automatically to the Serializer it is called on. A filename must still be provided.

Abstract Classes

Abstract classes are classes that have unimplemented methods and thus for security can't be instantiated; you need to set it to an implemented version of it using its apply function. Their main usage is for template code which can serve as the bare bones for future classes that have the same (or similar) concept or usage, but different methodology.

These are based in Java interfaces.

Functions

• abstractClass(Class other, optional Function onApply(Class s))

Function Scope: global - Function Return Type: AbstractClass

Returns an abstracted version of this class, which has an apply(Class other) static function that returns a version of other implementing this class (which is necessary to make it an implementation of this class).

Rules for abstract classes:

• All abstract functions must be null, static, and their name must be prefixed by either F_ for instance functions or S_ for static ones.

• Every other static property (functions or not) are inherited if their value is not null or undefined.

• Since abstract classes can never be instantiated, no instance function is inherited.

• isImplementation(Class other, Class abstractClass)

Function Scope: global - Function Return Type: boolean

Returns whether other implements abstractClass.