@tannin/sprintf 1.1.0 → 1.3.0

package/README.md

@@ -1,5 +1,4 @@
-`@tannin/sprintf`
-=================
+# `@tannin/sprintf`
 
 Given a format string, returns string with arguments interpolatation. Arguments can either be provided directly via function arguments spread, or with an array as the second argument.
 
@@ -32,16 +31,28 @@ Otherwise, download a pre-built copy from unpkg:
 
 ## Usage
 
+Using positional arguments:
+
 ```js
 import sprintf from '@tannin/sprintf';
 
-sprintf( 'Hello %s!', 'world' );
+sprintf('Hello %s!', 'world');
 // ⇒ 'Hello world!'
 ```
 
+Using named arguments:
+
+```js
+import sprintf from '@tannin/sprintf';
+
+sprintf('Hello %(place)s! From %(name)s.', { place: 'world', name: 'Andrew' });
+// ⇒ 'Hello world! From Andrew.'
+```
+
 ## Type coercions and default values
 
 When replacing numeric types (`%d` and `%f`), values will be coerced to numeric values, and default to 0:
+
 - `sprintf( '%d', 123 )` returns `'123'`
 - `sprintf( '%d', '123' )` returns `'123'`
 - `sprintf( '%d', 'string' )` returns `'0'`
@@ -50,6 +61,7 @@ When replacing numeric types (`%d` and `%f`), values will be coerced to numeric
 - `sprintf( '%d', undefined )` returns `'0'`
 
 When replacing string types (`%s`), values will be coerced to strings, and nullish values will be replaced with `''`:
+
 - `sprintf( '%s', 'string' )` returns `'string'`
 - `sprintf( '%s', 0 )` returns `'0'`
 - `sprintf( '%s', false )` returns `'false'`
@@ -58,6 +70,6 @@ When replacing string types (`%s`), values will be coerced to strings, and nulli
 
 ## License
 
-Copyright 2019 Andrew Duthie
+Copyright 2019-2025 Andrew Duthie
 
 Released under the [MIT License](https://opensource.org/licenses/MIT).

package/build/index.js

@@ -31,14 +31,14 @@
  *
  * @type {RegExp}
  */
-var PATTERN = /%(((\d+)\$)|(\(([$_a-zA-Z][$_a-zA-Z0-9]*)\)))?[ +0#-]*\d*(\.(\d+|\*))?(ll|[lhqL])?([cduxXefgsp%])/g;
+var PATTERN =
+	/%(((\d+)\$)|(\(([$_a-zA-Z][$_a-zA-Z0-9]*)\)))?[ +0#-]*\d*(\.(\d+|\*))?(ll|[lhqL])?([cduxXefgsp%])/g;
 //               ▲         ▲                    ▲       ▲  ▲            ▲           ▲ type
 //               │         │                    │       │  │            └ Length (unsupported)
 //               │         │                    │       │  └ Precision / max width
 //               │         │                    │       └ Min width (unsupported)
 //               │         │                    └ Flags (unsupported)
 //               └ Index   └ Name (for named arguments)
-
 /**
  * Given a format string, returns string with arguments interpolatation.
  * Arguments can either be provided directly via function arguments spread, or
@@ -54,84 +54,135 @@ var PATTERN = /%(((\d+)\$)|(\(([$_a-zA-Z][$_a-zA-Z0-9]*)\)))?[ +0#-]*\d*(\.(\d+|
  * sprintf( 'Hello %s!', 'world' );
  * // ⇒ 'Hello world!'
  * ```
+ * @template {string} T
+ * @overload
+ * @param {T} string - string printf format string
+ * @param {...import('../types').SprintfArgs<T>} args - arguments to interpolate
  *
- * @param {string} string printf format string
- * @param {Array}  [args] String arguments.
+ * @return {string} Formatted string.
+ */
+
+/**
+ * Given a format string, returns string with arguments interpolatation.
+ * Arguments can either be provided directly via function arguments spread, or
+ * with an array as the second argument.
+ *
+ * @see https://en.wikipedia.org/wiki/Printf_format_string
+ *
+ * @example
+ *
+ * ```js
+ * import sprintf from '@tannin/sprintf';
+ *
+ * sprintf( 'Hello %s!', 'world' );
+ * // ⇒ 'Hello world!'
+ * ```
+ * @template {string} T
+ * @overload
+ * @param {T} string - string printf format string
+ * @param {import('../types').SprintfArgs<T>} args - arguments to interpolate
  *
  * @return {string} Formatted string.
  */
-function sprintf( string, args ) {
-	var i;
 
-	if ( ! Array.isArray( args ) ) {
-		// Construct a copy of arguments from index one, used for replace
-		// function placeholder substitution.
-		args = new Array( arguments.length - 1 );
-		for ( i = 1; i < arguments.length; i++ ) {
-			args[ i - 1 ] = arguments[ i ];
-		}
+/**
+ * Given a format string, returns string with arguments interpolatation.
+ * Arguments can either be provided directly via function arguments spread, or
+ * with an array as the second argument.
+ *
+ * @see https://en.wikipedia.org/wiki/Printf_format_string
+ *
+ * @example
+ *
+ * ```js
+ * import sprintf from '@tannin/sprintf';
+ *
+ * sprintf( 'Hello %s!', 'world' );
+ * // ⇒ 'Hello world!'
+ * ```
+ * @template {string} T
+ * @param {T} string - string printf format string
+ * @param {...import('../types').SprintfArgs<T>} args - arguments to interpolate
+ *
+ * @return {string} Formatted string.
+ */
+function sprintf(string, ...args) {
+	var i = 0;
+	if (Array.isArray(args[0])) {
+		args = /** @type {import('../types').SprintfArgs<T>[]} */ (
+			/** @type {unknown} */ args[0]
+		);
 	}
 
-	i = 1;
-
-	return string.replace( PATTERN, function() {
-		var index, name, precision, type, value;
+	return string.replace(PATTERN, function () {
+		var index,
+			// name needs to be documented as `string | undefined` else value will have tpye unknown.
+			/**
+			 * Name of the argument to substitute, if any.
+			 *
+			 * @type {string | undefined}
+			 */
+			name,
+			precision,
+			type,
+			value;
 
-		index = arguments[ 3 ];
-		name = arguments[ 5 ];
-		precision = arguments[ 7 ];
-		type = arguments[ 9 ];
+		index = arguments[3];
+		name = arguments[5];
+		precision = arguments[7];
+		type = arguments[9];
 
 		// There's no placeholder substitution in the explicit "%", meaning it
 		// is not necessary to increment argument index.
-		if ( type === '%' ) {
+		if (type === '%') {
 			return '%';
 		}
 
 		// Asterisk precision determined by peeking / shifting next argument.
-		if ( precision === '*' ) {
-			precision = args[ i - 1 ];
+		if (precision === '*') {
+			precision = args[i];
 			i++;
 		}
 
-		if ( name !== undefined ) {
-			// If it's a named argument, use name.
-			if ( args[ 0 ] && typeof args[ 0 ] === 'object' &&
-					args[ 0 ].hasOwnProperty( name ) ) {
-				value = args[ 0 ][ name ];
-			}
-		} else {
+		if (name === undefined) {
 			// If not a positional argument, use counter value.
-			if ( index === undefined ) {
-				index = i;
+			if (index === undefined) {
+				index = i + 1;
 			}
 
 			i++;
 
 			// Positional argument.
-			value = args[ index - 1 ];
+			value = args[index - 1];
+		} else if (
+			args[0] &&
+			typeof args[0] === 'object' &&
+			args[0].hasOwnProperty(name)
+		) {
+			// If it's a named argument, use name.
+			value = args[0][name];
 		}
 
 		// Parse as type.
-		if ( type === 'f' ) {
-			value = parseFloat( value ) || 0;
-		} else if ( type === 'd' ) {
-			value = parseInt( value ) || 0;
+		if (type === 'f') {
+			value = parseFloat(value) || 0;
+		} else if (type === 'd') {
+			value = parseInt(value) || 0;
 		}
 
 		// Apply precision.
-		if ( precision !== undefined ) {
-			if ( type === 'f' ) {
-				value = value.toFixed( precision );
-			} else if ( type === 's' ) {
-				value = value.substr( 0, precision );
+		if (precision !== undefined) {
+			if (type === 'f') {
+				value = value.toFixed(precision);
+			} else if (type === 's') {
+				value = value.substr(0, precision);
 			}
 		}
 
 		// To avoid "undefined" concatenation, return empty string if no
 		// placeholder substitution can be performed.
 		return value !== undefined && value !== null ? value : '';
-	} );
+	});
 }
 
 module.exports = sprintf;

package/dist/sprintf.js

@@ -32,14 +32,14 @@ var sprintf = (function () {
 	 *
 	 * @type {RegExp}
 	 */
-	var PATTERN = /%(((\d+)\$)|(\(([$_a-zA-Z][$_a-zA-Z0-9]*)\)))?[ +0#-]*\d*(\.(\d+|\*))?(ll|[lhqL])?([cduxXefgsp%])/g;
+	var PATTERN =
+		/%(((\d+)\$)|(\(([$_a-zA-Z][$_a-zA-Z0-9]*)\)))?[ +0#-]*\d*(\.(\d+|\*))?(ll|[lhqL])?([cduxXefgsp%])/g;
 	//               ▲         ▲                    ▲       ▲  ▲            ▲           ▲ type
 	//               │         │                    │       │  │            └ Length (unsupported)
 	//               │         │                    │       │  └ Precision / max width
 	//               │         │                    │       └ Min width (unsupported)
 	//               │         │                    └ Flags (unsupported)
 	//               └ Index   └ Name (for named arguments)
-
 	/**
 	 * Given a format string, returns string with arguments interpolatation.
 	 * Arguments can either be provided directly via function arguments spread, or
@@ -55,86 +55,137 @@ var sprintf = (function () {
 	 * sprintf( 'Hello %s!', 'world' );
 	 * // ⇒ 'Hello world!'
 	 * ```
+	 * @template {string} T
+	 * @overload
+	 * @param {T} string - string printf format string
+	 * @param {...import('../types').SprintfArgs<T>} args - arguments to interpolate
+	 *
+	 * @return {string} Formatted string.
+	 */
+
+	/**
+	 * Given a format string, returns string with arguments interpolatation.
+	 * Arguments can either be provided directly via function arguments spread, or
+	 * with an array as the second argument.
+	 *
+	 * @see https://en.wikipedia.org/wiki/Printf_format_string
 	 *
-	 * @param {string} string printf format string
-	 * @param {Array}  [args] String arguments.
+	 * @example
+	 *
+	 * ```js
+	 * import sprintf from '@tannin/sprintf';
+	 *
+	 * sprintf( 'Hello %s!', 'world' );
+	 * // ⇒ 'Hello world!'
+	 * ```
+	 * @template {string} T
+	 * @overload
+	 * @param {T} string - string printf format string
+	 * @param {import('../types').SprintfArgs<T>} args - arguments to interpolate
 	 *
 	 * @return {string} Formatted string.
 	 */
-	function sprintf( string, args ) {
-		var i;
 
-		if ( ! Array.isArray( args ) ) {
-			// Construct a copy of arguments from index one, used for replace
-			// function placeholder substitution.
-			args = new Array( arguments.length - 1 );
-			for ( i = 1; i < arguments.length; i++ ) {
-				args[ i - 1 ] = arguments[ i ];
-			}
+	/**
+	 * Given a format string, returns string with arguments interpolatation.
+	 * Arguments can either be provided directly via function arguments spread, or
+	 * with an array as the second argument.
+	 *
+	 * @see https://en.wikipedia.org/wiki/Printf_format_string
+	 *
+	 * @example
+	 *
+	 * ```js
+	 * import sprintf from '@tannin/sprintf';
+	 *
+	 * sprintf( 'Hello %s!', 'world' );
+	 * // ⇒ 'Hello world!'
+	 * ```
+	 * @template {string} T
+	 * @param {T} string - string printf format string
+	 * @param {...import('../types').SprintfArgs<T>} args - arguments to interpolate
+	 *
+	 * @return {string} Formatted string.
+	 */
+	function sprintf(string, ...args) {
+		var i = 0;
+		if (Array.isArray(args[0])) {
+			args = /** @type {import('../types').SprintfArgs<T>[]} */ (
+				/** @type {unknown} */ args[0]
+			);
 		}
 
-		i = 1;
-
-		return string.replace( PATTERN, function() {
-			var index, name, precision, type, value;
-
-			index = arguments[ 3 ];
-			name = arguments[ 5 ];
-			precision = arguments[ 7 ];
-			type = arguments[ 9 ];
+		return string.replace(PATTERN, function () {
+			var index,
+				// name needs to be documented as `string | undefined` else value will have tpye unknown.
+				/**
+				 * Name of the argument to substitute, if any.
+				 *
+				 * @type {string | undefined}
+				 */
+				name,
+				precision,
+				type,
+				value;
+
+			index = arguments[3];
+			name = arguments[5];
+			precision = arguments[7];
+			type = arguments[9];
 
 			// There's no placeholder substitution in the explicit "%", meaning it
 			// is not necessary to increment argument index.
-			if ( type === '%' ) {
+			if (type === '%') {
 				return '%';
 			}
 
 			// Asterisk precision determined by peeking / shifting next argument.
-			if ( precision === '*' ) {
-				precision = args[ i - 1 ];
+			if (precision === '*') {
+				precision = args[i];
 				i++;
 			}
 
-			if ( name !== undefined ) {
-				// If it's a named argument, use name.
-				if ( args[ 0 ] && typeof args[ 0 ] === 'object' &&
-						args[ 0 ].hasOwnProperty( name ) ) {
-					value = args[ 0 ][ name ];
-				}
-			} else {
+			if (name === undefined) {
 				// If not a positional argument, use counter value.
-				if ( index === undefined ) {
-					index = i;
+				if (index === undefined) {
+					index = i + 1;
 				}
 
 				i++;
 
 				// Positional argument.
-				value = args[ index - 1 ];
+				value = args[index - 1];
+			} else if (
+				args[0] &&
+				typeof args[0] === 'object' &&
+				args[0].hasOwnProperty(name)
+			) {
+				// If it's a named argument, use name.
+				value = args[0][name];
 			}
 
 			// Parse as type.
-			if ( type === 'f' ) {
-				value = parseFloat( value ) || 0;
-			} else if ( type === 'd' ) {
-				value = parseInt( value ) || 0;
+			if (type === 'f') {
+				value = parseFloat(value) || 0;
+			} else if (type === 'd') {
+				value = parseInt(value) || 0;
 			}
 
 			// Apply precision.
-			if ( precision !== undefined ) {
-				if ( type === 'f' ) {
-					value = value.toFixed( precision );
-				} else if ( type === 's' ) {
-					value = value.substr( 0, precision );
+			if (precision !== undefined) {
+				if (type === 'f') {
+					value = value.toFixed(precision);
+				} else if (type === 's') {
+					value = value.substr(0, precision);
 				}
 			}
 
 			// To avoid "undefined" concatenation, return empty string if no
 			// placeholder substitution can be performed.
 			return value !== undefined && value !== null ? value : '';
-		} );
+		});
 	}
 
 	return sprintf;
 
-}());
+})();

package/dist/sprintf.min.js

@@ -1 +1 @@
-var sprintf=function(){"use strict";var t=/%(((\d+)\$)|(\(([$_a-zA-Z][$_a-zA-Z0-9]*)\)))?[ +0#-]*\d*(\.(\d+|\*))?(ll|[lhqL])?([cduxXefgsp%])/g;return function(r,o){var i;if(!Array.isArray(o))for(o=new Array(arguments.length-1),i=1;i<arguments.length;i++)o[i-1]=arguments[i];return i=1,r.replace(t,function(){var r,t,e,n,a;return r=arguments[3],t=arguments[5],e=arguments[7],"%"===(n=arguments[9])?"%":("*"===e&&(e=o[i-1],i++),void 0!==t?o[0]&&"object"==typeof o[0]&&o[0].hasOwnProperty(t)&&(a=o[0][t]):(void 0===r&&(r=i),i++,a=o[r-1]),"f"===n?a=parseFloat(a)||0:"d"===n&&(a=parseInt(a)||0),void 0!==e&&("f"===n?a=a.toFixed(e):"s"===n&&(a=a.substr(0,e))),null!=a?a:"")})}}();
+var sprintf=function(){"use strict";var r=/%(((\d+)\$)|(\(([$_a-zA-Z][$_a-zA-Z0-9]*)\)))?[ +0#-]*\d*(\.(\d+|\*))?(ll|[lhqL])?([cduxXefgsp%])/g;return function(t,...a){var e=0;return Array.isArray(a[0])&&(a=a[0]),t.replace(r,(function(){var r,t,n,o,s;return r=arguments[3],t=arguments[5],"%"===(o=arguments[9])?"%":("*"===(n=arguments[7])&&(n=a[e],e++),void 0===t?(void 0===r&&(r=e+1),e++,s=a[r-1]):a[0]&&"object"==typeof a[0]&&a[0].hasOwnProperty(t)&&(s=a[0][t]),"f"===o?s=parseFloat(s)||0:"d"===o&&(s=parseInt(s)||0),void 0!==n&&("f"===o?s=s.toFixed(n):"s"===o&&(s=s.substr(0,n))),null!=s?s:"")}))}}();

package/package.json

@@ -1,32 +1,41 @@
 {
-  "name": "@tannin/sprintf",
-  "version": "1.1.0",
-  "description": "printf string formatter",
-  "main": "build/index.js",
-  "module": "index.js",
-  "keywords": [],
-  "author": {
-    "name": "Andrew Duthie",
-    "email": "andrew@andrewduthie.com",
-    "url": "https://andrewduthie.com"
-  },
-  "homepage": "https://github.com/aduth/tannin",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/aduth/tannin.git",
-    "directory": "packages/sprintf"
-  },
-  "bugs": {
-    "url": "https://github.com/aduth/tannin/issues"
-  },
-  "license": "MIT",
-  "files": [
-    "index.js",
-    "build",
-    "dist"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "gitHead": "0e72800b6a32ef0bd82cb6d14c156bfa4093dc2c"
+	"name": "@tannin/sprintf",
+	"version": "1.3.0",
+	"type": "module",
+	"description": "printf string formatter",
+	"main": "build/index.js",
+	"module": "src/index.js",
+	"exports": {
+		".": {
+			"import": "./src/index.js",
+			"require": "./build/index.js"
+		}
+	},
+	"types": "src/index.d.ts",
+	"keywords": [],
+	"author": {
+		"name": "Andrew Duthie",
+		"email": "andrew@andrewduthie.com",
+		"url": "https://andrewduthie.com"
+	},
+	"homepage": "https://github.com/aduth/tannin",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/aduth/tannin.git",
+		"directory": "packages/sprintf"
+	},
+	"bugs": {
+		"url": "https://github.com/aduth/tannin/issues"
+	},
+	"license": "MIT",
+	"files": [
+		"src/index.js",
+		"src/index.d.ts",
+		"types/index.d.ts",
+		"build",
+		"dist"
+	],
+	"publishConfig": {
+		"access": "public"
+	}
 }

package/src/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Given a format string, returns string with arguments interpolatation.
+ * Arguments can either be provided directly via function arguments spread, or
+ * with an array as the second argument.
+ *
+ * @see https://en.wikipedia.org/wiki/Printf_format_string
+ *
+ * @example
+ *
+ * ```js
+ * import sprintf from '@tannin/sprintf';
+ *
+ * sprintf( 'Hello %s!', 'world' );
+ * // ⇒ 'Hello world!'
+ * ```
+ * @template {string} T
+ * @overload
+ * @param {T} string - string printf format string
+ * @param {...import('../types').SprintfArgs<T>} args - arguments to interpolate
+ *
+ * @return {string} Formatted string.
+ */
+export default function sprintf<T extends string>(string: T, ...args: import("../types").SprintfArgs<T>): string;
+/**
+ * Given a format string, returns string with arguments interpolatation.
+ * Arguments can either be provided directly via function arguments spread, or
+ * with an array as the second argument.
+ *
+ * @see https://en.wikipedia.org/wiki/Printf_format_string
+ *
+ * @example
+ *
+ * ```js
+ * import sprintf from '@tannin/sprintf';
+ *
+ * sprintf( 'Hello %s!', 'world' );
+ * // ⇒ 'Hello world!'
+ * ```
+ * @template {string} T
+ * @overload
+ * @param {T} string - string printf format string
+ * @param {import('../types').SprintfArgs<T>} args - arguments to interpolate
+ *
+ * @return {string} Formatted string.
+ */
+export default function sprintf<T extends string>(string: T, args: import("../types").SprintfArgs<T>): string;

package/{index.js → src/index.js}

@@ -29,14 +29,14 @@
  *
  * @type {RegExp}
  */
-var PATTERN = /%(((\d+)\$)|(\(([$_a-zA-Z][$_a-zA-Z0-9]*)\)))?[ +0#-]*\d*(\.(\d+|\*))?(ll|[lhqL])?([cduxXefgsp%])/g;
+var PATTERN =
+	/%(((\d+)\$)|(\(([$_a-zA-Z][$_a-zA-Z0-9]*)\)))?[ +0#-]*\d*(\.(\d+|\*))?(ll|[lhqL])?([cduxXefgsp%])/g;
 //               ▲         ▲                    ▲       ▲  ▲            ▲           ▲ type
 //               │         │                    │       │  │            └ Length (unsupported)
 //               │         │                    │       │  └ Precision / max width
 //               │         │                    │       └ Min width (unsupported)
 //               │         │                    └ Flags (unsupported)
 //               └ Index   └ Name (for named arguments)
-
 /**
  * Given a format string, returns string with arguments interpolatation.
  * Arguments can either be provided directly via function arguments spread, or
@@ -52,82 +52,133 @@ var PATTERN = /%(((\d+)\$)|(\(([$_a-zA-Z][$_a-zA-Z0-9]*)\)))?[ +0#-]*\d*(\.(\d+|
  * sprintf( 'Hello %s!', 'world' );
  * // ⇒ 'Hello world!'
  * ```
+ * @template {string} T
+ * @overload
+ * @param {T} string - string printf format string
+ * @param {...import('../types').SprintfArgs<T>} args - arguments to interpolate
  *
- * @param {string} string printf format string
- * @param {Array}  [args] String arguments.
+ * @return {string} Formatted string.
+ */
+
+/**
+ * Given a format string, returns string with arguments interpolatation.
+ * Arguments can either be provided directly via function arguments spread, or
+ * with an array as the second argument.
+ *
+ * @see https://en.wikipedia.org/wiki/Printf_format_string
+ *
+ * @example
+ *
+ * ```js
+ * import sprintf from '@tannin/sprintf';
+ *
+ * sprintf( 'Hello %s!', 'world' );
+ * // ⇒ 'Hello world!'
+ * ```
+ * @template {string} T
+ * @overload
+ * @param {T} string - string printf format string
+ * @param {import('../types').SprintfArgs<T>} args - arguments to interpolate
  *
  * @return {string} Formatted string.
  */
-export default function sprintf( string, args ) {
-	var i;
 
-	if ( ! Array.isArray( args ) ) {
-		// Construct a copy of arguments from index one, used for replace
-		// function placeholder substitution.
-		args = new Array( arguments.length - 1 );
-		for ( i = 1; i < arguments.length; i++ ) {
-			args[ i - 1 ] = arguments[ i ];
-		}
+/**
+ * Given a format string, returns string with arguments interpolatation.
+ * Arguments can either be provided directly via function arguments spread, or
+ * with an array as the second argument.
+ *
+ * @see https://en.wikipedia.org/wiki/Printf_format_string
+ *
+ * @example
+ *
+ * ```js
+ * import sprintf from '@tannin/sprintf';
+ *
+ * sprintf( 'Hello %s!', 'world' );
+ * // ⇒ 'Hello world!'
+ * ```
+ * @template {string} T
+ * @param {T} string - string printf format string
+ * @param {...import('../types').SprintfArgs<T>} args - arguments to interpolate
+ *
+ * @return {string} Formatted string.
+ */
+export default function sprintf(string, ...args) {
+	var i = 0;
+	if (Array.isArray(args[0])) {
+		args = /** @type {import('../types').SprintfArgs<T>[]} */ (
+			/** @type {unknown} */ args[0]
+		);
 	}
 
-	i = 1;
-
-	return string.replace( PATTERN, function() {
-		var index, name, precision, type, value;
+	return string.replace(PATTERN, function () {
+		var index,
+			// name needs to be documented as `string | undefined` else value will have tpye unknown.
+			/**
+			 * Name of the argument to substitute, if any.
+			 *
+			 * @type {string | undefined}
+			 */
+			name,
+			precision,
+			type,
+			value;
 
-		index = arguments[ 3 ];
-		name = arguments[ 5 ];
-		precision = arguments[ 7 ];
-		type = arguments[ 9 ];
+		index = arguments[3];
+		name = arguments[5];
+		precision = arguments[7];
+		type = arguments[9];
 
 		// There's no placeholder substitution in the explicit "%", meaning it
 		// is not necessary to increment argument index.
-		if ( type === '%' ) {
+		if (type === '%') {
 			return '%';
 		}
 
 		// Asterisk precision determined by peeking / shifting next argument.
-		if ( precision === '*' ) {
-			precision = args[ i - 1 ];
+		if (precision === '*') {
+			precision = args[i];
 			i++;
 		}
 
-		if ( name !== undefined ) {
-			// If it's a named argument, use name.
-			if ( args[ 0 ] && typeof args[ 0 ] === 'object' &&
-					args[ 0 ].hasOwnProperty( name ) ) {
-				value = args[ 0 ][ name ];
-			}
-		} else {
+		if (name === undefined) {
 			// If not a positional argument, use counter value.
-			if ( index === undefined ) {
-				index = i;
+			if (index === undefined) {
+				index = i + 1;
 			}
 
 			i++;
 
 			// Positional argument.
-			value = args[ index - 1 ];
+			value = args[index - 1];
+		} else if (
+			args[0] &&
+			typeof args[0] === 'object' &&
+			args[0].hasOwnProperty(name)
+		) {
+			// If it's a named argument, use name.
+			value = args[0][name];
 		}
 
 		// Parse as type.
-		if ( type === 'f' ) {
-			value = parseFloat( value ) || 0;
-		} else if ( type === 'd' ) {
-			value = parseInt( value ) || 0;
+		if (type === 'f') {
+			value = parseFloat(value) || 0;
+		} else if (type === 'd') {
+			value = parseInt(value) || 0;
 		}
 
 		// Apply precision.
-		if ( precision !== undefined ) {
-			if ( type === 'f' ) {
-				value = value.toFixed( precision );
-			} else if ( type === 's' ) {
-				value = value.substr( 0, precision );
+		if (precision !== undefined) {
+			if (type === 'f') {
+				value = value.toFixed(precision);
+			} else if (type === 's') {
+				value = value.substr(0, precision);
 			}
 		}
 
 		// To avoid "undefined" concatenation, return empty string if no
 		// placeholder substitution can be performed.
 		return value !== undefined && value !== null ? value : '';
-	} );
+	});
 }

package/types/index.d.ts

@@ -0,0 +1,87 @@
+type Specifiers = {
+	s: string;
+	d: number;
+	f: number;
+};
+type S = keyof Specifiers;
+
+type BuildTuple<L extends number, T extends any[] = []> = T['length'] extends L
+	? T
+	: BuildTuple<L, [any, ...T]>;
+
+type Subtract1<N extends number> = BuildTuple<N> extends [any, ...infer Rest]
+	? Rest['length']
+	: never;
+
+type StripEscapedPercents<T extends string> =
+	T extends `${infer Head}%%${infer Tail}`
+		? `${Head}${StripEscapedPercents<Tail>}`
+		: T;
+
+type HasNamedPlaceholders<T extends string> =
+	StripEscapedPercents<T> extends `${any}%(${string})${S}${string}`
+		? true
+		: false;
+
+type HasPositionalPlaceholders<T extends string> =
+	StripEscapedPercents<T> extends `${any}%${number}$${S}${string}`
+		? true
+		: false;
+
+type HasUnnamedPlaceholders<T extends string> =
+	StripEscapedPercents<T> extends `${any}%${S}${string}` ? true : false;
+
+type HasDynamicPrecisionPlaceholders<T extends string> =
+	StripEscapedPercents<T> extends `${any}%.*${S}${any}` ? true : false;
+
+type HasStaticPrecisionPlaceholders<T extends string> =
+	StripEscapedPercents<T> extends `${any}%.${number}${S}${any}` ? true : false;
+
+type ExtractNamedPlaceholders<T extends string> =
+	StripEscapedPercents<T> extends `${any}%(${infer Key})${infer Spec}${infer Rest}`
+		? Spec extends S
+			? { [K in Key]: Specifiers[Spec] } & ExtractNamedPlaceholders<Rest>
+			: never
+		: {};
+
+type ExtractPositionalPlaceholders<T extends string> =
+	StripEscapedPercents<T> extends `${any}%${infer Index extends number}$${infer Spec}${infer Rest}`
+		? Spec extends S
+			? {
+					[K in Subtract1<Index>]: Specifiers[Spec];
+			  } & ExtractPositionalPlaceholders<Rest>
+			: ExtractPositionalPlaceholders<Rest>
+		:  unknown[];
+
+type ExtractStaticPrecisionPlaceholders<T extends string> =
+	StripEscapedPercents<T> extends `${any}%.${infer Precision extends number}${infer Spec}${infer Rest}`
+		? Spec extends S
+			? [Specifiers[Spec], ...ExtractStaticPrecisionPlaceholders<Rest>]
+			: never
+		: [];
+
+type ExtractDynamicPrecisionPlaceholder<T extends string> =
+	StripEscapedPercents<T> extends `${any}%.*${infer Spec}${infer Rest}`
+		? Spec extends S
+			? [number, Specifiers[Spec], ...ExtractDynamicPrecisionPlaceholder<Rest>]
+			: never
+		: [];
+
+type ExtractUnnamedPlaceholders<T extends string> =
+	StripEscapedPercents<T> extends `${any}%${infer Spec}${infer Rest}`
+		? Spec extends S
+			? [Specifiers[Spec], ...ExtractUnnamedPlaceholders<Rest>]
+			: never
+		: [];
+
+export type SprintfArgs<T extends string> = HasNamedPlaceholders<T> extends true
+	? [values: ExtractNamedPlaceholders<T>]
+	: HasDynamicPrecisionPlaceholders<T> extends true
+	? ExtractDynamicPrecisionPlaceholder<T>
+	: HasStaticPrecisionPlaceholders<T> extends true
+	? ExtractStaticPrecisionPlaceholders<T>
+	: HasPositionalPlaceholders<T> extends true
+	? ExtractPositionalPlaceholders<T>
+	: HasUnnamedPlaceholders<T> extends true
+	? ExtractUnnamedPlaceholders<T>
+	: [];

package/CHANGELOG.md

@@ -1,25 +0,0 @@
-## 1.1.0 (2019-11-27)
-
-New Features
-
-- Add support for named arguments
-
-Bugfix
-
-- Fix handling of falsy values, notably 0
-
-## 1.0.2 (2019-03-07)
-
-Internal
-
-- Add `repository.directory` to `package.json`
-
-## 1.0.1 (2019-01-19)
-
-Documentation
-
-- Correct documentation unpkg links
-
-Internal
-
-- Use Lerna for managing mono-repo

package/LICENSE.md

@@ -1,7 +0,0 @@
-[The MIT License (MIT)](https://opensource.org/licenses/MIT)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.