@xmachines/docs 2.0.0-alpha.1 → 2.1.0

package/api/@xmachines/play-xstate/functions/buildRouteUrl.md

@@ -6,42 +6,38 @@
 function buildRouteUrl(routeTemplate, context?): string;
 ```
 
-Defined in: [packages/play-xstate/src/routing/build-url.ts:40](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/build-url.ts#L40)
+Defined in: [packages/play-xstate/src/routing/build-url.ts:38](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/build-url.ts#L38)
 
-Build a full URL from a route template and the actor's context.
+Builds a complete URL from a route template and the context of the actor.
 
-Substitutes `:param` and `:param?` placeholders from `context.params`,
-then appends query params and hash fragments.
+The function replaces each `:param` placeholder and each `:param?` placeholder
+with a value of `context.params`. It then appends the query params and the hash
+fragment.
 
-All parameter values must be in `context.params`. Flat context fields are not
-inspected — this is intentional so misspelled placeholders produce a compile-time
-error rather than silently resolving to `undefined`.
+Every parameter value must be in `context.params`. The function reads no flat
+context field, and this is deliberate: a placeholder with a spelling error
+therefore gives a compile-time error, and it does not resolve to `undefined` in
+silence.
 
 ## Parameters
 
-| Parameter       | Type                                            | Description                                                                                                                                                                                                                                                                                                         |
-| --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `routeTemplate` | `string`                                        | Route path template, e.g. `"/profile/:userId"` or `"/settings/:section?"`.                                                                                                                                                                                                                                          |
-| `context`       | [`RouteContext`](../interfaces/RouteContext.md) | Actor context object. Route parameters must be in `context.params`; flat context fields are not inspected. **Must include a `query` field** (use `query: {}` when no query parameters are needed). Omitting `query` when `params` is present throws `MissingQueryContextError` to prevent silent query-string loss. |
+| Parameter       | Type                                            | Description                                                                                                                                                                                                          |
+| --------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `routeTemplate` | `string`                                        | The template of the route path, for example `"/profile/:userId"` or `"/settings/:section?"`.                                                                                                                         |
+| `context`       | [`RouteContext`](../interfaces/RouteContext.md) | The context object of the actor. Each route parameter must be in `context.params`, because the function reads no flat context field. An absent `query` field builds a URL without a query, exactly like `query: {}`. |
 
 ## Returns
 
 `string`
 
-The fully resolved URL string.
+The complete URL string.
 
 ## Throws
 
-When a **required** `:param` placeholder has no
-matching value in context. Optional parameters (`:param?`) are silently omitted
-when missing. Import the class from `@xmachines/play-xstate/errors`.
-
-## Throws
-
-When the context has a `params` field but no
-`query` field. This indicates a routing-aware machine context that was not set up
-to receive query parameters, which would silently drop query params from
-`play.route` events. Import the class from `@xmachines/play-xstate/errors`.
+When a **necessary** `:param` placeholder has no
+value in the context. The function omits an optional parameter (`:param?`) in
+silence when its value is absent. Import the class from
+`@xmachines/play-xstate/errors`.
 
 ## Example
 
@@ -50,5 +46,5 @@ buildRouteUrl("/user/:id", { params: { id: "123" }, query: { tab: "profile" }, h
 // → "/user/123?tab=profile#top"
 
 buildRouteUrl("/settings/:section?", { params: {}, query: {} });
-// → "/settings"  (optional param omitted, no query string)
+// → "/settings"  (the optional param is absent, and there is no query string)
 ```

package/api/@xmachines/play-xstate/functions/composeGuards.md

@@ -1,58 +1,56 @@
 [API](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuards
 
-# Function: composeGuards()
+# ~~Function: composeGuards()~~
 
 ```ts
 function composeGuards<TContext, TEvent>(guards): ComposedGuard;
 ```
 
-Defined in: [packages/play-xstate/src/guards/compose.ts:130](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/compose.ts#L130)
+Defined in: [packages/play-xstate/src/guards/compose.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/guards/compose.ts#L100)
 
-Compose guards with AND logic.
+Composes the guards with the AND logic, through the and() helper of XState
 
-Combines multiple guard predicates using AND semantics—all guards must pass for
-the composition to succeed. Evaluation is short-circuiting, left to right.
+The function joins more than one guard predicate with the AND semantics: every
+guard must pass, and the composition then succeeds. It uses the built-in `and()`
+helper of XState. The type inference and the serialization of the machine are
+therefore correct.
 
-**Architectural Context:** Supports **Actor Authority (INV-01)** by enabling
-declarative guard composition in state machine transitions. Guards enforce business
-logic rules that determine whether navigation or actions are valid.
-
-**XState v6:** the composed value is a plain predicate. Call it inside a
-transition function and return early to block the transition:
+**Architectural context:** the function supports **Actor Authority (INV-01)**,
+because it composes the guards of a state machine transition declaratively. A
+guard enforces a rule of the business logic, and that rule decides if a
+navigation or an action is valid.
 
 ## Type Parameters
 
-| Type Parameter | Default type | Description                                                                                                            |
-| -------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------- |
-| `TContext`     | `any`        | State machine context type (defaults to `any` so the documented inline-predicate examples compile without annotations) |
-| `TEvent`       | `any`        | Event type                                                                                                             |
+| Type Parameter | Default type | Description                           |
+| -------------- | ------------ | ------------------------------------- |
+| `TContext`     | `any`        | The context type of the state machine |
+| `TEvent`       | `any`        | The event type                        |
 
 ## Parameters
 
-| Parameter | Type                                                                  | Description                                                                                                          |
-| --------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `guards`  | [`GuardArray`](../type-aliases/GuardArray.md)\<`TContext`, `TEvent`\> | Array of guard predicates or guard names (string references resolved against `args.guards` from `setup({ guards })`) |
+| Parameter | Type                                                                  | Description                                                         |
+| --------- | --------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| `guards`  | [`GuardArray`](../type-aliases/GuardArray.md)\<`TContext`, `TEvent`\> | The array of the guard predicates, or of the guard names as strings |
 
 ## Returns
 
 [`ComposedGuard`](../type-aliases/ComposedGuard.md)
 
-Predicate returning `true` only when every guard passes
+The and() guard composition of XState
 
 ## Throws
 
-If guards array is empty
+When the array of the guards is empty
 
 ## Examples
 
-AND composition with named guards
+An AND composition with named guards
 
 ```typescript
 import { setup } from "xstate";
 import { composeGuards } from "@xmachines/play-xstate";
 
-const canAccessAdmin = composeGuards(["isLoggedIn", "hasPermission"]);
-
 const machine = setup({
 	guards: {
 		isLoggedIn: ({ context }) => !!context.userId,
@@ -60,26 +58,29 @@ const machine = setup({
 	},
 }).createMachine({
 	on: {
-		accessAdmin: (args) => {
-			if (!canAccessAdmin(args)) return;
-			return { target: "adminPanel" };
+		accessAdmin: {
+			// Both guards must pass
+			guard: composeGuards(["isLoggedIn", "hasPermission"]),
+			target: "adminPanel",
 		},
 	},
 });
 ```
 
-AND composition with inline predicates
+An AND composition with inline predicates
 
 ```typescript
 import { composeGuards } from "@xmachines/play-xstate";
 
-const isEligible = composeGuards([
-	({ context }) => context.age >= 18,
-	({ context }) => context.verified,
-]);
+guard: composeGuards([({ context }) => context.age >= 18, ({ context }) => context.verified]);
 ```
 
 ## See
 
-- [composeGuardsOr](composeGuardsOr.md) for OR composition
-- [negateGuard](negateGuard.md) for NOT logic
+- [composeGuardsOr](composeGuardsOr.md) for the OR composition
+- [negateGuard](negateGuard.md) for the NOT logic
+
+## Deprecated
+
+Use the `and()`, `or()`, and `not()` combinators of XState directly. This helper
+does not compose with a guard slot that `setup()` types, and the next major version removes it.

package/api/@xmachines/play-xstate/functions/composeGuardsOr.md

@@ -1,51 +1,50 @@
 [API](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuardsOr
 
-# Function: composeGuardsOr()
+# ~~Function: composeGuardsOr()~~
 
 ```ts
 function composeGuardsOr<TContext, TEvent>(guards): ComposedGuard;
 ```
 
-Defined in: [packages/play-xstate/src/guards/compose.ts:189](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/compose.ts#L189)
+Defined in: [packages/play-xstate/src/guards/compose.ts:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/guards/compose.ts#L159)
 
-Compose guards with OR logic.
+Composes the guards with the OR logic, through the or() helper of XState
 
-Combines multiple guard predicates using OR semantics—at least one guard must pass
-for the composition to succeed. Evaluation is short-circuiting, left to right.
+The function joins more than one guard predicate with the OR semantics: one guard
+must pass at least, and the composition then succeeds. It uses the built-in `or()`
+helper of XState, and the type inference is therefore correct.
 
 ## Type Parameters
 
-| Type Parameter | Default type |
-| -------------- | ------------ |
-| `TContext`     | `any`        |
-| `TEvent`       | `any`        |
+| Type Parameter | Default type | Description                           |
+| -------------- | ------------ | ------------------------------------- |
+| `TContext`     | `any`        | The context type of the state machine |
+| `TEvent`       | `any`        | The event type                        |
 
 ## Parameters
 
-| Parameter | Type                                                                  | Description                                                                                                          |
-| --------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `guards`  | [`GuardArray`](../type-aliases/GuardArray.md)\<`TContext`, `TEvent`\> | Array of guard predicates or guard names (string references resolved against `args.guards` from `setup({ guards })`) |
+| Parameter | Type                                                                  | Description                                              |
+| --------- | --------------------------------------------------------------------- | -------------------------------------------------------- |
+| `guards`  | [`GuardArray`](../type-aliases/GuardArray.md)\<`TContext`, `TEvent`\> | The array of the guard predicates, or of the guard names |
 
 ## Returns
 
 [`ComposedGuard`](../type-aliases/ComposedGuard.md)
 
-Predicate returning `true` when any guard passes
+The or() guard composition of XState
 
 ## Throws
 
-If guards array is empty
+When the array of the guards is empty
 
 ## Example
 
-OR composition with named guards
+An OR composition with named guards
 
 ```typescript
 import { setup } from "xstate";
 import { composeGuardsOr } from "@xmachines/play-xstate";
 
-const canDelete = composeGuardsOr(["isOwner", "isAdmin"]);
-
 const machine = setup({
 	guards: {
 		isOwner: ({ context }) => context.role === "owner",
@@ -53,9 +52,10 @@ const machine = setup({
 	},
 }).createMachine({
 	on: {
-		deleteResource: (args, enq) => {
-			if (!canDelete(args)) return;
-			enq(() => deleteIt());
+		deleteResource: {
+			// One guard is sufficient
+			guard: composeGuardsOr(["isOwner", "isAdmin"]),
+			actions: "delete",
 		},
 	},
 });
@@ -63,5 +63,10 @@ const machine = setup({
 
 ## See
 
-- [composeGuards](composeGuards.md) for AND composition
-- [negateGuard](negateGuard.md) for NOT logic
+- [composeGuards](composeGuards.md) for the AND composition
+- [negateGuard](negateGuard.md) for the NOT logic
+
+## Deprecated
+
+Use the `and()`, `or()`, and `not()` combinators of XState directly. This helper
+does not compose with a guard slot that `setup()` types, and the next major version removes it.

package/api/@xmachines/play-xstate/functions/contextFieldMatches.md

@@ -1,22 +1,22 @@
 [API](../../../README.md) / [@xmachines/play-xstate](../README.md) / contextFieldMatches
 
-# Function: contextFieldMatches()
+# ~~Function: contextFieldMatches()~~
 
 ```ts
 function contextFieldMatches<TContext>(fieldPath, expectedValue): Guard<TContext, PlayEvent>;
 ```
 
-Defined in: [packages/play-xstate/src/guards/helpers.ts:71](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/helpers.ts#L71)
+Defined in: [packages/play-xstate/src/guards/helpers.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/guards/helpers.ts#L75)
 
-Check if a context field matches an expected value.
+Tells you if a context field holds the expected value.
 
-- Accepts an explicit dot-separated field path (e.g. `"user.role"`)
-- Uses strict equality for primitives, deep structural equality for objects
-- Object comparison is key-order-insensitive: `{a:1,b:2}` equals `{b:2,a:1}`
-- Supports Date, RegExp, class instances, nested objects and arrays via `dequal/lite`
-- Does NOT use substring matching — `"a"` will not match `"active"`
+- The function accepts an explicit field path, with a dot between two segments, for example `"user.role"`
+- It compares a primitive with a strict equality, and an object with a deep structural equality
+- The order of the keys has no effect on the comparison of an object: `{a:1,b:2}` equals `{b:2,a:1}`
+- It supports a Date, a RegExp, an instance of a class, a nested object, and an array, through `dequal/lite`
+- It does NOT match a substring: `"a"` does not match `"active"`
 
-For XState state-node matching, use the built-in `in:` guard syntax instead.
+For a match of an XState state node, use the built-in `in:` guard syntax instead.
 
 ## Type Parameters
 
@@ -26,13 +26,18 @@ For XState state-node matching, use the built-in `in:` guard syntax instead.
 
 ## Parameters
 
-| Parameter       | Type      | Description                                                          |
-| --------------- | --------- | -------------------------------------------------------------------- |
-| `fieldPath`     | `string`  | Dot-separated path to context property (e.g., "status", "user.role") |
-| `expectedValue` | `unknown` | Value to compare against (string, object, Date, etc.)                |
+| Parameter       | Type      | Description                                                                                            |
+| --------------- | --------- | ------------------------------------------------------------------------------------------------------ |
+| `fieldPath`     | `string`  | The path to the context property, with a dot between two segments, for example "status" or "user.role" |
+| `expectedValue` | `unknown` | The value for the comparison: a string, an object, a Date, and so on                                   |
 
 ## Returns
 
 [`Guard`](../type-aliases/Guard.md)\<`TContext`, [`PlayEvent`](../../play/type-aliases/PlayEvent.md)\>
 
-Guard predicate checking if context field matches
+The guard predicate. It tests the context field for the value
+
+## Deprecated
+
+This function is part of the guard utilities, and the next major version removes
+them. Write a plain typed predicate instead.

package/api/@xmachines/play-xstate/functions/definePlayer.md

@@ -6,36 +6,36 @@
 function definePlayer<TMachine>(config): PlayerFactory<TMachine>;
 ```
 
-Defined in: [packages/play-xstate/src/define-player.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/define-player.ts#L61)
+Defined in: [packages/play-xstate/src/define-player.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/define-player.ts#L61)
 
-Create a player factory from an XState machine
+Creates a player factory from an XState machine
 
-Factory pattern that accepts an XState v6 machine,
-returning a function that creates [PlayerActor](../classes/PlayerActor.md) instances. This enables
-creating multiple actor instances from a single configuration, useful for
-testing, multi-instance scenarios, or server-side rendering.
+This factory function accepts an XState v5 machine. It returns a function that
+makes [PlayerActor](../classes/PlayerActor.md) instances. One configuration can therefore make more
+than one actor instance, and this helps with a test, with an application of
+several instances, and with a render on the server.
 
 ## Type Parameters
 
-| Type Parameter                                                                                 | Description                  |
-| ---------------------------------------------------------------------------------------------- | ---------------------------- |
-| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | XState v6 state machine type |
+| Type Parameter                                                                                 | Description                             |
+| ---------------------------------------------------------------------------------------------- | --------------------------------------- |
+| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) | The type of the XState v5 state machine |
 
 ## Parameters
 
-| Parameter | Type                                                          | Description                 |
-| --------- | ------------------------------------------------------------- | --------------------------- |
-| `config`  | [`PlayerConfig`](../interfaces/PlayerConfig.md)\<`TMachine`\> | Player configuration object |
+| Parameter | Type                                                          | Description                            |
+| --------- | ------------------------------------------------------------- | -------------------------------------- |
+| `config`  | [`PlayerConfig`](../interfaces/PlayerConfig.md)\<`TMachine`\> | The configuration object of the player |
 
 ## Returns
 
 [`PlayerFactory`](../type-aliases/PlayerFactory.md)\<`TMachine`\>
 
-Factory function that creates actor instances with optional input context
+The factory function. It makes an actor instance, with an optional input context
 
 ## Examples
 
-Basic player factory
+A basic player factory
 
 ```typescript
 import { setup } from "xstate";
@@ -54,19 +54,19 @@ const actor = createPlayer();
 actor.start();
 ```
 
-Multiple actor instances from single factory
+More than one actor instance from one factory
 
 ```typescript
 const createPlayer = definePlayer({ machine });
 
-// Create actors for different users
+// Create an actor for each user
 const alice = createPlayer({ userId: "alice" });
 const bob = createPlayer({ userId: "bob" });
 
 alice.start();
 bob.start();
 
-// Independent state machines
+// The two state machines are independent
 console.log(alice.state.get() !== bob.state.get());
 ```
 
@@ -74,5 +74,5 @@ console.log(alice.state.get() !== bob.state.get());
 
 - [Play RFC](../../../../rfc/play.md)
 - [PlayerActor](../classes/PlayerActor.md) for the concrete actor implementation
-- [PlayerConfig](../interfaces/PlayerConfig.md) for configuration options
-- [PlayerFactory](../type-aliases/PlayerFactory.md) for factory function signature
+- [PlayerConfig](../interfaces/PlayerConfig.md) for the configuration options
+- [PlayerFactory](../type-aliases/PlayerFactory.md) for the signature of the factory function

package/api/@xmachines/play-xstate/functions/deriveRoute.md

@@ -6,34 +6,35 @@
 function deriveRoute(stateMeta): string | null;
 ```
 
-Defined in: [packages/play-xstate/src/routing/derive-route.ts:91](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/routing/derive-route.ts#L91)
+Defined in: [packages/play-xstate/src/routing/derive-route.ts:92](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/routing/derive-route.ts#L92)
 
-Derive route from XState state metadata
+Derives the route from the metadata of an XState state
 
-Extracts route URL template from `meta.route` in the active state's metadata.
-Supports both string routes (`"/about"`) and object routes with path property
-(`{ path: "/about" }`). Returns null for states without route metadata (not
-all states need to be routable).
+The function reads the URL template of the route from the `meta.route` field in
+the metadata of the active state. It supports a string route (`"/about"`) and also
+an object route with a path property (`{ path: "/about" }`). It returns null for a
+state without route metadata, because not every state needs a route.
 
-**Architectural Context:** Implements **Actor Authority (INV-01)** by extracting
-routing information from state machine definitions rather than external configuration.
-The route is determined by the Actor's current state, not by infrastructure decisions.
+**Architectural context:** the function implements **Actor Authority (INV-01)**,
+because it reads the routing information from the state machine definition, and
+not from an external configuration. The current state of the Actor decides the
+route, and no decision of the infrastructure decides it.
 
 ## Parameters
 
-| Parameter   | Type                            | Description                            |
-| ----------- | ------------------------------- | -------------------------------------- |
-| `stateMeta` | `Record`\<`string`, `unknown`\> | State metadata from snapshot.getMeta() |
+| Parameter   | Type                            | Description                                |
+| ----------- | ------------------------------- | ------------------------------------------ |
+| `stateMeta` | `Record`\<`string`, `unknown`\> | The state metadata from snapshot.getMeta() |
 
 ## Returns
 
 `string` \| `null`
 
-Route path template (may include :params) or null if no route found
+The template of the route path, which can hold a :param, or null when the function finds no route
 
 ## Examples
 
-Basic route extraction
+The basic read of a route
 
 ```typescript
 import { deriveRoute } from "@xmachines/play-xstate";
@@ -56,7 +57,7 @@ const route = deriveRoute(meta);
 console.log(route); // "/about"
 ```
 
-Route with parameters
+A route with a parameter
 
 ```typescript
 const machine = setup({}).createMachine({
@@ -71,10 +72,10 @@ const machine = setup({}).createMachine({
 });
 
 const route = deriveRoute(snapshot.getMeta());
-console.log(route); // "/profile/:userId" (template, before substitution)
+console.log(route); // "/profile/:userId" — the template, before the substitution
 ```
 
-Route object format
+The object form of a route
 
 ```typescript
 const machine = setup({}).createMachine({
@@ -95,15 +96,15 @@ console.log(route); // "/dashboard"
 ## See
 
 - [Play RFC](../../../../rfc/play.md)
-- [buildRouteUrl](buildRouteUrl.md) for URL construction with parameter substitution
-- [isAbsoluteRoute](isAbsoluteRoute.md) for checking path absoluteness
+- [buildRouteUrl](buildRouteUrl.md) for the construction of a URL, with the substitution of each parameter
+- [isAbsoluteRoute](isAbsoluteRoute.md) for the test of an absolute path
 
 ## Remarks
 
-This function checks `meta.route` for route definitions. States with `route: {}` config
-are routable. Parameter substitution happens via [buildRouteUrl](buildRouteUrl.md), not in this
-function (deriveRoute returns templates).
+This function reads the route definition from `meta.route`. A state with a
+`route: {}` config has a route. [buildRouteUrl](buildRouteUrl.md) substitutes each parameter,
+and this function does not: deriveRoute returns a template.
 
-**Non-routable States:** States without `meta.route` return `null`. This is intentional—
-not all states need routes. For example, intermediate loading states or substates may
-not correspond to distinct URLs.
+**A state without a route:** a state without a `meta.route` field gives `null`.
+This is deliberate, because not every state needs a route. An intermediate loading
+state and a substate, for example, often have no URL of their own.

package/api/@xmachines/play-xstate/functions/eventMatches.md

@@ -1,14 +1,14 @@
 [API](../../../README.md) / [@xmachines/play-xstate](../README.md) / eventMatches
 
-# Function: eventMatches()
+# ~~Function: eventMatches()~~
 
 ```ts
 function eventMatches<TEvent>(eventType): Guard<unknown, TEvent>;
 ```
 
-Defined in: [packages/play-xstate/src/guards/helpers.ts:50](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.0.0-alpha.1/packages/play-xstate/src/guards/helpers.ts#L50)
+Defined in: [packages/play-xstate/src/guards/helpers.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v2.1.0/packages/play-xstate/src/guards/helpers.ts#L52)
 
-Check if event type matches expected type
+Tells you if the type of the event is the expected type
 
 ## Type Parameters
 
@@ -18,15 +18,15 @@ Check if event type matches expected type
 
 ## Parameters
 
-| Parameter   | Type     | Description         |
-| ----------- | -------- | ------------------- |
-| `eventType` | `string` | Expected event type |
+| Parameter   | Type     | Description             |
+| ----------- | -------- | ----------------------- |
+| `eventType` | `string` | The expected event type |
 
 ## Returns
 
 [`Guard`](../type-aliases/Guard.md)\<`unknown`, `TEvent`\>
 
-Guard predicate checking event type
+The guard predicate. It tests the event type
 
 ## Example
 
@@ -38,3 +38,8 @@ const machine = setup({
 	},
 });
 ```
+
+## Deprecated
+
+This function is part of the guard utilities, and the next major version removes
+them. Write a plain typed predicate instead.