|
| 1 | +# feathers-ottoman |
| 2 | + |
| 3 | +__IMPORTANT__: This is still in early development stage, please report any issue found |
| 4 | + |
| 5 | +This library is written against [ottoman-2.0.0-beta.1](https://github.com/couchbaselabs/node-ottoman). It is tested against [Couchbase 7.0 BETA](https://docs.couchbase.com/server/7.0/introduction/intro.html) which supports [scope and collection](https://docs.couchbase.com/server/7.0/learn/data/scopes-and-collections.html) and it should work with current version, [Couchbase 6.6](https://docs.couchbase.com/server/current/introduction/intro.html) |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +A [Feathers](https://feathersjs.com) database adapter for [Ottoman](https://ottomanjs.com/), an object modeling tool for [Couchbase](https://www.couchbase.com/) |
| 10 | + |
| 11 | +```bash |
| 12 | +$ npm install feathers-ottoman |
| 13 | +``` |
| 14 | + |
| 15 | +> __Important:__ `feathers-ottoman` implements the [Feathers Common database adapter API](https://docs.feathersjs.com/api/databases/common.html) and [querying syntax](https://docs.feathersjs.com/api/databases/querying.html) |
| 16 | +
|
| 17 | +> This adapter also requires a [running Couchbase](https://docs.couchbase.com/tutorials/getting-started-ce/index.html) database server |
| 18 | +
|
| 19 | +## API |
| 20 | + |
| 21 | +### `service([options])` |
| 22 | + |
| 23 | +Returns a new service instance initialized with the given options. `Model` has to be a `Ottoman` model. See the [Ottoman Guide](https://ottomanjs.com/guides/schema.html#defining-your-schema) for more information on defining your model |
| 24 | + |
| 25 | +```js |
| 26 | +// commonjs |
| 27 | +const service = require('feathers-ottoman'); |
| 28 | +// es6 / typescript |
| 29 | +import { service } from 'feathers-ottoman'; |
| 30 | + |
| 31 | +app.use('/messages', service({ Model })); |
| 32 | +app.use('/messages', service({ Model, id, events, paginate, ottoman: { lean, consistency } })); |
| 33 | +``` |
| 34 | + |
| 35 | +__Options:__ |
| 36 | + |
| 37 | +- `Model` (**required**) - The Ottoman model definition |
| 38 | +- `id` (*optional*, default: `'id'`) - The name of the id field property. Note that the `id` has to be also define when initializing the `Ottoman Model` if not using default value |
| 39 | +- `events` (*optional*) - A list of [custom service events](https://docs.feathersjs.com/api/events.html#custom-events) sent by this service |
| 40 | +- `paginate` (*optional*) - A [pagination object](https://docs.feathersjs.com/api/databases/common.html#pagination) containing a `default` and `max` page size |
| 41 | +- `whitelist` (*optional*) - A list of additional query parameters to allow |
| 42 | +- `multi` (*optional*) - Allow `create` with arrays and `update` and `remove` with `id` `null` to change multiple items. Can be `true` for all methods or an array of allowed methods (e.g. `[ 'remove', 'create' ]`) |
| 43 | +- `ottoman.lean` (*optional*, default: `true`) - Runs queries faster by returning plain objects instead of `Ottoman Model` |
| 44 | +- `ottoman.consistency` (*optional*, default: `NONE`) - Define default [Search Consistency Strategy](https://docs.couchbase.com/server/current/learn/services-and-indexes/indexes/index-replication.html#index-consistency) |
| 45 | + |
| 46 | +> **Note:** You can get access to the Ottoman model via `this.Model` inside a [hook](https://docs.feathersjs.com/api/hooks.html) and use it as usual. See the [Ottoman Guide](https://ottomanjs.com/guides/schema.html#defining-your-schema) for more information on defining your model |
| 47 | +
|
| 48 | +## Example |
| 49 | + |
| 50 | +Here is an example of a Feathers server with a `messages` Ottoman service |
| 51 | + |
| 52 | +``` |
| 53 | +$ npm install @feathersjs/feathers @feathersjs/express ottoman feathers-ottoman |
| 54 | +``` |
| 55 | + |
| 56 | +In `index.js`: |
| 57 | + |
| 58 | +```js |
| 59 | +// Initialize Ottoman connection |
| 60 | +const { Ottoman, getModel, Schema, SearchConsistency } = require('ottoman'); |
| 61 | + |
| 62 | +const ottoman = new Ottoman(); |
| 63 | + |
| 64 | +ottoman.connect({ |
| 65 | + connectionString: 'couchbase://localhost', |
| 66 | + bucketName: 'messageBucket', |
| 67 | + username: 'user', |
| 68 | + password: 'password', |
| 69 | +}); |
| 70 | + |
| 71 | +const modelOptions = { |
| 72 | + // specify `idKey` if not using default |
| 73 | + // idKey: 'customId', |
| 74 | + scopeName: 'messageScope', |
| 75 | + collectionName: 'messageCollection', |
| 76 | +}; |
| 77 | + |
| 78 | +const schema = new Schema({ |
| 79 | + text: { type: String }, |
| 80 | +}); |
| 81 | + |
| 82 | +ottoman.model('message', schema, modelOptions); |
| 83 | + |
| 84 | +ottoman.start(); |
| 85 | + |
| 86 | +// Setup feathers service |
| 87 | +const feathers = require('@feathersjs/feathers'); |
| 88 | +const express = require('@feathersjs/express'); |
| 89 | + |
| 90 | +const { Service } = require('feathers-ottoman'); |
| 91 | + |
| 92 | +// Creates an ExpressJS compatible Feathers application |
| 93 | +const app = express(feathers()); |
| 94 | + |
| 95 | +// Parse HTTP JSON bodies |
| 96 | +app.use(express.json()); |
| 97 | +// Parse URL-encoded params |
| 98 | +app.use(express.urlencoded({ extended: true })); |
| 99 | +// Host static files from the current folder |
| 100 | +app.use(express.static(__dirname)); |
| 101 | +// Add REST API support |
| 102 | +app.configure(express.rest()); |
| 103 | +// Register a Ottoman message service |
| 104 | +app.use('/messages', new Service({ |
| 105 | + Model: getModel('message'), |
| 106 | + // if `idKey` is specify for the Model |
| 107 | + // id: 'customid', |
| 108 | + ottoman: { |
| 109 | + lean: true, |
| 110 | + consistency: SearchConsistency.LOCAL, |
| 111 | + }, |
| 112 | + paginate: { |
| 113 | + default: 10, |
| 114 | + max: 100 |
| 115 | + } |
| 116 | +})); |
| 117 | +// Register a nicer error handler than the default Express one |
| 118 | +app.use(express.errorHandler()); |
| 119 | + |
| 120 | +// Create a dummy Message |
| 121 | +app.service('messages').create({ |
| 122 | + text: 'Message created on Ottoman server' |
| 123 | +}).then(function(message) { |
| 124 | + console.log('Created messages', message); |
| 125 | +}); |
| 126 | + |
| 127 | +app.listen(3030).on('listening', () => console.log('feathers-ottoman example started')); |
| 128 | +``` |
| 129 | + |
| 130 | +Run the example with `node .` and go to [localhost:3030/messages](http://localhost:3030/messages) |
| 131 | + |
| 132 | +For a complete example, take a look at [feathers-ottoman-demo](https://github.com/bwgjoseph/feathers-ottoman-demo) repository |
| 133 | + |
| 134 | +## License |
| 135 | + |
| 136 | +Copyright (c) 2021 |
| 137 | + |
| 138 | +Licensed under the [MIT license](LICENSE). |
0 commit comments