---
title: PoolSpec
description: "What you pass to `pool()`: where the items come from, how many workers run at once, and what each worker gets."
---

# `PoolSpec`

Type, in `@jr2/orchestrator/src/pool.ts`. The signature of an export, or a type that it names, names this type. The [Authoring surface](../authoring-surface.md) page lists each export. This type is not an export of `@jr2/orchestrator`, so a workflow module does not import it by name.

```ts
type PoolSpec<T, TInput = unknown> = {
  id?: string;
  input?: z.ZodObject;
  source: SourceSpec<T>;
  itemId: (item: T) => string;
  cap?: number | ((args: { input: TInput }) => number);
  itemInput?: (item: T, args: { input: TInput }) => unknown;
  onDrained?: "final";
  failures?: "fail" | "report";
};
```

What you pass to `pool()`: where the items come from, how many workers run at once, and what
each worker gets.

**Fields**

- `id` (optional): `string`

  The Machine id: the name of the Pool in the Console. Default: `"pool"`.
- `input` (optional): `z.ZodObject`

  The run input of the Pool, as a zod object: what a caller sends to start a run. `cap` and
  `itemInput` read it, typed by it. A worker never gets it: each worker gets its item. Default:
  none, and then their `input` is `unknown`.
- `source`: `SourceSpec<T>`

  Where the items come from. Make it with [`source`](source.md).
- `itemId`: `(item: T) => string`

  The id of an item. The Pool uses it as the id of the item's worker and in the `active` list
  that `next` gets. It is also the key of that worker's output in `items`. Give each item an id
  of its own, and the same id every time.
- `cap` (optional): `number | ((args: { input: TInput; }) => number)`

  The most workers that run at once: a number, or a function of the run input. Default: `1`.
- `itemInput` (optional): `(item: T, args: { input: TInput; }) => unknown`

  Make a worker's input from its item and the run input. Default: the item itself.
- `onDrained` (optional): `"final"`

  What the Pool does when the Source has no more items and every worker has settled. Only
  `"final"`: the run ends. Default: `"final"`.
- `failures` (optional): `"fail" | "report"`

  What the Pool does at the end when one or more workers failed. The Pool catches each worker's
  Failure either way, so one failed item does not stop the other workers. `"fail"`: when the Pool
  ends with failures, `drained` or `deadlocked`, it fails the run with the reason
  `"<n> of <m> items failed"` and the detail `{ status, items, failures }`. `"report"`: the Pool
  ends `done`, with the failures in its output. Default: `"fail"`.