Skip to content
ContractSpec
Start here

Core guide · Start · 3 min read

Read your first operation

Trace a maintained contract from its input schema to its deliberately small handler.

Source context

Source reading walkthrough · d58fa5b7

Repository links may require access. Source inspection is separate from a clean public-package installation.

AN INTERACTIVE READING MAP

Get the shape of this guide.

Move through the ideas, inspect their relationships, or make a focused reading path. The complete guide stays below.

READING SEQUENCE

Understand how the ideas connect

01 / READING POINT

What this walkthrough demonstrates

The maintained minimal example declares an operation named user.create. It accepts an email and returns the same email. Despite the operation's name, the shown handler does not create a persistent account, send a message or call a provider.

This is a reading walkthrough of real source. It helps you understand the shape of an operation before introducing databases, authentication or transport setup. The complete files are linked from the source snapshot; the excerpts below are intentionally partial.

1 / 5

0 points in your packet

What this walkthrough demonstrates

The maintained minimal example declares an operation named user.create. It accepts an email and returns the same email. Despite the operation's name, the shown handler does not create a persistent account, send a message or call a provider.

This is a reading walkthrough of real source. It helps you understand the shape of an operation before introducing databases, authentication or transport setup. The complete files are linked from the source snapshot; the excerpts below are intentionally partial.

Read its identity first

The meta object gives the operation a stable key and version, then records its purpose, ownership and stability. These fields tell a caller which contract it is using and help a maintainer find the responsible team.

Use the key and version together when comparing an implementation with its documentation. A source path can move without changing the operation's public identity.

key: 'user.create',
version: '1.0.0',

Exact metadata excerpt from examples/minimal/src/contracts/user.ts at d58fa5b7; not a standalone declaration.

Follow the input and output

UserInput is a SchemaModel with one required email field. The maintained declaration uses ScalarTypeEnum.EmailAddress(). Both input and output point to that model, so the example describes the same shape on either side.

Its authentication setting is anonymous because the example is demonstrating data flow. Treat that as an intentional property of this sample, not a default to copy into an operation that reads or changes private data.

io: {
  input: UserInput,
  output: UserInput,
},
policy: {
  auth: 'anonymous',
},

Exact partial contract excerpt from examples/minimal/src/contracts/user.ts at d58fa5b7.

Find the business implementation

The companion userInputHandler has a type derived from CreateUser and returns the provided email. The contract describes the boundary; this function supplies the implementation. Editing the declaration does not magically add persistence to this function.

To turn the example into a real account workflow, you would need to decide how accounts are stored, what happens when an address is already used, how identity is established and which outcome the caller receives. Those choices belong to your application.

return {
  email: input.email,
};

Exact handler excerpt from examples/minimal/src/handlers/user-input.handler.ts at d58fa5b7.

Make the next experiment observable

First inspect the example's typecheck, validation and smoke scripts. Its smoke test checks stable example metadata and the feature-to-operation reference; it is not an end-to-end API test.

For your own next step, bind a disposable handler to the registry and test a valid email, invalid input and an invalid handler result. Then expose that registry through one adapter. This adds one responsibility at a time and makes failures easy to locate.

Change the entry point. Keep the meaning.

Follow a request to export a report through three interfaces. The useful common ground is the registered operation and its boundary.

Where does this request begin?

A CONCRETE SITUATION

A form helps someone make a valid request.

A person selects a report and gives a reason for the export.

01 / Form

Collect the report and reason, and explain errors in the person’s language.

What changes

Labels, validation messages and the way the result is presented.

What stays explicit

The report, required reason, business implementation and configured execution checks.

Follow the consequence

The form can make a requirement clear. The server still needs to reject a request that bypasses the form.

An authored situation, grounded in the linked source guides. Choosing a case explores its expected responsibilities; it does not execute an operation.