timer

function stable

timer(dueTime: number | Date = 0, intervalOrScheduler?: number | SchedulerLike, scheduler: SchedulerLike = asyncScheduler): Observable<number>

Parameters

dueTime

Optional. Default is 0.

Type: number | Date.

intervalOrScheduler

Optional. Default is undefined.

Type: number | SchedulerLike.

scheduler

Optional. Default is asyncScheduler.

Type: SchedulerLike.

Returns

Observable<number>

Overloads

timer(due: number | Date, scheduler?: SchedulerLike): Observable<0>

Creates an observable that will wait for a specified time period, or exact date, before emitting the number 0.

Parameters

due

If a number, the amount of time in milliseconds to wait before emitting. If a Date, the exact time at which to emit.

scheduler

Optional. Default is undefined.

The scheduler to use to schedule the delay. Defaults to asyncScheduler.

Returns

Observable<0>

Used to emit a notification after a delay.

This observable is useful for creating delays in code, or racing against other values for ad-hoc timeouts.

The delay is specified by default in milliseconds, however providing a custom scheduler could create a different behavior.

Examples

Wait 3 seconds and start another observable

You might want to use timer to delay subscription to an observable by a set amount of time. Here we use a timer with concatMapTo or concatMap in order to wait a few seconds and start a subscription to a source.

import { timer, of } from 'rxjs';
import { concatMapTo } from 'rxjs/operators';

// This could be any observable
const source = of(1, 2, 3);

const result = timer(3000).pipe(
  concatMapTo(source)
)
.subscribe(console.log);

Take all of the values until the start of the next minute

Using the a date as the trigger for the first emission, you can do things like wait until midnight to fire an event, or in this case, wait until a new minute starts (chosen so the example wouldn't take too long to run) in order to stop watching a stream. Leveraging takeUntil.

import { interval, timer } from 'rxjs';
import { takeUntil } from 'rxjs/operators';

// Build a Date object that marks the
// next minute.
const currentDate = new Date();
const startOfNextMinute = new Date(
  currentDate.getFullYear(),
  currentDate.getMonth(),
  currentDate.getDate(),
  currentDate.getHours(),
  currentDate.getMinutes() + 1,
)

// This could be any observable stream
const source = interval(1000);

const result = source.pipe(
  takeUntil(timer(startOfNextMinute))
);

result.subscribe(console.log);

Known Limitations

  • The asyncScheduler uses setTimeout which has limitations for how far in the future it can be scheduled.

  • If a scheduler is provided that returns a timestamp other than an epoch from now(), and a Date object is passed to the dueTime argument, the calculation for when the first emission should occur will be incorrect. In this case, it would be best to do your own calculations ahead of time, and pass a number in as the dueTime.

timer(startDue: number | Date, intervalDuration: number, scheduler?: SchedulerLike): Observable<number>

Creates an observable that starts an interval after a specified delay, emitting incrementing numbers -- starting at 0 -- on each interval after words.

Parameters

startDue

If a number, is the time to wait before starting the interval. If a Date, is the exact time at which to start the interval.

intervalDuration

The delay between each value emitted in the interval. Passing a negative number here will result in immediate completion after the first value is emitted, as though no intervalDuration was passed at all.

scheduler

Optional. Default is undefined.

The scheduler to use to schedule the delay. Defaults to asyncScheduler.

Returns

Observable<number>

The delay and intervalDuration are specified by default in milliseconds, however providing a custom scheduler could create a different behavior.

Example

Start an interval that starts right away

Since interval waits for the passed delay before starting, sometimes that's not ideal. You may want to start an interval immediately. timer works well for this. Here we have both side-by-side so you can see them in comparison.

Note that this observable will never complete.

import { timer, interval } from 'rxjs';

timer(0, 1000).subscribe(n => console.log('timer', n));
interval(1000).subscribe(n => console.log('interval', n));

Known Limitations

  • The asyncScheduler uses setTimeout which has limitations for how far in the future it can be scheduled.

  • If a scheduler is provided that returns a timestamp other than an epoch from now(), and a Date object is passed to the dueTime argument, the calculation for when the first emission should occur will be incorrect. In this case, it would be best to do your own calculations ahead of time, and pass a number in as the startDue.

timer(dueTime: number | Date, unused: undefined, scheduler?: SchedulerLike): Observable<0>

Deprecation Notes

The signature allowing undefined to be passed for intervalDuration will be removed in v8. Use the timer(dueTime, scheduler?) signature instead.

Parameters

dueTime

Type: number | Date.

unused

Type: undefined.

scheduler

Optional. Default is undefined.

Type: SchedulerLike.

Returns

Observable<0>

© 2015–2021 Google, Inc., Netflix, Inc., Microsoft Corp. and contributors.
Code licensed under an Apache-2.0 License. Documentation licensed under CC BY 4.0.
https://rxjs.dev/api/index/function/timer