nsbs

Node SQL bucket-like storage

0. Install
1. Usage
2. Importing
3. Create nsbs object
4. Create new bucket
5. Check bucket existance
6. Remove bucket
7. Adding items
8. List collection
9. Getting item
10. List items
11. List buckets
12. Update items
13. Delete item
14. About nsbs
15. Next Steps
16. Test
17. License

Install

To start using nsbs, simply run

npm i -S nsbs

(* i is a shorthand for install and S is shorthand for save)

Usage

To use this module, make sure you have node.js v4.0+ installed on your maching, to manage your node versions better, try n the node module management tool.

Importing

// ES6
import nsbs from 'nsbs';
// ES5
var nsbs = require('nsbs');

Create nsbs object

A nsbs object is needed to start storing and retreiving data with nsbs. You can have as many nsbs object you want. (* just make sure they point to differnet directories)

const database = new nsbs(options)

options

• databasePath: absolute path for the database (required)

Create new bucket

Before you add item to the database, you need to have at least one bucket created

database.newBucket(bucket)

This returns a promise resolve with [Object] that include the information of the created bucket

bucket

The name of your bucket (required)

Remove bucket

When you want to destroy everything inside a bucket, you can choose to remove the bucket from the database

database.removeBucket(bucket)

This returns a promise resolve with integer, if integer == 0 it means the deletion failed, if integer is >= 1, it means the deletion has succeeded.

bucket

The name of your bucket (required)

Bucket Exist

If you want to check if a bucket exist in the system, you can use this to check

database.existBucket(bucket)

This returns a promise resolve with a Boolean, true for exist and false for not exist.

bucket

The name of your bucket (required)

Adding items

nsbs is a bucket-like storage. Which means when you store an object, it needs to go to a group, and that group belongs to a bucket. When you add a item to the bucket, you must specify a collection that item belongs to. When the collection does not exist, it will be automatically created.

database.addItem(bucket, collection, object)

This returns a promise that resolve a [Object] which is the document that have been inserted to the db.

bucket

The bucket you want to store this item's collection (required)

collection

The collection you want to store the item (required)

object

The object you are storing (required)

Example

database.addItem('app-1', 'files', {filename: 'file.png'})

List collection

Sometimes its a nice idea to list all the collection in a bucket, you can do it using:

database.listCollection(bucket)

This returns a promise resolves with an array of collections.

bucket

The name of your bucket (required)

Getting item

When you want to retrieve an item from a collection

database.getItem(bucket, collection, query)

This returns a promise that will resolve either [Object] if your query is matched with an item in the collection or null of no item is matched

bucket

The name of your bucket (required)

collection

The name of your collection (required)

query

The query object for this collection (required)

example

database.getItem('app-1', 'files', '{name: 'file.png'}')

List items

When you want to retrieve all the items with in the collection, you can:

database.listItems(bucket, collection)

This returns a promise what resolve with a array of objects in that collection, if the collection does not exist or there is no object in the collection, it will resolve with empty array.

bucket

The name of your bucket (required)

collection

The name of your collection (required)

List buckets

You can list all the buckets in the database using:

database.listBuckets()

This returns a promise that resolves an array which include all the buckets in the system. If no buckets are created, it will resolve into empty array.

Update item

When you want to update an existing item:

database.updateItem(bucket, collection, query, newDocument)

This will return a promise which will resolve into an array of document thats been updated.

• note that this update is using a upsert method, if item does not exist, it will simply insert the item into the collection.

bucket

The name of your bucket (required)

collection

The name of your collection (required)

query

The query object for this collection (required)

newDocument

The object for the new document that will replace the one you are updating

example

database.updateItem('app-1', 'files', {name: test.png}, {name: test.png, path: '/new/file/path.png'})

Delete item

You can delete existing object from the collection using:

database.deleteItem(bucket, collection, query)

This returns a promise which resolves into an integer that indicate the number of document got deleted by this query.

bucket

The name of your bucket (required)

collection

The name of your collection (required)

query

The query object for this collection (required)

About

nsbs is build to replace the mess in the current build of yaas the asset server. Currently it is using Tingodb as its datastorage engine. nsbs will create a layer on top of Tingodb and expose some very simple APIs to be used in a server environment.

nsbs is not a replacement for anything, most of the time it is better to use Tingodb or Mongodb my itself. I created nsbs for the purpose of rewritting yaas completely. And nsbs will be used to demonstrate how build anthing as a plugin for the new yaas platform.

Next steps

nsbs is quite useless at this stage, since you will be better off just use the native Tingodb module or Mongodb, but later I will fully decouple the storage engine from nsbs so you can use the nsbs with any storage engine. This is mainly because I want to offer a a lot of freedom to ayase.js's users.

Test

All the test written for Mocha testing framework with assertion library such as Chai and chai-as-promised. You can run these test by executing:

gulp test

Test coverage can be generated by running:

gulp coverage

License

MIT License

Copyright (c) 2016 Siyuan Gao

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.