@thi.ng/date 2.4.26 → 2.5.2

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-11-01T11:05:34Z
+- **Last updated**: 2023-11-09T10:28:18Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,13 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [2.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/date@2.5.0) (2023-11-04)
+
+#### 🚀 Features
+
+- add durationAs() & asXXX() duration helpers ([ad17cee](https://github.com/thi-ng/umbrella/commit/ad17cee))
+- add absDifference(), add/update docs ([9b54f6c](https://github.com/thi-ng/umbrella/commit/9b54f6c))
+
 ### [2.4.10](https://github.com/thi-ng/umbrella/tree/@thi.ng/date@2.4.10) (2023-03-27)
 
 #### ♻️ Refactoring

package/README.md

@@ -58,7 +58,7 @@ For Node.js REPL:
 const date = await import("@thi.ng/date");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 5.12 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 5.34 KB
 
 ## Dependencies
 
@@ -176,14 +176,20 @@ a.eqDelta(a.add(99, "t"), 100)
 a.compare(a.add(1, "s"))
 // -1000
 
-// compute difference between dates (in milliseconds)
+// compute (signed) difference between dates (in milliseconds)
 difference(a, "1970-01-01") === a.getTime()
 // true
 
-difference("2021-02", "2020-02")
+// difference = a - b
+difference("2020-02", "2021-02")
+// -31622400000
+
+// always produces unsigned result
+absDifference("2020-02", "2021-02")
 // 31622400000
 
-difference("2021-02", "2020-02") / DAY
+// compute abs difference in days
+asDays(absDifference("2020-02", "2021-02"))
 // 366 (because 2020 was a leap year)
 ```
 

package/api.d.ts

@@ -158,6 +158,11 @@ export type EpochIterator = IterableIterator<number>;
  */
 export type Precision = "y" | "M" | "d" | "h" | "m" | "s" | "t";
 export type Period = Precision | "w" | "q";
+/**
+ * Object which maps {@link Period} IDs to their respective values (in
+ * milliseconds).
+ */
+export declare const PERIODS: Record<Period, number>;
 export type FormatFn = Fn2<Date, boolean, string>;
 export type MaybeDate = DateTime | Date | number | string;
 /**

package/api.js

@@ -40,3 +40,18 @@ export const YEAR = (DAYS_IN_400YEARS / 400) * DAY;
  * Mean month duration (30.436875 days) in milliseconds
  */
 export const MONTH = YEAR / 12;
+/**
+ * Object which maps {@link Period} IDs to their respective values (in
+ * milliseconds).
+ */
+export const PERIODS = {
+    y: YEAR,
+    M: MONTH,
+    d: DAY,
+    h: HOUR,
+    m: MINUTE,
+    s: SECOND,
+    t: 1,
+    w: WEEK,
+    q: 3 * MONTH,
+};

package/datetime.js

@@ -13,6 +13,13 @@ export const dateTime = (epoch, prec) => new DateTime(epoch, prec);
  * UTC only.
  */
 export class DateTime {
+    t;
+    s;
+    m;
+    h;
+    d;
+    M;
+    y;
     constructor(epoch = Date.now(), prec = "t") {
         const x = ensureDate(epoch);
         const id = __precisionToID(prec);

package/duration.d.ts

@@ -19,4 +19,59 @@ export declare const decomposeDuration: (dur: number) => number[];
  * @param parts
  */
 export declare const composeDuration: (parts: Partial<Record<Precision, number>>) => number;
+/**
+ * Calculates the given duration in units of given `prec`ision.
+ *
+ * @example
+ * ```ts
+ * durationAs("d", difference("2023-02-01T12:00:00Z", "2023-01-01"))
+ * // 31.5
+ * ```
+ *
+ * @param prec
+ * @param dur
+ */
+export declare const durationAs: (prec: Precision, dur: number) => number;
+/**
+ * Returns duration in seconds.
+ *
+ * @param dur
+ */
+export declare const asSeconds: (dur: number) => number;
+/**
+ * Returns duration in minutes.
+ *
+ * @param dur
+ */
+export declare const asMinutes: (dur: number) => number;
+/**
+ * Returns duration in hours.
+ *
+ * @param dur
+ */
+export declare const asHours: (dur: number) => number;
+/**
+ * Returns duration in days.
+ *
+ * @param dur
+ */
+export declare const asDays: (dur: number) => number;
+/**
+ * Returns duration in weeks.
+ *
+ * @param dur
+ */
+export declare const asWeeks: (dur: number) => number;
+/**
+ * Returns duration in months (as defined by {@link MONTH})..
+ *
+ * @param dur
+ */
+export declare const asMonths: (dur: number) => number;
+/**
+ * Returns duration in years (as defined by {@link YEAR}).
+ *
+ * @param dur
+ */
+export declare const asYears: (dur: number) => number;
 //# sourceMappingURL=duration.d.ts.map

package/duration.js

@@ -1,4 +1,4 @@
-import { YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, } from "./api.js";
+import { DAY, HOUR, MINUTE, MONTH, PERIODS, SECOND, WEEK, YEAR, } from "./api.js";
 /**
  * Decomposes given duration (in milliseconds) into a tuple of: `[year, month,
  * day, hour, minute, second, millis]`.
@@ -42,3 +42,58 @@ export const composeDuration = (parts) => {
     dur += parts.t || 0;
     return dur;
 };
+/**
+ * Calculates the given duration in units of given `prec`ision.
+ *
+ * @example
+ * ```ts
+ * durationAs("d", difference("2023-02-01T12:00:00Z", "2023-01-01"))
+ * // 31.5
+ * ```
+ *
+ * @param prec
+ * @param dur
+ */
+export const durationAs = (prec, dur) => dur / PERIODS[prec];
+/**
+ * Returns duration in seconds.
+ *
+ * @param dur
+ */
+export const asSeconds = (dur) => dur / SECOND;
+/**
+ * Returns duration in minutes.
+ *
+ * @param dur
+ */
+export const asMinutes = (dur) => dur / MINUTE;
+/**
+ * Returns duration in hours.
+ *
+ * @param dur
+ */
+export const asHours = (dur) => dur / HOUR;
+/**
+ * Returns duration in days.
+ *
+ * @param dur
+ */
+export const asDays = (dur) => dur / DAY;
+/**
+ * Returns duration in weeks.
+ *
+ * @param dur
+ */
+export const asWeeks = (dur) => dur / WEEK;
+/**
+ * Returns duration in months (as defined by {@link MONTH})..
+ *
+ * @param dur
+ */
+export const asMonths = (dur) => dur / MONTH;
+/**
+ * Returns duration in years (as defined by {@link YEAR}).
+ *
+ * @param dur
+ */
+export const asYears = (dur) => dur / YEAR;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/date",
-  "version": "2.4.26",
+  "version": "2.5.2",
   "description": "Datetime types, relative dates, math, iterators, composable formatters, locales",
   "type": "module",
   "module": "./index.js",
@@ -28,22 +28,21 @@
     "clean": "rimraf --glob '*.js' '*.d.ts' '*.map' doc internal i18n",
     "doc": "typedoc --excludePrivate --excludeInternal --out doc src/index.ts",
     "doc:ae": "mkdir -p .ae/doc .ae/temp && api-extractor run --local --verbose",
-    "doc:readme": "yarn doc:stats && tools:readme",
-    "doc:stats": "tools:module-stats",
+    "doc:readme": "bun ../../tools/src/module-stats.ts && bun ../../tools/src/readme.ts",
     "pub": "yarn npm publish --access public",
-    "test": "testament test"
+    "test": "bun test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.6",
-    "@thi.ng/checks": "^3.4.6",
-    "@thi.ng/strings": "^3.6.3"
+    "@thi.ng/api": "^8.9.8",
+    "@thi.ng/checks": "^3.4.8",
+    "@thi.ng/strings": "^3.6.6"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.38.0",
-    "@thi.ng/testament": "^0.3.24",
+    "@microsoft/api-extractor": "^7.38.2",
+    "@thi.ng/testament": "^0.4.1",
     "rimraf": "^5.0.5",
     "tools": "^0.0.1",
-    "typedoc": "^0.25.2",
+    "typedoc": "^0.25.3",
     "typescript": "^5.2.2"
   },
   "keywords": [
@@ -132,5 +131,5 @@
   "thi.ng": {
     "year": 2020
   },
-  "gitHead": "351014d081cee85803950eb6751c5a02dca2efbd\n"
+  "gitHead": "669a3151e4302480244fe3e60eff5e732ea5b7a7\n"
 }

package/relative.d.ts

@@ -50,12 +50,25 @@ export declare const parseRelative: (offset: string, base?: MaybeDate) => DateTi
 export declare const relative: (num: number, period: Period, base?: MaybeDate) => DateTime;
 /**
  * Returns the signed difference in milliseconds between given two dates `a` and
- * `b`.
+ * `b` (as `diff = a - b`).
+ *
+ * @remarks
+ * Also see {@link absDifference}.
  *
  * @param a -
  * @param b -
  */
 export declare const difference: (a: MaybeDate, b: MaybeDate) => number;
+/**
+ * Returns the unsigned difference in milliseconds between given dates.
+ *
+ * @remarks
+ * Also see {@link difference} for signed difference.
+ *
+ * @param a
+ * @param b
+ */
+export declare const absDifference: (a: MaybeDate, b: MaybeDate) => number;
 /**
  * Computes and decomposes difference between given dates. Returns tuple of:
  * `[sign, years, months, days, hours, mins, secs, millis]`. The `sign` is used

package/relative.js

@@ -106,12 +106,25 @@ const parsePeriod = (x) => {
 export const relative = (num, period, base = dateTime()) => dateTime(base).add(num, period);
 /**
  * Returns the signed difference in milliseconds between given two dates `a` and
- * `b`.
+ * `b` (as `diff = a - b`).
+ *
+ * @remarks
+ * Also see {@link absDifference}.
  *
  * @param a -
  * @param b -
  */
 export const difference = (a, b) => ensureEpoch(a) - ensureEpoch(b);
+/**
+ * Returns the unsigned difference in milliseconds between given dates.
+ *
+ * @remarks
+ * Also see {@link difference} for signed difference.
+ *
+ * @param a
+ * @param b
+ */
+export const absDifference = (a, b) => Math.abs(difference(a, b));
 /**
  * Computes and decomposes difference between given dates. Returns tuple of:
  * `[sign, years, months, days, hours, mins, secs, millis]`. The `sign` is used