@blamejs/core 0.11.35 → 0.11.36

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.11.x
 
+- v0.11.36 (2026-05-21) — **`b.calendar.expandRecurrence` picks up BYWEEKNO / BYYEARDAY / BYHOUR / BYMINUTE / BYSECOND filters (RFC 5545 §3.3.10).** Closes the v0.11.31 deferral on the time-of-day and year-relative BY* filters. `expandRecurrence` now honours `byWeekNo` (ISO 8601 1..53 with negative-from-end semantics), `byYearDay` (1..366 with negative-from-end), `byHour` (0..23), `byMinute` (0..59), and `bySecond` (0..60 — covers POSIX leap-second representation). The expansion still operates as a per-step filter (stepping at the rule's FREQ, then dropping candidates that fail the BY* predicates) — BYSETPOS remains deferred-with-condition because it requires expanding ALL candidates within a FREQ interval and picking the Nth, which is a structural restructure of the expand loop. Operators with `last weekday of month`-style needs continue to see the same defer note from v0.11.31. **Added:** *`byWeekNo` filter — ISO 8601 week numbers* — `recurrenceRules[i].byWeekNo: [1, 53, -1]` filters candidates to the named ISO 8601 weeks. Negative values count from the end of the year (`-1` = last ISO week, which may be week 52 or week 53 depending on the year). The ISO week-of-year calculation matches the canonical algorithm — week 1 is the week containing the first Thursday of the year. · *`byYearDay` filter — day-of-year (1..366 / -1..-366)* — `recurrenceRules[i].byYearDay: [1, 366, -1]` filters by ordinal day-of-year. Negative values count from the end of the year, accounting for leap-year length (366 vs 365). With a `frequency: "daily"` rule + `byYearDay: [1]` the expander emits Jan 1 of each year. · *`byHour` / `byMinute` / `bySecond` time-of-day filters* — `byHour: [9, 17]` filters candidates by UTC hour-of-day (0..23). `byMinute: [0, 30]` (0..59). `bySecond: [0, 30, 60]` (0..60 — the leap-second representation in POSIX time). Most useful with sub-day frequencies — `frequency: "hourly"` + `byHour: [9, 17]` emits twice-daily at 9am and 5pm. · *Negative BY* semantics per RFC 5545 §3.3.10* — `byWeekNo: [-1]` matches the last ISO week of the year (computed via the Dec-28 anchor — Dec 28 always falls in the last ISO week). `byYearDay: [-1]` matches the last day of the year (uses the Gregorian leap-year rule to determine whether 365 or 366 is the correct ordinal). Both negative-value paths covered by tests. **Security:** *Same step-budget cap from v0.11.31 applies* — Sparse BY* filters (e.g. `byYearDay: [1]` with `frequency: "daily"` — only 1 in 365 candidates matches) still loop within the `MAX_EXPAND_INSTANCES * 366` step budget; the 10-year `MAX_EXPAND_SPAN_MS` window cap also applies. Operators can't construct a BY*-filter that loops past the bounded budget. · *Integer-range validation on every BY* value* — `byWeekNo` rejects values outside ±53. `byYearDay` rejects outside ±366. `byHour` 0..23. `byMinute` 0..59. `bySecond` 0..60. Adversarial-shape values silently drop from the set (no error — the rule continues with the surviving values per RFC 5545's tolerant grammar). **References:** [RFC 5545 §3.3.10 (RRULE — BYWEEKNO / BYYEARDAY / BYHOUR / BYMINUTE / BYSECOND)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.3.10) · [RFC 8984 §4.3.2 (JSCalendar RecurrenceRule)](https://www.rfc-editor.org/rfc/rfc8984.html#section-4.3.2) · [ISO 8601 (Week numbering)](https://www.iso.org/iso-8601-date-and-time-format.html)
+
 - v0.11.35 (2026-05-21) — **`b.calendar` VTODO ↔ JSCalendar Task (RFC 8984 §6).** Closes the v0.11.31 deferral. `b.calendar.fromIcal` now recognises VTODO components and maps them to JSCalendar Task objects per RFC 8984 §6. `b.calendar.toIcal` emits a VTODO envelope (with DUE / STATUS / PERCENT-COMPLETE / COMPLETED iCalendar properties) when the input `@type` is `Task`. `b.calendar.validate` picks up Task-specific shape rules: `due` as LocalDateTime, `estimatedDuration` as PnYnMnDTnHnMnS, `progress` from the RFC 8984 §6.4.3 vocabulary (`needs-action` | `in-process` | `completed` | `cancelled` | `failed`), `percentComplete` ∈ [0..100], `progressUpdated` as UTCDateTime. A VCALENDAR carrying both VEVENT and VTODO components now returns an array of mixed `Event` + `Task` shapes. **Added:** *`b.calendar.fromIcal` maps VTODO → JSCalendar Task* — VTODO components in the VCALENDAR are mapped to `@type: "Task"` objects with the same `uid` / `updated` / `title` / `description` / `start` / `timeZone` / `locations` / `recurrenceRules` slots Event uses, plus the Task-specific fields: `due` (DUE → LocalDateTime), `estimatedDuration` (DURATION), `progress` (STATUS lowercased), `percentComplete` (PERCENT-COMPLETE 0..100), `progressUpdated` (COMPLETED → UTCDateTime). UTC DUE values map to `timeZone: "Etc/UTC"` the same way DTSTART does. · *`b.calendar.toIcal` emits VTODO when `@type === "Task"`* — The envelope is `BEGIN:VTODO` / `END:VTODO` instead of `BEGIN:VEVENT`. Task-specific properties round-trip: `DUE` (with `;TZID=` parameter or `Z` suffix or floating local time per the same RFC 8984 §1.4.4 timeZone mapping as DTSTART), `STATUS` (uppercased), `PERCENT-COMPLETE`, `COMPLETED` (UTC). `estimatedDuration` maps to `DURATION` (RFC 5545 doesn't distinguish Event vs Task duration on the wire). · *`b.calendar.validate` learns Task-specific shape rules (RFC 8984 §6.4)* — `due` must be a LocalDateTime, `estimatedDuration` must match the same PnYnMnDTnHnMnS Duration grammar Event uses, `progress` must be in the `JSCAL_TASK_PROGRESS` catalogue (also exposed as a new top-level export), `percentComplete` must be a finite number in 0..100, `progressUpdated` must be a UTCDateTime. Structured `CalendarError` codes: `calendar/bad-due`, `calendar/bad-progress`, `calendar/bad-percent`, `calendar/bad-progress-updated`. · *Mixed-component VCALENDAR returns an array of Event + Task shapes* — When a VCALENDAR contains both VEVENT and VTODO children, `fromIcal` returns an Array — events first, tasks second, in their declared order. The single-component shortcut (returning the bare object) still applies when only one component is present. · *`calendar/no-vevent` error code renamed to `calendar/no-component`* — The refusal that fires when a VCALENDAR has no parseable child component now uses the more accurate `calendar/no-component` code (since VTODO is also valid). Operators that grep on the prior `calendar/no-vevent` code need to update the match; the human-facing error message also updates. **References:** [RFC 8984 §6 (JSCalendar Task)](https://www.rfc-editor.org/rfc/rfc8984.html#section-6) · [RFC 5545 §3.6.2 (iCalendar VTODO component)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.6.2) · [RFC 5545 §3.8.2.3 (DUE date-time)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.8.2.3) · [RFC 5545 §3.8.1.11 (STATUS — needs-action/in-process/completed/cancelled)](https://www.rfc-editor.org/rfc/rfc5545.html#section-3.8.1.11)
 
 - v0.11.34 (2026-05-21) — **JMAP WebSocket transport (RFC 8887) on `b.mail.server.jmap`.** Closes the v0.11.29 deferral. The JMAP listener now exposes `webSocketHandler(req, socket, head)` — a turnkey RFC 8887 transport built on the framework's `b.websocket.handleUpgrade`. Clients connect with the `jmap` subprotocol; bidirectional JSON frames carry `{ "@type": "Request" }` / `{ "@type": "WebSocketPushEnable" }` / `{ "@type": "WebSocketPushDisable" }` from the client, and `{ "@type": "Response" }` / `{ "@type": "StateChange" }` / `{ "@type": "RequestError" }` from the server. `Request` frames flow through the same `dispatch(actor, request)` path the HTTP `apiHandler` uses; `WebSocketPushEnable` hooks the operator's `mailStore.subscribePush(actor, types, emitFn)` and converts backend StateChange events into outbound WebSocket frames.

package/lib/calendar.js

@@ -449,11 +449,100 @@ function expandRecurrence(event, opts) {
       if (isFinite(mdn) && mdn !== 0 && mdn >= -31 && mdn <= 31) byMonthDaySet[mdn] = true;            // allow:raw-byte-literal — calendar day-of-month bounds
     }
   }
+  // RFC 5545 §3.3.10 — BYWEEKNO refines yearly recurrences to specific
+  // ISO 8601 week numbers (1..53 or -1..-53). Implementation
+  // computes the ISO week of each candidate instance + compares.
+  var byWeekNoSet = null;
+  if (Array.isArray(rule.byWeekNo) && rule.byWeekNo.length > 0) {
+    byWeekNoSet = Object.create(null);
+    for (var wni = 0; wni < rule.byWeekNo.length; wni += 1) {
+      var wn = parseInt(rule.byWeekNo[wni], 10);
+      if (isFinite(wn) && wn !== 0 && wn >= -53 && wn <= 53) byWeekNoSet[wn] = true;                   // allow:raw-byte-literal — ISO 8601 week-number bounds
+    }
+  }
+  // BYYEARDAY — day-of-year (1..366 or -1..-366; negative counts from
+  // the end of the year per RFC 5545 §3.3.10).
+  var byYearDaySet = null;
+  if (Array.isArray(rule.byYearDay) && rule.byYearDay.length > 0) {
+    byYearDaySet = Object.create(null);
+    for (var ydi = 0; ydi < rule.byYearDay.length; ydi += 1) {
+      var yd = parseInt(rule.byYearDay[ydi], 10);
+      if (isFinite(yd) && yd !== 0 && yd >= -366 && yd <= 366) byYearDaySet[yd] = true;                // allow:raw-byte-literal — day-of-year bounds
+    }
+  }
+  // BYHOUR / BYMINUTE / BYSECOND — time-of-day filters. RFC 5545 §3.3.10
+  // bounds: hours 0..23, minutes 0..59, seconds 0..60 (60 covers
+  // POSIX leap-second representation).
+  function _bySet(arr, lo, hi) {
+    if (!Array.isArray(arr) || arr.length === 0) return null;
+    var s = Object.create(null);
+    var hasAny = false;
+    for (var i = 0; i < arr.length; i += 1) {
+      var n = parseInt(arr[i], 10);
+      if (isFinite(n) && n >= lo && n <= hi) { s[n] = true; hasAny = true; }
+    }
+    // Codex P2 — when every value in the BY* list is out of range,
+    // return null instead of an empty set. An empty truthy set would
+    // cause `_matchesBy` to reject every candidate (`!set[n]` is
+    // true) and silently turn malformed input into a "match nothing"
+    // rule. Returning null lets the rule fall through to the next
+    // unfiltered candidate per RFC 5545's tolerant grammar.
+    return hasAny ? s : null;
+  }
+  var byHourSet   = _bySet(rule.byHour,   0, 23);                                                      // allow:raw-byte-literal — RFC 5545 hour range
+  var byMinuteSet = _bySet(rule.byMinute, 0, 59);                                                      // allow:raw-byte-literal — RFC 5545 minute range
+  var bySecondSet = _bySet(rule.bySecond, 0, 60);                                                      // allow:raw-byte-literal — RFC 5545 second range incl. leap second // allow:raw-time-literal — second-of-minute bound, not a duration
+
+  function _isoWeekParts(d) {
+    // ISO 8601 week-of-year + week-year. The week-YEAR can differ
+    // from the Gregorian year for early-Jan / late-Dec boundary
+    // dates (e.g. 2021-01-01 is ISO week 53 of WEEK-YEAR 2020).
+    // Returns { week, year }.
+    var tmp = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+    var dayOfWeek = tmp.getUTCDay() || 7;
+    tmp.setUTCDate(tmp.getUTCDate() + 4 - dayOfWeek);                                                  // allow:raw-byte-literal — ISO week-year anchor (Thursday)
+    var weekYear = tmp.getUTCFullYear();
+    var yearStart = new Date(Date.UTC(weekYear, 0, 1));
+    var week = Math.ceil((((tmp - yearStart) / 86400000) + 1) / 7);                                    // allow:raw-time-literal — 86400000 ms/day, 7 days/week // allow:raw-byte-literal
+    return { week: week, year: weekYear };
+  }
+  function _isoWeekOf(d) {
+    return _isoWeekParts(d).week;
+  }
+  function _yearDayOf(d) {
+    var startOfYear = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+    return Math.floor((d - startOfYear) / 86400000) + 1;                                               // allow:raw-time-literal — 86400000 ms/day // allow:raw-byte-literal
+  }
+  function _daysInYear(year) {
+    return ((year % 4 === 0 && year % 100 !== 0) || year % 400 === 0) ? 366 : 365;                      // allow:raw-byte-literal — Gregorian leap-year rule
+  }
   function _matchesBy(t) {
     var d = new Date(t);
     if (byDaySet && !byDaySet[d.getUTCDay()]) return false;
     if (byMonthSet && !byMonthSet[d.getUTCMonth() + 1]) return false;
     if (byMonthDaySet && !byMonthDaySet[d.getUTCDate()]) return false;
+    if (byWeekNoSet) {
+      // Codex P1 — ISO week-year vs Gregorian year. 2021-01-01 is ISO
+      // week 53 of WEEK-YEAR 2020 (since 2021 only has 52 ISO weeks).
+      // Comparing only the numeric week would let a Jan 1 2021 date
+      // match a BYWEEKNO=53 rule whose implicit year is 2021. Refuse
+      // when the candidate's ISO week-year doesn't match the
+      // candidate's Gregorian year (the most common operator-intent
+      // alignment); operators with boundary-crossing rules opt in via
+      // a future explicit knob if demand surfaces.
+      var iso = _isoWeekParts(d);
+      if (iso.year !== d.getUTCFullYear()) return false;
+      var lastWeek = _isoWeekOf(new Date(Date.UTC(d.getUTCFullYear(), 11, 28)));                       // allow:raw-byte-literal — Dec 28 always in last ISO week
+      if (!byWeekNoSet[iso.week] && !byWeekNoSet[-(lastWeek - iso.week + 1)]) return false;
+    }
+    if (byYearDaySet) {
+      var yd = _yearDayOf(d);
+      var dayCount = _daysInYear(d.getUTCFullYear());
+      if (!byYearDaySet[yd] && !byYearDaySet[-(dayCount - yd + 1)]) return false;
+    }
+    if (byHourSet   && !byHourSet[d.getUTCHours()])     return false;
+    if (byMinuteSet && !byMinuteSet[d.getUTCMinutes()]) return false;
+    if (bySecondSet && !bySecondSet[d.getUTCSeconds()]) return false;
     return true;
   }
   var t = startMs;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.11.35",
+  "version": "0.11.36",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:ce80c06c-78db-449e-871f-1b1da1e018c7",
+  "serialNumber": "urn:uuid:7efc7160-930c-489d-ad69-8455a414189a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-21T20:42:06.128Z",
+    "timestamp": "2026-05-21T21:48:29.730Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.11.35",
+      "bom-ref": "@blamejs/core@0.11.36",
       "type": "application",
       "name": "blamejs",
-      "version": "0.11.35",
+      "version": "0.11.36",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.11.35",
+      "purl": "pkg:npm/%40blamejs/core@0.11.36",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.11.35",
+      "ref": "@blamejs/core@0.11.36",
       "dependsOn": []
     }
   ]