feat: string/coerce

README.md

@@ -22,6 +22,21 @@ isObject(true); // false
 isObject(null); // false
 ```
 
+#### String
+
+_string_ primitives
+
+##### `string/coerce`
+
+Restricted string coercion. Returns `null` for non-values or non implicitly coercible (to string) values
+
+```javascript
+const stringCoerce = require("type/string/coerce");
+
+stringCoerce(12); // "12"
+stringCoerce(undefined); // null
+```
+
 #### Value
 
 _Value_ is assumed to be any JavaScript value that's neither `null` nor `undefined` (_the only primitives which are not accompanied with object representation. Hence any property access on them (as e.g. `null.foo`) results with an exception_)

package.json

@@ -39,6 +39,15 @@
 				"files": "test/**/*.js",
 				"env": {
 					"mocha": true
+				},
+				"rules": {
+					"no-new-wrappers": "off"
+				}
+			},
+			{
+				"files": "string/coerce.js",
+				"rules": {
+					"no-implicit-coercion": "off"
 				}
 			}
 		]

string/coerce.js

@@ -0,0 +1,12 @@
+"use strict";
+
+var isValue = require("../value/is");
+
+module.exports = function (value) {
+	if (!isValue(value)) return null;
+	try {
+		return "" + value; // Ensureimplicit coercion
+	} catch (error) {
+		return null;
+	}
+};

test/string/coerce.js

@@ -0,0 +1,27 @@
+"use strict";
+
+var assert       = require("chai").assert
+  , stringCoerce = require("../../string/coerce");
+
+describe("string/coerce", function () {
+	it("Should return input string", function () { assert.equal(stringCoerce("foo"), "foo"); });
+	it("Should coerce numbers", function () { assert.equal(stringCoerce(12), "12"); });
+	it("Should coerce booleans", function () { assert.equal(stringCoerce(true), "true"); });
+	it("Should coerce string objects", function () {
+		assert.equal(stringCoerce(new String("bar")), "bar");
+	});
+	it("Should coerce objects", function () {
+		assert.equal(
+			stringCoerce({ toString: function () { return "Some object"; } }), "Some object"
+		);
+	});
+	it("Should not coerce null", function () { assert.equal(stringCoerce(null), null); });
+	it("Should not coerce undefined", function () { assert.equal(stringCoerce(undefined), null); });
+
+	if (typeof Symbol === "function") {
+		it("Should not coerce symbols", function () {
+			// eslint-disable-next-line no-undef
+			assert.equal(stringCoerce(Symbol()), null);
+		});
+	}
+});