refactor(dsp): various minor additions, updates, renames, docs

thi-ng · Jan 15, 2020 · e5e1a22 · e5e1a22
1 parent bf506a5
commit e5e1a22
Show file tree

Hide file tree

Showing 14 changed files with 138 additions and 93 deletions.
diff --git a/packages/dsp/src/gen/add.ts b/packages/dsp/src/gen/add.ts
@@ -10,8 +10,9 @@ import { AGen } from "./agen";
 export const add = (step?: number, start?: number) => new Add(step, start);
 
 /**
- * Creates a new `Add` gen based on given `start` (default: 0) and `end`
- * (default: 1) positions and tracing a line over `num` steps.
+ * Timebased version of {@link add}. Creates a new `Add` gen based on
+ * given `start` (default: 0) and `end` (default: 1) positions and
+ * tracing a line over `num` steps.
  *
  * @remarks
  * Since `start` will be the first generated value, the `end` value is

diff --git a/packages/dsp/src/gen/addg.ts b/packages/dsp/src/gen/addg.ts
@@ -1,5 +1,5 @@
 import { IGen } from "../api";
-import { Comp1 } from "./comp";
+import { CompG1 } from "./comp";
 
 /**
  * Creates a new {@link IGen} using given `step` gen and `start
@@ -20,4 +20,4 @@ import { Comp1 } from "./comp";
  * @param start
  */
 export const addg = (step: IGen<number>, start = 0) =>
-    new Comp1((a, b) => a + b, step, start - step.deref());
+    new CompG1((a, b) => a + b, step, start - step.deref());
diff --git a/packages/dsp/src/gen/alt.ts b/packages/dsp/src/gen/alt.ts
@@ -1,8 +1,8 @@
 import { AGen } from "./agen";
 
-export const alt = <T>(a: T, b: T) => new Alt(a, b);
+export const alt = (n = 1) => new Alt(n, -n);
 
-export const altN = (n = 1) => new Alt(n, -n);
+export const altT = <T>(a: T, b: T) => new Alt(a, b);
 
 export const altB = (x = true) => new Alt(x, !x);
 

diff --git a/packages/dsp/src/gen/comp.ts b/packages/dsp/src/gen/comp.ts
@@ -1,8 +1,41 @@
-import { Fn2, Fn3, Fn4 } from "@thi.ng/api";
+import {
+    Fn2,
+    Fn3,
+    Fn4,
+    FnAny
+} from "@thi.ng/api";
+import { illegalArity } from "@thi.ng/errors";
 import { IGen } from "../api";
 import { AGen } from "./agen";
 
-export class Comp1<A, T> extends AGen<T> {
+export function compG<A, T>(op: Fn2<A, T, T>, a: IGen<A>, init: T): IGen<T>;
+export function compG<A, B, T>(
+    op: Fn3<A, B, T, T>,
+    a: IGen<A>,
+    b: IGen<B>,
+    init: T
+): IGen<T>;
+export function compG<A, B, C, T>(
+    op: Fn4<A, B, C, T, T>,
+    a: IGen<A>,
+    b: IGen<B>,
+    c: IGen<C>,
+    init: T
+): IGen<T>;
+export function compG(op: FnAny<any>, ...args: any[]): IGen<any> {
+    switch (args.length) {
+        case 2:
+            return new CompG1(op, args[0], args[1]);
+        case 3:
+            return new CompG2(op, args[0], args[1], args[2]);
+        case 4:
+            return new CompG3(op, args[0], args[1], args[2], args[3]);
+        default:
+            illegalArity(args.length);
+    }
+}
+
+export class CompG1<A, T> extends AGen<T> {
     constructor(protected _op: Fn2<A, T, T>, protected _a: IGen<A>, init: T) {
         super(init);
     }
@@ -12,7 +45,7 @@ export class Comp1<A, T> extends AGen<T> {
     }
 }
 
-export class Comp2<A, B, T> extends AGen<T> {
+export class CompG2<A, B, T> extends AGen<T> {
     constructor(
         protected _op: Fn3<A, B, T, T>,
         protected _a: IGen<A>,
@@ -31,7 +64,7 @@ export class Comp2<A, B, T> extends AGen<T> {
     }
 }
 
-export class Comp3<A, B, C, T> extends AGen<T> {
+export class CompG3<A, B, C, T> extends AGen<T> {
     constructor(
         protected _op: Fn4<A, B, C, T, T>,
         protected _a: IGen<A>,

diff --git a/packages/dsp/src/gen/cosp.ts → packages/dsp/src/gen/cosine.ts b/packages/dsp/src/gen/cosp.ts → packages/dsp/src/gen/cosine.ts
@@ -8,9 +8,9 @@ import { AGen } from "./agen";
  * @param freq -
  * @param amp -
  */
-export const cosp = (freq: number, amp?: number) => new CosP(freq, amp);
+export const cosine = (freq: number, amp?: number) => new Cosine(freq, amp);
 
-export class CosP extends AGen<number> {
+export class Cosine extends AGen<number> {
     protected _cos!: number;
     protected _nxt!: number;
 

diff --git a/packages/dsp/src/gen/impulse-train.ts b/packages/dsp/src/gen/impulse-train.ts
@@ -0,0 +1,39 @@
+import { AGen } from "./agen";
+
+/**
+ * https://en.wikipedia.org/wiki/Dirac_comb
+ *
+ * @param period -
+ * @param start -
+ */
+export const impulseTrain = (period: number, start?: number) =>
+    new ImpulseTrain(1, 0, period, start);
+
+export const impulseTrainT = <T>(
+    on: T,
+    off: T,
+    period: number,
+    start?: number
+) => new ImpulseTrain(on, off, period, start);
+
+export const impulseTrainB = (period: number, start?: number) =>
+    new ImpulseTrain(true, false, period, start);
+
+export class ImpulseTrain<T> extends AGen<T> {
+    constructor(
+        protected _on: T,
+        protected _off: T,
+        protected _period: number,
+        protected _pos = 0
+    ) {
+        super(_off);
+        this._pos--;
+    }
+
+    next() {
+        return (this._val =
+            ++this._pos >= this._period
+                ? ((this._pos = 0), this._on)
+                : this._off);
+    }
+}
diff --git a/packages/dsp/src/gen/impulse.ts b/packages/dsp/src/gen/impulse.ts
@@ -1,24 +1,24 @@
 import { AGen } from "./agen";
 
 /**
- * Creates a new impulse gen, producing `on` for the first invocation of
- * {@link IGen.next}, then `off` thereafter.
+ * Numeric version of {@link impulseT}, using given `on` (default: 1) as
+ * initial value and zero for the remaining values.
  *
- * @param on - impulse value
- * @param off -
+ * @param on
  */
-export const impulse = <T>(on: T, off: T) => new Impulse<T>(on, off);
+export const impulse = (on = 1) => new Impulse(on, 0);
 
 /**
- * Numeric version of {@link impulse}, using given `on` (default: 1) as
- * initial value and zero for the remaining values.
+ * Creates a new impulse gen, producing a single `on` for the first
+ * invocation of {@link IGen.next}, then only `off` thereafter.
  *
- * @param on
+ * @param on - impulse value
+ * @param off -
  */
-export const impulseN = (on = 1) => new Impulse(on, 0);
+export const impulseT = <T>(on: T, off: T) => new Impulse<T>(on, off);
 
 /**
- * Boolean version of {@link impulse}, using given `start` (default:
+ * Boolean version of {@link impulseT}, using given `start` (default:
  * true) as initial value and its inverse for the remaining values.
  *
  * @param start

diff --git a/packages/dsp/src/gen/osc.ts b/packages/dsp/src/gen/osc.ts
@@ -39,29 +39,30 @@ export const osc = (
  * Syntax sugar for creating frequency modulated `Osc` gens.
  *
  * @remarks
- * The `modAmp` value defines the +/- normalized frequency modulation
+ * The `fmod` value defines the +/- normalized frequency modulation
  * range, added to the main oscillator `freq`.
  *
  * @example
  * ```ts
- * // rect modulated sin oscillator
- * fmodOsc(sin, osc(rect, 0.1, 0.2), 0.01)
+ * // FM sin osc using rect osc as modulator
+ * modOsc(sin, 0.01, osc(rect, 0.1, 0.2))
  *
+ * // FM & AM sin osc using rect osc as fmod and saw as amod
+ * modOsc(sin, 0.01, osc(rect, 0.1, 0.2), osc(saw, 0.05))
  *
  * ```
  *
- * @param osc
- * @param freq - normalized freq
- * @param modFreq - normalized freq
- * @param modAmp - normalized freq
- * @param phase - normalized start phase
+ * @param osc - stateless main osc
+ * @param freq - main osc freq
+ * @param fmod - freq modulator
+ * @param amod` - normalized freq
  */
 export const modOsc = (
     osc: StatelessOscillator,
-    mod: IGen<number>,
     freq: IGen<number> | number,
-    amp: IGen<number> | number
-) => new Osc(osc, sum(mod, isNumber(freq) ? add(freq) : freq), amp);
+    fmod: IGen<number>,
+    amod: IGen<number> | number = 1
+) => new Osc(osc, sum(fmod, isNumber(freq) ? add(freq) : freq), amod);
 
 export class Osc extends AGen<number> {
     protected _phase!: IGen<number>;

diff --git a/packages/dsp/src/gen/product.ts b/packages/dsp/src/gen/product.ts
@@ -1,5 +1,5 @@
 import { IGen } from "../api";
-import { Comp2, Comp3 } from "./comp";
+import { CompG2, CompG3 } from "./comp";
 
 /**
  * Higher order gen. Returns a {@link Comp2} or {@link Comp3} yielding
@@ -8,17 +8,14 @@ import { Comp2, Comp3 } from "./comp";
  * @param a - factor
  * @param b - factor
  */
-export function product(
-    a: IGen<number>,
-    b: IGen<number>
-): Comp2<number, number, number>;
+export function product(a: IGen<number>, b: IGen<number>): IGen<number>;
 export function product(
     a: IGen<number>,
     b: IGen<number>,
     c: IGen<number>
-): Comp3<number, number, number, number>;
+): IGen<number>;
 export function product(a: IGen<number>, b: IGen<number>, c?: IGen<number>) {
     return c
-        ? new Comp3((a, b, c) => a * b * c, a, b, c, 0)
-        : new Comp2((a, b) => a * b, a, b, 0);
+        ? new CompG3((a, b, c) => a * b * c, a, b, c, 0)
+        : new CompG2((a, b) => a * b, a, b, 0);
 }
diff --git a/packages/dsp/src/gen/reciprocal.ts b/packages/dsp/src/gen/reciprocal.ts
@@ -1,7 +1,15 @@
 import { AGen } from "./agen";
 
+/**
+ * Returns a gen which yield sequence `y(t) = 1 / (y(t - 1) + step)`.
+ *
+ * @param step
+ */
+export const reciprocal = (step?: number) => new Reciprocal(step);
+
 export class Reciprocal extends AGen<number> {
     protected _n: number;
+
     constructor(protected _step = 1) {
         super(1);
         this._n = 1 - this._step;
@@ -12,5 +20,3 @@ export class Reciprocal extends AGen<number> {
         return (this._val = 1 / this._n);
     }
 }
-
-export const reciprocal = (step?: number) => new Reciprocal(step);
diff --git a/packages/dsp/src/gen/sum.ts b/packages/dsp/src/gen/sum.ts
@@ -1,5 +1,5 @@
 import { IGen } from "../api";
-import { Comp2, Comp3 } from "./comp";
+import { CompG2, CompG3 } from "./comp";
 
 /**
  * Higher order gen. Returns a {@link Comp2} or {@link Comp3} yielding
@@ -8,17 +8,14 @@ import { Comp2, Comp3 } from "./comp";
  * @param a - summand
  * @param b - summand
  */
-export function sum(
-    a: IGen<number>,
-    b: IGen<number>
-): Comp2<number, number, number>;
+export function sum(a: IGen<number>, b: IGen<number>): IGen<number>;
 export function sum(
     a: IGen<number>,
     b: IGen<number>,
     c: IGen<number>
-): Comp3<number, number, number, number>;
+): IGen<number>;
 export function sum(a: IGen<number>, b: IGen<number>, c?: IGen<number>) {
     return c
-        ? new Comp3((a, b, c) => a + b + c, a, b, c, 0)
-        : new Comp2((a, b) => a + b, a, b, 0);
+        ? new CompG3((a, b, c) => a + b + c, a, b, c, 0)
+        : new CompG2((a, b) => a + b, a, b, 0);
 }
diff --git a/packages/dsp/src/gen/trigger.ts b/packages/dsp/src/gen/trigger.ts
diff --git a/packages/dsp/src/index.ts b/packages/dsp/src/index.ts
@@ -9,15 +9,15 @@ export * from "./gen/agen";
 export * from "./gen/alt";
 export * from "./gen/comp";
 export * from "./gen/const";
-export * from "./gen/cosp";
+export * from "./gen/cosine";
 export * from "./gen/impulse";
+export * from "./gen/impulse-train";
 export * from "./gen/madd";
 export * from "./gen/mul";
 export * from "./gen/osc";
 export * from "./gen/product";
 export * from "./gen/reciprocal";
 export * from "./gen/sum";
-export * from "./gen/trigger";
 export * from "./gen/wrap-around";
 
 export * from "./proc/allpass";