@intech-software/chronera 0.1.6 → 0.1.7

package/dist/operations/recurrence.js

@@ -0,0 +1,279 @@
+import { addDays, addMonths, addYears, getAbsoluteDay, isAfter, } from "./convenience.js";
+// ---------------------------------------------------------------------------
+// Day-of-week mapping
+// ---------------------------------------------------------------------------
+// absoluteDay % 7 → correct mapping per actual absoluteDayFromGregorianFields:
+// Thursday=0, Friday=1, Saturday=2, Sunday=3, Monday=4, Tuesday=5, Wednesday=6
+const DOW_INDEX = {
+    thursday: 0,
+    friday: 1,
+    saturday: 2,
+    sunday: 3,
+    monday: 4,
+    tuesday: 5,
+    wednesday: 6,
+};
+// ---------------------------------------------------------------------------
+// Core computation
+// ---------------------------------------------------------------------------
+const MAX_OCCURRENCES = 500;
+const MAX_YEARS_AHEAD = 50;
+/**
+ * Computes all occurrences of a recurring schedule.
+ */
+export function getOccurrences(startDate, rule, limit) {
+    const maxCount = Math.min(limit ?? MAX_OCCURRENCES, MAX_OCCURRENCES);
+    const results = [];
+    // Compute absolute "50 years from start" safety boundary
+    const farFuture = addYears(startDate, MAX_YEARS_AHEAD, "constrain");
+    const withinBounds = (date) => {
+        if (rule.until && isAfter(date, rule.until))
+            return false;
+        if (isAfter(date, farFuture))
+            return false;
+        return true;
+    };
+    const withinCount = () => {
+        if (rule.count !== undefined && results.length >= rule.count)
+            return false;
+        return true;
+    };
+    switch (rule.frequency) {
+        case "daily": {
+            let current = startDate;
+            while (withinBounds(current) &&
+                withinCount() &&
+                results.length < maxCount) {
+                results.push(current);
+                current = addDays(current, rule.interval);
+            }
+            break;
+        }
+        case "weekly": {
+            if (rule.daysOfWeek && rule.daysOfWeek.length > 0) {
+                // For weekly with daysOfWeek: iterate week by week (interval * 7 days)
+                // Within each week boundary, include occurrences on matching days of week
+                const startAbs = getAbsoluteDay(startDate);
+                const dowTargets = new Set(rule.daysOfWeek.map((d) => DOW_INDEX[d]));
+                // DOW offset: we need to know startDate's day of week
+                // Find the start-of-week (Sunday) for startDate
+                // We'll iterate day by day within each week window
+                let weekAnchor = startDate;
+                let done = false;
+                while (!done) {
+                    // Check each day of the 7-day window starting at weekAnchor
+                    for (let i = 0; i < 7 && !done; i++) {
+                        const candidate = addDays(weekAnchor, i);
+                        const candidateAbs = getAbsoluteDay(candidate);
+                        // Must not be before startDate
+                        if (candidateAbs < startAbs)
+                            continue;
+                        const dow = ((candidateAbs % 7) + 7) % 7;
+                        if (dowTargets.has(dow)) {
+                            if (!withinBounds(candidate) ||
+                                !withinCount() ||
+                                results.length >= maxCount) {
+                                done = true;
+                                break;
+                            }
+                            results.push(candidate);
+                        }
+                    }
+                    if (!done) {
+                        weekAnchor = addDays(weekAnchor, rule.interval * 7);
+                        if (!withinBounds(weekAnchor) || results.length >= maxCount) {
+                            done = true;
+                        }
+                    }
+                }
+            }
+            else {
+                // Simple weekly: every interval * 7 days
+                let current = startDate;
+                while (withinBounds(current) &&
+                    withinCount() &&
+                    results.length < maxCount) {
+                    results.push(current);
+                    current = addDays(current, rule.interval * 7);
+                }
+            }
+            break;
+        }
+        case "monthly": {
+            let current = startDate;
+            while (withinBounds(current) &&
+                withinCount() &&
+                results.length < maxCount) {
+                results.push(current);
+                current = addMonths(current, rule.interval, "constrain");
+            }
+            break;
+        }
+        case "yearly": {
+            let current = startDate;
+            while (withinBounds(current) &&
+                withinCount() &&
+                results.length < maxCount) {
+                results.push(current);
+                current = addYears(current, rule.interval, "constrain");
+            }
+            break;
+        }
+    }
+    return results;
+}
+/**
+ * Returns true if the given date is an occurrence of the recurrence rule starting from startDate.
+ */
+export function isOccurrence(date, startDate, rule) {
+    const dateAbs = getAbsoluteDay(date);
+    const startAbs = getAbsoluteDay(startDate);
+    if (dateAbs < startAbs)
+        return false;
+    if (rule.until && isAfter(date, rule.until))
+        return false;
+    const diff = dateAbs - startAbs;
+    switch (rule.frequency) {
+        case "daily":
+            return diff % rule.interval === 0;
+        case "weekly": {
+            if (rule.daysOfWeek && rule.daysOfWeek.length > 0) {
+                // Check if the week offset is a multiple of interval
+                const weekDiff = Math.floor(diff / 7);
+                if (weekDiff % rule.interval !== 0)
+                    return false;
+                // Check if the day of week matches
+                const dow = ((dateAbs % 7) + 7) % 7;
+                return rule.daysOfWeek.some((d) => DOW_INDEX[d] === dow);
+            }
+            return diff % (rule.interval * 7) === 0;
+        }
+        case "monthly": {
+            // Compute how many months apart the two dates are
+            // and check that diff is an exact multiple of rule.interval months
+            // by stepping through
+            let cursor = startDate;
+            let monthCount = 0;
+            const targetAbs = dateAbs;
+            while (getAbsoluteDay(cursor) <= targetAbs) {
+                const cursorAbs = getAbsoluteDay(cursor);
+                if (cursorAbs === targetAbs && monthCount % rule.interval === 0) {
+                    return true;
+                }
+                if (cursorAbs > targetAbs)
+                    break;
+                cursor = addMonths(cursor, rule.interval, "constrain");
+                monthCount += rule.interval;
+                if (monthCount > 12 * MAX_YEARS_AHEAD)
+                    break;
+            }
+            return false;
+        }
+        case "yearly": {
+            let cursor = startDate;
+            let yearCount = 0;
+            const targetAbs = dateAbs;
+            while (getAbsoluteDay(cursor) <= targetAbs) {
+                if (getAbsoluteDay(cursor) === targetAbs)
+                    return true;
+                cursor = addYears(cursor, rule.interval, "constrain");
+                yearCount += rule.interval;
+                if (yearCount > MAX_YEARS_AHEAD)
+                    break;
+            }
+            return false;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Fluent Builder Implementation
+// ---------------------------------------------------------------------------
+class RecurrenceRuleBuilderImpl {
+    _startDate;
+    _frequency;
+    _interval;
+    _daysOfWeek;
+    _until;
+    _count;
+    constructor(startDate, frequency, interval) {
+        this._startDate = startDate;
+        this._frequency = frequency;
+        this._interval = interval;
+    }
+    on(days) {
+        this._daysOfWeek = days;
+        return this;
+    }
+    until(date) {
+        this._until = date;
+        return this;
+    }
+    count(n) {
+        this._count = n;
+        return this;
+    }
+    build() {
+        const rule = {
+            frequency: this._frequency,
+            interval: this._interval,
+        };
+        if (this._daysOfWeek)
+            rule.daysOfWeek = this._daysOfWeek;
+        if (this._until)
+            rule.until = this._until;
+        if (this._count !== undefined)
+            rule.count = this._count;
+        return rule;
+    }
+    next(n) {
+        return getOccurrences(this._startDate, this.build(), n);
+    }
+    occurrences() {
+        return getOccurrences(this._startDate, this.build());
+    }
+}
+class FrequencySelectorImpl {
+    _startDate;
+    _interval;
+    constructor(startDate, interval) {
+        this._startDate = startDate;
+        this._interval = interval;
+    }
+    days() {
+        return new RecurrenceRuleBuilderImpl(this._startDate, "daily", this._interval);
+    }
+    weeks() {
+        return new RecurrenceRuleBuilderImpl(this._startDate, "weekly", this._interval);
+    }
+    months() {
+        return new RecurrenceRuleBuilderImpl(this._startDate, "monthly", this._interval);
+    }
+    years() {
+        return new RecurrenceRuleBuilderImpl(this._startDate, "yearly", this._interval);
+    }
+}
+class RecurrenceBuilderImpl {
+    _startDate;
+    constructor(startDate) {
+        this._startDate = startDate;
+    }
+    every(n) {
+        return new FrequencySelectorImpl(this._startDate, n);
+    }
+}
+/**
+ * Creates a fluent recurrence builder anchored to the given start date.
+ *
+ * @example
+ * ```ts
+ * const dates = recur(localDate(2026, 1, 1))
+ *   .every(1).weeks()
+ *   .on(['monday', 'wednesday', 'friday'])
+ *   .until(localDate(2026, 3, 31))
+ *   .occurrences();
+ * ```
+ */
+export function recur(startDate) {
+    return new RecurrenceBuilderImpl(startDate);
+}
+//# sourceMappingURL=recurrence.js.map

package/dist/operations/recurrence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recurrence.js","sourceRoot":"","sources":["../../src/operations/recurrence.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  addDays,\n  addMonths,\n  addYears,\n  getAbsoluteDay,\n  isAfter,\n} from \"./convenience.js\";\n\nimport type { DateOrCalendarDate } from \"../public-types.js\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type RecurrenceFrequency = \"daily\" | \"weekly\" | \"monthly\" | \"yearly\";\n\nexport type DayOfWeek =\n  | \"monday\"\n  | \"tuesday\"\n  | \"wednesday\"\n  | \"thursday\"\n  | \"friday\"\n  | \"saturday\"\n  | \"sunday\";\n\nexport interface RecurrenceRule {\n  readonly frequency: RecurrenceFrequency;\n  readonly interval: number;\n  readonly daysOfWeek?: DayOfWeek[];\n  readonly until?: DateOrCalendarDate;\n  readonly count?: number;\n}\n\n// ---------------------------------------------------------------------------\n// Builder Interfaces\n// ---------------------------------------------------------------------------\n\nexport interface RecurrenceBuilder {\n  every(n: number): FrequencySelector;\n}\n\nexport interface FrequencySelector {\n  days(): RecurrenceRuleBuilder;\n  weeks(): RecurrenceRuleBuilder;\n  months(): RecurrenceRuleBuilder;\n  years(): RecurrenceRuleBuilder;\n}\n\nexport interface RecurrenceRuleBuilder {\n  on(days: DayOfWeek[]): RecurrenceRuleBuilder;\n  until(date: DateOrCalendarDate): RecurrenceRuleBuilder;\n  count(n: number): RecurrenceRuleBuilder;\n  next(n: number): DateOrCalendarDate[];\n  occurrences(): DateOrCalendarDate[];\n  build(): RecurrenceRule;\n}\n\n// ---------------------------------------------------------------------------\n// Day-of-week mapping\n// ---------------------------------------------------------------------------\n\n// absoluteDay % 7 → correct mapping per actual absoluteDayFromGregorianFields:\n// Thursday=0, Friday=1, Saturday=2, Sunday=3, Monday=4, Tuesday=5, Wednesday=6\nconst DOW_INDEX: Record<DayOfWeek, number> = {\n  thursday: 0,\n  friday: 1,\n  saturday: 2,\n  sunday: 3,\n  monday: 4,\n  tuesday: 5,\n  wednesday: 6,\n};\n\n// ---------------------------------------------------------------------------\n// Core computation\n// ---------------------------------------------------------------------------\n\nconst MAX_OCCURRENCES = 500;\nconst MAX_YEARS_AHEAD = 50;\n\n/**\n * Computes all occurrences of a recurring schedule.\n */\nexport function getOccurrences<T extends DateOrCalendarDate>(\n  startDate: T,\n  rule: RecurrenceRule,\n  limit?: number,\n): T[] {\n  const maxCount = Math.min(limit ?? MAX_OCCURRENCES, MAX_OCCURRENCES);\n  const results: T[] = [];\n\n  // Compute absolute \"50 years from start\" safety boundary\n  const farFuture = addYears(startDate, MAX_YEARS_AHEAD, \"constrain\");\n\n  const withinBounds = (date: T): boolean => {\n    if (rule.until && isAfter(date, rule.until as T)) return false;\n    if (isAfter(date, farFuture)) return false;\n    return true;\n  };\n\n  const withinCount = (): boolean => {\n    if (rule.count !== undefined && results.length >= rule.count) return false;\n    return true;\n  };\n\n  switch (rule.frequency) {\n    case \"daily\": {\n      let current = startDate;\n      while (\n        withinBounds(current) &&\n        withinCount() &&\n        results.length < maxCount\n      ) {\n        results.push(current);\n        current = addDays(current, rule.interval);\n      }\n      break;\n    }\n\n    case \"weekly\": {\n      if (rule.daysOfWeek && rule.daysOfWeek.length > 0) {\n        // For weekly with daysOfWeek: iterate week by week (interval * 7 days)\n        // Within each week boundary, include occurrences on matching days of week\n        const startAbs = getAbsoluteDay(startDate);\n        const dowTargets = new Set(rule.daysOfWeek.map((d) => DOW_INDEX[d]));\n\n        // DOW offset: we need to know startDate's day of week\n        // Find the start-of-week (Sunday) for startDate\n        // We'll iterate day by day within each week window\n\n        let weekAnchor = startDate;\n        let done = false;\n\n        while (!done) {\n          // Check each day of the 7-day window starting at weekAnchor\n          for (let i = 0; i < 7 && !done; i++) {\n            const candidate = addDays(weekAnchor, i);\n            const candidateAbs = getAbsoluteDay(candidate);\n\n            // Must not be before startDate\n            if (candidateAbs < startAbs) continue;\n\n            const dow = ((candidateAbs % 7) + 7) % 7;\n            if (dowTargets.has(dow)) {\n              if (\n                !withinBounds(candidate) ||\n                !withinCount() ||\n                results.length >= maxCount\n              ) {\n                done = true;\n                break;\n              }\n              results.push(candidate);\n            }\n          }\n\n          if (!done) {\n            weekAnchor = addDays(weekAnchor, rule.interval * 7);\n            if (!withinBounds(weekAnchor) || results.length >= maxCount) {\n              done = true;\n            }\n          }\n        }\n      } else {\n        // Simple weekly: every interval * 7 days\n        let current = startDate;\n        while (\n          withinBounds(current) &&\n          withinCount() &&\n          results.length < maxCount\n        ) {\n          results.push(current);\n          current = addDays(current, rule.interval * 7);\n        }\n      }\n      break;\n    }\n\n    case \"monthly\": {\n      let current = startDate;\n      while (\n        withinBounds(current) &&\n        withinCount() &&\n        results.length < maxCount\n      ) {\n        results.push(current);\n        current = addMonths(current, rule.interval, \"constrain\");\n      }\n      break;\n    }\n\n    case \"yearly\": {\n      let current = startDate;\n      while (\n        withinBounds(current) &&\n        withinCount() &&\n        results.length < maxCount\n      ) {\n        results.push(current);\n        current = addYears(current, rule.interval, \"constrain\");\n      }\n      break;\n    }\n  }\n\n  return results;\n}\n\n/**\n * Returns true if the given date is an occurrence of the recurrence rule starting from startDate.\n */\nexport function isOccurrence<T extends DateOrCalendarDate>(\n  date: T,\n  startDate: T,\n  rule: RecurrenceRule,\n): boolean {\n  const dateAbs = getAbsoluteDay(date);\n  const startAbs = getAbsoluteDay(startDate);\n\n  if (dateAbs < startAbs) return false;\n  if (rule.until && isAfter(date, rule.until as T)) return false;\n\n  const diff = dateAbs - startAbs;\n\n  switch (rule.frequency) {\n    case \"daily\":\n      return diff % rule.interval === 0;\n\n    case \"weekly\": {\n      if (rule.daysOfWeek && rule.daysOfWeek.length > 0) {\n        // Check if the week offset is a multiple of interval\n        const weekDiff = Math.floor(diff / 7);\n        if (weekDiff % rule.interval !== 0) return false;\n        // Check if the day of week matches\n        const dow = ((dateAbs % 7) + 7) % 7;\n        return rule.daysOfWeek.some((d) => DOW_INDEX[d] === dow);\n      }\n      return diff % (rule.interval * 7) === 0;\n    }\n\n    case \"monthly\": {\n      // Compute how many months apart the two dates are\n      // and check that diff is an exact multiple of rule.interval months\n      // by stepping through\n      let cursor = startDate;\n      let monthCount = 0;\n      const targetAbs = dateAbs;\n\n      while (getAbsoluteDay(cursor) <= targetAbs) {\n        const cursorAbs = getAbsoluteDay(cursor);\n        if (cursorAbs === targetAbs && monthCount % rule.interval === 0) {\n          return true;\n        }\n        if (cursorAbs > targetAbs) break;\n        cursor = addMonths(cursor, rule.interval, \"constrain\");\n        monthCount += rule.interval;\n\n        if (monthCount > 12 * MAX_YEARS_AHEAD) break;\n      }\n      return false;\n    }\n\n    case \"yearly\": {\n      let cursor = startDate;\n      let yearCount = 0;\n      const targetAbs = dateAbs;\n\n      while (getAbsoluteDay(cursor) <= targetAbs) {\n        if (getAbsoluteDay(cursor) === targetAbs) return true;\n        cursor = addYears(cursor, rule.interval, \"constrain\");\n        yearCount += rule.interval;\n        if (yearCount > MAX_YEARS_AHEAD) break;\n      }\n      return false;\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Fluent Builder Implementation\n// ---------------------------------------------------------------------------\n\nclass RecurrenceRuleBuilderImpl implements RecurrenceRuleBuilder {\n  private _startDate: DateOrCalendarDate;\n  private _frequency: RecurrenceFrequency;\n  private _interval: number;\n  private _daysOfWeek?: DayOfWeek[];\n  private _until?: DateOrCalendarDate;\n  private _count?: number;\n\n  constructor(\n    startDate: DateOrCalendarDate,\n    frequency: RecurrenceFrequency,\n    interval: number,\n  ) {\n    this._startDate = startDate;\n    this._frequency = frequency;\n    this._interval = interval;\n  }\n\n  on(days: DayOfWeek[]): RecurrenceRuleBuilder {\n    this._daysOfWeek = days;\n    return this;\n  }\n\n  until(date: DateOrCalendarDate): RecurrenceRuleBuilder {\n    this._until = date;\n    return this;\n  }\n\n  count(n: number): RecurrenceRuleBuilder {\n    this._count = n;\n    return this;\n  }\n\n  build(): RecurrenceRule {\n    const rule: {\n      frequency: RecurrenceFrequency;\n      interval: number;\n      daysOfWeek?: DayOfWeek[];\n      until?: DateOrCalendarDate;\n      count?: number;\n    } = {\n      frequency: this._frequency,\n      interval: this._interval,\n    };\n    if (this._daysOfWeek) rule.daysOfWeek = this._daysOfWeek;\n    if (this._until) rule.until = this._until;\n    if (this._count !== undefined) rule.count = this._count;\n    return rule;\n  }\n\n  next(n: number): DateOrCalendarDate[] {\n    return getOccurrences(this._startDate, this.build(), n);\n  }\n\n  occurrences(): DateOrCalendarDate[] {\n    return getOccurrences(this._startDate, this.build());\n  }\n}\n\nclass FrequencySelectorImpl implements FrequencySelector {\n  private _startDate: DateOrCalendarDate;\n  private _interval: number;\n\n  constructor(startDate: DateOrCalendarDate, interval: number) {\n    this._startDate = startDate;\n    this._interval = interval;\n  }\n\n  days(): RecurrenceRuleBuilder {\n    return new RecurrenceRuleBuilderImpl(\n      this._startDate,\n      \"daily\",\n      this._interval,\n    );\n  }\n\n  weeks(): RecurrenceRuleBuilder {\n    return new RecurrenceRuleBuilderImpl(\n      this._startDate,\n      \"weekly\",\n      this._interval,\n    );\n  }\n\n  months(): RecurrenceRuleBuilder {\n    return new RecurrenceRuleBuilderImpl(\n      this._startDate,\n      \"monthly\",\n      this._interval,\n    );\n  }\n\n  years(): RecurrenceRuleBuilder {\n    return new RecurrenceRuleBuilderImpl(\n      this._startDate,\n      \"yearly\",\n      this._interval,\n    );\n  }\n}\n\nclass RecurrenceBuilderImpl implements RecurrenceBuilder {\n  private _startDate: DateOrCalendarDate;\n\n  constructor(startDate: DateOrCalendarDate) {\n    this._startDate = startDate;\n  }\n\n  every(n: number): FrequencySelector {\n    return new FrequencySelectorImpl(this._startDate, n);\n  }\n}\n\n/**\n * Creates a fluent recurrence builder anchored to the given start date.\n *\n * @example\n * ```ts\n * const dates = recur(localDate(2026, 1, 1))\n *   .every(1).weeks()\n *   .on(['monday', 'wednesday', 'friday'])\n *   .until(localDate(2026, 3, 31))\n *   .occurrences();\n * ```\n */\nexport function recur<T extends DateOrCalendarDate>(\n  startDate: T,\n): RecurrenceBuilder {\n  return new RecurrenceBuilderImpl(startDate);\n}\n"]}

package/dist/operations/time-series.d.ts

@@ -0,0 +1,58 @@
+import type { DateOrCalendarDate } from "../public-types.js";
+export type BucketUnit = "day" | "week" | "month" | "quarter" | "year";
+export interface BucketKey {
+    readonly key: string;
+    readonly label: string;
+    readonly unit: BucketUnit;
+}
+export type BucketMap<T extends DateOrCalendarDate> = Map<string, T[]>;
+/**
+ * Groups an array of dates into buckets by the given unit.
+ * Returns a Map of key → dates[].
+ * Keys are sorted chronologically.
+ *
+ * @example
+ * const dates = [localDate(2026,9,1), localDate(2026,9,15), localDate(2026,10,1)];
+ * bucketDates(dates, 'month')
+ * // Map { '2026-09' => [...], '2026-10' => [...] }
+ */
+export declare function bucketDates<T extends DateOrCalendarDate>(dates: T[], unit: BucketUnit): BucketMap<T>;
+export declare function bucketByDay<T extends DateOrCalendarDate>(dates: T[]): BucketMap<T>;
+export declare function bucketByWeek<T extends DateOrCalendarDate>(dates: T[]): BucketMap<T>;
+export declare function bucketByMonth<T extends DateOrCalendarDate>(dates: T[]): BucketMap<T>;
+export declare function bucketByQuarter<T extends DateOrCalendarDate>(dates: T[]): BucketMap<T>;
+export declare function bucketByYear<T extends DateOrCalendarDate>(dates: T[]): BucketMap<T>;
+export interface HistogramEntry {
+    readonly key: string;
+    readonly label: string;
+    readonly count: number;
+}
+/**
+ * Returns a frequency histogram of dates grouped by the given unit.
+ * Result is sorted chronologically.
+ *
+ * @example
+ * histogram(dates, 'month')
+ * // [{ key: '2026-09', label: '2026-09', count: 12 }, ...]
+ */
+export declare function histogram(dates: DateOrCalendarDate[], unit: BucketUnit): HistogramEntry[];
+/**
+ * Sorts an array of dates chronologically (ascending).
+ */
+export declare function sortDates<T extends DateOrCalendarDate>(dates: T[], direction?: "asc" | "desc"): T[];
+/**
+ * Finds the minimum (earliest) date in an array.
+ */
+export declare function minDate<T extends DateOrCalendarDate>(dates: T[]): T;
+/**
+ * Finds the maximum (latest) date in an array.
+ */
+export declare function maxDate<T extends DateOrCalendarDate>(dates: T[]): T;
+/**
+ * Finds the date nearest to the reference date.
+ */
+export declare function nearestDate<T extends DateOrCalendarDate>(dates: T[], ref: T): T;
+/**
+ * Removes duplicate dates from an array (keeps first occurrence).
+ */
+export declare function uniqueDates<T extends DateOrCalendarDate>(dates: T[]): T[];

package/dist/operations/time-series.js

@@ -0,0 +1,153 @@
+import { absoluteDayFromGregorianFields, gregorianFieldsFromAbsoluteDay, } from "../core/absolute-day.js";
+import { getAbsoluteDay } from "./convenience.js";
+function toLocalDate(date) {
+    if (date.kind === "local-date")
+        return date;
+    const abs = getAbsoluteDay(date);
+    const f = gregorianFieldsFromAbsoluteDay(abs);
+    return { kind: "local-date", year: f.year, month: f.month, day: f.day };
+}
+function pad(n, w = 2) {
+    return String(n).padStart(w, "0");
+}
+function bucketKeyFor(date, unit) {
+    switch (unit) {
+        case "day":
+            return `${date.year}-${pad(date.month)}-${pad(date.day)}`;
+        case "week": {
+            // ISO week: find Monday of that week
+            const abs = absoluteDayFromGregorianFields(date.year, date.month, date.day);
+            const dow = abs % 7; // 0=Mon
+            const monday = gregorianFieldsFromAbsoluteDay(abs - dow);
+            return `${monday.year}-W${pad(monday.month)}-${pad(monday.day)}`;
+        }
+        case "month":
+            return `${date.year}-${pad(date.month)}`;
+        case "quarter": {
+            const q = Math.ceil(date.month / 3);
+            return `${date.year}-Q${q}`;
+        }
+        case "year":
+            return `${date.year}`;
+    }
+}
+function bucketLabelFor(key, unit) {
+    switch (unit) {
+        case "day":
+            return key; // YYYY-MM-DD
+        case "week":
+            return key; // YYYY-WMM-DD (start of week)
+        case "month":
+            return key; // YYYY-MM
+        case "quarter":
+            return key; // YYYY-Q1
+        case "year":
+            return key; // YYYY
+    }
+}
+/**
+ * Groups an array of dates into buckets by the given unit.
+ * Returns a Map of key → dates[].
+ * Keys are sorted chronologically.
+ *
+ * @example
+ * const dates = [localDate(2026,9,1), localDate(2026,9,15), localDate(2026,10,1)];
+ * bucketDates(dates, 'month')
+ * // Map { '2026-09' => [...], '2026-10' => [...] }
+ */
+export function bucketDates(dates, unit) {
+    const map = new Map();
+    for (const date of dates) {
+        const local = toLocalDate(date);
+        const key = bucketKeyFor(local, unit);
+        if (!map.has(key))
+            map.set(key, []);
+        map.get(key).push(date);
+    }
+    // Sort keys chronologically
+    const sorted = new Map([...map.entries()].sort(([a], [b]) => a.localeCompare(b)));
+    return sorted;
+}
+export function bucketByDay(dates) {
+    return bucketDates(dates, "day");
+}
+export function bucketByWeek(dates) {
+    return bucketDates(dates, "week");
+}
+export function bucketByMonth(dates) {
+    return bucketDates(dates, "month");
+}
+export function bucketByQuarter(dates) {
+    return bucketDates(dates, "quarter");
+}
+export function bucketByYear(dates) {
+    return bucketDates(dates, "year");
+}
+/**
+ * Returns a frequency histogram of dates grouped by the given unit.
+ * Result is sorted chronologically.
+ *
+ * @example
+ * histogram(dates, 'month')
+ * // [{ key: '2026-09', label: '2026-09', count: 12 }, ...]
+ */
+export function histogram(dates, unit) {
+    const bucketed = bucketDates(dates, unit);
+    return [...bucketed.entries()].map(([key, items]) => ({
+        key,
+        label: bucketLabelFor(key, unit),
+        count: items.length,
+    }));
+}
+// ---------------------------------------------------------------------------
+// Sorting & Finding
+// ---------------------------------------------------------------------------
+/**
+ * Sorts an array of dates chronologically (ascending).
+ */
+export function sortDates(dates, direction = "asc") {
+    const sorted = [...dates].sort((a, b) => getAbsoluteDay(a) - getAbsoluteDay(b));
+    return direction === "desc" ? sorted.reverse() : sorted;
+}
+/**
+ * Finds the minimum (earliest) date in an array.
+ */
+export function minDate(dates) {
+    if (dates.length === 0)
+        throw new RangeError("Cannot find min of empty array.");
+    return dates.reduce((m, d) => getAbsoluteDay(d) < getAbsoluteDay(m) ? d : m);
+}
+/**
+ * Finds the maximum (latest) date in an array.
+ */
+export function maxDate(dates) {
+    if (dates.length === 0)
+        throw new RangeError("Cannot find max of empty array.");
+    return dates.reduce((m, d) => getAbsoluteDay(d) > getAbsoluteDay(m) ? d : m);
+}
+/**
+ * Finds the date nearest to the reference date.
+ */
+export function nearestDate(dates, ref) {
+    if (dates.length === 0)
+        throw new RangeError("Cannot find nearest in empty array.");
+    const refAbs = getAbsoluteDay(ref);
+    return dates.reduce((nearest, d) => Math.abs(getAbsoluteDay(d) - refAbs) <
+        Math.abs(getAbsoluteDay(nearest) - refAbs)
+        ? d
+        : nearest);
+}
+/**
+ * Removes duplicate dates from an array (keeps first occurrence).
+ */
+export function uniqueDates(dates) {
+    const seen = new Set();
+    return dates.filter((d) => {
+        const abs = getAbsoluteDay(d);
+        if (seen.has(abs))
+            return false;
+        seen.add(abs);
+        return true;
+    });
+}
+//# sourceMappingURL=time-series.js.map

package/dist/operations/time-series.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-series.js","sourceRoot":"","sources":["../../src/operations/time-series.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  absoluteDayFromGregorianFields,\n  gregorianFieldsFromAbsoluteDay,\n} from \"../core/absolute-day.js\";\nimport { getAbsoluteDay } from \"./convenience.js\";\nimport type { DateOrCalendarDate, LocalDate } from \"../public-types.js\";\n\n// ---------------------------------------------------------------------------\n// Time Series & Bucketing Engine\n// ---------------------------------------------------------------------------\n\nexport type BucketUnit = \"day\" | \"week\" | \"month\" | \"quarter\" | \"year\";\n\nexport interface BucketKey {\n  readonly key: string;\n  readonly label: string;\n  readonly unit: BucketUnit;\n}\n\nexport type BucketMap<T extends DateOrCalendarDate> = Map<string, T[]>;\n\nfunction toLocalDate(date: DateOrCalendarDate): LocalDate {\n  if (date.kind === \"local-date\") return date;\n  const abs = getAbsoluteDay(date);\n  const f = gregorianFieldsFromAbsoluteDay(abs);\n  return { kind: \"local-date\", year: f.year, month: f.month, day: f.day };\n}\n\nfunction pad(n: number, w = 2): string {\n  return String(n).padStart(w, \"0\");\n}\n\nfunction bucketKeyFor(date: LocalDate, unit: BucketUnit): string {\n  switch (unit) {\n    case \"day\":\n      return `${date.year}-${pad(date.month)}-${pad(date.day)}`;\n    case \"week\": {\n      // ISO week: find Monday of that week\n      const abs = absoluteDayFromGregorianFields(\n        date.year,\n        date.month,\n        date.day,\n      );\n      const dow = abs % 7; // 0=Mon\n      const monday = gregorianFieldsFromAbsoluteDay(abs - dow);\n      return `${monday.year}-W${pad(monday.month)}-${pad(monday.day)}`;\n    }\n    case \"month\":\n      return `${date.year}-${pad(date.month)}`;\n    case \"quarter\": {\n      const q = Math.ceil(date.month / 3);\n      return `${date.year}-Q${q}`;\n    }\n    case \"year\":\n      return `${date.year}`;\n  }\n}\n\nfunction bucketLabelFor(key: string, unit: BucketUnit): string {\n  switch (unit) {\n    case \"day\":\n      return key; // YYYY-MM-DD\n    case \"week\":\n      return key; // YYYY-WMM-DD (start of week)\n    case \"month\":\n      return key; // YYYY-MM\n    case \"quarter\":\n      return key; // YYYY-Q1\n    case \"year\":\n      return key; // YYYY\n  }\n}\n\n/**\n * Groups an array of dates into buckets by the given unit.\n * Returns a Map of key → dates[].\n * Keys are sorted chronologically.\n *\n * @example\n * const dates = [localDate(2026,9,1), localDate(2026,9,15), localDate(2026,10,1)];\n * bucketDates(dates, 'month')\n * // Map { '2026-09' => [...], '2026-10' => [...] }\n */\nexport function bucketDates<T extends DateOrCalendarDate>(\n  dates: T[],\n  unit: BucketUnit,\n): BucketMap<T> {\n  const map = new Map<string, T[]>();\n  for (const date of dates) {\n    const local = toLocalDate(date);\n    const key = bucketKeyFor(local, unit);\n    if (!map.has(key)) map.set(key, []);\n    map.get(key)!.push(date);\n  }\n  // Sort keys chronologically\n  const sorted = new Map<string, T[]>(\n    [...map.entries()].sort(([a], [b]) => a.localeCompare(b)),\n  );\n  return sorted;\n}\n\nexport function bucketByDay<T extends DateOrCalendarDate>(\n  dates: T[],\n): BucketMap<T> {\n  return bucketDates(dates, \"day\");\n}\n\nexport function bucketByWeek<T extends DateOrCalendarDate>(\n  dates: T[],\n): BucketMap<T> {\n  return bucketDates(dates, \"week\");\n}\n\nexport function bucketByMonth<T extends DateOrCalendarDate>(\n  dates: T[],\n): BucketMap<T> {\n  return bucketDates(dates, \"month\");\n}\n\nexport function bucketByQuarter<T extends DateOrCalendarDate>(\n  dates: T[],\n): BucketMap<T> {\n  return bucketDates(dates, \"quarter\");\n}\n\nexport function bucketByYear<T extends DateOrCalendarDate>(\n  dates: T[],\n): BucketMap<T> {\n  return bucketDates(dates, \"year\");\n}\n\n// ---------------------------------------------------------------------------\n// Histogram\n// ---------------------------------------------------------------------------\n\nexport interface HistogramEntry {\n  readonly key: string;\n  readonly label: string;\n  readonly count: number;\n}\n\n/**\n * Returns a frequency histogram of dates grouped by the given unit.\n * Result is sorted chronologically.\n *\n * @example\n * histogram(dates, 'month')\n * // [{ key: '2026-09', label: '2026-09', count: 12 }, ...]\n */\nexport function histogram(\n  dates: DateOrCalendarDate[],\n  unit: BucketUnit,\n): HistogramEntry[] {\n  const bucketed = bucketDates(dates, unit);\n  return [...bucketed.entries()].map(([key, items]) => ({\n    key,\n    label: bucketLabelFor(key, unit),\n    count: items.length,\n  }));\n}\n\n// ---------------------------------------------------------------------------\n// Sorting & Finding\n// ---------------------------------------------------------------------------\n\n/**\n * Sorts an array of dates chronologically (ascending).\n */\nexport function sortDates<T extends DateOrCalendarDate>(\n  dates: T[],\n  direction: \"asc\" | \"desc\" = \"asc\",\n): T[] {\n  const sorted = [...dates].sort(\n    (a, b) => getAbsoluteDay(a) - getAbsoluteDay(b),\n  );\n  return direction === \"desc\" ? sorted.reverse() : sorted;\n}\n\n/**\n * Finds the minimum (earliest) date in an array.\n */\nexport function minDate<T extends DateOrCalendarDate>(dates: T[]): T {\n  if (dates.length === 0)\n    throw new RangeError(\"Cannot find min of empty array.\");\n  return dates.reduce((m, d) =>\n    getAbsoluteDay(d) < getAbsoluteDay(m) ? d : m,\n  );\n}\n\n/**\n * Finds the maximum (latest) date in an array.\n */\nexport function maxDate<T extends DateOrCalendarDate>(dates: T[]): T {\n  if (dates.length === 0)\n    throw new RangeError(\"Cannot find max of empty array.\");\n  return dates.reduce((m, d) =>\n    getAbsoluteDay(d) > getAbsoluteDay(m) ? d : m,\n  );\n}\n\n/**\n * Finds the date nearest to the reference date.\n */\nexport function nearestDate<T extends DateOrCalendarDate>(\n  dates: T[],\n  ref: T,\n): T {\n  if (dates.length === 0)\n    throw new RangeError(\"Cannot find nearest in empty array.\");\n  const refAbs = getAbsoluteDay(ref);\n  return dates.reduce((nearest, d) =>\n    Math.abs(getAbsoluteDay(d) - refAbs) <\n    Math.abs(getAbsoluteDay(nearest) - refAbs)\n      ? d\n      : nearest,\n  );\n}\n\n/**\n * Removes duplicate dates from an array (keeps first occurrence).\n */\nexport function uniqueDates<T extends DateOrCalendarDate>(dates: T[]): T[] {\n  const seen = new Set<number>();\n  return dates.filter((d) => {\n    const abs = getAbsoluteDay(d);\n    if (seen.has(abs)) return false;\n    seen.add(abs);\n    return true;\n  });\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intech-software/chronera",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "A universal, type-safe date, time, calendar, era, locale, and timezone toolkit for JavaScript and TypeScript.",
   "keywords": [
     "date",
@@ -86,7 +86,7 @@
     {
       "name": "Root (@intech-software/chronera)",
       "path": "dist/index.js",
-      "limit": "25 KB"
+      "limit": "30 KB"
     },
     {
       "name": "Calendar (@intech-software/chronera/calendar)",