enju v5.3.0

enju

An elasticsearch client on node.js written in CoffeeScript.
Enju provides a simple way to define mapping and access data.

Installation

$ npm install enju --save

Config

enju use node-config.
/your_project/config/default.json
Read more elasticsearch config at here:
https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/configuration.html

{
    "enju": {
        "indexPrefix": "",
        "elasticsearchConfig": {
            "apiVersion": "5.6",
            "host": "http://localhost:9200"
        }
    }
}

Quick start

1. Define models

enju = require 'enju'
class UserModel extends enju.Document
    @_index = 'users'  # your index name
    @_settings =
        analysis:
            analyzer:
                email_url:
                    type: 'custom'
                    tokenizer: 'uax_url_email'
    @define
        name: new enju.KeywordProperty
            required: yes
        email: new enju.TextProperty
            required: yes
            analyzer: 'email_url'
        createTime: new enju.DateProperty
            autoNow: yes
            dbField: 'create_time'
class ProductModel extends enju.Document
    @_index = 'products'
    @define
        user: new enju.ReferenceProperty
            referenceClass: UserModel
            required: yes
        title: new enju.KeywordProperty
            required: yes

2. Update elasticsearch mapping

UserModel.updateMapping()
ProductModel.updateMapping()

3. Insert documents

user = new UserModel
    name: 'Kelp'
    email: 'kelp@phate.org'
user.save().then (user) ->
    product = new ProductModel
        user: user
        title: 'enju'
    product.save()

4. Fetch documents

ProductModel.where('title', '==': 'enju').fetch().then (result) ->
    console.log JSON.stringify(result.items, null, 4)
    # [{
    #     "id": "AU-mMiIwtrhIjlPeQBbT",
    #     "version": 1,
    #     "user": {
    #         "id": "AU-mMiIOtrhIjlPeQBbS",
    #         "version": 1,
    #         "name": "Kelp",
    #         "email": "kelp@phate.org",
    #         "createTime": "2015-09-07T05:05:47.500Z"
    #     },
    #     "title": "enju"
    # }]

Develop

# install dependencies
npm install -g grunt-cli
npm install

# compile and watch
grunt dev

# build CoffeeScript
npm run build

# run test
npm run build
npm test

Document

# CoffeeScript
enju = require 'enju'
class UserModel extends enju.Document
    @_index = 'users'  # your index name
    @_settings =
        analysis:
            analyzer:
                email_url:
                    type: 'custom'
                    tokenizer: 'uax_url_email'
    @define
        name: new enju.KeywordProperty
            required: yes
        email: new enju.TextProperty
            required: yes
            analyzer: 'email_url'
        createTime: new enju.DateProperty
            autoNow: yes
            dbField: 'create_time'

// JavaScript
var enju = require('enju');
var UserModel = enju.Document.define('UserModel', {
    _index: 'users',
    _settings: {
        analysis: {
            analyzer: {
                email_url: {
                    type: 'custom',
                    tokenizer: 'uax_url_email'
                }
            }
        }
    },
    name: new enju.KeywordProperty({
        required: true
    }),
    email: new enju.TextProperty({
        required: true,
        analyzer: 'email_url'
    }),
    createTime: new enju.DateProperty({
        autoNow: true,
        dbField: 'create_time'
    })
});

Properties

class Document
    ###
    _index {string} You can set index name by this attribute. **constructor property**
    _type {string} You can set type of the document. The default is class name. **constructor property**
    _settings {object} You can set index settings by this attribute. **constructor property**
    id {string}
    version {number}
    ###

Class method

@get = (ids, fetchReference=yes) ->
    ###
    Fetch the document with id or ids.
    If the document is not exist, it will return null.
    @param ids {string|list}
    @param fetchReference {bool} Fetch reference data of this document.
    @returns {promise<Document>}
    ###
# ex: Document.get('MQ-ULRSJ291RG_eEwSfQ').then (result) ->
# ex: Document.get(['MQ-ULRSJ291RG_eEwSfQ']).then (result) ->

@exists = (id) ->
    ###
    Is the document exists?
    @param id {string} The documents' id.
    @returns {promise<bool>}
    ###

@all = ->
    ###
    Generate a query for this document.
    @returns {Query}
    ###
# ex: query = Document.all()

@where = (field, operation) ->
    ###
    Generate the query for this document.
    @param field {string|function}
        string: The property name of the document.
        function: The sub query.
    @param operation {object}
        key: [
            '!=', 'unequal'
            '==', 'equal'
            '<', 'less'
            '<=', 'lessEqual'
            '>', 'greater',
            '>=', 'greaterEqual'
            'like'
            'unlike'
            'contains'
            'exclude'
        ]
    @returns {Query}
    ###
# ex: query = Document.where('field', '==': 'value')

@refresh = (args) ->
    ###
    Explicitly refresh one or more index.
    https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/api-reference-5-6.html#api-indices-refresh-5-6
    @params args {object}
    @returns {promise}
    ###

@updateMapping = ->
    ###
    Update the index mapping.
    https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-update-settings.html
    https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-put-mapping.html
    @returns {promise}
    ###

Method

save: (refresh=no) ->
    ###
    Save this document.
    @param refresh {bool} Refresh the index after performing the operation.
    @returns {promise<Document>}
    ###

delete: (refresh=no) ->
    ###
    Delete this document.
    @returns {promise<Document>}
    ###

Property

class Property
    ###
    @property default {any}
    @property required {bool}
    @property dbField {string}
    @property type {string}  https://www.elastic.co/guide/en/elasticsearch/reference/5.6/mapping-types.html
    @property index {bool}  https://www.elastic.co/guide/en/elasticsearch/reference/5.6/mapping-index.html
    @property mapping {object}  https://www.elastic.co/guide/en/elasticsearch/reference/5.6/mapping.html
    @property propertyName {string} The property name in the document. It will be set at Document.define()
    ###

class StringProperty extends Property
    ###
    https://www.elastic.co/guide/en/elasticsearch/reference/5.6/analyzer.html
    @property analyzer {string}
    ###

class TextProperty extends Property
    ###
    https://www.elastic.co/guide/en/elasticsearch/reference/5.6/analyzer.html
    @property analyzer {string}
    ###

class KeywordProperty extends Property
    ###
    https://www.elastic.co/guide/en/elasticsearch/reference/5.6/analysis-normalizers.html
    @property normalizer {string}
    ###

class IntegerProperty extends Property

class FloatProperty extends Property

class BooleanProperty extends Property

class DateProperty extends Property
    ###
    @property autoNow {bool}
    ###

class ListProperty extends Property
    ###
    @property itemClass {constructor}
    ###

class ObjectProperty extends Property

class ReferenceProperty extends Property
    ###
    @property referenceClass {Property}
    ###

Query

The enju query.

Methods

where: (field, operation) ->
    ###
    Append a query as intersect.
    @param field {string|function}
        string: The property name of the document.
        function: The sub query.
    @param operation {object}
        key: [
            '!=', 'unequal'
            '==', 'equal'
            '<', 'less'
            '<=', 'lessEqual'
            '>', 'greater',
            '>=', 'greaterEqual'
            'like'
            'unlike'
            'contains'
            'exclude'
        ]
    @returns {Query}
    ###

union: (field, operation) ->
    ###
    Append a query as intersect.
    @param field {string} string: The property name of the document.
    @param operation {object}
        key: [
            '!=', 'unequal'
            '==', 'equal'
            '<', 'less'
            '<=', 'lessEqual'
            '>', 'greater',
            '>=', 'greaterEqual'
            'like'
            'unlike'
            'contains'
            'exclude'
        ]
    @returns {Query}
    ###

orderBy: (field, descending=no) ->
    ###
    Append the order query.
    @param field {string} The property name of the document.
    @param descending {bool} Is sorted by descending?
    @returns {Query}
    ###

fetch: (args={}) ->
    ###
    Fetch documents by this query.
    @param args {object}
        limit: {number} The size of the pagination. (The limit of the result items.) default is 1000
        skip: {number} The offset of the pagination. (Skip x items.) default is 0
        fetchReference: {bool} Fetch documents of reference properties. default is true.
    @returns {promise<object>} ({items: {Document}, total: {number}})
    ###

first: (fetchReference=yes) ->
    ###
    Fetch the first document by this query.
    @param fetchReference {bool}
    @returns {promise<Document|null>}
    ###

count: ->
    ###
    Count documents by the query.
    @returns {promise<number>}
    ###

sum: (field) ->
    ###
    Sum the field of documents by the query.
    https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-metrics-sum-aggregation.html
    @param field {string} The property name of the document.
    @returns {promise<number>}
    ###

groupBy: (field, args) ->
    ###
    @param field {string} The property name of the document.
    @param args {object}
        limit: {number}  Default is 1,000.
        order: {string} "count|term"  Default is "term".
        descending: {bool}  Default is no.
    @returns {promise<list<object>>}
        [{
            doc_count: {number}
            key: {string}
        }]
    ###

Example

select * from "ExampleModel" where "name" = "tina"

ExampleModel.where('name', equal: 'tina').fetch().then (result) ->

select * from "ExampleModel" where "name" = "tina" and "email" = "kelp@phate.org"

ExampleModel.where('name', equal: 'enju')
    .where('email', equal: 'kelp@phate.org')
    .fetch().then (result) ->

select * from "ExampleModel" where "name" like "%tina%" or "email" like "%tina%"

ExampleModel.where (query) ->
    query.where('name', like: 'tina').union('email', like: 'tina')
.fetch().then (result) ->

select * from "ExampleModel" where "category" = 1 or "category" = 3
    order by "created_at" limit 20 offset 20

ExampleModel.where('category', contains: [1, 3])
    .orderBy('created_at')
    .fetch(20, 20).then (result) ->

Fetch the first item.

select * from "ExampleModel" where "age" >= 10
     order by "created_at" desc limit 1

ExampleModel.where('age', '>=': 10)
    .orderBy('created_at', yes).first().then (model) ->

Count items.

select count(*) from "ExampleModel" where "age" < 10

ExampleModel.where('age', less: 10).count().then (result) ->