Attempt at keep documentation

packages/core/pattern.mjs

@@ -1061,10 +1061,12 @@ const COMPOSERS = {
    * combines `a` and `b` such that anything defined in `b`
    * overwrites the corresponding value in `a`
    *
+   * This is the inverse of `keep`
+   *
    * See examples below
    * @name set
    * @param {Pattern} pat
-   * @returns Pattern
+   * @returns {Pattern}
    * @memberof Pattern
    * @tags internal, combiners
    * @example
@@ -1087,6 +1089,25 @@ const COMPOSERS = {
    * })
    */
   set: [(a, b) => b],
+  /**
+   * When called on a pattern `a`, with a input pattern `b` (`a.keep(b)`),
+   * combines `a` and `b` such that anything defined in `a`
+   * overwrites the corresponding value in `b`
+   *
+   * This is the inverse of `set`
+   *
+   * See examples below
+   * @name keep
+   * @param {Pattern} pat
+   * @memberof Pattern
+   * @returns {Pattern}
+   * @tags internal, combiners
+   * @example
+   * // Struct, already defined in original pattern
+   * // Is combined with the input, such that we get
+   * // c c a a f f e e
+   * pure(0).struct("x!8").keep(note("c a f e"))
+   */
   keep: [(a) => a],
   keepif: [(a, b) => (b ? a : undefined)],
 

test/__snapshots__/examples.test.mjs.snap

@@ -6403,6 +6403,43 @@ exports[`runs examples > example "juxBy" example index 0 1`] = `
 ]
 `;
 
+exports[`runs examples > example "keep" example index 0 1`] = `
+[
+  "[ 0/1 → 1/8 | value:0 note:c ]",
+  "[ 1/8 → 1/4 | value:0 note:c ]",
+  "[ 1/4 → 3/8 | value:0 note:a ]",
+  "[ 3/8 → 1/2 | value:0 note:a ]",
+  "[ 1/2 → 5/8 | value:0 note:f ]",
+  "[ 5/8 → 3/4 | value:0 note:f ]",
+  "[ 3/4 → 7/8 | value:0 note:e ]",
+  "[ 7/8 → 1/1 | value:0 note:e ]",
+  "[ 1/1 → 9/8 | value:0 note:c ]",
+  "[ 9/8 → 5/4 | value:0 note:c ]",
+  "[ 5/4 → 11/8 | value:0 note:a ]",
+  "[ 11/8 → 3/2 | value:0 note:a ]",
+  "[ 3/2 → 13/8 | value:0 note:f ]",
+  "[ 13/8 → 7/4 | value:0 note:f ]",
+  "[ 7/4 → 15/8 | value:0 note:e ]",
+  "[ 15/8 → 2/1 | value:0 note:e ]",
+  "[ 2/1 → 17/8 | value:0 note:c ]",
+  "[ 17/8 → 9/4 | value:0 note:c ]",
+  "[ 9/4 → 19/8 | value:0 note:a ]",
+  "[ 19/8 → 5/2 | value:0 note:a ]",
+  "[ 5/2 → 21/8 | value:0 note:f ]",
+  "[ 21/8 → 11/4 | value:0 note:f ]",
+  "[ 11/4 → 23/8 | value:0 note:e ]",
+  "[ 23/8 → 3/1 | value:0 note:e ]",
+  "[ 3/1 → 25/8 | value:0 note:c ]",
+  "[ 25/8 → 13/4 | value:0 note:c ]",
+  "[ 13/4 → 27/8 | value:0 note:a ]",
+  "[ 27/8 → 7/2 | value:0 note:a ]",
+  "[ 7/2 → 29/8 | value:0 note:f ]",
+  "[ 29/8 → 15/4 | value:0 note:f ]",
+  "[ 15/4 → 31/8 | value:0 note:e ]",
+  "[ 31/8 → 4/1 | value:0 note:e ]",
+]
+`;
+
 exports[`runs examples > example "keyDown" example index 0 1`] = `[]`;
 
 exports[`runs examples > example "lastOf" example index 0 1`] = `