Play Authoring And In-Play Runtime

`deepline`

import deepline from 'deepline' — the play runtime. A play is a .play.ts file that default-exports an async function of its input. The file name is the play name. The parameter’s type is the input contract and the returned object is the result. Every runtime call below is deepline.<name>, including inside dataset resolvers and step bodies.

import deepline from 'deepline';

export default async function (input: { domain: string }) {
  const company = await deepline.tools.execute({
    id: 'company',
    tool: 'company_lookup',
    input: { domain: input.domain },
    description: 'Look up the company.',
    staleAfterSeconds: 0,
  });
  return { company };
}

deepline run lookup.play.ts --input '{"domain":"stripe.com"}'
deepline run -e 'deepline.log("hello"); return { ok: true };'

Compose with import child from './child.play' and await deepline.runPlay('key', child, input, { description }), or by name. deepline works only in the play file. pass it to helper modules as an argument typed DeeplinePlayRuntimeContext. The file exports only the play function and, optionally, its config.
Signature:

export type ScriptPlayContext = DeeplinePlayRuntimeContext & { config(config: PlayBindings & { name?: string }): void; input<TInput = Record<string, unknown>>(): TInput; output(result: PlayReturnObject): void; };

`export const config`

Optional Play configuration, declared once at the top of the play file as an object literal: export const config = { ... };. Settings: name (defaults to the file name), description, displayName, cron, webhook, sqlListeners, runtime, billing, compatibility. It is read without running the play, so its values must be literals. A play can be triggered three ways:

webhook — an inbound HTTP call (with optional legacy HMAC or Standard Webhooks signature verification).
cron — a schedule.
sqlListeners — a monitor: the play runs whenever a monitor writes a new row to its output stream. This is how you build a play “on top of” a monitor (e.g. run enrichment every time a watched company posts a new job). Each listener binds to a monitor tool id + one of its output stream keys (see deepline describe <id> for a tool’s streams and row columns). The changed row is delivered as the listener event’s after in the play function’s input.

The default Play runtime is 30 minutes with the standard 1 GiB / 1 CPU profile. Set runtime.size to standard or 1gb (1 GiB / 1 CPU), large or 4gb (4 GiB / 2 CPU), or xlarge or 8gb (8 GiB / 4 CPU). Each alias selects the same resource profile and compute price.

export const config = { runtime: { size: '4gb' } };

Compute pricing follows the workspace plan. Use deepline billing quote for the session ceiling. Set runtime.timeout for longer bounded runs. duration values are whole minutes or hours, up to 4h. It differs from deepline.tools.execute({ timeoutMs }), which limits one provider call.
Signature: export type PlayBindings<TInput = Record<string, unknown>> = PlayAuthoringBindings<TInput>;

`deepline.csv(path, options)`

Load a staged CSV file as a durable dataset handle. Signature: csv<T = Record<string, unknown>>( path: string | CsvInput<T & object>, options?: CsvOptions, ): Promise<PlayDataset<T>>;

Parameters

Name	Type	Required	Description
`path`	`string \| CsvInput<T & object>`	Yes
`options`	`CsvOptions`	No

Returns: Promise<PlayDataset<T>> — see PlayDataset

`CsvOptions`

Options for loading a staged CSV with deepline.csv(...).
Signature: export type CsvOptions = CsvOptions;

`deepline.dataset(key, items)`

Create a persisted row dataset and define durable output columns. Signature:

dataset<TSource extends PlayDatasetInput<object>>( key: string, items: TSource, ): DatasetBuilder< PlayDatasetRow<TSource> & object, PlayDatasetRow<TSource> & object, DeeplinePlayRuntimeContext >;

Parameters

Name	Type	Required	Description
`key`	`string`	Yes
`items`	`TSource`	Yes

Returns: DatasetBuilder< PlayDatasetRow<TSource> & object, PlayDatasetRow<TSource> & object, DeeplinePlayRuntimeContext >

`.dataset(...).withColumn(name, resolver).run(options)`

Define one output column for every row in this dataset.

withColumn<Name extends string, Value>( name: Name, resolver: ColumnResolver<OutputRow, Value>, ): DatasetBuilder< InputRow, OutputRow & Record<Name, Value> >;

withColumn<Name extends string, Value>( name: Name, definition: DatasetColumnDefinition< OutputRow, Value > & { readonly runIf: ( row: OutputRow, index: number, ) => boolean | Promise<boolean>; }, ): DatasetBuilder< InputRow, OutputRow & Record<Name, Value | null> >;

withColumn<Name extends string, Value>( name: Name, definition: DatasetColumnDefinition< OutputRow, Value >, ): DatasetBuilder< InputRow, OutputRow & Record<Name, Value> >;

withColumn<Name extends string, Value>( name: Name, resolver: StepResolver<OutputRow, Value> | RunnableStepProgram<unknown, Value>, options: StepOptions<OutputRow, Value>, ): DatasetBuilder< InputRow, OutputRow & Record<Name, Value | null> >;

run( options?: DatasetRunOptions<InputRow>, ): Promise<PlayDataset<OutputRow>>;

Column Overload 1 Parameters

Name	Type	Required	Description
`name`	`Name`	Yes
`resolver`	`ColumnResolver<OutputRow, Value>`	Yes

Column Overload 1 Returns: DatasetBuilder< InputRow, OutputRow & Record<Name, Value> >

Column Overload 2 Parameters

Name	Type	Required	Description
`name`	`Name`	Yes
`definition`	`DatasetColumnDefinition< OutputRow, Value > & { readonly runIf: ( row: OutputRow, index: number, ) => boolean \| Promise<boolean>; }`	Yes

Column Overload 2 Returns: DatasetBuilder< InputRow, OutputRow & Record<Name, Value | null> >

Column Overload 3 Parameters

Name	Type	Required	Description
`name`	`Name`	Yes
`definition`	`DatasetColumnDefinition< OutputRow, Value >`	Yes

Column Overload 3 Returns: DatasetBuilder< InputRow, OutputRow & Record<Name, Value> >

Column Overload 4 Parameters

Name	Type	Required
`name`	`Name`	Yes
`resolver`	`\| StepResolver<OutputRow, Value> \| RunnableStepProgram<unknown, Value>`	Yes
`options`	`StepOptions<OutputRow, Value>`	Yes

Column Overload 4 Returns: DatasetBuilder< InputRow, OutputRow & Record<Name, Value | null> >

Run Parameters

Name	Type	Required	Description
`options`	`DatasetRunOptions<InputRow>`	No

Run Returns: Promise<PlayDataset<OutputRow>> — see PlayDataset Execute the row-column program and return a durable dataset handle. upsert preserves row-by-row enrichment. net_new admits and returns only unseen stable keys. isolate records failed rows while siblings continue. fail opts into fail-fast behavior.

`DatasetColumnRunInput`

Input object passed to an object-column run resolver.

Name	Type	Required	Description
`row`	`Row`	Yes	Current row, including previously computed columns.
`ctx`	`DeeplinePlayRuntimeContext`	Yes	The play runtime, the same object as `deepline`.
`index`	`number`	Yes	Zero-based row index for this dataset run.
`previousCell`	`PreviousCell<Value>`	No	Prior stored cell value and freshness metadata when this cell reruns.

`DatasetColumnDefinition`

Object-column form for .withColumn(...). Use this when a column needs runIf or typed previousCell.

Name	Type	Required	Description
`run`	`( input: DatasetColumnRunInput<Row, Value>, ) => Value \| Promise<Value>`	Yes	Compute one cell value. Receives the previous stored value when rerunning.
`runIf`	`(row: Row, index: number) => boolean \| Promise<boolean>`	No	Optional row-level gate. Skipped rows produce `null` for this column.

`StepOptions`

Options for row-level .withColumn(...) and steps().step(...) entries.

Name	Type	Required	Description
`runIf`	`(row: Row, index: number) => boolean \| Promise<boolean>`	No	Optional row-level gate. Skipped rows produce `null` for this column.
`recompute`	`boolean`	No	Legacy dataset-column flag. Prefer freshness on the reusable call.
`recomputeOnError`	`boolean`	No	Legacy error-recompute flag accepted for older authored Plays.
`staleAfterSeconds`	`number \| null`	No	Legacy cell staleness metadata accepted for older authored Plays.

`PreviousCell`

Previous durable cell value passed to object-column resolvers. The runtime supplies this when a row+column is being recomputed after a previous value existed. value has the same type that the column returns. freshness metadata lives beside it.

Name	Type	Required	Description
`value`	`Value`	Yes	Previous completed value for this row+column.
`completedAt`	`number`	No	Millisecond timestamp when the previous value completed.
`staleAt`	`number \| null`	No	Millisecond timestamp when the previous value becomes stale. `null` means no expiry.
`staleAfterSeconds`	`number`	No	Resolved numeric TTL in seconds for the previous value, when present.

`deepline.step(id, fn)`

Create one scalar durable checkpoint. Signature: step<T>( id: string, run: () => T | Promise<T>, options?: RuntimeStepOptions, ): Promise<T>;

Parameters

Name	Type	Required
`id`	`string`	Yes
`run`	`() => T \| Promise<T>`	Yes
`options`	`RuntimeStepOptions`	No

Returns: Promise<T>

`deepline.runPlay(key, playRef, input, options)`

Compose another Play inline under a stable call key. Signature:

runPlay<TOutput = unknown>( key: string, playRef: string | PlayReferenceLike, input: Record<string, unknown>, options: PlayCallOptions, ): Promise<TOutput>;

Parameters

Name	Type	Required
`key`	`string`	Yes
`playRef`	`string \| PlayReferenceLike`	Yes
`input`	`Record<string, unknown>`	Yes
`options`	`PlayCallOptions`	Yes

Returns: Promise<TOutput>

`deepline.runPlayAsync(key, playRef, input, options)`

Admit an independent scalar Play Run and return its durable identity after scheduler admission, before child completion. Signature:

runPlayAsync<TInput extends Record<string, unknown>>( key: string, playRef: PlayReferenceLike<TInput>, input: NoInfer<TInput>, options: PlayAuthoringAsyncCallOptions, ): Promise<AsyncPlayRunRef>;

Parameters

Name	Type	Required
`key`	`string`	Yes
`playRef`	`PlayReferenceLike<TInput>`	Yes
`input`	`NoInfer<TInput>`	Yes
`options`	`PlayAuthoringAsyncCallOptions`	Yes

Returns: Promise<AsyncPlayRunRef> — see AsyncPlayRunRef

`AsyncPlayRunRef`

Serializable reference returned after an async child Run is durable.
Signature:

export type AsyncPlayRunRef = Readonly<{ runId: PlayRunId; rateLimited?: { latestRunId: string; nextAllowedAt: string; message: string }; }>;

`deepline.tools.execute(request)`

Execute a provider tool through the terminal-result cache contract. Signature: execute<TOutput = PlayLooseObject>( request: PlayToolExecutionRequest, ): Promise< ToolExecuteResult<TOutput> >;

Parameters

Name	Type	Required	Description
`request`	`PlayToolExecutionRequest`	Yes

Returns: Promise< ToolExecuteResult<TOutput> > — see ToolExecuteResult

`ToolExecutionRequest`

Keyword-style request object for deepline.tools.execute(...). The tool value comes from live tool discovery. The id is the stable logical call name used for logs, metadata, and result-cache identity. Provider result reuse is keyed by play, tool, semantic input, auth scope, provider action version, and cache policy.
Signature: export type ToolExecutionRequest = PlayToolExecutionRequest;

`deepline.fetch(key, url, init)`

Execute a guarded HTTP request. Edition 11 requires an explicit freshness choice. Only GET, HEAD, and OPTIONS can retain completed responses. Mutating methods must use staleAfterSeconds: 0. The choice governs only the completed call receipt, never dataset/request identity. Failed requests do not publish completed cache entries. A headers timeout leaves an upstream write’s outcome unknown and does not establish whether its body was sent. The transport does not automatically retry that timed-out write, but a later invocation can execute it again. Mutating requests require provider-supported idempotency with the same key retained across retries and replay. Deadlines are platform-controlled. callers may cancel through init.signal. Pass { transient: true } only on GET, HEAD, and OPTIONS when the response must not be retained in a receipt or checkpoint. edition 11 rejects transient writes. Edition 5+ throws CtxFetchHttpError for non-2xx. catch it only when the Play intentionally recovers, otherwise let it fail the Play. Editions 1–4 retain their previous response projections. Signature:

fetch( key: string, url: string | URL, init?: SecretAwareRequestInit, options?: FetchOptions, ): Promise<PlayFetchResponse>;

Parameters

Name	Type	Required
`key`	`string`	Yes
`url`	`string \| URL`	Yes
`init`	`SecretAwareRequestInit`	No
`options`	`FetchOptions`	No

Returns: Promise<PlayFetchResponse> — see PlayFetchResponse

`deepline.secrets.get(name)`

Read an allowed workspace secret inside the running Play. do not log or return it. Declare uppercase names in top-level secrets. Signature: get(name: string): PlaySecretPromise;

Parameters

Name	Type	Required	Description
`name`	`string`	Yes

Returns: PlaySecretPromise

`deepline.secrets.bearer(secret)`

Send a credential as Authorization: Bearer <value>. Await get first. its direct promise remains accepted for source compatibility, while other promises are rejected. Signature: bearer( secret: string | PlaySecretPromise | SecretHandle, ): SecretAuth;

Parameters

Name	Type	Required	Description
`secret`	`string \| PlaySecretPromise \| SecretHandle`	Yes

Returns: SecretAuth — see SecretAuth

`deepline.secrets.header(header, secret)`

Send a credential as a named header, for APIs that do not use bearer tokens — x-api-key, apikey, private-token, and similar. Signature: header( header: string, secret: string | PlaySecretPromise | SecretHandle, ): SecretAuth;

Parameters

Name	Type	Required	Description
`header`	`string`	Yes
`secret`	`string \| PlaySecretPromise \| SecretHandle`	Yes

Returns: SecretAuth — see SecretAuth

`SecretAwareRequestInit`

The init accepted by deepline.fetch. Same shape as RequestInit plus auth.

Name	Type	Required	Description
`headers`	`HeadersInit`	No	Ordinary request headers, recorded in the durable receipt with any resolved Play secret value redacted. Prefer `auth` for credentials: it enforces HTTPS and keeps the auth header out of the receipt.
`auth`	`SecretAuthInput`	No	One or more credentialed headers for this request. Pass a single `deepline.secrets` auth for the common case, or an array when an API requires multiple credentialed headers. Auth-helper requests require HTTPS and omit the credential from the durable receipt. Each auth entry must target a distinct header.

`PlayFetchResponse`

A durable response record, not a WHATWG Response: read the already-materialized bodyText and json properties. do not call .json(), .text(), or .body.

Name	Type	Required	Description
`freshness` `ok`	`import('./tool-result-types').CallFreshnessMetadata` `boolean`	No Yes	Freshness and same-run recovery metadata for edition 11 calls. True when the response status is in the 2xx range.
`status`	`number`	Yes	HTTP status code as returned by the upstream server.
`statusText`	`string`	Yes	HTTP status text as returned by the upstream server.
`url`	`string`	Yes	Final response URL after any redirects.
`headers`	`Record<string, string>`	Yes	Response headers, lowercased, with any known secret values redacted.
`bodyText`	`string`	Yes	Full response body as text, with any known secret values redacted.
`json`	`unknown \| null`	Yes	The runtime parses the body at request time. Read the property with `const body = res.json`. Do not call `await res.json()`. The value is null when the body is empty or is not valid JSON. Malformed JSON produces null instead of an error. Check `res.ok`. Check `res.bodyText` before you interpret null as an empty response.

`SecretHandle`

An opaque reference to a workspace secret used by legacy authoring-contract editions. New Plays receive plaintext strings from deepline.secrets.get.

Name	Type	Required	Description
`name`	`string`	Yes	Name of the workspace secret, uppercased. Never its value.

`SecretAuth`

One resolved authentication scheme, built by deepline.secrets.bearer or deepline.secrets.header and attached to a request through init.auth.

Name	Type	Required	Description
`kind`	`'bearer' \| 'header'`	Yes	`bearer` sends `Authorization: Bearer <value>`. `header` sends a named header.
`secret`	`string \| PlaySecretPromise \| PlaySecretValue`	Yes	The value whose bytes the runtime attaches.
`header`	`string`	No	Header name, set only when `kind` is `header`.

`CtxFetchHttpError`

Edition 5+ deepline.fetch error for a non-2xx response. Its full readable body is secret-redacted. editions 1–4 retain PlayFetchResponse { ok: false }. Signature: class CtxFetchHttpError extends Error

Members

Member	Kind	Purpose	Parameters	Returns / type
`constructor`	constructor	Build the error from the durable response record.	`response: PlayAuthoringFetchResponse`
`code`	property	Stable machine-readable HTTP-failure code.		`"CTX_FETCH_HTTP_ERROR"`
`status`	property	Upstream HTTP status.		`number`
`statusText`	property	Upstream HTTP status text.		`string`
`url`	property	Final response URL after redirects.		`string`
`headers`	property	Secret-redacted response headers.		`Record<string, string>`
`bodyText`	property	Complete secret-redacted response body.		`string`
`json`	property	Eagerly parsed secret-redacted JSON, or null.		`unknown \| null`

`deepline.billing.entitlements()`

Read current workspace plan benefits. Execution rechecks admission. this read is fresh and is not a durable receipt. Signature: entitlements(): Promise<BillingEntitlements>; Returns: Promise<BillingEntitlements>

`deepline.runSteps(program, input, options)`

Execute one reusable step program against a scalar input. Signature:

runSteps<TInput extends Record<string, unknown>, TOutput>( program: PlayAuthoringRunnableStepProgram< TOutput, DeeplinePlayRuntimeContext > & { readonly __inputType?: (input: TInput) => void }, input: TInput, options?: PlayAuthoringRunStepsOptions, ): Promise<TOutput>;

Parameters

Name	Type	Required
`program`	`PlayAuthoringRunnableStepProgram< TOutput, DeeplinePlayRuntimeContext > & { readonly __inputType?: (input: TInput) => void }`	Yes
`input`	`TInput`	Yes
`options`	`PlayAuthoringRunStepsOptions`	No

Returns: Promise<TOutput>

`deepline.pages.write(name, options)`

Replace a named page in this workspace and return its URL. Signature: write( name: string, options: PlayAuthoringPageWriteOptions, ): Promise<PlayAuthoringPageWriteResult>;

Parameters

Name	Type	Required	Description
`name`	`string`	Yes
`options`	`PlayAuthoringPageWriteOptions`	Yes

Returns: Promise<PlayAuthoringPageWriteResult>

`PlayDataset`

Durable handle for rows produced by deepline.csv(...) or deepline.dataset(...).run(). A PlayDataset is not a normal in-memory array. It points at runtime-managed rows, usually backed by persisted sheet storage, and carries metadata such as dataset kind, dataset id, table namespace, count, and preview rows. Pass dataset handles directly into later deepline.dataset(...) stages by default so Deepline keeps row progress, retries, memory use, and table output under runtime control. Use count() and peek() for bounded inspection. Use materialize(limit) or async iteration only when the dataset is intentionally small and bounded. PlayDataset intentionally does not expose .rows, .toArray(), .length, numeric indexing, spread, or synchronous iteration. these hide loading costs or make behavior depend on row residency.

Name	Type	Required	Description
`datasetKind`	`PlayDatasetKind`	Yes	Dataset kind.
`datasetId`	`string`	Yes	Dataset id.
`backing`	`PlayDatasetBacking`	No	Backing store info.
`sourceLabel`	`string \| null`	No	Display label.
`tableNamespace`	`string \| null`	No	Runtime table name.
`columnTypes`	`PlayDatasetColumnTypes`	No	Advisory source types. transformed fields must infer from their values.

`ToolExecuteResult`

Canonical result returned by Deepline tool execution. Known values: fields.person.email.value, fields.email.value, and a declared list at fields.<list>.value. or field('person.email.value'). A value whose meaning is not known is absent: read it from response, the complete provider response (also toolResponse.rawV2). Metadata: toolResponse.meta. The older getters extractedValues.<name>.get() and extractedLists.<name>.get() return the same values and keep working. One record per list item: rows(), each with fields, field() and response. .value is the one value or null, and throws when there are several rather than miss data. .values is always an array. Edition 10 and later Plays receive ordinary arrays from list .get() synchronously. persist explicitly with deepline.dataset. Lazy or incomplete lists throw: use readList(result, path) for explicit dataset access. Provider pagination requires a separate request. getters never fetch it. Historical editions 1–9 retain PlayDataset getters and async materialize/peek. missing getters never mean empty results. Inspect toolResponse.rawV2 for debugging: parsed, scrubbed envelopes, pagination and siblings, not HTTP bytes or headers.
Signature:

export type ToolExecuteResult< TResult = unknown, TMeta = Record<string, unknown>, TExtracted extends Record<string, unknown> = Partial<DeeplineGetterValueMap>, TLists extends Record<string, Record<string, unknown>> = Record< string, Record<string, unknown> >, > = ToolExecuteResultBase<TResult, TMeta> & ToolExecuteResultAccessors<TExtracted, TLists>;

​deepline

​export const config

​deepline.csv(path, options)

​Parameters

​CsvOptions

​deepline.dataset(key, items)

​Parameters

​.dataset(...).withColumn(name, resolver).run(options)

​Column Overload 1 Parameters

​Column Overload 2 Parameters

​Column Overload 3 Parameters

​Column Overload 4 Parameters

​Run Parameters

​DatasetColumnRunInput

​DatasetColumnDefinition

​StepOptions

​PreviousCell

​deepline.step(id, fn)

​Parameters

​deepline.runPlay(key, playRef, input, options)

​Parameters

​deepline.runPlayAsync(key, playRef, input, options)

​Parameters

​AsyncPlayRunRef

​deepline.tools.execute(request)

​Parameters

​ToolExecutionRequest

​deepline.fetch(key, url, init)

​Parameters

​deepline.secrets.get(name)

​Parameters

​deepline.secrets.bearer(secret)

​Parameters

​deepline.secrets.header(header, secret)

​Parameters

​SecretAwareRequestInit

​PlayFetchResponse

​SecretHandle

​SecretAuth

​CtxFetchHttpError

​Members

​deepline.billing.entitlements()

​deepline.runSteps(program, input, options)

​Parameters

​deepline.pages.write(name, options)

​Parameters

​PlayDataset

​ToolExecuteResult

`deepline`

`export const config`

`deepline.csv(path, options)`

Parameters

`CsvOptions`

`deepline.dataset(key, items)`

Parameters

`.dataset(...).withColumn(name, resolver).run(options)`

Column Overload 1 Parameters

Column Overload 2 Parameters

Column Overload 3 Parameters

Column Overload 4 Parameters

Run Parameters

`DatasetColumnRunInput`

`DatasetColumnDefinition`

`StepOptions`

`PreviousCell`

`deepline.step(id, fn)`

Parameters

`deepline.runPlay(key, playRef, input, options)`

Parameters

`deepline.runPlayAsync(key, playRef, input, options)`

Parameters

`AsyncPlayRunRef`

`deepline.tools.execute(request)`

Parameters

`ToolExecutionRequest`

`deepline.fetch(key, url, init)`

Parameters

`deepline.secrets.get(name)`

Parameters

`deepline.secrets.bearer(secret)`

Parameters

`deepline.secrets.header(header, secret)`

Parameters

`SecretAwareRequestInit`

`PlayFetchResponse`

`SecretHandle`

`SecretAuth`

`CtxFetchHttpError`

Members

`deepline.billing.entitlements()`

`deepline.runSteps(program, input, options)`

Parameters

`deepline.pages.write(name, options)`

Parameters

`PlayDataset`

`ToolExecuteResult`