npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@bemedev/app-contract

v3.0.3

Published

Lightweight machine contracts for @bemedev/app

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-contract

Breaking changes in v3.0.0

The delay types are unified across both machine flavors:

  • SyncDelayFunction3 and AsyncDelayFunction3 → DelayFunction3
  • SyncDelayFunction2 and AsyncDelayFunction2 → 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>; // MachineOptions

The 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) or SyncSimpleMachineOptions (unnamed).
  • otherwise → AsyncMachineOptions2 (named) or AsyncSimpleMachineOptions (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 --contract

Creating 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