Class RRStack

constructor

• new RRStack(opts: RRStackOptions): RRStack

  Create a new RRStack.

  Parameters

  • opts: RRStackOptions

    Constructor options. timeUnit defaults to 'ms'.

  Returns RRStack

  Remarks

  Options are normalized and frozen on the instance. The stack * compiles its rules immediately. The optional version is ignored.

Readonlyoptions

rules

• get rules(): readonly RuleJson[]

  Get the rule list (frozen).

  Returns readonly RuleJson[]

• set rules(next: readonly RuleJson[]): void

  Replace the rule list and recompile.

  Parameters

  • next: readonly RuleJson[]

    New rule array. A lightweight runtime check is applied; full validation occurs during compilation.

  Returns void

timeUnit

• get timeUnit(): UnixTimeUnit
  • Get the configured time unit ('ms' | 's'). Immutable.

  Returns UnixTimeUnit

timezone

• get timezone(): string

  Get the current IANA timezone id (unbranded string).

  Returns string

• set timezone(next: string): void

  Set the timezone and recompile.

  Parameters

  • next: string

    IANA timezone id (validated).

  Returns void

  Throws

  If the timezone is invalid.

addRule

• addRule(rule?: RuleJson, index?: number): void

  Insert a rule at a specific index (or append when index is omitted). Delegates to the rules setter (single recompile). When called with no arguments, inserts a default span rule: { effect: 'active', options: {} }.

  Parameters

  • Optionalrule: RuleJson
  • Optionalindex: number

  Returns void

bottom

• bottom(i: number): void

  Move a rule to the bottom (last index).

  Parameters

  • i: number

  Returns void

classifyRange

• classifyRange(from: number, to: number): RangeStatus

  Parameters

  • from: number
  • to: number

  Returns RangeStatus

describeRule

• describeRule(index: number, cfg?: DescribeConfig): string

  Describe a rule by index as human-readable text. Leverages rrule.toText() plus effect and duration phrasing. *

  Parameters

  • index: number

    Zero-based index into rules.

  • cfg: DescribeConfig = {}

  Returns string

  Throws

  RangeError if index is out of bounds; TypeError if not an integer.

  Example

  const text = stack.describeRule(0, { includeTimeZone: true, includeBounds: true });
  // e.g., "Active for 1 hour: every day at 5:00 (timezone UTC) [from 2024-01-10T00:00:00Z]"
  Copy

down

• down(i: number): void

  Move a rule down by one (toward the end). No-op if already at the bottom.

  Parameters

  • i: number

  Returns void

formatInstant

• formatInstant(t: number, opts?: { format?: string; locale?: string }): string

  Format an instant using this stack's configured timezone and time unit.

  • In 'ms' mode, t is interpreted as milliseconds since epoch.
  • In 's' mode, t is interpreted as integer seconds since epoch.

  Parameters

  • t: number

    Instant in the configured unit.

  • Optionalopts: { format?: string; locale?: string }

    Optional formatting:

    • format?: Luxon toFormat string (e.g., 'yyyy-LL-dd HH:mm').
    • locale?: BCP-47 locale tag applied prior to formatting.

  Returns string

  A string representation (ISO by default).

  Example

  stack.formatInstant(Date.UTC(2024, 0, 2, 5, 30, 0)); // '2024-01-02T05:30:00Z' (UTC)
  stack.formatInstant(ms, { format: 'yyyy-LL-dd HH:mm' }); // '2024-01-02 05:30'
  Copy

getEffectiveBounds

• getEffectiveBounds(): { empty: boolean; end?: number; start?: number }

  Compute effective active bounds across all rules.

  Returns { empty: boolean; end?: number; start?: number }

  { start?: number; end?: number; empty: boolean }

  • start and/or end are omitted for open-sided coverage.
  • empty indicates no active coverage.

  Example: Open-ended end

  const stack = new RRStack({
    timezone: 'UTC',
    rules: [{
      effect: 'active',
      duration: { hours: 1 },
      options: { freq: 'daily', byhour: [5], byminute: [0], bysecond: [0], starts: Date.UTC(2024, 0, 10, 0, 0, 0) },
    }],
  });
  const b = stack.getEffectiveBounds();
  // b.start is 2024-01-10T05:00:00Z (number); b.end is undefined (open end)
  Copy

getSegments

• getSegments(
      from: number,
      to: number,
      opts?: { limit?: number },
  ): Iterable<{ end: number; start: number; status: InstantStatus }>

  Stream contiguous status segments over [from, to). *

  Parameters

  • from: number

    Start of the window (inclusive), in the configured unit.

  • to: number

    End of the window (exclusive), in the configured unit.

  • Optionalopts: { limit?: number }

    Optional settings:

    • limit?: number — maximum number of segments to yield; throws if more would be produced (no silent truncation).

  Returns Iterable<{ end: number; start: number; status: InstantStatus }>

  An iterable of { start, end, status } entries. Memory-bounded and stable for long windows.

  Example

  for (const seg of stack.getSegments(from, to)) {
    // { start: number; end: number; status: 'active' | 'blackout' }
  }
  Copy

  Example: Using a limit to cap enumeration and guard long windows

  const segs: Array<{ start: number; end: number; status: 'active' | 'blackout' }> = [];
  try {
    for (const seg of stack.getSegments(from, to, { limit: 1000 })) {
      segs.push(seg);
    }
  } catch (err) {
    // If more than 1000 segments would be produced, an Error is thrown.
    // Consider reducing the window or processing in chunks (e.g., day/week).
  }
  Copy

  Note: The iterator is streaming and memory-bounded, but the number of segments can be large when many rules overlap across long windows. Use the limit option to make this explicit, or query in smaller chunks for real-time UIs.

isActiveAt

• isActiveAt(t: number): boolean

  Determine whether the stack is active at t.

  Parameters

  • t: number

    Timestamp in the configured unit.

  Returns boolean

  true when active; false when blackout.

now

• now(): number

  Return the current time in the configured unit.

  Returns number

removeRule

• removeRule(i: number): void

  Remove the rule at the specified index. Delegates to the rules setter (single recompile).

  Parameters

  • i: number

    Zero-based index of the rule to remove.

  Returns void

  Throws

  TypeError if i is not an integer; RangeError if out of range.

subscribe

• subscribe(listener: (self: RRStack) => void): () => void

  Subscribe to post‑mutation notifications. The listener is invoked exactly once after a successful state change (after recompile). The constructor initialization does not trigger notifications.

  Parameters

  • listener: (self: RRStack) => void

  Returns () => void

  Unsubscribe function.

swap

• swap(i: number, j: number): void

  Swap two rules by index (no-op if indices are equal).

  Parameters

  • i: number
  • j: number

  Returns void

toJson

• toJson(): RRStackOptions

  Serialize the stack to JSON.

  Returns RRStackOptions

  A RRStackOptions including version injected at build time * (fallback '0.0.0' in dev/test).

top

• top(i: number): void

  Move a rule to the top (index 0).

  Parameters

  • i: number

  Returns void

up

• up(i: number): void

  Move a rule up by one (toward index 0). No-op if already at the top.

  Parameters

  • i: number

  Returns void

update

• update(
      partial?: Partial<RRStackOptions>,
      policy?: UpdatePolicy,
  ): readonly Notice[]

  Ingest a partial RRStackOptions JSON with version/unit handling, replacements, and notices.

  • Applies timezone, defaultEffect, rules, and timeUnit in one pass.
  • Version pipeline (upgrade-config) executes first; defaults: • onVersionUp: 'off', onVersionDown: 'error', onVersionInvalid: 'error'.
  • timeUnit change: • If rules provided: replace rules as-is (assumed in new unit). • If not: convert retained rules' options.starts/options.ends between units (ms ↔ s).
  • Recompiles exactly once on success.

  Parameters

  • partial: Partial<RRStackOptions> = {}
  • policy: UpdatePolicy = {}

  Returns readonly Notice[]

StaticasTimeZoneId

• asTimeZoneId(tz: string): TimeZoneId

  Validate and brand a timezone id.

  Parameters

  • tz: string

    Candidate IANA timezone string.

  Returns TimeZoneId

  The branded TimeZoneId.

  Throws

  If the timezone is invalid in the current environment.

StaticisValidTimeZone

• isValidTimeZone(tz: string): boolean

  Validate an IANA timezone id.

  Parameters

  • tz: string

    Candidate IANA timezone string.

  Returns boolean

  True if recognized by the host ICU/Intl data.