@libraz/libcantus 1.0.0 → 1.1.0

package/dist/{index-Cj49F892.d.ts → index-D_hzxD8w.d.cts}

@@ -1,4 +1,4 @@
-import { P as ParseResult } from './index-B9MNZboQ.js';
+import { P as ParseResult } from './index-Cy15oTvh.cjs';
 
 /**
  * Meter arithmetic shared by the meter module and the validation guards.
@@ -83,6 +83,11 @@ type MeterChange = {
  * The first entry also governs everything before it, which is what reads a
  * pickup written at negative beats in the signature the piece opens in.
  *
+ * Beat 0 is the first downbeat here as everywhere else: the opening signature
+ * lays its bar lines from beat 0 whatever beat the first entry is written at, so
+ * a map opening at the pickup it covers numbers its bars exactly as the bare
+ * signature does. Every later entry starts a bar at the beat it takes effect.
+ *
  * @category Rhythm & Meter
  */
 type MeterMap = MeterChange[];
@@ -123,7 +128,10 @@ type MeterLike = string | TimeSignature | MeterMap | {
  *   value whose `toJSON` returns one of those.
  * @param name What the meter is called in an error message, so a caller that
  *   holds several of them hears which one was malformed.
- * @returns The validated signature, or the validated map.
+ * @returns The validated signature, or the validated map, freshly allocated
+ *   down to every grouping array — so a caller may keep and edit what it gets
+ *   back without editing the meter it passed in, and without any two calls
+ *   handing out the same object.
  * @throws If the value names no meter, or the meter it names is malformed.
  */
 declare function toMeterData(value: MeterLike, name?: string): MeterData;
@@ -186,17 +194,23 @@ declare function tryParseTimeSignature(text: string): ParseResult<TimeSignature>
  *
  * The additive form is what {@link parseTimeSignature} reads back, and it adds
  * its terms to get the numerator — so only a grouping written in denominator
- * units can be rendered that way. A grouping counted in main pulses (9/8 as
- * `[1, 1, 1]`, 12/8 as `[2, 2]`) would come back as a different bar, so it
- * falls back to the plain form, which those groupings cost nothing: they select
- * the same reading the bare signature does.
+ * units can be rendered that way. A grouping counted in main pulses whose groups
+ * are all the same length (9/8 as `[1, 1, 1]`, 12/8 as `[2, 2]`) states the
+ * division the bare signature already has, so it falls back to the plain form at
+ * no cost. One whose groups differ (12/8 as `[1, 1, 2]`) states an accent no
+ * signature text can carry, and asking for the additive form of it is refused
+ * rather than answered with a bar that weighs its pulses differently.
  *
  * The plain form drops the grouping, so a round trip through it reads 7/8 as
  * flat rather than as 2+2+3; ask for the additive form to keep it.
  *
- * @param ts The time signature.
+ * @param ts The time signature, in any form that names one; a meter map is
+ *   rendered as the signature it opens in.
  * @param opts Set `grouping: true` to render an additive grouping.
  * @returns The formatted signature.
+ * @throws If `grouping: true` is asked of a grouping that no signature text can
+ *   spell: one counted in main pulses, on a compound numerator, whose groups are
+ *   not all the same length.
  * @example
  * ```ts
  * import { formatTimeSignature } from '@libraz/libcantus';
@@ -206,7 +220,7 @@ declare function tryParseTimeSignature(text: string): ParseResult<TimeSignature>
  * ```
  * @category Rhythm & Meter
  */
-declare function formatTimeSignature(ts: TimeSignature, opts?: {
+declare function formatTimeSignature(ts: MeterLike, opts?: {
     grouping?: boolean;
 }): string;
 /**
@@ -217,19 +231,27 @@ declare function formatTimeSignature(ts: TimeSignature, opts?: {
  * is a signature whose {@link TimeSignature.grouping} selects the additive
  * reading (9/8 as 2+2+2+3).
  *
- * @param ts The time signature.
+ * @param ts The time signature, in any form that names one; a meter map is read
+ *   as the signature it opens in.
  * @returns True for compound meters.
  * @category Rhythm & Meter
  */
-declare function isCompound(ts: TimeSignature): boolean;
+declare function isCompound(ts: MeterLike): boolean;
 /**
  * Length of a bar in quarter-note beats.
  *
- * @param ts The time signature.
+ * @param ts The time signature, in any form that names one; a meter map has no
+ *   single bar length, so it is read as the signature it opens in. Ask
+ *   {@link beatsPerBarAt} for the bar a given beat falls in.
  * @returns The bar length in quarter notes.
+ * @example
+ * ```ts
+ * import { beatsPerBar } from '@libraz/libcantus';
+ * beatsPerBar('6/8'); // 3
+ * ```
  * @category Rhythm & Meter
  */
-declare function beatsPerBar(ts: TimeSignature): number;
+declare function beatsPerBar(ts: MeterLike): number;
 /**
  * The time signature in force at a beat.
  *
@@ -284,6 +306,12 @@ declare function barIndexAt(beatInQuarters: number, meter: MeterLike): number;
  * The meter-map counterpart of {@link beatsPerBar}, which answers for one
  * signature and so cannot be asked about a piece that changes meter.
  *
+ * The bar the beat is in, not the bar its signature nominally has: a change of
+ * meter starts a new bar, so a bar interrupted by one is shorter than its own
+ * signature says. Reading the signature's own length there would put the end of
+ * the bar past where the next one begins, and every span measured in bars from
+ * that point on would be counted against a bar length the music never had.
+ *
  * @param beatInQuarters Absolute position in quarter-note beats.
  * @param meter A single signature, or the piece's meter map.
  * @returns The bar length in quarter notes.
@@ -300,7 +328,9 @@ declare function beatsPerBarAt(beatInQuarters: number, meter: MeterLike): number
  *
  * @param opts The options carrying `ts`, `meters`, or neither.
  * @param name What the options belong to, for the error message.
- * @returns The meter map to analyse against; 4/4 throughout when neither is given.
+ * @returns The meter map to analyse against, freshly allocated down to every
+ *   signature and grouping array, so writing to it changes nothing another
+ *   caller reads; 4/4 throughout when neither `ts` nor `meters` is given.
  * @throws If both `ts` and `meters` are given, or the map is malformed.
  * @example
  * ```ts
@@ -311,8 +341,8 @@ declare function beatsPerBarAt(beatInQuarters: number, meter: MeterLike): number
  * @category Rhythm & Meter
  */
 declare function resolveMeters(opts: {
-    ts?: TimeSignature;
-    meters?: MeterMap;
+    ts?: MeterLike;
+    meters?: MeterLike;
 }, name?: string): MeterMap;
 /**
  * Number of main pulses (felt beats) per bar: the numerator for simple meters,
@@ -324,11 +354,12 @@ declare function resolveMeters(opts: {
  * {@link TimeSignature.grouping}; {@link metricWeight} then accents each
  * group's head pulse.
  *
- * @param ts The time signature.
+ * @param ts The time signature, in any form that names one; a meter map is read
+ *   as the signature it opens in.
  * @returns The pulse count per bar.
  * @category Rhythm & Meter
  */
-declare function pulsesPerBar(ts: TimeSignature): number;
+declare function pulsesPerBar(ts: MeterLike): number;
 /**
  * Convert an absolute quarter-note position to a bar index and in-bar offset.
  *
@@ -351,16 +382,17 @@ declare function beatToBarPosition(beatInQuarters: number, meter: MeterLike): Ba
  * denominator unit in an additive metre. Position displays, click tracks, and
  * score export are all written against this length.
  *
- * @param ts The time signature.
+ * @param ts The time signature, in any form that names one; a meter map is read
+ *   as the signature it opens in.
  * @returns The pulse length in quarter-note beats.
  * @example
  * ```ts
- * import { parseTimeSignature, pulseBeats } from '@libraz/libcantus';
- * pulseBeats(parseTimeSignature('6/8')); // 1.5
+ * import { pulseBeats } from '@libraz/libcantus';
+ * pulseBeats('6/8'); // 1.5
  * ```
  * @category Rhythm & Meter
  */
-declare function pulseBeats(ts: TimeSignature): number;
+declare function pulseBeats(ts: MeterLike): number;
 /**
  * The felt-beat number of a bar position, 1-based.
  *
@@ -391,11 +423,16 @@ declare function barPositionToPulse(pos: BarPosition, meter: MeterLike): number;
  * @param beatInQuarters Absolute position in quarter-note beats.
  * @param meter A single signature, or the piece's meter map.
  * @param decimals Digits of the fractional beat to keep.
- * @returns The formatted position, e.g. `'3.2'` for bar 3, felt beat 2.
+ * @returns The formatted position in one of two forms: `bar.beat` on a felt
+ *   beat, e.g. `'3.2'` for bar 3, felt beat 2; and `bar.beat+fraction` between
+ *   felt beats, e.g. `'3.2+0.5'` halfway from the second felt beat to the third.
+ *   A reader of these strings has to take both, since most onsets of an ordinary
+ *   piece fall between pulses.
  * @example
  * ```ts
  * import { formatBarPosition, parseTimeSignature } from '@libraz/libcantus';
  * formatBarPosition(7.5, parseTimeSignature('6/8')); // '3.2'
+ * formatBarPosition(8.25, parseTimeSignature('6/8')); // '3.2+0.5'
  * ```
  * @category Rhythm & Meter
  */
@@ -425,7 +462,7 @@ declare function barPositionToBeat(pos: BarPosition, meter: MeterLike): number;
  * an ungrouped bar rather than accenting every group head.
  *
  * Given a meter map, the weight follows the signature in force at that beat, so
- * beat 5 of a piece is a mid-bar accent in 4/4 and a plain main pulse in 3/4.
+ * beat 2 of a piece is a mid-bar accent in 4/4 and a plain main pulse in 3/4.
  * The downbeat is beat 0 however much pickup precedes it, so a note in the
  * pickup weighs as the upbeat it is rather than as a downbeat.
  *