@libraz/libcantus 0.9.1 → 0.9.2

package/dist/function-2bJW1Zp_.d.ts

@@ -0,0 +1,187 @@
+import { K as KeyScale } from './types-MGP29r3t.js';
+import { C as Chord } from './index-CM5W4rcm.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 = 'parallel-minor' | 'parallel-major' | '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, from its root's offset above the
+ * tonic. The mapping follows common-practice major-key function and is a useful
+ * approximation in minor and for borrowed chords.
+ *
+ * @param chord The chord.
+ * @param key The prevailing key.
+ * @returns The harmonic function.
+ * @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.
+ * @param key The prevailing key.
+ * @returns A dominant-seventh chord a fifth above the target's root.
+ * @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-r2sh-jOO.d.cts

@@ -0,0 +1,187 @@
+import { K as KeyScale } from './types-MGP29r3t.cjs';
+import { C as Chord } from './index-BOBXBNwP.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 = 'parallel-minor' | 'parallel-major' | '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, from its root's offset above the
+ * tonic. The mapping follows common-practice major-key function and is a useful
+ * approximation in minor and for borrowed chords.
+ *
+ * @param chord The chord.
+ * @param key The prevailing key.
+ * @returns The harmonic function.
+ * @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.
+ * @param key The prevailing key.
+ * @returns A dominant-seventh chord a fifth above the target's root.
+ * @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 };