@libraz/libcantus 1.0.0 → 1.1.0

package/dist/chunk-7GOKQJTQ.js

@@ -0,0 +1,145 @@
+import {
+  BEAT_EPS,
+  assertFiniteNumber,
+  assertNoteEvents,
+  assertOptions
+} from "./chunk-PQL7E5F6.js";
+
+// src/core/event-index/index.ts
+function upperBound(values, beat) {
+  let low = 0;
+  let high = values.length;
+  while (low < high) {
+    const middle = Math.floor((low + high) / 2);
+    if ((values[middle]?.note.startBeat ?? Number.POSITIVE_INFINITY) <= beat) {
+      low = middle + 1;
+    } else {
+      high = middle;
+    }
+  }
+  return low;
+}
+function sortedNoteEvents(events) {
+  const sorted = events.map((note) => ({ ...note }));
+  sorted.sort((a, b) => a.startBeat - b.startBeat);
+  return sorted;
+}
+function createNoteEventIndex(events, options = {}) {
+  const asked = assertOptions(options, "options");
+  assertNoteEvents(events, asked.name ?? "note events", asked);
+  const tieBreak = asked.tieBreak ?? "highest";
+  const notes = Object.freeze(
+    events.map(
+      (note, originalIndex) => Object.freeze({
+        note: Object.freeze({ ...note }),
+        originalIndex,
+        endBeat: note.startBeat + note.durationBeat
+      })
+    ).sort((a, b) => a.note.startBeat - b.note.startBeat || a.originalIndex - b.originalIndex)
+  );
+  let maxEndTree;
+  let treeSize = 0;
+  const endTree = () => {
+    if (maxEndTree !== void 0) {
+      return maxEndTree;
+    }
+    treeSize = 1;
+    while (treeSize < notes.length) treeSize *= 2;
+    const tree = new Array(treeSize * 2).fill(Number.NEGATIVE_INFINITY);
+    for (let index = 0; index < notes.length; index += 1) {
+      tree[treeSize + index] = notes[index]?.endBeat ?? Number.NEGATIVE_INFINITY;
+    }
+    for (let index = treeSize - 1; index > 0; index -= 1) {
+      tree[index] = Math.max(
+        tree[index * 2] ?? Number.NEGATIVE_INFINITY,
+        tree[index * 2 + 1] ?? Number.NEGATIVE_INFINITY
+      );
+    }
+    maxEndTree = tree;
+    return tree;
+  };
+  const latestActiveIndex = (exclusive, beat) => {
+    const tree = endTree();
+    const find = (node, start, end) => {
+      if (start >= exclusive || (tree[node] ?? Number.NEGATIVE_INFINITY) <= beat + BEAT_EPS) {
+        return -1;
+      }
+      if (end - start === 1) return start < notes.length ? start : -1;
+      const mid = Math.floor((start + end) / 2);
+      const right = find(node * 2 + 1, mid, end);
+      return right >= 0 ? right : find(node * 2, start, mid);
+    };
+    return find(1, 0, treeSize);
+  };
+  return {
+    notes,
+    at(beat) {
+      assertFiniteNumber(beat, "beat");
+      const index = latestActiveIndex(upperBound(notes, beat + BEAT_EPS), beat);
+      if (index < 0) return void 0;
+      const onset = notes[index]?.note.startBeat;
+      let best;
+      for (let candidateIndex = index; candidateIndex >= 0; candidateIndex -= 1) {
+        const indexed = notes[candidateIndex];
+        if (indexed !== void 0 && indexed.note.startBeat !== onset) break;
+        if (indexed === void 0 || indexed.note.durationBeat <= 0 || indexed.note.startBeat - BEAT_EPS > beat || beat >= indexed.endBeat - BEAT_EPS) {
+          continue;
+        }
+        if (best === void 0) {
+          best = indexed;
+          continue;
+        }
+        if (tieBreak === "last") continue;
+        const difference = indexed.note.pitch - best.note.pitch;
+        const wins = difference === 0 ? indexed.originalIndex < best.originalIndex : difference > 0 === (tieBreak === "highest");
+        if (wins) {
+          best = indexed;
+        }
+      }
+      return best;
+    },
+    attacksAt(beat) {
+      assertFiniteNumber(beat, "beat");
+      let index = upperBound(notes, beat + BEAT_EPS) - 1;
+      while (index >= 0) {
+        const candidate = notes[index];
+        if (candidate === void 0 || Math.abs(candidate.note.startBeat - beat) >= BEAT_EPS) {
+          return false;
+        }
+        if (candidate.note.durationBeat > 0) {
+          return true;
+        }
+        index -= 1;
+      }
+      return false;
+    },
+    onsetsBetween(startBeat, endBeat) {
+      assertFiniteNumber(startBeat, "startBeat");
+      assertFiniteNumber(endBeat, "endBeat");
+      const result = [];
+      let index = upperBound(notes, startBeat + BEAT_EPS);
+      while (index < notes.length) {
+        const indexed = notes[index];
+        const onset = indexed?.note.startBeat;
+        if (indexed === void 0 || onset === void 0 || onset >= endBeat - BEAT_EPS) {
+          break;
+        }
+        index += 1;
+        if (indexed.note.durationBeat <= 0) {
+          continue;
+        }
+        const previous = result[result.length - 1];
+        if (previous === void 0 || Math.abs(previous - onset) >= BEAT_EPS) {
+          result.push(onset);
+        }
+      }
+      return result;
+    }
+  };
+}
+
+export {
+  sortedNoteEvents,
+  createNoteEventIndex
+};
+//# sourceMappingURL=chunk-7GOKQJTQ.js.map

package/dist/chunk-7GOKQJTQ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/event-index/index.ts"],"sourcesContent":["import { BEAT_EPS } from '../meter/internal.js';\nimport type { NoteEvent } from '../types.js';\nimport { assertFiniteNumber, assertNoteEvents, assertOptions } from '../validation/index.js';\n\n/**\n * A validated note retaining its position in the caller's original array.\n *\n * @category Core\n */\nexport type IndexedNoteEvent = {\n  readonly note: Readonly<NoteEvent>;\n  readonly originalIndex: number;\n  readonly endBeat: number;\n};\n\n/**\n * Which note wins when several sound from the same onset.\n *\n * `'highest'` and `'lowest'` name a voice, so the answer does not depend on the\n * order the caller happened to store the chord in; `'last'` takes the one\n * latest in the input array. Two notes of the same pitch name no voice apart,\n * so both voice tie-breaks settle a unison on the lower `originalIndex` and\n * name the same note.\n *\n * @category Core\n */\nexport type OnsetTieBreak = 'highest' | 'lowest' | 'last';\n\n/**\n * Binary-searchable, stable-sorted index over note onsets and active spans.\n *\n * @category Core\n */\nexport type NoteEventIndex = {\n  notes: readonly IndexedNoteEvent[];\n  /**\n   * Latest-onset note sounding at `beat`. Simultaneous onsets are resolved by\n   * the index's {@link OnsetTieBreak}.\n   *\n   * @throws If `beat` is not finite.\n   */\n  at: (beat: number) => IndexedNoteEvent | undefined;\n  /**\n   * Whether one or more sounding notes attack at `beat`.\n   *\n   * @throws If `beat` is not finite.\n   */\n  attacksAt: (beat: number) => boolean;\n  /**\n   * Unique sounding-note attack beats strictly inside `(startBeat, endBeat)`.\n   *\n   * @throws If either bound is not finite.\n   */\n  onsetsBetween: (startBeat: number, endBeat: number) => number[];\n};\n\nfunction upperBound(values: readonly IndexedNoteEvent[], beat: number): number {\n  let low = 0;\n  let high = values.length;\n  while (low < high) {\n    const middle = Math.floor((low + high) / 2);\n    if ((values[middle]?.note.startBeat ?? Number.POSITIVE_INFINITY) <= beat) {\n      low = middle + 1;\n    } else {\n      high = middle;\n    }\n  }\n  return low;\n}\n\n/**\n * Copy note events and put them in stable onset order.\n *\n * The order is the one {@link createNoteEventIndex} numbers its notes in, so a\n * pass may read the sequence here and the index there and see the same notes in\n * the same places. What it does not build is the index itself: a caller that\n * only walks the notes in time order would otherwise pay for a segment tree and\n * a wrapper per note that it never queries.\n *\n * The events are copied, so the sequence is the caller's own and two entries\n * that arrived as one shared object stay two.\n *\n * @param events The events to order; already validated by the caller.\n * @returns The copies, earliest onset first, ties in input order.\n */\nexport function sortedNoteEvents(events: readonly NoteEvent[]): NoteEvent[] {\n  const sorted = events.map((note) => ({ ...note }));\n  // Array sort is stable, so events sharing an onset keep the order they were\n  // given in — the tie-break the index spells out as `originalIndex`.\n  sorted.sort((a, b) => a.startBeat - b.startBeat);\n  return sorted;\n}\n\n/**\n * How an index reads the events it is built from.\n *\n * @category Core\n */\nexport type NoteEventIndexOptions = {\n  allowNonPositiveDuration?: boolean;\n  tieBreak?: OnsetTieBreak;\n  budget?: number;\n  /** What the events are, for the validation error message. */\n  name?: string;\n};\n\n/**\n * Validate and stable-sort note events once, then expose onset and active-note\n * lookups that cost `O(log n + k)`, where `k` is how many notes share the onset\n * the answer comes from. Non-positive-duration notes may be retained for\n * callers that intentionally filter them later, but never count as sounding.\n *\n * @category Core\n */\nexport function createNoteEventIndex(\n  events: readonly NoteEvent[],\n  options: NoteEventIndexOptions = {},\n): NoteEventIndex {\n  const asked = assertOptions(options, 'options');\n  assertNoteEvents(events, asked.name ?? 'note events', asked);\n  const tieBreak = asked.tieBreak ?? 'highest';\n  // Each wrapper is frozen, not only the array and the note inside it: `endBeat`\n  // is what the active-note search is built from, so a host that writes to it\n  // would leave the index answering from a span nothing else knows about.\n  const notes = Object.freeze(\n    events\n      .map((note, originalIndex) =>\n        Object.freeze({\n          note: Object.freeze({ ...note }),\n          originalIndex,\n          endBeat: note.startBeat + note.durationBeat,\n        }),\n      )\n      .sort((a, b) => a.note.startBeat - b.note.startBeat || a.originalIndex - b.originalIndex),\n  );\n  // Segment-tree maxima find the latest active onset in logarithmic time even\n  // when an early, very long note would defeat a prefix-max backwards scan.\n  //\n  // It is built on the first `at` query rather than on construction: the onset\n  // queries answer from the sorted notes alone, so a caller that never asks\n  // which note is sounding would otherwise pay for a structure it never reads.\n  let maxEndTree: number[] | undefined;\n  let treeSize = 0;\n  const endTree = (): number[] => {\n    if (maxEndTree !== undefined) {\n      return maxEndTree;\n    }\n    treeSize = 1;\n    while (treeSize < notes.length) treeSize *= 2;\n    const tree = new Array<number>(treeSize * 2).fill(Number.NEGATIVE_INFINITY);\n    for (let index = 0; index < notes.length; index += 1) {\n      tree[treeSize + index] = notes[index]?.endBeat ?? Number.NEGATIVE_INFINITY;\n    }\n    for (let index = treeSize - 1; index > 0; index -= 1) {\n      tree[index] = Math.max(\n        tree[index * 2] ?? Number.NEGATIVE_INFINITY,\n        tree[index * 2 + 1] ?? Number.NEGATIVE_INFINITY,\n      );\n    }\n    maxEndTree = tree;\n    return tree;\n  };\n  const latestActiveIndex = (exclusive: number, beat: number): number => {\n    const tree = endTree();\n    const find = (node: number, start: number, end: number): number => {\n      if (start >= exclusive || (tree[node] ?? Number.NEGATIVE_INFINITY) <= beat + BEAT_EPS) {\n        return -1;\n      }\n      if (end - start === 1) return start < notes.length ? start : -1;\n      const mid = Math.floor((start + end) / 2);\n      const right = find(node * 2 + 1, mid, end);\n      return right >= 0 ? right : find(node * 2, start, mid);\n    };\n    return find(1, 0, treeSize);\n  };\n\n  return {\n    notes,\n    at(beat) {\n      // A query beat comes from wherever the host got it — a scrub position, a\n      // parsed field — so it is checked like any other entry argument. `NaN`\n      // compares false against every bound, which would read as an open window\n      // rather than as the missing value it is.\n      assertFiniteNumber(beat, 'beat');\n      const index = latestActiveIndex(upperBound(notes, beat + BEAT_EPS), beat);\n      if (index < 0) return undefined;\n      const onset = notes[index]?.note.startBeat;\n      let best: IndexedNoteEvent | undefined;\n      for (let candidateIndex = index; candidateIndex >= 0; candidateIndex -= 1) {\n        const indexed = notes[candidateIndex];\n        if (indexed !== undefined && indexed.note.startBeat !== onset) break;\n        if (\n          indexed === undefined ||\n          indexed.note.durationBeat <= 0 ||\n          indexed.note.startBeat - BEAT_EPS > beat ||\n          beat >= indexed.endBeat - BEAT_EPS\n        ) {\n          continue;\n        }\n        if (best === undefined) {\n          best = indexed;\n          continue;\n        }\n        if (tieBreak === 'last') continue;\n        const difference = indexed.note.pitch - best.note.pitch;\n        // Equal pitches name no voice apart, so they are settled on the lower\n        // original index rather than on whichever end of the array the scan\n        // happens to reach last — otherwise `'highest'` and `'lowest'` would\n        // answer a unison differently.\n        const wins =\n          difference === 0\n            ? indexed.originalIndex < best.originalIndex\n            : difference > 0 === (tieBreak === 'highest');\n        if (wins) {\n          best = indexed;\n        }\n      }\n      return best;\n    },\n    attacksAt(beat) {\n      assertFiniteNumber(beat, 'beat');\n      // Only a sounding note attacks: a zero-length artefact must not make\n      // `attacksAt(b)` true on a beat where `at(b)` finds nothing.\n      let index = upperBound(notes, beat + BEAT_EPS) - 1;\n      while (index >= 0) {\n        const candidate = notes[index];\n        if (candidate === undefined || Math.abs(candidate.note.startBeat - beat) >= BEAT_EPS) {\n          return false;\n        }\n        if (candidate.note.durationBeat > 0) {\n          return true;\n        }\n        index -= 1;\n      }\n      return false;\n    },\n    onsetsBetween(startBeat, endBeat) {\n      assertFiniteNumber(startBeat, 'startBeat');\n      assertFiniteNumber(endBeat, 'endBeat');\n      const result: number[] = [];\n      let index = upperBound(notes, startBeat + BEAT_EPS);\n      while (index < notes.length) {\n        const indexed = notes[index];\n        const onset = indexed?.note.startBeat;\n        if (indexed === undefined || onset === undefined || onset >= endBeat - BEAT_EPS) {\n          break;\n        }\n        index += 1;\n        if (indexed.note.durationBeat <= 0) {\n          continue;\n        }\n        const previous = result[result.length - 1];\n        if (previous === undefined || Math.abs(previous - onset) >= BEAT_EPS) {\n          result.push(onset);\n        }\n      }\n      return result;\n    },\n  };\n}\n"],"mappings":"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","names":[]}