Diaspora
Multi-source ORM for NodeJS & the browser
Build status
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
- Edge
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
props
]) => Entity
spawn([object Create an entity, defining its properties with provided props
. The returned
entity should be persisted later.
props
]) => Set
spawnMany([object[] See spawn
.
props
]) => Promise(Entity)
insert([object Create an entity, defining its properties with provided props
, and persist it
immediately.
props
]) => Promise(Set)
insertMany([object[] See insertMany
.
query
, [object options
], [string source
]) => Promise(Entity)
find(object || Any Retrieve an entity matching query
. If query
isn't an object, it is
considered as an ID.
query
, [object options
], [string source
]) => Promise(Set)
findMany(object || Any See find
query
, [object options
], [string source
]) => Promise(Entity)
delete(object || Any Delete an entity matching query
. If query
isn't an object, it is considered
as an ID. options
can contain allowEmptyQuery
.
query
, [object options
], [string source
]) => Promise(Entity)
deleteMany(object || Any See delete
query
, object newAttrs
, [object options
], [string source
]) => Promise(Entity)
update(object || Any Update a single entity matching query
with attributes in newAttrs
. If query
isn't an object, it is considered as an ID. options
can contain
allowEmptyQuery
.
query
, object newAttrs
, [object options
], [string source
]) => Promise(Set)
updateMany(object || Any See update
Entity/Set methods
source
]) => Promise(this)
destroy([string Delete this entity from the specified source
. Source hash object is set to
undefined
source
]) => Promise(this)
persist([string Save current entity to the specified source
.
source
]) => Promise(this)
fetch([string 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 develop
ment 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.