blork - npm Package Compare versions

Comparing version 1.1.2 to 1.1.3

lib/blork.js

@@ -22,3 +22,3 @@ "use strict";
     if (argsObj.length > l) {
-        throw new errorConstructor(helpers_1.format(`Must not have more than ${l} arguments`, argsObj.length, 'arguments'));
+        throw new errorConstructor(helpers_1.format(`Too many arguments (expected ${l})`, argsObj.length, 'arguments'));
     }
@@ -25,0 +25,0 @@ return pass;

lib/internal.js

@@ -74,3 +74,3 @@ "use strict";
             if (value.length > l)
-                throw new err(helpers_1.format(`Must not have more than ${l} array items`, value.length, prefix));
+                throw new err(helpers_1.format(`Too many array items (expected ${l})`, value.length, prefix));
         }
@@ -77,0 +77,0 @@ return pass;

package.json

 {
 	"name": "blork",
-	"description": "Blork! Mini (non-static) argument checking in Javascript",
-	"version": "1.1.2",
+	"description": "Blork! Mini runtime type checking in Javascript",
+	"version": "1.1.3",
 	"license": "0BSD",
@@ -6,0 +6,0 @@ "author": "Dave Houlbrooke <[e-mail]>",

README.md

@@ -1,2 +0,2 @@
-# Blork! Mini (non-static) argument checking in Javascript
+# Blork! Mini runtime type checking in Javascript
 
@@ -11,3 +11,3 @@ [![Build Status](https://travis-ci.org/dhoulb/blork.svg?branch=master)](https://travis-ci.org/dhoulb/blork)
 
-```
+```sh
 npm install blork
@@ -18,8 +18,8 @@ ```
 
-### Checking function arguments
+### args(): Check function arguments
 
 The primary use case of Blork is validating function input arguments. The `args()` function is provided for this purpose, and should be passed two arguments:
 
-1. `arguments` — The **arguments** object provided automatically to functions in Javascript
-2. `types` — An array identifying the types for the arguments (list of types is available below)
+1. `arguments` | The **arguments** object provided automatically to functions in Javascript
+2. `types` | An array identifying the types for the arguments (list of types is available below)
 
@@ -47,13 +47,13 @@ ```js
 myFunc(); // Throws TypeError "arguments[0]: Must be string (received undefined)"
-myFunc('abc', 123, true); // Throws TypeError "Too many arguments (expected 2 but received 3)"
+myFunc('abc', 123, true); // Throws TypeError "arguments: Too many arguments (expected 2) (received 3)"
 ```
 
-### Checking individual values
+### check(): Check individual values
 
-The `args()` function is a convenient wrapper for the `check()` function, which allows you to test individual values and more. The `check()` function is more versatile and allows more use cases than validating function input arguments.
+The `check()` function allows you to test individual values with more granularity. The `check()` function is more versatile and allows more use cases than validating function input arguments.
 
 `check()` can be passed three arguments:
 
-1. `value` — The value to check
-2. `type` — The type to check the value against (list of types is available below)
+1. `value` | The value to check
+2. `type` | The type to check the value against (list of types is available below)
 3. An optional string name for the value, which is prepended to any error message thrown to help debugging
@@ -64,13 +64,16 @@
 
-// Check that passes.
+// Checks that pass.
 check('Sally', 'string'); // Returns 1
+check('Sally', String); // Returns 1
 
-// Check that fails.
+// Checks that fail.
 check('Sally', 'number'); // Throws TypeError "Must be a number (received 'Sally')"
+check('Sally', Boolean); // Throws TypeError "Must be true or false (received 'Sally')"
 
-// Check that fails (with a name set).
-check('Sally', 'number', 'name'); // Throws TypeError "name: Must be a number (received 'Sally')"
+// Checks that fail (with a name set).
+check('Sally', 'num', 'name'); // Throws TypeError "name: Must be a number (received 'Sally')"
+check(true, 'str', 'status'); // Throws TypeError "status: Must be a string (received true)"
 ```
 
-### Optional values
+### Checking optional values
 
@@ -80,6 +83,6 @@ Appending `?` question mark to any type string makes it optional. This means it will accept `undefined` in addition to the specified type.
 ```js
-// This check fails.
-check(undefined, 'number'); // Throws TypeError "Must be a number (received 'Sally')"
+// This check fails because it's not optional.
+check(undefined, 'number'); // Throws TypeError "Must be a number (received undefined)"
 
-// This check passes (because it's optional).
+// This check passes because it's optional.
 check(undefined, 'number?'); // Returns 0
@@ -91,7 +94,7 @@
 
-_`check()` and `args()` return the number of defined values that passed their tests. i.e. If a single-value check doesn't throw an error because it's optional, it will return `0` as shown above._
+_`check()` and `args()` return the number of **defined** values that passed. i.e. If a check passes because it's optional it will return `0` as shown above._
 
 ### Checking objects and arrays
 
-Blork can perform deep checks on objects and arrays to ensure the schema is correct _all_ the way down. To use this pass an array or object `check()` (or to to `args()`).
+Blork can perform deep checks on objects and arrays to ensure the schema is correct. To do object or array checks pass literal arrays or literal objects to `check()` or `args()`:
 
@@ -103,3 +106,3 @@ ```js
 // Check all array items.
-check(['Sally', 'John', 'Sonia'], ['string']); // Returns 3
+check(['Sally', 'John', 'Sonia'], ['str']); // Returns 3
 
@@ -109,15 +112,43 @@ // Check tuple-style array.
 
-// Check deep object properties.
+// Failing checks.
+check({ name: 'Sally' }, { name: 'string' }); // Returns 1
+check(['Sally', 'John', 'Sonia'], ['str']); // Returns 3
+check([1029, 'Sonia'], ['number', 'string']); // Returns 2
+check([1029, 'Sonia', true], ['number', 'string']); // Throws TypeError: "Array: Too many array items (expected 2) (received 3)"
+```
+
+Arrays and objects can be deeply nested within each other and Blork will recursively check the schema _all_ the way down:
+
+```js
+// Deeply nested check (passes).
+// Will return 1
 check(
-	{ owner: { id: 1028, name: 'Sally' }},
-	{ owner: { id: 'num', name: 'str' }}
-);
+	[
+		{ id: 1028, name: 'Sally', status: [1, 2, 3] },
+		{ id: 1062, name: 'Bobby', status: [1, 2, 3] }
+	],
+	[
+		{ id: Number, name: String, status: [Number] }
+	]
+); 
+
+// Deeply nested check (fails).
+// Will throw TypeError "Array[1][status][2]: Must be a number (received 'not_a_number')"
+check(
+	[
+		{ id: 1028, name: 'Sally', status: [1, 2, 3] },
+		{ id: 1062, name: 'Bobby', status: [1, 2, 'not_a_number'] }
+	],
+	[
+		{ id: Number, name: String, status: [Number] }
+	]
+); 
 ```
 
-### Add a custom checker
+### add(): Add a custom checker type
 
-Register your own checker using the `add()` function. If you're going to be applying the same check over and over and want to make sure your error messages are consistent, or want your custom type to clean and integrated with our built-in types, this is a great way to go.
+Register your own checker using the `add()` function. If you're going to be applying the same check over and over and want a custom type that's integrated with Blork's built-in types and has consistent error messages, this is a great way to go.
 
 ```js
-import { add, check, args } from 'blork';
+import { add, check } from 'blork';
 
@@ -130,6 +161,12 @@ // Register your new checker.
 
-// Check some strings with your checker.
+// Passes.
 check('That cat is having fun', 'catty'); // Returns 1.
+
+// Fails.
 check('A dog sits on the chair', 'catty'); // Throws TypeError "Must be a string containing 'cat' (received 'A dog sits on the chair')"
+```
 
+```js
+import { add, args } from 'blork';
+
 // Use your checker to check function args.
@@ -142,10 +179,12 @@ function myFunc(str)
 
-// Try out your custom function.
+// Passes.
 myFunc('That cat is chasing string'); // Returns "It passed!"
+
+// Fails.
 myFunc('A dog sits over there'); // Throws TypeError "arguments[1]: Must be a string containing 'cat' (received 'A dog sits over there')"
 ```
 
-### Custom error type
+### throws(): Set a custom error constructor
 
-To change the error type Blork throws when a type doesn't match, use the `throws()` function.
+To change the error object Blork throws when a type doesn't match, use the `throws()` function.
 
@@ -169,38 +208,40 @@ ```js
 
-- `null` — Value is **null**
-- `undefined`,`undef`,`void` — Value is **undefined**
-- `defined`,`def` — Value is **not undefined**
-- `boolean`,`bool` — Value is **true** or **false**
-- `true` — Value is **true**
-- `false` — Value is **false**
-- `truthy` — Truthy values (i.e. **== true**)
-- `falsy` — Falsy values (i.e. **== false**)
-- `number`,`num` — Numbers (using **typeof**)
-- `integer`,`int` — Integers (using **Number.isInteger()**)
-- `natural` — Natural numbers **(1, 2, 3...)**
-- `whole` — Whole numbers **(1, 2, 3...)**
-- `finite` — Finite numbers (not **NaN** or **Infinity**)
-- `string`,`str` — Strings (using **typeof**)
-- `string+`,`str+` — Non-empty strings (using **str.length**)
-- `lowercase`,`lower` — Strings with no uppercase characters
-- `lowercase+`,`lower+` — Non-empty strings with no uppercase characters
-- `uppercase`,`upper` — Strings with no lowercase characters
-- `uppercase+`,`upper+` — Non-empty strings with no lowercase characters
-- `function`,`func` — Functions (using **instanceof Function**)
-- `object`,`obj` — Objects (using **instanceof Object**)
-- `object+`,`obj` — Objects with one or more enumerable properties (using **Object.keys().length**)
-- `iterable` — Objects with a **Symbol.iterator** method that can be used with **for..of** loops
-- `array`,`arr` — Arrays (using **instanceof Array**)
-- `array+`,`arr+` — Arrays with one or more items
-- `map` — Instances of **Map**
-- `map+` — Instances of **Map** with one or more items
-- `weakmap` — Instances of **WeakMap**
-- `set` — Instances of **Set**
-- `set+` — Instances of **Set** with one or more items
-- `weakset` — Instances of **WeakSet**
-- `arguments`,`args` — Arguments objects (has a numeric **.length** property)
-- `promise` — Instances of **Promise**
-- `date` — Instances of **Date**
-- `future` — Instances of **Date** with a value in the future
-- `past` — Instances of **Date** with a value in the past
+| Type string reference      | Description                                                                         |
+|----------------------------|-------------------------------------------------------------------------------------|
+| `null`                     | Value is **null**                                                                   |
+| `undefined` `undef` `void` | Value is **undefined**                                                              |
+| `defined` `def`            | Value is **not undefined**                                                          |
+| `boolean` `bool`           | Value is **true** or **false**                                                      |
+| `true`                     | Value is **true**                                                                   |
+| `false`                    | Value is **false**                                                                  |
+| `truthy`                   | Any truthy values (i.e. **== true**)                                                |
+| `falsy`                    | Any falsy values (i.e. **== false**)                                                |
+| `number` `num`             | Numbers (using **typeof**)                                                          |
+| `integer` `int`            | Integers (i.e. not floats, using **Number.isInteger()**)                            |
+| `natural`                  | Natural numbers **(1, 2, 3...)**                                                    |
+| `whole`                    | Whole numbers **(1, 2, 3...)**                                                      |
+| `finite`                   | Finite numbers (not **NaN** or **Infinity**)                                        |
+| `string` `str`             | Strings (using **typeof**)                                                          |
+| `string+` `str+`           | Non-empty strings (using **str.length**)                                            |
+| `lowercase` `lower`        | Strings with no uppercase characters                                                |
+| `lowercase+` `lower+`      | Non-empty strings with no uppercase characters                                      |
+| `uppercase` `upper`        | Strings with no lowercase characters                                                |
+| `uppercase+` `upper+`      | Non-empty strings with no lowercase characters                                      |
+| `function` `func`          | Functions (using **instanceof Function**)                                           |
+| `object` `obj`             | Objects (using **instanceof Object**)                                               |
+| `object+` `obj+`           | Objects with one or more properties (using **Object.keys().length**)                |
+| `iterable`                 | Objects with a **Symbol.iterator** method (that can be used with **for..of** loops) |
+| `array` `arr`              | Instances of Array (using **instanceof Array**)                                     |
+| `array+` `arr+`            | Instances of Array with one or more items                                           |
+| `map`                      | Instances of **Map**                                                                |
+| `map+`                     | Instances of **Map** with one or more items                                         |
+| `weakmap`                  | Instances of **WeakMap**                                                            |
+| `set`                      | Instances of **Set**                                                                |
+| `set+`                     | Instances of **Set** with one or more items                                         |
+| `weakset`                  | Instances of **WeakSet**                                                            |
+| `promise`                  | Instances of **Promise**                                                            |
+| `date`                     | Instances of **Date**                                                               |
+| `future`                   | Instances of **Date** with a value in the future                                    |
+| `past`                     | Instances of **Date** with a value in the past                                      |
+| `arguments` `args`         | Arguments (any object, not just arrays, with numeric **.length** property)          |
 
@@ -239,7 +280,9 @@ ```js
 
-- `Boolean` — Same as **'boolean'** type
-- `String` — Same as **'string'** type
-- `Number` — Same as **'number'** type
-- `Array` — Same as **'array'** type
-- `Object` — Same as **'object'** type
+| Type      | Description                |
+|-----------|----------------------------|
+| `Boolean` | Same as **'boolean'** type |
+| `String`  | Same as **'string'** type  |
+| `Number`  | Same as **'number'** type  |
+| `Array`   | Same as **'array'** type   |
+| `Object`  | Same as **'object'** type  |
 
@@ -302,2 +345,10 @@ You can also pass in _any_ class name, and Blork will check the value using `instanceof` and generate a corresponding error message if the type doesn't match.
 check([123, 'abc', true], ['num', 'str']); // Throws TypeError "Array: Too many items (expected 2 but received 3)"
-```
+```
+
+## Contributing
+
+Please see (CONTRIBUTING.md)
+
+## Roadmap
+
+- [ ] Support `@decorator` syntax for class methods (PRs welcome)

src/blork.ts

@@ -63,3 +63,3 @@ /**
 	// No excess arguments.
-	if (argsObj.length > l) { throw new errorConstructor(format(`Must not have more than ${l} arguments`, argsObj.length, 'arguments')); }
+	if (argsObj.length > l) { throw new errorConstructor(format(`Too many arguments (expected ${l})`, argsObj.length, 'arguments')); }
 
@@ -66,0 +66,0 @@ // Success.

src/internal.ts

@@ -161,3 +161,3 @@ /**
 			// No excess items in a tuple.
-			if (value.length > l) throw new err(format(`Must not have more than ${l} array items`, value.length, prefix));
+			if (value.length > l) throw new err(format(`Too many array items (expected ${l})`, value.length, prefix));
 
@@ -164,0 +164,0 @@ }

No alert changes

Improved metrics

Total package byte prevSize

78657

increased by8.54%

Number of package files

33

increased by6.45%

Number of lines in readme file

341

increased by17.59%

No dependency changes