smartdata/README.md

106 lines
4.4 KiB
Markdown
Raw Normal View History

2016-09-11 16:03:47 +00:00
# smartdata
2016-09-13 08:17:34 +00:00
> Note: Still in Beta
2016-11-17 21:41:01 +00:00
## Availabililty
[![npm](https://push.rocks/assets/repo-button-npm.svg)](https://www.npmjs.com/package/smartdata)
[![git](https://push.rocks/assets/repo-button-git.svg)](https://gitlab.com/pushrocks/smartdata)
[![git](https://push.rocks/assets/repo-button-mirror.svg)](https://github.com/pushrocks/smartdata)
[![docs](https://push.rocks/assets/repo-button-docs.svg)](https://pushrocks.gitlab.io/smartdata/)
## Status for master
[![build status](https://gitlab.com/pushrocks/smartdata/badges/master/build.svg)](https://gitlab.com/pushrocks/smartdata/commits/master)
[![coverage report](https://gitlab.com/pushrocks/smartdata/badges/master/coverage.svg)](https://gitlab.com/pushrocks/smartdata/commits/master)
[![Dependency Status](https://david-dm.org/pushrocks/smartdata.svg)](https://david-dm.org/pushrocks/smartdata)
[![bitHound Dependencies](https://www.bithound.io/github/pushrocks/smartdata/badges/dependencies.svg)](https://www.bithound.io/github/pushrocks/smartdata/master/dependencies/npm)
[![bitHound Code](https://www.bithound.io/github/pushrocks/smartdata/badges/code.svg)](https://www.bithound.io/github/pushrocks/smartdata)
[![TypeScript](https://img.shields.io/badge/TypeScript-2.x-blue.svg)](https://nodejs.org/dist/latest-v6.x/docs/api/)
[![node](https://img.shields.io/badge/node->=%206.x.x-blue.svg)](https://nodejs.org/dist/latest-v6.x/docs/api/)
[![JavaScript Style Guide](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)
2016-09-13 08:26:17 +00:00
smartdata is an ODM that adheres to TypeScript practices and uses classes to organize data.
2016-11-17 21:36:12 +00:00
It uses MongoDB or NeDb as persistent storage.
2016-09-12 20:11:17 +00:00
## Intention
2016-09-13 08:31:14 +00:00
There are many ODMs out there, however when we searched for an ODM that uses TypeScript,
2016-11-17 21:41:01 +00:00
acts smart while still embracing the NoSQL idea we didn't find a matching solution.
2016-09-13 08:31:14 +00:00
This is why we started smartdata.
2016-09-12 20:11:17 +00:00
How MongoDB terms map to smartdata classes
MongoDB term | smartdata class
--- | ---
2016-09-12 21:47:57 +00:00
Database | smartdata.Db
2016-09-12 20:11:17 +00:00
Collection | smartdata.DbCollection
Document | smartdata.DbDoc
2016-09-12 21:47:57 +00:00
### class Db
represents a Database. Naturally it has .connect() etc. methods on it.
Since it is a class you can have multiple DBs defined.
2016-11-17 21:36:12 +00:00
```javascript
2016-09-12 21:47:57 +00:00
import * as smartdata from 'smartdata'
2016-11-17 21:36:12 +00:00
// mongodb
2016-09-12 21:47:57 +00:00
let myDb1 = new smartdata.Db('someConnectionUrl')
let myDb2 = new smartdata.Db('someConnectionUrl')
2016-11-17 21:36:12 +00:00
// nedb
let myDb3 = new smartdata('/some/path/for/persistence', 'nedb') // you may set first argument to null for just in memory db
2016-09-12 21:47:57 +00:00
myDb1.connect()
myDb2.connect()
2016-09-12 22:04:07 +00:00
// continues in next block...
2016-09-12 21:47:57 +00:00
```
2016-09-12 22:13:00 +00:00
### class DbCollection
2016-09-12 21:47:57 +00:00
represents a collection of objects.
A collection is defined by the object class (that is extending smartdata.dbdoc) it respresents
So to get to get access to a specific collection you document
2016-11-17 21:36:12 +00:00
```javascript
2016-09-12 22:04:07 +00:00
// continues from the block before...
@Collection(myDb1)
2016-09-13 23:03:25 +00:00
class myObject extends smartdata.DbDoc<myObject> { // read the next block about DbDoc
2016-11-17 23:59:57 +00:00
@smartdata.saveable property1: string // @smartdata.saveable marks the property for db save
property2: number // this one is not marked, so it won't be save upon calling this.save()
2016-09-12 21:47:57 +00:00
constructor(optionsArg:{
2016-11-17 23:59:57 +00:00
property1: string,
property2: number
2016-09-12 21:47:57 +00:00
}) {
super()
2016-09-12 21:47:57 +00:00
}
2016-11-17 11:20:52 +00:00
}
2016-09-13 20:53:21 +00:00
let myCollection = myDb1.getCollectionByName<myObject>(myObject)
2016-11-17 21:36:12 +00:00
// start to instantiate classes from scratch or database
2016-09-12 21:47:57 +00:00
```
> Alert: You NEVER instantiate a collection.
This is done for you!!!
### class DbDoc
2016-09-12 22:13:00 +00:00
represents a individual document in a collection
and thereby is ideally suited to extend the class you want to actually store.
2016-09-12 21:47:57 +00:00
2016-09-13 08:17:34 +00:00
DbDoc extends your class with the following methods:
* `.save()` will save (or update) the object you call it on only. Any referenced non-savable objects will not get stored.
* `.saveDeep()` does the same like `.save()`.
In addition it will look for properties that reference an object
that extends DbDoc as well and call .saveDeep() on them as well.
Loops are prevented
2016-09-12 21:47:57 +00:00
2016-09-13 08:23:46 +00:00
So now we can **store** instances of classes to Db...
How do we **get** a new class instance from a Doc in the DB?
## TypeScript
How does TypeScript play into this?
2016-09-13 08:26:17 +00:00
Since you define your classes in TypeScript and types flow through smartdata in a generic way
2016-09-13 08:23:46 +00:00
you should get all the Intellisense and type checking you love when using smartdata.
smartdata itself also bundles typings.
2016-09-13 08:26:17 +00:00
So you don't need to install any additional types when importing smartdata.
2016-09-12 21:47:57 +00:00
2016-09-12 20:11:17 +00:00
[![npm](https://push.rocks/assets/repo-header.svg)](https://push.rocks)