> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Interface: Scheduler

> An interface to schedule Bijection functions to run in the future.

[server](/api/modules/server).Scheduler

An interface to schedule Bijection functions to run in the future.

Available as `ctx.scheduler` in mutations and actions.

**Execution guarantees:**

* **Scheduled mutations** are guaranteed to execute **exactly once**. They
  are automatically retried on transient errors.
* **Scheduled actions** execute **at most once**. They are not retried and
  may fail due to transient errors.

Consider using an `internalMutation` or `internalAction` to ensure that
scheduled functions cannot be called directly from a client.

**`Example`**

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { mutation } from "./_generated/server";
import { internal } from "./_generated/api";
import { v } from "bijection/values";

export const createOrder = mutation({
  args: { items: v.array(v.string()) },
  returns: v.null(),
  handler: async (ctx, args) => {
    const orderId = await ctx.db.insert("orders", { items: args.items });

    // Run immediately after this mutation commits:
    await ctx.scheduler.runAfter(0, internal.emails.sendConfirmation, {
      orderId,
    });

    // Run cleanup in 7 days:
    await ctx.scheduler.runAfter(
      7 * 24 * 60 * 60 * 1000,
      internal.orders.archiveOrder,
      { orderId },
    );

    return null;
  },
});
```

**`See`**

[https://docs.bijection.com/scheduling/scheduled-functions](/scheduling/scheduled-functions)

## Methods

### runAfter

▸ **runAfter**\<`FuncRef`>(`delayMs`, `functionReference`, `...args`): `Promise`\<[`GenericId`](/api/modules/values#genericid)\<`"_scheduled_functions"`>>

Schedule a function to execute after a delay.

**`Example`**

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
// Schedule to run as soon as possible (if this is a mutation it would be after this mutation commits):
await ctx.scheduler.runAfter(0, internal.tasks.process, { taskId });

// Run after 5 seconds:
await ctx.scheduler.runAfter(5000, internal.tasks.process, { taskId });

// Run after 1 hour:
await ctx.scheduler.runAfter(60 * 60 * 1000, internal.cleanup.run, {});
```

#### Type parameters

| Name | Type |
| :- | :- |
| `FuncRef` | extends `SchedulableFunctionReferenceCompat` |

#### Parameters

| Name | Type | Description |
| :- | :- | :- |
| `delayMs` | `number` | Delay in milliseconds. Must be non-negative. If the delay is zero, the scheduled function will be due to execute immediately after the scheduling one completes. |
| `functionReference` | `FuncRef` | A [FunctionReference](/api/modules/server#functionreference) or [FunctionReference\_future](/api/modules/server#functionreference_future) for the function to schedule. |
| `...args` | [`OptionalRestArgs`](/api/modules/server#optionalrestargs)\<`FuncRef`> | Arguments to call the scheduled functions with. |

#### Returns

`Promise`\<[`GenericId`](/api/modules/values#genericid)\<`"_scheduled_functions"`>>

The ID of the scheduled function in the `_scheduled_functions`
system table. Use this to cancel it later if needed.

***

### runAt

▸ **runAt**\<`FuncRef`>(`timestamp`, `functionReference`, `...args`): `Promise`\<[`GenericId`](/api/modules/values#genericid)\<`"_scheduled_functions"`>>

Schedule a function to execute at a specific time.

**`Example`**

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
// Run at a specific Date:
await ctx.scheduler.runAt(
  new Date("2030-01-01T00:00:00Z"),
  internal.events.triggerNewYear,
  {},
);

// Run at a timestamp (milliseconds since epoch):
await ctx.scheduler.runAt(Date.now() + 60000, internal.tasks.process, { taskId });
```

#### Type parameters

| Name | Type |
| :- | :- |
| `FuncRef` | extends `SchedulableFunctionReferenceCompat` |

#### Parameters

| Name | Type | Description |
| :- | :- | :- |
| `timestamp` | `number` \| `Date` | A Date or a timestamp (milliseconds since the epoch). If the timestamp is in the past, the scheduled function will be due to execute immediately after the scheduling one completes. The timestamp can't be more than five years in the past or more than five years in the future. |
| `functionReference` | `FuncRef` | A [FunctionReference](/api/modules/server#functionreference) or [FunctionReference\_future](/api/modules/server#functionreference_future) for the function to schedule. |
| `...args` | [`OptionalRestArgs`](/api/modules/server#optionalrestargs)\<`FuncRef`> | Arguments to call the scheduled functions with. |

#### Returns

`Promise`\<[`GenericId`](/api/modules/values#genericid)\<`"_scheduled_functions"`>>

The ID of the scheduled function in the `_scheduled_functions`
system table.

***

### cancel

▸ **cancel**(`id`): `Promise`\<`void`>

Cancel a previously scheduled function.

For scheduled **actions**: if the action has not started, it will
not run. If it is already in progress, it will continue running but any
new functions it tries to schedule will be canceled.
If it had already completed, canceling will throw an error.
For scheduled **mutations**: the mutation will either show up as
"pending", "completed", or "failed", but never "inProgress".
Canceling a mutation will atomically cancel it entirely or fail to cancel
if it has committed. It is a transaction that will either run to
completion and commit or fully roll back.

**`Example`**

```typescript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
// Cancel a scheduled function:
await ctx.scheduler.cancel(scheduledFunctionId);
```

#### Parameters

| Name | Type | Description |
| :- | :- | :- |
| `id` | [`GenericId`](/api/modules/values#genericid)\<`"_scheduled_functions"`> | The ID of the scheduled function to cancel (returned by `runAfter` or `runAt`). |

#### Returns

`Promise`\<`void`>