tuning-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NewTonality
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# tuning-core
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.2.15. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.

package/benches/fraction-performance.bench.ts

@@ -0,0 +1,141 @@
+import Fraction from 'fraction.js';
+
+/**
+ * Performance benchmark for Fraction.js constructor with different input types.
+ * Tests creating 10,000 Fraction objects from various input formats.
+ */
+
+const ITERATIONS = 100_000_000;
+
+// A relatively complex ratio for testing
+const COMPLEX_RATIO_STRING = '440';
+const COMPLEX_RATIO_FLOAT = 440;
+const COMPLEX_RATIO_ARRAY: [number, number] = [440, 1];
+const COMPLEX_RATIO_OBJECT = { n: 440, d: 1 };
+const COMPLEX_RATIO_FRACTION = new Fraction(440, 1);
+
+interface BenchmarkResult {
+  inputType: string;
+  timeMs: number;
+  timePerOpNs: number;
+  iterations: number;
+}
+
+function benchmark(name: string, fn: () => void): BenchmarkResult {
+  // Warmup
+  for (let i = 0; i < 100; i++) {
+    fn();
+  }
+
+  // Actual benchmark
+  const start = performance.now();
+  for (let i = 0; i < ITERATIONS; i++) {
+    fn();
+  }
+  const end = performance.now();
+
+  const timeMs = end - start;
+  const timePerOpNs = (timeMs / ITERATIONS) * 1_000_000; // Convert to nanoseconds
+
+  return {
+    inputType: name,
+    timeMs,
+    timePerOpNs,
+    iterations: ITERATIONS,
+  };
+}
+
+function runBenchmarks(): BenchmarkResult[] {
+  const results: BenchmarkResult[] = [];
+
+  // Test 1: String input
+  results.push(
+    benchmark('String ("440")', () => {
+      new Fraction(COMPLEX_RATIO_STRING);
+    })
+  );
+
+  // Test 2: Float input
+  results.push(
+    benchmark('Float (440)', () => {
+      new Fraction(COMPLEX_RATIO_FLOAT);
+    })
+  );
+
+  // Test 3: Array input
+  results.push(
+    benchmark('Array ([440, 1])', () => {
+      new Fraction(COMPLEX_RATIO_ARRAY);
+    })
+  );
+
+  // Test 4: Object input
+  results.push(
+    benchmark('Object ({n: 440, d: 1})', () => {
+      new Fraction(COMPLEX_RATIO_OBJECT);
+    })
+  );
+
+  // Test 5: Fraction input (copying)
+  results.push(
+    benchmark('Fraction (copying existing)', () => {
+      new Fraction(COMPLEX_RATIO_FRACTION);
+    })
+  );
+
+  return results;
+}
+
+function formatResults(results: BenchmarkResult[]): void {
+  console.log('\n' + '='.repeat(80));
+  console.log(`Fraction.js Constructor Performance Benchmark`);
+  console.log(`Iterations per test: ${ITERATIONS.toLocaleString()}`);
+  console.log('='.repeat(80));
+  console.log('\n');
+
+  // Find the fastest
+  const fastest = results.reduce((min, r) => (r.timeMs < min.timeMs ? r : min), results[0]!);
+
+  console.log('Results:');
+  console.log('-'.repeat(80));
+  console.log(
+    `${'Input Type'.padEnd(35)} ${'Total Time (ms)'.padEnd(18)} ${'Time per Op (ns)'.padEnd(18)} ${'Relative Speed'.padEnd(15)}`
+  );
+  console.log('-'.repeat(80));
+
+  for (const result of results) {
+    const relativeSpeed = (result.timeMs / fastest.timeMs).toFixed(2) + 'x';
+    const timeMsStr = result.timeMs.toFixed(2);
+    const timePerOpStr = result.timePerOpNs.toFixed(2);
+
+    console.log(
+      `${result.inputType.padEnd(35)} ${timeMsStr.padEnd(18)} ${timePerOpStr.padEnd(18)} ${relativeSpeed.padEnd(15)}`
+    );
+  }
+
+  console.log('-'.repeat(80));
+  console.log(`\nFastest: ${fastest.inputType} (${fastest.timeMs.toFixed(2)} ms)`);
+  console.log('='.repeat(80) + '\n');
+}
+
+// Run benchmarks
+const results = runBenchmarks();
+formatResults(results);
+
+// Verify all produce the same result
+console.log('Verification: All input types produce the same Fraction:');
+const f1 = new Fraction(COMPLEX_RATIO_STRING);
+const f2 = new Fraction(COMPLEX_RATIO_FLOAT);
+const f3 = new Fraction(COMPLEX_RATIO_ARRAY);
+const f4 = new Fraction(COMPLEX_RATIO_OBJECT);
+const f5 = new Fraction(COMPLEX_RATIO_FRACTION);
+
+console.log(`String:   ${f1.toFraction()} = ${f1.valueOf()}`);
+console.log(`Float:    ${f2.toFraction()} = ${f2.valueOf()}`);
+console.log(`Array:    ${f3.toFraction()} = ${f3.valueOf()}`);
+console.log(`Object:   ${f4.toFraction()} = ${f4.valueOf()}`);
+console.log(`Fraction: ${f5.toFraction()} = ${f5.valueOf()}`);
+
+const allEqual =
+  f1.equals(f2) && f2.equals(f3) && f3.equals(f4) && f4.equals(f5);
+console.log(`\nAll results equal: ${allEqual ? '✓' : '✗'}`);

package/benches/spectrum-serialization.bench.ts

@@ -0,0 +1,167 @@
+import { Spectrum } from '../classes';
+import { type SpectrumData } from '../lib';
+
+/**
+ * Performance benchmark for Spectrum serialization and deserialization.
+ * Tests creating a Spectrum with fundamental of 10 and 100 harmonics,
+ * then performing 1000 serialization/deserialization passes.
+ */
+
+const ITERATIONS = 10_000;
+const HARMONIC_COUNT = 100;
+const FUNDAMENTAL = 1234/567;
+
+// Create a test spectrum with fundamental 10 and 100 harmonics
+function createTestSpectrum(): Spectrum {
+  const spectrum = new Spectrum();
+  
+  for (let i = 1; i <= HARMONIC_COUNT; i++) {
+    const frequency = FUNDAMENTAL * i;
+    const amplitude = 1 / i; // Natural decay
+    const phase = 0;
+    spectrum.add(frequency, amplitude, phase);
+  }
+  
+  return spectrum;
+}
+
+interface BenchmarkResult {
+  operation: string;
+  timeMs: number;
+  timePerOpMs: number;
+  iterations: number;
+}
+
+function benchmark(name: string, fn: () => void): BenchmarkResult {
+  // Warmup
+  for (let i = 0; i < 10; i++) {
+    fn();
+  }
+
+  // Actual benchmark
+  const start = performance.now();
+  for (let i = 0; i < ITERATIONS; i++) {
+    fn();
+  }
+  const end = performance.now();
+
+  const timeMs = end - start;
+  const timePerOpMs = timeMs / ITERATIONS;
+
+  return {
+    operation: name,
+    timeMs,
+    timePerOpMs,
+    iterations: ITERATIONS,
+  };
+}
+
+function runBenchmarks(): BenchmarkResult[] {
+  const results: BenchmarkResult[] = [];
+  
+  // Create test spectrum once
+  const testSpectrum = createTestSpectrum();
+  console.log(`Created test spectrum with ${testSpectrum.size} harmonics`);
+  console.log(`Fundamental: ${FUNDAMENTAL} Hz, Highest harmonic: ${FUNDAMENTAL * HARMONIC_COUNT} Hz\n`);
+
+  // Benchmark 1: Serialization (toJSON)
+  let serializedData: SpectrumData | null = null;
+  results.push(
+    benchmark('Serialization (toJSON)', () => {
+      serializedData = testSpectrum.toJSON();
+    })
+  );
+
+  if (!serializedData) {
+    throw new Error('Serialization failed');
+  }
+
+  // Benchmark 2: Deserialization (new Spectrum(data))
+  results.push(
+    benchmark('Deserialization (new Spectrum(data))', () => {
+      new Spectrum(serializedData!);
+    })
+  );
+
+  // Benchmark 3: Round-trip (serialize + deserialize)
+  results.push(
+    benchmark('Round-trip (serialize + deserialize)', () => {
+      const data = testSpectrum.toJSON();
+      new Spectrum(data);
+    })
+  );
+
+  // Benchmark 4: Verify correctness
+  const deserialized = new Spectrum(serializedData);
+  const isEqual = testSpectrum.size === deserialized.size &&
+    Array.from(testSpectrum.getHarmonics()).every((h1, i) => {
+      const h2 = deserialized.getHarmonics()[i];
+      if (!h2) return false;
+      return h1.frequencyStr === h2.frequencyStr &&
+        Math.abs(h1.amplitude - h2.amplitude) < 1e-10 &&
+        Math.abs(h1.phase - h2.phase) < 1e-10;
+    });
+  
+  console.log(`Verification: Round-trip preserves data correctly: ${isEqual ? '✓' : '✗'}\n`);
+
+  return results;
+}
+
+function formatResults(results: BenchmarkResult[]): void {
+  console.log('='.repeat(80));
+  console.log(`Spectrum Serialization/Deserialization Performance Benchmark`);
+  console.log(`Test Spectrum: ${HARMONIC_COUNT} harmonics, fundamental ${FUNDAMENTAL} Hz`);
+  console.log(`Iterations per test: ${ITERATIONS.toLocaleString()}`);
+  console.log('='.repeat(80));
+  console.log('\n');
+
+  // Find the fastest
+  const fastest = results.reduce((min, r) => (r.timeMs < min.timeMs ? r : min), results[0]!);
+
+  console.log('Results:');
+  console.log('-'.repeat(80));
+  console.log(
+    `${'Operation'.padEnd(45)} ${'Total Time (ms)'.padEnd(18)} ${'Time per Op (ms)'.padEnd(18)} ${'Relative Speed'.padEnd(15)}`
+  );
+  console.log('-'.repeat(80));
+
+  for (const result of results) {
+    const relativeSpeed = (result.timeMs / fastest.timeMs).toFixed(2) + 'x';
+    const timeMsStr = result.timeMs.toFixed(2);
+    const timePerOpStr = result.timePerOpMs.toFixed(4);
+
+    console.log(
+      `${result.operation.padEnd(45)} ${timeMsStr.padEnd(18)} ${timePerOpStr.padEnd(18)} ${relativeSpeed.padEnd(15)}`
+    );
+  }
+
+  console.log('-'.repeat(80));
+  console.log(`\nFastest: ${fastest.operation} (${fastest.timeMs.toFixed(2)} ms)`);
+  console.log('='.repeat(80) + '\n');
+
+  // Additional statistics
+  const serialization = results.find(r => r.operation.includes('Serialization'));
+  const deserialization = results.find(r => r.operation.includes('Deserialization'));
+  const roundTrip = results.find(r => r.operation.includes('Round-trip'));
+
+  if (serialization && deserialization && roundTrip) {
+    console.log('Breakdown:');
+    console.log(`  Serialization: ${serialization.timePerOpMs.toFixed(4)} ms per operation`);
+    console.log(`  Deserialization: ${deserialization.timePerOpMs.toFixed(4)} ms per operation`);
+    console.log(`  Round-trip: ${roundTrip.timePerOpMs.toFixed(4)} ms per operation`);
+    console.log(`  Expected round-trip: ${(serialization.timePerOpMs + deserialization.timePerOpMs).toFixed(4)} ms`);
+    console.log(`  Overhead: ${(roundTrip.timePerOpMs - serialization.timePerOpMs - deserialization.timePerOpMs).toFixed(4)} ms\n`);
+  }
+}
+
+// Run benchmarks
+const results = runBenchmarks();
+formatResults(results);
+
+// Show sample of serialized data
+const sampleSpectrum = createTestSpectrum();
+const sampleData = sampleSpectrum.toJSON();
+console.log('Sample serialized data (first 3 harmonics):');
+console.log(JSON.stringify(sampleData.slice(0, 3), null, 2));
+console.log(`\nTotal harmonics in serialized data: ${sampleData.length}`);
+console.log(`Average size per harmonic: ${(JSON.stringify(sampleData).length / sampleData.length).toFixed(2)} bytes`);

package/classes/Harmonic.ts

@@ -0,0 +1,183 @@
+import Fraction, { type FractionInput } from 'fraction.js';
+import { type HarmonicData, isHarmonicData } from '../lib';
+
+/**
+ * Represents a single partial in an arbitrary spectrum.
+ * The name Harmonic does not imply a harmonic series but chosen over 
+ * Partial to avoid coflict with the TypeScript's Partial type.
+ * Mutable for better real-time performance.
+ * Frequencies are stored as rational numbers for exact tuning mathematics.
+ * 
+ * The constructor accepts either a HarmonicData object or individual parameters.
+ * 
+ * @example
+ * // Using HarmonicData object
+ * const harmonic1 = new Harmonic({
+ *   frequency: 440,
+ *   amplitude: 0.5,
+ *   phase: Math.PI
+ * });
+ * 
+ * @example
+ * // Using individual parameters
+ * const harmonic2 = new Harmonic(440, 0.5, Math.PI);
+ * const harmonic3 = new Harmonic("440"); // amplitude defaults to 1, phase defaults to 0
+ * const harmonic4 = new Harmonic("440 1/3"); // frequency as a string with whole and fractional part
+ * const harmonic4 = new Harmonic([107, 100]); // frequency as a fraction of two integers 107/100
+ * // Note that frequency is treated as a rational number from Fraction.js lib
+ * // so it accepts FractionInput type
+ */
+export class Harmonic {
+  private _frequency: Fraction;  // Frequency as ratio (e.g., 3/2 for perfect fifth)
+  private _amplitude: number;    // 0-1 normalized
+  private _phase: number;        // 0-2π radians
+
+  /**
+   * Get frequency as a Fraction
+   */
+  get frequency(): Fraction {
+    return this._frequency;
+  }
+
+  /**
+   * Get frequency as a float number
+   */
+  get frequencyNum(): number {
+    return this._frequency.valueOf();
+  }
+
+  /**
+   * Get frequency as a simplified fraction string (e.g., "3/2")
+   */
+  get frequencyStr(): string {
+    return this._frequency.toFraction();
+  }
+
+  /**
+   * Get amplitude (0-1 normalized)
+   */
+  get amplitude(): number {
+    return this._amplitude;
+  }
+
+  /**
+   * Get phase (0-2π radians)
+   */
+  get phase(): number {
+    return this._phase;
+  }
+
+  constructor(data: HarmonicData);
+  constructor(frequency: FractionInput, amplitude?: number, phase?: number);
+  constructor(frequencyOrData: FractionInput | HarmonicData, amplitude = 1, phase = 0) {
+    if (isHarmonicData(frequencyOrData)) {
+      // HarmonicData case
+      this._frequency = new Fraction(frequencyOrData.frequency);
+      this._amplitude = frequencyOrData.amplitude;
+      this._phase = frequencyOrData.phase;
+    } else {
+      // Original case: frequency, amplitude, phase
+      this._frequency = new Fraction(frequencyOrData);
+      this._amplitude = amplitude ?? 1;
+      this._phase = phase ?? 0;
+    }
+
+    this.validate();
+  }
+
+  private validate(): void {
+    if (this._frequency.compare(0) <= 0) {
+      throw new Error('Frequency must be positive');
+    }
+    if (this._amplitude < 0 || this._amplitude > 1) {
+      throw new Error('Amplitude must be between 0 and 1');
+    }
+    if (this._phase < 0 || this._phase >= 2 * Math.PI) {
+      throw new Error('Phase must be between 0 and 2π');
+    }
+  }
+
+  /**
+   * Sets frequency to the provided value
+   */
+  setFrequency(frequency: FractionInput): this {
+    this._frequency = new Fraction(frequency);
+    if (this._frequency.compare(0) <= 0) {
+      throw new Error('Frequency must be positive');
+    }
+    return this;
+  }
+
+  /**
+   * Sets amplitude (0-1)
+   */
+  setAmplitude(amplitude: number): this {
+    if (amplitude < 0 || amplitude > 1) {
+      throw new Error('Amplitude must be between 0 and 1');
+    }
+    this._amplitude = amplitude;
+    return this;
+  }
+
+  /**
+   * Sets phase (0-2π)
+   */
+  setPhase(phase: number): this {
+    if (phase < 0 || phase >= 2 * Math.PI) {
+      throw new Error('Phase must be between 0 and 2π');
+    }
+    this._phase = phase;
+    return this;
+  }
+
+  /**
+   * Multiply frequency by a ratio (for transposition)
+   */
+  transpose(ratio: FractionInput): this {
+    this._frequency = this._frequency.mul(ratio);
+    return this;
+  }
+
+  /**
+ * Multiply frequency by a ratio (for transposition)
+ */
+  toTransposed(ratio: FractionInput): Harmonic {
+    return this.clone().transpose(ratio);
+  }
+
+  /**
+   * Scale amplitude by a factor
+   */
+  scale(factor: number): this {
+    this._amplitude = Math.max(0, Math.min(1, this._amplitude * factor));
+    return this;
+  }
+
+  /**
+   * Create a copy of this harmonic
+   */
+  clone(): Harmonic {
+    return new Harmonic(this._frequency, this._amplitude, this._phase);
+  }
+
+  /**
+   * Compare frequencies (for sorting)
+   */
+  compareFrequency(other: Harmonic): number {
+    return this._frequency.compare(other._frequency);
+  }
+
+  /**
+   * Serializes the harmonic to a HarmonicData object
+   */
+  toJSON(): HarmonicData {
+    return {
+      frequency: {
+        n: Number(this._frequency.n),
+        d: Number(this._frequency.d),
+      },
+      amplitude: this._amplitude,
+      phase: this._phase,
+    };
+  }
+}