TinyTick logoTinyTick

useScheduleTaskRun

The useScheduleTaskRun hook can be used to schedule a specific task in the Manager provided by a Provider component.

useScheduleTaskRun(
  taskId: string,
  arg?: string,
  startAfter?: number,
  config?: TaskRunConfig,
  configDeps?: DependencyList,
): Id | undefined
TypeDescription
taskIdstring

The Id of the task to run.

arg?string

An optional string argument to pass to the Task.

startAfter?number

A timestamp at, or duration after which, the task should run.

config?TaskRunConfig

An optional TaskRunConfig to set for this run.

configDeps?DependencyList

An optional array of dependencies for the config object, which, if any change, result in the task being scheduled again. Defaults to an empty array.

returnsId | undefined

The new unique Id of the scheduled task run, or undefined if unsuccessful.

When called, the task will be executed with the optional string argument provided, and can be configured to start at a specific time (TimestampMs), or after a specific delay (DurationMs).

You can also provide a custom TaskRunConfig which lets you indicate the duration of the task run and its retry behaviors, for example.

The hook will return a unique Id for the scheduled task run. However, if the Manager is in the stopping state, new task runs can not be scheduled, and in that case, the method will return undefined.

The task run will be scheduled once when the component is first rendered, and will be only scheduled again if any of the arguments or configDeps dependencies change. If they do, any previously scheduled task run will be deleted.

Example

This example shows how to use the useScheduleTaskRun hook within a component that's nested inside a Provider. The hook is used to create a callback that will schedule a task in response to a click event.

import React from 'react';
import {createRoot} from 'react-dom/client';
import {createManager} from 'tinytick';
import {Provider, useScheduleTaskRun} from 'tinytick/ui-react';

const Pane = () => {
  useScheduleTaskRun('log');
  return null;
};
const App = ({manager}) => (
  <Provider manager={manager}>
    <Pane />
  </Provider>
);

const manager = createManager().start();
manager.setTask('log', async () => console.log('Task ran'));

const app = document.createElement('div');
const root = createRoot(app);
root.render(<App manager={manager} />);

// ... wait 100ms for task to start running
// -> 'Task ran'

Since

v1.2.1

When called with an object as the first argument, the useScheduleTaskRun hook destructures it to make it easier to skip optional parameters.

useScheduleTaskRun(
  args: {
    taskId: string;
    arg?: string;
    startAfter?: number;
    config?: TaskRunConfig;
  },
  configDeps?: DependencyList,
): Id | undefined
TypeDescription
args{ taskId: string; arg?: string; startAfter?: number; config?: TaskRunConfig; }

An object containing the Id of the task to run, an optional string argument to pass to the Task, an optional timestamp at, or duration after which, the task should run; and an optional TaskRunConfig to set for this run.

configDeps?DependencyList

An optional array of dependencies for the config object, which, if any change, result in the task being scheduled again. Defaults to an empty array.

returnsId | undefined

The new unique Id of the scheduled task run, or undefined if unsuccessful.

Example

This example shows how to use the useScheduleTaskRun hook within a component that's nested inside a Provider. The hook is used to create a callback that will schedule a task in response to a click event.

import React from 'react';
import {createRoot} from 'react-dom/client';
import {createManager} from 'tinytick';
import {Provider, useScheduleTaskRun} from 'tinytick/ui-react';

const Pane = () => {
  useScheduleTaskRun({taskId: 'log'});
  return null;
};
const App = ({manager}) => (
  <Provider manager={manager}>
    <Pane />
  </Provider>
);

const manager = createManager().start();
manager.setTask('log', async () => console.log('Task ran'));

const app = document.createElement('div');
const root = createRoot(app);
root.render(<App manager={manager} />);

// ... wait 100ms for task to start running
// -> 'Task ran'

Since

v1.2.5