api.md

« back to README

Unionized API

The unionized module exports an instance of the Factory class:

var factory = require('unionized');

---

Factory

Factory contains the following public methods:

Method	Description
factory.factory()	Build a new factory as a child of the current factory
factory.create()	Create an object using this factory
factory.createAsync()	Create an object using this factory, asynchronously

Additionally, every instance of Factory contains the following utility methods:

Method	Description
factory.array()	Describe the contents of an array that a factory can create
factory.async()	Define an asynchronous and dynamically-generated factory attribute
factory.enum()	Define a list of options for a factory attribute
factory.mongooseFactory()	Build a new factory out of a mongoose model

Factory is a subtype of Definition — which means you can embed factories inside other factories. More on this later.

---

factory.factory()

Build a new factory out of a Definition. Returns another instance of Factory.

Usage:

var factory = parentFactory.factory(definition)

Example:

The most common type of Definition to use here is a DotNotationObjectDefinition, which can be coerced from an Object like in the following example:

var factory = require('unionized');
var blogFactory = factory.factory({
  title: 'How to make falafel'
  body: loremIpsumGenerator
  'metadata.tags': ['cooking', 'middle-eastern']
})

Once you have defined your Factory, you can call create() or createAsync() on it to make it create an object, or you can call factory() on it again to create a (generally more specific) variation on the Factory you already have. For example:

var blogByNatsumiFactory = blogFactory.factory({
  'metadata.author': 'Natsumi'
})

Now, creating an instance out of blogByNatsumiFactory will give you a blog entry that looks like the following:

blogByNatsumiFactory.create() // =>
{
  title: 'How to make falafel',
  body: 'Lorem ipsum dolor sit amet',
  metadata: {
    tags: ['cooking', 'middle-eastern'],
    author: 'Natsumi'
  },
}

---

factory.create()

Create an instance using this Factory. In most cases, this creates an instance of Object, but that depends on the Definitions that were used to build up the Factory. Optionally, also accepts a Definition that can be used to override existing values or add new values to the created instance.

Usage:

var instance = factory.create()
var instance = factory.create(definition)

Example:

If we're starting with a Factory that's alredy been created:

var factory = require('unionized');
var creditCardFactory = factory.factory({
  type: 'Visa',
  last4: '1111',
  'exp.month': '04'
  'exp.year': '15'
})

...then you can create an instance and override things with create():

var card = creditCardFactory.create({
  name: 'Chloris Elisaveta'
  'exp.year': '17'
}) // =>
{
  type: 'Visa',
  last4: '1111',
  exp: {
    month: '04'
    year: '17'
  },
  name: 'Chloris Elisaveta'
}

If any of the Definitions that make up the Factory are asynchronous, you should use factory.createAsync(); using factory.create() will throw an exception.

---

factory.createAsync()

Create an object asynchronously, using this Factory. This method returns a Promise for an instance. In most cases, the instance will be an Object, but that depends on the Definitions that were used to build up the Factory. Optionally, accepts a Definition that can be used to override existing values or add new values to the created instance. Optionally, also accepts a traditional Node-style callback function which returns the instance.

This method can be used with a factory whose Definitions are entirely synchronous, or with an object whose Definitions are asynchronous — in either case, createAsync() will do its work asynchronously.

Usage:

// Promises
factory.createAsync().then(function(instance) { /* ... */ })
factory.createAsync(definition).then(function(instance) { /* ... */ })

// Callbacks
factory.createAsync(function(err, instance) { /* ... */ })
factory.createAsync(definition, function(err, instance) { /* ... */ })

Example:

If we're starting with a Factory that's already been created:

var factory = require('unionized');
var request = require('request');
var quoteSource = 'http://www.iheartquotes.com/api/v1/random';
var quoteFactory = factory.factory({
  content: factory.async(function (done) {
    request(quoteSource, function(err, response, body) { done(err, body) });
  }),
  source: quoteSource
});

...then you can create an instance and override things with createAsync() (using the promise syntax):

var promise = quoteFactory.createAsync({createdAt: new Date()})
promise.then(function (quote) {
  quote // =>
  {
    content: "A man who turns green has eschewed protein.",
    source: "http://www.iheartquotes.com/api/v1/random",
    createdAt: '2015-05-18T06:17:16.989Z'
  }
})

Alternatively, here's the same example using node-style callbacks:

quoteFactory.createAsync({createdAt: new Date()}, function (err, quote) {
  quote // =>
  {
    content: "The best laid plans of mice and men are usually about equal."
    source: "http://www.iheartquotes.com/api/v1/random",
    createdAt: '2015-05-18T06:17:16.989Z'
  }
})

---

factory.array()

Terse syntax to create an ArrayDefinition. Allows you to specify an array by describing an object to repeat, and a default length.

Usage:

var arrayDefinition = factory.array(definition, length)

Example:

Here is a factory for a carton of green eggs:

var factory = require('unionized');
var eggCartonFactory = factory.factory({
  eggs: factory.array({shellColor: 'ecru', yolkColor: 'yellow'}, 12)
})
eggCartonFactory.create() // =>
{
  eggs: [
    { shellColor: 'ecru', yolkColor: 'yellow' }
    { shellColor: 'ecru', yolkColor: 'yellow' }
    { shellColor: 'ecru', yolkColor: 'yellow' }
    { shellColor: 'ecru', yolkColor: 'yellow' }
    { shellColor: 'ecru', yolkColor: 'yellow' }
    { shellColor: 'ecru', yolkColor: 'yellow' }
    { shellColor: 'ecru', yolkColor: 'yellow' }
    { shellColor: 'ecru', yolkColor: 'yellow' }
    { shellColor: 'ecru', yolkColor: 'yellow' }
    { shellColor: 'ecru', yolkColor: 'yellow' }
    { shellColor: 'ecru', yolkColor: 'yellow' }
    { shellColor: 'ecru', yolkColor: 'yellow' }
  ]
}

Here we create a half-carton with one green egg:

eggCartonFactory.create({'eggs[]': 6, 'eggs[1].shellColor': 'green'}) // =>
{
  eggs: [
    { shellColor: 'ecru', yolkColor: 'yellow' }
    { shellColor: 'green', yolkColor: 'yellow' }
    { shellColor: 'ecru', yolkColor: 'yellow' }
    { shellColor: 'ecru', yolkColor: 'yellow' }
    { shellColor: 'ecru', yolkColor: 'yellow' }
    { shellColor: 'ecru', yolkColor: 'yellow' }
  ]
}

---

factory.async()

Create an asynchronous factory definition using node-style callbacks.

Usage:

var asyncDefinition = factory.async(function(done) { done(error, definition) })

Example:

Let's say we want to grab the contents of a file in a factory:

var factory = require('unionized');
var fs = require('fs');
var fileFactory = factory.factory({
  name: 'paul-clifford.txt'
  contents: factory.async(function(done) {
    fs.readFile('paul-clifford.txt', {encoding: 'utf-8'}, done)
  })
});
fileFactory.createAsync(function(err, file) {
  file // =>
  {
    name: 'paul-clifford.txt',
    contents: 'It was a dark and stormy night; the rain fell in torrents...'
  }
})

---

factory.enum()

---

factory.mongooseFactory()

---

Definition