@d3plus/format 3.0.16 → 3.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 D3plus
+
+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.

package/README.md

@@ -1,5 +1,8 @@
 # @d3plus/format
-  
+
+[![NPM version](https://img.shields.io/npm/v/@d3plus/format.svg)](https://www.npmjs.com/package/@d3plus/format)
+[![codecov](https://codecov.io/gh/d3plus/d3plus/graph/badge.svg?flag=format)](https://codecov.io/gh/d3plus/d3plus/flags)
+
 JavaScript formatters for localized numbers and dates.
 
 ## Installing
@@ -7,10 +10,10 @@ JavaScript formatters for localized numbers and dates.
 If using npm, `npm install @d3plus/format`. Otherwise, you can download the [latest release from GitHub](https://github.com/d3plus/d3plus/releases/latest) or load from a [CDN](https://cdn.jsdelivr.net/npm/@d3plus/format).
 
 ```js
-import modules from "@d3plus/format";
+import {*} from "@d3plus/format";
 ```
 
-In vanilla JavaScript, a `d3plus` global is exported from the pre-bundled version:
+In a vanilla environment, a `d3plus` global is exported from the pre-bundled version:
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/@d3plus/format"></script>
@@ -21,55 +24,103 @@ In vanilla JavaScript, a `d3plus` global is exported from the pre-bundled versio
 
 ## Examples
 
-Live examples can be found on [d3plus.org](https://d3plus.org/), which includes a collection of example visualizations using @d3plus/react.
+Live examples can be found on [d3plus.org](https://d3plus.org/), which includes a collection of example visualizations using [@d3plus/react](https://github.com/d3plus/d3plus/tree/main/packages/react).
 
 ## API Reference
 
-##### 
-* [format](#format) - An extension to d3's [format](https://github.com/d3/d3-format#api-reference) function that adds more string formatting types and localizations.
-* [formatAbbreviate](#formatAbbreviate) - Formats a number to an appropriate number of decimal places and rounding, adding suffixes if applicable (ie. `1200000` to `"1.2M"`).
-* [formatDate](#formatDate) - A default set of date formatters, which takes into account both the interval in between in each data point but also the start/end data points.
-* [formatDefaultLocale](#formatDefaultLocale) - An extension to d3's [formatDefaultLocale](https://github.com/d3/d3-format#api-reference) function that allows setting the locale globally for formatters.
+| Functions | Description |
+| --- | --- |
+| [`format`](#format) |  |
+| [`formatAbbreviate`](#formatabbreviate) | Formats a number to an appropriate number of decimal places and rounding, adding suffixes if applicable (ie. `1200000` t |
+| [`formatDate`](#formatdate) | A default set of date formatters, which takes into account both the interval in between in each data point but also the  |
+| [`formatDefaultLocale`](#formatdefaultlocale) | An extension to d3's [formatDefaultLocale](https://github.com/d3/d3-format#api-reference) function that allows setting t |
+
+## Functions
+
+<a id="format"></a>
+
+### format()
 
----
+> **format**(`specifier`: `string`): `Formatter`
 
-<a name="format"></a>
-#### d3plus.**format**(specifier) [<>](https://github.com/d3plus/d3plus/blob/main/packages/format/src/format.js#L4)
+Defined in: [format.ts:10](https://github.com/d3plus/d3plus/blob/fe174c3153bf379a226e4a41b6a8492a86c3a1b7/packages/format/src/format.ts#L10)
 
-An extension to d3's [format](https://github.com/d3/d3-format#api-reference) function that adds more string formatting types and localizations.
+#### Parameters
 
+| Parameter | Type |
+| ------ | ------ |
+| `specifier` | `string` |
 
-This is a global function
+#### Returns
 
----
+`Formatter`
 
-<a name="formatAbbreviate"></a>
-#### d3plus.**formatAbbreviate**(n, locale) [<>](https://github.com/d3plus/d3plus/blob/main/packages/format/src/formatAbbreviate.js#L38)
+***
+
+<a id="formatabbreviate"></a>
+
+### formatAbbreviate()
+
+> **formatAbbreviate**(`n`: `string` \| `number`, `locale?`: `string` \| `FormatLocaleDefinition`, `precision?`: `string`): `string`
+
+Defined in: [formatAbbreviate.ts:55](https://github.com/d3plus/d3plus/blob/fe174c3153bf379a226e4a41b6a8492a86c3a1b7/packages/format/src/formatAbbreviate.ts#L55)
 
 Formats a number to an appropriate number of decimal places and rounding, adding suffixes if applicable (ie. `1200000` to `"1.2M"`).
 
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| ------ | ------ | ------ | ------ |
+| `n` | `string` \| `number` | *required* | The number to be formatted. |
+| `locale` | `string` \| `FormatLocaleDefinition` | `"en-US"` | The locale config to be used. If an object is provided, the function will format the numbers according to the object. The object must include `suffixes`, `delimiter` and `currency` properties. |
+| `precision?` | `string` | *required* | Number of significant digits to display. |
 
-This is a global function
+#### Returns
 
----
+`string`
 
-<a name="formatDate"></a>
-#### d3plus.**formatDate**(d, dataArray, [formatter]) [<>](https://github.com/d3plus/d3plus/blob/main/packages/format/src/formatDate.js#L4)
+***
+
+<a id="formatdate"></a>
+
+### formatDate()
+
+> **formatDate**(`d`: `Date`, `dataArray`: `Date`[], `formatter?`: `DateFormatter`): `string`
+
+Defined in: [formatDate.ts:12](https://github.com/d3plus/d3plus/blob/fe174c3153bf379a226e4a41b6a8492a86c3a1b7/packages/format/src/formatDate.ts#L12)
 
 A default set of date formatters, which takes into account both the interval in between in each data point but also the start/end data points.
 
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| ------ | ------ | ------ | ------ |
+| `d` | `Date` | *required* | The date to format. |
+| `dataArray` | `Date`[] | *required* | The full array of ordered Date Objects. |
+| `formatter` | `DateFormatter` | `timeFormat` | Optional custom format string or function. |
+
+#### Returns
+
+`string`
+
+***
+
+<a id="formatdefaultlocale"></a>
 
-This is a global function
+### formatDefaultLocale()
 
----
+> **formatDefaultLocale**(`definition`: `FormatLocaleDefinition`): `Record`\<`string`, `unknown`\>
 
-<a name="formatDefaultLocale"></a>
-#### d3plus.**formatDefaultLocale**(definition) [<>](https://github.com/d3plus/d3plus/blob/main/packages/format/src/formatDefaultLocale.js#L4)
+Defined in: [formatDefaultLocale.ts:8](https://github.com/d3plus/d3plus/blob/fe174c3153bf379a226e4a41b6a8492a86c3a1b7/packages/format/src/formatDefaultLocale.ts#L8)
 
 An extension to d3's [formatDefaultLocale](https://github.com/d3/d3-format#api-reference) function that allows setting the locale globally for formatters.
 
+#### Parameters
 
-This is a global function
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `definition` | `FormatLocaleDefinition` | The localization definition. |
 
----
+#### Returns
 
+`Record`\<`string`, `unknown`\>

package/es/src/format.js

@@ -1,11 +1,6 @@
 import abbreviate from "./formatAbbreviate.js";
 import { format } from "d3-format";
-/**
-    @function format
-    @desc An extension to d3's [format](https://github.com/d3/d3-format#api-reference) function that adds more string formatting types and localizations.
-    @param {String} specifier The string specifier used by the format function.
-    @returns {Function}
-*/ export default function(specifier) {
+export default function(specifier) {
     if (specifier === ".3~a") return abbreviate;
     return format(specifier);
-};
+}

package/es/src/formatAbbreviate.js

@@ -4,14 +4,14 @@ function _type_of(obj) {
 }
 import { formatLocale } from "d3-format";
 import { formatLocale as defaultLocale } from "@d3plus/locales";
-var round = function(x, n) {
-    return parseFloat(Math.round(x * Math.pow(10, n)) / Math.pow(10, n)).toFixed(n);
+var round = function round(x, n) {
+    return parseFloat((Math.round(x * Math.pow(10, n)) / Math.pow(10, n)).toString()).toFixed(n);
 };
 /**
  * @private
-*/ function formatSuffix(str, precision, suffixes) {
+ */ function formatSuffix(str, precision, suffixes) {
     var i = 0;
-    var value = parseFloat(str.replace("−", "-"), 10);
+    var value = parseFloat(str.replace("\u2212", "-"));
     if (value) {
         if (value < 0) value *= -1;
         i = 1 + Math.floor(1e-12 + Math.log(value) / Math.LN10);
@@ -25,7 +25,7 @@ var round = function(x, n) {
 }
 /**
  * @private
-*/ function parseSuffixes(d, i) {
+ */ function parseSuffixes(d, i) {
     var k = Math.pow(10, Math.abs(8 - i) * 3);
     return {
         scale: i > 8 ? function(d) {
@@ -37,14 +37,13 @@ var round = function(x, n) {
     };
 }
 /**
-    @function formatAbbreviate
-    @desc Formats a number to an appropriate number of decimal places and rounding, adding suffixes if applicable (ie. `1200000` to `"1.2M"`).
-    @param {Number|String} n The number to be formatted.
-    @param {Object|String} locale The locale config to be used. If *value* is an object, the function will format the numbers according the object. The object must include `suffixes`, `delimiter` and `currency` properties.
-    @returns {String}
-*/ export default function(n) {
-    var locale = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : "en-US", precision = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : undefined;
-    if (isFinite(n)) n *= 1;
+    Formats a number to an appropriate number of decimal places and rounding, adding suffixes if applicable (ie. `1200000` to `"1.2M"`).
+    @param n The number to be formatted.
+    @param locale The locale config to be used. If an object is provided, the function will format the numbers according to the object. The object must include `suffixes`, `delimiter` and `currency` properties.
+    @param precision Number of significant digits to display.
+*/ export default function formatAbbreviate(n) {
+    var locale = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : "en-US", precision = arguments.length > 2 ? arguments[2] : void 0;
+    if (isFinite(n)) n = n * 1;
     else return "N/A";
     var negative = n < 0;
     var length = n.toString().split(".")[0].replace("-", "").length, localeConfig = (typeof locale === "undefined" ? "undefined" : _type_of(locale)) === "object" ? locale : defaultLocale[locale] || defaultLocale["en-US"], suffixes = localeConfig.suffixes.map(parseSuffixes);
@@ -71,7 +70,7 @@ var round = function(x, n) {
     } else if (length === 3) val = d3plusFormatLocale.format(",f")(n);
     else if (n < 1 && n > -1) val = d3plusFormatLocale.format(".2g")(n);
     else val = d3plusFormatLocale.format(".3g")(n);
-    return "".concat(negative && val.charAt(0) !== "−" ? "−" : "").concat(val).replace(/−/g, "-") // replace new d3 default minus sign (−) to hyphen-minus (-)
+    return "".concat(negative && val.charAt(0) !== "\u2212" ? "\u2212" : "").concat(val).replace(/\u2212/g, "-") // replace new d3 default minus sign (\u2212) to hyphen-minus (-)
     .replace(/(\.[0]*[1-9]*)[0]*$/g, "$1") // removes any trailing zeros
     .replace(/\.[0]*$/g, ""); // removes any trailing decimal point
 }

package/es/src/formatDate.js

@@ -47,13 +47,11 @@ function _unsupported_iterable_to_array(o, minLen) {
 import { timeYear, timeMonth, timeHour, timeMinute, timeSecond } from "d3-time";
 import { timeFormat } from "d3-time-format";
 /**
-    @function formatDate
-    @desc A default set of date formatters, which takes into account both the interval in between in each data point but also the start/end data points.
-    @param {Date} d The date string to be formatted.
-    @param {Array} dataArray The full array of ordered Date Objects.
-    @param {Function} [formatter = d3.timeFormat] An optional instance of d3.timeFormat to be used for localization.
-    @returns {String}
-*/ export default function(d, dataArray) {
+    A default set of date formatters, which takes into account both the interval in between in each data point but also the start/end data points.
+    @param d The date to format.
+    @param dataArray The full array of ordered Date Objects.
+    @param formatter Optional custom format string or function.
+*/ export default function formatDate(d, dataArray) {
     var formatter = arguments.length > 2 && arguments[2] !== void 0 ? arguments[2] : timeFormat;
     var formatHour = formatter("%I %p"), formatMillisecond = formatter(".%L"), formatMinute = formatter("%I:%M"), formatMonth = formatter("%b"), formatMonthDay = formatter("%b %-d"), formatMonthDayYear = formatter("%b %-d, %Y"), formatMonthYear = formatter("%b %Y"), formatQuarter = formatter("Q%q"), formatQuarterYear = formatter("Q%q %Y"), formatSecond = formatter(":%S"), formatYear = formatter("%Y");
     var labelIndex = dataArray.findIndex(function(a) {
@@ -65,8 +63,8 @@ import { timeFormat } from "d3-time-format";
         if (i) {
             arr[0].push(d.getFullYear() - dataArray[i - 1].getFullYear());
             arr[1].push(monthDiff(dataArray[i - 1], d));
-            arr[2].push(Math.round((d - dataArray[i - 1]) / (1000 * 60 * 60 * 24)));
-            arr[3].push(Math.round((d - dataArray[i - 1]) / (1000 * 60 * 60)));
+            arr[2].push(Math.round((+d - +dataArray[i - 1]) / (1000 * 60 * 60 * 24)));
+            arr[3].push(Math.round((+d - +dataArray[i - 1]) / (1000 * 60 * 60)));
         }
         return arr;
     }, [
@@ -77,26 +75,26 @@ import { timeFormat } from "d3-time-format";
     ]), 4), yearlySteps = _dataArray_reduce[0], monthlySteps = _dataArray_reduce[1], dailySteps = _dataArray_reduce[2], hourlySteps = _dataArray_reduce[3];
     return (yearlySteps.every(function(s) {
         return s >= 1 && !(s % 1);
-    }) // Yearly Data 
+    }) // Yearly Data
      ? formatYear : monthlySteps.every(function(s) {
         return s >= 3 && !(s % 3);
     }) // Quarterly Data
-     ? +timeYear(d) === d || firstOrLast || smallArray ? formatQuarterYear : formatQuarter : monthlySteps.every(function(s) {
+     ? +timeYear(d) === +d || firstOrLast || smallArray ? formatQuarterYear : formatQuarter : monthlySteps.every(function(s) {
         return s >= 1 && !(s % 1);
     }) // Monthly Data
-     ? +timeYear(d) === d || firstOrLast || smallArray ? formatMonthYear : formatMonth : dailySteps.every(function(s) {
+     ? +timeYear(d) === +d || firstOrLast || smallArray ? formatMonthYear : formatMonth : dailySteps.every(function(s) {
         return s >= 1 && !(s % 1);
     }) // Daily Data
-     ? +timeYear(d) === d || firstOrLast || smallArray ? formatMonthDayYear : formatMonthDay : hourlySteps.every(function(s) {
+     ? +timeYear(d) === +d || firstOrLast || smallArray ? formatMonthDayYear : formatMonthDay : hourlySteps.every(function(s) {
         return s >= 1 && !(s % 1);
     }) // Hourly Data
-     ? firstOrLast || smallArray ? formatMonthDayYear : +timeMonth(d) === d ? formatMonthDay : formatHour : timeSecond(d) < d ? formatMillisecond : timeMinute(d) < d ? formatSecond : timeHour(d) < d ? formatMinute : d)(d);
+     ? firstOrLast || smallArray ? formatMonthDayYear : +timeMonth(d) === +d ? formatMonthDay : formatHour : timeSecond(d) < d ? formatMillisecond : timeMinute(d) < d ? formatSecond : timeHour(d) < d ? formatMinute : function(_d) {
+        return _d.toString();
+    })(d);
 }
 /**
-    @function monthDiff
-    @desc Returns the number of months between two Date objects
-    @param {*} d1
-    @param {*} d2
+    Returns the number of months between two Date objects
+
     @returns {Number} the number of months between the two Date objects
     @private
 */ function monthDiff(d1, d2) {

package/es/src/formatDefaultLocale.js

@@ -1,12 +1,10 @@
 import format from "./format.js";
 import { formatDefaultLocale } from "d3-format";
 /**
-    @function formatDefaultLocale
-    @desc An extension to d3's [formatDefaultLocale](https://github.com/d3/d3-format#api-reference) function that allows setting the locale globally for formatters.
-    @param {Object} definition The localization definition.
-    @returns {Object}
+    An extension to d3's [formatDefaultLocale](https://github.com/d3/d3-format#api-reference) function that allows setting the locale globally for formatters.
+    @param definition The localization definition.
 */ export default function(definition) {
     var locale = formatDefaultLocale(definition);
     locale.format = format;
     return locale;
-};
+}

package/package.json

@@ -1,18 +1,25 @@
 {
   "name": "@d3plus/format",
-  "version": "3.0.16",
+  "version": "3.1.1",
   "description": "JavaScript formatters for localized numbers and dates.",
   "license": "MIT",
   "type": "module",
-  "exports": "./es/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./es/index.js"
+    }
+  },
   "browser": "./umd/d3plus-format.full.js",
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "sideEffects": false,
   "files": [
     "umd",
-    "es"
+    "es",
+    "types"
   ],
   "homepage": "https://d3plus.org",
   "repository": {
@@ -27,16 +34,18 @@
     "data",
     "visualization"
   ],
+  "dependencies": {
+    "d3-format": "^3.1.0",
+    "d3-time": "^3.1.0",
+    "d3-time-format": "^4.1.0",
+    "@d3plus/locales": "3.1.1"
+  },
   "scripts": {
     "build:esm": "node ../../scripts/build-esm.js",
+    "build:types": "tsc",
     "build:umd": "node ../../scripts/build-umd.js",
     "dev": "node ../../scripts/dev.js",
-    "test": "eslint index.js src/**/*.js && eslint --global=it test && mocha 'test/**/*-test.js'"
-  },
-  "dependencies": {
-    "@d3plus/locales": "3.0.16",
-    "d3-format": "^3.1.0",
-    "d3-time": "^3.1.0",
-    "d3-time-format": "^4.1.0"
+    "test": "eslint index.ts src/**/*.ts && eslint --global=it test && mocha 'test/**/*-test.js'",
+    "test:coverage": "c8 -r text -r lcov --src src mocha 'test/**/*-test.js'"
   }
 }

package/types/index.d.ts

@@ -0,0 +1,4 @@
+export { default as format } from "./src/format.js";
+export { default as formatDefaultLocale } from "./src/formatDefaultLocale.js";
+export { default as formatAbbreviate } from "./src/formatAbbreviate.js";
+export { default as formatDate } from "./src/formatDate.js";

package/types/src/format.d.ts

@@ -0,0 +1,9 @@
+/**
+    An extension to d3's [format](https://github.com/d3/d3-format#api-reference) function that adds more string formatting types and localizations.
+    @param specifier The string specifier used by the format function.
+*/
+type Formatter = (n: number | string | {
+    valueOf(): number;
+}) => string;
+export default function (specifier: string): Formatter;
+export {};

package/types/src/formatAbbreviate.d.ts

@@ -0,0 +1,8 @@
+import type { FormatLocaleDefinition } from "@d3plus/locales";
+/**
+    Formats a number to an appropriate number of decimal places and rounding, adding suffixes if applicable (ie. `1200000` to `"1.2M"`).
+    @param n The number to be formatted.
+    @param locale The locale config to be used. If an object is provided, the function will format the numbers according to the object. The object must include `suffixes`, `delimiter` and `currency` properties.
+    @param precision Number of significant digits to display.
+*/
+export default function formatAbbreviate(n: number | string, locale?: string | FormatLocaleDefinition, precision?: string): string;

package/types/src/formatDate.d.ts

@@ -0,0 +1,9 @@
+type DateFormatter = (specifier: string) => (date: Date) => string;
+/**
+    A default set of date formatters, which takes into account both the interval in between in each data point but also the start/end data points.
+    @param d The date to format.
+    @param dataArray The full array of ordered Date Objects.
+    @param formatter Optional custom format string or function.
+*/
+export default function formatDate(d: Date, dataArray: Date[], formatter?: DateFormatter): string;
+export {};

package/types/src/formatDefaultLocale.d.ts

@@ -0,0 +1,6 @@
+import { formatDefaultLocale } from "d3-format";
+/**
+    An extension to d3's [formatDefaultLocale](https://github.com/d3/d3-format#api-reference) function that allows setting the locale globally for formatters.
+    @param definition The localization definition.
+*/
+export default function (definition: Parameters<typeof formatDefaultLocale>[0]): Record<string, unknown>;