suricate

Module to assemble MongoDB documents containing references

3 years after

suricate

Module to assemble MongoDB documents containing references

require('suricate')

How to

  • any of Suricate.schema methods returns builder

    @typedef {Object} builder
    @property {buildEmbedder} build
    @property {projectBuilder} [project]
    @typedef {function} buildEmbedder - builds embedder
    @param {Object[]} documents - MongoDB documents
    @returns {embedder|undefined}
    @typedef {function} projectBuilder - rebuilds builder in runtime (if builder builds multiple fields)
    @param {projection} projection - MongoDB projection
    @returns {builder}
  • builder.build method returns embedder

    @typedef {Object} embedder
    @property {query} query - MongoDB query to find documents to be embedded
    @property {embedDocuments} embed
  • embedder.embed method embeds documents found using embedder.query

    @typedef {function} embedDocuments - embeds documents
    @param {Object[]} documents - MongoDB documents

Suricate.schema example

Suricate

require('suricate')(finder, graph);
@function Suricate - factory to build promises chain
@param {finder} finder
@param {graph|graph[]} graph
@returns {suricate}
  • finder - object to find MongoDB documents

    @typedef {Object} finder
    @property {thunk} find
  • thunk - function that returns Promise to find MongoDB documents

    @typedef {function} thunk
    @param {query} query
    @param {*} [any] - any other params to pass to every next thunk (finder.find)
    @returns {Object} instance of Promise which resolves to array (collection.find().toArray())
  • graph - configuration object to build promises chain

    @typedef {Object} graph
    @property {builder} builder
    @property {finder} finder
    @property {graph|graph[]} [next] - next graph (if array runs in parallel)
  • suricate - object to find and embed documents

    @typedef {Object} suricate
    @property {thunk} find
    @property {projectSuricate} project
  • suricate.find - finds MongoDB documents and embeds documents using promises chain built using graph

  • suricate.project - rebuilds suricate (promises chain) in runtime

    @typedef {function} projectSuricate
    @param {projection} projection
    @returns {suricate}
  • query - MongoDB query

    @typedef {Object} query
  • projection - MongoDB projection

    @typedef {Object} projection

suricate.find example #1, example #2

suricate.project example #1, example #2

Suricate.graph

require('suricate').graph;
@function graph - helper method to build graph by params
@param {builder} builder
@param {finder} finder
@param {graph|graph[]} [next] - object[s] built by Suricate.graph method
@returns {graph}

Suricate.graph example

Suricate.schema

require('suricate').schema;
@function schema - helper method to add Suricate.schema methods
@param {Object} methods
@param {function} methods.name - new Suricate.schema method
@returns {suricate}

Suricate.schema.oneToOne

@function oneToOne
@param {Object} opts
@param {Object} opts.by
@param {string} opts.by.key - key containing ObjectID
@param {queryProject|queryProjection} [opts.by.query] - function or query to identify object before embedding
@param {string} [opts.field = opts.by.key] - field to embed document
@param {string} [opts.prop] - embed document.prop instead of a document
@param {boolean} [opts.assign] - assign to opts.field instead of embedding
@returns {builder}

Suricate.schema.oneToOne example

Suricate.schema.oneToMany

@function oneToMany
@param {Object} opts
@param {Object} opts.by
@param {string} opts.by.key - key containing ObjectID
@param {queryProject|queryProjection} [opts.by.query] - function or query to identify object before embedding
@param {string} [opts.field = opts.by.key] - field to embed document
@param {string} [opts.prop] - embed document.prop instead of a document
@param {boolean} [opts.assign] - assign to opts.field instead of embedding
@returns {builder}

Suricate.schema.oneToMany example

Suricate.schema.oneByMany

@function oneByMany
@param {Object} opts
@param {Object} opts.to
@param {string} opts.to.key - key containing ObjectID
@param {query} opts.to.query = {} - query to identify to.key
@param {string} [opts.key = '_id'] - key containing ObjectID
@param {string} opts.field - field to embed document
@param {string} [opts.prop] - embed document.prop instead of a document
@returns {builder}

Suricate.schema.oneByMany example

Suricate.schema.manyByMany

@function manyByMany
@param {Object} opts
@param {Object} opts.to
@param {string} opts.to.key - key containing ObjectID
@param {query} opts.to.query = {} - query to identify to.key
@param {string} [opts.key = '_id'] - key containing ObjectID
@param {Object} opts.fields
@param {Object} opts.fields.any
@param {queryProject|queryProjection} opts.fields.any.query - function or query to identify object before embedding
@param {string} [opts.fields.any.prop] - embed document.prop instead of a document
@returns {builder}

Suricate.schema.manyByMany example

Suricate.schema.oneByOne

@function oneByOne
@param {Object} opts
@param {Object} opts.by
@param {string} opts.by.key - key containing ObjectID
@param {query} [opts.by.query = {}] - query to identify by.key
@param {Object} opts.to
@param {string} opts.to.key - key containing ObjectID
@param {query} [opts.to.query = {}] - query to identify to.key
@param {string} opts.field - field to embed document
@param {string} [opts.key = '_id'] - key containing ObjectID
@param {string} [opts.prop] - embed document.prop instead of a document
@param {*} [opts.v = 0] - default value if document not found or document.prop undefined
@returns {builder}

Suricate.schema.oneByOne example

Suricate.schema.oneByOneX

@function oneByOneX
@param {Object} opts
@param {Object} opts.by
@param {string} opts.by.key - key containing ObjectID
@param {query} [opts.by.query = {}] - query to identify by.key
@param {Object} opts.to
@param {string} opts.to.key - key containing ObjectID
@param {query} [opts.to.query = {}] - query to identify to.key
@param {string} opts.field - field to embed document 
@param {string} [opts.key = '_id'] - key containing ObjectID
@param {string} [opts.prop] - embed document.prop instead of a document
@param {*} [opts.v = 0] - default value if document not found or document.prop undefined
@returns {builder}

Suricate.schema.oneByOneX example

Suricate.schema.manyByOne

@function manyByOne
@param {Object} opts
@param {Object} opts.by
@param {string} opts.by.key - key containing ObjectID
@param {query} [opts.by.query = {}] - query to identify by.key
@param {Object} opts.to
@param {string} opts.to.key - key containing ObjectID
@param {query} [opts.to.query = {}] - query to identify to.key
@param {string} opts.fields - fields to embed document
@param {Object} opts.fields.any
@param {number} opts.fields.any.value - value to intersect with opts.prop
@param {string} [opts.key = '_id'] - key containing ObjectID
@param {string} opts.prop - document.prop to intersect with fields.any.value
@returns {builder}

Suricate.schema.manyByOne example

Suricate.schema.manyByOneX

@function manyByOneX
@param {Object} opts
@param {Object} opts.by
@param {string} opts.by.key - key containing ObjectID
@param {query} [opts.by.query = {}] - query to identify by.key
@param {Object} opts.to
@param {string} opts.to.key - key containing ObjectID
@param {query} [opts.to.query = {}] - query to identify to.key
@param {string} opts.fields - fields to embed document
@param {Object} opts.fields.any
@param {number} opts.fields.any.value - value to intersect with opts.prop
@param {string} [opts.key = '_id'] - key containing ObjectID
@param {string} opts.prop - document.prop to intersect with fields.any.value
@returns {builder}

Suricate.schema.manyByOneX example

Type definitions

  • queryProjection - MongoDB query with comparison, logical, array or $exists selectors to identify object before embedding
    @typedef {Object} queryProjection
  • queryProject - function to identify object before embedding
    @typedef {function} queryProject
    @param {Object} obj
    @returns {boolean}

Tests

  • set MONGODB_CONNECTION_STRING environment variable
  • run npm test

More examples