feat!(scalable): 💥 make difference return the closest number of semitones

lib/src/note/base_note.dart

@@ -109,9 +109,9 @@ enum BaseNote implements Comparable<BaseNote> {
   /// ```dart
   /// BaseNote.c.difference(BaseNote.c) == 0
   /// BaseNote.c.difference(BaseNote.e) == 4
-  /// BaseNote.a.difference(BaseNote.d) == -7
+  /// BaseNote.a.difference(BaseNote.d) == 5
   /// ```
-  int difference(BaseNote other) => other.semitones - semitones;
+  int difference(BaseNote other) => Note(this).difference(Note(other));
 
   /// Returns the positive difference in semitones between this [BaseNote] and
   /// [other].

lib/src/note/note.dart

@@ -79,11 +79,11 @@ final class Note extends Scalable<Note> implements Comparable<Note> {
   /// Example:
   /// ```dart
   /// Note.c.difference(Note.d) == 2
-  /// Note.e.flat.difference(Note.b.flat) == 7
   /// Note.a.difference(Note.g) == -2
+  /// Note.e.flat.difference(Note.b.flat) == -5
   /// ```
   @override
-  int difference(Note other) => other.semitones - semitones;
+  int difference(Note other) => super.difference(other);
 
   /// Returns this [Note] sharpened by 1 semitone.
   ///

lib/src/note/pitch_class.dart

@@ -178,9 +178,10 @@ final class PitchClass extends Scalable<PitchClass>
   /// ```dart
   /// PitchClass.g.difference(PitchClass.a) == 2
   /// PitchClass.dSharp.difference(PitchClass.c) == -3
+  /// PitchClass.c.difference(PitchClass.fSharp) == -6
   /// ```
   @override
-  int difference(PitchClass other) => other.semitones - semitones;
+  int difference(PitchClass other) => super.difference(other);
 
   /// Performs a pitch-class multiplication modulo [chromaticDivisions] of this
   /// [PitchClass].

lib/src/scalable.dart

@@ -8,11 +8,17 @@ abstract interface class Scalable<T extends Scalable<T>>
   /// The number of semitones that define this [Scalable].
   int get semitones;
 
-  /// Returns the [Interval] between this [T] and [other].
+  /// Returns the [Interval] between this [Scalable] and [other].
   Interval interval(T other);
 
-  /// Returns the difference in semitones between this [T] and [other].
-  int difference(T other);
+  /// Returns the difference in semitones between this [Scalable] and [other].
+  int difference(T other) {
+    final diff = other.semitones - semitones;
+
+    return diff.abs() < chromaticDivisions ~/ 2
+        ? diff
+        : diff - chromaticDivisions * diff.sign;
+  }
 }
 
 /// A Scalable iterable.

test/src/note/base_note_test.dart

@@ -48,19 +48,22 @@ void main() {
     });
 
     group('.difference()', () {
-      test('should return the difference in semitones with other', () {
-        expect(BaseNote.b.difference(BaseNote.c), -11);
-        expect(BaseNote.a.difference(BaseNote.d), -7);
-        expect(BaseNote.e.difference(BaseNote.c), -4);
-        expect(BaseNote.e.difference(BaseNote.d), -2);
-        expect(BaseNote.c.difference(BaseNote.c), 0);
-        expect(BaseNote.c.difference(BaseNote.d), 2);
-        expect(BaseNote.c.difference(BaseNote.e), 4);
-        expect(BaseNote.c.difference(BaseNote.f), 5);
-        expect(BaseNote.e.difference(BaseNote.b), 7);
-        expect(BaseNote.d.difference(BaseNote.b), 9);
-        expect(BaseNote.c.difference(BaseNote.b), 11);
-      });
+      test(
+        'should return the difference in semitones with another BaseNote',
+        () {
+          expect(BaseNote.e.difference(BaseNote.b), -5);
+          expect(BaseNote.e.difference(BaseNote.c), -4);
+          expect(BaseNote.d.difference(BaseNote.b), -3);
+          expect(BaseNote.e.difference(BaseNote.d), -2);
+          expect(BaseNote.c.difference(BaseNote.b), -1);
+          expect(BaseNote.c.difference(BaseNote.c), 0);
+          expect(BaseNote.b.difference(BaseNote.c), 1);
+          expect(BaseNote.c.difference(BaseNote.d), 2);
+          expect(BaseNote.c.difference(BaseNote.e), 4);
+          expect(BaseNote.a.difference(BaseNote.d), 5);
+          expect(BaseNote.c.difference(BaseNote.f), 5);
+        },
+      );
     });
 
     group('.positiveDifference()', () {

test/src/note/note_test.dart

@@ -53,23 +53,24 @@ void main() {
       test(
         'should return the difference in semitones with another Note',
         () {
+          expect(Note.d.difference(Note.a.flat), -6);
+          expect(Note.e.flat.difference(Note.b.flat), -5);
+          expect(Note.d.sharp.difference(Note.a.sharp), -5);
+          expect(Note.d.difference(Note.a.sharp), -4);
+          expect(Note.c.sharp.difference(Note.b.flat), -3);
+          expect(Note.c.sharp.difference(Note.b), -2);
+          expect(Note.d.flat.difference(Note.b), -2);
+          expect(Note.c.difference(Note.b), -1);
           expect(Note.c.difference(Note.c), 0);
           expect(Note.e.sharp.difference(Note.f), 0);
           expect(Note.c.difference(Note.d.flat), 1);
           expect(Note.c.difference(Note.c.sharp), 1);
-          expect(Note.b.difference(Note.c), -11);
+          expect(Note.b.difference(Note.c), 1);
           expect(Note.f.difference(Note.g), 2);
           expect(Note.f.difference(Note.a.flat), 3);
           expect(Note.e.difference(Note.a.flat), 4);
-          expect(Note.a.difference(Note.d), -7);
-          expect(Note.d.difference(Note.a.flat), 6);
-          expect(Note.e.flat.difference(Note.b.flat), 7);
-          expect(Note.d.sharp.difference(Note.a.sharp), 7);
-          expect(Note.d.difference(Note.a.sharp), 8);
-          expect(Note.c.sharp.difference(Note.b.flat), 9);
-          expect(Note.c.sharp.difference(Note.b), 10);
-          expect(Note.d.flat.difference(Note.b), 10);
-          expect(Note.c.difference(Note.b), 11);
+          expect(Note.a.difference(Note.d), 5);
+          expect(Note.a.difference(Note.d.sharp), 6);
         },
       );
     });

test/src/note/pitch_class_test.dart

@@ -285,6 +285,28 @@ void main() {
       });
     });
 
+    group('.difference()', () {
+      test(
+        'should return the difference in semitones with another PitchClass',
+        () {
+          expect(PitchClass.d.difference(PitchClass.gSharp), -6);
+          expect(PitchClass.dSharp.difference(PitchClass.aSharp), -5);
+          expect(PitchClass.d.difference(PitchClass.aSharp), -4);
+          expect(PitchClass.cSharp.difference(PitchClass.aSharp), -3);
+          expect(PitchClass.cSharp.difference(PitchClass.b), -2);
+          expect(PitchClass.c.difference(PitchClass.b), -1);
+          expect(PitchClass.c.difference(PitchClass.c), 0);
+          expect(PitchClass.c.difference(PitchClass.cSharp), 1);
+          expect(PitchClass.b.difference(PitchClass.c), 1);
+          expect(PitchClass.f.difference(PitchClass.g), 2);
+          expect(PitchClass.f.difference(PitchClass.gSharp), 3);
+          expect(PitchClass.e.difference(PitchClass.gSharp), 4);
+          expect(PitchClass.a.difference(PitchClass.d), 5);
+          expect(PitchClass.a.difference(PitchClass.dSharp), 6);
+        },
+      );
+    });
+
     group('.transposeBy()', () {
       test('should transpose this PitchClass by Interval', () {
         expect(PitchClass.c.transposeBy(Interval.d1), PitchClass.b);