Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/eder-ai/compass-db
https://github.com/eder-ai/compass-db
blockstack gaia
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/eder-ai/compass-db
- Owner: eder-ai
- Created: 2018-01-03T17:44:13.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2018-03-26T17:58:11.000Z (almost 7 years ago)
- Last Synced: 2024-10-15T09:30:01.373Z (3 months ago)
- Topics: blockstack, gaia
- Language: JavaScript
- Size: 6.84 KB
- Stars: 29
- Watchers: 6
- Forks: 4
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# CompassDB
CompassDB is an open soruce ORM for [Gaia] (https://github.com/blockstack/gaia) storage.
It provides an abstraction of a database over the file-based storage system provided by Gaia.
It’s compatible with the Blockstack ecosystem which leverages the Gaia storage, to provide database methods for developers.
## Getting Started
To get started,
> `npm install compass-db`
Or you can download the compassDB-min-js from here.
### Example: Initialization
```javascript
// Create reliable connection with CompassDB
const compassdb = new CompassDB();
// Creating a collection
const collection = compassdb.newCollectionInstance(COLLECTION_NAME, true);
collection.createCollection()
.then((successResponse) => {
// Promise Resolved
.catch((failureResponse) => {
// Promise Rejected
});
});
```
## Core Components
CompassDB uses abstraction concepts to render the database and create a relationship with the actual Gaia storage.
The two main components are:
* **Documents:** These are the basic structural unit of the database. Every document contains a group of key-value pairs. These are used to identify and manage request of files in the storage.
A basic constructor declaration is done with `constructor(collectionName, encrypt_decrypt).`
* **Collections** Collections are described as a set of Documents. Every Collection instance contains the name of all the Documents within that set and their status.
To setup a new connection, we must first create an instance of CompassDB followed by creating a new collection for usage(as shown in the example previously).
## Methods
### Collection Operations
* **createCollection:** Creates a new collection.
* **dropCollection:** Drops an existing collection
### Document Operations
* **insert:** inserts value within a document
* **update:** updates document with help of Id reference
* **findOne:** Finds document within collection
* **findAll:** Finds all documents with certain properties within a collection
* **deleteOne:** Deletes one document from the collection
* **deleteAll:** Deletes all documents with certain properties within a collection
### Types of Response
* **successResponse:**
Status code: 200, Status text: `SUCCESS` , Description and Payload
* **failureResponse:**
Status code: 400, Status text: `FAILURE`, Description
-----------------------
## createCollection
`.createCollection()` creates a new collection. It fetches the list of existing collections and verifies if the requested collection exists or not.
#### Arguments:
No arguments; But to instantiate a Collection object, collectionName, encrypt_decrypt these two infomration are required.
#### Returns:
Promise.
#### Example:
```javascript
const collection = compassdb.newCollectionInstance(COLLECTION_NAME, true);
collection.createCollection()
.then((successResponse) => {
// Promise Resolved
})
.catch((failureResponse) => {
// Promise Rejected
});
```
## dropCollection
`.dropCollection()` implements a soft delete of the collection. It changes the `activeState` to false.
#### Arguments:
No arguments;
#### Returns:
Promise.
#### Example:
```javascript
collection.dropCollection()
.then((successResponse) => {
// Promise Resolved
})
.catch((failureResponse) => {
// Promise Rejected
});
```
## insert
`.insert(newDocument)` puts a document into the collection.
#### Arguments:
`newDocument`, reference to the document that is to be pushed into the collection.
#### Returns:
Promise.
If successful then will return the inserted `Document Object` in successResponse.payload
#### Example:
```javascript
collection.insert(newDocument)
.then((successResponse) => {
// Promise Resolved
})
.catch((failureResponse) => {
// Promise Rejected
});
```
## update
`.update(id,queries)` is used for updating documents already inserted in a collection.
#### Arguments:
`id` and `query`.
The id is used to find the particular document in the collection and after that, the requested queries are processed if eligible.
#### Returns:
Promise.
If successful then will return the updated `Document Object` in successResponse.payload
#### Example:
```javascript
const id = 1;
collection.update(id, { 'title' : 'CompassDB', 'note' : 'Most promising ORM' })
.then((successResponse) => {
// Promise Resolved
})
.catch((failureResponse) => {
// Promise Rejected
});
```
## findOne
`.findOne(queries)` fetches the first document in the collection that contains the given queries.
#### Arguments:
`query`.
The search result brings the first document that matches the description of the key-value pair of the queries. If not found, it gives a `failureResponse` in return.
#### Returns:
Promise
If successful then will return the `Document Object` in successResponse.payload
#### Example:
```javascript
collection.findOne({ 'title' : 'CompassDB', 'note' : 'Most promising ORM' })
.then((successResponse) => {
// Promise Resolved
})
.catch((failureResponse) => {
// Promise Rejected
});
```
## findAll
`.findAll(queries)` fetches all the documents in the collection that contains the given queries as an array of object.
#### Arguments:
`query`.
The search result brings all documents that match the description of the key-value pair of the queries. If not a single document found, it gives a `failureResponse` in return.
#### Returns:
Promise
If successful then will return an array of `Document Objects` in successResponse.payload
#### Example:
```javascript
collection.findAll({ 'title' : 'CompassDB', 'note' : 'Most promising ORM' })
.then((successResponse) => {
// Promise Resolved
})
.catch((failureResponse) => {
// Promise Rejected
});
```
## deleteOne
`.deleteOne(query)` removes the first document that is found matching the query. Here, the `isActive` state of the document is changed to false.
#### Arguments:
`query`
deletes the first document that matches the description of the key-value pair of the queries. If not found, it gives a `failureResponse` in return.
#### Returns:
Promise.
If successful then will return the deleted `Document Object` in successResponse.payload
#### Example:
```javascript
collection.deleteOne({ 'title' : 'another', 'note' : 'test' })
.then((successResponse) => {
// Promise Resolved
})
.catch((failureResponse) => {
// Promise Rejected
});
```
## deleteAll
`.deleteAll(query)` removes the all the documents that match the query. Here, the `isActive` state of the documents are changed to false.
#### Arguments:
`query`
deletes all documents that match the description of the key-value pair of the queries. If not found, it gives a `failureResponse` in return.
#### Returns:
Promise.
If successful then will return an array of deleted `Document Objects` in successResponse.payload
#### Example:
```javascript
collection.deleteAll({ 'title' : 'check', 'note' : 'check' })
.then((successResponse) => {
// Promise Resolved
})
.catch((failureResponse) => {
// Promise Rejected
});
```