@kensio/quando 0.1.0 → 1.0.0

package/README.md

@@ -2,8 +2,139 @@
 
 Declarative temporal rules for schedules, deadlines, constraints, and exceptions.
 
-## Status
+Quando answers one question: **given these rules about time, when does something
+happen?** `Temporal` tells you what a moment _is_; Quando tells you when
+something _occurs_ — "weekdays nine to five, except bank holidays", and then
+what that implies about now, about a window, and about three working hours from
+here.
 
-Early. The API is still being designed and nothing is published yet, so there is
-nothing here to install or call. `src/index.ts` is a placeholder that exists to
-keep the build and test pipeline honest until it has real code to run over.
+```bash
+npm install @kensio/quando
+```
+
+Requires a runtime with `Temporal`: **Node 26 or later**, or a browser that
+implements it. Quando reads the global rather than importing a polyfill, so it
+has no runtime dependencies; anywhere without `Temporal` natively can load
+`temporal-polyfill` first and everything here works untouched.
+
+## A rule
+
+```ts
+import { timeOfDay, weekdays } from "@kensio/quando";
+
+const openingHours = weekdays().and(timeOfDay("09:00", "17:00"));
+```
+
+There is no build step to that: it is already the rule, a plain JSON-shaped
+object with methods hanging off it. `JSON.stringify` gives you a document you
+can store, and `parseRule` gives you the rule back.
+
+## Four questions
+
+```ts
+import { activeAt, advanceBy, elapsed, next } from "@kensio/quando";
+
+const friday = Temporal.ZonedDateTime.from("2026-03-13T16:55[Europe/London]");
+
+// Is it open?
+activeAt(openingHours, friday);
+// → true
+
+// When does it next open?
+next(openingHours, { from: friday.add({ hours: 2 }) })?.start?.toString();
+// → 2026-03-16T09:00:00+00:00[Europe/London]
+
+// How much opening is there this week?
+elapsed(openingHours, {
+  from: Temporal.ZonedDateTime.from("2026-03-09T00:00[Europe/London]"),
+  to: Temporal.ZonedDateTime.from("2026-03-16T00:00[Europe/London]"),
+}).toString();
+// → PT40H
+
+// Three hours of packing that only count while it is open — when is it done?
+advanceBy(friday, Temporal.Duration.from({ hours: 3 }), {
+  during: openingHours,
+})?.toString();
+// → 2026-03-16T11:55:00+00:00[Europe/London]
+```
+
+That last one is why the library exists, and it is the one that is genuinely
+awkward to do by hand.
+
+## Or say it the way you would say it
+
+For opening hours and rotas there is a plainer front door, which builds the same
+thing:
+
+```ts
+import { rota, schedule, tally, weekdays, weekends } from "@kensio/quando";
+
+const openingHours = schedule()
+  .open(weekdays(), "09:00-17:00")
+  .closed("2026-12-25")
+  .hoursOn("2026-03-11", "09:00-15:00"); // close early, just that day
+
+openingHours.isOpen(friday);
+// → true
+
+const onCall = rota().assign(weekdays(), "alice").assign(weekends(), "bob");
+
+onCall.whoIsOn(friday);
+// → "alice"
+
+const staff = tally().plus(weekdays(), 3).plus("2026-03-11", 2);
+
+staff.at(Temporal.ZonedDateTime.from("2026-03-11T11:00[Europe/London]"));
+// → 5
+```
+
+For a schedule and a rota each line outranks the ones above it, so exceptions
+read in the order you would say them. A tally is the one that adds instead,
+because two teams of three on a Monday are six people. See
+[schedules and rotas](docs/schedules/) and [merging](docs/merging/).
+
+## Why intervals
+
+A rule does not answer about an instant — it produces the intervals over which
+it holds. Anything that samples has to choose a step size, trading correctness
+against speed, and every derived question becomes the same loop. Producing
+intervals turns those loops into arithmetic: working time in a window is a sum,
+three working days from now is a walk, and a rule that can never be satisfied
+yields nothing instead of never finishing.
+
+[Concepts](docs/concepts/) has the long version.
+
+## Documentation
+
+[quandojs.dev](https://quandojs.dev), which is built from [`docs/`](docs/) in
+this repository:
+
+- [Getting started](docs/getting-started/) — requirements, install, first query
+- [Concepts](docs/concepts/) — the model, and why it is that shape
+- [Rules](docs/rules/) — every rule type, and what each produces
+- [Queries](docs/queries/) — the four questions, and termination
+- [Time zones](docs/time-zones/) — wall clock against elapsed time
+- [Serialisation](docs/serialisation/) — the JSON form and its boundary
+- [Schedules and rotas](docs/schedules/) — opening hours and who is on, plainly
+- [Cascades](docs/cascades/) — layers carrying values, resolved by precedence
+- [Merging](docs/merging/) — overlap that adds rather than displaces
+- [Comparing](docs/comparing/) — canonical form, equality and cache keys
+- [API](docs/api/) — everything the package exports
+
+## What it is not
+
+Not a date library — `Temporal` is that, and Quando is built on it. Not a
+scheduler: Quando calculates _when_ and never fires anything, so its answer is
+your scheduler's input. Not storage, and not a holiday data provider; calendar
+data belongs in satellite packages so that the core carries none.
+
+Not a constraint solver either. Caps per window, minimum spacing and
+rolling-window totals ("ninety days in any hundred and eighty") constrain a
+pattern of occurrences rather than the moments in one, which is a different
+problem. See [what a rule cannot say](docs/concepts/#what-a-rule-cannot-say).
+
+Estimates, rule set diffing and a command line are designed and not yet built.
+
+## Licence
+
+[Apache-2.0](LICENSE).

package/dist/assigned.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Asking the four questions of a cascade rather than of a rule.
+ *
+ * `activeAt`, `elapsed`, `next` and `advanceBy` are about *when*, and a rule
+ * is what they read. A cascade says *what holds when*, which is a different
+ * question. Narrowing one to a single value turns it back into the first.
+ * The times a rota assigns to Alice are a stretch of when, and every question
+ * worth asking about a rule is worth asking about them.
+ *
+ * So {@link assigned} is what the queries take in place of a rule, and
+ * {@link valueAt} is the one question a rule has no version of.
+ */
+import type { Cascade, Valued } from "./cascade.js";
+import type { Context } from "./context.js";
+import type { IntervalStream } from "./interval-stream.js";
+import type { Rule } from "./rule.js";
+/**
+ * A cascade narrowed to the times it assigns one value.
+ *
+ * Not a rule, and deliberately not made to look like one. A rule is a document
+ * that stores and travels, and this is a question asked at the point of
+ * asking. Building one costs nothing and evaluates nothing.
+ */
+export interface Assigned<V> {
+    readonly cascade: Cascade<V>;
+    readonly is: V;
+}
+/** Either of the two things a query can read as the times it covers. */
+export type Covers<V> = Rule | Assigned<V>;
+/**
+ * The times a cascade assigns a value.
+ *
+ * ```ts
+ * elapsed(assigned(onCall, "alice"), week);
+ * advanceBy(from, threeHours, { during: assigned(onCall, "alice") });
+ * ```
+ *
+ * Sameness is `Object.is`, the same test {@link coalesce} uses, so a value
+ * matches by identity rather than by shape.
+ */
+export declare function assigned<V>(cascade: Cascade<V>, is: V): Assigned<V>;
+/**
+ * The times something covers, whichever of the two it is.
+ *
+ * This is the one place the queries have to know that a cascade exists, and
+ * what comes back either way is an ordinary interval stream, so everything
+ * above it stays written once.
+ */
+export declare function covered<V>(covers: Covers<V>, context: Context): IntervalStream;
+/**
+ * What a cascade assigns at an instant, or `undefined` where nothing does.
+ *
+ * The question a rule has no version of. `activeAt` asks whether a rule covers
+ * a moment, and the answer for a cascade is not whether but what.
+ *
+ * Always terminates, whatever the layers say, because it asks about the
+ * smallest window there is.
+ */
+export declare function valueAt<V>(cascade: Cascade<V>, at: Temporal.ZonedDateTime, context?: Omit<Context, "from" | "to">): V | undefined;
+/**
+ * The next stretch a cascade assigns anything at all, with its value.
+ *
+ * `next` narrowed to one value answers "when is Alice next on". This answers
+ * "what happens next", whatever that turns out to be, which is the question a
+ * timeline asks.
+ */
+export declare function nextValue<V>(cascade: Cascade<V>, context: Context): Valued<V> | undefined;
+//# sourceMappingURL=assigned.d.ts.map

package/dist/assigned.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assigned.d.ts","sourceRoot":"","sources":["../src/assigned.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAGtC;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;CAChB;AAED,wEAAwE;AACxE,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;AAE3C;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAEnE;AAOD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EACjB,OAAO,EAAE,OAAO,GACf,cAAc,CAKhB;AAWD;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,EAAE,EAAE,QAAQ,CAAC,aAAa,EAC1B,OAAO,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC,GACrC,CAAC,GAAG,SAAS,CAQf;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,OAAO,EAAE,OAAO,GACf,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,CAGvB"}

package/dist/assigned.js

@@ -0,0 +1,84 @@
+/**
+ * Asking the four questions of a cascade rather than of a rule.
+ *
+ * `activeAt`, `elapsed`, `next` and `advanceBy` are about *when*, and a rule
+ * is what they read. A cascade says *what holds when*, which is a different
+ * question. Narrowing one to a single value turns it back into the first.
+ * The times a rota assigns to Alice are a stretch of when, and every question
+ * worth asking about a rule is worth asking about them.
+ *
+ * So {@link assigned} is what the queries take in place of a rule, and
+ * {@link valueAt} is the one question a rule has no version of.
+ */
+import { intervals } from "./interpret.js";
+import { resolve } from "./resolve.js";
+import { take } from "./stream.js";
+/**
+ * The times a cascade assigns a value.
+ *
+ * ```ts
+ * elapsed(assigned(onCall, "alice"), week);
+ * advanceBy(from, threeHours, { during: assigned(onCall, "alice") });
+ * ```
+ *
+ * Sameness is `Object.is`, the same test {@link coalesce} uses, so a value
+ * matches by identity rather than by shape.
+ */
+export function assigned(cascade, is) {
+    return { cascade, is };
+}
+/** Whether a query is reading a rule or a narrowed cascade. */
+function isRule(covers) {
+    return "type" in covers;
+}
+/**
+ * The times something covers, whichever of the two it is.
+ *
+ * This is the one place the queries have to know that a cascade exists, and
+ * what comes back either way is an ordinary interval stream, so everything
+ * above it stays written once.
+ */
+export function covered(covers, context) {
+    if (isRule(covers)) {
+        return intervals(covers, context);
+    }
+    return matching(covers, context);
+}
+/** The stretches of a resolved cascade carrying the value asked for. */
+function* matching(covers, context) {
+    for (const span of resolve(covers.cascade, context)) {
+        if (Object.is(span.value, covers.is)) {
+            yield { start: span.start, end: span.end };
+        }
+    }
+}
+/**
+ * What a cascade assigns at an instant, or `undefined` where nothing does.
+ *
+ * The question a rule has no version of. `activeAt` asks whether a rule covers
+ * a moment, and the answer for a cascade is not whether but what.
+ *
+ * Always terminates, whatever the layers say, because it asks about the
+ * smallest window there is.
+ */
+export function valueAt(cascade, at, context) {
+    const moment = {
+        ...context,
+        from: at,
+        to: at.add({ nanoseconds: 1 }),
+    };
+    const [now] = take(resolve(cascade, moment), 1);
+    return now?.value;
+}
+/**
+ * The next stretch a cascade assigns anything at all, with its value.
+ *
+ * `next` narrowed to one value answers "when is Alice next on". This answers
+ * "what happens next", whatever that turns out to be, which is the question a
+ * timeline asks.
+ */
+export function nextValue(cascade, context) {
+    const [first] = take(resolve(cascade, context), 1);
+    return first;
+}
+//# sourceMappingURL=assigned.js.map

package/dist/assigned.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assigned.js","sourceRoot":"","sources":["../src/assigned.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAiBnC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,QAAQ,CAAI,OAAmB,EAAE,EAAK;IACpD,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AACzB,CAAC;AAED,+DAA+D;AAC/D,SAAS,MAAM,CAAI,MAAiB;IAClC,OAAO,MAAM,IAAI,MAAM,CAAC;AAC1B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CACrB,MAAiB,EACjB,OAAgB;IAEhB,IAAI,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QACnB,OAAO,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACnC,CAAC;AAED,wEAAwE;AACxE,QAAQ,CAAC,CAAC,QAAQ,CAAI,MAAmB,EAAE,OAAgB;IACzD,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;QACpD,IAAI,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;YACrC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7C,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,OAAO,CACrB,OAAmB,EACnB,EAA0B,EAC1B,OAAsC;IAEtC,MAAM,MAAM,GAAY;QACtB,GAAG,OAAO;QACV,IAAI,EAAE,EAAE;QACR,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;KAC/B,CAAC;IACF,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IAChD,OAAO,GAAG,EAAE,KAAK,CAAC;AACpB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CACvB,OAAmB,EACnB,OAAgB;IAEhB,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;IACnD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/build.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A readable way to write a rule, which is also the rule.
+ *
+ * `weekdays().and(timeOfDay("09:00", "17:00"))` reads better than the nested
+ * object literal it stands for — and it *is* that object literal, with methods
+ * hanging off it. `JSON.stringify` omits function-valued properties, so a built
+ * rule serialises to exactly the document a hand-written one would, with no
+ * `.build()` step and nothing to unwrap.
+ *
+ * That is the whole trick: there is no builder type to convert out of, because
+ * a built rule already satisfies `Rule`.
+ */
+import type { AllRule, AlwaysRule, AnyRule, DatesRule, DaysOfWeekRule, NeverRule, NotRule, Rule, TimeOfDayRule, Weekday } from "./rule.js";
+/** A rule, plus the methods for combining it with others. */
+export type Built<R extends Rule> = R & {
+    /** Both this and the others must hold. */
+    readonly and: (...others: readonly Rule[]) => Built<AllRule>;
+    /** This or any of the others. */
+    readonly or: (...others: readonly Rule[]) => Built<AnyRule>;
+    /**
+     * This, minus the times the others cover.
+     *
+     * The common shape by far — opening hours except holidays, a schedule except
+     * a shutdown — and worth its own method because writing it out is
+     * `all(this, not(any(others)))`, which reads like nothing at all.
+     */
+    readonly except: (...others: readonly Rule[]) => Built<AllRule>;
+};
+/** All of time. */
+export declare function always(): Built<AlwaysRule>;
+/** No time at all. */
+export declare function never(): Built<NeverRule>;
+/** Whole days, by day of the week. */
+export declare function daysOfWeek(...days: readonly Weekday[]): Built<DaysOfWeekRule>;
+/** Monday to Friday. */
+export declare function weekdays(): Built<DaysOfWeekRule>;
+/** Saturday and Sunday. */
+export declare function weekends(): Built<DaysOfWeekRule>;
+/**
+ * A wall-clock window within each day. A `to` earlier than `from` wraps past
+ * midnight, so `timeOfDay("22:00", "06:00")` is a night shift.
+ */
+export declare function timeOfDay(from: string, to: string, zone?: string): Built<TimeOfDayRule>;
+/** Whole days, by date. */
+export declare function dates(...days: readonly string[]): Built<DatesRule>;
+/** Every one of these must hold. With none, all of time. */
+export declare function all(...rules: readonly Rule[]): Built<AllRule>;
+/** Any one of these. With none, no time at all. */
+export declare function any(...rules: readonly Rule[]): Built<AnyRule>;
+/** The times a rule does not cover. */
+export declare function not(rule: Rule): Built<NotRule>;
+/** Whole days, by the zone a day is measured in. */
+export declare function inZone<R extends DaysOfWeekRule | DatesRule | TimeOfDayRule>(rule: R, zone: string): Built<R>;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,OAAO,EACP,SAAS,EACT,cAAc,EACd,SAAS,EACT,OAAO,EACP,IAAI,EACJ,aAAa,EACb,OAAO,EACR,MAAM,WAAW,CAAC;AAEnB,6DAA6D;AAC7D,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG;IACtC,0CAA0C;IAC1C,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,MAAM,EAAE,SAAS,IAAI,EAAE,KAAK,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7D,iCAAiC;IACjC,QAAQ,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,EAAE,SAAS,IAAI,EAAE,KAAK,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5D;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,SAAS,IAAI,EAAE,KAAK,KAAK,CAAC,OAAO,CAAC,CAAC;CACjE,CAAC;AAmBF,mBAAmB;AACnB,wBAAgB,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,CAE1C;AAED,sBAAsB;AACtB,wBAAgB,KAAK,IAAI,KAAK,CAAC,SAAS,CAAC,CAExC;AAED,sCAAsC;AACtC,wBAAgB,UAAU,CAAC,GAAG,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,KAAK,CAAC,cAAc,CAAC,CAE7E;AAED,wBAAwB;AACxB,wBAAgB,QAAQ,IAAI,KAAK,CAAC,cAAc,CAAC,CAEhD;AAED,2BAA2B;AAC3B,wBAAgB,QAAQ,IAAI,KAAK,CAAC,cAAc,CAAC,CAEhD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,IAAI,CAAC,EAAE,MAAM,GACZ,KAAK,CAAC,aAAa,CAAC,CAMtB;AAED,2BAA2B;AAC3B,wBAAgB,KAAK,CAAC,GAAG,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC,CAElE;AAED,4DAA4D;AAC5D,wBAAgB,GAAG,CAAC,GAAG,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,CAE7D;AAED,mDAAmD;AACnD,wBAAgB,GAAG,CAAC,GAAG,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,KAAK,CAAC,OAAO,CAAC,CAE7D;AAED,uCAAuC;AACvC,wBAAgB,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,CAE9C;AAED,oDAAoD;AACpD,wBAAgB,MAAM,CAAC,CAAC,SAAS,cAAc,GAAG,SAAS,GAAG,aAAa,EACzE,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,MAAM,GACX,KAAK,CAAC,CAAC,CAAC,CAEV"}

package/dist/build.js

@@ -0,0 +1,77 @@
+/**
+ * A readable way to write a rule, which is also the rule.
+ *
+ * `weekdays().and(timeOfDay("09:00", "17:00"))` reads better than the nested
+ * object literal it stands for — and it *is* that object literal, with methods
+ * hanging off it. `JSON.stringify` omits function-valued properties, so a built
+ * rule serialises to exactly the document a hand-written one would, with no
+ * `.build()` step and nothing to unwrap.
+ *
+ * That is the whole trick: there is no builder type to convert out of, because
+ * a built rule already satisfies `Rule`.
+ */
+function build(node) {
+    const self = {
+        ...node,
+        and: (...others) => build({ type: "all", rules: [self, ...others] }),
+        or: (...others) => build({ type: "any", rules: [self, ...others] }),
+        except: (...others) => build({
+            type: "all",
+            rules: [
+                self,
+                { type: "not", rule: { type: "any", rules: [...others] } },
+            ],
+        }),
+    };
+    return self;
+}
+/** All of time. */
+export function always() {
+    return build({ type: "always" });
+}
+/** No time at all. */
+export function never() {
+    return build({ type: "never" });
+}
+/** Whole days, by day of the week. */
+export function daysOfWeek(...days) {
+    return build({ type: "daysOfWeek", days });
+}
+/** Monday to Friday. */
+export function weekdays() {
+    return daysOfWeek("monday", "tuesday", "wednesday", "thursday", "friday");
+}
+/** Saturday and Sunday. */
+export function weekends() {
+    return daysOfWeek("saturday", "sunday");
+}
+/**
+ * A wall-clock window within each day. A `to` earlier than `from` wraps past
+ * midnight, so `timeOfDay("22:00", "06:00")` is a night shift.
+ */
+export function timeOfDay(from, to, zone) {
+    return build(zone === undefined
+        ? { type: "timeOfDay", from, to }
+        : { type: "timeOfDay", from, to, zone });
+}
+/** Whole days, by date. */
+export function dates(...days) {
+    return build({ type: "dates", dates: days });
+}
+/** Every one of these must hold. With none, all of time. */
+export function all(...rules) {
+    return build({ type: "all", rules });
+}
+/** Any one of these. With none, no time at all. */
+export function any(...rules) {
+    return build({ type: "any", rules });
+}
+/** The times a rule does not cover. */
+export function not(rule) {
+    return build({ type: "not", rule });
+}
+/** Whole days, by the zone a day is measured in. */
+export function inZone(rule, zone) {
+    return build({ ...rule, zone });
+}
+//# sourceMappingURL=build.js.map

package/dist/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"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"}

package/dist/canonical-rule.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The one form of a rule that says what a rule says.
+ *
+ * `.except(…)` is `all(this, not(any(…)))` spelled out, so a rule built with
+ * it carries an `all` inside an `all`. Nothing is wrong with that, and it does
+ * mean two rules a reader would call identical are two different documents.
+ * Comparing them, hashing them or diffing them all want the same thing first,
+ * which is a form that depends on what a rule says rather than on how it was
+ * written.
+ *
+ * The normal form here is syntactic. It flattens, drops identities, collapses
+ * double negation, sorts and deduplicates, and stops. Two rules that *cover
+ * the same time* by different routes stay different, because deciding that in
+ * general means evaluating them over all of time. `always` and the seven days
+ * of the week are the pair to keep in mind.
+ *
+ * Nothing here throws. A rule holding a date that will not parse comes back
+ * with that date untouched, because a function used for cache keys is worth
+ * more total than strict, and `parseRule` is the place that refuses.
+ */
+import { type Rule } from "./rule.js";
+export declare function canonicalRule(rule: Rule): Rule;
+//# sourceMappingURL=canonical-rule.d.ts.map

package/dist/canonical-rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-rule.d.ts","sourceRoot":"","sources":["../src/canonical-rule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,KAAK,IAAI,EAA0B,MAAM,WAAW,CAAC;AAyF9D,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAqD9C"}

package/dist/canonical-rule.js

@@ -0,0 +1,139 @@
+/**
+ * The one form of a rule that says what a rule says.
+ *
+ * `.except(…)` is `all(this, not(any(…)))` spelled out, so a rule built with
+ * it carries an `all` inside an `all`. Nothing is wrong with that, and it does
+ * mean two rules a reader would call identical are two different documents.
+ * Comparing them, hashing them or diffing them all want the same thing first,
+ * which is a form that depends on what a rule says rather than on how it was
+ * written.
+ *
+ * The normal form here is syntactic. It flattens, drops identities, collapses
+ * double negation, sorts and deduplicates, and stops. Two rules that *cover
+ * the same time* by different routes stay different, because deciding that in
+ * general means evaluating them over all of time. `always` and the seven days
+ * of the week are the pair to keep in mind.
+ *
+ * Nothing here throws. A rule holding a date that will not parse comes back
+ * with that date untouched, because a function used for cache keys is worth
+ * more total than strict, and `parseRule` is the place that refuses.
+ */
+import { WEEKDAYS } from "./rule.js";
+/** Where a weekday sorts. Calendar order rather than alphabetical. */
+const DAY_ORDER = new Map(WEEKDAYS.map((day, index) => [day, index]));
+/** A rule's stable string form, which is what sorting and equality compare. */
+function key(rule) {
+    return JSON.stringify(rule);
+}
+/** Present or absent, never present-and-undefined. */
+function zonePart(zone) {
+    return zone === undefined ? {} : { zone };
+}
+const asTime = (from) => Temporal.PlainTime.from(from);
+const asDate = (from) => Temporal.PlainDate.from(from);
+/**
+ * A `Temporal` value written the one way, where it can be read at all.
+ *
+ * `"09:00"` and `"09:00:00"` are the same time of day written twice, and two
+ * rules holding one each should compare equal. A string neither form can read
+ * is handed back as it came, so this stays total.
+ */
+function written(value, read) {
+    try {
+        return read(value).toString();
+    }
+    catch {
+        return value;
+    }
+}
+function canonicalDays(days) {
+    return [...new Set(days)].toSorted((a, b) => (DAY_ORDER.get(a) ?? 0) - (DAY_ORDER.get(b) ?? 0));
+}
+function canonicalDates(dates) {
+    const one = dates.map((date) => written(date, asDate));
+    return [...new Set(one)].toSorted();
+}
+/**
+ * The operands of an `all` or an `any`, flattened, reduced and ordered.
+ *
+ * Both are the same shape with the two constants swapped. For `all`, `always`
+ * adds nothing and `never` settles it. For `any` it is the other way round.
+ */
+function combined(type, rules) {
+    const absorbed = type === "all" ? "always" : "never";
+    const settles = type === "all" ? "never" : "always";
+    const flat = [];
+    for (const rule of rules) {
+        const inner = canonicalRule(rule);
+        if (inner.type === settles) {
+            return { type: settles };
+        }
+        if (inner.type === absorbed) {
+            continue;
+        }
+        // Already canonical, so its own operands are reduced and its type is not
+        // the one being flattened into unless it genuinely nests.
+        if (inner.type === type) {
+            flat.push(...inner.rules);
+            continue;
+        }
+        flat.push(inner);
+    }
+    const kept = [...new Map(flat.map((rule) => [key(rule), rule])).values()];
+    const unique = kept.toSorted((a, b) => key(a).localeCompare(key(b)));
+    const only = unique[0];
+    if (only === undefined) {
+        return { type: absorbed };
+    }
+    return unique.length === 1 ? only : { type, rules: unique };
+}
+export function canonicalRule(rule) {
+    switch (rule.type) {
+        case "always":
+        case "never": {
+            return { type: rule.type };
+        }
+        case "daysOfWeek": {
+            return {
+                type: "daysOfWeek",
+                days: canonicalDays(rule.days),
+                ...zonePart(rule.zone),
+            };
+        }
+        case "dates": {
+            return {
+                type: "dates",
+                dates: canonicalDates(rule.dates),
+                ...zonePart(rule.zone),
+            };
+        }
+        case "timeOfDay": {
+            return {
+                type: "timeOfDay",
+                from: written(rule.from, asTime),
+                to: written(rule.to, asTime),
+                ...zonePart(rule.zone),
+            };
+        }
+        case "not": {
+            const inner = canonicalRule(rule.rule);
+            // Two complements cancel, and the complement of a constant is the other
+            // one. Both keep a `not` out of the form where it says nothing.
+            if (inner.type === "not") {
+                return inner.rule;
+            }
+            if (inner.type === "always") {
+                return { type: "never" };
+            }
+            if (inner.type === "never") {
+                return { type: "always" };
+            }
+            return { type: "not", rule: inner };
+        }
+        case "all":
+        case "any": {
+            return combined(rule.type, rule.rules);
+        }
+    }
+}
+//# sourceMappingURL=canonical-rule.js.map

package/dist/canonical-rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-rule.js","sourceRoot":"","sources":["../src/canonical-rule.ts"],"names":[],"mappings":"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"}