From 32e736034bd27ed25d4566b22aa93aa66c7901cf Mon Sep 17 00:00:00 2001
From: Mariusz Nowak <medyk@medikoo.com>
Date: Wed, 31 Aug 2022 12:41:33 +0200
Subject: [PATCH] feat: `string.capitalize` method

---
 README.md                            |  1 +
 _es5-ext/string/#/capitalize.js      |  8 --------
 _es5-ext/test/string/#/capitalize.js |  9 ---------
 docs/string_/capitalize.md           |  9 +++++++++
 string_/capitalize.js                |  9 +++++++++
 test/string_/capitalize.js           | 21 +++++++++++++++++++++
 6 files changed, 40 insertions(+), 17 deletions(-)
 delete mode 100644 _es5-ext/string/#/capitalize.js
 delete mode 100644 _es5-ext/test/string/#/capitalize.js
 create mode 100644 docs/string_/capitalize.md
 create mode 100644 string_/capitalize.js
 create mode 100644 test/string_/capitalize.js

diff --git a/README.md b/README.md
index ad4dda2f..fceb552d 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,7 @@ npm install ext
   - [`random`](docs/string/random.md)
 - `String.prototype`
   - [`campelToHyphen`](docs/string_/camel-to-hyphen.md)
+  - [`capitalize`](docs/string_/capitalize.md)
   - [`includes`](docs/string_/includes.md)
 - `Thenable.prototype`
   - [`finally`](docs/thenable_/finally.md)
diff --git a/_es5-ext/string/#/capitalize.js b/_es5-ext/string/#/capitalize.js
deleted file mode 100644
index fc92a9fb..00000000
--- a/_es5-ext/string/#/capitalize.js
+++ /dev/null
@@ -1,8 +0,0 @@
-"use strict";
-
-var value = require("../../object/valid-value");
-
-module.exports = function () {
-	var str = String(value(this));
-	return str.charAt(0).toUpperCase() + str.slice(1);
-};
diff --git a/_es5-ext/test/string/#/capitalize.js b/_es5-ext/test/string/#/capitalize.js
deleted file mode 100644
index 884ae9cb..00000000
--- a/_es5-ext/test/string/#/capitalize.js
+++ /dev/null
@@ -1,9 +0,0 @@
-"use strict";
-
-module.exports = function (t, a) {
-	a(t.call("raz"), "Raz", "Word");
-	a(t.call("BLA"), "BLA", "Uppercase");
-	a(t.call(""), "", "Empty");
-	a(t.call("a"), "A", "One letter");
-	a(t.call("this is a test"), "This is a test", "Sentence");
-};
diff --git a/docs/string_/capitalize.md b/docs/string_/capitalize.md
new file mode 100644
index 00000000..319e194e
--- /dev/null
+++ b/docs/string_/capitalize.md
@@ -0,0 +1,9 @@
+# `string.capitalize()` _(ext/string\_/capitalize)_
+
+Capitalize input string, e.g. convert `this is a test` into `This is a test`.
+
+```javascript
+const capitalize = require("ext/string_/capitalize");
+
+capitalize.call("this is a test"); // This is a test
+```
diff --git a/string_/capitalize.js b/string_/capitalize.js
new file mode 100644
index 00000000..bc76311e
--- /dev/null
+++ b/string_/capitalize.js
@@ -0,0 +1,9 @@
+"use strict";
+
+var ensureString = require("type/string/ensure");
+
+module.exports = function () {
+	var input = ensureString(this);
+	if (!input) return input;
+	return input.charAt(0).toUpperCase() + input.slice(1);
+};
diff --git a/test/string_/capitalize.js b/test/string_/capitalize.js
new file mode 100644
index 00000000..1ae8b224
--- /dev/null
+++ b/test/string_/capitalize.js
@@ -0,0 +1,21 @@
+"use strict";
+
+var assert = require("chai").assert;
+
+var capitalize = require("../../string_/capitalize");
+
+describe("string_/capitalize", function () {
+	it("should capitalize lowercase word", function () {
+		assert.equal(capitalize.call("raz"), "Raz");
+		assert.equal(capitalize.call("raZ"), "RaZ");
+	});
+	it("should return as-is capitalized word", function () {
+		assert.equal(capitalize.call("Raz"), "Raz");
+		assert.equal(capitalize.call("RAZ"), "RAZ");
+	});
+	it("should return emptry string as is", function () { assert.equal(capitalize.call(""), ""); });
+	it("should capitalize single letter", function () { assert.equal(capitalize.call("a"), "A"); });
+	it("should capitalize sentence", function () {
+		assert.equal(capitalize.call("this is a Test"), "This is a Test");
+	});
+});