rcdb v0.0.1

RCDB - Relational CouchDB

This library is still in an alpha state and is not recommended for production environments. Api specs are likely to greatly change.

This library allows you to make and manage relational data in a CouchDB instance using nano (and PouchDB in the future). The goal is to give as many of the nice features of relational databases while still keeping the benefits of CouchDB.

Features are implemented using CouchDB design documents to do type checking and some basic security to maintain consistency.

Features:

• Minimal - Most methods match their Nano equivalents so if you know Nano you know RCDB.
• TypeScript - All types are documented and built in.
• Promises - Most methods return native promises.

Installing

npm install rcdb

Getting Started

import nano from 'nano';
import rcdb from 'rcdb';

const con = nano({
	url: 'http://localhost:5984',
	requestDefaults: {
		jar: true,
	},
});

(async () => {
	await con.auth('username', 'password');

	// pass a nano document scope object and a type name
	const relation = await rcdb.nano.TypeScope.use(
		con.use('database'),
		'languages'
	);

	// all operations on the relation object will tag passed objects with type information
	const docs = await relation.bulk({
		docs: [
			{ name: 'JavaScript' },
			{ name: 'C++' }
		]
	});

	/* Will output something like...
		[
			{
				"_id": '...',
				"_rev": '...',
				"name": 'JavaScript',
				"rcdb:_type": 'languages'
			},
			{
				"_id": '...',
				"_rev": '...',
				"name": 'C++',
				"rcdb:_type": 'languages'
			}
		]
	 */
	console.log(docs);
})();

Configuration

TypeScope.use(opt)

opt.type - The name of the type.

opt.indexes - A list of field names that should be used as an index. Order does matter. The CouchDB index view will use these fields to generate the keys.

opt.write_roles - A list of user roles CouchDB docs which are granted access to write documents to this type. This does not restrict read access or write access to the entire database due to restrictions of CouchDB. If you want this behavior I'd recommend looking into CouchDB's database security CouchDB docs.

Type Functions

TypeScope.tag(document0)

Tags a document with type information.

TypeScope.insert(document)

Same as nano.insert but adds type information.

const con = nano.use('database');
const langs = await TypeScope.use(con, 'languages')
await langs.insert({ id: 'ts', name: 'TypeScript' });

TypeScope.destroy(docname, rev)

Same as nano.destroy

await langs.destroy('ts', '1-2a00fed267f946dbba0fccdd66520463');

TypeScope.destroy(document)

Same as nano.destroy

await langs.destroy({ _id: 'ts', _rev: '1-2a00fed267f946dbba0fccdd66520463' });

TypeScope.get(docname)

Same as nano.get

await langs.get('ts');

TypeScope.head

Same as nano.head

TypeScope.bulk

Same as nano.bulk but adds type information.

TypeScope.list

Same as nano.list

TypeScope.listAsStream

Same as nano.listAsStream

TypeScope.fetch

Same as nano.fetch

TypeScope.fetchRevs

Same as nano.fetchRevs

Further Documentation

See nano's docuementation for any additional info.

Developer Guide

Testing

You must have docker installed.

npm test

Roadmap

• Type based design documents
• Per type write security
• Global database write security
• Partition types in databse
• Foreign keys
• PouchDB support