n1kben/elm-debounce/1.0.0

NOTE: the latest version is 1.0.1

Debounce

Debounce tasks while keeping their lifecycle explicit in update.

The input remains in your application model. Debounce stores only the revision and execution status needed to ignore superseded timers and tasks.

Types

type Debounce error output

State for one debounced task.

The type is opaque so revision bookkeeping cannot get out of sync.

type Msg input error output

Internal messages produced by a debounced task.

Wrap this in one constructor of your application's Msg type and pass it to update.

type Status error output
= Idle
| Waiting
| Running
| Completed (Result error output)

The observable lifecycle of a debounced task.

Waiting means the delay has not elapsed. Running means the task has started. Completed retains its latest result until another operation starts or the state is cancelled.

Lifecycle

init : Debounce error output

Create idle debounce state.

Float
-> input
-> Debounce error output
-> ( Debounce error output, Cmd (Msg input error output) )

Schedule an input to run after the given number of milliseconds.

Scheduling again supersedes the previous timer. Superseded timers may still wake, but update ignores them and never starts their tasks.

(input -> Task error output)
-> input
-> Debounce error output
-> ( Debounce error output, Cmd (Msg input error output) )

Start a task immediately, superseding any scheduled or running task.

This is useful on submit, where the same work should run without the debounce delay.

(input -> Task error output)
-> Msg input error output
-> Debounce error output
-> ( Debounce error output, Cmd (Msg input error output) )

Handle a debounce sub-message.

When the current delay elapses, this starts the supplied task. When the task finishes, its result is stored in the status. Messages from superseded revisions are ignored.

State

cancel : Debounce error output -> Debounce error output

Cancel scheduled or running work and return to Idle.

Elm does not expose the process behind Task.perform, so this is logical cancellation: later messages from the cancelled revision are ignored.

status : Debounce error output -> Status error output

Inspect the current lifecycle status.