simplebuild - npm Package Compare versions

Comparing version 0.4.0 to 0.5.0

build.js

@@ -16,3 +16,3 @@ #!/usr/local/bin/node
 	options: lintOptions(),
-	globals: {}
+	globals: lintGlobals()
 })
@@ -25,6 +25,6 @@ .then(function() {
 .then(function() {
-	console.log("\n\nOK");
+	console.log("\n\nBUILD OK");
 })
 .fail(function(message) {
-	console.log("\n\nFAILED: " + message);
+	console.log("\n\nBUILD FAILED: " + message);
 });
@@ -50,2 +50,14 @@
 	};
-}
+}
+
+function lintGlobals() {
+	return {
+		// Mocha
+		describe: false,
+		it: false,
+		before: false,
+		after: false,
+		beforeEach: false,
+		afterEach: false,
+	};
+}

Gruntfile.js

@@ -12,3 +12,3 @@ // Copyright (c) 2013 Titanium I.T. LLC. All rights reserved. See LICENSE.TXT for details.
 			options: lintOptions(),
-			globals: {}
+			globals: lintGlobals()
 		},
@@ -46,2 +46,14 @@
 
+	function lintGlobals() {
+		return {
+			// Mocha
+			describe: false,
+			it: false,
+			before: false,
+			after: false,
+			beforeEach: false,
+			afterEach: false,
+		};
+	}
+
 };

Jakefile.js

@@ -15,3 +15,3 @@ // Copyright (c) 2013 Titanium I.T. LLC. All rights reserved. See LICENSE.TXT for details.
 task("default", ["lint", "test"], function() {
-	console.log("\n\nOK");
+	console.log("\n\nBUILD OK");
 });
@@ -23,3 +23,3 @@
 	options: lintOptions(),
-	globals: {}
+	globals: lintGlobals()
 });
@@ -51,2 +51,14 @@
 	};
-}
+}
+
+function lintGlobals() {
+	return {
+		// Mocha
+		describe: false,
+		it: false,
+		before: false,
+		after: false,
+		beforeEach: false,
+		afterEach: false,
+	};
+}

lib/simplebuild.js

@@ -5,3 +5,17 @@ // Copyright (c) 2013 Titanium I.T. LLC. All rights reserved. See LICENSE.TXT for details.
 var glob = require("glob");
+var type = require("./type.js");
+var objectAssign = require("object-assign");   // Object.assign ponyfill. Check if Node supports it yet.
 
+exports.normalizeOptions = function(userOptions, defaults, types) {
+	check(userOptions, Object);
+	var normalizedOptions = objectAssign({}, defaults, userOptions);
+	check(normalizedOptions, types);
+	return normalizedOptions;
+
+	function check(options, types) {
+		var err = type.check(options, types, { name: "options" });
+		if (err !== null) throw new Error(err);
+	}
+};
+
 exports.deglobSync = function(globs) {
@@ -8,0 +22,0 @@ if (typeof globs === "string") globs = [ globs ];

package.json

 {
   "name": "simplebuild",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Universal task automation",
@@ -24,13 +24,17 @@ "main": "lib/simplebuild.js",
   "devDependencies": {
-    "jshint": "~2.3.0",
-    "mocha": "~1.15.0",
+    "chai": "^3.2.0",
     "expect.js": "~0.2.0",
+    "gaze": "^0.5.1",
+    "grunt": "~0.4.2",
+    "grunt-cli": "~0.1.11",
     "jake": "~0.7.6",
-    "grunt": "~0.4.2",
-    "grunt-cli": "~0.1.11"
+    "jshint": "~2.3.0",
+    "mocha": "~1.15.0"
   },
   "dependencies": {
-    "q": "~0.9.7",
-    "glob": "~3.2.7"
+    "array-to-sentence": "^1.0.1",
+    "glob": "~3.2.7",
+    "object-assign": "^4.0.1",
+    "q": "~0.9.7"
   }
 }

README.md

@@ -172,4 +172,5 @@ # Simplebuild - Universal Task Automation for Node.js
 
-Task module authors may wish to use this function:
+Task module authors may wish to use these functions:
  
+* `normalizeOptions(userOptions, defaults, types)`: Check the `userOptions` parameter provided to a simplebuild task.
 * `deglobSync(globs)`: Convert file globs into files.
@@ -183,2 +184,49 @@
 
+### `normalizeOptions(userOptions, defaults, types)`
+
+Applies defaults to a simplebuild task's `userOptions` argument and type-checks the result.
+
+* `userOptions`: The options passed into the task function. Must be an object.
+
+* `defaults`: The task's default options. Any parameter that's present in `defaults` but not in `userOptions` will be included in the final options object.
+
+* `types`: An object containing the expected types for each option. The parameters in this object correspond to the parameters in the options object. The types are checked on the final options object after the defaults are applied. Any fields that are in the final options and *not* in the `types` object will not be checked.
+
+    * To specify a **language type**, use the corresponding object constructor: `Boolean`, `String`, `Number`, `Object`, `Array`, or `Function`. For example, if your options include a "name" parameter that's a string, you would use `name: String`.
+
+    * To specify an **object type**, use the object constructor, such as `RegExp` or `Date`. You may also pass in the constructor for a custom subclass. For example, if your options object requires a "timestamp" parameter that's a Date object, you would use `timestamp: Date`.
+  
+    * To specify **specific object fields**, recursively provide another `types`-style object containing the fields you want to check. For example, if your options object requires a "report" object that contains a "verbose" boolean and a "filename" string, you would use `report: { verbose: Boolean, filename: String }`.
+  
+    * To specify **multiple valid types**, provide an array containing each type. For example, if your options object requires a "files" parameter that may be a string or an array, you would use `files: [ String, Array ]`.
+  
+    * To specify **optional, nullable, or NaN-able types**, put `undefined`, `null`, or `NaN` as one of the valid types in the array. For example, if your options object takes an optional "output" parameter that's a string, you would use `output: [ String, undefined ]`.
+  
+* **Returns**: The normalized options object, consisting of `userOptions` combined with `defaults`.
+ 
+* **Throws**: If the type check fails, an `Error` object will be thrown with a human-readable explanation of the type check failure in the `message` parameter. Note that simplebuild task functions are not allowed to throw exceptions, so be sure to catch errors and return `err.message` via the `fail` callback. 
+  
+**Example:**
+
+```javascript
+function myTask(userOptions, succeed, fail) {
+  try {
+    var defaults = {
+      timestamp: Date.now()
+    };
+    var types = {
+      files: [ String, Array ],
+      timestamp: Date,
+      output: [ String, undefined ]
+    };
+    var options = simplebuild.normalizeOptions(userOptions, defaults, types);
+   
+    // ... task implemented here ...
+  }
+  catch (err) {
+    return fail(err.message);
+  }
+}
+```
+
 ### `deglobSync(globs)`
@@ -236,9 +284,9 @@
 
-    exports.yourFunction = function(options, success, failure) { ... }
+    exports.yourFunction = function(options, succeed, fail) { ... }
 
 `options` (REQUIRED): Configuration information. Any type of variable may be used, but an object is recommended. If a task function has no configuration, this variable is still required, but may be ignored.
 
-`success()` (REQUIRED): Callback function. Each task function MUST call success() with no parameters when it finishes successfully.
+`succeed()` (REQUIRED): Callback function. Each task function MUST call succeed() with no parameters when it finishes successfully.
 
-`failure(messageString)` (REQUIRED): Callback function. Each task function MUST call failure() with a brief human-readable explanation when it fails. The explanation SHOULD be less than 50 characters.
+`fail(messageString)` (REQUIRED): Callback function. Each task function MUST call fail() with a brief human-readable explanation when it fails. The explanation SHOULD be less than 50 characters.
 
@@ -248,3 +296,3 @@
 
-Task functions MUST NOT return values or throw exceptions. Instead, either the `success()` or `failure()` callback MUST be called exactly once when the task is complete. The callback may be called synchronously or asynchronously.
+Task functions MUST NOT return values or throw exceptions. Instead, either the `succeed()` or `fail()` callback MUST be called exactly once when the task is complete. The callback may be called synchronously or asynchronously.
 
@@ -288,3 +336,3 @@ Tasks that fail SHOULD provide a detailed explanation suitable for debugging the problem. If the explanation is too long to fit in the 50-character failure mesage, the task SHOULD write the details to `process.stdout` before failing. (Note that calling `console.log()` is a convenient way of writing to `process.stdout`.)
 - Pull `__test_files.js` out of simplebuild-jshint into its own module or helper
-- Pull `expectSuccess()` and `expectFailure()` out of simplebuild-jshint (_index_test.js)
+- Pull `expectsucceed()` and `expectFailure()` out of simplebuild-jshint (_index_test.js)
 - The examples use an out-of-date version of the spec. In particular, they rely on descriptors, which have been removed from the spec for now.
@@ -295,2 +343,3 @@
 
+* 0.5.0: Added `normalizeOptions` API call
 * 0.4.0: Removed descriptors for now, updated documentation
@@ -297,0 +346,0 @@ * 0.3.0: Reworked descriptors

New alerts

Shell access

Supply chain risk

This module accesses the system shell. Accessing the system shell increases the risk of executing arbitrary code.

Found 1 instance in 1 package

Fixed alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

48472

increased by43.02%

Number of package files

25

increased by13.64%

Lines of code

806

increased by46.81%

Number of lines in readme file

383

increased by14.67%

Number of low supply chain risk alerts

3

decreased by-25%

Worsened metrics

Dependency count

4

increased by100%

Dev dependency count

8

increased by33.33%

Dependency changes

• + Addedarray-to-sentence@^1.0.1

• + Addedobject-assign@^4.0.1

• + Addedarray-to-sentence@1.1.0(transitive)

• + Addedobject-assign@4.1.1(transitive)