Add TypeScript definition (#50)

sindresorhus · Apr 24, 2019 · 44858ce · 44858ce
1 parent 9db9f7d
commit 44858ce
Show file tree

Hide file tree

Showing 7 changed files with 123 additions and 60 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -1,2 +1 @@
-* text=auto
-*.js text eol=lf
+* text=auto eol=lf
diff --git a/index.d.ts b/index.d.ts
@@ -0,0 +1,52 @@
+declare namespace prettyBytes {
+	interface Options {
+		/**
+		Include plus sign for positive numbers. If the difference is exactly zero a space character will be prepended instead for better alignment.
+
+		@default false
+		*/
+		readonly signed?: boolean;
+
+		/**
+		- If `false`: Output won't be localized.
+		- If `true`: Localize the output using the system/browser locale.
+		- If `string`: Expects a [BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag) (For example: `en`, `de`, …)
+
+		__Note:__ Localization should generally work in browsers. Node.js needs to be [built](https://github.com/nodejs/node/wiki/Intl) with `full-icu` or `system-icu`. Alternatively, the [`full-icu`](https://github.com/unicode-org/full-icu-npm) module can be used to provide support at runtime.
+
+		@default false
+		*/
+		readonly locale?: boolean | string;
+	}
+}
+
+/**
+Convert bytes to a human readable string: `1337` → `1.34 kB`.
+
+@param number - The number to format.
+
+@example
+```
+import prettyBytes = require('pretty-bytes');
+
+prettyBytes(1337);
+//=> '1.34 kB'
+
+prettyBytes(100);
+//=> '100 B'
+
+// Display file size differences
+prettyBytes(42, {signed: true});
+//=> '+42 B'
+
+// Localized output using German locale
+prettyBytes(1337, {locale: 'de'});
+//=> '1,34 kB'
+```
+*/
+declare function prettyBytes(
+	number: number,
+	options?: prettyBytes.Options
+): string;
+
+export = prettyBytes;
diff --git a/index.js b/index.js
@@ -53,6 +53,7 @@ module.exports = (number, options) => {
 	}
 
 	const exponent = Math.min(Math.floor(Math.log10(number) / 3), UNITS.length - 1);
+	// eslint-disable-next-line unicorn/prefer-exponentiation-operator
 	number = Number((number / Math.pow(1000, exponent)).toPrecision(3));
 	const numberString = toLocaleString(number, options.locale);
 

diff --git a/index.test-d.ts b/index.test-d.ts
@@ -0,0 +1,9 @@
+import {expectType} from 'tsd';
+import prettyBytes = require('.');
+
+const options: prettyBytes.Options = {};
+
+expectType<string>(prettyBytes(1337));
+expectType<string>(prettyBytes(42, {signed: true}));
+expectType<string>(prettyBytes(1337, {locale: 'de'}));
+expectType<string>(prettyBytes(1337, {locale: true}));
diff --git a/package.json b/package.json
@@ -13,10 +13,11 @@
 		"node": ">=6"
 	},
 	"scripts": {
-		"test": "xo && NODE_ICU_DATA=node_modules/full-icu ava"
+		"test": "xo && NODE_ICU_DATA=node_modules/full-icu ava && tsd"
 	},
 	"files": [
-		"index.js"
+		"index.js",
+		"index.d.ts"
 	],
 	"keywords": [
 		"pretty",
@@ -35,8 +36,9 @@
 		"localized"
 	],
 	"devDependencies": {
-		"ava": "*",
+		"ava": "^1.4.1",
 		"full-icu": "^1.2.1",
-		"xo": "*"
+		"tsd": "^0.7.2",
+		"xo": "^0.24.0"
 	}
 }
diff --git a/readme.md b/readme.md
@@ -38,17 +38,17 @@ prettyBytes(1337, {locale: 'de'});
 
 ## API
 
-### prettyBytes(input, [options])
+### prettyBytes(number, [options])
 
-#### input
+#### number
 
 Type: `number`
 
 The number to format.
 
 #### options
 
-Type: `Object`
+Type: `object`
 
 ##### signed
 

diff --git a/test.js b/test.js
@@ -1,71 +1,71 @@
 import test from 'ava';
-import m from '.';
+import prettyBytes from '.';
 
 test('throws on invalid input', t => {
-	t.throws(() => m(''));
-	t.throws(() => m('1'));
-	t.throws(() => m(NaN));
-	t.throws(() => m(true));
-	t.throws(() => m(Infinity));
-	t.throws(() => m(-Infinity));
-	t.throws(() => m(null));
+	t.throws(() => prettyBytes(''));
+	t.throws(() => prettyBytes('1'));
+	t.throws(() => prettyBytes(NaN));
+	t.throws(() => prettyBytes(true));
+	t.throws(() => prettyBytes(Infinity));
+	t.throws(() => prettyBytes(-Infinity));
+	t.throws(() => prettyBytes(null));
 });
 
 test('converts bytes to human readable strings', t => {
-	t.is(m(0), '0 B');
-	t.is(m(0.4), '0.4 B');
-	t.is(m(0.7), '0.7 B');
-	t.is(m(10), '10 B');
-	t.is(m(10.1), '10.1 B');
-	t.is(m(999), '999 B');
-	t.is(m(1001), '1 kB');
-	t.is(m(1001), '1 kB');
-	t.is(m(1e16), '10 PB');
-	t.is(m(1e30), '1000000 YB');
+	t.is(prettyBytes(0), '0 B');
+	t.is(prettyBytes(0.4), '0.4 B');
+	t.is(prettyBytes(0.7), '0.7 B');
+	t.is(prettyBytes(10), '10 B');
+	t.is(prettyBytes(10.1), '10.1 B');
+	t.is(prettyBytes(999), '999 B');
+	t.is(prettyBytes(1001), '1 kB');
+	t.is(prettyBytes(1001), '1 kB');
+	t.is(prettyBytes(1e16), '10 PB');
+	t.is(prettyBytes(1e30), '1000000 YB');
 });
 
 test('supports negative number', t => {
-	t.is(m(-0.4), '-0.4 B');
-	t.is(m(-0.7), '-0.7 B');
-	t.is(m(-10.1), '-10.1 B');
-	t.is(m(-999), '-999 B');
-	t.is(m(-1001), '-1 kB');
+	t.is(prettyBytes(-0.4), '-0.4 B');
+	t.is(prettyBytes(-0.7), '-0.7 B');
+	t.is(prettyBytes(-10.1), '-10.1 B');
+	t.is(prettyBytes(-999), '-999 B');
+	t.is(prettyBytes(-1001), '-1 kB');
 });
 
 test('locale option', t => {
-	t.is(m(-0.4, {locale: 'de'}), '-0,4 B');
-	t.is(m(0.4, {locale: 'de'}), '0,4 B');
-	t.is(m(1001, {locale: 'de'}), '1 kB');
-	t.is(m(10.1, {locale: 'de'}), '10,1 B');
-	t.is(m(1e30, {locale: 'de'}), '1.000.000 YB');
+	t.is(prettyBytes(-0.4, {locale: 'de'}), '-0,4 B');
+	t.is(prettyBytes(0.4, {locale: 'de'}), '0,4 B');
+	t.is(prettyBytes(1001, {locale: 'de'}), '1 kB');
+	t.is(prettyBytes(10.1, {locale: 'de'}), '10,1 B');
+	t.is(prettyBytes(1e30, {locale: 'de'}), '1.000.000 YB');
 
-	t.is(m(-0.4, {locale: 'en'}), '-0.4 B');
-	t.is(m(0.4, {locale: 'en'}), '0.4 B');
-	t.is(m(1001, {locale: 'en'}), '1 kB');
-	t.is(m(10.1, {locale: 'en'}), '10.1 B');
-	t.is(m(1e30, {locale: 'en'}), '1,000,000 YB');
+	t.is(prettyBytes(-0.4, {locale: 'en'}), '-0.4 B');
+	t.is(prettyBytes(0.4, {locale: 'en'}), '0.4 B');
+	t.is(prettyBytes(1001, {locale: 'en'}), '1 kB');
+	t.is(prettyBytes(10.1, {locale: 'en'}), '10.1 B');
+	t.is(prettyBytes(1e30, {locale: 'en'}), '1,000,000 YB');
 
-	t.is(m(-0.4, {locale: true}), '-0.4 B');
-	t.is(m(0.4, {locale: true}), '0.4 B');
-	t.is(m(1001, {locale: true}), '1 kB');
-	t.is(m(10.1, {locale: true}), '10.1 B');
-	t.is(m(1e30, {locale: true}), '1,000,000 YB');
+	t.is(prettyBytes(-0.4, {locale: true}), '-0.4 B');
+	t.is(prettyBytes(0.4, {locale: true}), '0.4 B');
+	t.is(prettyBytes(1001, {locale: true}), '1 kB');
+	t.is(prettyBytes(10.1, {locale: true}), '10.1 B');
+	t.is(prettyBytes(1e30, {locale: true}), '1,000,000 YB');
 
-	t.is(m(-0.4, {locale: false}), '-0.4 B');
-	t.is(m(0.4, {locale: false}), '0.4 B');
-	t.is(m(1001, {locale: false}), '1 kB');
-	t.is(m(10.1, {locale: false}), '10.1 B');
-	t.is(m(1e30, {locale: false}), '1000000 YB');
+	t.is(prettyBytes(-0.4, {locale: false}), '-0.4 B');
+	t.is(prettyBytes(0.4, {locale: false}), '0.4 B');
+	t.is(prettyBytes(1001, {locale: false}), '1 kB');
+	t.is(prettyBytes(10.1, {locale: false}), '10.1 B');
+	t.is(prettyBytes(1e30, {locale: false}), '1000000 YB');
 
-	t.is(m(-0.4, {locale: undefined}), '-0.4 B');
-	t.is(m(0.4, {locale: undefined}), '0.4 B');
-	t.is(m(1001, {locale: undefined}), '1 kB');
-	t.is(m(10.1, {locale: undefined}), '10.1 B');
-	t.is(m(1e30, {locale: undefined}), '1000000 YB');
+	t.is(prettyBytes(-0.4, {locale: undefined}), '-0.4 B');
+	t.is(prettyBytes(0.4, {locale: undefined}), '0.4 B');
+	t.is(prettyBytes(1001, {locale: undefined}), '1 kB');
+	t.is(prettyBytes(10.1, {locale: undefined}), '10.1 B');
+	t.is(prettyBytes(1e30, {locale: undefined}), '1000000 YB');
 });
 
 test('signed option', t => {
-	t.is(m(42, {signed: true}), '+42 B');
-	t.is(m(-13, {signed: true}), '-13 B');
-	t.is(m(0, {signed: true}), ' 0 B');
+	t.is(prettyBytes(42, {signed: true}), '+42 B');
+	t.is(prettyBytes(-13, {signed: true}), '-13 B');
+	t.is(prettyBytes(0, {signed: true}), ' 0 B');
 });