Skip to content

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

License

Notifications You must be signed in to change notification settings

canhazdb/client

Repository files navigation

canhazdb-client

GitHub code size in bytes GitHub package.json version GitHub js-semistandard-style

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.