Extended Deepstream client

Promise based deepstream client. It's basically the deepstream.io-client-js with basic calls promisified, plus some extra methods. All methods are added as polyfills.

Install

npm i -S extended-ds-client

Overview

Creating a client through this package will give you additional methods on the client object, leaving everything from the default client untouched (getRecord, getList etc).

These are the additional functions:

p.login (alias: loginP)
record.p.getRecord (alias: record.getRecordP)
record.p.getList (alias: record.getListP)
record.p.setData (alias: record.setDataP)
record.p.snapshot (alias: record.snapshotP)
record.p.has (alias: record.hasP)
rpc.p.make (alias: rpc.makeP)
record.p.getExistingRecord (alias: record.getExistingRecordP)
record.p.getExistingList (alias: record.getExistingListP)
record.p.deleteRecord (alias: record.deleteRecordP)
record.p.deleteList (alias: record.deleteListP)
record.p.addToList (alias: record.addToListP)
record.p.removeFromList (alias: record.removeFromListP)
record.p.updateExistingRecord (alias: record.updateExistingRecordP)
record.p.getDatasetRecord (alias: record.getDatasetRecordP)

In case of rejection on any of these functions, the rejected argument is always an instance of Error.

There is also a utility function to import from this module:

addEntry (prevents duplicates)

Tunneling export of CONSTANTS & MERGE_STRATEGIES (so that you don't also have to import deepstream.io-client-js for these).

Example 1

import getClient from 'extended-ds-client';

const client = getClient('localhost:6020');

client.p
  .login({})
  .then(data => {
    console.log('Successful login.', data);
  })
  .catch(data => {
    console.log('Login failed.', data);
  });

const users = {};
client.record.p.getList('users').then(list => {
  // With the list of entries, map each entry to a record promise and
  // wait for all to get finished:
  Promise.all(list.getEntries().map(path => client.record.p.getRecord(path))).then(records =>
    records.forEach(record => {
      // Now save all data etc
      const user = record.get();
      users[user.id] = user;
    }),
  );
});

// Default functions still work
client.record.getList('article/x35b/comments').whenReady(l => {
  // ...
});

Example 2

import getClient, { CONSTANTS, ds } from 'extended-ds-client';

ds.client = getClient('localhost:6020'); // use singleton feature

ds.client.loginP({}); // using alias pattern (instead of p.login)

console.log(CONSTANTS); // MERGE_STRATEGIES is also available as import

Example 3

// Given Example 2 file is imported together with this one

import { ds } from 'extended-ds-client';

// And why not use async-await now...

async function fetchUsers() {
  const l = await ds.client.record.p.getExistingList('users');
  const records = await Promise.all(
    l.getEntries().map(path => ds.client.record.p.getExistingRecord(path)),
  );
  const users = {};
  records.forEach(r => {
    const user = r.get();
    users[user.id] = user;
  });
  return users;
}

getClient

Default export from this module is the function getClient to create a client (just like deepstream() in original client). In the same way it also accepts an options object.

const client = getClient('localhost:6020', {
  datasetRecordFullPaths: false,
  datasetRecordIdKey: 'rid',
  splitChar: '.',
});

Option	Type	Default	Description
`datasetRecordFullPaths`	`boolean`	true	Full paths in lists (or only id) for datasetRecord methods.
`datasetRecordIdKey`	`string`	`'id'`	ID key for dataset records.
`splitChar`	`string`	`'/'`	Splitting character in paths (for dataset records).

Promisification API

The promises will be resolved with the same argument(s) as the default client callbacks would get (or the whenReady when applicable). See the deepstream JS client documentation.

`p.login`

Alias: loginP

Straightforward promisification of login. See Example 1 above.

Note: Default login still works, you can still do the standard line with callback: client.login({}, success => console.log(success));

`record.p.getRecord`

Alias: record.getRecordP

Promisification of record.getRecord.

client.record.p.getRecord(name)
  .then(dsRecord => ...)
  .catch(error => ...);

`record.p.getList`

Alias: record.getListP

Promisification of record.getList.

client.record.p.getList(name)
  .then(dsList => ...)
  .catch(error => ...);

`record.p.setData`

Alias: record.setDataP

Promisification of record.setData.

client.record.p.setData(name, path, data)
  .then(() => ...)
  .catch(error => ...);

`record.p.snapshot`

Alias: record.snapshotP

Promisification of record.snapshot.

client.record.p.snapshot(name)
  .then(record => ...)
  .catch(error => ...);

`record.p.has`

Alias: record.hasP

Promisification of record.has, but will reject if it does not exist (and on error of course).

A second optional argument makes the check inverted -- rejecting on existing record. (This can be handy to make sure an id is free).

client.record.p.has(name)
  .then(() => ...)
  .catch(error => ...);

await client.record.p.has('record1');
// if we get here, record1 is a non-taken record id

`rpc.p.make`

Alias: rpc.makeP

Promisification of rpc.make.

client.rpc.p.make(name, data)
  .then(result => ...)
  .catch(error => ...);

Additional API functions

`record.p.getExistingRecord`

Alias: record.getExistingRecordP

Additional method that does a .has-check before .getRecord to get a record handler without implicit record creation (Compare with snapshot that also fails if the record does not exist, but returns the actual record instead of a record handler). It rejects the promise if the record does not exist.

client.record.p.getExistingRecord(name)
  .then(dsRecord => ...)
  .catch(error => ...);

`record.p.getExistingList`

Alias: record.getExistingListP

Like p.getExistingRecord above, but for List.

client.record.p.getExistingList(name)
  .then(dsList => ...)
  .catch(error => ...);

`record.p.deleteRecord`

Alias: record.deleteRecordP

Will resolve when the delete event is emitted (avoiding the race condition risk).

client.record.p.deleteRecord(arg)
  .then(() => ...)
  .catch(error => ...);

Argument	Type	Default	Description
`arg`	`string`/`Object`		The path to the record OR a DS Record object.

`record.p.deleteList`

Alias: record.deleteListP

Like p.deleteRecord above, but for List.

client.record.p.deleteList(arg)
  .then(() => ...)
  .catch(error => ...);

Argument	Type	Default	Description
`arg`	`string`/`Object`		The path to the list OR a DS List object.

`record.p.addToList`

Alias: record.addToListP

Add an entry or multiple entries to an existing list, without duplicates.

client.record.p.addToList('books', 'selfish-gene')
  .then(dsList => ...)
  .catch(error => ...);

Argument	Type	Default	Description
`listPath`	`string`		The name/path of the record.
`id`	`string`/`Array`		Entry(ies) to add.

`record.p.removeFromList`

Alias: record.removeFromListP

Remove an entry or multiple entries from an existing list.

client.record.p.removeFromList('books', 'selfish-gene')
  .then(dsList => ...)
  .catch(error => ...);

Argument	Type	Default	Description
`listPath`	`string`		The name/path of the record.
`id`	`string`/`Array`		Entry(ies) to add.

`record.p.updateExistingRecord`

Alias: record.updateExistingRecordP

Update a record, choosing from one of multiple update modes:

shallow: Default mode. Overwrite each property at the base level.
overwrite: Replace the whole record.
deep: Deep merge of the updates into record (using lodash.merge).
deepConcat: Deep merge, but concatenate arrays with only simple values.
deepConcatAll: Merge like deepConcat, but concatenate ALL arrays.
deepIgnore: Deep merge, but leave unchanged if some value in updates is '%IGNORE%'.
deepConcatIgnore: Merge like deepConcat, but skip values like deepIgnore.
removeKeys: With updates as an array, remove corresponding keys in record.

Two additional array arguments, lockedKeys and protectedKeys, makes it possible to lock or protect given keys, regardless of update mode. Locked keys won't be altered and protected ones won't be removed.

client.record.p.updateExistingRecord('record1', { a: 1, data: { b: 2 }})
  .then(() => ...)
  .catch(error => ...);

client.record.p.updateExistingRecord(
  'records/r-x',
  { data: { configs: [{ items: ['toBeConcatenated'] }] } },
  'deepConcat',
)
  .then(() => ...)
  .catch(error => ...);

client.record.p.updateExistingRecord(
  'record1',
  { data: { confs: ['%IGNORE%', { items: ['replacingFirstItem'] }] }, id: 'xb24' },
  'deepIgnore',
  ['id']
)
  .then(() => ...)
  .catch(error => ...);

Argument	Type	Default	Description
`name`	`string`		The name/path of the record.
`updates`	`Object`/`Array`		The updates. Array for mode = `removeKeys`
`mode`	`string`	`"shallow"`	Update mode, see details above.
`lockedKeys`	`Array`		Keys which values can't be altered.
`protectedKeys`	`Array`		Keys which can't be removed.

`record.p.getDatasetRecord`

Alias: record.getDatasetRecordP

In case you often end up with the structure of having a list of some type of records as the "parent" of those records. For example a list of all bookings at bookings and the bookings at bookings/room-19, bookings/room-27 etc.

On resolve you get back both the deepstream list handle and record handle.

The options described in getClient above will influence how this function operates.

client.record.p.getDatasetRecord('bookings', 'room-27').then(([dsList, dsRecord]) => {
  const booking = dsRecord.get();
  console.log(dsList.getEntries());
  console.log(booking.time, '-', booking.customer);
});

Argument	Type	Description
`listPath`	`string`	The path to the list.
`recordId`	`string`	The ID of the record.
`initiation`	`Object`	If created, initiate record with this.

`record.p.deleteDatasetRecord`

Alias: record.deleteDatasetRecordP

Removes both a record and its entry in the list, as created with getDatasetRecord.

client.record.p.deleteDatasetRecord('bookings', 'room-27').then(dsList => {
  console.log('List of records after delete:', dsList.getEntries());
});

Argument	Type	Default	Description
`listPath`	`string`		The path to the list.
`recordId`	`string`		The ID of the record.

Utility functions

These are not extensions of the client object, but freely importable functions.

`addEntry`

An alternative way to add entries to a deepstream list, that prevents duplicates.

See also above method record.p.addToList that utilizes this one.

import { addEntry } from 'extended-ds-client';

client.record.p.getExistingList('books')
  .then(dsList => addEntry(dsList, 'selfish-gene'));
  .catch(error => ...);

Argument	Type	Default	Description
`list`	`Object`		A DS List object.
`str`	`string`		The entry to add.

Licence

MIT

Change log

6.0

Removed \*ListedRecord in favor of new getDatasetRecord & deleteDatasetRecord
Name changes of options
- listedRecordFullPaths -> datasetRecordFullPaths
- listedRecordIdKey -> datasetRecordIdKey
Added a very versatile updateExistingRecord method
record.p.has now rejects on non-existent record

5.0

Added getListedRecord that returns list & record handles
- Will create both list & record if non-existent
- Consistent with original getList/getRecord
setListedRecord now only returns the record id
Added method deleteListedRecord
addToList & removeFromList now also accepts multiple entries
Options added that controls how *listedRecord operates
- datasetRecordFullPaths
- datasetRecordIdKey
- splitChar

4.0

New primary naming / method access, using p as scope
- Keeping old naming as aliases
Full test coverage
Much smaller footprint in node_modules
Dropping unofficial tenant extension
Dropping deprecated methods
Improved documentation with more examples/code

3.0

Methods added as polyfills
New method addToList
Re-exporting of deepstream client constants

Name		Name	Last commit message	Last commit date
Latest commit History 171 Commits
src		src
test		test
.babelrc		.babelrc
.editorconfig		.editorconfig
.eslintrc		.eslintrc
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

License

whitelizard/extended-ds-client

Folders and files

Latest commit

History

Repository files navigation

Extended Deepstream client

Install

Overview

Example 1

Example 2

Example 3

getClient

Promisification API

p.login

record.p.getRecord

record.p.getList

record.p.setData

record.p.snapshot

record.p.has

rpc.p.make

Additional API functions

record.p.getExistingRecord

record.p.getExistingList

record.p.deleteRecord

record.p.deleteList

record.p.addToList

record.p.removeFromList

record.p.updateExistingRecord

record.p.getDatasetRecord

record.p.deleteDatasetRecord

Utility functions

addEntry

Licence

Change log

6.0

5.0

4.0

3.0

Please create an Issue in github if you feel something is missing!

About

Resources