@libraz/libcantus 0.9.4 → 1.0.0

package/dist/function-BtiZb9i9.d.ts

@@ -1,208 +0,0 @@
-import { K as KeyScale } from './types-BN6_Q9Kl.js';
-import { C as Chord } from './index-C83mZI1P.js';
-
-/**
- * Borrowed chords (modal interchange) and the Neapolitan.
- *
- * Roots are pitch classes measured against the key tonic, so borrowed and
- * chromatic chords are handled by their semitone offset rather than requiring a
- * spelled key signature.
- */
-
-/**
- * The origin of a recognized non-diatonic chord, or null when none applies.
- *
- * @category Functional Harmony
- */
-type BorrowedSource = 'parallelMinor' | 'parallelMajor' | 'neapolitan' | null;
-/**
- * Whether a chord is borrowed from the parallel mode (modal interchange).
- *
- * True when the chord is not diatonic to `key` but is diatonic to its
- * {@link parallelKey} — e.g. iv, bVI, or bVII in a major key, or the Picardy
- * tonic and major IV in a minor key. Two non-diatonic families are excluded:
- * chords diatonic to neither mode (they are chromatic, not borrowed), and, in
- * a minor key, chords explained by the harmonic minor scale (the major
- * dominant and raised-leading-tone chords), which are in-key alterations
- * rather than interchange even though they happen to fit the parallel major.
- *
- * @param chord The chord to test.
- * @param key The prevailing key.
- * @returns True if the chord is borrowed from the parallel mode.
- * @category Functional Harmony
- */
-declare function isBorrowedChord(chord: Chord, key: KeyScale): boolean;
-/**
- * Identify where a non-diatonic chord comes from.
- *
- * The Neapolitan (major triad on b2) is recognized first, since it sits
- * outside both parallel modes; parallel-mode borrowing follows the
- * {@link isBorrowedChord} rules. Diatonic chords, harmonic-minor alterations,
- * and unrecognized chromatic chords all yield null.
- *
- * @param chord The chord to classify.
- * @param key The prevailing key.
- * @returns The borrowing source, or null.
- * @category Functional Harmony
- */
-declare function borrowedSource(chord: Chord, key: KeyScale): BorrowedSource;
-
-/**
- * Cadence detection between two successive chords.
- *
- * Roots are pitch classes measured against the key tonic, so borrowed and
- * chromatic chords are handled by their semitone offset rather than requiring a
- * spelled key signature.
- */
-
-/**
- * A recognized cadence type, or null when a chord pair forms none.
- *
- * @category Functional Harmony
- */
-type Cadence = 'authentic' | 'plagal' | 'half' | 'deceptive' | null;
-/**
- * Classify the cadence formed by moving from one chord to the next.
- *
- * - authentic: V (dominant a fifth above the tonic) to I
- * - plagal: IV (a fourth above the tonic) to I
- * - deceptive: V to the submediant (diatonic vi or borrowed bVI in major, VI in
- *   minor)
- * - half: any chord other than the dominant itself to V
- *
- * A static V-to-V repeat with no root motion is not a cadence and yields null.
- *
- * @param from The penultimate chord.
- * @param to The final chord.
- * @param key The prevailing key.
- * @returns The cadence type, or null.
- * @example
- * ```ts
- * import { detectCadence, makeChord, majorKey } from '@libraz/libcantus';
- * detectCadence(makeChord(7, 'maj'), makeChord(0, 'maj'), majorKey(0)); // => 'authentic'
- * ```
- * @category Functional Harmony
- */
-declare function detectCadence(from: Chord, to: Chord, key: KeyScale): Cadence;
-
-/**
- * Harmonic function (tonic / subdominant / dominant), diatonicity, parallel-key
- * mirroring, and full chord analysis.
- *
- * Roots are pitch classes measured against the key tonic, so borrowed and
- * chromatic chords are handled by their semitone offset rather than requiring a
- * spelled key signature.
- */
-
-/**
- * The three broad harmonic functions of tonal music.
- *
- * @category Functional Harmony
- */
-type HarmonicFunction = 'tonic' | 'subdominant' | 'dominant';
-/**
- * Whether a key's scale has a minor third and no major third (a minor key).
- *
- * @category Functional Harmony
- */
-declare function isMinorKey(key: KeyScale): boolean;
-/**
- * The harmonic function of a chord in a key.
- *
- * The root's offset above the tonic gives the baseline mapping, which follows
- * common-practice major-key function and is a useful approximation in minor and
- * for borrowed chords. Chord quality then refines it where the sonority settles
- * an ambiguity the root offset cannot:
- *
- * - A chord that *sounds* like a dominant — a major third with a minor seventh,
- *   or a diminished-family chord — and is not diatonic to the key has dominant
- *   function when its root resolves down a fifth or by a semitone onto a
- *   diatonic degree. This is what makes an applied dominant (`A7` in C, which
- *   tonicizes ii) and its tritone substitute (`Db7`) read as dominant rather
- *   than inheriting the function of the degree they happen to sit on.
- * - The Neapolitan is subdominant.
- * - A major triad on bVI or bVII of a major key is subdominant — the borrowed
- *   pop cadence chord, distinct from the bVII7 above, which has a seventh and
- *   is a dominant sonority.
- *
- * @param chord The chord.
- * @param key The prevailing key.
- * @returns The harmonic function.
- * @example
- * ```ts
- * import { functionOf, makeChord, majorKey } from '@libraz/libcantus';
- * functionOf(makeChord(9, 'dom7'), majorKey(0)); // 'dominant' — A7 tonicizes ii
- * functionOf(makeChord(10, 'maj'), majorKey(0)); // 'subdominant' — borrowed bVII
- * ```
- * @category Functional Harmony
- */
-declare function functionOf(chord: Chord, key: KeyScale): HarmonicFunction;
-/**
- * The result of {@link analyzeChord}: function, borrowing, and Roman numeral.
- *
- * @category Functional Harmony
- */
-type ChordAnalysis = {
-    function: HarmonicFunction;
-    borrowed: boolean;
-    source: BorrowedSource;
-    roman: string;
-};
-/**
- * Whether every pitch class of a chord belongs to the key's scale.
- *
- * The test is strict against the key's own mode mask: in a natural-minor key
- * the harmonic-minor dominant (major V) is *not* diatonic, since the raised
- * leading tone lies outside the mask. Borrowing predicates treat that case as
- * an in-key alteration separately (see {@link isBorrowedChord}).
- *
- * @param chord The chord to test.
- * @param key The prevailing key.
- * @returns True if all chord pitch classes are scale tones.
- * @category Functional Harmony
- */
-declare function isDiatonic(chord: Chord, key: KeyScale): boolean;
-/**
- * The parallel key: same tonic, opposite mode.
- *
- * A key with a minor third (natural/harmonic/melodic minor, dorian, phrygian)
- * maps to the parallel major; any other key maps to the parallel natural minor.
- *
- * @param key The key to mirror.
- * @returns The parallel major or natural-minor key on the same tonic.
- * @category Functional Harmony
- */
-declare function parallelKey(key: KeyScale): KeyScale;
-/**
- * Analyze a chord in a key: harmonic function, borrowing, and Roman numeral.
- *
- * The function is quality-aware (see the predicates behind it), the source
- * follows {@link borrowedSource}, and the numeral comes from
- * {@link chordToRoman}. `borrowed` is true whenever a source is identified —
- * including the Neapolitan, which the stricter parallel-mode predicate
- * {@link isBorrowedChord} does not count.
- *
- * @param chord The chord to analyze.
- * @param key The prevailing key.
- * @returns The chord analysis.
- * @example
- * ```ts
- * import { analyzeChord, makeChord, majorKey } from '@libraz/libcantus';
- * analyzeChord(makeChord(7, 'dom7'), majorKey(0));
- * // { function: 'dominant', borrowed: false, source: null, roman: 'V7' }
- * ```
- * @category Functional Harmony
- */
-declare function analyzeChord(chord: Chord, key: KeyScale): ChordAnalysis;
-/**
- * The secondary dominant (V7) that tonicizes a scale degree.
- *
- * @param targetDegree 0-based scale degree to tonicize, in 0..6.
- * @param key The prevailing key.
- * @returns A dominant-seventh chord a fifth above the target's root.
- * @throws If `targetDegree` is not an integer in 0..6.
- * @category Functional Harmony
- */
-declare function secondaryDominant(targetDegree: number, key: KeyScale): Chord;
-
-export { type BorrowedSource as B, type Cadence as C, type HarmonicFunction as H, type ChordAnalysis as a, analyzeChord as b, borrowedSource as c, detectCadence as d, isDiatonic as e, functionOf as f, isMinorKey as g, isBorrowedChord as i, parallelKey as p, secondaryDominant as s };

package/dist/function-DNugAOrt.d.cts

@@ -1,208 +0,0 @@
-import { K as KeyScale } from './types-BN6_Q9Kl.cjs';
-import { C as Chord } from './index-y_ak9_Hi.cjs';
-
-/**
- * Borrowed chords (modal interchange) and the Neapolitan.
- *
- * Roots are pitch classes measured against the key tonic, so borrowed and
- * chromatic chords are handled by their semitone offset rather than requiring a
- * spelled key signature.
- */
-
-/**
- * The origin of a recognized non-diatonic chord, or null when none applies.
- *
- * @category Functional Harmony
- */
-type BorrowedSource = 'parallelMinor' | 'parallelMajor' | 'neapolitan' | null;
-/**
- * Whether a chord is borrowed from the parallel mode (modal interchange).
- *
- * True when the chord is not diatonic to `key` but is diatonic to its
- * {@link parallelKey} — e.g. iv, bVI, or bVII in a major key, or the Picardy
- * tonic and major IV in a minor key. Two non-diatonic families are excluded:
- * chords diatonic to neither mode (they are chromatic, not borrowed), and, in
- * a minor key, chords explained by the harmonic minor scale (the major
- * dominant and raised-leading-tone chords), which are in-key alterations
- * rather than interchange even though they happen to fit the parallel major.
- *
- * @param chord The chord to test.
- * @param key The prevailing key.
- * @returns True if the chord is borrowed from the parallel mode.
- * @category Functional Harmony
- */
-declare function isBorrowedChord(chord: Chord, key: KeyScale): boolean;
-/**
- * Identify where a non-diatonic chord comes from.
- *
- * The Neapolitan (major triad on b2) is recognized first, since it sits
- * outside both parallel modes; parallel-mode borrowing follows the
- * {@link isBorrowedChord} rules. Diatonic chords, harmonic-minor alterations,
- * and unrecognized chromatic chords all yield null.
- *
- * @param chord The chord to classify.
- * @param key The prevailing key.
- * @returns The borrowing source, or null.
- * @category Functional Harmony
- */
-declare function borrowedSource(chord: Chord, key: KeyScale): BorrowedSource;
-
-/**
- * Cadence detection between two successive chords.
- *
- * Roots are pitch classes measured against the key tonic, so borrowed and
- * chromatic chords are handled by their semitone offset rather than requiring a
- * spelled key signature.
- */
-
-/**
- * A recognized cadence type, or null when a chord pair forms none.
- *
- * @category Functional Harmony
- */
-type Cadence = 'authentic' | 'plagal' | 'half' | 'deceptive' | null;
-/**
- * Classify the cadence formed by moving from one chord to the next.
- *
- * - authentic: V (dominant a fifth above the tonic) to I
- * - plagal: IV (a fourth above the tonic) to I
- * - deceptive: V to the submediant (diatonic vi or borrowed bVI in major, VI in
- *   minor)
- * - half: any chord other than the dominant itself to V
- *
- * A static V-to-V repeat with no root motion is not a cadence and yields null.
- *
- * @param from The penultimate chord.
- * @param to The final chord.
- * @param key The prevailing key.
- * @returns The cadence type, or null.
- * @example
- * ```ts
- * import { detectCadence, makeChord, majorKey } from '@libraz/libcantus';
- * detectCadence(makeChord(7, 'maj'), makeChord(0, 'maj'), majorKey(0)); // => 'authentic'
- * ```
- * @category Functional Harmony
- */
-declare function detectCadence(from: Chord, to: Chord, key: KeyScale): Cadence;
-
-/**
- * Harmonic function (tonic / subdominant / dominant), diatonicity, parallel-key
- * mirroring, and full chord analysis.
- *
- * Roots are pitch classes measured against the key tonic, so borrowed and
- * chromatic chords are handled by their semitone offset rather than requiring a
- * spelled key signature.
- */
-
-/**
- * The three broad harmonic functions of tonal music.
- *
- * @category Functional Harmony
- */
-type HarmonicFunction = 'tonic' | 'subdominant' | 'dominant';
-/**
- * Whether a key's scale has a minor third and no major third (a minor key).
- *
- * @category Functional Harmony
- */
-declare function isMinorKey(key: KeyScale): boolean;
-/**
- * The harmonic function of a chord in a key.
- *
- * The root's offset above the tonic gives the baseline mapping, which follows
- * common-practice major-key function and is a useful approximation in minor and
- * for borrowed chords. Chord quality then refines it where the sonority settles
- * an ambiguity the root offset cannot:
- *
- * - A chord that *sounds* like a dominant — a major third with a minor seventh,
- *   or a diminished-family chord — and is not diatonic to the key has dominant
- *   function when its root resolves down a fifth or by a semitone onto a
- *   diatonic degree. This is what makes an applied dominant (`A7` in C, which
- *   tonicizes ii) and its tritone substitute (`Db7`) read as dominant rather
- *   than inheriting the function of the degree they happen to sit on.
- * - The Neapolitan is subdominant.
- * - A major triad on bVI or bVII of a major key is subdominant — the borrowed
- *   pop cadence chord, distinct from the bVII7 above, which has a seventh and
- *   is a dominant sonority.
- *
- * @param chord The chord.
- * @param key The prevailing key.
- * @returns The harmonic function.
- * @example
- * ```ts
- * import { functionOf, makeChord, majorKey } from '@libraz/libcantus';
- * functionOf(makeChord(9, 'dom7'), majorKey(0)); // 'dominant' — A7 tonicizes ii
- * functionOf(makeChord(10, 'maj'), majorKey(0)); // 'subdominant' — borrowed bVII
- * ```
- * @category Functional Harmony
- */
-declare function functionOf(chord: Chord, key: KeyScale): HarmonicFunction;
-/**
- * The result of {@link analyzeChord}: function, borrowing, and Roman numeral.
- *
- * @category Functional Harmony
- */
-type ChordAnalysis = {
-    function: HarmonicFunction;
-    borrowed: boolean;
-    source: BorrowedSource;
-    roman: string;
-};
-/**
- * Whether every pitch class of a chord belongs to the key's scale.
- *
- * The test is strict against the key's own mode mask: in a natural-minor key
- * the harmonic-minor dominant (major V) is *not* diatonic, since the raised
- * leading tone lies outside the mask. Borrowing predicates treat that case as
- * an in-key alteration separately (see {@link isBorrowedChord}).
- *
- * @param chord The chord to test.
- * @param key The prevailing key.
- * @returns True if all chord pitch classes are scale tones.
- * @category Functional Harmony
- */
-declare function isDiatonic(chord: Chord, key: KeyScale): boolean;
-/**
- * The parallel key: same tonic, opposite mode.
- *
- * A key with a minor third (natural/harmonic/melodic minor, dorian, phrygian)
- * maps to the parallel major; any other key maps to the parallel natural minor.
- *
- * @param key The key to mirror.
- * @returns The parallel major or natural-minor key on the same tonic.
- * @category Functional Harmony
- */
-declare function parallelKey(key: KeyScale): KeyScale;
-/**
- * Analyze a chord in a key: harmonic function, borrowing, and Roman numeral.
- *
- * The function is quality-aware (see the predicates behind it), the source
- * follows {@link borrowedSource}, and the numeral comes from
- * {@link chordToRoman}. `borrowed` is true whenever a source is identified —
- * including the Neapolitan, which the stricter parallel-mode predicate
- * {@link isBorrowedChord} does not count.
- *
- * @param chord The chord to analyze.
- * @param key The prevailing key.
- * @returns The chord analysis.
- * @example
- * ```ts
- * import { analyzeChord, makeChord, majorKey } from '@libraz/libcantus';
- * analyzeChord(makeChord(7, 'dom7'), majorKey(0));
- * // { function: 'dominant', borrowed: false, source: null, roman: 'V7' }
- * ```
- * @category Functional Harmony
- */
-declare function analyzeChord(chord: Chord, key: KeyScale): ChordAnalysis;
-/**
- * The secondary dominant (V7) that tonicizes a scale degree.
- *
- * @param targetDegree 0-based scale degree to tonicize, in 0..6.
- * @param key The prevailing key.
- * @returns A dominant-seventh chord a fifth above the target's root.
- * @throws If `targetDegree` is not an integer in 0..6.
- * @category Functional Harmony
- */
-declare function secondaryDominant(targetDegree: number, key: KeyScale): Chord;
-
-export { type BorrowedSource as B, type Cadence as C, type HarmonicFunction as H, type ChordAnalysis as a, analyzeChord as b, borrowedSource as c, detectCadence as d, isDiatonic as e, functionOf as f, isMinorKey as g, isBorrowedChord as i, parallelKey as p, secondaryDominant as s };

package/dist/index-6VR8-kit.d.ts

@@ -1,143 +0,0 @@
-import { K as KeyScale } from './types-BN6_Q9Kl.js';
-import { C as Chord } from './index-C83mZI1P.js';
-
-/**
- * Severity policy: `strict` counterpoint vs. lenient `pop` voice-leading.
- *
- * @category Arrangement & Analysis
- */
-type SafetyProfile = 'strict' | 'pop';
-/**
- * Overall placeability verdict for a candidate pitch.
- *
- * @category Arrangement & Analysis
- */
-declare enum NoteSafety {
-    Safe = 0,
-    Warning = 1,
-    Dissonant = 2
-}
-/**
- * Bit flags describing why a pitch received its verdict.
- *
- * @category Arrangement & Analysis
- */
-declare enum ReasonFlag {
-    ChordTone = 1,
-    Tension = 2,
-    AvoidNote = 4,
-    ScaleTone = 8,
-    NonScale = 16,
-    OutOfRange = 32,
-    Tritone = 64,
-    LargeLeap = 128,
-    MinorSecond = 256,
-    MajorSeventh = 512,
-    VerticalDissonance = 1024,
-    ParallelPerfect = 2048,
-    HiddenParallel = 4096,
-    VoiceCrossing = 8192,
-    Suspension = 16384,
-    NeedsResolution = 32768
-}
-/**
- * A neighbouring voice's current and previous pitch.
- *
- * @category Arrangement & Analysis
- */
-type VoiceSnapshot = {
-    pitch: number;
-    prevPitch?: number;
-};
-/**
- * Everything needed to evaluate one candidate pitch.
- *
- * @category Arrangement & Analysis
- */
-type SafetyQuery = {
-    profile: SafetyProfile;
-    candidatePitch: number;
-    prevPitch?: number;
-    chord: Chord | null;
-    key: KeyScale;
-    otherVoices: VoiceSnapshot[];
-    strongBeat: boolean;
-    vocalLow?: number;
-    vocalHigh?: number;
-};
-/**
- * The verdict, reason flags, and optional resolution guidance.
- *
- * @category Arrangement & Analysis
- */
-type SafetyResult = {
-    safety: NoteSafety;
-    reasons: number;
-    resolveTo?: number;
-    suggestions?: number[];
-    rationale?: string;
-};
-/**
- * Evaluate the safety of placing a candidate pitch in a voice.
- *
- * Reasons are merged from harmonic context (chord tone / tension / avoid / scale)
- * and counterpoint (vertical dissonance, parallels, voice crossing). The `strict`
- * profile treats avoid notes and parallels as dissonant; `pop` treats them as
- * warnings. The final verdict is the worst severity among the reasons.
- *
- * @param q The candidate and its harmonic/voice-leading context.
- * @returns The verdict, reason bitmask, and optional resolution guidance.
- * @example
- * ```ts
- * import { evaluateSafety, makeChord, majorKey, NoteSafety } from '@libraz/libcantus';
- * const result = evaluateSafety({
- *   profile: 'pop',
- *   candidatePitch: 60, // C over a C major chord
- *   chord: makeChord(0, 'maj'),
- *   key: majorKey(0),
- *   otherVoices: [],
- *   strongBeat: true,
- * });
- * result.safety === NoteSafety.Safe; // true — C is a chord tone
- * ```
- * @category Arrangement & Analysis
- */
-declare function evaluateSafety(q: SafetyQuery, opts?: EvaluateSafetyOptions): SafetyResult;
-/**
- * Options for {@link evaluateSafety}.
- *
- * @category Arrangement & Analysis
- */
-type EvaluateSafetyOptions = {
-    /**
-     * Whether to search for safe replacement pitches when the verdict is not
-     * safe. Turning it off skips up to two dozen extra evaluations per rejected
-     * pitch, which is worth doing when only the verdict is wanted.
-     *
-     * @defaultValue true
-     */
-    suggestions?: boolean;
-};
-/**
- * Enumerate placeable pitches in a range, chord tones first, descending.
- *
- * @param q The safety context minus the candidate pitch.
- * @param pitchLow Lowest MIDI pitch to consider (inclusive).
- * @param pitchHigh Highest MIDI pitch to consider (inclusive).
- * @returns Placeable pitches (non-dissonant), chord tones before others, each group descending.
- * @throws If either bound is non-finite/non-integral, reversed, or exceeds the generation budget.
- * @example
- * ```ts
- * import { enumerateSafePitches, makeChord, majorKey } from '@libraz/libcantus';
- * const pitches = enumerateSafePitches(
- *   { profile: 'pop', chord: makeChord(0, 'maj'), key: majorKey(0), otherVoices: [], strongBeat: true },
- *   60,
- *   72,
- * );
- * pitches; // placeable pitches in [60, 72], chord tones first, each group descending
- * ```
- * @category Arrangement & Analysis
- */
-declare function enumerateSafePitches(q: Omit<SafetyQuery, 'candidatePitch'>, pitchLow: number, pitchHigh: number): number[];
-
-export { type EvaluateSafetyOptions as E, NoteSafety as N, ReasonFlag as R, type SafetyProfile as S, type VoiceSnapshot as V, type SafetyQuery as a, type SafetyResult as b, evaluateSafety as c, enumerateSafePitches as e };