feat: Add TimerState

Author: techniq

.changeset/angry-sheep-matter.md

@@ -0,0 +1,5 @@
+---
+'@layerstack/svelte-state': patch
+---
+
+feat: Add `TimerState`

packages/svelte-state/src/lib/timerState.svelte.ts

@@ -0,0 +1,91 @@
+export type TimerOptions<T> = {
+  initial?: T;
+
+  /** Delay between ticks in milliseconds
+   * @default 1000
+   */
+  delay?: number;
+
+  /** Start disabled (manually call `start()`)
+   * @default false
+   */
+  disabled?: boolean;
+
+  /** Called on each interval tick.  Returned value is used to update store value, defaulting to current Date */
+  onTick?: (current: T | null) => any;
+};
+
+/**
+ * Subscribable timer/interval state
+ */
+export class TimerState<T = any> {
+  #initial: T | null;
+  #current: T | null = $state(null);
+  #intervalId: ReturnType<typeof setInterval> | null = null;
+  #delay: number;
+  #disabled: boolean;
+  #running = $state(false);
+  #onTick: (current: T | null) => any;
+
+  constructor(options: TimerOptions<T> = {}) {
+    this.#initial = options.initial ?? null;
+    this.#current = this.#initial;
+    this.#delay = options.delay ?? 1000;
+    this.#disabled = options.disabled ?? false;
+    this.#onTick = options.onTick ?? (() => new Date());
+
+    if (!this.#disabled) {
+      this.start();
+    }
+
+    $effect(() => {
+      return this.stop;
+    });
+  }
+
+  get current() {
+    return this.#current;
+  }
+
+  set current(value: T | null) {
+    if (!this.#disabled) {
+      this.start();
+    }
+
+    this.#current = value;
+  }
+
+  get delay() {
+    return this.#delay;
+  }
+
+  set delay(value: number) {
+    this.stop();
+    this.#delay = value;
+    this.start();
+  }
+
+  start = () => {
+    stop();
+    this.#intervalId = setInterval(() => {
+      this.#current = this.#onTick(this.#current) ?? new Date();
+    }, this.#delay);
+    this.#running = true;
+  };
+
+  stop = () => {
+    if (this.#intervalId) {
+      clearInterval(this.#intervalId);
+    }
+    this.#intervalId = null;
+    this.#running = false;
+  };
+
+  reset = () => {
+    return (this.#current = this.#initial);
+  };
+
+  get running() {
+    return this.#running;
+  }
+}

sites/docs/src/routes/_NavMenu.svelte

@@ -19,7 +19,7 @@
     'styles',
   ];
 
-  const state = ['SelectionState', 'UniqueState'];
+  const state = ['SelectionState', 'TimerState', 'UniqueState'];
 
   const stores = [
     'changeStore',

sites/docs/src/routes/docs/svelte-state/TimerState/+page.svelte

@@ -0,0 +1,55 @@
+<script lang="ts">
+  import { subDays, subMonths } from 'date-fns';
+
+  import { Switch } from 'svelte-ux';
+  import { TimerState } from '@layerstack/svelte-state';
+  import Preview from '$docs/Preview.svelte';
+  import Code from '$docs/Code.svelte';
+
+  const dateTimer = new TimerState({ initial: new Date(), onTick: () => new Date() });
+  const tickTimer = new TimerState({ initial: 0, onTick: (value) => (value ?? 0) + 1 });
+</script>
+
+<h1>Usage</h1>
+
+<Code source={`const timer = new TimerState();`} language="javascript" />
+
+<Code
+  source={`const timer = new TimerState<T>({ initial?: T, onTick?: (value: T) => {...}, delay?: number, disabled?: boolean })`}
+  language="javascript"
+/>
+
+<h1>Examples</h1>
+
+<h2>Default</h2>
+
+<Code source={`const dateTimer = new TimerState();`} language="javascript" />
+
+<Preview>
+  <div>{dateTimer.current}</div>
+  <Switch
+    checked={dateTimer.running}
+    on:change={(e) => {
+      // @ts-expect-error
+      e.target?.checked ? dateTimer.start() : dateTimer.stop();
+    }}
+  />
+</Preview>
+
+<h2>Tick count</h2>
+
+<Code
+  source={`const tickTimer = new TimerState({ initial: 0, onTick: (value) => value + 1 });`}
+  language="javascript"
+/>
+
+<Preview>
+  <div>{tickTimer.current}</div>
+  <Switch
+    checked={tickTimer.running}
+    on:change={(e) => {
+      // @ts-expect-error
+      e.target?.checked ? tickTimer.start() : tickTimer.stop();
+    }}
+  />
+</Preview>

sites/docs/src/routes/docs/svelte-state/TimerState/+page.ts

@@ -0,0 +1,13 @@
+import source from '$svelte-state/timerState.svelte.ts?raw';
+import pageSource from './+page.svelte?raw';
+
+export async function load() {
+  return {
+    meta: {
+      source,
+      pageSource,
+      description: 'Manage interval ticks, useful for timely updates and countdowns',
+      related: ['components/Duration', 'components/ScrollingValue'],
+    },
+  };
+}