tuning-core 1.0.0 → 1.0.2

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './classes';
+export * from './lib';

package/dist/lib/index.js

@@ -0,0 +1,2 @@
+export * from './utils';
+export * from './types';

package/dist/lib/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Plain object for serialization/deserialization
+ */
+export type HarmonicData = {
+    frequency: {
+        n: number;
+        d: number;
+    };
+    amplitude: number;
+    phase: number;
+};
+export type SpectrumData = HarmonicData[];

package/dist/lib/utils.d.ts

@@ -0,0 +1,20 @@
+import Fraction, { type FractionInput } from 'fraction.js';
+import type { HarmonicData } from './types';
+/**
+ * Convert a frequency ratio to cents.
+ * @param ratio - The ratio as FractionInput (number, string, array, object, or Fraction)
+ * @param places - Number of decimal places to round to (default: 0, no decimals)
+ * @returns The ratio in cents (1200 * log2(ratio)), rounded to the specified number of decimals
+ */
+export declare function ratioToCents(ratio: FractionInput, places?: number): Fraction;
+/**
+ * Convert cents to a frequency ratio.
+ * @param cents - The interval in cents as FractionInput (number, string, array, object, or Fraction)
+ * @param places - Number of decimal places to round to (default: 0, no decimals)
+ * @returns The ratio as a Fraction object (2^(cents/1200)), rounded to the specified number of decimals
+ */
+export declare function centsToRatio(cents: FractionInput, places?: number): Fraction;
+/**
+ * Type guard to check if a value is HarmonicData
+ */
+export declare function isHarmonicData(value: unknown): value is HarmonicData;

package/dist/lib/utils.js

@@ -0,0 +1,38 @@
+import Fraction, {} from 'fraction.js';
+function round(num, places = 0) {
+    return Math.round(num * Math.pow(10, places)) / Math.pow(10, places);
+}
+/**
+ * Convert a frequency ratio to cents.
+ * @param ratio - The ratio as FractionInput (number, string, array, object, or Fraction)
+ * @param places - Number of decimal places to round to (default: 0, no decimals)
+ * @returns The ratio in cents (1200 * log2(ratio)), rounded to the specified number of decimals
+ */
+export function ratioToCents(ratio, places = 0) {
+    const val = new Fraction(ratio).valueOf();
+    const num = 1200 * Math.log2(val);
+    const rounded = round(num, places);
+    return new Fraction(rounded);
+}
+/**
+ * Convert cents to a frequency ratio.
+ * @param cents - The interval in cents as FractionInput (number, string, array, object, or Fraction)
+ * @param places - Number of decimal places to round to (default: 0, no decimals)
+ * @returns The ratio as a Fraction object (2^(cents/1200)), rounded to the specified number of decimals
+ */
+export function centsToRatio(cents, places = 0) {
+    const val = new Fraction(cents).valueOf();
+    const num = Math.pow(2, val / 1200);
+    const rounded = round(num, places);
+    return new Fraction(rounded);
+}
+/**
+ * Type guard to check if a value is HarmonicData
+ */
+export function isHarmonicData(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'frequency' in value &&
+        'amplitude' in value &&
+        'phase' in value);
+}

package/package.json

@@ -1,10 +1,13 @@
 {
     "name": "tuning-core",
-    "version": "1.0.0",
-    "module": "index.ts",
+    "version": "1.0.2",
+    "module": "index.js",
     "type": "module",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
     "scripts": {
         "build": "npx tsc",
         "publish": "npx tsc && bun publish --access public"

package/benches/fraction-performance.bench.ts

@@ -1,141 +0,0 @@
-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

@@ -1,167 +0,0 @@
-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

@@ -1,183 +0,0 @@
-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,
-    };
-  }
-}