2020-06-11 23:05:45 +00:00
# @pushrocks/smartdata
do more with data
## Availabililty and Links
* [npmjs.org (npm package) ](https://www.npmjs.com/package/@pushrocks/smartdata )
* [gitlab.com (source) ](https://gitlab.com/pushrocks/smartdata )
* [github.com (source mirror) ](https://github.com/pushrocks/smartdata )
* [docs (typedoc) ](https://pushrocks.gitlab.io/smartdata/ )
## Status for master
2020-06-12 05:59:07 +00:00
Status Category | Status Badge
-- | --
GitLab Pipelines | [](https://lossless.cloud)
GitLab Pipline Test Coverage | [](https://lossless.cloud)
npm | [](https://lossless.cloud)
Snyk | [](https://lossless.cloud)
TypeScript Support | [](https://lossless.cloud)
node Support | [](https://nodejs.org/dist/latest-v10.x/docs/api/)
Code Style | [](https://lossless.cloud)
PackagePhobia (total standalone install weight) | [](https://lossless.cloud)
PackagePhobia (package size on registry) | [](https://lossless.cloud)
BundlePhobia (total size when bundled) | [](https://lossless.cloud)
2020-06-11 23:05:45 +00:00
## Usage
Use TypeScript for best in class instellisense.
smartdata is an ODM that adheres to TypeScript practices and uses classes to organize data.
It uses RethinkDB as persistent storage.
## Intention
There are many ODMs out there, however when we searched for an ODM that uses TypeScript,
acts smart while still embracing the NoSQL idea we didn't find a matching solution.
This is why we started smartdata.
How RethinkDB's terms map to the ones of smartdata:
| MongoDb term | smartdata class |
| ------------ | ----------------------------- |
| Database | smartdata.SmartdataDb |
| Collection | smartdata.SmartdataCollection |
| Document | smartdata.SmartadataDoc |
### class Db
represents a Database. Naturally it has .connect() etc. methods on it.
```typescript
2021-06-06 15:54:47 +00:00
// Assuming toplevel await
2020-06-11 23:05:45 +00:00
import * as smartdata from 'smartdata';
const smartdataDb = new smartdata.SmartdataDb({
mongoDbUrl: '//someurl',
mongoDbName: 'myDatabase',
2020-08-18 12:01:46 +00:00
mongoDbPass: 'mypassword',
2020-06-11 23:05:45 +00:00
});
2021-06-06 15:54:47 +00:00
await smartdataDb.connect();
2020-06-11 23:05:45 +00:00
```
### class DbCollection
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
```typescript
2021-06-06 15:54:47 +00:00
// Assuming toplevel await
2020-06-11 23:05:45 +00:00
// continues from the block before...
@smartdata .Collection(smartdataDb)
2021-06-06 15:54:47 +00:00
class MyObject extends smartdata.DbDoc< MyObject / * , [ an optional interface to implement ] * / > {
2020-06-11 23:05:45 +00:00
// read the next block about DbDoc
@smartdata .svDb()
property1: string; // @smartdata .svDb() marks the property for db save
2020-06-12 05:59:07 +00:00
2020-06-11 23:05:45 +00:00
property2: number; // this one is not marked, so it won't be save upon calling this.save()
2020-06-12 05:59:07 +00:00
2020-06-11 23:05:45 +00:00
constructor() {
super(); // the super call is important ;) But you probably know that.
}
}
// start to instantiate instances of classes from scratch or database
const localObject = new MyObject({
property1: 'hi',
2021-06-06 15:54:47 +00:00
property2: {
2021-10-16 19:17:02 +00:00
deep: 3,
2021-06-06 15:54:47 +00:00
},
2020-06-11 23:05:45 +00:00
});
2021-06-06 15:54:47 +00:00
await localObject.save(); // saves the object to the database
2020-06-11 23:05:45 +00:00
// start retrieving instances
2021-06-06 15:54:47 +00:00
// .getInstance is staticly inheritied, yet fully typed static function to get instances with fully typed filters
const myInstance = await MyObject.getInstance({
property1: 'hi',
property2: {
deep: {
2021-10-16 19:17:02 +00:00
$gt: 2,
} as any,
},
2020-06-11 23:05:45 +00:00
}); // outputs a new instance of MyObject with the values from db assigned
```
### class DbDoc
represents a individual document in a collection
and thereby is ideally suited to extend the class you want to actually store.
### CRUD operations
2020-06-12 05:59:07 +00:00
smartdata supports full CRUD operations
2020-06-11 23:05:45 +00:00
**Store** or **Update** instances of classes to MongoDB:
DbDoc extends your class with the following methods:
- async `.save()` will save (or update) the object you call it on only. Any referenced non-savable objects will not get stored.
- async `.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
**Get** a new class instance from MongoDB:
DbDoc exposes a static method that allows you specify a filter to retrieve a cloned class of the one you used to that doc at some point later in time:
2020-06-12 05:59:07 +00:00
- static async `.getInstance({ /* filter props here */ })` gets you an instance that has the data of the first matched document as properties.
- static async `getInstances({ /* filter props here */ })` get you an array instances (one instance for every matched document).
2020-06-11 23:05:45 +00:00
**Delete** instances from MongoDb:
smartdata extends your class with a method to easily delete the doucment from DB:
2020-06-12 05:59:07 +00:00
- async `.delete()` will delete the document from DB.
2020-06-11 23:05:45 +00:00
## TypeScript
How does TypeScript play into this?
Since you define your classes in TypeScript and types flow through smartdata in a generic way
you should get all the Intellisense and type checking you love when using smartdata.
smartdata itself also bundles typings. You don't need to install any additional types for smartdata.
2020-06-12 05:59:07 +00:00
## Contribution
We are always happy for code contributions. If you are not the code contributing type that is ok. Still, maintaining Open Source repositories takes considerable time and thought. If you like the quality of what we do and our modules are useful to you we would appreciate a little monthly contribution: You can [contribute one time ](https://lossless.link/contribute-onetime ) or [contribute monthly ](https://lossless.link/contribute ). :)
2020-06-11 23:05:45 +00:00
For further information read the linked docs at the top of this readme.
2023-06-24 23:27:09 +00:00
## Legal
> MIT licensed | **©** [Task Venture Capital GmbH](https://task.vc)
2020-06-11 23:05:45 +00:00
| By using this npm module you agree to our [privacy policy ](https://lossless.gmbH/privacy )
