README.md

canhazdb-client

A client to simplify making rest api calls by using database like functions.

Getting Started

You should create a server before trying to use the client.

Client

Connecting

const client = require('canhazdb-client');

const tls = {
  key: fs.readFileSync('./certs/localhost.privkey.pem'),
  cert: fs.readFileSync('./certs/localhost.cert.pem'),
  ca: [ fs.readFileSync('./certs/ca.cert.pem') ],
  requestCert: true /* this denys any cert not signed with our ca above */
};
const client = createClient('https://localhost:8063', { tls });

Making requests

const document = await client.post('tests', { a: 1 });
const changed = await client.put('tests', { id: document.id }, { query: { b: 2 } });
const changedDocument = await client.getOne('tests', { query: { id: document.id } });

Using events

// Capture an event based on regex
// client.on('.*:/tests/.*', ...)
// client.on('.*:/tests/uuid-uuid-uuid-uuid', ...)
// client.on('POST:/tests', ...)
// client.on('DELETE:/tests/.*', ...)
// client.on('(PUT|PATCH):/tests/uuid-uuid-uuid-uuid', ...)

client.on('POST:/tests/.*', (path, collectionId, resourceId, pattern) => {
  console.log(path) // === 'POST:/tests/uuid-uuid-uuid-uuid'
  console.log(collectionId) // === 'tests'
  console.log(resourceId) // === 'uuid-uuid-uuid-uuid'
  console.log(pattern) // === 'POST:/tests/.*'
})

console.log( {
  document, /* { a: 1 } */
  changed, /* { changes: 1 } */
  changedDocument, /* { b: 2 } */
})

Examples

1. Get item by id

client.get('tests', { 
  query: {
    id: 'example-uuid-paramater'
  }
});

2. Get document count in a collection

client.count('tests', {
  query: {
    firstName: 'Joe'
  }
});

3. Get items in a collection

client.get('tests', {
  query: {
    firstName: 'Joe'
  },
  limit: 10,
  order: 'desc(firstName)'
});

4. Create a new document in a collection

client.post('tests', {
  firstName: 'Joe'
});

5. Replace a document by id

client.put('tests', {
  firstName: 'Joe'
});

6. Replace multiple documents by query

client.put('tests', {
    firstName: 'Zoe',
    location: 'GB',
    timezone: 'GMT'
}, {
  query: {
    location: 'GB'
  }
});

7. Partially update multiple documents by id

client.patch('tests', {
    timezone: 'GMT'
}, {
  query: {
    location: 'GB'
  }
});

8. Partially update multiple documents by query

client.patch('tests', {
    timezone: 'GMT'
}, {
  query: {
    location: 'GB'
  }
});

9. Delete a document by id

client.delete('tests', {
  query: {
    id: 'example-uuid-paramater'
  }
});

10. Delete multiple documents by query

client.delete('tests', {
  query: {
    location: 'GB'
  }
});

11. Lock a collection/document/field combination

const lockId = await client.lock(['users']);

12. Release a lock

const lockId = await client.lock(['users']);
const newDocument = await client.post('users', {
  name: 'mark'
}, {
  lockId,
  lockStrategy: 'wait' // optional: can be 'fail' or 'wait'. default is 'wait'.
});
await client.unlock(lockId);

License

This project is licensed under the terms of the AGPL-3.0 license.