@libraz/libcantus 0.9.3 → 0.9.5

package/dist/core/index.d.ts

@@ -1,40 +1,154 @@
-import { N as NoteEvent } from '../types-MGP29r3t.js';
-export { K as KeyScale } from '../types-MGP29r3t.js';
-import { T as TimeSignature } from '../index-Cl7mhOFM.js';
-export { B as BarPosition, b as barPositionToBeat, a as beatToBarPosition, c as beatsPerBar, f as formatTimeSignature, i as isCompound, d as isStrongBeat, m as metricWeight, p as parseTimeSignature, e as pulsesPerBar, t as tuplet } from '../index-Cl7mhOFM.js';
-export { N as NoteData, S as SpelledInterval, f as formatNote, m as midiToNote, n as noteToMidi, a as noteToPitchClass, p as parseNote, s as spelledInterval } from '../index-CGMZNCx6.js';
+import { N as NoteEvent } from '../types-BN6_Q9Kl.js';
+export { K as KeyScale } from '../types-BN6_Q9Kl.js';
+import { T as TimeSignature } from '../index-DXd9JikN.js';
+export { B as BarPosition, b as barPositionToBeat, a as barPositionToPulse, c as beatToBarPosition, d as beatsPerBar, f as formatBarPosition, e as formatTimeSignature, i as isCompound, g as isStrongBeat, m as metricWeight, p as parseTimeSignature, h as pulseBeats, j as pulsesPerBar, t as tuplet } from '../index-DXd9JikN.js';
+export { I as IntervalQualityLabel, N as NoteData, S as SpelledInterval, d as diatonicLetterOf, f as formatNote, i as intervalSemitones, m as midiToNote, n as naturalPitchClassOf, a as noteToMidi, b as noteToPitchClass, p as parseInterval, c as parseNote, e as pitchClassOf, s as spelledInterval, t as transposeByInterval, g as transposeNote } from '../index-tR9jTn26.js';
 
-/** A validated note retaining its position in the caller's original array. */
+/**
+ * The library's error taxonomy.
+ *
+ * Every failure this library raises falls into one of three kinds, and the kind
+ * decides what a caller can do about it. Batch-voicing a lead sheet, for
+ * instance, has to tell "fix the input" apart from "loosen the constraints",
+ * and a message string is not a contract.
+ *
+ * The classes extend the built-in error types a caller would otherwise catch —
+ * a rejected argument is still a `RangeError` — so the `code` narrows an
+ * existing category rather than replacing it.
+ */
+/**
+ * What kind of failure an error reports.
+ *
+ * - `INVALID_INPUT`: an argument is malformed or out of range. The caller's
+ *   input must change.
+ * - `NO_SOLUTION`: the input is valid but nothing satisfies the constraints.
+ *   The constraints must change, or the failure must be accepted.
+ * - `BUDGET_EXCEEDED`: the requested work is larger than the synchronous
+ *   generation budget. The request must be smaller, or the budget larger.
+ *
+ * @category Core
+ */
+type LibcantusErrorCode = 'INVALID_INPUT' | 'NO_SOLUTION' | 'BUDGET_EXCEEDED';
+/**
+ * A rejected argument: malformed, out of range, or naming something unknown.
+ *
+ * @category Core
+ */
+declare class InvalidInputError extends RangeError {
+    readonly code: "INVALID_INPUT";
+    readonly name = "InvalidInputError";
+}
+/**
+ * A valid request with no answer: no voicing fits the given ranges, no chord
+ * matches the pitches, no preset claims the style.
+ *
+ * @category Core
+ */
+declare class NoSolutionError extends Error {
+    readonly code: "NO_SOLUTION";
+    readonly name = "NoSolutionError";
+    /**
+     * Where in a sequence the failure occurred, when the operation was working
+     * through one — the chord index of a progression, say.
+     */
+    readonly at: number | undefined;
+    constructor(message: string, options?: {
+        at?: number;
+    });
+}
+/**
+ * Work that would exceed the synchronous generation budget.
+ *
+ * @category Core
+ */
+declare class BudgetExceededError extends RangeError {
+    readonly code: "BUDGET_EXCEEDED";
+    readonly name = "BudgetExceededError";
+}
+/**
+ * Whether a caught value is one of this library's coded errors.
+ *
+ * @param value The caught value.
+ * @returns True when it carries a {@link LibcantusErrorCode}.
+ * @example
+ * ```ts
+ * import { isLibcantusError, voiceChord, parseChordSymbol } from '@libraz/libcantus';
+ * try {
+ *   voiceChord(parseChordSymbol('C'), { ranges: [] });
+ * } catch (error) {
+ *   if (isLibcantusError(error) && error.code === 'NO_SOLUTION') {
+ *     // loosen the constraints rather than blaming the input
+ *   }
+ * }
+ * ```
+ * @category Core
+ */
+declare function isLibcantusError(value: unknown): value is InvalidInputError | NoSolutionError | BudgetExceededError;
+
+/**
+ * A validated note retaining its position in the caller's original array.
+ *
+ * @category Core
+ */
 type IndexedNoteEvent = {
-    note: NoteEvent;
+    note: Readonly<NoteEvent>;
     originalIndex: number;
     endBeat: number;
 };
-/** Binary-searchable, stable-sorted index over note onsets and active spans. */
+/**
+ * Which note wins when several sound from the same onset.
+ *
+ * `'highest'` and `'lowest'` name a voice, so the answer does not depend on the
+ * order the caller happened to store the chord in; `'last'` takes the one
+ * latest in the input array.
+ *
+ * @category Core
+ */
+type OnsetTieBreak = 'highest' | 'lowest' | 'last';
+/**
+ * Binary-searchable, stable-sorted index over note onsets and active spans.
+ *
+ * @category Core
+ */
 type NoteEventIndex = {
-    notes: IndexedNoteEvent[];
-    /** Latest-onset note sounding at `beat`, with later input order winning ties. */
+    notes: readonly IndexedNoteEvent[];
+    /**
+     * Latest-onset note sounding at `beat`. Simultaneous onsets are resolved by
+     * the index's {@link OnsetTieBreak}.
+     */
     at: (beat: number) => IndexedNoteEvent | undefined;
-    /** Whether one or more notes attack at `beat`. */
+    /** Whether one or more sounding notes attack at `beat`. */
     attacksAt: (beat: number) => boolean;
-    /** Unique attack beats strictly inside `(startBeat, endBeat)`. */
+    /** Unique sounding-note attack beats strictly inside `(startBeat, endBeat)`. */
     onsetsBetween: (startBeat: number, endBeat: number) => number[];
 };
 /**
  * Validate and stable-sort note events once, then expose logarithmic onset and
  * active-note lookups. Non-positive-duration notes may be retained for callers
  * that intentionally filter them later, but never count as sounding.
+ *
+ * @category Core
  */
-declare function createNoteEventIndex(events: NoteEvent[], options?: {
+declare function createNoteEventIndex(events: readonly NoteEvent[], options?: {
     allowNonPositiveDuration?: boolean;
+    tieBreak?: OnsetTieBreak;
+    budget?: number;
+    /** What the events are, for the validation error message. */
+    name?: string;
 }): NoteEventIndex;
 
 /**
- * Counterpoint classification of a harmonic interval.
+ * Counterpoint classification of a harmonic interval by consonance.
+ *
+ * Distinct from a spelled interval's quality label — see
+ * {@link IntervalQualityLabel}, which names the `'P'` / `'M'` / `'m'` / `'A'` /
+ * `'d'` spelling of an interval rather than how it sounds against another
+ * voice.
  *
+ * @see {@link IntervalQualityLabel}
  * @category Pitch & Intervals
  */
-declare enum IntervalQuality {
+declare enum ConsonanceClass {
     PerfectConsonance = 0,
     ImperfectConsonance = 1,
     Dissonance = 2
@@ -52,16 +166,22 @@ declare enum IntervalQuality {
  * @returns The counterpoint quality of the interval.
  * @example
  * ```ts
- * import { classifyInterval, IntervalQuality } from '@libraz/libcantus';
- * classifyInterval(7); // IntervalQuality.PerfectConsonance
- * classifyInterval(5); // IntervalQuality.Dissonance (two-voice)
- * classifyInterval(5, false); // IntervalQuality.ImperfectConsonance
+ * import { classifyInterval, ConsonanceClass } from '@libraz/libcantus';
+ * classifyInterval(7); // ConsonanceClass.PerfectConsonance
+ * classifyInterval(5); // ConsonanceClass.Dissonance (two-voice)
+ * classifyInterval(5, false); // ConsonanceClass.ImperfectConsonance
  * ```
  * @category Pitch & Intervals
  */
-declare function classifyInterval(semitones: number, twoVoice?: boolean): IntervalQuality;
+declare function classifyInterval(semitones: number, twoVoice?: boolean): ConsonanceClass;
 /**
- * Test whether an interval is a perfect interval (unison/octave or fifth).
+ * Test whether an interval is a perfect consonance: the unison/octave or the
+ * fifth.
+ *
+ * The perfect fourth is deliberately excluded. This is the predicate the
+ * parallel-motion rules are written against, where the fourth behaves as a
+ * dissonance between two voices; {@link classifyInterval} is the general
+ * classifier, and it treats the fourth as context-dependent.
  *
  * @param semitones Interval size in semitones (may be negative or compound).
  * @returns True for the unison/octave (0) and the perfect fifth (7) mod 12.
@@ -136,11 +256,11 @@ declare function createRng(seed: number): Rng;
  */
 type Tuning = {
     /** Step index (MIDI number when `divisions` is 12) whose frequency is `refFreq`. */
-    refStep: number;
+    readonly refStep: number;
     /** Frequency in Hz of `refStep`. */
-    refFreq: number;
+    readonly refFreq: number;
     /** Equal divisions of the octave (12 standard; e.g. 19 or 31 for microtonal). */
-    divisions: number;
+    readonly divisions: number;
 };
 /**
  * Standard twelve-tone equal temperament, A4 (MIDI 69) = 440 Hz.
@@ -189,6 +309,67 @@ declare function frequencyOf(step: number, tuning?: Tuning): number;
  * @category Pitch & Intervals
  */
 declare function nearestStep(freq: number, tuning?: Tuning): number;
+/**
+ * Step index of a frequency under a tuning, unrounded.
+ *
+ * The exact inverse of {@link frequencyOf}. {@link nearestStep} rounds it,
+ * which discards how far off the pitch actually is — the figure a tuner
+ * display, a pitch-bend amount, or an intonation check is built on.
+ *
+ * @param freq Frequency in Hz.
+ * @param tuning The tuning (default 12-TET).
+ * @returns The fractional step index.
+ * @example
+ * ```ts
+ * import { stepOf } from '@libraz/libcantus';
+ * stepOf(442); // slightly above 69, the step for A440
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function stepOf(freq: number, tuning?: Tuning): number;
+/**
+ * How far a frequency sits from its nearest step, in cents.
+ *
+ * Positive means sharp of the step, negative flat.
+ *
+ * @param freq Frequency in Hz.
+ * @param tuning The tuning (default 12-TET).
+ * @returns The signed deviation in cents.
+ * @example
+ * ```ts
+ * import { centsFromNearestStep } from '@libraz/libcantus';
+ * Math.round(centsFromNearestStep(442)); // 8
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function centsFromNearestStep(freq: number, tuning?: Tuning): number;
+/**
+ * Steps spanned by an interval in cents, unrounded — the inverse of
+ * {@link centsOfSteps}.
+ *
+ * @param cents The interval in cents.
+ * @param tuning The tuning (default 12-TET).
+ * @returns The fractional step count.
+ * @category Pitch & Intervals
+ */
+declare function stepsOfCents(cents: number, tuning?: Tuning): number;
+/**
+ * The frequency ratio an interval in cents spans — the inverse of
+ * {@link ratioToCents}.
+ *
+ * Multiply a frequency by this to move it by that many cents, which is how a
+ * cents offset (a pitch-bend spec, a tuning table entry) is applied.
+ *
+ * @param cents The interval in cents.
+ * @returns The frequency ratio.
+ * @example
+ * ```ts
+ * import { centsToRatio } from '@libraz/libcantus';
+ * 440 * centsToRatio(14); // A440 raised by 14 cents
+ * ```
+ * @category Pitch & Intervals
+ */
+declare function centsToRatio(cents: number): number;
 /**
  * Interval in cents between two frequencies.
  *
@@ -223,7 +404,7 @@ declare function ratioToCents(numerator: number, denominator: number): number;
  *
  * @category Pitch & Intervals
  */
-declare const JUST_RATIOS: Record<number, [number, number]>;
+declare const JUST_RATIOS: Readonly<Record<number, readonly [number, number]>>;
 /**
  * Cents by which a five-limit just interval departs from its 12-TET tempering
  * (positive means the just interval is wider).
@@ -235,28 +416,119 @@ declare const JUST_RATIOS: Record<number, [number, number]>;
  */
 declare function justDeviationCents(semitoneClass: number): number;
 
-/** Default upper bound for synchronous event/window/candidate generation. */
+/**
+ * Default upper bound for synchronous event/window/candidate generation.
+ *
+ * @category Core
+ */
 declare const DEFAULT_GENERATION_BUDGET = 1000000;
-/** Require a finite JavaScript number and return it unchanged. */
+/**
+ * Require a finite JavaScript number and return it unchanged.
+ *
+ * @category Core
+ */
 declare function assertFiniteNumber(value: number, name: string): number;
-/** Require an integer in the inclusive range `[min, max]`. */
+/**
+ * Require an integer in the inclusive range `[min, max]`.
+ *
+ * @category Core
+ */
 declare function assertInteger(value: number, name: string, min?: number, max?: number): number;
-/** Require a positive safe integer, optionally capped by `max`. */
+/** Require an integer MIDI pitch in the inclusive range 0..127. */
+declare function assertMidiPitch(value: number, name?: string): number;
+/** Clamp an integer MIDI pitch to the inclusive range 0..127. */
+declare function clampToMidi(value: number, name?: string): number;
+/** Require a bounded integer scale/chord degree. */
+declare function assertDegree(value: number, name?: string): number;
+/** Require a finite semitone offset before pitch-class reduction. */
+declare function assertFiniteSemitones(value: number, name?: string): number;
+/**
+ * Drop the notes that never sound.
+ *
+ * A MIDI or DAW import routinely carries zero-length artefacts. Every entry
+ * point in this library ignores them, but a caller holding such an array still
+ * has to decide what to do with it before comparing note counts or indices;
+ * this is the one filter to apply.
+ *
+ * @param events The note events to filter.
+ * @returns A new array containing only the notes with a positive duration.
+ * @example
+ * ```ts
+ * import { dropSilentNotes } from '@libraz/libcantus';
+ * dropSilentNotes([{ pitch: 60, startBeat: 0, durationBeat: 0 }]); // []
+ * ```
+ * @category Core
+ */
+declare function dropSilentNotes(events: readonly NoteEvent[]): NoteEvent[];
+/** Alias that makes the shared positive-duration policy explicit at API entrances. */
+declare const soundingNotesOnly: typeof dropSilentNotes;
+/**
+ * Require a value to be one of a fixed set of names.
+ *
+ * TypeScript checks string-union options at compile time only, so a value that
+ * arrives from JSON, a config file, or a JavaScript caller reaches the engine
+ * unchecked and is then read against a table that has no entry for it —
+ * producing a silent `undefined`, a NaN velocity, or a crash far from the call.
+ *
+ * @param value The value to check.
+ * @param allowed Every accepted name.
+ * @param name What the value is, for the error message.
+ * @returns The value, narrowed to the allowed union.
+ * @throws If the value is not one of `allowed`.
+ *
+ * @category Core
+ */
+declare function assertOneOf<const T extends string>(value: unknown, allowed: readonly T[], name: string): T;
+/**
+ * Require a positive safe integer, optionally capped by `max`.
+ *
+ * @category Core
+ */
 declare function assertPositiveInt(value: number, name: string, max?: number): number;
-/** Require a finite number in the inclusive range `[min, max]`. */
+/**
+ * Require a finite number in the inclusive range `[min, max]`.
+ *
+ * @category Core
+ */
 declare function assertRange(value: number, min: number, max: number, name: string): number;
-/** Reject work estimates that would exceed a synchronous generation budget. */
-declare function assertGenerationBudget(estimated: number, name: string, limit?: number): number;
-/** Validate a time signature, including additive grouping, before any early return. */
+/**
+ * Reject work estimates that would exceed a synchronous generation budget.
+ *
+ * @category Core
+ */
+declare function assertGenerationBudget(estimated: number, name: string, limit?: number | undefined): number;
+/**
+ * Validate a time signature, including additive grouping, before any early return.
+ *
+ * @category Core
+ */
 declare function assertTimeSignature(ts: TimeSignature, name?: string): TimeSignature;
-/** Validate the finite fields of one timeline note event. */
-declare function assertNoteEvent(event: NoteEvent, name?: string, options?: {
-    allowNonPositiveDuration?: boolean;
-}): NoteEvent;
-/** Validate an event array and its allocation budget without copying it. */
-declare function assertNoteEvents(events: NoteEvent[], name?: string, options?: {
+/**
+ * How strictly {@link assertNoteEvent} and {@link assertNoteEvents} read an
+ * event array.
+ *
+ * @category Core
+ */
+type NoteEventAssertOptions = {
+    /**
+     * Accept notes that never sound. The analysis side does, so an array from a
+     * MIDI import can be validated before the zero-length artefacts are dropped.
+     */
     allowNonPositiveDuration?: boolean;
+    /** Upper bound on the event count; defaults to the generation budget. */
     budget?: number;
-}): NoteEvent[];
+};
+/**
+ * Validate the finite fields of one timeline note event.
+ *
+ * @category Core
+ */
+declare function assertNoteEvent(event: NoteEvent, name?: string, options?: NoteEventAssertOptions): NoteEvent;
+/**
+ * Validate an event array and its allocation budget without copying it.
+ *
+ * @category Core
+ */
+declare function assertNoteEvents(events: readonly NoteEvent[], name?: string, options?: NoteEventAssertOptions): NoteEvent[];
 
-export { DEFAULT_GENERATION_BUDGET, type IndexedNoteEvent, IntervalQuality, JUST_RATIOS, NoteEvent, type NoteEventIndex, type Rng, TWELVE_TET, TimeSignature, type Tuning, assertFiniteNumber, assertGenerationBudget, assertInteger, assertNoteEvent, assertNoteEvents, assertPositiveInt, assertRange, assertTimeSignature, centsBetweenFreq, centsOfSteps, classifyInterval, createNoteEventIndex, createRng, edo, frequencyOf, isConsonantInterval, isPerfectInterval, justDeviationCents, nearestStep, ratioToCents };
+export { BudgetExceededError, ConsonanceClass, DEFAULT_GENERATION_BUDGET, type IndexedNoteEvent, InvalidInputError, JUST_RATIOS, type LibcantusErrorCode, NoSolutionError, NoteEvent, type NoteEventAssertOptions, type NoteEventIndex, type OnsetTieBreak, type Rng, TWELVE_TET, TimeSignature, type Tuning, assertDegree, assertFiniteNumber, assertFiniteSemitones, assertGenerationBudget, assertInteger, assertMidiPitch, assertNoteEvent, assertNoteEvents, assertOneOf, assertPositiveInt, assertRange, assertTimeSignature, centsBetweenFreq, centsFromNearestStep, centsOfSteps, centsToRatio, clampToMidi, classifyInterval, createNoteEventIndex, createRng, dropSilentNotes, edo, frequencyOf, isConsonantInterval, isLibcantusError, isPerfectInterval, justDeviationCents, nearestStep, ratioToCents, soundingNotesOnly, stepOf, stepsOfCents };

package/dist/core/index.js

@@ -2,92 +2,140 @@ import {
   JUST_RATIOS,
   TWELVE_TET,
   centsBetweenFreq,
+  centsFromNearestStep,
   centsOfSteps,
+  centsToRatio,
   edo,
   frequencyOf,
   justDeviationCents,
   nearestStep,
-  ratioToCents
-} from "../chunk-AKLYPWIN.js";
+  ratioToCents,
+  stepOf,
+  stepsOfCents
+} from "../chunk-EDOTEABK.js";
 import {
   createRng
-} from "../chunk-62QZKCJQ.js";
+} from "../chunk-ZGLJM4A4.js";
 import {
   barPositionToBeat,
+  barPositionToPulse,
   beatToBarPosition,
   beatsPerBar,
   createNoteEventIndex,
+  formatBarPosition,
   formatTimeSignature,
   isCompound,
   isStrongBeat,
   metricWeight,
   parseTimeSignature,
+  pulseBeats,
   pulsesPerBar,
   tuplet
-} from "../chunk-I5R7ZBJS.js";
-import {
-  formatNote,
-  midiToNote,
-  noteToMidi,
-  noteToPitchClass,
-  parseNote,
-  spelledInterval
-} from "../chunk-DYWFNC4A.js";
+} from "../chunk-2PTFGVD7.js";
 import {
+  BudgetExceededError,
+  ConsonanceClass,
   DEFAULT_GENERATION_BUDGET,
-  IntervalQuality,
+  InvalidInputError,
+  NoSolutionError,
+  assertDegree,
   assertFiniteNumber,
+  assertFiniteSemitones,
   assertGenerationBudget,
   assertInteger,
+  assertMidiPitch,
   assertNoteEvent,
   assertNoteEvents,
+  assertOneOf,
   assertPositiveInt,
   assertRange,
   assertTimeSignature,
+  clampToMidi,
   classifyInterval,
+  diatonicLetterOf,
+  dropSilentNotes,
+  formatNote,
+  intervalSemitones,
   isConsonantInterval,
-  isPerfectInterval
-} from "../chunk-FBQK3ZQN.js";
+  isLibcantusError,
+  isPerfectInterval,
+  midiToNote,
+  naturalPitchClassOf,
+  noteToMidi,
+  noteToPitchClass,
+  parseInterval,
+  parseNote,
+  pitchClassOf,
+  soundingNotesOnly,
+  spelledInterval,
+  transposeByInterval,
+  transposeNote
+} from "../chunk-R2VVFAIN.js";
 export {
+  BudgetExceededError,
+  ConsonanceClass,
   DEFAULT_GENERATION_BUDGET,
-  IntervalQuality,
+  InvalidInputError,
   JUST_RATIOS,
+  NoSolutionError,
   TWELVE_TET,
+  assertDegree,
   assertFiniteNumber,
+  assertFiniteSemitones,
   assertGenerationBudget,
   assertInteger,
+  assertMidiPitch,
   assertNoteEvent,
   assertNoteEvents,
+  assertOneOf,
   assertPositiveInt,
   assertRange,
   assertTimeSignature,
   barPositionToBeat,
+  barPositionToPulse,
   beatToBarPosition,
   beatsPerBar,
   centsBetweenFreq,
+  centsFromNearestStep,
   centsOfSteps,
+  centsToRatio,
+  clampToMidi,
   classifyInterval,
   createNoteEventIndex,
   createRng,
+  diatonicLetterOf,
+  dropSilentNotes,
   edo,
+  formatBarPosition,
   formatNote,
   formatTimeSignature,
   frequencyOf,
+  intervalSemitones,
   isCompound,
   isConsonantInterval,
+  isLibcantusError,
   isPerfectInterval,
   isStrongBeat,
   justDeviationCents,
   metricWeight,
   midiToNote,
+  naturalPitchClassOf,
   nearestStep,
   noteToMidi,
   noteToPitchClass,
+  parseInterval,
   parseNote,
   parseTimeSignature,
+  pitchClassOf,
+  pulseBeats,
   pulsesPerBar,
   ratioToCents,
+  soundingNotesOnly,
   spelledInterval,
+  stepOf,
+  stepsOfCents,
+  transposeByInterval,
+  transposeNote,
   tuplet
 };
 //# sourceMappingURL=index.js.map