@bemedev/app-contract
v3.0.3
Published
Lightweight machine contracts for @bemedev/app
Maintainers
Readme
@bemedev/app-contract
Lightweight machine contracts for @bemedev/app.
A contract registers a state machine's JSON config and its types only. It never contains option implementations (actions, guards, delays, actors), so it can be shared with API layers and other consumers that only need the machine's typing surface.
The package is self-contained: every type it needs is vendored inside
@bemedev/app-contract, and it does not import or re-export anything from
@bemedev/app.
Installation
pnpm add @bemedev/app-contractBreaking changes in v3.0.0
The delay types are unified across both machine flavors:
SyncDelayFunction3andAsyncDelayFunction3→DelayFunction3SyncDelayFunction2andAsyncDelayFunction2→DelayFunction2
The delays members of SyncMachineOptions2, AsyncMachineOptions2,
SyncSimpleMachineOptions and AsyncSimpleMachineOptions now use DelayFunction2,
so annotate your delay callbacks with the new names.
Usage
// auth.contract.ts
import { createContract } from '@bemedev/app-contract';
import { type } from '@bemedev/typings';
export const authContract = createContract(
{
initial: 'idle',
states: {
idle: { on: { LOGIN: '/authenticated' } },
authenticated: { initial: 'loading', states: { loading: {} } },
},
},
{
context: type({ count: 'number' }),
pContext: type({ token: 'string' }),
eventsMap: type({ LOGIN: 'undefined' }),
},
);The signature mirrors createMachine(config, types) from @bemedev/app, but the
types argument only accepts context, pContext, eventsMap, actorsMap and
sync. There is no options argument.
A named form is also available: createContract('auth', config, types). The name is
type-level only — it selects the matching Register entry and is not part of the
returned object.
Reading the contract types
import type {
ContractContext,
ContractEventArg,
ContractEvents,
ContractOptions,
ContractPaths,
ContractPContext,
} from '@bemedev/app-contract';
import { authContract } from './auth.contract';
type Paths = ContractPaths<typeof authContract>;
// '/' | '/idle' | '/authenticated' | '/authenticated/loading'
type Context = ContractContext<typeof authContract>; // { count: number }
type PrivateContext = ContractPContext<typeof authContract>; // { token: string }
type Events = ContractEvents<typeof authContract>;
type EventArg = ContractEventArg<typeof authContract>;
type Options = ContractOptions<typeof authContract>; // MachineOptionsThe returned object is frozen and has the shape { config, types }. It does not
expose any machine runtime, option implementation, or interpreter.
A contract type carries three things: the config, the inferred types (events,
eventMap, actorsMap, context, pContext, tags, paths, sync) and the
type-only options surface returned by createOptions (nothing is emitted at
runtime).
The options surface follows the sync flag:
sync: true→SyncMachineOptions2(named) orSyncSimpleMachineOptions(unnamed).- otherwise →
AsyncMachineOptions2(named) orAsyncSimpleMachineOptions(unnamed).
Named contracts narrow the option keys with the Register entry (actions,
guards, delays, children, emitters).
Using a contract from a machine
A contract can be passed directly to createMachine:
import { createMachine } from '@bemedev/app';
import { authContract } from './auth.contract';
export const authMachine = createMachine(authContract).createOptions(
({ action }) => ({ actions: { login: action(() => {}) } }),
);The explicit form is still supported, and is useful when the machine is registered under a name:
export const authMachine = createMachine(
'auth',
authContract.config,
authContract.types,
).createOptions(({ action }) => ({ actions: { login: action(() => {}) } }));Contract-driven options are built without a machine instance, using createOptions
from @bemedev/app-options, then attached to the machine:
import { createMachine } from '@bemedev/app';
import { createOptions } from '@bemedev/app-options';
const options = createOptions(authContract)(({ assign }) => ({
actions: {
increment: assign('context.count', ({ context }) => context.count + 1),
},
}));
const authMachine = createMachine(authContract);
authMachine.addOptions(() => options);CLI compatibility
@bemedev/app-cli handles *.contract.ts files in a dedicated pass, separate from
machines. Machine generation (*.machine.ts and *.fsm.ts) is the default, and
contract generation is opt-in through --contract, which then only scans
*.contract.ts files. Machine types are written to app.gen.ts, while contract
types are written to app.contract.gen.ts and registered in the
@bemedev/app-contract Register interface. A default-exported named
createContract('name', ...) call is parsed exactly like createMachine(...). The
unnamed form is not discoverable, because it carries no name:
# Machine types only, into app.gen.ts (default)
npx app-cli generate
# Contract types only, into app.contract.gen.ts
npx app-cli generate --contractCreating a new empty *.contract.ts file while app-cli watch is running scaffolds
it with a createContract starter. Run app-cli watch --contract to regenerate
contract types on change.
Exports
| Export | Kind | Description |
| --------------------------- | ---- | ----------------------------------------------------------------- |
| createContract | Fn | Registers a JSON config plus types and returns a frozen contract. |
| StatePaths | Type | Resolves every state path declared by a config. |
| Contract | Type | Contract shape. |
| CreateContract_F | Type | Function signature of createContract. |
| CreateContractNamed_F | Type | Named signature, resolved through Register. |
| CreateContractNoName_F | Type | Unnamed signature, resolved from the config. |
| Register | Type | Registry augmented with pre-resolved contract types. |
| RegisterOptions | Type | Option identifiers available for a registry entry. |
| TargetDef | Type | Registry path tree node. |
| ContractSchemas | Type | Schema map accepted by createContract. |
| ContractTypes | Type | Inferred typing surface shape. |
| MachineOptions | Type | Union of async and sync machine options. |
| AnyMachineOptions | Type | Base shape satisfied by every machine options surface. |
| SimpleMachineOptions | Type | Union of async and sync simple machine options. |
| AsyncMachineOptions2 | Type | Registered async machine options. |
| SyncMachineOptions2 | Type | Registered sync machine options. |
| AsyncSimpleMachineOptions | Type | Loose async machine options. |
| SyncSimpleMachineOptions | Type | Loose sync machine options. |
| ContractConfig | Type | Machine JSON config. |
| ContractTypesOf | Type | Inferred types. |
| ContractOptions | Type | Machine options surface. |
| ContractEvents | Type | Union of typed event objects. |
| ContractEventType | Type | Union of event names. |
| ContractEventArg | Type | Accepted arguments when sending an event. |
| ContractEventsMap | Type | Raw events map. |
| ContractActorsMap | Type | Raw actors map. |
| ContractContext | Type | Public context. |
| ContractPContext | Type | Private context. |
| ContractTags | Type | Union of tags declared by the contract. |
| ContractPaths | Type | Union of state paths. |
| ContractSync | Type | Sync execution flag. |
The vendored machine types are exported from the same entry point: CommonConfig2,
NodeConfig2, TransitionsConfig, EventObject, EventsMap, ActorsConfigMap,
PrimitiveObject, StandardOutput, inferT, DelayFunction2, DelayFunction3,
and their supporting helper types. Import them from @bemedev/app-contract — no
@bemedev/app installation is required.
License
MIT
