Factory

Quick and easy template scaffolding for Node

Installation

npm install factory

Example

var factory = require('factory');

var widgetFactory = factory({
	template: 'templates/widget',
	placeholders: [
		{
			name: 'foo',
			type: 'input',
			message: 'Enter a value for foo'
		},
		{
			name: 'bar',
			type: 'input',
			message: 'Enter a value for bar'
		}
	]
});

var options = {
	destination: 'app/widgets',
	overwrite: true,
};
var context = {
	foo: 'baz'
};

// Node-style callback interface
widgetFactory(options, context, function(error, results) {
	if (error) {
		console.error('Widget creation failed: ' + error);
	} else {
		console.info('Widget created successfully');
	}
});

// Promise interface
widgetFactory(options, context)
	.then(function(results) {
		console.info('Widget created successfully');
	}).catch(function(error) {
		console.error('Widget creation failed: ' + error);
	});

Contents of templates/widget/<%= foo %>.js:

module.exports = function <%= foo %>() {
	console.log('<%= bar %>');
};

Output at app/widgets/baz.js:

module.exports = function baz() {
	console.log('[user-prompted value]');
};

How it works

• Call the factory() function with the following parameters:
  • template: path to the template folder
  • placeholders: (optional) array of inquirer prompts used to gather data for injecting into templates
  • getContext: (optional) function that transforms placeholder values before they are passed to the template
• You can then call the function that is returned, specifying a destination path and any copy options, and optionally passing in a key/value object containing template placeholder values
• The user is prompted for the value of any placeholders which were not provided in the placeholder values object
• The files are copied from the template folder to the destination folder, replacing any placeholders in filenames and file content with the supplied values (using lodash template syntax)

Usage

factory(options)

Create a factory from an existing template

Template filenames/contents can use lodash template syntax to specify placeholder values. These are injected into the template when the factory function is invoked.

Options:

| Name | Type | Required | Default | Description | | ---- | ---- | -------- | ------- | ----------- | | template | string | Yes | N/A | Path to the template folder | | placeholders | Array | No | [] | Array of inquirer prompts used to gather data for injecting into templates | | getContext | function | No | null | Function that transforms placeholder values before they are passed to the template |

Notes:

• getContext has the following signature:

  function(context)

  Arguments:

  | Name | Type | Description | | ---- | ---- | ----------- | | context | object | Key/value object containing placeholder values, gathered from factory context and template placeholders |

  Returns:

  object Key/value object containing transformed context placeholder for use in templates

Returns:

• function(options, [context], [callback])

  Factory function used to create instances of the template

  The user will be prompted for the value of any placeholders which are not specified in the context object.

  Options:

  | Name | Type | Required | Default | Description | | ---- | ---- | -------- | ------- | ----------- | | options.destination | string | Yes | N/A | Destination directory for output files | | options.overwrite | boolean | No | false | Whether to overwrite existing files | | context | object | No | {} | Preset template placeholder values | | callback | function | No | null | Node-style callback that is invoked when the operation completes/fails |

  Returns:

  Promise<Array> Promise, fulfilled with array of copy results:

  [
  	{
  		"src": "/path/to/src",
  		"dest": "/path/to/dest",
  		"stats": <Stats>
  	},
  	{
  		"src": "/path/to/src/file.txt",
  		"dest": "/path/to/dest/file.txt",
  		"stats": <Stats>
  	},
  	{
  		"src": "/path/to/src/subfolder",
  		"dest": "/path/to/dest/subfolder",
  		"stats": <Stats>
  	},
  	{
  		"src": "/path/to/src/subfolder/nested.txt",
  		"dest": "/path/to/dest/subfolder/nested.txt",
  		"stats": <Stats>
  	}
  ]

Events

The value returned by the generated factory function implements the EventEmitter interface, and emits the following events:

| Event | Handler signature | | ----- | ----------------- | | factory.events.ERROR | function(error, ErrorInfo) | | factory.events.COMPLETE | function(Array<CopyOperation>) | | factory.events.CREATE_DIRECTORY_START | function(CopyOperation) | | factory.events.CREATE_DIRECTORY_ERROR | function(error, CopyOperation) | | factory.events.CREATE_DIRECTORY_COMPLETE | function(CopyOperation) | | factory.events.CREATE_SYMLINK_START | function(CopyOperation) | | factory.events.CREATE_SYMLINK_ERROR | function(error, CopyOperation) | | factory.events.CREATE_SYMLINK_COMPLETE | function(CopyOperation) | | factory.events.COPY_FILE_START | function(CopyOperation) | | factory.events.COPY_FILE_ERROR | function(error, CopyOperation) | | factory.events.COPY_FILE_COMPLETE | function(CopyOperation) |

...where the types referred to in the handler signature are as follows:

ErrorInfo

| Property | Type | Description | | -------- | ---- | ----------- | | src | string | Source path of the file/folder/symlink that failed to copy | | dest | string | Destination path of the file/folder/symlink that failed to copy |

CopyOperation

| Property | Type | Description | | -------- | ---- | ----------- | | src | string | Source path of the relevant file/folder/symlink | | dest | string | Destination path of the relevant file/folder/symlink | | stats | fs.Stats | Stats for the relevant file/folder/symlink |

Example: using events

var factory = require('factory');

var widgetFactory = factory({
	template: 'templates/widget'
});

var options = {
	destination: 'app/widgets'
};
var context = {};
widgetFactory(options, context)
	.on(factory.events.COPY_FILE_START, function(copyOperation) {
		console.info('Copying file ' + copyOperation.src + '...');
	})
	.on(factory.events.COPY_FILE_COMPLETE, function(copyOperation) {
		console.info('Copied to ' + copyOperation.dest);
	})
	.on(factory.events.ERROR, function(error, copyOperation) {
		console.error('Unable to copy ' + copyOperation.dest);
	})
	.then(function(results) {
		console.info('Widget created successfully');
	}).catch(function(error) {
		console.error('Widget creation failed: ' + error);
	});