chooseInWith, choose2, randcat, and some reformatting

packages/core/signal.mjs

@@ -47,7 +47,6 @@ export const sine2 = signal((t) => Math.sin(Math.PI * 2 * t));
  */
 export const sine = sine2._fromBipolar();
 
-
 /**
  *  A cosine signal between 0 and 1.
  *
@@ -59,7 +58,6 @@ export const sine = sine2._fromBipolar();
 export const cosine = sine._early(Fraction(1).div(4));
 export const cosine2 = sine2._early(Fraction(1).div(4));
 
-
 /**
  *  A square signal between 0 and 1.
  *
@@ -112,7 +110,14 @@ const timeToRandsPrime = (seed, n) => {
 
 const timeToRands = (t, n) => timeToRandsPrime(timeToIntSeed(t), n);
 
+/**
+ * A continuous pattern of random numbers, between 0 and 1
+ */
 export const rand = signal(timeToRand);
+/**
+ * A continuous pattern of random numbers, between -1 and 1
+ */
+ export const rand2 = rand._toBipolar();
 
 export const _brandBy = (p) => rand.fmap((x) => x < p);
 export const brandBy = (pPat) => reify(pPat).fmap(_brandBy).innerJoin();
@@ -121,32 +126,67 @@ export const brand = _brandBy(0.5);
 export const _irand = (i) => rand.fmap((x) => Math.trunc(x * i));
 export const irand = (ipat) => reify(ipat).fmap(_irand).innerJoin();
 
-export const chooseWith = (pat, xs) => {
+export const __chooseWith = (pat, xs) => {
   xs = xs.map(reify);
   if (xs.length == 0) {
     return silence;
   }
-  return pat
-    .range(0, xs.length)
-    .fmap((i) => xs[Math.floor(i)])
-    .outerJoin();
+  return pat.range(0, xs.length).fmap((i) => xs[Math.floor(i)]);
+};
+/**
+ * Choose from the list of values (or patterns of values) using the given
+ * pattern of numbers, which should be in the range of 0..1
+ * @param {Pattern} pat 
+ * @param {*} xs 
+ * @returns 
+ */
+export const chooseWith = (pat, xs) => {
+  return __chooseWith(pat, xs).outerJoin();
+};
+
+/**
+ * As with {chooseWith}, but the structure comes from the chosen values, rather
+ * than the pattern you're using to choose with.
+ * @param {Pattern} pat 
+ * @param {*} xs 
+ * @returns 
+ */
+export const chooseInWith = (pat, xs) => {
+  return __chooseWith(pat, xs).innerJoin();
 };
 
+/**
+ * Chooses randomly from the given list of values.
+ * @param  {...any} xs
+ * @returns {Pattern} - a continuous pattern.
+ */
 export const choose = (...xs) => chooseWith(rand, xs);
 
-export const chooseInWith = (pat, xs) => {
-  xs = xs.map(reify);
-  if (xs.length == 0) {
-    return silence;
-  }
-  return pat
-    .range(0, xs.length)
-    .fmap((i) => xs[Math.floor(i)])
-    .innerJoin();
+/**
+ * Chooses from the given list of values (or patterns of values), according
+ * to the pattern that the method is called on. The pattern should be in
+ * the range 0 .. 1.
+ * @param  {...any} xs
+ * @returns {Pattern}
+ */
+Pattern.prototype.choose = function (...xs) {
+  return chooseWith(this, xs);
+};
+
+/**
+ * As with choose, but the pattern that this method is called on should be
+ * in the range -1 .. 1
+ * @param  {...any} xs
+ * @returns {Pattern}
+ */
+ Pattern.prototype.choose2 = function (...xs) {
+  return chooseWith(this._fromBipolar(), xs);
 };
 
 export const chooseCycles = (...xs) => chooseInWith(rand.segment(1), xs);
 
+export const randcat = chooseCycles;
+
 const _wchooseWith = function (pat, ...pairs) {
   const values = pairs.map((pair) => reify(pair[0]));
   const weights = [];