Merge pull request #236 from shimataro/develop

version 1.0.0-rc.3

CHANGELOG.md

@@ -6,6 +6,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
+## [1.0.0-rc.3] - 2018-08-28
+### Others
+* documents proofreading
+* some minor changes of JSDoc and `index.d.ts`
+
 ## [1.0.0-rc.2] - 2018-08-25
 ### Changed
 * `adjuster.string().pattern()` and `adjuster.email().pattern()` accept only RegExp (reject string)
@@ -196,7 +201,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ## [0.1.0] - 2018-04-18
 * First release.
 
-[Unreleased]: https://github.com/shimataro/node-adjuster/compare/v1.0.0-rc.2...HEAD
+[Unreleased]: https://github.com/shimataro/node-adjuster/compare/v1.0.0-rc.3...HEAD
+[1.0.0-rc.3]: https://github.com/shimataro/node-adjuster/compare/v1.0.0-rc.2...v1.0.0-rc.3
 [1.0.0-rc.2]: https://github.com/shimataro/node-adjuster/compare/v1.0.0-rc.1...v1.0.0-rc.2
 [1.0.0-rc.1]: https://github.com/shimataro/node-adjuster/compare/v0.16.0...v1.0.0-rc.1
 [0.16.0]: https://github.com/shimataro/node-adjuster/compare/v0.15.1...v0.16.0

README.md

@@ -39,7 +39,7 @@ All of web applications need handling input parameters, consists of following st
     * all required parameters exist?
     * fill omittable parameters by default values
 1. type check
-    * e.g., `typeof age === "number`
+    * e.g., `typeof age === "number"`
     * cast them if needed; `"20"`(string) to `20`(number)
 1. domain check
     * e.g., `1 <= limit && limit <= 100`
@@ -150,15 +150,28 @@ import adjuster from "adjuster";
 #### `AdjusterError`
 The `AdjusterError` object represents an error when trying to adjust invalid value.
 
+##### ambient declaration
+
+```typescript
+interface AdjusterError extends Error
+{
+    name: string
+    message: string
+	cause: string
+	value: any
+	keyStack: (string|number)[]
+}
+```
+
 ##### properties
 
 |name|description|
 |----|-----------|
 |`name`|`"AdjusterError"`|
 |`message`|human-readable description of the error, including a string `cause`|
-|`cause`|the cause of adjustment error; see `adjuster.CAUSE`|
-|`value`|the value to adjust|
-|`keyStack`|an array path to key name(for object) or index(for array) that caused error; for nested object or array|
+|`cause`|cause of adjustment error; see `adjuster.CAUSE`|
+|`value`|value to adjust|
+|`keyStack`|array consists of path to key name(for object) or index(for array) that caused error; for nested object or array|
 
 See below example.
 For detail about constraints / `adjuster`, see [basic usage](#basic-usage)
@@ -167,6 +180,7 @@ For detail about constraints / `adjuster`, see [basic usage](#basic-usage)
 import adjuster from "adjuster";
 import assert from "assert";
 
+// {foo: Array<{bar: {baz: number}}>}
 const constraints = {
     foo: adjuster.array().each(adjuster.object().constraints({
         bar: adjuster.object().constraints({
@@ -2138,7 +2152,7 @@ See [CHANGELOG.md](CHANGELOG.md).
 [link-build-macos]: https://travis-ci.org/shimataro/node-adjuster
 [image-build-linux]: https://img.shields.io/travis/shimataro/node-adjuster/master.svg?label=Linux
 [link-build-linux]: https://travis-ci.org/shimataro/node-adjuster
-[image-code-coverage]: https://codecov.io/gh/shimataro/node-adjuster/branch/master/graph/badge.svg
+[image-code-coverage]: https://img.shields.io/codecov/c/github/shimataro/node-adjuster/master.svg
 [link-code-coverage]: https://codecov.io/gh/shimataro/node-adjuster
 [image-release]: https://img.shields.io/github/release/shimataro/node-adjuster.svg
 [link-release]: https://github.com/shimataro/node-adjuster/releases

package.json

@@ -1,7 +1,7 @@
 {
   "name": "adjuster",
   "description": "validate and adjust input values",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0-rc.3",
   "author": "shimataro",
   "license": "MIT",
   "repository": {
@@ -45,18 +45,20 @@
     "check-updates": "ncu"
   },
   "devDependencies": {
+    "@types/core-js": "2.5.0",
     "@types/jest": "23.3.1",
+    "@types/node": "10.9.2",
     "babel-eslint": "8.2.6",
     "eslint": "5.4.0",
     "eslint-plugin-import": "2.14.0",
     "jest": "23.5.0",
     "npm-check-updates": "2.14.2"
   },
   "dependencies": {
-    "@babel/cli": "7.0.0-rc.3",
-    "@babel/core": "7.0.0-rc.3",
-    "@babel/plugin-proposal-decorators": "7.0.0-rc.3",
-    "@babel/preset-env": "7.0.0-rc.3",
+    "@babel/cli": "7.0.0-rc.4",
+    "@babel/core": "7.0.0-rc.4",
+    "@babel/plugin-proposal-decorators": "7.0.0-rc.4",
+    "@babel/preset-env": "7.0.0-rc.4",
     "babel-core": "7.0.0-bridge.0",
     "babel-plugin-add-module-exports": "0.3.3",
     "cross-env": "5.2.0",

src/decorators/acceptEmptyString.mjs

@@ -9,9 +9,16 @@ export default AdjusterBase.decoratorBuilder(_adjust)
 	})
 	.build();
 
+/**
+ * @package
+ * @typedef {Params} Params-AcceptEmptyString
+ * @property {boolean} flag
+ * @property {*|null} valueOnEmpty
+ */
+
 /**
  * init
- * @param {Object} params parameters
+ * @param {Params-AcceptEmptyString} params parameters
  * @returns {void}
  */
 function _init(params)
@@ -21,7 +28,7 @@ function _init(params)
 
 /**
  * accept empty string
- * @param {Object} params parameters
+ * @param {Params-AcceptEmptyString} params parameters
  * @param {*} [value=null] value on empty
  * @returns {void}
  */
@@ -33,8 +40,8 @@ function _featureAcceptEmptyString(params, value = null)
 
 /**
  * adjust
- * @param {Object} params parameters
- * @param {DecoratorValues} values original / adjusted values
+ * @param {Params-AcceptEmptyString} params parameters
+ * @param {Decorator-Values} values original / adjusted values
  * @param {Key[]} keyStack path to key that caused error
  * @returns {boolean} end adjustment
  * @throws {AdjusterError}

src/decorators/acceptNull.mjs

@@ -9,9 +9,16 @@ export default AdjusterBase.decoratorBuilder(_adjust)
 	})
 	.build();
 
+/**
+ * @package
+ * @typedef {Params} Params-AcceptNull
+ * @property {boolean} flag
+ * @property {*|null} valueOnNull
+ */
+
 /**
  * init
- * @param {Object} params parameters
+ * @param {Params-AcceptNull} params parameters
  * @returns {void}
  */
 function _init(params)
@@ -21,7 +28,7 @@ function _init(params)
 
 /**
  * accept null
- * @param {Object} params parameters
+ * @param {Params-AcceptNull} params parameters
  * @param {*} [value=null] value on null
  * @returns {void}
  */
@@ -33,8 +40,8 @@ function _featureAcceptNull(params, value = null)
 
 /**
  * adjust
- * @param {Object} params parameters
- * @param {DecoratorValues} values original / adjusted values
+ * @param {Params-AcceptNull} params parameters
+ * @param {Decorator-Values} values original / adjusted values
  * @param {Key[]} keyStack path to key that caused error
  * @returns {boolean} end adjustment
  * @throws {AdjusterError}

src/decorators/array/each.mjs

@@ -8,9 +8,16 @@ export default AdjusterBase.decoratorBuilder(_adjust)
 	})
 	.build();
 
+/**
+ * @package
+ * @typedef {Params} Params-Array-Each
+ * @property {AdjusterBase} objAdjuster
+ * @property {boolean} ignoreEachErrors
+ */
+
 /**
  * init
- * @param {Object} params parameters
+ * @param {Params-Array-Each} params parameters
  * @returns {void}
  */
 function _init(params)
@@ -21,7 +28,7 @@ function _init(params)
 
 /**
  * apply constraints for each elements
- * @param {Object} params parameters
+ * @param {Params-Array-Each} params parameters
  * @param {AdjusterBase} objAdjuster adjuster to apply
  * @param {boolean} [ignoreEachErrors=false] ignore errors of each elements
  * @returns {void}
@@ -34,8 +41,8 @@ function _featureEach(params, objAdjuster, ignoreEachErrors = false)
 
 /**
  * adjuster
- * @param {Object} params parameters
- * @param {DecoratorValues} values original / adjusted values
+ * @param {Params-Array-Each} params parameters
+ * @param {Decorator-Values} values original / adjusted values
  * @param {Key[]} keyStack path to key that caused error
  * @returns {boolean} end adjustment
  * @throws {AdjusterError}
@@ -73,4 +80,3 @@ function _adjust(params, values, keyStack)
 	values.adjusted = adjusted;
 	return false;
 }
-

src/decorators/array/maxLength.mjs

@@ -9,9 +9,17 @@ export default AdjusterBase.decoratorBuilder(_adjust)
 	})
 	.build();
 
+/**
+ * @package
+ * @typedef {Params} Params-Array-MaxLength
+ * @property {boolean} flag
+ * @property {number} length
+ * @property {boolean} adjust
+ */
+
 /**
  * init
- * @param {Object} params parameters
+ * @param {Params-Array-MaxLength} params parameters
  * @returns {void}
  */
 function _init(params)
@@ -21,7 +29,7 @@ function _init(params)
 
 /**
  * set max-length of array
- * @param {Object} params parameters
+ * @param {Params-Array-MaxLength} params parameters
  * @param {number} length min-length; error if shorter
  * @param {boolean} adjust adjust value or not
  * @returns {void}
@@ -35,8 +43,8 @@ function _featureMaxLength(params, length, adjust = false)
 
 /**
  * adjuster
- * @param {Object} params parameters
- * @param {DecoratorValues} values original / adjusted values
+ * @param {Params-Array-MaxLength} params parameters
+ * @param {Decorator-Values} values original / adjusted values
  * @param {Key[]} keyStack path to key that caused error
  * @returns {boolean} end adjustment
  * @throws {AdjusterError}

src/decorators/array/minLength.mjs

@@ -9,9 +9,16 @@ export default AdjusterBase.decoratorBuilder(_adjust)
 	})
 	.build();
 
+/**
+ * @package
+ * @typedef {Params} Params-Array-MinLength
+ * @property {boolean} flag
+ * @property {number} length
+ */
+
 /**
  * init
- * @param {Object} params parameters
+ * @param {Params-Array-MinLength} params parameters
  * @returns {void}
  */
 function _init(params)
@@ -21,7 +28,7 @@ function _init(params)
 
 /**
  * set min-length of array
- * @param {Object} params parameters
+ * @param {Params-Array-MinLength} params parameters
  * @param {number} length max-length
  * @returns {void}
  */
@@ -33,8 +40,8 @@ function _featureMinLength(params, length)
 
 /**
  * adjuster
- * @param {Object} params parameters
- * @param {DecoratorValues} values original / adjusted values
+ * @param {Params-Array-MinLength} params parameters
+ * @param {Decorator-Values} values original / adjusted values
  * @param {Key[]} keyStack path to key that caused error
  * @returns {boolean} end adjustment
  * @throws {AdjusterError}

src/decorators/array/type.mjs

@@ -11,43 +11,51 @@ export default AdjusterBase.decoratorBuilder(_adjust)
 	})
 	.build();
 
+/**
+ * @package
+ * @typedef {Params} Params-Array-Type
+ * @property {boolean} flagSeparatedBy
+ * @property {boolean} flagToArray
+ * @property {Separator} separator
+ */
+
 /**
  * init
- * @param {Object} params parameters
+ * @param {Params-Array-Type} params parameters
  * @returns {void}
  */
 function _init(params)
 {
-	params.separatedBy = false;
-	params.toArray = false;
+	params.flagSeparatedBy = false;
+	params.flagToArray = false;
 }
 
 /**
  * accept string and set separator
- * @param {Object} params parameters
+ * @param {Params-Array-Type} params parameters
  * @param {Separator} separator separator
  * @returns {void}
  */
 function _featureSeparatedBy(params, separator)
 {
-	params.separatedBy = true;
+	params.flagSeparatedBy = true;
 	params.separator = separator;
 }
 
 /**
  * convert to array, if not
- * @param {Object} params parameters
+ * @param {Params-Array-Type} params parameters
  * @returns {void}
  */
 function _featureToArray(params)
 {
-	params.toArray = true;
+	params.flagToArray = true;
 }
 
 /**
  * adjuster
- * @param {Object} params parameters
- * @param {DecoratorValues} values original / adjusted values
+ * @param {Params-Array-Type} params parameters
+ * @param {Decorator-Values} values original / adjusted values
  * @param {Key[]} keyStack path to key that caused error
  * @returns {boolean} end adjustment
  * @throws {AdjusterError}
@@ -59,13 +67,13 @@ function _adjust(params, values, keyStack)
 		return false;
 	}
 
-	if(isString(values.adjusted) && params.separatedBy)
+	if(isString(values.adjusted) && params.flagSeparatedBy)
 	{
 		values.adjusted = values.adjusted.split(params.separator);
 		return false;
 	}
 
-	if(params.toArray)
+	if(params.flagToArray)
 	{
 		values.adjusted = [values.adjusted];
 		return false;