Typing / CLI

Both the TypeScript and Python SDKs ship with a CLI that generates type definitions for your services. Types are derived from the schemas you defined in the Requence UI — input, configuration, and outputs — and kept in sync automatically.

Generating Types

TypeScript

npx requence-service generate-types

This creates a requence-env.d.ts file in your project root. TypeScript picks it up automatically — no import needed. Your ctx.input, ctx.configuration, and ctx.toOutput() calls will be fully typed.

Python

requence-service generate-types

This creates type stubs in a typings/requence/service/ directory. Pylance and pyright read a top-level typings/ directory automatically, so no configuration is needed (if you change --outdir, point your type checker’s stub path at it).

Using the Generated Types

TypeScript

Nothing to do — TypeScript picks up requence-env.d.ts automatically and types the createService callback contextually:

createService('some-types', (ctx) => {
  const name = ctx.input.name       // typed from the input schema
  return { number: 10 }             // checked against the output schema
})

Python

Unlike TypeScript, a Python type checker cannot infer a named handler’s parameter type from the Service(...) call. Import the type for your service version and annotate the handler’s ctx:

from requence.service import Service
from requence.service.types import some_types  # one class per service version

def handler(ctx: some_types.context) -> some_types.output:
    name = ctx.input["name"]        # typed from the input schema
    return {"number": 10}           # checked against the output schema

Service("some-types", handler)      # the version string is validated too

The class name is your service version with every non-alphanumeric character replaced by _ (and a leading v if it starts with a digit) — e.g. some-types → some_types, 1.2.3 → v1_2_3.

The -> some_types.output annotation is needed when returning an output dict literal directly; omit it if you return through ctx.to_output(...). For a trivial one-liner, a lambda is typed contextually with no annotation or import:

Service("some-types", lambda ctx: {"number": 10})  # ctx is fully typed

Options

Option	Default	Description
--access-token	—	Service access token (falls back to env / config file)
--dev-token	—	Personal access token for branch-specific types
--watch	false	Watch for schema changes and regenerate automatically
--clear / --no-clear	true	Clear the terminal on watch updates

TypeScript

| Option | Default | Description | |—|—|—| | --outfile | requence-env.d.ts | Name of the generated type file | | --outdir | . | Directory to write the type file to |

Python

| Option | Default | Description | |—|—|—| | --outdir | typings | Directory to write the type stubs to |

Watch Mode

During development, use --watch to keep types in sync as you edit schemas in the Requence UI:

TypeScript

bash npx requence-service generate-types --watch

Python

bash requence-service generate-types --watch

The CLI connects to Requence via server-sent events and regenerates types whenever a schema changes.

Branch Types

When using a dev token, the CLI generates types for the active branch instead of the published version. A comment is added to the generated files to indicate which branch the types belong to.