Diaspora

Multi-source ORM for NodeJS & the browser

Build status

Fancy badges:

Thanks to

$3

for integration tests.

Installation

To install Diaspora, simply run one of the following commands:

``bash


With NPM

npm install --save @diaspora/diaspora

With Yarn

yarn add @diaspora/diaspora
`

Documentation & important notes

Welcome on the GitHub repository of Diaspora. Please visit the manual website, where you can find guides, tutorials, or the API tocumentation

> Important note: Diaspora is very young and under heavy development. You
are totally free to use it or contribute, but be aware that some important
features are incomplete or absent:
Relations*: Not implemented
Query language*: Supported up to Specification level 2.
Multi sources*: not tested

Diaspora extensions

$3

Adapter	Description	Links	Maintainer	Platform		Other infos
				Node	Browser
In Memory	A simple adapter that stores its data directly in the memory	Built-in		✓	✓	[QL] v2
WebApi	A customizable adapter that use HTTP APIs as data source. Convinient to query easily REST, SOAP or GraphQL apis.			✓	✓
WebStorage	A simple adapter that stores its data in the browser's local or session storage.			✗	✓
MongoDB				✓	✗	[QL] v2
Redis				✓	✗	[QL] v2

$3

plugin-server: a package to easily create APIs for Diaspora models

Compatibility

Diaspora requires:

* Node >= 6.4.0
* Browsers:
* Edge >= 12
* Firefox >= 18
* Chrome >= 49
* Safari & iOS Safari >=10
* Chrome for Android >= 61
* Samsung Internet >= 5

More briefly, Diaspora runs on all browsers & JavaScript engines that supports
Proxies.

Notable incompatible browsers are

* Internet Explorer (all versions)
* Opera Mini
* UC Browser for Android

API Overview

Need help getting started? We have a page on how to get started in 5 minutes.

Here is a short API overview. For a detailed API documentation, check the Diaspora API Documentation

$3

#### spawn([object props]) => Entity

Create an entity, defining its properties with provided props. The returned
entity should be persisted later.

#### spawnMany([object[] props]) => Set

See spawn.

#### insert([object props]) => Promise(Entity)

Create an entity, defining its properties with provided props, and persist it
immediately.

#### insertMany([object[] props]) => Promise(Set)

See insertMany.

#### find(object || Any query, [object options], [string source]) => Promise(Entity)

Retrieve an entity matching query. If query isn't an object, it is
considered as an ID.

#### findMany(object || Any query, [object options], [string source]) => Promise(Set)

See find

#### delete(object || Any query, [object options], [string source]) => Promise(Entity)

Delete an entity matching query. If query isn't an object, it is considered
as an ID. options can contain allowEmptyQuery.

#### deleteMany(object || Any query, [object options], [string source]) => Promise(Entity)

See delete

#### update(object || Any query, object newAttrs, [object options], [string source]) => Promise(Entity)

Update a single entity matching querywith attributes in newAttrs. If query
isn't an object, it is considered as an ID. options can contain
allowEmptyQuery.

#### updateMany(object || Any query, object newAttrs, [object options], [string source]) => Promise(Set)

See update

$3

#### destroy([string source]) => Promise(this)

Delete this entity from the specified source. Source hash object is set to
undefined

#### persist([string source]) => Promise(this)

Save current entity to the specified source.

#### fetch([string source]) => Promise(this)

Reload entity from specified source.

Planned or unsure Diaspora behaviors/features

> Manual change of properties

Unsure > Entity may change status to desync ?

> P2P Adapter

Unsure > May be interesting... Check for possible problems about data
modification, etc etc.

> IndexedDB Adapter (browser)

Unsure > IndexedDB technology may be too immature. See MDN about IndexedDB.
Note: Plan to show fallback implementations

[QL]: https://diaspora.ithoughts.io/guides/query-language#match-queries

Working with the development version

If you are having issues, or you want to participate to the development and create new features, you may have to use the development or staging version of Diaspora. Here is how you can do that:

`sh


Clone the repository & go into it


git clone https://github.com/diaspora-orm/diaspora.git && cd diaspora


Go on the staging branch (you can also use directly the develop branch, but it may be less stable)

git checkout staging

The following command installs dependencies & compiles the package

npm run build

Finally, expose your local build so that it can be used in other projects.

You may need to run it with sudo.

npm link

Go to your project

cd ~/myproject

Ensure deps are installed

npm install

And link the local version

npm link @diaspora/diaspora
`

> Note that you may need to re-run npm link @diaspora/diaspora after every install (npm install`) in your project.