elektron-lfo 1.0.0

package/tests/triggers.test.ts

@@ -0,0 +1,345 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  handleTrigger,
+  checkModeStop,
+  requiresTriggerToStart,
+  resetsPhaseOnTrigger,
+  resetsFadeOnTrigger,
+} from '../src/engine/triggers';
+import type { LFOConfig, LFOState } from '../src/engine/types';
+import { DEFAULT_CONFIG } from '../src/engine/types';
+
+// Helper to create config with defaults
+function createConfig(overrides: Partial<LFOConfig>): LFOConfig {
+  return { ...DEFAULT_CONFIG, ...overrides };
+}
+
+// Helper to create state with defaults
+function createState(overrides: Partial<LFOState> = {}): LFOState {
+  return {
+    phase: 0.5,
+    output: 0.5,
+    rawOutput: 0.5,
+    isRunning: true,
+    fadeMultiplier: 1,
+    fadeProgress: 0.5,
+    randomValue: 0.5,
+    previousPhase: 0.4,
+    heldOutput: 0,
+    startPhaseNormalized: 0,
+    cycleCount: 2,
+    triggerCount: 0,
+    hasTriggered: false,
+    randomStep: 8,
+    ...overrides,
+  };
+}
+
+describe('handleTrigger - FRE mode', () => {
+  test('does not change phase', () => {
+    const config = createConfig({ mode: 'FRE' });
+    const state = createState({ phase: 0.75 });
+
+    const newState = handleTrigger(config, state, 0.5);
+    expect(newState.phase).toBe(0.75);
+  });
+
+  test('does not reset fade', () => {
+    const config = createConfig({ mode: 'FRE', fade: -32 });
+    const state = createState({ fadeProgress: 0.8, fadeMultiplier: 0.8 });
+
+    const newState = handleTrigger(config, state, 0.5);
+    expect(newState.fadeProgress).toBe(0.8);
+    expect(newState.fadeMultiplier).toBe(0.8);
+  });
+
+  test('increments trigger count', () => {
+    const config = createConfig({ mode: 'FRE' });
+    const state = createState({ triggerCount: 5 });
+
+    const newState = handleTrigger(config, state, 0.5);
+    expect(newState.triggerCount).toBe(6);
+  });
+});
+
+describe('handleTrigger - TRG mode', () => {
+  test('resets phase to start phase', () => {
+    const config = createConfig({ mode: 'TRG', startPhase: 32 });
+    const state = createState({ phase: 0.75, startPhaseNormalized: 0.25 });
+
+    const newState = handleTrigger(config, state, 0.5);
+    expect(newState.phase).toBe(0.25);
+  });
+
+  test('resets fade for fade in', () => {
+    const config = createConfig({ mode: 'TRG', fade: -32 });
+    const state = createState({ fadeProgress: 0.8, fadeMultiplier: 0.8 });
+
+    const newState = handleTrigger(config, state, 0.5);
+    expect(newState.fadeProgress).toBe(0);
+    expect(newState.fadeMultiplier).toBe(0); // Fade in starts at 0
+  });
+
+  test('resets fade for fade out', () => {
+    const config = createConfig({ mode: 'TRG', fade: 32 });
+    const state = createState({ fadeProgress: 0.8, fadeMultiplier: 0.2 });
+
+    const newState = handleTrigger(config, state, 0.5);
+    expect(newState.fadeProgress).toBe(0);
+    expect(newState.fadeMultiplier).toBe(1); // Fade out starts at 1
+  });
+
+  test('resets cycle count', () => {
+    const config = createConfig({ mode: 'TRG' });
+    const state = createState({ cycleCount: 10 });
+
+    const newState = handleTrigger(config, state, 0.5);
+    expect(newState.cycleCount).toBe(0);
+  });
+
+  test('generates new random value for RND waveform', () => {
+    const config = createConfig({ mode: 'TRG', waveform: 'RND' });
+    const state = createState({ randomValue: 0.5 });
+
+    const newState = handleTrigger(config, state, 0.5);
+    // Can't guarantee different value, but randomStep should be reset
+    expect(newState.randomStep).toBeDefined();
+  });
+});
+
+describe('handleTrigger - HLD mode', () => {
+  test('holds current output value', () => {
+    const config = createConfig({ mode: 'HLD' });
+    const state = createState();
+
+    const newState = handleTrigger(config, state, 0.75);
+    expect(newState.heldOutput).toBe(0.75);
+  });
+
+  test('does not reset phase', () => {
+    const config = createConfig({ mode: 'HLD' });
+    const state = createState({ phase: 0.6 });
+
+    const newState = handleTrigger(config, state, 0.5);
+    expect(newState.phase).toBe(0.6);
+  });
+
+  test('resets fade', () => {
+    const config = createConfig({ mode: 'HLD', fade: -32 });
+    const state = createState({ fadeProgress: 0.8, fadeMultiplier: 0.8 });
+
+    const newState = handleTrigger(config, state, 0.5);
+    expect(newState.fadeProgress).toBe(0);
+    expect(newState.fadeMultiplier).toBe(0);
+  });
+});
+
+describe('handleTrigger - ONE mode', () => {
+  test('resets phase to start phase', () => {
+    const config = createConfig({ mode: 'ONE', startPhase: 64 });
+    const state = createState({ phase: 0.75, startPhaseNormalized: 0.5 });
+
+    const newState = handleTrigger(config, state, 0.5);
+    expect(newState.phase).toBe(0.5);
+  });
+
+  test('starts running', () => {
+    const config = createConfig({ mode: 'ONE' });
+    const state = createState({ isRunning: false });
+
+    const newState = handleTrigger(config, state, 0.5);
+    expect(newState.isRunning).toBe(true);
+  });
+
+  test('sets hasTriggered flag', () => {
+    const config = createConfig({ mode: 'ONE' });
+    const state = createState({ hasTriggered: false });
+
+    const newState = handleTrigger(config, state, 0.5);
+    expect(newState.hasTriggered).toBe(true);
+  });
+
+  test('resets fade and cycle count', () => {
+    const config = createConfig({ mode: 'ONE', fade: -32 });
+    const state = createState({ fadeProgress: 0.8, cycleCount: 5 });
+
+    const newState = handleTrigger(config, state, 0.5);
+    expect(newState.fadeProgress).toBe(0);
+    expect(newState.cycleCount).toBe(0);
+  });
+});
+
+describe('handleTrigger - HLF mode', () => {
+  test('resets phase to start phase', () => {
+    const config = createConfig({ mode: 'HLF', startPhase: 32 });
+    const state = createState({ phase: 0.8, startPhaseNormalized: 0.25 });
+
+    const newState = handleTrigger(config, state, 0.5);
+    expect(newState.phase).toBe(0.25);
+  });
+
+  test('starts running and sets hasTriggered', () => {
+    const config = createConfig({ mode: 'HLF' });
+    const state = createState({ isRunning: false, hasTriggered: false });
+
+    const newState = handleTrigger(config, state, 0.5);
+    expect(newState.isRunning).toBe(true);
+    expect(newState.hasTriggered).toBe(true);
+  });
+});
+
+describe('checkModeStop - ONE mode', () => {
+  test('stops after completing one cycle (forward)', () => {
+    const config = createConfig({ mode: 'ONE', speed: 16 });
+    const state = createState({
+      hasTriggered: true,
+      startPhaseNormalized: 0,
+      cycleCount: 1,
+    });
+
+    // Phase wrapping from near 1 to near 0
+    const result = checkModeStop(config, state, 0.95, 0.05);
+    expect(result.shouldStop).toBe(true);
+    expect(result.cycleCompleted).toBe(true);
+  });
+
+  test('does not stop before cycle completes', () => {
+    const config = createConfig({ mode: 'ONE', speed: 16 });
+    const state = createState({
+      hasTriggered: true,
+      startPhaseNormalized: 0,
+      cycleCount: 0,
+    });
+
+    const result = checkModeStop(config, state, 0.4, 0.5);
+    expect(result.shouldStop).toBe(false);
+  });
+
+  test('stops when phase crosses start phase (with non-zero start)', () => {
+    const config = createConfig({ mode: 'ONE', speed: 16, startPhase: 64 });
+    const state = createState({
+      hasTriggered: true,
+      startPhaseNormalized: 0.5,
+      cycleCount: 0,
+    });
+
+    // Going from just before 0.5 (after wrapping) back to 0.5
+    const result = checkModeStop(config, state, 0.6, 0.4);
+    expect(result.shouldStop).toBe(false); // Haven't completed a full cycle yet
+  });
+
+  test('stops for negative speed (backward)', () => {
+    const config = createConfig({ mode: 'ONE', speed: -16 });
+    const state = createState({
+      hasTriggered: true,
+      startPhaseNormalized: 0,
+      cycleCount: 1,
+    });
+
+    // Phase wrapping from near 0 to near 1 (backward direction)
+    const result = checkModeStop(config, state, 0.05, 0.95);
+    expect(result.shouldStop).toBe(true);
+  });
+});
+
+describe('checkModeStop - HLF mode', () => {
+  test('stops at half cycle (forward, start at 0)', () => {
+    const config = createConfig({ mode: 'HLF', speed: 16 });
+    const state = createState({
+      hasTriggered: true,
+      startPhaseNormalized: 0,
+    });
+
+    // Crossing phase 0.5
+    const result = checkModeStop(config, state, 0.45, 0.55);
+    expect(result.shouldStop).toBe(true);
+  });
+
+  test('stops at half cycle (start at 0.25)', () => {
+    const config = createConfig({ mode: 'HLF', speed: 16, startPhase: 32 });
+    const state = createState({
+      hasTriggered: true,
+      startPhaseNormalized: 0.25, // 32/128
+    });
+
+    // Half point is 0.25 + 0.5 = 0.75
+    const result = checkModeStop(config, state, 0.7, 0.8);
+    expect(result.shouldStop).toBe(true);
+  });
+
+  test('does not stop before half cycle', () => {
+    const config = createConfig({ mode: 'HLF', speed: 16 });
+    const state = createState({
+      hasTriggered: true,
+      startPhaseNormalized: 0,
+    });
+
+    const result = checkModeStop(config, state, 0.2, 0.3);
+    expect(result.shouldStop).toBe(false);
+  });
+});
+
+describe('checkModeStop - other modes', () => {
+  test('FRE mode never stops', () => {
+    const config = createConfig({ mode: 'FRE' });
+    const state = createState({ hasTriggered: true });
+
+    const result = checkModeStop(config, state, 0.9, 0.1);
+    expect(result.shouldStop).toBe(false);
+  });
+
+  test('TRG mode never stops', () => {
+    const config = createConfig({ mode: 'TRG' });
+    const state = createState({ hasTriggered: true });
+
+    const result = checkModeStop(config, state, 0.9, 0.1);
+    expect(result.shouldStop).toBe(false);
+  });
+
+  test('HLD mode never stops', () => {
+    const config = createConfig({ mode: 'HLD' });
+    const state = createState({ hasTriggered: true });
+
+    const result = checkModeStop(config, state, 0.9, 0.1);
+    expect(result.shouldStop).toBe(false);
+  });
+});
+
+describe('requiresTriggerToStart', () => {
+  test('ONE and HLF require trigger', () => {
+    expect(requiresTriggerToStart('ONE')).toBe(true);
+    expect(requiresTriggerToStart('HLF')).toBe(true);
+  });
+
+  test('other modes do not require trigger', () => {
+    expect(requiresTriggerToStart('FRE')).toBe(false);
+    expect(requiresTriggerToStart('TRG')).toBe(false);
+    expect(requiresTriggerToStart('HLD')).toBe(false);
+  });
+});
+
+describe('resetsPhaseOnTrigger', () => {
+  test('TRG, ONE, HLF reset phase', () => {
+    expect(resetsPhaseOnTrigger('TRG')).toBe(true);
+    expect(resetsPhaseOnTrigger('ONE')).toBe(true);
+    expect(resetsPhaseOnTrigger('HLF')).toBe(true);
+  });
+
+  test('FRE and HLD do not reset phase', () => {
+    expect(resetsPhaseOnTrigger('FRE')).toBe(false);
+    expect(resetsPhaseOnTrigger('HLD')).toBe(false);
+  });
+});
+
+describe('resetsFadeOnTrigger', () => {
+  test('all modes except FRE reset fade', () => {
+    expect(resetsFadeOnTrigger('TRG')).toBe(true);
+    expect(resetsFadeOnTrigger('ONE')).toBe(true);
+    expect(resetsFadeOnTrigger('HLF')).toBe(true);
+    expect(resetsFadeOnTrigger('HLD')).toBe(true);
+  });
+
+  test('FRE does not reset fade', () => {
+    expect(resetsFadeOnTrigger('FRE')).toBe(false);
+  });
+});

package/tests/waveforms.test.ts

@@ -0,0 +1,273 @@
+import { describe, test, expect } from 'bun:test';
+import {
+  generateTriangle,
+  generateSine,
+  generateSquare,
+  generateSawtooth,
+  generateExponential,
+  generateRamp,
+  generateRandom,
+  generateWaveform,
+  isUnipolar,
+  getWaveformRange,
+} from '../src/engine/waveforms';
+import type { LFOState } from '../src/engine/types';
+import { createInitialState } from '../src/engine/types';
+
+// Helper to create a mock state for random waveform testing
+function createMockState(overrides: Partial<LFOState> = {}): LFOState {
+  return {
+    phase: 0,
+    output: 0,
+    rawOutput: 0,
+    isRunning: true,
+    fadeMultiplier: 1,
+    fadeProgress: 0,
+    randomValue: 0.5,
+    previousPhase: 0,
+    heldOutput: 0,
+    startPhaseNormalized: 0,
+    cycleCount: 0,
+    triggerCount: 0,
+    hasTriggered: false,
+    randomStep: 0,
+    ...overrides,
+  };
+}
+
+describe('Triangle Waveform', () => {
+  test('starts at 0 at phase 0', () => {
+    expect(generateTriangle(0)).toBeCloseTo(0, 5);
+  });
+
+  test('peaks at +1 at phase 0.25', () => {
+    expect(generateTriangle(0.25)).toBeCloseTo(1, 5);
+  });
+
+  test('returns to 0 at phase 0.5', () => {
+    expect(generateTriangle(0.5)).toBeCloseTo(0, 5);
+  });
+
+  test('troughs at -1 at phase 0.75', () => {
+    expect(generateTriangle(0.75)).toBeCloseTo(-1, 5);
+  });
+
+  test('returns to near 0 at phase ~1', () => {
+    expect(generateTriangle(0.999)).toBeCloseTo(0, 1);
+  });
+
+  test('is bipolar (range -1 to +1)', () => {
+    const samples = Array.from({ length: 100 }, (_, i) => generateTriangle(i / 100));
+    expect(Math.min(...samples)).toBeGreaterThanOrEqual(-1);
+    expect(Math.max(...samples)).toBeLessThanOrEqual(1);
+    expect(Math.min(...samples)).toBeLessThan(0); // Has negative values
+    expect(Math.max(...samples)).toBeGreaterThan(0); // Has positive values
+  });
+});
+
+describe('Sine Waveform', () => {
+  test('starts at 0 at phase 0', () => {
+    expect(generateSine(0)).toBeCloseTo(0, 5);
+  });
+
+  test('peaks at +1 at phase 0.25', () => {
+    expect(generateSine(0.25)).toBeCloseTo(1, 5);
+  });
+
+  test('returns to 0 at phase 0.5', () => {
+    expect(generateSine(0.5)).toBeCloseTo(0, 5);
+  });
+
+  test('troughs at -1 at phase 0.75', () => {
+    expect(generateSine(0.75)).toBeCloseTo(-1, 5);
+  });
+
+  test('returns to 0 at phase 1', () => {
+    expect(generateSine(1)).toBeCloseTo(0, 5);
+  });
+
+  test('is bipolar (range -1 to +1)', () => {
+    const samples = Array.from({ length: 100 }, (_, i) => generateSine(i / 100));
+    expect(Math.min(...samples)).toBeGreaterThanOrEqual(-1);
+    expect(Math.max(...samples)).toBeLessThanOrEqual(1);
+  });
+});
+
+describe('Square Waveform', () => {
+  test('is +1 at phase 0', () => {
+    expect(generateSquare(0)).toBe(1);
+  });
+
+  test('is +1 just before phase 0.5', () => {
+    expect(generateSquare(0.49)).toBe(1);
+  });
+
+  test('is -1 at phase 0.5', () => {
+    expect(generateSquare(0.5)).toBe(-1);
+  });
+
+  test('is -1 at phase 0.75', () => {
+    expect(generateSquare(0.75)).toBe(-1);
+  });
+
+  test('is -1 just before phase 1', () => {
+    expect(generateSquare(0.99)).toBe(-1);
+  });
+
+  test('is bipolar (only +1 and -1 values)', () => {
+    const samples = Array.from({ length: 100 }, (_, i) => generateSquare(i / 100));
+    samples.forEach(s => {
+      expect(s === 1 || s === -1).toBe(true);
+    });
+  });
+});
+
+describe('Sawtooth Waveform', () => {
+  test('starts at -1 at phase 0', () => {
+    expect(generateSawtooth(0)).toBe(-1);
+  });
+
+  test('is 0 at phase 0.5', () => {
+    expect(generateSawtooth(0.5)).toBe(0);
+  });
+
+  test('approaches +1 at phase ~1', () => {
+    expect(generateSawtooth(1)).toBe(1);
+    expect(generateSawtooth(0.999)).toBeCloseTo(1, 2);
+  });
+
+  test('is bipolar and linear', () => {
+    expect(generateSawtooth(0.25)).toBeCloseTo(-0.5, 5);
+    expect(generateSawtooth(0.75)).toBeCloseTo(0.5, 5);
+  });
+});
+
+describe('Exponential Waveform', () => {
+  test('starts at 0 at phase 0', () => {
+    expect(generateExponential(0)).toBeCloseTo(0, 5);
+  });
+
+  test('ends at 1 at phase 1', () => {
+    expect(generateExponential(1)).toBeCloseTo(1, 5);
+  });
+
+  test('is unipolar (0 to +1)', () => {
+    const samples = Array.from({ length: 100 }, (_, i) => generateExponential(i / 100));
+    expect(Math.min(...samples)).toBeGreaterThanOrEqual(0);
+    expect(Math.max(...samples)).toBeLessThanOrEqual(1);
+  });
+
+  test('has accelerating (exponential) curve shape', () => {
+    // At phase 0.5, should be less than 0.5 (curve bends up)
+    const midValue = generateExponential(0.5);
+    expect(midValue).toBeLessThan(0.5);
+  });
+});
+
+describe('Ramp Waveform', () => {
+  test('starts at 1 at phase 0', () => {
+    expect(generateRamp(0)).toBe(1);
+  });
+
+  test('ends at 0 at phase 1', () => {
+    expect(generateRamp(1)).toBe(0);
+  });
+
+  test('is 0.5 at phase 0.5', () => {
+    expect(generateRamp(0.5)).toBe(0.5);
+  });
+
+  test('is unipolar (0 to +1)', () => {
+    const samples = Array.from({ length: 100 }, (_, i) => generateRamp(i / 100));
+    expect(Math.min(...samples)).toBeGreaterThanOrEqual(0);
+    expect(Math.max(...samples)).toBeLessThanOrEqual(1);
+  });
+
+  test('is linear', () => {
+    expect(generateRamp(0.25)).toBe(0.75);
+    expect(generateRamp(0.75)).toBe(0.25);
+  });
+});
+
+describe('Random Waveform', () => {
+  test('returns current random value when step unchanged', () => {
+    const state = createMockState({ randomValue: 0.5, randomStep: 0 });
+    const result = generateRandom(0.01, state); // Still in step 0
+    expect(result.value).toBe(0.5);
+    expect(result.newRandomStep).toBe(0);
+  });
+
+  test('generates new random value on step change', () => {
+    const state = createMockState({ randomValue: 0.5, randomStep: 0 });
+    const result = generateRandom(0.1, state); // Step 1 (16 steps per cycle)
+    expect(result.newRandomStep).toBe(1);
+    expect(result.newRandomValue).not.toBe(0.5); // New random value (with high probability)
+  });
+
+  test('has 16 steps per cycle', () => {
+    const stepPhases = [0, 0.0625, 0.125, 0.1875, 0.25];
+    const expectedSteps = [0, 1, 2, 3, 4];
+
+    stepPhases.forEach((phase, i) => {
+      expect(Math.floor(phase * 16)).toBe(expectedSteps[i]);
+    });
+  });
+
+  test('generates values in bipolar range (-1 to +1)', () => {
+    const state = createMockState({ randomStep: -1 }); // Force new value generation
+    const values: number[] = [];
+
+    for (let i = 0; i < 100; i++) {
+      const result = generateRandom(i / 100, state);
+      values.push(result.value);
+      state.randomStep = result.newRandomStep;
+      state.randomValue = result.newRandomValue;
+    }
+
+    expect(Math.min(...values)).toBeGreaterThanOrEqual(-1);
+    expect(Math.max(...values)).toBeLessThanOrEqual(1);
+  });
+});
+
+describe('generateWaveform', () => {
+  test('routes to correct waveform generator', () => {
+    const state = createMockState();
+
+    expect(generateWaveform('TRI', 0.25, state).value).toBeCloseTo(1, 5);
+    expect(generateWaveform('SIN', 0.25, state).value).toBeCloseTo(1, 5);
+    expect(generateWaveform('SQR', 0.25, state).value).toBe(1);
+    expect(generateWaveform('SAW', 0.5, state).value).toBe(0);
+    expect(generateWaveform('EXP', 1, state).value).toBeCloseTo(1, 5);
+    expect(generateWaveform('RMP', 0, state).value).toBe(1);
+  });
+});
+
+describe('isUnipolar', () => {
+  test('identifies unipolar waveforms', () => {
+    expect(isUnipolar('EXP')).toBe(true);
+    expect(isUnipolar('RMP')).toBe(true);
+  });
+
+  test('identifies bipolar waveforms', () => {
+    expect(isUnipolar('TRI')).toBe(false);
+    expect(isUnipolar('SIN')).toBe(false);
+    expect(isUnipolar('SQR')).toBe(false);
+    expect(isUnipolar('SAW')).toBe(false);
+    expect(isUnipolar('RND')).toBe(false);
+  });
+});
+
+describe('getWaveformRange', () => {
+  test('returns correct range for unipolar waveforms', () => {
+    expect(getWaveformRange('EXP')).toEqual({ min: 0, max: 1 });
+    expect(getWaveformRange('RMP')).toEqual({ min: 0, max: 1 });
+  });
+
+  test('returns correct range for bipolar waveforms', () => {
+    expect(getWaveformRange('TRI')).toEqual({ min: -1, max: 1 });
+    expect(getWaveformRange('SIN')).toEqual({ min: -1, max: 1 });
+    expect(getWaveformRange('SQR')).toEqual({ min: -1, max: 1 });
+    expect(getWaveformRange('SAW')).toEqual({ min: -1, max: 1 });
+    expect(getWaveformRange('RND')).toEqual({ min: -1, max: 1 });
+  });
+});

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*", "tests/**/*"]
+}