@diaspora/diaspora

Diaspora

Multi-source ORM for NodeJS & the browser

Build status

Fancy badges:

Thanks to

Browserstack

for integration tests.

Installation

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

# 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

Available adapters

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

Other modules

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

Model methods

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

Entity/Set methods

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

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:

# 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.