@libraz/libcantus 1.0.1 → 1.2.0

package/dist/{index-B9MNZboQ.d.ts → index-Cy15oTvh.d.cts}

@@ -315,13 +315,18 @@ type SpelledInterval = {
     /** Signed semitone distance from the first note to the second. */
     semitones: number;
     /**
-     * True when the diatonic letters move down, and absent otherwise — an
-     * ascending interval leaves the key out rather than carrying `false`, so
-     * every producer of this type returns the same object for the same interval.
-     * The flag is not redundant with the sign of the span: a descending unison
-     * spans zero semitones, and a letter can rise while the pitch falls.
+     * Whether the diatonic letters move down.
+     *
+     * Always present, so the direction of a written-down interval is not
+     * something a reader can lose: data rebuilt without the key would otherwise
+     * come back ascending with nothing to say it had changed. Every producer
+     * decides it, and the compiler asks each one to.
+     *
+     * Not redundant with the sign of the span: a descending unison spans zero
+     * semitones, and a letter can rise while the pitch falls — `dd2` climbs a
+     * letter and loses a semitone.
      */
-    descending?: boolean;
+    descending: boolean;
 };
 /**
  * Reduce a MIDI pitch, a bare pitch class, or any signed offset to a pitch
@@ -599,7 +604,11 @@ declare function transposeNote(note: Note, semitones: number, opts?: {
  *
  * @param numberValue Diatonic size: 1 = unison, 2 = second, ... 8 = octave.
  * @param quality Quality label: `'P'`, `'M'`, `'m'`, or repeated `'A'`/`'d'`.
- * @returns The unsigned semitone span.
+ * @returns The signed semitone span the name covers when its letters ascend.
+ *   Nearly every name spans upward, but a second narrowed far enough crosses
+ *   zero while its letters still rise — C# up to Dbb is a doubly diminished
+ *   second spanning -1 — and the sign is what keeps that name reading as the
+ *   same interval a measurement of those two notes reports.
  * @throws If the quality cannot apply to the number, such as a major fifth or a
  *   diminished unison.
  * @example
@@ -620,15 +629,16 @@ declare function intervalSemitones(numberValue: number, quality: IntervalQuality
  *
  * @param name The interval name: an optional `'-'`, a quality label, and a
  *   diatonic number. Surrounding whitespace is ignored.
- * @returns The spelled interval. An ascending name carries a non-negative span
- *   and no `descending` flag.
+ * @returns The spelled interval. `descending` is always present, `false` for an
+ *   ascending name, and the span is the one {@link intervalSemitones} reports —
+ *   negative for the rare second narrowed past a zero span.
  * @throws If the name is not a quality label followed by a number, or the two
  *   cannot describe the same interval. Use {@link tryParseInterval} where
  *   failure is ordinary, such as an interval field read on every keystroke.
  * @example
  * ```ts
  * import { parseInterval } from '@libraz/libcantus';
- * parseInterval('m3'); // { number: 3, quality: 'm', semitones: 3 }
+ * parseInterval('m3'); // { number: 3, quality: 'm', semitones: 3, descending: false }
  * parseInterval('-m3'); // { number: 3, quality: 'm', semitones: -3, descending: true }
  * ```
  * @category Pitch & Intervals
@@ -659,9 +669,23 @@ declare function tryParseInterval(name: string): ParseResult<SpelledInterval>;
  *
  * @category Pitch & Intervals
  */
-type IntervalLike = string | SpelledInterval | {
+type IntervalLike = string | IntervalData | {
     /** The interval data this value stands for. */
-    toJSON(): SpelledInterval;
+    toJSON(): IntervalData;
+};
+/**
+ * Interval data as a caller may write it, with the direction optional.
+ *
+ * Deliberately wider than {@link SpelledInterval}: a caller hands in what they
+ * have, including data written before the direction travelled with it, and
+ * {@link toSpelledInterval} decides what is missing. Narrowing the input to the
+ * resolved shape would refuse the very data the resolver exists to repair.
+ *
+ * @category Pitch & Intervals
+ */
+type IntervalData = Omit<SpelledInterval, 'descending'> & {
+    /** Whether the letters move down; read from the span and quality when absent. */
+    descending?: boolean;
 };
 /**
  * Resolve any interval-shaped value to plain {@link SpelledInterval} data.
@@ -674,14 +698,14 @@ type IntervalLike = string | SpelledInterval | {
  *
  * @param value An interval name, plain interval data, or a value whose `toJSON`
  *   returns interval data.
- * @returns The validated interval data, carrying `descending` only when the
- *   interval descends.
+ * @returns The validated interval data, always carrying `descending`, `false`
+ *   for an interval that ascends.
  * @throws If the value is not interval-shaped, or its number, quality, and span
  *   do not describe the same interval.
  * @example
  * ```ts
  * import { toSpelledInterval } from '@libraz/libcantus';
- * toSpelledInterval('P5'); // { number: 5, quality: 'P', semitones: 7 }
+ * toSpelledInterval('P5'); // { number: 5, quality: 'P', semitones: 7, descending: false }
  * toSpelledInterval({ number: 5, quality: 'P', semitones: -7 });
  * // { number: 5, quality: 'P', semitones: -7, descending: true }
  * ```
@@ -736,17 +760,23 @@ declare function toNoteData(value: NoteLike): Note;
  * the diatonic number decides the letter here: transposing C by an augmented
  * second gives D#, not Eb.
  *
- * @param note The note to transpose.
- * @param interval The interval to apply; a negative span transposes downward.
+ * Both arguments are taken in whatever form the caller holds them — the text a
+ * field carries, the plain data the library returns, or the class that wraps
+ * it — as the class mirror of this operation already did.
+ *
+ * @param given The note to transpose: a name, a MIDI number, plain note data,
+ *   or a `Note`.
+ * @param named The interval to apply: a name, plain interval data, or an
+ *   `Interval`. A negative span transposes downward.
  * @returns The transposed note, octave-less if the source was.
  * @example
  * ```ts
- * import { formatNote, parseInterval, parseNote, transposeByInterval } from '@libraz/libcantus';
- * formatNote(transposeByInterval(parseNote('C4'), parseInterval('A2'))); // 'D#4'
+ * import { formatNote, transposeByInterval } from '@libraz/libcantus';
+ * formatNote(transposeByInterval('C4', 'A2')); // 'D#4'
  * ```
  * @category Pitch & Intervals
  */
-declare function transposeByInterval(note: Note, interval: SpelledInterval): Note;
+declare function transposeByInterval(given: NoteLike, named: IntervalLike): Note;
 /**
  * The spelled interval from one note to another.
  *
@@ -761,10 +791,10 @@ declare function transposeByInterval(note: Note, interval: SpelledInterval): Not
  * ```ts
  * import { spelledInterval, parseNote } from '@libraz/libcantus';
  * spelledInterval(parseNote('C4'), parseNote('G4'));
- * // { number: 5, quality: 'P', semitones: 7 }
+ * // { number: 5, quality: 'P', semitones: 7, descending: false }
  * ```
  * @category Pitch & Intervals
  */
 declare function spelledInterval(a: Note, b: Note): SpelledInterval;
 
-export { ARTICULATIONS as A, BudgetExceededError as B, toSpelledInterval as C, transposeByInterval as D, transposeNote as E, tryParseInterval as F, tryParseKeyName as G, tryParseNote as H, type IntervalLike as I, type KeyName as K, type LibcantusError as L, NoSolutionError as N, type ParseResult as P, type SpelledInterval as S, type Articulation as a, type IntervalQualityLabel as b, InvalidInputError as c, type KeyScale as d, type LibcantusErrorCode as e, type Note as f, type NoteEvent as g, type NoteLike as h, type NoteNameOptions as i, type NoteNameSystem as j, detectNoteNameSystem as k, diatonicLetterOf as l, formatKeyName as m, formatNote as n, intervalSemitones as o, isLibcantusError as p, midiToNote as q, naturalPitchClassOf as r, noteToMidi as s, noteToPitchClass as t, parseInterval as u, parseKeyName as v, parseNote as w, pitchClassOf as x, spelledInterval as y, toNoteData as z };
+export { ARTICULATIONS as A, BudgetExceededError as B, toNoteData as C, toSpelledInterval as D, transposeByInterval as E, transposeNote as F, tryParseInterval as G, tryParseKeyName as H, type IntervalData as I, tryParseNote as J, type KeyName as K, type LibcantusError as L, NoSolutionError as N, type ParseResult as P, type SpelledInterval as S, type Articulation as a, type IntervalLike as b, type IntervalQualityLabel as c, InvalidInputError as d, type KeyScale as e, type LibcantusErrorCode as f, type Note as g, type NoteEvent as h, type NoteLike as i, type NoteNameOptions as j, type NoteNameSystem as k, detectNoteNameSystem as l, diatonicLetterOf as m, formatKeyName as n, formatNote as o, intervalSemitones as p, isLibcantusError as q, midiToNote as r, naturalPitchClassOf as s, noteToMidi as t, noteToPitchClass as u, parseInterval as v, parseKeyName as w, parseNote as x, pitchClassOf as y, spelledInterval as z };

package/dist/{index-B9MNZboQ.d.cts → index-Cy15oTvh.d.ts}

@@ -315,13 +315,18 @@ type SpelledInterval = {
     /** Signed semitone distance from the first note to the second. */
     semitones: number;
     /**
-     * True when the diatonic letters move down, and absent otherwise — an
-     * ascending interval leaves the key out rather than carrying `false`, so
-     * every producer of this type returns the same object for the same interval.
-     * The flag is not redundant with the sign of the span: a descending unison
-     * spans zero semitones, and a letter can rise while the pitch falls.
+     * Whether the diatonic letters move down.
+     *
+     * Always present, so the direction of a written-down interval is not
+     * something a reader can lose: data rebuilt without the key would otherwise
+     * come back ascending with nothing to say it had changed. Every producer
+     * decides it, and the compiler asks each one to.
+     *
+     * Not redundant with the sign of the span: a descending unison spans zero
+     * semitones, and a letter can rise while the pitch falls — `dd2` climbs a
+     * letter and loses a semitone.
      */
-    descending?: boolean;
+    descending: boolean;
 };
 /**
  * Reduce a MIDI pitch, a bare pitch class, or any signed offset to a pitch
@@ -599,7 +604,11 @@ declare function transposeNote(note: Note, semitones: number, opts?: {
  *
  * @param numberValue Diatonic size: 1 = unison, 2 = second, ... 8 = octave.
  * @param quality Quality label: `'P'`, `'M'`, `'m'`, or repeated `'A'`/`'d'`.
- * @returns The unsigned semitone span.
+ * @returns The signed semitone span the name covers when its letters ascend.
+ *   Nearly every name spans upward, but a second narrowed far enough crosses
+ *   zero while its letters still rise — C# up to Dbb is a doubly diminished
+ *   second spanning -1 — and the sign is what keeps that name reading as the
+ *   same interval a measurement of those two notes reports.
  * @throws If the quality cannot apply to the number, such as a major fifth or a
  *   diminished unison.
  * @example
@@ -620,15 +629,16 @@ declare function intervalSemitones(numberValue: number, quality: IntervalQuality
  *
  * @param name The interval name: an optional `'-'`, a quality label, and a
  *   diatonic number. Surrounding whitespace is ignored.
- * @returns The spelled interval. An ascending name carries a non-negative span
- *   and no `descending` flag.
+ * @returns The spelled interval. `descending` is always present, `false` for an
+ *   ascending name, and the span is the one {@link intervalSemitones} reports —
+ *   negative for the rare second narrowed past a zero span.
  * @throws If the name is not a quality label followed by a number, or the two
  *   cannot describe the same interval. Use {@link tryParseInterval} where
  *   failure is ordinary, such as an interval field read on every keystroke.
  * @example
  * ```ts
  * import { parseInterval } from '@libraz/libcantus';
- * parseInterval('m3'); // { number: 3, quality: 'm', semitones: 3 }
+ * parseInterval('m3'); // { number: 3, quality: 'm', semitones: 3, descending: false }
  * parseInterval('-m3'); // { number: 3, quality: 'm', semitones: -3, descending: true }
  * ```
  * @category Pitch & Intervals
@@ -659,9 +669,23 @@ declare function tryParseInterval(name: string): ParseResult<SpelledInterval>;
  *
  * @category Pitch & Intervals
  */
-type IntervalLike = string | SpelledInterval | {
+type IntervalLike = string | IntervalData | {
     /** The interval data this value stands for. */
-    toJSON(): SpelledInterval;
+    toJSON(): IntervalData;
+};
+/**
+ * Interval data as a caller may write it, with the direction optional.
+ *
+ * Deliberately wider than {@link SpelledInterval}: a caller hands in what they
+ * have, including data written before the direction travelled with it, and
+ * {@link toSpelledInterval} decides what is missing. Narrowing the input to the
+ * resolved shape would refuse the very data the resolver exists to repair.
+ *
+ * @category Pitch & Intervals
+ */
+type IntervalData = Omit<SpelledInterval, 'descending'> & {
+    /** Whether the letters move down; read from the span and quality when absent. */
+    descending?: boolean;
 };
 /**
  * Resolve any interval-shaped value to plain {@link SpelledInterval} data.
@@ -674,14 +698,14 @@ type IntervalLike = string | SpelledInterval | {
  *
  * @param value An interval name, plain interval data, or a value whose `toJSON`
  *   returns interval data.
- * @returns The validated interval data, carrying `descending` only when the
- *   interval descends.
+ * @returns The validated interval data, always carrying `descending`, `false`
+ *   for an interval that ascends.
  * @throws If the value is not interval-shaped, or its number, quality, and span
  *   do not describe the same interval.
  * @example
  * ```ts
  * import { toSpelledInterval } from '@libraz/libcantus';
- * toSpelledInterval('P5'); // { number: 5, quality: 'P', semitones: 7 }
+ * toSpelledInterval('P5'); // { number: 5, quality: 'P', semitones: 7, descending: false }
  * toSpelledInterval({ number: 5, quality: 'P', semitones: -7 });
  * // { number: 5, quality: 'P', semitones: -7, descending: true }
  * ```
@@ -736,17 +760,23 @@ declare function toNoteData(value: NoteLike): Note;
  * the diatonic number decides the letter here: transposing C by an augmented
  * second gives D#, not Eb.
  *
- * @param note The note to transpose.
- * @param interval The interval to apply; a negative span transposes downward.
+ * Both arguments are taken in whatever form the caller holds them — the text a
+ * field carries, the plain data the library returns, or the class that wraps
+ * it — as the class mirror of this operation already did.
+ *
+ * @param given The note to transpose: a name, a MIDI number, plain note data,
+ *   or a `Note`.
+ * @param named The interval to apply: a name, plain interval data, or an
+ *   `Interval`. A negative span transposes downward.
  * @returns The transposed note, octave-less if the source was.
  * @example
  * ```ts
- * import { formatNote, parseInterval, parseNote, transposeByInterval } from '@libraz/libcantus';
- * formatNote(transposeByInterval(parseNote('C4'), parseInterval('A2'))); // 'D#4'
+ * import { formatNote, transposeByInterval } from '@libraz/libcantus';
+ * formatNote(transposeByInterval('C4', 'A2')); // 'D#4'
  * ```
  * @category Pitch & Intervals
  */
-declare function transposeByInterval(note: Note, interval: SpelledInterval): Note;
+declare function transposeByInterval(given: NoteLike, named: IntervalLike): Note;
 /**
  * The spelled interval from one note to another.
  *
@@ -761,10 +791,10 @@ declare function transposeByInterval(note: Note, interval: SpelledInterval): Not
  * ```ts
  * import { spelledInterval, parseNote } from '@libraz/libcantus';
  * spelledInterval(parseNote('C4'), parseNote('G4'));
- * // { number: 5, quality: 'P', semitones: 7 }
+ * // { number: 5, quality: 'P', semitones: 7, descending: false }
  * ```
  * @category Pitch & Intervals
  */
 declare function spelledInterval(a: Note, b: Note): SpelledInterval;
 
-export { ARTICULATIONS as A, BudgetExceededError as B, toSpelledInterval as C, transposeByInterval as D, transposeNote as E, tryParseInterval as F, tryParseKeyName as G, tryParseNote as H, type IntervalLike as I, type KeyName as K, type LibcantusError as L, NoSolutionError as N, type ParseResult as P, type SpelledInterval as S, type Articulation as a, type IntervalQualityLabel as b, InvalidInputError as c, type KeyScale as d, type LibcantusErrorCode as e, type Note as f, type NoteEvent as g, type NoteLike as h, type NoteNameOptions as i, type NoteNameSystem as j, detectNoteNameSystem as k, diatonicLetterOf as l, formatKeyName as m, formatNote as n, intervalSemitones as o, isLibcantusError as p, midiToNote as q, naturalPitchClassOf as r, noteToMidi as s, noteToPitchClass as t, parseInterval as u, parseKeyName as v, parseNote as w, pitchClassOf as x, spelledInterval as y, toNoteData as z };
+export { ARTICULATIONS as A, BudgetExceededError as B, toNoteData as C, toSpelledInterval as D, transposeByInterval as E, transposeNote as F, tryParseInterval as G, tryParseKeyName as H, type IntervalData as I, tryParseNote as J, type KeyName as K, type LibcantusError as L, NoSolutionError as N, type ParseResult as P, type SpelledInterval as S, type Articulation as a, type IntervalLike as b, type IntervalQualityLabel as c, InvalidInputError as d, type KeyScale as e, type LibcantusErrorCode as f, type Note as g, type NoteEvent as h, type NoteLike as i, type NoteNameOptions as j, type NoteNameSystem as k, detectNoteNameSystem as l, diatonicLetterOf as m, formatKeyName as n, formatNote as o, intervalSemitones as p, isLibcantusError as q, midiToNote as r, naturalPitchClassOf as s, noteToMidi as t, noteToPitchClass as u, parseInterval as v, parseKeyName as w, parseNote as x, pitchClassOf as y, spelledInterval as z };