sethares-dissonance 2.0.1 → 2.1.0

package/README.md

@@ -1,15 +1,114 @@
 # sethares-dissonance
 
-To install dependencies:
+A JavaScript/TypeScript library for analyzing **dissonance curves** using William Sethares' sensory dissonance model. Dissonance curves show how sensory dissonance varies across a range of musical intervals, based on the spectral content of sounds.
+
+For the theoretical foundation and detailed explanation of the model, see the book **[_Tuning, Timbre, Spectrum, Scale_](https://www.williamsethares.com/ttss.html)** by William Sethares.
+
+## Installation
 
 ```bash
-bun install
+bun add sethares-dissonance
+# or
+npm install sethares-dissonance
 ```
 
-To run:
+## Usage
 
-```bash
-bun run index.ts
+```ts
+import { DissonanceCurve, Spectrum } from "sethares-dissonance";
+
+const context = Spectrum.harmonicSeries(10, 440);
+const complement = Spectrum.harmonicSeries(10, 440);
+
+const curve = new DissonanceCurve({
+    context,
+    complement,
+    start: 1,
+    end: 2,
+    maxDenominator: 60,
+});
+
+const points = curve.points;
+const plotData = curve.plot();
 ```
 
-This project was created using `bun init` in bun v1.2.15. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.
+## React
+
+Because DissonanceCurve class mutates data in place, it is not directly suited for React applications as reference to the instance does not change. React will not detect dissonance curve mutations in dependency arrays or state and thus will not rerender. You can solve it in two ways.
+
+### 1. Create new instances
+
+Create a fresh `DissonanceCurve` whenever options change. `useMemo` ensures a new instance is created when dependencies change, so React detects the update and re-renders.
+
+```tsx
+import { useMemo } from "react";
+import { DissonanceCurve, Spectrum } from "sethares-dissonance";
+
+function DissonanceChart({ context, complement, start = 1, end = 2 }) {
+    const curve = useMemo(
+        () =>
+            new DissonanceCurve({
+                context,
+                complement,
+                start,
+                end,
+                maxDenominator: 60,
+            }),
+        [context, complement, start, end],
+    );
+
+    const plotData = curve.plot();
+    return <svg>{/* render plotData */}</svg>;
+}
+```
+
+This solution ok, but there is a downside that `curve` object contains methods that can mutate the internal state which will not be registered by React, thus leading to bugs.
+
+### 2. Use read-only wrappers (Recommended)
+
+This method relies on creating new instances of read-only objects rather than new DissonanceCurve instances. It is demonstrated in the following `useDissonanceCurve` hook. Memoize options with `useMemo` when they contain objects (e.g. `Spectrum`) to avoid recalculating on every render.
+
+```tsx
+"use client";
+
+import { useMemo, useState } from "react";
+import {
+    DissonanceCurve,
+    type DissonanceCurveOptions,
+} from "sethares-dissonance";
+import type { ReadOnlyDissonanceCurve } from "sethares-dissonance";
+
+/**
+ * Read-only view of DissonanceCurve without the recalculate method.
+ * Use this type when exposing the curve from hooks to prevent external mutation.
+ */
+export type ReadOnlyDissonanceCurve = Partial<Omit<
+  DissonanceCurve,
+  "recalculate"
+>>;
+
+function createReadOnlyWrapper(
+    curve: DissonanceCurve,
+): ReadOnlyDissonanceCurve {
+    
+    return {
+        get maxDissonance() {
+            return curve.maxDissonance;
+        },
+        plotCents: () => curve.plotCents(),
+        findNearestPoint: (ratio) => curve.findNearestPoint(ratio),
+        // .. can add more methods if needed, aboid those that cause mutations
+    };
+}
+
+export function useDissonanceCurve(
+    options: DissonanceCurveOptions,
+): ReadOnlyDissonanceCurve {
+    const [curve] = useState(() => new DissonanceCurve(options));
+
+    return useMemo(() => {
+        curve.recalculate(options);
+        return createReadOnlyWrapper(curve);
+    }, [options, curve]);
+}
+```

package/dist/classes/DissonanceCurve.d.ts

@@ -1,6 +1,6 @@
 import { Fraction, type FractionInput } from "fraction.js";
-import { type DissonanceParams, type DissonanceCurvePoint, type DissonanceCurveData } from "../lib";
 import { Spectrum } from "tuning-core";
+import type { DissonanceParams, DissonanceCurvePoint, DissonanceCurveData } from "../lib";
 export type DissonanceCurveOptions = DissonanceParams & {
     context: Spectrum;
     complement: Spectrum;
@@ -41,12 +41,21 @@ export type DissonanceCurveOptions = DissonanceParams & {
  */
 export declare class DissonanceCurve {
     private _data;
-    readonly start: Fraction;
-    readonly end: Fraction;
-    readonly context: Spectrum;
-    readonly complement: Spectrum;
-    readonly maxDissonance: number;
+    start: Fraction;
+    end: Fraction;
+    context: Spectrum;
+    complement: Spectrum;
+    maxDissonance: number;
     constructor(opts: DissonanceCurveOptions);
+    /**
+     * Recalculate the dissonance curve with new options.
+     * Updates the curve in place.
+     */
+    recalculate(opts: DissonanceCurveOptions): void;
+    /**
+     * Build _data from public props (context, complement, start, end).
+     */
+    private build;
     /**
      * Get all dissonance curve points sorted by interval ratio.
      * @returns Array of DissonanceCurvePoint objects sorted in ascending order by interval

package/dist/classes/DissonanceCurve.js

@@ -1,6 +1,6 @@
 import { Fraction } from "fraction.js";
-import { getSetharesDissonance, } from "../lib";
 import { ratioToCents, Spectrum, IntervalSet } from "tuning-core";
+import { getSetharesDissonance } from "../lib";
 const DEFAULT_COLUMN_DELIMITER = ",";
 const DEFAULT_ROW_DELIMITER = "\n";
 /**
@@ -49,15 +49,38 @@ export class DissonanceCurve {
         this.end = new Fraction(end ?? 2);
         if (this.start.compare(this.end) > 0)
             throw Error("startCents should be less or equal to endCents");
-        const intervals = IntervalSet.affinitive(this.context, this.complement).densify(20);
+        this.build(dissonanceParams);
+    }
+    /**
+     * Recalculate the dissonance curve with new options.
+     * Updates the curve in place.
+     */
+    recalculate(opts) {
+        const { context, complement, start, end, maxDenominator, ...dissonanceParams } = opts;
+        this.context = context;
+        this.complement = complement;
+        this.start = new Fraction(start ?? 1);
+        this.end = new Fraction(end ?? 2);
+        if (this.start.compare(this.end) > 0)
+            throw Error("startCents should be less or equal to endCents");
+        this.build(dissonanceParams);
+    }
+    /**
+     * Build _data from public props (context, complement, start, end).
+     */
+    build(dissonanceParams) {
+        this._data.clear();
+        let maxDissonance = 0;
+        const intervals = IntervalSet.affinitive(this.context.size > 1 ? this.context : Spectrum.harmonic(2, 1), this.complement.size > 1 ? this.complement : Spectrum.harmonic(2, 1)).densify(20);
         const ratios = intervals.getRatios();
         for (let i = 0; i < ratios.length; i++) {
             const interval = ratios[i];
             const dissonance = getSetharesDissonance(this.context, this.complement.toTransposed(interval), dissonanceParams);
-            if (dissonance > this.maxDissonance)
-                this.maxDissonance = dissonance;
+            if (dissonance > maxDissonance)
+                maxDissonance = dissonance;
             this._data.set(interval.toFraction(), { interval, dissonance });
         }
+        this.maxDissonance = maxDissonance;
     }
     /**
      * Get all dissonance curve points sorted by interval ratio.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sethares-dissonance",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "type": "module",
   "devDependencies": {
     "@types/bun": "latest"
@@ -16,10 +16,10 @@
   ],
   "scripts": {
     "build": "npx tsc",
-    "publish": "npx tsc && bun publish --access public"
+    "release": "./release.sh"
   },
   "dependencies": {
     "fraction.js": "^5.3.4",
-    "tuning-core": "^1.0.3"
+    "tuning-core": "^1.1.0"
   }
 }