1/*
2stateful.mjs - File of shame for stateful, impure and otherwise illegal pattern methods
3Copyright (C) 2025 Strudel contributors - see <https://codeberg.org/uzu/strudel/src/branch/main/packages/core/index.mjs>
4This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program.  If not, see <https://www.gnu.org/licenses/>.
5*/
6
7import { register, reify, Pattern } from './pattern.mjs';
8
9let timelines = {};
10
11export const reset_state = function () {
12  reset_timelines();
13};
14
15export const reset_timelines = function () {
16  timelines = {};
17};
18
19/***
20 * Allows you to switch a pattern between different 'timelines'. This is particularly useful when
21 * live coding, for example when you want to cue a pattern up to play from its start.
22 *
23 * Timelines are specified by number, so that if you had a pattern like
24 * `n("<0 1 2 3>").s("num").timeline(1)` playing, then changed the '1'
25 * to '2', it would always align '0' to the nearest cycle. You will likely want to trigger
26 * an evaluation a little bit before the cycle starts, to avoid missing events.
27 *
28 * After the first use, a timeline will continue with the same 'offset'. That is, if you change
29 * a pattern without changing its timeline number, it will stay on that timeline without resetting.
30 *
31 * Rather than incrementing a timeline to reset it, it's easier to negate it, e.g. by switching between `-2`
32 * and `2`. This is because when you negate a timeline it will always reset.
33 *
34 * You can also pattern the timeline if you want, to create strange resetting patterns.
35 * @param {number | Pattern} timeline The timeline that the pattern should play on.
36 * @example
37 * n("<0 1 2 3>(3,8)")
38 *   .sound("num")
39 *   // resets the timeline every two cycles, by negating the timeline.
40 *   // in a lot of cases this will be edited by a human live coder
41 *   // rather than patterned!
42 *   .timeline("<2 -2>".slow(2))
43 */
44
45export const timeline = register(
46  'timeline',
47  function (tpat, pat) {
48    tpat = reify(tpat);
49    const f = function (state) {
50      // Is this called from the scheduler? (rather than from e.g. the visualiser)
51      const scheduler = !!state.controls.cyclist;
52      const timehaps = tpat.query(state);
53      const result = [];
54      for (const timehap of timehaps) {
55        const tlid = timehap.value;
56        let offset;
57        if (tlid === 0) {
58          offset = 0;
59        } else if (tlid in timelines) {
60          offset = timelines[tlid];
61        } else {
62          const timearc = timehap.wholeOrPart();
63          if (!scheduler || state.span.begin.lt(timearc.midpoint())) {
64            offset = timearc.begin;
65          } else {
66            // Sync to end of timearc if we first see it over halfway into its
67            // timespan. Allows 'cuing up' next timeline when live coding.
68            offset = timearc.end;
69          }
70        }
71        if (scheduler) {
72          // update state
73          timelines[tlid] = offset;
74          if (tlid !== 0) {
75            delete timelines[-tlid];
76          }
77        }
78
79        const pathaps = pat
80          .late(offset)
81          .query(state.setSpan(timehap.part))
82          .map((h) => h.setContext(h.combineContext(timehap)));
83        result.push(...pathaps);
84      }
85      return result;
86    };
87    return new Pattern(f, pat._steps);
88  },
89  false,
90);