# @gyral/time

> Gyral time: delays, debounces and wall-clock ticks (every) as commands.

Source: https://gyral.dev/docs/api/time/

Gyral time: delays, debounces and wall-clock ticks (every) as commands.

```sh
npm install @gyral/time
```

> **Writing code? Start from working code, not from this page.** [Effects and drivers](https://gyral.dev/docs/effects/). Adapt the closest example and check it, then look a name up here when you are about to call it.

Generated from the package's type declarations. Entry points: [`@gyral/time`](#gyraltime).

## `@gyral/time`

### Functions

| Name | Summary |
| --- | --- |
| [`debounce`](#time-debounce) | Sends `msg` once `ms` pass without another `debounce` in the same lane: a delay under `switch`, so each call cancels the pending one. |
| [`delay`](#time-delay) | Sends `msg` after `ms`. |
| [`every`](#time-every) | Sends `toMsg(now)` at once and then every `ms`, `now` being `Date.now()` (virtual under `virtualTime()`), until it is stopped. |

#### `debounce`

```ts
function debounce<M>(ms: number, msg: M, key?: string): Command<M>;
```

Sends `msg` once `ms` pass without another `debounce` in the same lane: a delay under
`switch`, so each call cancels the pending one.

#### `delay`

```ts
function delay<M>(ms: number, msg: M, lane?: Lane): Command<M>;
```

Sends `msg` after `ms`. By default every delay runs (`merge` in lane `time:delay`).

#### `every`

```ts
function every<M>(ms: number, toMsg: (now: number) => M | undefined, key?: string): Command<M>;
```

Sends `toMsg(now)` at once and then every `ms`, `now` being `Date.now()` (virtual under
`virtualTime()`), until it is stopped. Made for `subscriptions` (ADR 0025):
`subscriptions: (s) => (s.live ? [every(1000, (now) => ({ _tag: 'Tick', now }))] : [])`.
Each `every` runs in lane `key` (`switch`: another one in the same lane replaces it).

### Constants

| Name | Summary |
| --- | --- |
| [`time`](#time-time) | The default time driver. |

#### `time`

```ts
const time: TimeDriver
```

The default time driver.

### Types and interfaces

You rarely write most of these yourself: TypeScript infers them from the functions above. Look one up when an example or a compiler error names it.

| Name | Summary |
| --- | --- |
| [`Frame`](#time-frame) | One animation frame: the rAF timestamp and the time since the previous frame. |
| [`Lane`](#time-lane) | Concurrency lane for a timer. |
| [`TimeDriver`](#time-timedriver) |  |
| [`TimeInput`](#time-timeinput) |  |
| [`TimeOutput`](#time-timeoutput) | Delays resolve `undefined`; `every` streams wall-clock times (`Date.now()`); frames stream `Frame`s. |

#### `Frame`

```ts
interface Frame {
    readonly time: number;
    readonly delta: number;
}
```

One animation frame: the rAF timestamp and the time since the previous frame.

#### `Lane`

```ts
interface Lane {
    /** Lane name. Default: one shared lane per command kind (see each command). */
    readonly key?: string;
    readonly concurrency?: Concurrency;
}
```

Concurrency lane for a timer. Timers in different lanes run independently.

#### `TimeDriver`

```ts
type TimeDriver = Driver<TimeInput, TimeOutput>;
```


#### `TimeInput`

```ts
type TimeInput = {
    readonly _tag: 'Delay';
    readonly ms: number;
} | {
    readonly _tag: 'Every';
    readonly ms: number;
} | {
    readonly _tag: 'Frames';
};
```


#### `TimeOutput`

```ts
type TimeOutput = undefined | number | Frame;
```

Delays resolve `undefined`; `every` streams wall-clock times (`Date.now()`); frames stream `Frame`s.