{"name":"jaguardb","version":"0.1.2","author":{"name":"Hector Correa","email":"hector@hectorcorrea.com"},"description":"The simplest in-process database for Node.js that could possible work.","repository":{"type":"git","url":"https://github.com/hectorcorrea/jaguarDb.git"},"keywords":["database","embedded database for node.js","small database for node.js","javascript database for node.js","embedded in-process database for node.js"],"license":"MIT","engines":{"node":">=0.8"},"readme":"jaguarDb\n================\nThe simplest in-process database for Node.js that could possible work. \n\nThis library provides the ability to store information in a Node.js application emulating a simple document-oriented database and without requiring an external process to be running.\n\nThe goal is to provide a quick and dirty way of storing information for small prototypes and unit testing. Do not use this to power your web site or the next eBay.\n\nThe API mimics MongoDB’s API to allow for easy migration of applications using jaguarDb to a real database. Also, the fact the MongoDB has a kickass API makes it an great model to follow.\n\nThis database does not support transactions or any of the ACID properties. In fact you should not even consider it a database. It's basically a glorified wrapper around JSON.stringfy and JSON.parse tailored to mimic a database. \n\nThe API for jaguarDb is asynchronous so that the code using it can easily migrated to use a real database. I might provide a synchronous API later on to make its use much simpler, particularly for unit tests or batch processes.\n\nInstallation\n------------\nThe easiest way to install it is via NPM:\n\n    npm install jaguardb\n\nAlternatively you can download the jaguarDb.js and jaguarUtil.js files from this repo and reference them from your project.\n\n\nBasic Samples\n-------------\nThese following samples assume that you installed jaguarDb via NPM.\n\n**demoAdd.js** shows how to add data to a brand new database.  \n\n    var JaguarDb = require('jaguarDb').JaguarDb;\n    var db = new JaguarDb();\n    db.connect('./data', function(err) {\n      if(err) {\n        // handle error\n        return;\n      }\n      var data = {title: 'hello', content: 'blah blah blah'};\n      db.insert(data, function(err, insertedData) {\n        // insertedData has the new document\n      });\n    });\n\n\n**demoFind.js** shows how to query documents from the database. The basic structure is as follow: \n\n    var JaguarDb = require('jaguarDb').JaguarDb;\n    var db = new JaguarDb();\n    db.connect('./data', function(err) {\n      if(err) {\n        // handle error\n        return;\n      }\n      var query = {}; // all records\n      var fields = {}; // all fields\n      db.find(query, fields, function(err, documents) {\n        // your data is in the documents array\n      });\n    });\n\nYou can filter the documents by providing a query object with the fields and attributes to use to filter: The following example will select documents where the title is 'hello'\n\n    var query = { title: 'hello' };\n\n\nSample using Express\n--------------------\n**demoExpress.js** shows how to use jaguarDb with Express.js. You need to install Express.js on your system via **npm install express** before running this example: \n\n    var express = require('express');\n    var app = express();\n\n    var JaguarDb = require('jaguarDb').JaguarDb;\n    var db = new JaguarDb();\n\n    db.connect('./data', function(err) {\n      if(err) {\n        console.log('Could not connect to database: ' + err);\n        return;\n      }\n    });\n\n    app.get('/', function(req, res){\n      var query = {}; // all records\n      var fields = {}; // all fields\n      db.find(query, fields, function(err, docs) {\n        if(err) {\n          res.send('Error reading documents: ' + err);\n          return;\n        }\n        // build HTML with your documents\n        var html = \"\";\n        res.send(html);\n      });\n    });\n\n\nStorage\n-------\nData is stored in one directory per database. A master file \"index.json\" contains the list of documents in the database plus other general information about the database (e.g. list of indexes, list of ids, and list of indexed values.) \n\nEach document is automatically assigned an _id field with a sequential value. \n\nOne individual JSON file is created for each document, these files are named \"n.json\" where n is the value of the _id for the document.\n\nThe structure of the index.json file is more or less as follows:\n\n    {\n      \"nextId\":3,\n      \"indexes\":[\"field1\"],\n      \"documents\":[\n        {\"_id\":1,\"field1\":\"valueA\"},\n        {\"_id\":2,\"field1\":\"valueB\"}\n      ]\n    }\n\nThe structure of a document file (say 1.json) is more or less as follows: \n\n    {\"_id\":1, \"field1\"\":\"valueA\",\"content\":\"blah blah blah\"}\n\n\nLimitations (a lot)\n-------------------\nThis library is meant to be used in a single-user environment as it has no multi-user provisions. \n\nTransactions are not supported.\n\nNo sorting or aggregations are provided.\n\nThe contents of the index.json file is kept in memory. This include the keys to all the documents and the values of the indexes.\n\nExcept for findById, all find operations are sequential (i.e. no binary tree or btree are used for searching.)\n\nAlthought the API is asynchronous, several of the operations **do block** while executing. \n\n\nFuture enhancements\n-------------------\nAdd support for complex queries. Currently only exact match queries are allowed.\n\n    // This is currently supported\n    // filter where fieldA == 'a' and fieldB == 'b'\n    var query = {fieldA: 'a', fieldB: 'b'};\n\n    // This is NOT currently supported\n    // filter where fieldA == 'a' or fieldB == 'b'\n    // filter where fieldA > 'a'\n\n\nAllow for sorting operations.\n\n\nQuestions, comments, thoughts?\n------------------------------\nThis is a very rough work in progress. \n\nFeel free to contact me at hector@hectorcorrea.com with questions or comments about this project.\n\n\n\n","readmeFilename":"README.md","_id":"jaguardb@0.1.2","dist":{"shasum":"4fa8df03fe8be062ea207195394b1e25feb5fb78","tarball":"https://registry.npmjs.org/jaguardb/-/jaguardb-0.1.2.tgz","integrity":"sha512-YHbcdmcjmJfkqMhCGonp/CGRq/VRMionWvqM2uT6ZmiHC0LnZGVaEy3i/sCaCyhgKRsYEa+ASU3YepSougAOEQ==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIBKwOnqmRdSSTDnB6OX90Y686H7zYMQXRO2HeQKaHJf2AiAKh4wuEtBYX7YdDvsnzD4lFiIDWwWH1ezlAyEg3TvUMQ=="}]},"_from":".","_npmVersion":"1.2.11","_npmUser":{"name":"hectorcorrea","email":"hector@hectorcorrea.com"},"maintainers":[{"name":"hectorcorrea","email":"hector@hectorcorrea.com"}]}