streamDB

A working back-end + API service in 60 seconds.

---

Features | Usage | Guide | API

---

Designed for front-end development so you can just focus on building your awesome application.

Key Features

A Full Featured Database

• Generated ids (incr, uid)
• Timestamps (created_at, updated-at)
• Queries (includes geo-search)
• Splits JSON store files, as data grows
• Uses Node Streams to literallly zoom through data

---

Data Model + Validation

• Schema validation & settings
• Parent/subdocument refs
• Mongoose inspired syntax and modeling

---

Server + API Routes

• Built with Express Framework
• Simple CRUD starter routes
• Helper methods to help you customize routes faster
• Launch as standalone, or mount onto existing server

---

➤ Launch server with one line of code
➤ Simple promise-based CRUD methods
➤ Automatically creates router + model files

Table of Contents

• Usage
• Starter Routes
• Using Schema Models
• Launching Server
• ➥ Guide
• ➥ API Reference
• ➥ Examples
• Tests
• What's Next
• CHANGELOG

Usage

Install:

$ npm i streamdb

To use CLI without global install, prefix commands with npx:

$ npx streamdb create --db sampleDB

Or, install a global copy as well:

$ npm i -g streamdb

Create DB:

In terminal:

$ streamdb create --db sampleDB

Or, run in file:

const streamdb = require('streamdb')

streamdb.createDb({ dbName: 'sampleDB' })
  .then(res => console.log(res))
  .catch(e => console.log(e))

Add Collections:

In terminal:

$ streamdb sampleDB --add users 

Or, run in file:

const streamdb = require('streamdb')
const db = new streamdb.DB('sampleDB')

db.addCollection('users')
  .then(res => console.log(res))
  .catch(e => console.log(e))

Add Documents:

const streamdb = require('streamdb')
const db = new streamdb.DB('sampleDB')

const documents = [
  {
    firstname: 'Bugs',
    lastname: 'Bunny',
    email: 'bbunny@email.com'
  },
  {
    firstname: 'Scooby',
    lastname: 'Doo',
    email: 'sdoo@email.com'
  },
  {
    firstname: 'Tom',
    lastname: 'Cat',
    email: 'tcat@email.com'
  }
]

db.collection('users').insertMany(documents)
  .then(res => console.log(res))
  .catch(e => console.log(e))

Read Documents:

const streamdb = require('streamdb')
const db = new streamdb.DB('sampleDB')

db.collection('users').getById(1)
  .then(res => console.log(res))
  .catch(e => console.log(e))

// using queries:
// db.collection('users')
//  .where('id = 1')
//  .and('firstname = Bugs')
//  .find()
//  .then(..)

// Response object: 
//{
//  success: true,
//  data: [
//    {
//      id: 1,
//      firstname: 'Bugs',
//      lastname: 'Bunny',
//      email: 'bbunny@email.com'
//    }
//  ]
//}

Update Documents:

const streamdb = require('streamdb')
const db = new streamdb.DB('sampleDB')

const docUpdate = {
  id: 1,
  email: b-bunny@email.com
}

db.collection('users').updateOne(docUpdate)
  .then(res => console.log(res))
  .catch(e => console.log(e))

// using queries:
// db.collection('users')
//  .where('id = 1')
//  .setProperty('email', 'b-bunny@email.com')
//  .then(..)

// Response object: 
//{
//  success: true,
//  message: 'Document 1 updated successfully'
//  data: [
//    {
//      id: 1,
//      firstname: 'Bugs',
//      lastname: 'Bunny',
//      email: 'b-bunny@email.com'
//    }
//  ]
//}

Delete Documents:

const streamdb = require('streamdb')
const db = new streamdb.DB('sampleDB')

db.collection('users').deleteMany([2,3])
  .then(res => console.log(res))
  .catch(e => console.log(e))

// Response object: 
//{
//  success: true,
//  message: '2 documents removed from "users" collection'
//  data: [2,3]
//}

---

Starter Collection Routes

Creating new collections scaffolds a new Router file with the following routes you may edit/add to:

Request	Route	Description	-	Method
GET	/api/collection	Get all docs		get()
GET	/api/collection/:id	Get by id		getById()
GET	/api/collection/_q/	Run compound queries		helper_methods
POST	/api/collection	Insert many docs		insertMany()
PUT	/api/collection	Update many docs		updateMany()
PUT	/api/collection/_q/	Run update queries		helper_methods
DELETE	/api/collection/:id	Delete by id		deleteOne()

Example GET (all documents) route in template:

---

Using Schema Validation

Starter Schema Model Template:

Edit template if you wish to add validation and document settings:

// User Model
const streamdb = require('streamdb')
const Schema = streamdb.Schema

const User = new Schema({
    id: streamdb.Types.$incr,
    firstname: String,
    lastname: String,
    email: {
        type: String,
    required: true,
        maxlength: 100
    }
}, 
    {
        strict: false,
        timestamps: {
            created_at: true,
            updated_at: true
    }
})

module.exports = streamdb.model('User', User)

---

Launching/Using Server

const streamdb = require('streamdb')

const app = streamdb.server('sampleDB', 'api', 3000)

// open browser (or send GET query)..
// get all --> get(): http://localhost:3000/api/users
// get by id --> getById(1): http://localhost:3000/api/users/1

// sending POST request with JSON data in body..
// add many --> insertMany(docs): http://localhost:3000/api/users

// in POST body:
// [{
//  "firstname": "john",
//  "lastname": "smith",
//  "email": "jsmith@email.com"
//	},
//	{
//  "firstname": "mary",
//  "lastname": "jane",
//  "email": "mj@email.com"
//	}]

▲ back to top

---

Tests

Tests are implemented using the Jest Framework, and located in the __tests__ directory.

To run tests, fork/clone a copy of https://github.com/fabiantoth/streamdb.git locally, install all dev/dependencies and run:

$ npm test

Run coverage report:

$ npm run test-coverage

---

What's Next

• remove legacy 'default' workflow from codebase
• add populate() to chainQuery helper
• add 'unique' index schema option
• add text-search feature
• build demo w/FE Framework
• refactor cache to support multiple dbs
• add CI automation

---

Stability Notice

• streamDB is mainly for prototyping, do not use in production, or use sensitive/important data.
• Early v0.x.x updates may be breaking, experimental, or temporary (keep track of updates, CHANGELOG).