@xmachines/docs 3.0.0 → 4.0.0

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

@@ -1,86 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuards
-
-# ~~Function: composeGuards()~~
-
-```ts
-function composeGuards<TContext, TEvent>(guards): ComposedGuard;
-```
-
-Defined in: [packages/play-xstate/src/guards/compose.ts:100](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/guards/compose.ts#L100)
-
-Composes the guards with the AND logic, through the and() helper of XState
-
-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:** 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`        | The context type of the state machine |
-| `TEvent`       | `any`        | The event type                        |
-
-## Parameters
-
-| 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)
-
-The and() guard composition of XState
-
-## Throws
-
-When the array of the guards is empty
-
-## Examples
-
-An AND composition with named guards
-
-```typescript
-import { setup } from "xstate";
-import { composeGuards } from "@xmachines/play-xstate";
-
-const machine = setup({
-	guards: {
-		isLoggedIn: ({ context }) => !!context.userId,
-		hasPermission: ({ context }) => context.permissions.includes("admin"),
-	},
-}).createMachine({
-	on: {
-		accessAdmin: {
-			// Both guards must pass
-			guard: composeGuards(["isLoggedIn", "hasPermission"]),
-			target: "adminPanel",
-		},
-	},
-});
-```
-
-An AND composition with inline predicates
-
-```typescript
-import { composeGuards } from "@xmachines/play-xstate";
-
-guard: composeGuards([({ context }) => context.age >= 18, ({ context }) => context.verified]);
-```
-
-## See
-
-- [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,72 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / composeGuardsOr
-
-# ~~Function: composeGuardsOr()~~
-
-```ts
-function composeGuardsOr<TContext, TEvent>(guards): ComposedGuard;
-```
-
-Defined in: [packages/play-xstate/src/guards/compose.ts:159](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/guards/compose.ts#L159)
-
-Composes the guards with the OR logic, through the or() helper of XState
-
-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 | 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`\> | The array of the guard predicates, or of the guard names |
-
-## Returns
-
-[`ComposedGuard`](../type-aliases/ComposedGuard.md)
-
-The or() guard composition of XState
-
-## Throws
-
-When the array of the guards is empty
-
-## Example
-
-An OR composition with named guards
-
-```typescript
-import { setup } from "xstate";
-import { composeGuardsOr } from "@xmachines/play-xstate";
-
-const machine = setup({
-	guards: {
-		isOwner: ({ context }) => context.role === "owner",
-		isAdmin: ({ context }) => context.role === "admin",
-	},
-}).createMachine({
-	on: {
-		deleteResource: {
-			// One guard is sufficient
-			guard: composeGuardsOr(["isOwner", "isAdmin"]),
-			actions: "delete",
-		},
-	},
-});
-```
-
-## See
-
-- [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,43 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / contextFieldMatches
-
-# ~~Function: contextFieldMatches()~~
-
-```ts
-function contextFieldMatches<TContext>(fieldPath, expectedValue): Guard<TContext, PlayEvent>;
-```
-
-Defined in: [packages/play-xstate/src/guards/helpers.ts:75](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/guards/helpers.ts#L75)
-
-Tells you if a context field holds the expected value.
-
-- 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 a match of an XState state node, use the built-in `in:` guard syntax instead.
-
-## Type Parameters
-
-| Type Parameter | Default type                    |
-| -------------- | ------------------------------- |
-| `TContext`     | `Record`\<`string`, `unknown`\> |
-
-## Parameters
-
-| 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)\>
-
-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

@@ -1,78 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / definePlayer
-
-# Function: definePlayer()
-
-```ts
-function definePlayer<TMachine>(config): PlayerFactory<TMachine>;
-```
-
-Defined in: [packages/play-xstate/src/define-player.ts:61](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/define-player.ts#L61)
-
-Creates a player factory from an XState machine
-
-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) | The type of the XState v5 state machine |
-
-## Parameters
-
-| Parameter | Type                                                          | Description                            |
-| --------- | ------------------------------------------------------------- | -------------------------------------- |
-| `config`  | [`PlayerConfig`](../interfaces/PlayerConfig.md)\<`TMachine`\> | The configuration object of the player |
-
-## Returns
-
-[`PlayerFactory`](../type-aliases/PlayerFactory.md)\<`TMachine`\>
-
-The factory function. It makes an actor instance, with an optional input context
-
-## Examples
-
-A basic player factory
-
-```typescript
-import { setup } from "xstate";
-import { definePlayer } from "@xmachines/play-xstate";
-
-const machine = setup({}).createMachine({
-	initial: "idle",
-	states: {
-		idle: { meta: { route: "/" } },
-		active: { meta: { route: "/active" } },
-	},
-});
-
-const createPlayer = definePlayer({ machine });
-const actor = createPlayer();
-actor.start();
-```
-
-More than one actor instance from one factory
-
-```typescript
-const createPlayer = definePlayer({ machine });
-
-// Create an actor for each user
-const alice = createPlayer({ userId: "alice" });
-const bob = createPlayer({ userId: "bob" });
-
-alice.start();
-bob.start();
-
-// The two state machines are independent
-console.log(alice.state.get() !== bob.state.get());
-```
-
-## See
-
-- [Play RFC](../../../../rfc/play.md)
-- [PlayerActor](../classes/PlayerActor.md) for the concrete actor implementation
-- [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/eventMatches.md

@@ -1,45 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / eventMatches
-
-# ~~Function: eventMatches()~~
-
-```ts
-function eventMatches<TEvent>(eventType): Guard<unknown, TEvent>;
-```
-
-Defined in: [packages/play-xstate/src/guards/helpers.ts:52](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/guards/helpers.ts#L52)
-
-Tells you if the type of the event is the expected type
-
-## Type Parameters
-
-| Type Parameter                                                         | Default type                                        |
-| ---------------------------------------------------------------------- | --------------------------------------------------- |
-| `TEvent` _extends_ [`PlayEvent`](../../play/type-aliases/PlayEvent.md) | [`PlayEvent`](../../play/type-aliases/PlayEvent.md) |
-
-## Parameters
-
-| Parameter   | Type     | Description             |
-| ----------- | -------- | ----------------------- |
-| `eventType` | `string` | The expected event type |
-
-## Returns
-
-[`Guard`](../type-aliases/Guard.md)\<`unknown`, `TEvent`\>
-
-The guard predicate. It tests the event type
-
-## Example
-
-```typescript
-const machine = setup({
-	guards: {
-		isSubmitEvent: eventMatches("submit"),
-		isBackOrForward: composeGuardsOr([eventMatches("back"), eventMatches("forward")]),
-	},
-});
-```
-
-## 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/hasContext.md

@@ -1,45 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / hasContext
-
-# ~~Function: hasContext()~~
-
-```ts
-function hasContext<TContext>(path): Guard<TContext, PlayEvent>;
-```
-
-Defined in: [packages/play-xstate/src/guards/helpers.ts:24](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/guards/helpers.ts#L24)
-
-Tells you if the context holds a value at the path, and that the value is truthy
-
-## Type Parameters
-
-| Type Parameter | Default type                    |
-| -------------- | ------------------------------- |
-| `TContext`     | `Record`\<`string`, `unknown`\> |
-
-## Parameters
-
-| Parameter | Type     | Description                                                       |
-| --------- | -------- | ----------------------------------------------------------------- |
-| `path`    | `string` | The path to the context property, with a dot between two segments |
-
-## Returns
-
-[`Guard`](../type-aliases/Guard.md)\<`TContext`, [`PlayEvent`](../../play/type-aliases/PlayEvent.md)\>
-
-The guard predicate. It tests the property for a truthy value
-
-## Example
-
-```typescript
-const machine = setup({
-	guards: {
-		hasUserId: hasContext("userId"),
-		hasEmail: hasContext("user.email"),
-	},
-});
-```
-
-## 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/negateGuard.md

@@ -1,67 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / negateGuard
-
-# ~~Function: negateGuard()~~
-
-```ts
-function negateGuard<TContext, TEvent>(guard): ComposedGuard;
-```
-
-Defined in: [packages/play-xstate/src/guards/compose.ts:215](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/guards/compose.ts#L215)
-
-Negates a guard, through the not() helper of XState
-
-The function inverts the result of a guard: the guard passes, and NOT then fails;
-the guard fails, and NOT then passes. It uses the built-in `not()` helper of
-XState, and the serialization is therefore correct.
-
-## Type Parameters
-
-| Type Parameter | Default type | Description                           |
-| -------------- | ------------ | ------------------------------------- |
-| `TContext`     | `any`        | The context type of the state machine |
-| `TEvent`       | `any`        | The event type                        |
-
-## Parameters
-
-| Parameter | Type                                                                    | Description                                |
-| --------- | ----------------------------------------------------------------------- | ------------------------------------------ |
-| `guard`   | `string` \| [`Guard`](../type-aliases/Guard.md)\<`TContext`, `TEvent`\> | The guard predicate to negate, or its name |
-
-## Returns
-
-[`ComposedGuard`](../type-aliases/ComposedGuard.md)
-
-The not() guard negation of XState
-
-## Example
-
-A NOT composition with a named guard
-
-```typescript
-import { setup } from "xstate";
-import { negateGuard } from "@xmachines/play-xstate";
-
-const machine = setup({
-	guards: {
-		isGuest: ({ context }) => !context.userId,
-	},
-}).createMachine({
-	on: {
-		accessDashboard: {
-			// Permit the transition when the user is NOT a guest, which means an authenticated user
-			guard: negateGuard("isGuest"),
-			target: "dashboard",
-		},
-	},
-});
-```
-
-## See
-
-- [composeGuards](composeGuards.md) for the AND composition
-- [composeGuardsOr](composeGuardsOr.md) for the OR composition
-
-## 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/interfaces/PlayerConfig.md

@@ -1,20 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerConfig
-
-# Interface: PlayerConfig\<TMachine\>
-
-Defined in: [packages/play-xstate/src/types.ts:7](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/types.ts#L7)
-
-The configuration of definePlayer()
-
-## Type Parameters
-
-| Type Parameter                                                                                 |
-| ---------------------------------------------------------------------------------------------- |
-| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |
-
-## Properties
-
-| Property                                 | Type                                              | Description                               | Defined in                                                                                                                             |
-| ---------------------------------------- | ------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-machine"></a> `machine`  | `TMachine`                                        | The XState v5 state machine               | [packages/play-xstate/src/types.ts:9](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/types.ts#L9)   |
-| <a id="property-options"></a> `options?` | [`PlayerOptions`](PlayerOptions.md)\<`TMachine`\> | The lifecycle hooks and the configuration | [packages/play-xstate/src/types.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/types.ts#L12) |

package/api/@xmachines/play-xstate/interfaces/RouteObject.md

@@ -1,17 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteObject
-
-# Interface: RouteObject
-
-Defined in: [packages/play-xstate/src/routing/types.ts:1](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/types.ts#L1)
-
-## Indexable
-
-```ts
-[key: string]: unknown
-```
-
-## Properties
-
-| Property                          | Type     | Defined in                                                                                                                                           |
-| --------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| <a id="property-path"></a> `path` | `string` | [packages/play-xstate/src/routing/types.ts:2](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/types.ts#L2) |

package/api/@xmachines/play-xstate/type-aliases/ComposedGuard.md

@@ -1,19 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / ComposedGuard
-
-# ~~Type Alias: ComposedGuard~~
-
-```ts
-type ComposedGuard = GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>;
-```
-
-Defined in: [packages/play-xstate/src/guards/compose.ts:33](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/guards/compose.ts#L33)
-
-The narrowest public return type of the guard composition helpers.
-
-`GuardPredicate<MachineContext, EventObject, unknown, ParameterizedObject>` is the
-concrete XState guard type with the widest compatibility that uses no `any`.
-
-## Deprecated
-
-The next major version removes the guard utilities. Use the
-combinator types of XState directly.

package/api/@xmachines/play-xstate/type-aliases/Guard.md

@@ -1,36 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / Guard
-
-# ~~Type Alias: Guard\<TContext, TEvent\>~~
-
-```ts
-type Guard<TContext, TEvent> = (args) => boolean;
-```
-
-Defined in: [packages/play-xstate/src/guards/types.ts:12](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/guards/types.ts#L12)
-
-The standard signature of an XState guard function. A guard receives `{ context, event }`.
-
-## Type Parameters
-
-| Type Parameter | Default type                                        |
-| -------------- | --------------------------------------------------- |
-| `TContext`     | `Record`\<`string`, `unknown`\>                     |
-| `TEvent`       | [`PlayEvent`](../../play/type-aliases/PlayEvent.md) |
-
-## Parameters
-
-| Parameter      | Type                                            | Description                                           |
-| -------------- | ----------------------------------------------- | ----------------------------------------------------- |
-| `args`         | \{ `context`: `TContext`; `event`: `TEvent`; \} | The arguments of the guard: the context and the event |
-| `args.context` | `TContext`                                      | The current machine context                           |
-| `args.event`   | `TEvent`                                        | The event that started the evaluation of the guard    |
-
-## Returns
-
-`boolean`
-
-The boolean value. It tells you if the guard passes
-
-## Deprecated
-
-The next major version removes the guard utilities.

package/api/@xmachines/play-xstate/type-aliases/GuardArray.md

@@ -1,23 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / GuardArray
-
-# ~~Type Alias: GuardArray\<TContext, TEvent\>~~
-
-```ts
-type GuardArray<TContext, TEvent> = (Guard<TContext, TEvent> | string)[];
-```
-
-Defined in: [packages/play-xstate/src/guards/types.ts:23](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/guards/types.ts#L23)
-
-The array of the guard predicates, or of the guard names. An array means AND:
-every guard must pass.
-
-## Type Parameters
-
-| Type Parameter | Default type                                        |
-| -------------- | --------------------------------------------------- |
-| `TContext`     | `Record`\<`string`, `unknown`\>                     |
-| `TEvent`       | [`PlayEvent`](../../play/type-aliases/PlayEvent.md) |
-
-## Deprecated
-
-The next major version removes the guard utilities.

package/api/@xmachines/play-xstate/type-aliases/PlayerFactory.md

@@ -1,26 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / PlayerFactory
-
-# Type Alias: PlayerFactory\<TMachine\>
-
-```ts
-type PlayerFactory<TMachine> =
-	undefined extends InputFrom<TMachine>
-		? (input?, options?) => PlayerActor<TMachine>
-		: (input, options?) => PlayerActor<TMachine>;
-```
-
-Defined in: [packages/play-xstate/src/types.ts:135](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/types.ts#L135)
-
-The factory function that definePlayer() returns. Each call makes an independent
-actor instance from the same configuration.
-
-The `input` argument follows the rule of `createActor` in XState. If the input of
-a machine cannot be `undefined`, the first argument of the factory is necessary.
-An absent input is then a compile error, and not an actor that starts in an error
-status with a `null` initial route.
-
-## Type Parameters
-
-| Type Parameter                                                                                 |
-| ---------------------------------------------------------------------------------------------- |
-| `TMachine` _extends_ [`AnyStateMachine`](https://www.jsdocs.io/package/xstate#AnyStateMachine) |

package/api/@xmachines/play-xstate/type-aliases/RouteMetadata.md

@@ -1,9 +0,0 @@
-[API](../../../README.md) / [@xmachines/play-xstate](../README.md) / RouteMetadata
-
-# Type Alias: RouteMetadata
-
-```ts
-type RouteMetadata = string | RouteObject;
-```
-
-Defined in: [packages/play-xstate/src/routing/types.ts:6](https://gitlab.com/xmachin-es/xmachines-js/-/blob/v3.0.0/packages/play-xstate/src/routing/types.ts#L6)