@kensio/quando 0.1.0 → 0.2.0

package/dist/query.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Asking a rule a question, rather than reading the times it covers.
+ *
+ * `intervals` is the plumbing. These are what a caller actually wants: is it
+ * open now, how much working time is in this window, when does it next open,
+ * and — the one both of the libraries this evolves from were built around —
+ * where do you get to after three hours that only count while it is open.
+ *
+ * Durations are exact elapsed time throughout. Three operating hours means
+ * three real hours of opening, so a window spanning a clock change is measured
+ * by how long it lasted rather than by what the clock said.
+ */
+import type { Context } from "./context.js";
+import { type Interval } from "./interval.js";
+import type { Rule } from "./rule.js";
+/**
+ * How far a search runs.
+ *
+ * With neither the context's `to` nor a `within`, a search is unbounded. That
+ * is fine and often what you want — the first interval of a satisfiable rule
+ * arrives immediately, however far the rule recurs. It is only a rule that
+ * covers *nothing* that has no answer to give and no way to discover it, and
+ * that case runs until stopped. Give a bound when the answer might be nothing.
+ */
+export interface Search {
+    /**
+     * Look no further ahead than this from where the search starts.
+     *
+     * Narrows only. A context that already ends before the horizon keeps its own
+     * end, because a caller who gave a window meant it.
+     */
+    readonly within?: Temporal.Duration;
+}
+/**
+ * Whether a rule covers an instant.
+ *
+ * Always terminates, whatever the rule and whatever the context: it asks about
+ * the smallest window there is, so nothing can walk far looking for an answer.
+ */
+export declare function activeAt(rule: Rule, at: Temporal.ZonedDateTime, context?: Omit<Context, "from" | "to">): boolean;
+/**
+ * How much time a rule covers within a window.
+ *
+ * Needs a window with an end, because the alternative is a number that never
+ * finishes being counted.
+ */
+export declare function elapsed(rule: Rule, context: Context): Temporal.Duration;
+/**
+ * The next stretch of time a rule covers, at or after the context's start.
+ *
+ * `undefined` when there is none within the search. If the rule is covering
+ * time already at the context's start, that stretch is returned clipped to
+ * begin there — "when does it next open" answers "it is open" rather than
+ * skipping to tomorrow.
+ */
+export declare function next(rule: Rule, context: Context, search?: Search): Interval | undefined;
+/**
+ * Where you get to after an amount of time that only counts while a rule holds.
+ *
+ * Three operating hours from an order placed at five to five on a Friday is
+ * some way into Monday morning, and this is the function that says where.
+ * `undefined` when the search runs out before the time does.
+ */
+export declare function advanceBy(from: Temporal.ZonedDateTime, amount: Temporal.Duration, options: {
+    readonly during: Rule;
+} & Search & Omit<Context, "from" | "to">): Temporal.ZonedDateTime | undefined;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAwB,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEpE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAMtC;;;;;;;;GAQG;AACH,MAAM,WAAW,MAAM;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,QAAQ,CAAC;CACrC;AA0CD;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,IAAI,EACV,EAAE,EAAE,QAAQ,CAAC,aAAa,EAC1B,OAAO,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC,GACrC,OAAO,CAOT;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAevE;AAED;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAClB,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,OAAO,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,QAAQ,GAAG,SAAS,CAGtB;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,QAAQ,CAAC,aAAa,EAC5B,MAAM,EAAE,QAAQ,CAAC,QAAQ,EACzB,OAAO,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;CAAE,GAAG,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC,GACzE,QAAQ,CAAC,aAAa,GAAG,SAAS,CA8BpC"}

package/dist/query.js

@@ -0,0 +1,121 @@
+/**
+ * Asking a rule a question, rather than reading the times it covers.
+ *
+ * `intervals` is the plumbing. These are what a caller actually wants: is it
+ * open now, how much working time is in this window, when does it next open,
+ * and — the one both of the libraries this evolves from were built around —
+ * where do you get to after three hours that only count while it is open.
+ *
+ * Durations are exact elapsed time throughout. Three operating hours means
+ * three real hours of opening, so a window spanning a clock change is measured
+ * by how long it lasted rather than by what the clock said.
+ */
+import { duration, earlierEnd } from "./interval.js";
+import { intervals } from "./interpret.js";
+import { take } from "./stream.js";
+/** Zero, as a duration to accumulate onto. */
+const NOTHING = Temporal.Duration.from({ seconds: 0 });
+function bounded(context, search) {
+    const within = search?.within;
+    if (within === undefined) {
+        return context;
+    }
+    // Whichever runs out first. `within` narrows a search and must never widen
+    // one: a context that already ends on Saturday means the caller is not
+    // interested in Monday, whatever horizon the search asks for.
+    const horizon = context.from.add(within);
+    return { ...context, to: earlierEnd(context.to, horizon) ?? horizon };
+}
+/**
+ * Refuses an amount whose units do not mean one fixed length of time.
+ *
+ * A day is not 24 hours on the two mornings a year a clock changes, and a
+ * month is not any number of hours at all. Both halves of this function would
+ * otherwise disagree about that: the accounting compares durations without a
+ * reference point, where a day *is* 24 hours, while the final step adds to a
+ * `ZonedDateTime`, where it is a calendar day. `P1D` and `PT24H` would land an
+ * hour apart, and neither answer would be wrong enough to notice.
+ *
+ * Weeks and months do not even get that far — comparing them without a
+ * reference point throws, with an empty message.
+ */
+function checkExact(amount) {
+    const calendar = ["years", "months", "weeks", "days"].filter((unit) => amount[unit] !== 0);
+    if (calendar.length > 0) {
+        throw new RangeError(`advanceBy() measures elapsed time, so ${amount.toString()} is ambiguous: ` +
+            `${calendar.join(" and ")} are calendar units, and a day is not 24 hours ` +
+            `on the mornings a clock changes. Give hours, minutes or seconds.`);
+    }
+}
+/**
+ * Whether a rule covers an instant.
+ *
+ * Always terminates, whatever the rule and whatever the context: it asks about
+ * the smallest window there is, so nothing can walk far looking for an answer.
+ */
+export function activeAt(rule, at, context) {
+    const moment = {
+        ...context,
+        from: at,
+        to: at.add({ nanoseconds: 1 }),
+    };
+    return take(intervals(rule, moment), 1).length > 0;
+}
+/**
+ * How much time a rule covers within a window.
+ *
+ * Needs a window with an end, because the alternative is a number that never
+ * finishes being counted.
+ */
+export function elapsed(rule, context) {
+    if (context.to === undefined) {
+        throw new RangeError("elapsed() needs a window with an end: give the context a `to`.");
+    }
+    let total = NOTHING;
+    for (const interval of intervals(rule, context)) {
+        const length = duration(interval);
+        if (length !== undefined) {
+            total = total.add(length);
+        }
+    }
+    return total.round({ largestUnit: "hour" });
+}
+/**
+ * The next stretch of time a rule covers, at or after the context's start.
+ *
+ * `undefined` when there is none within the search. If the rule is covering
+ * time already at the context's start, that stretch is returned clipped to
+ * begin there — "when does it next open" answers "it is open" rather than
+ * skipping to tomorrow.
+ */
+export function next(rule, context, search) {
+    const [first] = take(intervals(rule, bounded(context, search)), 1);
+    return first;
+}
+/**
+ * Where you get to after an amount of time that only counts while a rule holds.
+ *
+ * Three operating hours from an order placed at five to five on a Friday is
+ * some way into Monday morning, and this is the function that says where.
+ * `undefined` when the search runs out before the time does.
+ */
+export function advanceBy(from, amount, options) {
+    checkExact(amount);
+    if (Temporal.Duration.compare(amount, NOTHING) < 0) {
+        throw new RangeError(`advanceBy() cannot go backwards. Asked for ${amount.toString()}.`);
+    }
+    const { during, within, ...rest } = options;
+    const context = bounded({ ...rest, from }, within === undefined ? undefined : { within });
+    let remaining = amount;
+    for (const interval of intervals(during, context)) {
+        const length = duration(interval);
+        // An interval with no end has more than enough of whatever is left.
+        if (length === undefined ||
+            Temporal.Duration.compare(length, remaining) >= 0) {
+            return interval.start?.add(remaining);
+        }
+        remaining = remaining.subtract(length);
+    }
+    return undefined;
+}
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

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

package/dist/resolve.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Reading a cascade as the values it assigns, over time.
+ *
+ * The whole of resolution is one idea: **a layer holds where its own scope
+ * holds and no layer above it claims the moment.** Said as a rule that is
+ * `all(scope, not(any(…the scopes above)))`, which the rule interpreter
+ * already knows how to evaluate — so precedence costs no new algebra, and the
+ * clipping, the zone normalisation and the laziness all come along unchanged.
+ *
+ * What comes back is only the time a cascade actually assigns. A moment no
+ * layer claims is absent from the stream rather than present with some empty
+ * value, for the same reason a rule yields only the time it covers: there is
+ * no such thing as the value of an unassigned moment.
+ */
+import type { Cascade } from "./cascade.js";
+import type { Context } from "./context.js";
+import { type ValuedStream } from "./valued-stream.js";
+/**
+ * The values a cascade assigns within a context, in order and coalesced.
+ *
+ * Lazy, and endless when the context has no end and the layers recur — the
+ * same contract `intervals` keeps, because this is built out of it.
+ */
+export declare function resolve<V>(cascade: Cascade<V>, context: Context): ValuedStream<V>;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAS,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAI5C,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE7E;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EACvB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,OAAO,EAAE,OAAO,GACf,YAAY,CAAC,CAAC,CAAC,CASjB"}

package/dist/resolve.js

@@ -0,0 +1,80 @@
+/**
+ * Reading a cascade as the values it assigns, over time.
+ *
+ * The whole of resolution is one idea: **a layer holds where its own scope
+ * holds and no layer above it claims the moment.** Said as a rule that is
+ * `all(scope, not(any(…the scopes above)))`, which the rule interpreter
+ * already knows how to evaluate — so precedence costs no new algebra, and the
+ * clipping, the zone normalisation and the laziness all come along unchanged.
+ *
+ * What comes back is only the time a cascade actually assigns. A moment no
+ * layer claims is absent from the stream rather than present with some empty
+ * value, for the same reason a rule yields only the time it covers: there is
+ * no such thing as the value of an unassigned moment.
+ */
+import { intervals } from "./interpret.js";
+import { coalesce, interleave } from "./valued-stream.js";
+/**
+ * The values a cascade assigns within a context, in order and coalesced.
+ *
+ * Lazy, and endless when the context has no end and the layers recur — the
+ * same contract `intervals` keeps, because this is built out of it.
+ */
+export function resolve(cascade, context) {
+    const claimed = cascade.layers.map((layer, index) => assignments(layer, wins(layer.scope, cascade.layers.slice(index + 1)), context));
+    return coalesce(interleave(claimed));
+}
+/**
+ * Where a layer wins: inside its own scope, and outside every scope above it.
+ *
+ * The layers above are re-evaluated once per layer below them, which is
+ * quadratic in the number of layers. Layers are few and the streams are lazy,
+ * so this buys a precedence that needs no sweep of its own for the price of
+ * some repeated work over a handful of rules.
+ */
+function wins(scope, above) {
+    // For the top layer this is `all(scope, not(any()))` — `any()` covers no
+    // time, its complement covers all of it, and the intersection is the scope
+    // itself. Left general rather than special-cased: one path is easier to
+    // trust than two, and the identities make the general one right.
+    return {
+        type: "all",
+        rules: [
+            scope,
+            {
+                type: "not",
+                rule: { type: "any", rules: above.map((layer) => layer.scope) },
+            },
+        ],
+    };
+}
+/** What a layer assigns, over the region it wins. */
+function* assignments(layer, region, context) {
+    for (const interval of intervals(region, context)) {
+        if ("value" in layer) {
+            yield { ...interval, value: layer.value };
+            continue;
+        }
+        // A replacing layer claims the region and hands the question inwards. The
+        // inner cascade is resolved against the region rather than against the
+        // whole context, which is what stops it reaching outside the scope it
+        // replaces — and what makes anything it leaves unassigned stay unassigned
+        // rather than falling through to the layers this one outranks.
+        yield* resolve(layer.replace, within(context, interval));
+    }
+}
+/**
+ * A context narrowed to one interval.
+ *
+ * The interval came from evaluating a rule against this context, so its start
+ * is inside the window and never unbounded; the fallback is for the type
+ * rather than for a case that occurs.
+ */
+function within(context, interval) {
+    const { from, to: _replaced, ...rest } = context;
+    const start = interval.start ?? from;
+    return interval.end === undefined
+        ? { ...rest, from: start }
+        : { ...rest, from: start, to: interval.end };
+}
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAqB,MAAM,oBAAoB,CAAC;AAE7E;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CACrB,OAAmB,EACnB,OAAgB;IAEhB,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAClD,WAAW,CACT,KAAK,EACL,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,EAClD,OAAO,CACR,CACF,CAAC;IACF,OAAO,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,IAAI,CAAC,KAAW,EAAE,KAAgC;IACzD,yEAAyE;IACzE,2EAA2E;IAC3E,wEAAwE;IACxE,iEAAiE;IACjE,OAAO;QACL,IAAI,EAAE,KAAK;QACX,KAAK,EAAE;YACL,KAAK;YACL;gBACE,IAAI,EAAE,KAAK;gBACX,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;aAChE;SACF;KACF,CAAC;AACJ,CAAC;AAED,qDAAqD;AACrD,QAAQ,CAAC,CAAC,WAAW,CACnB,KAAe,EACf,MAAY,EACZ,OAAgB;IAEhB,KAAK,MAAM,QAAQ,IAAI,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;QAClD,IAAI,OAAO,IAAI,KAAK,EAAE,CAAC;YACrB,MAAM,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;YAC1C,SAAS;QACX,CAAC;QAED,0EAA0E;QAC1E,uEAAuE;QACvE,sEAAsE;QACtE,0EAA0E;QAC1E,+DAA+D;QAC/D,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC3D,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,MAAM,CAAC,OAAgB,EAAE,QAAkB;IAClD,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IACjD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,IAAI,IAAI,CAAC;IAErC,OAAO,QAAQ,CAAC,GAAG,KAAK,SAAS;QAC/B,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE;QAC1B,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,CAAC,GAAG,EAAE,CAAC;AACjD,CAAC"}

package/dist/rota.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Who is on, in the words people use for that.
+ *
+ * The same machinery as a [schedule](./schedule.ts) with the value left open:
+ * a rota assigns a person, a tariff assigns a rate, a roster assigns how many
+ * are working. A `Rota<V>` is a `Cascade<V>`, so the core reads it unchanged.
+ *
+ * The value type accumulates as layers are added, so a rota of two names
+ * answers `"alice" | "bob" | undefined` rather than `string` — which is what
+ * makes an exhaustive switch over who is on call actually exhaustive. Ask for
+ * `rota<string>()` when the names are not known up front.
+ */
+import { type Cascade } from "./cascade.js";
+import { type PlainRule } from "./plain-forms.js";
+import type { ValuedStream } from "./valued-stream.js";
+/** Who or what holds when, and the questions worth asking about that. */
+export interface Rota<V> extends Cascade<V> {
+    /** These times belong to this one, unless something later says otherwise. */
+    readonly assign: <const W>(scope: PlainRule, value: W) => Rota<V | W>;
+    /**
+     * A swap: this day goes to this one instead.
+     *
+     * The same thing as an `assign` naming a single day — it exists because
+     * "Carol is swapping the eleventh" is what happened, and a rota reads better
+     * when the exceptions say they are exceptions.
+     */
+    readonly swap: <const W>(day: PlainRule, value: W) => Rota<V | W>;
+    /** Who is on at that moment, or `undefined` if nobody is. */
+    readonly whoIsOn: (at: Temporal.ZonedDateTime) => V | undefined;
+    /**
+     * Each stretch between two moments, and who has it.
+     *
+     * Leave `to` out for an endless run of them, which is lazy and safe to stop
+     * pulling from whenever you have enough.
+     */
+    readonly shifts: (from: Temporal.ZonedDateTime, to?: Temporal.ZonedDateTime) => ValuedStream<V>;
+}
+/**
+ * An empty rota: nobody is on until something says they are.
+ *
+ * ```ts
+ * const onCall = rota()
+ *   .assign(weekdays(), "alice")
+ *   .assign(weekends(), "bob")
+ *   .swap("2026-03-11", "carol");
+ * ```
+ */
+export declare function rota<V = never>(): Rota<V>;
+//# sourceMappingURL=rota.d.ts.map

package/dist/rota.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rota.d.ts","sourceRoot":"","sources":["../src/rota.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAqB,MAAM,cAAc,CAAC;AAE/D,OAAO,EAAU,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAG1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,yEAAyE;AACzE,MAAM,WAAW,IAAI,CAAC,CAAC,CAAE,SAAQ,OAAO,CAAC,CAAC,CAAC;IACzC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAEtE;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAElE,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,QAAQ,CAAC,aAAa,KAAK,CAAC,GAAG,SAAS,CAAC;IAEhE;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,CACf,IAAI,EAAE,QAAQ,CAAC,aAAa,EAC5B,EAAE,CAAC,EAAE,QAAQ,CAAC,aAAa,KACxB,YAAY,CAAC,CAAC,CAAC,CAAC;CACtB;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,CAAC,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,CAEzC"}

package/dist/rota.js

@@ -0,0 +1,47 @@
+/**
+ * Who is on, in the words people use for that.
+ *
+ * The same machinery as a [schedule](./schedule.ts) with the value left open:
+ * a rota assigns a person, a tariff assigns a rate, a roster assigns how many
+ * are working. A `Rota<V>` is a `Cascade<V>`, so the core reads it unchanged.
+ *
+ * The value type accumulates as layers are added, so a rota of two names
+ * answers `"alice" | "bob" | undefined` rather than `string` — which is what
+ * makes an exhaustive switch over who is on call actually exhaustive. Ask for
+ * `rota<string>()` when the names are not known up front.
+ */
+import { layer } from "./cascade.js";
+import { asDays } from "./plain-forms.js";
+import { resolve } from "./resolve.js";
+import { take } from "./stream.js";
+function build(layers) {
+    const self = {
+        type: "cascade",
+        layers,
+        assign: (scope, value) => build([...layers, layer(asDays(scope), value)]),
+        swap: (day, value) => build([...layers, layer(asDays(day), value)]),
+        whoIsOn: (at) => {
+            // The smallest window there is, so this terminates whatever the layers
+            // say — the same trick `activeAt` uses on a rule.
+            const moment = { from: at, to: at.add({ nanoseconds: 1 }) };
+            const [now] = take(resolve(self, moment), 1);
+            return now?.value;
+        },
+        shifts: (from, to) => resolve(self, to === undefined ? { from } : { from, to }),
+    };
+    return self;
+}
+/**
+ * An empty rota: nobody is on until something says they are.
+ *
+ * ```ts
+ * const onCall = rota()
+ *   .assign(weekdays(), "alice")
+ *   .assign(weekends(), "bob")
+ *   .swap("2026-03-11", "carol");
+ * ```
+ */
+export function rota() {
+    return build([]);
+}
+//# sourceMappingURL=rota.js.map

package/dist/rota.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rota.js","sourceRoot":"","sources":["../src/rota.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAA4B,KAAK,EAAE,MAAM,cAAc,CAAC;AAE/D,OAAO,EAAE,MAAM,EAAkB,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAgCnC,SAAS,KAAK,CAAI,MAA2B;IAC3C,MAAM,IAAI,GAAY;QACpB,IAAI,EAAE,SAAS;QACf,MAAM;QAEN,MAAM,EAAE,CAAI,KAAgB,EAAE,KAAQ,EAAE,EAAE,CACxC,KAAK,CAAQ,CAAC,GAAG,MAAM,EAAE,KAAK,CAAQ,MAAM,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;QAE/D,IAAI,EAAE,CAAI,GAAc,EAAE,KAAQ,EAAE,EAAE,CACpC,KAAK,CAAQ,CAAC,GAAG,MAAM,EAAE,KAAK,CAAQ,MAAM,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;QAE7D,OAAO,EAAE,CAAC,EAAE,EAAE,EAAE;YACd,uEAAuE;YACvE,kDAAkD;YAClD,MAAM,MAAM,GAAY,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;YACrE,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;YAC7C,OAAO,GAAG,EAAE,KAAK,CAAC;QACpB,CAAC;QAED,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CACnB,OAAO,CAAC,IAAI,EAAE,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;KAC5D,CAAC;IAEF,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,IAAI;IAClB,OAAO,KAAK,CAAI,EAAE,CAAC,CAAC;AACtB,CAAC"}

package/dist/rule.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The rule language, as data.
+ *
+ * A rule is a plain JSON value with a `type` tag — not an object with methods.
+ * That is what makes storing one, sending one over a wire, and validating one
+ * cost nothing: the document *is* the rule. It also means a new operation over
+ * rules is a new function rather than a new method on every rule type, which
+ * matters because there are many operations coming — evaluating, describing,
+ * validating, rendering, diffing — and comparatively few rule types.
+ */
+export declare const WEEKDAYS: readonly ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"];
+export type Weekday = (typeof WEEKDAYS)[number];
+/**
+ * A rule says *when*, and nothing else. It is boolean: the times it covers and
+ * the times it does not.
+ *
+ * Values — who is on call, what the tariff is — attach to layers rather than to
+ * rules, which is what keeps `not` meaningful and the set algebra simple.
+ */
+export type Rule = AlwaysRule | NeverRule | DaysOfWeekRule | TimeOfDayRule | DatesRule | AllRule | AnyRule | NotRule;
+/** All time. The identity for intersection. */
+export interface AlwaysRule {
+    readonly type: "always";
+}
+/** No time at all. The identity for union. */
+export interface NeverRule {
+    readonly type: "never";
+}
+/** Whole days, by their day of the week. */
+export interface DaysOfWeekRule {
+    readonly type: "daysOfWeek";
+    readonly days: readonly Weekday[];
+    /** Overrides the context's zone, for a rule about a particular place. */
+    readonly zone?: string;
+}
+/**
+ * A window within each day, as wall-clock times: `"09:00"` to `"17:00"`.
+ *
+ * Wall clock is what people write and what schedules mean. Across a daylight
+ * saving transition the elapsed length of the window changes and the clock
+ * times do not, which is the right way round.
+ *
+ * A `to` earlier than `from` wraps past midnight, so `"22:00"` to `"06:00"` is
+ * a night shift rather than nothing.
+ */
+export interface TimeOfDayRule {
+    readonly type: "timeOfDay";
+    readonly from: string;
+    readonly to: string;
+    readonly zone?: string;
+}
+/** Whole days, by date: `"2026-03-14"`. */
+export interface DatesRule {
+    readonly type: "dates";
+    readonly dates: readonly string[];
+    readonly zone?: string;
+}
+/** Every rule must hold: intersection. */
+export interface AllRule {
+    readonly type: "all";
+    readonly rules: readonly Rule[];
+}
+/** At least one rule must hold: union. */
+export interface AnyRule {
+    readonly type: "any";
+    readonly rules: readonly Rule[];
+}
+/** The times a rule does not hold: complement. */
+export interface NotRule {
+    readonly type: "not";
+    readonly rule: Rule;
+}
+//# sourceMappingURL=rule.d.ts.map

package/dist/rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule.d.ts","sourceRoot":"","sources":["../src/rule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAO,MAAM,QAAQ,YACnB,QAAQ,EACR,SAAS,EACT,WAAW,EACX,UAAU,EACV,QAAQ,EACR,UAAU,EACV,QAAQ,CACA,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,MAAM,IAAI,GACZ,UAAU,GACV,SAAS,GACT,cAAc,GACd,aAAa,GACb,SAAS,GACT,OAAO,GACP,OAAO,GACP,OAAO,CAAC;AAEZ,+CAA+C;AAC/C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB;AAED,8CAA8C;AAC9C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;IAClC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,2CAA2C;AAC3C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,0CAA0C;AAC1C,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;CACjC;AAED,0CAA0C;AAC1C,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;CACjC;AAED,kDAAkD;AAClD,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB"}

package/dist/rule.js

@@ -0,0 +1,20 @@
+/**
+ * The rule language, as data.
+ *
+ * A rule is a plain JSON value with a `type` tag — not an object with methods.
+ * That is what makes storing one, sending one over a wire, and validating one
+ * cost nothing: the document *is* the rule. It also means a new operation over
+ * rules is a new function rather than a new method on every rule type, which
+ * matters because there are many operations coming — evaluating, describing,
+ * validating, rendering, diffing — and comparatively few rule types.
+ */
+export const WEEKDAYS = [
+    "monday",
+    "tuesday",
+    "wednesday",
+    "thursday",
+    "friday",
+    "saturday",
+    "sunday",
+];
+//# sourceMappingURL=rule.js.map

package/dist/rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule.js","sourceRoot":"","sources":["../src/rule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,QAAQ;IACR,SAAS;IACT,WAAW;IACX,UAAU;IACV,QAAQ;IACR,UAAU;IACV,QAAQ;CACA,CAAC"}

package/dist/schedule.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Opening hours, in the words people use for them.
+ *
+ * Everything here is a cascade underneath, and a `Schedule` *is* one — the
+ * same trick the rule builders use, so it serialises to the same document and
+ * `resolve` reads it unchanged. What this adds is vocabulary: nobody running a
+ * warehouse says "add a layer to the cascade", they say we are open weekdays,
+ * closed on bank holidays, and on the eleventh we close at three.
+ *
+ * Those three read in the order they are said, and each one outranks what came
+ * before it — which is the same precedence a cascade has, arrived at by
+ * writing the sentence in the obvious order rather than by knowing the rule.
+ */
+import { type Cascade } from "./cascade.js";
+import { type Interval } from "./interval.js";
+import { type PlainRule } from "./plain-forms.js";
+/**
+ * When something is open, and the questions worth asking about that.
+ *
+ * A `Schedule` is a `Cascade<boolean>`, so anything that takes a cascade takes
+ * one of these. The methods below are the common half said plainly; the
+ * cascade underneath is the whole of it.
+ */
+export interface Schedule extends Cascade<boolean> {
+    /**
+     * Open during these times. With hours, inside them on those days; without,
+     * for the whole of them.
+     */
+    readonly open: (scope: PlainRule, hours?: PlainRule) => Schedule;
+    /** Closed for the whole of these times, whatever was said before. */
+    readonly closed: (scope: PlainRule) => Schedule;
+    /**
+     * The hours on this day, in place of whatever was said before.
+     *
+     * Instead of, not as well as: the usual hours do not show through the part
+     * this leaves out, which is what "we close early on the eleventh" means and
+     * what makes it different from being shut between three and five.
+     */
+    readonly hoursOn: (day: PlainRule, hours: PlainRule) => Schedule;
+    /** Whether it is open at that moment. */
+    readonly isOpen: (at: Temporal.ZonedDateTime) => boolean;
+    /**
+     * The next stretch it is open, at or after a moment, or `undefined` if there
+     * is none within `within` of it.
+     *
+     * `within` bounds how far to look and not what is found: a stretch that
+     * starts inside the horizon is returned whole, ending when it really closes
+     * rather than where the search stopped. That differs from `next` on a rule,
+     * which clips its answer to the window it was given.
+     *
+     * A schedule that is never open has no answer to give and no way to discover
+     * that, so pass `within` when that is a possibility.
+     */
+    readonly opensNext: (at: Temporal.ZonedDateTime, within?: Temporal.Duration) => Interval | undefined;
+    /** How long it is open between two moments. */
+    readonly openBetween: (from: Temporal.ZonedDateTime, to: Temporal.ZonedDateTime) => Temporal.Duration;
+}
+/**
+ * An empty schedule: open for nothing until something says otherwise.
+ *
+ * ```ts
+ * const openingHours = schedule()
+ *   .open(weekdays(), "09:00-17:00")
+ *   .closed("2026-12-25")
+ *   .hoursOn("2026-03-11", "09:00-15:00");
+ * ```
+ */
+export declare function schedule(): Schedule;
+//# sourceMappingURL=schedule.d.ts.map

package/dist/schedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.d.ts","sourceRoot":"","sources":["../src/schedule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,KAAK,OAAO,EAA8B,MAAM,cAAc,CAAC;AAExE,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAOnE;;;;;;GAMG;AACH,MAAM,WAAW,QAAS,SAAQ,OAAO,CAAC,OAAO,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,SAAS,KAAK,QAAQ,CAAC;IAEjE,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,QAAQ,CAAC;IAEhD;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,QAAQ,CAAC;IAEjE,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,QAAQ,CAAC,aAAa,KAAK,OAAO,CAAC;IAEzD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,SAAS,EAAE,CAClB,EAAE,EAAE,QAAQ,CAAC,aAAa,EAC1B,MAAM,CAAC,EAAE,QAAQ,CAAC,QAAQ,KACvB,QAAQ,GAAG,SAAS,CAAC;IAE1B,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,CACpB,IAAI,EAAE,QAAQ,CAAC,aAAa,EAC5B,EAAE,EAAE,QAAQ,CAAC,aAAa,KACvB,QAAQ,CAAC,QAAQ,CAAC;CACxB;AA+DD;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,IAAI,QAAQ,CAEnC"}