rrule-ts 0.1.0 → 0.2.1

package/README.md

@@ -45,6 +45,68 @@ console.log(stringify(result.value))
 | `rrule-ts/locales/en` | English locale pack (planned) |
 | `rrule-ts/locales/de` | German locale pack (planned) |
 
+## Timezones and DST
+
+### Temporal and polyfill setup
+
+rrule-ts is Temporal-native and has zero runtime dependencies. Temporal is obtained through
+`getTemporal()`, which returns `globalThis.Temporal` when it is present (Node.js 26+, modern browsers
+with native Temporal) and otherwise returns the implementation injected by the caller via
+`setTemporal()`. If neither is available, `getTemporal()` throws a descriptive error.
+
+On Node.js < 26 or older browsers, install a polyfill and inject it once at application startup,
+before any RRULE expansion:
+
+```ts
+import { setTemporal } from 'rrule-ts'
+import { Temporal } from 'temporal-polyfill'
+
+setTemporal(Temporal)
+```
+
+### Wall-clock semantics
+
+rrule-ts uses wall-clock semantics throughout. For DAILY and coarser frequencies (WEEKLY, MONTHLY,
+YEARLY), the engine advances a `PlainDate` counter by the rule interval and pairs each date with the
+same target time components (hour, minute, second) taken from the `DTSTART`. Occurrences are then
+resolved to `ZonedDateTime` values by calling `Temporal.ZonedDateTime.from` with those components and
+the rule's timezone. As a result, a daily 09:00 event stays at 09:00 local time before and after a
+DST transition, even though the UTC offset changes.
+
+Sub-daily frequencies (HOURLY, MINUTELY, SECONDLY) also advance using wall-clock arithmetic on the
+time fields. The UTC-elapsed distance between consecutive occurrences can therefore vary across DST
+boundaries.
+
+### Fall-back (repeated hour)
+
+When a computed local time falls in a "fall back" ambiguity (the clock is set back and a local hour
+occurs twice), rrule-ts resolves the ambiguity with `disambiguation: 'compatible'`. The
+`'compatible'` setting selects the earlier of the two possible instants (equivalent to fold=0 in
+Python's datetime). This matches python-dateutil's fall-back behavior exactly.
+
+### Spring-forward (skipped hour)
+
+When a computed local time falls in the DST gap created by a spring-forward transition (a local time
+that does not exist), rrule-ts again applies `disambiguation: 'compatible'`. For a skipped time,
+`'compatible'` shifts the wall-clock time forward to the first valid instant after the gap. For
+example, 02:30 in a zone where clocks jump from 02:00 to 03:00 is normalised to 03:30 with the
+post-gap offset. Both times correspond to the same epoch milliseconds, but the ISO strings differ.
+
+This is the one deliberate deviation from python-dateutil. When dateutil encounters a nonexistent
+local time, it preserves the original wall-clock digits with the pre-gap UTC offset (e.g.
+`02:30-08:00` during the Los Angeles spring-forward). The resulting ISO string describes an instant
+that does not exist in the timezone. rrule-ts, via Temporal, always emits a valid instant. The
+epoch milliseconds are identical between the two representations, so downstream consumers that
+compare by timestamp are unaffected.
+
+This deviation is covered by three documented conformance cases in `packages/conformance`:
+
+| Case ID | Timezone | Description |
+|---|---|---|
+| `dst-la-spring-daily` | `America/Los_Angeles` | 02:30 in spring-forward gap; dateutil: `02:30-08:00`; rrule-ts: `03:30-07:00` |
+| `dst-berlin-spring-daily` | `Europe/Berlin` | 02:00 in spring-forward gap; dateutil: `02:00+01:00`; rrule-ts: `03:00+02:00` |
+| `dst-lord-howe-spring-daily` | `Australia/Lord_Howe` | 02:00 in 30-min gap; dateutil: `02:00+10:30`; rrule-ts: `02:30+11:00` |
+
 ## License
 
 MIT

package/dist/expand.d.ts

@@ -0,0 +1,34 @@
+import type { RRuleOptions, RRuleDtstart } from './types.js';
+/**
+ * Lazily iterate over RRULE occurrences.
+ *
+ * Yields Temporal values matching the dtstart type: Temporal.PlainDate,
+ * Temporal.PlainDateTime, Temporal.Instant, or Temporal.ZonedDateTime.
+ */
+export declare function iterate(options: RRuleOptions): Generator<RRuleDtstart>;
+/**
+ * Options for controlling which occurrences are returned by expand().
+ */
+export interface ExpandOptions {
+    /** Maximum number of occurrences to return. */
+    limit?: number;
+    /** Only return occurrences after this value. */
+    after?: RRuleDtstart;
+    /** Only return occurrences before (or at) this value. */
+    before?: RRuleDtstart;
+    /** Whether `after` and `before` bounds are inclusive (default true). */
+    inclusive?: boolean;
+}
+/**
+ * Materialize RRULE occurrences into an array.
+ *
+ * The second argument can be:
+ * - A plain number: the maximum number of occurrences to return (a hard limit
+ *   applied AFTER COUNT/UNTIL from the rule itself).
+ * - An ExpandOptions object with optional `limit`, `after`, `before`,
+ *   `inclusive` fields.
+ *
+ * Returns an array of Temporal values matching the dtstart type.
+ */
+export declare function expand(options: RRuleOptions, limitOrOpts?: number | ExpandOptions): RRuleDtstart[];
+//# sourceMappingURL=expand.d.ts.map

package/dist/expand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expand.d.ts","sourceRoot":"","sources":["../src/expand.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAuB,MAAM,YAAY,CAAA;AAw+BjF;;;;;GAKG;AACH,wBAAiB,OAAO,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC,YAAY,CAAC,CA2XvE;AA6CD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gDAAgD;IAChD,KAAK,CAAC,EAAE,YAAY,CAAA;IACpB,yDAAyD;IACzD,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CACpB,OAAO,EAAE,YAAY,EACrB,WAAW,CAAC,EAAE,MAAM,GAAG,aAAa,GACnC,YAAY,EAAE,CAkChB"}