@thi.ng/date 2.4.25 → 2.5.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-10-30T14:31:56Z
+- **Last updated**: 2023-11-04T22:20:11Z
 - **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.25 KB
 
 ## Dependencies
 
@@ -72,11 +72,12 @@ Several projects in this repo's
 [/examples](https://github.com/thi-ng/umbrella/tree/develop/examples)
 directory are using this package:
 
-| Screenshot                                                                                                            | Description                                                                                             | Live demo                                           | Source                                                                            |
-|:----------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------|:----------------------------------------------------|:----------------------------------------------------------------------------------|
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/commit-heatmap.png" width="240"/> | Heatmap visualization of this mono-repo's commits                                                       |                                                     | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/commit-heatmap) |
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/mastodon-feed.jpg" width="240"/>  | Mastodon API feed reader with support for different media types, fullscreen media modal, HTML rewriting | [Demo](https://demo.thi.ng/umbrella/mastodon-feed/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/mastodon-feed)  |
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-todo-list.png" width="240"/>  | Zig-based To-Do list, DOM creation, local storage task persistence                                      | [Demo](https://demo.thi.ng/umbrella/zig-todo-list/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-todo-list)  |
+| Screenshot                                                                                                            | Description                                                                                             | Live demo                                            | Source                                                                            |
+|:----------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------|:-----------------------------------------------------|:----------------------------------------------------------------------------------|
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/commit-heatmap.png" width="240"/> | Heatmap visualization of this mono-repo's commits                                                       |                                                      | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/commit-heatmap) |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/mastodon-feed.jpg" width="240"/>  | Mastodon API feed reader with support for different media types, fullscreen media modal, HTML rewriting | [Demo](https://demo.thi.ng/umbrella/mastodon-feed/)  | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/mastodon-feed)  |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/pointfree-geom.jpg" width="240"/> | Live coding playground for 2D geometry generation using @thi.ng/pointfree-lang                          | [Demo](https://demo.thi.ng/umbrella/pointfree-geom/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/pointfree-geom) |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-todo-list.png" width="240"/>  | Zig-based To-Do list, DOM creation, local storage task persistence                                      | [Demo](https://demo.thi.ng/umbrella/zig-todo-list/)  | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-todo-list)  |
 
 ## API
 
@@ -175,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/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.25",
+  "version": "2.5.0",
   "description": "Datetime types, relative dates, math, iterators, composable formatters, locales",
   "type": "module",
   "module": "./index.js",
@@ -36,7 +36,7 @@
   "dependencies": {
     "@thi.ng/api": "^8.9.6",
     "@thi.ng/checks": "^3.4.6",
-    "@thi.ng/strings": "^3.6.3"
+    "@thi.ng/strings": "^3.6.4"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.38.0",
@@ -132,5 +132,5 @@
   "thi.ng": {
     "year": 2020
   },
-  "gitHead": "bfa16829786146bd24df3cdbd44649a45a603e44\n"
+  "gitHead": "336bd1bf95825b3c318a3ab49c54451c94aaa883\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