@forthtilliath/ts-kit 0.8.0 → 0.9.0

package/README.md

@@ -46,6 +46,10 @@ import { chunk } from "@forthtilliath/ts-kit/array/chunk";
 - `rankByNameMatch(items, query, getName)` — ranks `items` by relevance to
   `query`: earlier match position first, then shorter name — for a
   search-as-you-type list.
+- `sortUpcomingFirst(items, getDates, { now? })` — upcoming items first
+  (nearest first), then past ones (most recent first), undated last — for a
+  list of events. An item may carry several dates: it stays upcoming while
+  one is ahead (ranked by its next date), then is ranked by its latest date.
 - `swapItems(items, i, j)` — copy of `items` with the elements at `i` and `j`
   swapped (e.g. moving an item up/down) — a plain copy if either position is
   out of bounds.

package/dist/array/index.d.ts

@@ -3,5 +3,6 @@ export * from "./flattenDeep.js";
 export * from "./getMostRecentIds.js";
 export * from "./nextInCycle.js";
 export * from "./rankByNameMatch.js";
+export * from "./sortUpcomingFirst.js";
 export * from "./swapItems.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/array/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/array/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC"}

package/dist/array/index.js

@@ -3,4 +3,5 @@ export * from "./flattenDeep.js";
 export * from "./getMostRecentIds.js";
 export * from "./nextInCycle.js";
 export * from "./rankByNameMatch.js";
+export * from "./sortUpcomingFirst.js";
 export * from "./swapItems.js";

package/dist/array/sortUpcomingFirst.d.ts

@@ -0,0 +1,30 @@
+export type DateInput = Date | string | number;
+export interface SortUpcomingFirstOptions {
+    /** Instant separating upcoming from past items. Defaults to now. */
+    now?: DateInput;
+}
+/**
+ * Sorts items around a reference instant: upcoming items first, nearest
+ * first, then past items, most recent first — the usual order for a list of
+ * events (concerts, meetings, bookings…). Items without a valid date go last.
+ * Ties keep their original order.
+ *
+ * An item may carry several dates (e.g. an event with several sessions): it
+ * stays upcoming as long as one of its dates is still ahead and is ranked by
+ * its next date; once all are past, it is ranked by its latest date.
+ *
+ * @param items - The items to sort (left untouched).
+ * @param getDates - Reads the date(s) off an item (`Date`, ISO string or
+ *   timestamp); `null`/`undefined` or invalid dates are ignored.
+ * @param options - `now`: the reference instant (a date equal to it counts as
+ *   upcoming). Defaults to now.
+ * @returns A sorted copy of `items`.
+ * @example
+ * sortUpcomingFirst(
+ *   [{ d: "2026-01-01" }, { d: "2026-12-01" }, { d: "2026-03-01" }, { d: "2026-10-01" }],
+ *   (item) => item.d,
+ *   { now: "2026-06-01" },
+ * ); // => 2026-10-01, 2026-12-01, 2026-03-01, 2026-01-01
+ */
+export declare function sortUpcomingFirst<T>(items: readonly T[], getDates: (item: T) => DateInput | readonly DateInput[] | null | undefined, { now }?: SortUpcomingFirstOptions): T[];
+//# sourceMappingURL=sortUpcomingFirst.d.ts.map

package/dist/array/sortUpcomingFirst.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sortUpcomingFirst.d.ts","sourceRoot":"","sources":["../../src/array/sortUpcomingFirst.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAE/C,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,GAAG,CAAC,EAAE,SAAS,CAAC;CACjB;AAiBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,SAAS,GAAG,SAAS,SAAS,EAAE,GAAG,IAAI,GAAG,SAAS,EAC1E,EAAE,GAAgB,EAAE,GAAE,wBAA6B,GAClD,CAAC,EAAE,CAaL"}

package/dist/array/sortUpcomingFirst.js

@@ -0,0 +1,51 @@
+// Upcoming items first, then past items, then items without a usable date.
+const UPCOMING = 0;
+const PAST = 1;
+const UNDATED = 2;
+function toTimes(dates) {
+    if (dates == null)
+        return [];
+    const list = Array.isArray(dates)
+        ? dates
+        : [dates];
+    return list
+        .map((date) => new Date(date).getTime())
+        .filter((time) => !Number.isNaN(time));
+}
+/**
+ * Sorts items around a reference instant: upcoming items first, nearest
+ * first, then past items, most recent first — the usual order for a list of
+ * events (concerts, meetings, bookings…). Items without a valid date go last.
+ * Ties keep their original order.
+ *
+ * An item may carry several dates (e.g. an event with several sessions): it
+ * stays upcoming as long as one of its dates is still ahead and is ranked by
+ * its next date; once all are past, it is ranked by its latest date.
+ *
+ * @param items - The items to sort (left untouched).
+ * @param getDates - Reads the date(s) off an item (`Date`, ISO string or
+ *   timestamp); `null`/`undefined` or invalid dates are ignored.
+ * @param options - `now`: the reference instant (a date equal to it counts as
+ *   upcoming). Defaults to now.
+ * @returns A sorted copy of `items`.
+ * @example
+ * sortUpcomingFirst(
+ *   [{ d: "2026-01-01" }, { d: "2026-12-01" }, { d: "2026-03-01" }, { d: "2026-10-01" }],
+ *   (item) => item.d,
+ *   { now: "2026-06-01" },
+ * ); // => 2026-10-01, 2026-12-01, 2026-03-01, 2026-01-01
+ */
+export function sortUpcomingFirst(items, getDates, { now = Date.now() } = {}) {
+    const nowTime = new Date(now).getTime();
+    const keyed = items.map((item) => {
+        const times = toTimes(getDates(item));
+        const upcoming = times.filter((time) => time >= nowTime);
+        if (upcoming.length > 0)
+            return { item, group: UPCOMING, key: Math.min(...upcoming) };
+        if (times.length > 0)
+            return { item, group: PAST, key: -Math.max(...times) };
+        return { item, group: UNDATED, key: 0 };
+    });
+    keyed.sort((a, b) => a.group - b.group || a.key - b.key);
+    return keyed.map((k) => k.item);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forthtilliath/ts-kit",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {