---
title: source
description: "Declare a Source: where a `pool()` gets its work items, one at a time."
---

# `source`

Function, in `@jr2/orchestrator/src/pool.ts`. It is an export of `@jr2/orchestrator`, on the [Authoring surface](../authoring-surface.md) page, in Composition.

```ts
function source<T>(spec: SourceSpec<T>): SourceSpec<T>
```

Declare a Source: where a `pool()` gets its work items, one at a time. It gives back the spec
that you pass. The item type `T` types what `next` gives. `pool()` does not carry `T` to
`itemId` and `itemInput`, so write the item type on their parameter, as the `pool()` example does.

**Parameters**

- `spec`: How to claim the next item, and when to look again. See [`SourceSpec`](type-sourcespec.md).

**Returns**: The same spec.

**Example**

```ts
import { fromPromise } from "xstate";
import { source } from "@jr2/orchestrator";

type Issue = { id: string; title: string };

const backlog: Issue[] = [
  { id: "ISSUE-1", title: "Fix the greeting." },
  { id: "ISSUE-2", title: "Add a --name flag." },
];

export const issues = source<Issue>({
  next: fromPromise(async ({ input }: { input: { active: string[] } }) => {
    const issue = backlog.find((i) => !input.active.includes(i.id)) ?? null;
    if (issue) backlog.splice(backlog.indexOf(issue), 1);
    return issue;
  }),
  pollEvery: 60_000,
});
```

**See also**

- [Run one worker per item](../../guides/run-one-worker-per-item.md)
- [Pools and Sources](../../concepts/pools-and-sources.md)
- [ADR-0017: The run loop is a jr2 `pool` over a generalized source port](../decisions/0017-pool-over-a-source-port.md)