@kensio/quando 0.1.0 → 1.0.0

package/dist/valued-stream.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Streams of intervals that carry values, and the operations resolution needs
+ * over them.
+ *
+ * The same shape as `interval-stream.ts` one level down, and deliberately
+ * separate from it. Those sweeps are set algebra over *when*, and nothing in
+ * them has an opinion about values. {@link overlay} is where an opinion is
+ * needed, and it is handed one rather than choosing.
+ */
+import type { Valued } from "./cascade.js";
+import type { Merge } from "./merge.js";
+/**
+ * A lazy sequence of valued intervals.
+ *
+ * Same contract as `IntervalStream` — ascending by start, non-overlapping,
+ * coalesced — with one addition: touching intervals carrying the same value
+ * are merged, so where two intervals do touch, the values on either side of
+ * the boundary differ.
+ */
+export type ValuedStream<V> = Iterable<Valued<V>>;
+/**
+ * Two streams laid over one another, with `merge` settling the overlap.
+ *
+ * Where only one covers a moment, its value comes through. Where both do, the
+ * two values go to `merge`, `under` first. Where neither does, the moment is
+ * absent, the same as everywhere else in the library.
+ *
+ * It walks both fronts and cuts whichever runs on at the other's boundary, so
+ * it pulls only as far as the next piece of the answer and stays lazy over
+ * endless sources.
+ *
+ * Output is not coalesced. Cutting at every boundary splits runs carrying the
+ * same value on both sides, and {@link coalesce} over the top puts them back.
+ * Teaching this sweep to look ahead instead would buy nothing.
+ */
+export declare function overlay<V>(under: ValuedStream<V>, over: ValuedStream<V>, merge: Merge<V>): ValuedStream<V>;
+/**
+ * Adjacent intervals carrying the same value are one interval.
+ *
+ * Without this, a run that happens to be split across two layers comes back as
+ * two touching intervals with equal values — the same assignment said twice,
+ * and a stream that no longer satisfies the coalesced contract the rest of the
+ * library keeps.
+ *
+ * Sameness is `Object.is`, so primitives and shared references merge while
+ * structurally-equal objects do not. That is the conservative way round: it
+ * splits an interval that could have been merged rather than merging two the
+ * caller meant to keep apart.
+ */
+export declare function coalesce<V>(source: ValuedStream<V>): ValuedStream<V>;
+//# sourceMappingURL=valued-stream.d.ts.map

package/dist/valued-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"valued-stream.d.ts","sourceRoot":"","sources":["../src/valued-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGxC;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AACH,wBAAiB,OAAO,CAAC,CAAC,EACxB,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EACtB,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,EACrB,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GACd,YAAY,CAAC,CAAC,CAAC,CAsDjB;AA+CD;;;;;;;;;;;;GAYG;AACH,wBAAiB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAmBrE"}

package/dist/valued-stream.js

@@ -0,0 +1,148 @@
+/**
+ * Streams of intervals that carry values, and the operations resolution needs
+ * over them.
+ *
+ * The same shape as `interval-stream.ts` one level down, and deliberately
+ * separate from it. Those sweeps are set algebra over *when*, and nothing in
+ * them has an opinion about values. {@link overlay} is where an opinion is
+ * needed, and it is handed one rather than choosing.
+ */
+import { compareEnds, compareStarts, earlierEnd } from "./interval.js";
+import { peekable } from "./stream.js";
+/**
+ * Two streams laid over one another, with `merge` settling the overlap.
+ *
+ * Where only one covers a moment, its value comes through. Where both do, the
+ * two values go to `merge`, `under` first. Where neither does, the moment is
+ * absent, the same as everywhere else in the library.
+ *
+ * It walks both fronts and cuts whichever runs on at the other's boundary, so
+ * it pulls only as far as the next piece of the answer and stays lazy over
+ * endless sources.
+ *
+ * Output is not coalesced. Cutting at every boundary splits runs carrying the
+ * same value on both sides, and {@link coalesce} over the top puts them back.
+ * Teaching this sweep to look ahead instead would buy nothing.
+ */
+export function* overlay(under, over, merge) {
+    const a = peekable(under);
+    const b = peekable(over);
+    // What is left of each front interval. A stretch already yielded is cut off
+    // the front rather than yielded twice, which is what keeps this to one pass
+    // over sources that can only be read forwards.
+    let restA = a.peek();
+    let restB = b.peek();
+    for (;;) {
+        if (restA === undefined || restB === undefined) {
+            yield* remainder(restA ?? restB, restA === undefined ? b : a);
+            return;
+        }
+        const order = compareStarts(restA.start, restB.start);
+        if (order === 0) {
+            // Both cover the stretch up to whichever ends first, and that stretch is
+            // the only place `merge` is ever called.
+            const end = earlierEnd(restA.end, restB.end);
+            yield { start: restA.start, end, value: merge(restA.value, restB.value) };
+            const cutA = cut(restA, end, a);
+            restB = cut(restB, end, b);
+            restA = cutA;
+            continue;
+        }
+        // One of them starts first and holds alone until the other begins. Its own
+        // end may come first, in which case the whole of it stands alone.
+        if (order < 0) {
+            const boundary = restB.start;
+            if (compareEnds(restA.end, boundary) <= 0) {
+                yield restA;
+                a.drop();
+                restA = a.peek();
+                continue;
+            }
+            yield { start: restA.start, end: boundary, value: restA.value };
+            restA = { ...restA, start: boundary };
+            continue;
+        }
+        const boundary = restA.start;
+        if (compareEnds(restB.end, boundary) <= 0) {
+            yield restB;
+            b.drop();
+            restB = b.peek();
+            continue;
+        }
+        yield { start: restB.start, end: boundary, value: restB.value };
+        restB = { ...restB, start: boundary };
+    }
+}
+/**
+ * Whatever is left of one side once the other is spent, beginning with the
+ * piece already in hand.
+ *
+ * That piece may have been cut short, so it is yielded from the local rather
+ * than read again from the source, and the source's own copy of it dropped.
+ */
+function* remainder(held, source) {
+    if (held === undefined) {
+        return;
+    }
+    yield held;
+    source.drop();
+    for (;;) {
+        const next = source.peek();
+        if (next === undefined) {
+            return;
+        }
+        source.drop();
+        yield next;
+    }
+}
+/**
+ * What is left of an interval once the stretch up to `end` has been yielded.
+ *
+ * An interval used up entirely is dropped and the next one pulled, so the
+ * front always holds something still to yield.
+ */
+function cut(interval, end, source) {
+    if (end === undefined || compareEnds(interval.end, end) <= 0) {
+        source.drop();
+        return source.peek();
+    }
+    return { ...interval, start: end };
+}
+/**
+ * Adjacent intervals carrying the same value are one interval.
+ *
+ * Without this, a run that happens to be split across two layers comes back as
+ * two touching intervals with equal values — the same assignment said twice,
+ * and a stream that no longer satisfies the coalesced contract the rest of the
+ * library keeps.
+ *
+ * Sameness is `Object.is`, so primitives and shared references merge while
+ * structurally-equal objects do not. That is the conservative way round: it
+ * splits an interval that could have been merged rather than merging two the
+ * caller meant to keep apart.
+ */
+export function* coalesce(source) {
+    let open;
+    for (const next of source) {
+        if (open === undefined) {
+            open = next;
+            continue;
+        }
+        if (Object.is(open.value, next.value) && touches(open, next)) {
+            open = { ...open, end: next.end };
+            continue;
+        }
+        yield open;
+        open = next;
+    }
+    if (open !== undefined) {
+        yield open;
+    }
+}
+/** Whether one interval ends exactly where the next begins. */
+function touches(open, next) {
+    return (open.end !== undefined &&
+        next.start !== undefined &&
+        Temporal.ZonedDateTime.compare(open.end, next.start) === 0);
+}
+//# sourceMappingURL=valued-stream.js.map

package/dist/valued-stream.js.map

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

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@kensio/quando",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Declarative temporal rules for schedules, deadlines, constraints, and exceptions",
-  "repository": "https://github.com/KensioSoftware/quando",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KensioSoftware/quando"
+  },
   "homepage": "https://quandojs.dev",
   "bugs": "https://github.com/KensioSoftware/quando/issues",
   "main": "./dist/index.js",
@@ -23,25 +26,11 @@
   "imports": {
     "#test/*": "./test/*"
   },
-  "packageManager": "pnpm@11.21.0+sha512.521705bce689924eac72f5a3587122f362689ef6571e55ba80076fd637c11132ecffada26fad4ea79c485bfddbfd3d5a2a5b05805a77e893de71ec8a6cca3bb1",
   "engines": {
     "node": ">=26.0.0"
   },
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json",
-    "prepack": "pnpm build",
-    "build:check": "tsc -p tsconfig.json --noEmit",
-    "fmt": "oxlint --fix . && oxfmt .",
-    "lint": "oxlint . && oxfmt --check .",
-    "lint:ci": "oxlint --format=github . && oxfmt --check .",
-    "docs:check": "./scripts/sh/docs-check.sh",
-    "fta": "./scripts/sh/fta.sh",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "pack:check": "./scripts/sh/pack-check.sh",
-    "check": "pnpm fmt && pnpm docs:check && pnpm fta && pnpm build:check && pnpm pack:check && pnpm test:coverage"
-  },
   "devDependencies": {
+    "@faker-js/faker": "^10.6.0",
     "@kensio/smartass": "^1.33.0",
     "@semantic-release/exec": "7.1.0",
     "@types/node": "^26.0.0",
@@ -49,7 +38,7 @@
     "@vitest/coverage-v8": "^4.1.10",
     "conventional-changelog-conventionalcommits": "9.3.1",
     "fta-cli": "^3.0.0",
-    "oxfmt": "^0.62.0",
+    "oxfmt": "^0.65.0",
     "oxlint": "^1.77.0",
     "oxlint-tsgolint": "^7.0.2001",
     "semantic-release": "25.0.9",
@@ -67,5 +56,18 @@
   },
   "author": "Kensio Software",
   "license": "Apache-2.0",
-  "type": "module"
-}
+  "type": "module",
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "build:check": "tsc -p tsconfig.json --noEmit",
+    "fmt": "oxlint --fix . && oxfmt .",
+    "lint": "oxlint . && oxfmt --check .",
+    "lint:ci": "oxlint --format=github . && oxfmt --check .",
+    "docs:check": "./scripts/sh/docs-check.sh",
+    "fta": "./scripts/sh/fta.sh",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "pack:check": "./scripts/sh/pack-check.sh",
+    "check": "pnpm fmt && pnpm docs:check && pnpm fta && pnpm build:check && pnpm pack:check && pnpm test:coverage"
+  }
+}