@kontsedal/olas-core 0.0.5 → 0.1.0

package/src/timing/debounced.ts

@@ -1,52 +1,135 @@
 import { effect, signal } from '../signals'
+import { readOnly } from '../signals/readonly'
 import type { ReadSignal } from '../signals/types'
 
+/**
+ * A `ReadSignal<T>` returned by `debounced` / `throttled`. Extends the
+ * subscription surface with manual `cancel()` and `flush()`.
+ *
+ * - `cancel()` drops any pending emission without firing. Useful when a
+ *   navigation away from the screen should discard the latest in-flight
+ *   draft instead of writing it through to the debounced output.
+ * - `flush()` immediately emits the pending value (if any). Useful at
+ *   submit time: "commit whatever the user just typed without waiting
+ *   for the debounce timer to fire."
+ *
+ * Both are no-ops when nothing is pending.
+ */
+export type TimingSignal<T> = ReadSignal<T> & {
+  cancel(): void
+  flush(): void
+  /**
+   * Tear down the internal effect (drop the subscription to `source`) and
+   * clear any pending timer. Idempotent. Call this when the timing signal
+   * has no `options.signal` tying its lifecycle to an AbortController —
+   * otherwise the effect keeps `source` subscribed forever.
+   */
+  dispose(): void
+}
+
 /**
  * Lag a signal by `ms`. The returned signal updates only after the source has
  * been unchanged for `ms`. Each new write resets the timer.
  *
- * Pass `options.signal` (an `AbortSignal`) to tie the internal effect to a
- * lifecycle — when the signal aborts the effect disposes, the pending timer
- * clears, and the subscriber chain on `source` drops. Without `signal`, the
- * effect lives as long as `source` does; pass a signal whenever the source
- * outlives the consumer.
+ * - `leading: true` (default `false`) emits immediately on the first write,
+ *   then suppresses further writes until `ms` has passed since the last
+ *   emission. Combine with trailing (default `true`) for "first + last"
+ *   semantics.
+ * - `trailing: false` disables the trailing emission. Pair with
+ *   `leading: true` for "only fire on the leading edge" semantics.
+ * - `options.signal` (`AbortSignal`) ties the internal effect to a
+ *   lifecycle — when the signal aborts the effect disposes, the pending
+ *   timer clears, and the subscriber chain on `source` drops.
  */
 export function debounced<T>(
   source: ReadSignal<T>,
   ms: number,
-  options?: { signal?: AbortSignal },
-): ReadSignal<T> {
+  options?: { signal?: AbortSignal; leading?: boolean; trailing?: boolean },
+): TimingSignal<T> {
+  const leading = options?.leading ?? false
+  const trailing = options?.trailing ?? true
+  if (!leading && !trailing) {
+    throw new Error(
+      '[olas] debounced: at least one of `leading` or `trailing` must be true (both false never emits).',
+    )
+  }
   const out = signal<T>(source.peek())
   let timer: ReturnType<typeof setTimeout> | null = null
+  let pendingValue: T = source.peek()
+  let hasPending = false
   let initial = true
+  let inCooldown = false
+
+  const fireTrailing = () => {
+    timer = null
+    inCooldown = false
+    if (hasPending && trailing) {
+      out.set(pendingValue)
+      hasPending = false
+    }
+  }
 
-  const dispose = effect(() => {
+  const disposeEffect = effect(() => {
     const value = source.value
     if (initial) {
-      // The first effect run reads the source for tracking; we already
-      // initialized `out` to the same value, so skip scheduling.
       initial = false
       return
     }
+    pendingValue = value
     if (timer != null) clearTimeout(timer)
-    timer = setTimeout(() => {
+    if (leading && !inCooldown) {
+      // Leading edge — emit now, start a cooldown timer that, if untouched
+      // by another write, fires the trailing edge with the same value.
       out.set(value)
-      timer = null
-    }, ms)
+      hasPending = false
+      inCooldown = true
+      timer = setTimeout(fireTrailing, ms)
+    } else {
+      // Pending only matters if a trailing emit can actually happen. With
+      // `trailing: false` the timer just resets the cooldown and must NOT
+      // leave a value for a later `flush()` to emit. (T2.7)
+      hasPending = trailing
+      timer = setTimeout(fireTrailing, ms)
+    }
   })
 
+  const cancel = () => {
+    if (timer != null) {
+      clearTimeout(timer)
+      timer = null
+    }
+    hasPending = false
+    inCooldown = false
+  }
+  const flush = () => {
+    if (timer != null) {
+      clearTimeout(timer)
+      timer = null
+    }
+    if (hasPending) {
+      out.set(pendingValue)
+      hasPending = false
+    }
+    inCooldown = false
+  }
+
+  const dispose = () => {
+    cancel()
+    disposeEffect()
+  }
+
   const sig = options?.signal
   if (sig) {
-    const stop = () => {
-      if (timer != null) {
-        clearTimeout(timer)
-        timer = null
-      }
-      dispose()
-    }
-    if (sig.aborted) stop()
-    else sig.addEventListener('abort', stop, { once: true })
+    if (sig.aborted) dispose()
+    else sig.addEventListener('abort', dispose, { once: true })
   }
 
-  return out
+  // Expose a read-only projection of `out` plus the control surface. The old
+  // `out as TimingSignal` cast leaked `out.set` to callers. (T2.7)
+  const handle = Object.assign(Object.create(readOnly(out)), {
+    cancel,
+    flush,
+    dispose,
+  }) as TimingSignal<T>
+  return handle
 }

package/src/timing/index.ts

@@ -1,2 +1,2 @@
-export { debounced } from './debounced'
+export { debounced, type TimingSignal } from './debounced'
 export { throttled } from './throttled'

package/src/timing/throttled.ts

@@ -1,65 +1,122 @@
 import { effect, signal } from '../signals'
+import { readOnly } from '../signals/readonly'
 import type { ReadSignal } from '../signals/types'
+import type { TimingSignal } from './debounced'
+
+/**
+ * Time source — `Date.now()`. Stays in lockstep with `vi.setSystemTime()`
+ * for tests that exercise time-jumps; downstream consumers that need a
+ * monotonic clock can pass `options.signal` and gate on system-time
+ * changes externally.
+ */
+function now(): number {
+  return Date.now()
+}
 
 /**
  * Rate-limit a signal so it emits at most once per `ms` (leading + trailing).
  * The first change passes through immediately. Subsequent changes within the
  * window are coalesced; the latest value is emitted when the window expires.
  *
- * Pass `options.signal` to tie the internal effect to a lifecycle — when the
- * signal aborts the effect disposes and any pending trailing timer clears.
- * Without `signal`, the effect lives as long as `source` does.
+ * - `leading: false` (default `true`) skips the immediate leading-edge
+ *   emission. Useful for "fire only after the window settles" semantics.
+ * - `trailing: false` (default `true`) skips the windowed trailing emit.
+ *   Combine with `leading: true` for "only fire on the leading edge."
+ * - `options.signal` ties the internal effect to a lifecycle.
+ *
+ * The returned handle exposes `cancel()` / `flush()` — see `TimingSignal`.
  */
 export function throttled<T>(
   source: ReadSignal<T>,
   ms: number,
-  options?: { signal?: AbortSignal },
-): ReadSignal<T> {
+  options?: { signal?: AbortSignal; leading?: boolean; trailing?: boolean },
+): TimingSignal<T> {
+  const leading = options?.leading ?? true
+  const trailing = options?.trailing ?? true
+  if (!leading && !trailing) {
+    throw new Error(
+      '[olas] throttled: at least one of `leading` or `trailing` must be true (both false never emits).',
+    )
+  }
   const out = signal<T>(source.peek())
   let lastEmit = Number.NEGATIVE_INFINITY
   let trailingTimer: ReturnType<typeof setTimeout> | null = null
   let trailingValue: T = source.peek()
+  let hasPending = false
   let initial = true
 
-  const dispose = effect(() => {
+  const fireTrailing = () => {
+    trailingTimer = null
+    if (hasPending && trailing) {
+      out.set(trailingValue)
+      lastEmit = now()
+      hasPending = false
+    }
+  }
+
+  const disposeEffect = effect(() => {
     const value = source.value
     if (initial) {
       initial = false
       return
     }
-    const now = Date.now()
-    const elapsed = now - lastEmit
-    if (elapsed >= ms) {
+    const t = now()
+    const elapsed = t - lastEmit
+    if (elapsed >= ms && leading) {
       out.set(value)
-      lastEmit = now
+      lastEmit = t
+      hasPending = false
+      // The leading emit consumed the value — drop any stale trailing-pending.
       if (trailingTimer != null) {
         clearTimeout(trailingTimer)
         trailingTimer = null
       }
-    } else {
+    } else if (trailing) {
+      // Coalesce into the trailing edge. With `trailing: false` we schedule
+      // nothing and never set `hasPending`, so a later `flush()` can't emit a
+      // value the option said should never fire. (T2.7)
       trailingValue = value
-      if (trailingTimer == null) {
-        trailingTimer = setTimeout(() => {
-          out.set(trailingValue)
-          lastEmit = Date.now()
-          trailingTimer = null
-        }, ms - elapsed)
-      }
+      hasPending = true
+      const delay = elapsed >= ms ? ms : ms - elapsed
+      if (trailingTimer == null) trailingTimer = setTimeout(fireTrailing, delay)
     }
   })
 
+  const cancel = () => {
+    if (trailingTimer != null) {
+      clearTimeout(trailingTimer)
+      trailingTimer = null
+    }
+    hasPending = false
+  }
+  const flush = () => {
+    if (trailingTimer != null) {
+      clearTimeout(trailingTimer)
+      trailingTimer = null
+    }
+    if (hasPending) {
+      out.set(trailingValue)
+      lastEmit = now()
+      hasPending = false
+    }
+  }
+
+  const dispose = () => {
+    cancel()
+    disposeEffect()
+  }
+
   const sig = options?.signal
   if (sig) {
-    const stop = () => {
-      if (trailingTimer != null) {
-        clearTimeout(trailingTimer)
-        trailingTimer = null
-      }
-      dispose()
-    }
-    if (sig.aborted) stop()
-    else sig.addEventListener('abort', stop, { once: true })
+    if (sig.aborted) dispose()
+    else sig.addEventListener('abort', dispose, { once: true })
   }
 
-  return out
+  // Read-only projection + control surface; the old cast leaked `out.set`. (T2.7)
+  const handle = Object.assign(Object.create(readOnly(out)), {
+    cancel,
+    flush,
+    dispose,
+  }) as TimingSignal<T>
+  return handle
 }

package/src/utils.ts

@@ -24,7 +24,7 @@ export function isAbortError(err: unknown): boolean {
 export function abortableSleep(ms: number, signal: AbortSignal): Promise<void> {
   return new Promise((resolve, reject) => {
     if (signal.aborted) {
-      reject(new DOMException('Aborted', 'AbortError'))
+      reject(abortReason(signal))
       return
     }
     const timer = setTimeout(() => {
@@ -34,8 +34,21 @@ export function abortableSleep(ms: number, signal: AbortSignal): Promise<void> {
     const onAbort = () => {
       clearTimeout(timer)
       signal.removeEventListener('abort', onAbort)
-      reject(new DOMException('Aborted', 'AbortError'))
+      reject(abortReason(signal))
     }
     signal.addEventListener('abort', onAbort, { once: true })
   })
 }
+
+/**
+ * Read the caller-supplied abort reason if present, falling back to the
+ * canonical `DOMException('Aborted', 'AbortError')`. `signal.reason` lets
+ * users propagate context (e.g. "supersededByLatestWins") through abort
+ * chains — discarding it would force every caller to wrap with custom
+ * cancellation tokens.
+ */
+function abortReason(signal: AbortSignal): unknown {
+  const reason: unknown = (signal as { reason?: unknown }).reason
+  if (reason !== undefined) return reason
+  return new DOMException('Aborted', 'AbortError')
+}