@libraz/libcantus 0.9.1 → 0.9.3

package/dist/chunk-FBQK3ZQN.js

@@ -0,0 +1,131 @@
+// src/core/validation/index.ts
+var DEFAULT_GENERATION_BUDGET = 1e6;
+function assertFiniteNumber(value, name) {
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`${name} must be finite; received ${value}`);
+  }
+  return value;
+}
+function assertInteger(value, name, min = Number.MIN_SAFE_INTEGER, max = Number.MAX_SAFE_INTEGER) {
+  assertFiniteNumber(value, name);
+  if (!Number.isSafeInteger(value) || value < min || value > max) {
+    throw new RangeError(`${name} must be an integer in [${min}, ${max}]; received ${value}`);
+  }
+  return value;
+}
+function assertPositiveInt(value, name, max = DEFAULT_GENERATION_BUDGET) {
+  return assertInteger(value, name, 1, max);
+}
+function assertRange(value, min, max, name) {
+  assertFiniteNumber(value, name);
+  if (value < min || value > max) {
+    throw new RangeError(`${name} must be in [${min}, ${max}]; received ${value}`);
+  }
+  return value;
+}
+function assertGenerationBudget(estimated, name, limit = DEFAULT_GENERATION_BUDGET) {
+  assertFiniteNumber(estimated, name);
+  assertPositiveInt(limit, `${name} limit`, Number.MAX_SAFE_INTEGER);
+  if (estimated < 0 || estimated > limit) {
+    throw new RangeError(`${name} exceeds the generation budget ${limit}; received ${estimated}`);
+  }
+  return estimated;
+}
+function assertTimeSignature(ts, name = "time signature") {
+  assertPositiveInt(ts.numerator, `${name}.numerator`);
+  assertPositiveInt(ts.denominator, `${name}.denominator`);
+  if (ts.grouping !== void 0) {
+    if (ts.grouping.length === 0) {
+      throw new RangeError(`${name}.grouping must not be empty`);
+    }
+    let sum = 0;
+    for (let index = 0; index < ts.grouping.length; index += 1) {
+      sum += assertPositiveInt(ts.grouping[index] ?? Number.NaN, `${name}.grouping[${index}]`);
+    }
+    const compound = ts.numerator % 3 === 0 && ts.numerator > 3;
+    const pulses = compound ? ts.numerator / 3 : ts.numerator;
+    if (sum !== pulses) {
+      throw new RangeError(`${name}.grouping must sum to ${pulses}; received ${sum}`);
+    }
+  }
+  return ts;
+}
+function assertNoteEvent(event, name = "note event", options = {}) {
+  assertFiniteNumber(event.pitch, `${name}.pitch`);
+  assertRange(event.startBeat, 0, Number.MAX_SAFE_INTEGER, `${name}.startBeat`);
+  assertRange(
+    event.durationBeat,
+    options.allowNonPositiveDuration ? -Number.MAX_SAFE_INTEGER : Number.MIN_VALUE,
+    Number.MAX_SAFE_INTEGER,
+    `${name}.durationBeat`
+  );
+  if (!options.allowNonPositiveDuration && event.durationBeat <= 0) {
+    throw new RangeError(`${name}.durationBeat must be positive; received ${event.durationBeat}`);
+  }
+  if (event.velocity !== void 0) {
+    assertRange(event.velocity, 0, 127, `${name}.velocity`);
+  }
+  return event;
+}
+function assertNoteEvents(events, name = "note events", options = {}) {
+  assertGenerationBudget(events.length, `${name} count`, options.budget);
+  for (let index = 0; index < events.length; index += 1) {
+    const event = events[index];
+    if (event !== void 0) {
+      assertNoteEvent(event, `${name}[${index}]`, options);
+    }
+  }
+  return events;
+}
+
+// src/core/interval/index.ts
+var IntervalQuality = /* @__PURE__ */ ((IntervalQuality2) => {
+  IntervalQuality2[IntervalQuality2["PerfectConsonance"] = 0] = "PerfectConsonance";
+  IntervalQuality2[IntervalQuality2["ImperfectConsonance"] = 1] = "ImperfectConsonance";
+  IntervalQuality2[IntervalQuality2["Dissonance"] = 2] = "Dissonance";
+  return IntervalQuality2;
+})(IntervalQuality || {});
+function simpleInterval(semitones) {
+  return Math.abs(semitones) % 12;
+}
+function classifyInterval(semitones, twoVoice = true) {
+  const pc = simpleInterval(semitones);
+  if (pc === 0 || pc === 7) {
+    return 0 /* PerfectConsonance */;
+  }
+  if (pc === 3 || pc === 4 || pc === 8 || pc === 9) {
+    return 1 /* ImperfectConsonance */;
+  }
+  if (pc === 5) {
+    return twoVoice ? 2 /* Dissonance */ : 1 /* ImperfectConsonance */;
+  }
+  return 2 /* Dissonance */;
+}
+function isPerfectInterval(semitones) {
+  const pc = simpleInterval(semitones);
+  return pc === 0 || pc === 7;
+}
+function isConsonantInterval(semitones, twoVoice = true) {
+  const pc = simpleInterval(semitones);
+  if (pc === 5) {
+    return !twoVoice;
+  }
+  return pc === 0 || pc === 3 || pc === 4 || pc === 7 || pc === 8 || pc === 9;
+}
+
+export {
+  DEFAULT_GENERATION_BUDGET,
+  assertFiniteNumber,
+  assertInteger,
+  assertPositiveInt,
+  assertRange,
+  assertGenerationBudget,
+  assertTimeSignature,
+  assertNoteEvent,
+  assertNoteEvents,
+  IntervalQuality,
+  classifyInterval,
+  isPerfectInterval,
+  isConsonantInterval
+};
+//# sourceMappingURL=chunk-FBQK3ZQN.js.map

package/dist/chunk-FBQK3ZQN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/validation/index.ts","../src/core/interval/index.ts"],"sourcesContent":["import type { TimeSignature } from '../meter/index.js';\nimport type { NoteEvent } from '../types.js';\n\n/** Default upper bound for synchronous event/window/candidate generation. */\nexport const DEFAULT_GENERATION_BUDGET = 1_000_000;\n\n/** Require a finite JavaScript number and return it unchanged. */\nexport function assertFiniteNumber(value: number, name: string): number {\n  if (!Number.isFinite(value)) {\n    throw new RangeError(`${name} must be finite; received ${value}`);\n  }\n  return value;\n}\n\n/** Require an integer in the inclusive range `[min, max]`. */\nexport function assertInteger(\n  value: number,\n  name: string,\n  min = Number.MIN_SAFE_INTEGER,\n  max = Number.MAX_SAFE_INTEGER,\n): number {\n  assertFiniteNumber(value, name);\n  if (!Number.isSafeInteger(value) || value < min || value > max) {\n    throw new RangeError(`${name} must be an integer in [${min}, ${max}]; received ${value}`);\n  }\n  return value;\n}\n\n/** Require a positive safe integer, optionally capped by `max`. */\nexport function assertPositiveInt(\n  value: number,\n  name: string,\n  max = DEFAULT_GENERATION_BUDGET,\n): number {\n  return assertInteger(value, name, 1, max);\n}\n\n/** Require a finite number in the inclusive range `[min, max]`. */\nexport function assertRange(value: number, min: number, max: number, name: string): number {\n  assertFiniteNumber(value, name);\n  if (value < min || value > max) {\n    throw new RangeError(`${name} must be in [${min}, ${max}]; received ${value}`);\n  }\n  return value;\n}\n\n/** Reject work estimates that would exceed a synchronous generation budget. */\nexport function assertGenerationBudget(\n  estimated: number,\n  name: string,\n  limit = DEFAULT_GENERATION_BUDGET,\n): number {\n  assertFiniteNumber(estimated, name);\n  assertPositiveInt(limit, `${name} limit`, Number.MAX_SAFE_INTEGER);\n  if (estimated < 0 || estimated > limit) {\n    throw new RangeError(`${name} exceeds the generation budget ${limit}; received ${estimated}`);\n  }\n  return estimated;\n}\n\n/** Validate a time signature, including additive grouping, before any early return. */\nexport function assertTimeSignature(ts: TimeSignature, name = 'time signature'): TimeSignature {\n  assertPositiveInt(ts.numerator, `${name}.numerator`);\n  assertPositiveInt(ts.denominator, `${name}.denominator`);\n  if (ts.grouping !== undefined) {\n    if (ts.grouping.length === 0) {\n      throw new RangeError(`${name}.grouping must not be empty`);\n    }\n    let sum = 0;\n    for (let index = 0; index < ts.grouping.length; index += 1) {\n      sum += assertPositiveInt(ts.grouping[index] ?? Number.NaN, `${name}.grouping[${index}]`);\n    }\n    const compound = ts.numerator % 3 === 0 && ts.numerator > 3;\n    const pulses = compound ? ts.numerator / 3 : ts.numerator;\n    if (sum !== pulses) {\n      throw new RangeError(`${name}.grouping must sum to ${pulses}; received ${sum}`);\n    }\n  }\n  return ts;\n}\n\n/** Validate the finite fields of one timeline note event. */\nexport function assertNoteEvent(\n  event: NoteEvent,\n  name = 'note event',\n  options: { allowNonPositiveDuration?: boolean } = {},\n): NoteEvent {\n  assertFiniteNumber(event.pitch, `${name}.pitch`);\n  assertRange(event.startBeat, 0, Number.MAX_SAFE_INTEGER, `${name}.startBeat`);\n  assertRange(\n    event.durationBeat,\n    options.allowNonPositiveDuration ? -Number.MAX_SAFE_INTEGER : Number.MIN_VALUE,\n    Number.MAX_SAFE_INTEGER,\n    `${name}.durationBeat`,\n  );\n  if (!options.allowNonPositiveDuration && event.durationBeat <= 0) {\n    throw new RangeError(`${name}.durationBeat must be positive; received ${event.durationBeat}`);\n  }\n  if (event.velocity !== undefined) {\n    assertRange(event.velocity, 0, 127, `${name}.velocity`);\n  }\n  return event;\n}\n\n/** Validate an event array and its allocation budget without copying it. */\nexport function assertNoteEvents(\n  events: NoteEvent[],\n  name = 'note events',\n  options: { allowNonPositiveDuration?: boolean; budget?: number } = {},\n): NoteEvent[] {\n  assertGenerationBudget(events.length, `${name} count`, options.budget);\n  for (let index = 0; index < events.length; index += 1) {\n    const event = events[index];\n    if (event !== undefined) {\n      assertNoteEvent(event, `${name}[${index}]`, options);\n    }\n  }\n  return events;\n}\n","/**\n * Counterpoint classification of a harmonic interval.\n *\n * @category Pitch & Intervals\n */\nexport enum IntervalQuality {\n  PerfectConsonance = 0,\n  ImperfectConsonance = 1,\n  Dissonance = 2,\n}\n\n/** Reduce an interval to a simple interval class in the range [0, 11]. */\nfunction simpleInterval(semitones: number): number {\n  return Math.abs(semitones) % 12;\n}\n\n/**\n * Classify an interval for counterpoint evaluation.\n *\n * The interval is reduced modulo 12, so compound intervals classify as their\n * simple equivalents. The perfect fourth (5) is context-dependent: with\n * `twoVoice` (the default) it classifies as a dissonance, matching\n * {@link isConsonantInterval}; otherwise it is an imperfect consonance.\n *\n * @param semitones Interval size in semitones (may be negative or compound).\n * @param twoVoice When true, the perfect fourth is treated as dissonant.\n * @returns The counterpoint quality of the interval.\n * @example\n * ```ts\n * import { classifyInterval, IntervalQuality } from '@libraz/libcantus';\n * classifyInterval(7); // IntervalQuality.PerfectConsonance\n * classifyInterval(5); // IntervalQuality.Dissonance (two-voice)\n * classifyInterval(5, false); // IntervalQuality.ImperfectConsonance\n * ```\n * @category Pitch & Intervals\n */\nexport function classifyInterval(semitones: number, twoVoice = true): IntervalQuality {\n  const pc = simpleInterval(semitones);\n  if (pc === 0 || pc === 7) {\n    return IntervalQuality.PerfectConsonance;\n  }\n  if (pc === 3 || pc === 4 || pc === 8 || pc === 9) {\n    return IntervalQuality.ImperfectConsonance;\n  }\n  if (pc === 5) {\n    return twoVoice ? IntervalQuality.Dissonance : IntervalQuality.ImperfectConsonance;\n  }\n  return IntervalQuality.Dissonance;\n}\n\n/**\n * Test whether an interval is a perfect interval (unison/octave or fifth).\n *\n * @param semitones Interval size in semitones (may be negative or compound).\n * @returns True for the unison/octave (0) and the perfect fifth (7) mod 12.\n * @category Pitch & Intervals\n */\nexport function isPerfectInterval(semitones: number): boolean {\n  const pc = simpleInterval(semitones);\n  return pc === 0 || pc === 7;\n}\n\n/**\n * Test whether an interval is consonant.\n *\n * The consonant set is {0, 3, 4, 5, 7, 8, 9} mod 12. In two-voice counterpoint\n * the perfect fourth (5) is treated as a dissonance, so `twoVoice` set to true\n * excludes it.\n *\n * @param semitones Interval size in semitones (may be negative or compound).\n * @param twoVoice When true, the perfect fourth is treated as dissonant.\n * @returns True if the interval is consonant in the given context.\n * @category Pitch & Intervals\n */\nexport function isConsonantInterval(semitones: number, twoVoice = true): boolean {\n  const pc = simpleInterval(semitones);\n  if (pc === 5) {\n    return !twoVoice;\n  }\n  return pc === 0 || pc === 3 || pc === 4 || pc === 7 || pc === 8 || pc === 9;\n}\n"],"mappings":"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","names":["IntervalQuality"]}