MobX Keystone

https://github.com/xaviergonz/mobx-keystone
Admin
MobX Keystone is a MobX-powered state management solution based on data trees, offering first-class...
Tokens:25,263
Snippets:181
Trust Score:8.4
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Installing mobx-keystone with npm (bash)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/installation.mdx

Installs the mobx-keystone library using the npm package manager, saving it as a project dependency. This is an alternative to using Yarn for installation.

```bash
npm install --save mobx-keystone
```

--------------------------------

### Installing mobx-keystone with Yarn (bash)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/installation.mdx

Installs the mobx-keystone library using the Yarn package manager. This is one of the standard ways to add the library to your project dependencies.

```bash
yarn add mobx-keystone
```

--------------------------------

### Install mobx-keystone-yjs with npm

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/packages/mobx-keystone-yjs/README.md

Use npm to install the mobx-keystone-yjs package as a project dependency.

```Shell
npm install mobx-keystone-yjs
```

--------------------------------

### Install MobX-Keystone using yarn

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/README.md

Installs the mobx-keystone library and its dependencies using the yarn package manager. This command adds the library to your project's dependencies.

```shell
yarn add mobx-keystone
```

--------------------------------

### Install mobx-keystone-yjs with yarn

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/packages/mobx-keystone-yjs/README.md

Use yarn to install the mobx-keystone-yjs package as a project dependency.

```Shell
yarn add mobx-keystone-yjs
```

--------------------------------

### Install MobX-Keystone using npm

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/README.md

Installs the mobx-keystone library and its dependencies using the npm package manager. This command adds the library to your project's dependencies.

```shell
npm install mobx-keystone
```

--------------------------------

### Configuring Babel for mobx-keystone (JSON)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/installation.mdx

Configures Babel (`babel.config.json`) with necessary presets and plugins to support TypeScript (if used), decorators, and class properties for mobx-keystone. The `loose` option for `plugin-proposal-class-properties` depends on your MobX version (5/6 or 4).

```json
{
  "presets": [
    // ...
    // If you use TypeScript
    ["@babel/preset-typescript", { "allowDeclareFields": true }]
  ],
  "plugins": [
    ["@babel/plugin-proposal-decorators", { "version": "legacy" }],
    // MobX 5/6
    ["@babel/plugin-proposal-class-properties"]
    // MobX 4
    // ["@babel/plugin-proposal-class-properties", { "loose": true }]
  ]
}
```

--------------------------------

### Server Simulation (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/examples/clientServer/clientServer.mdx

This file simulates the server side of the application. It likely receives actions captured from client instances, applies them to its own state, and potentially sends back confirmation or the applied action to the clients, incorporating a simulated network delay.

```ts
// server.ts simulation
import { createRootStore } from "mobx-keystone";

// Simulate server logic here
export const server = {
  processAction: (action: any) => {
    console.log("Server received action:", action);
    // Simulate delay
    return new Promise(resolve => setTimeout(() => resolve(action), 500));
  }
};
```

--------------------------------

### App Instance Component (TSX)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/examples/clientServer/clientServer.mdx

This component represents a single instance of the client application or a part of it. It interacts with a local store, captures actions performed locally, and sends them to the simulated server, waiting for the server's confirmation before applying the action locally (pessimistic update).

```tsx
// appInstance.tsx simulation
import React from "react";
import { createRootStore, captureAction, applyAction } from "mobx-keystone";

// Simulate an app instance component
const AppInstance = () => {
  const store = createRootStore({}); // Simulate store

  const doSomething = () => {
    const action = captureAction(() => {
      // Simulate local action
      console.log("Local action performed");
    });

    // Send action to server and wait for confirmation (pessimistic)
    server.processAction(action).then(serverAction => {
      applyAction(store, serverAction);
      console.log("Action applied after server confirmation");
    });
  };

  return (
    <div>
      <h2>App Instance</h2>
      <button onClick={doSomething}>Do Something</button>
    </div>
  );
};

export default AppInstance;
```

--------------------------------

### Main App Component (TSX)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/examples/clientServer/clientServer.mdx

This is the main application component that sets up and renders the two simulated client instances. It likely handles the communication layer between the instances and the simulated server, demonstrating how actions are captured, sent, and applied across different parts of the application.

```tsx
// app.tsx simulation
import React from "react";
import AppInstance from "./appInstance";

// Main app component rendering two instances
export const App = () => {
  return (
    <div>
      <h1>Client/Server Simulation</h1>
      <div style={{ display: 'flex', gap: '20px' }}>
        <AppInstance />
        <AppInstance />
      </div>
    </div>
  );
};
```

--------------------------------

### Configuring SWC for mobx-keystone (JSON)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/installation.mdx

Configures SWC (`.swcrc`) to parse TypeScript or ECMAScript with decorator support for mobx-keystone. The `legacyDecorator` and `loose` options may need adjustment based on language and MobX version (5/6 or 4).

```json
{
  "jsc": {
    "parser": {
      "syntax": "typescript", // "ecmascript" if you use JavaScript
      "decorators": true
    },
    "transform": {
      // Optional if you use TypeScript
      // Required if you use JavaScript
      "legacyDecorator": true
    },
    // MobX 5/6
    "loose": false
    // MobX 4
    // "loose": true
  }
}
```

--------------------------------

### Configuring TypeScript Compiler for mobx-keystone (JSON)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/installation.mdx

Configures the TypeScript compiler (`tsconfig.json`) to support decorators and class properties required by mobx-keystone. Adjust `useDefineForClassFields` based on your MobX version (5/6 or 4).

```json
{
  // ...
  "compilerOptions": {
    // ...
    "experimentalDecorators": true,
    // MobX 5/6
    "useDefineForClassFields": true
    // MobX 4
    // "useDefineForClassFields": false
  }
}
```

--------------------------------

### Defining Literal Types in TypeScript

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/runtimeTypeChecking.mdx

This example demonstrates how to create types that match an exact primitive value using `types.literal`. It shows examples for both string and number literals.

```typescript
const hiType = types.literal("hi") // the string with value "hi"
const number5Type = types.literal(5) // the number with value 5
```

--------------------------------

### Defining a Mobx-Keystone Model

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/actionMiddlewares/undoMiddleware.mdx

Defines a simple 'Counter' model using Mobx-Keystone with a 'count' property and an 'add' action. This model serves as a basic example for demonstrating the application of the undo middleware.

```typescript
@model("MyApp/Counter")
class Counter extends Model({ count: prop(0) }) {
  @modelAction
  add(n: number) {
    this.count += n
  }
}

const counter = new Counter({})
```

--------------------------------

### Creating and Registering Root Store (MobX-Keystone, TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/rootStores.mdx

Shows how to create an instance of the 'RootStore' using the loaded 'UserPreferences' model instance. It then registers the root store using 'registerRootStore', which attaches the 'userPreferences' model to the root store tree, activating its 'onAttachedToRootStore' hook and starting the auto-save reaction.

```TypeScript
const myRootStore = new RootStore({ userPreferences: myPreferences })

// after this next function is called, `myPreferences` will become part of a root store
// and therefore start saving now and on changes
registerRootStore(myRootStore)
// the preferences get saved ...
```

--------------------------------

### Clone Example (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/snapshots.mdx

Shows a simple usage of the `clone` function to create a new instance (`clonedTodo`) that is a deep copy of an existing object (`todo`). By default, `clone` generates new model IDs for the cloned object and its children.

```ts
const clonedTodo = clone(todo)
```

--------------------------------

### Defining a Class Model (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/classModels.mdx

Demonstrates how to define a class model using the `@model` decorator and extending `Model`. It shows how to declare properties using `prop`, define actions with `@modelAction`, and create computed properties with `@computed`. Includes examples of required properties and optional properties with default values.

```TypeScript
// the model decorator marks this class as a model, an object with actions, etc.
// the string identifies this model type and must be unique across your whole application
@model("myCoolApp/Todo")
export class Todo extends Model({
  // here we define the type of the model data, which is observable and snapshotable
  // and also part of the required initialization data of the model

  // in this case we don't use runtime type checking
  text: prop<string>(), // a required string
  done: prop(false), // an optional boolean that will default to `false` when the input is `null` or `undefined`
  // if you want to make a property truly optional then use `x: prop<TYPE | undefined>()`

  // if we required runtime type checking we could do this
  // text: tProp(types.string),
  // done: tProp(types.boolean, false),
  // if you want to make a property truly optional then use `x: tProp(types.maybe(TYPE))`
}) {
  // the `modelAction` decorator marks the method as a model action, giving it access
  // to modify any model data and other superpowers such as action
  // middlewares, replication, etc.
  @modelAction
  setDone(done: boolean) {
    this.done = done
  }

  @modelAction
  setText(text: string) {
    this.text = text
  }

  @computed
  get asString() {
    return `${!this.done ? "TODO" : "DONE"} ${this.text}`
  }
}
```

--------------------------------

### Apply Snapshot Example (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/snapshots.mdx

Demonstrates how to use `applySnapshot` to update an existing object (`todo`) with data from a snapshot. This process reconciles the object's properties, ensuring only changed values trigger updates and reusing the existing instance if the model ID matches.

```ts
// given `todo` is a todo with `{ done: false, text: "buy some milk" }`

applySnapshot(todo, {
  done: true,
  text: "buy some milk",
  $modelType: todo.$modelType,
})
```

--------------------------------

### Getting Snapshot of MobX-Keystone Model Instance (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/snapshots.mdx

Demonstrates how to use getSnapshot to obtain an immutable representation of a mobx-keystone model instance. It shows the model definition, instance creation, and the resulting snapshot structure including the $modelType metadata.

```TypeScript
@model("myApp/Todo")
class Todo extends Model({
  done: prop(false),
  text: prop<string>()
}) {
}

const todo = new Todo({ text: "buy some milk" })

const todoSnapshot = getSnapshot(todo)

// this returns an object like
{
  done: false,
  text: "buy some milk",
  $modelType: "myApp/Todo"
}
```

--------------------------------

### Defining a Basic Model with Mobx-Keystone (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/sandboxes.mdx

Defines a simple `EvenNumber` model with a numeric `value` property and a computed property `isValid` to check if the value is even. This model is used as an example for the sandbox utility.

```TypeScript
@model("MyApp/EvenNumber")
class EvenNumber extends Model({
  value: prop<number>().withSetter(),
}) {
  @computed
  get isValid(): number {
    return value % 2 === 0
  }
}
```

--------------------------------

### Using fromSnapshotProcessor for Snapshot Transformation/Versioning with Mobx-Keystone - TypeScript

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/classModels.mdx

Explains how to use `fromSnapshotProcessor` to intercept and transform an incoming snapshot before it's used to create a model instance. The example shows handling different snapshot versions (`_version: 1` vs `_version: 2`) by splitting a `fullName` property into `firstName` and `lastName` for older versions.

```TypeScript
// we split it here so it is accessible to `FromSnapshotDefaultType<>`
const modelProps = {
  // in version 2 we split `fullName` into `firstName` and `lastName`
  _version: prop(2),
  firstName: prop<string>(),
  lastName: prop<string>()
}

@model("name")
class Name extends Model(modelProps, {
  fromSnapshotProcessor(
    sn: FromSnapshotDefaultType<typeof modelProps> | { _version: 1; fullName: string }
  ) {
    if (sn._version === 2) {
      return sn
    }

    const [firstName, lastName] = sn.fullName.split(" ")

    return {
      _version: 2,
      firstName,
      lastName
    }
  }
}) {
  // ...
}
```

--------------------------------

### Defining Nullable Types with types.maybeNull in TypeScript

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/runtimeTypeChecking.mdx

This example demonstrates how to create a type that accepts either a specified type or `null` using `types.maybeNull`. It's a convenient shorthand for `types.or(type, types.null)`.

```typescript
const numberOrNullType = types.maybeNull(types.number)
```

--------------------------------

### Defining Async Model Actions with @modelFlow

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/dataModels.mdx

Demonstrates how to create asynchronous model actions using the `@modelFlow` decorator. It shows both TypeScript (using `_async` and `this: THISCLASS`) and JavaScript (using `function*`) syntax for the generator function, and highlights the use of `yield* _await(X)` for awaiting promises. It also includes an example of how to call the async action.

```TypeScript
interface Book {
  title: string
  price: number
}

@model("myApp/BookStore")
class BookStore extends DataModel({
  books: prop<Book[]>(() => []),
}) {
  // TypeScript version

  @modelFlow
  // note: `_async` is a function that has to be imported, we have to use `this: THISCLASS`
  fetchMyBooksAsync = _async(function* (this: BookStore, token: string) {
    // we use `yield* _await(X)` where we would use `await X`
    // note: it is `yield*`, NOT just `yield`; `_await` is a function that has to be imported

    const myBooks = yield* _await(myBackendClient.getBooks(token))

    this.books = myBooks
  });
}
```

```JavaScript
// JavaScript version

@modelFlow
// we use `function*` (a function generator) where we would use `async`
*fetchMyBooksAsync(token) {
  // we use `yield* _await(X)` where we would use `await X`
  // note: it is `yield*`, NOT just `yield`; `_await` is a function that has to be imported

  const myBooks = yield* _await(myBackendClient.getBooks(token))

  this.books = myBooks
}
```

```JavaScript
// in either case it can be used like this
const myBookStore = new BookStore({})
await myBookStore.fetchMyBooksAsync("someToken")
```

--------------------------------

### Illustrating mobx-keystone Tree Rule 4 - Allowed Primitive Parent - TypeScript

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/treeLikeStructure.mdx

Shows an example where adding the same primitive value (`somePrimitive`) as a child to two different parent models (`someModel` and `someOtherModel`) is allowed because primitives are copied by value, creating distinct nodes in each tree.

```TypeScript
// given `someModel`, `someOtherModel`
const somePrimitive = "hi!"

// ok, the primitive is copied, and has now one parent
someModel.setPrimitive(somePrimitive)

// ok too, since the primitive is copied again, and has one parent
someOtherModel.setPrimitive(somePrimitive)
```

--------------------------------

### Defining a Model for Drafting - MobX-Keystone - TypeScript

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/drafts.mdx

This code defines a MobX-Keystone Model representing user preferences with properties and computed validation logic. This model serves as an example of the type of state structure that can be drafted for editing in a form, demonstrating a typical use case.

```TypeScript
@model("myApp/Preferences")
class Preferences extends Model({
  username: prop<string>().withSetter(),
  avatarUrl: prop<string>().withSetter(),
}) {
  // just as an example, some validation code
  @computed
  get usernameValidationError(): string | null {
    // ...
  }

  @computed
  get avatarUrlValidationError(): string | null {
    // ...
  }

  @computed
  get hasValidationErrors() {
    return !!(this.usernameValidationError || this.avatarUrlValidationError)
  }
}
```

--------------------------------

### Creating a Custom Property Transform in mobx-keystone (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/mapsSetsDates.mdx

Provides an example of how to define a custom property transform using the `ModelPropTransform` interface. It details the `transform` and `untransform` methods, explaining the parameters and their roles in converting between the original snapshot value and the transformed runtime value.

```TypeScript
// first we designate the transform, with the type
// `ModelPropTransform<TOriginalValue, TTransformedValue>`
const _timestampToDateTransform: ModelPropTransform<number, Date> = {
  transform({ originalValue, cachedTransformedValue, setOriginalValue }) {
    // `originalValue` is the original (number) value to transform

    // `cachedTransformedValue` is previously transformed value (`Date`) related
    // to that original value (if any)

    // `setOriginalValue` can be called in case we want to change the original value

    return cachedTransformedValue ?? new ImmutableDate(originalValue)
  },

  untransform({ transformedValue, cacheTransformedValue }) {
    // `transformedValue` is the transformed value (`Date`)

    // `cacheTransformedValue()` can be called if we want to save into the cache
    // that the current `transformedValue` can be cached and reused for that particular
    // original value

    if (transformedValue instanceof ImmutableDate) {
      cacheTransformedValue()
    }
    return +transformedValue
  }
}

// we need to export it as a function that returns the transform to keep TS happy
// whenever a generic is involed (e.g. see the source code of `arrayToSetTransform`)
// we will always return the same instance though instead of recreating it every time
export const timestampToDateTransform = () => _timestampToDateTransform
```

--------------------------------

### Using objectToMapTransform in mobx-keystone (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/mapsSetsDates.mdx

Illustrates the usage of `objectToMapTransform` to represent a Map as a plain object (`Record<string, V>`) in the snapshot. It shows defining the property, creating an instance with a Map, accessing the transformed Map and the original object representation, and getting the snapshot.

```TypeScript
@model(...)
class M extends Model({
  map: prop<Record<string, number>>().withTransform(objectToMapTransform())
}) {}

const m = new M({
  map: new Map(...)
})

m.map // `Map<string, number>`
m.$.map // `Record<string, number>`

getSnapshot(m) // `{ map: Record<string, number>, ... }`
```

--------------------------------

### Sharing Contextual Data via Root Store (MobX-Keystone, TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/rootStores.mdx

Presents a pattern for storing global, non-serializable contextual or environmental data directly on the root store. It shows how to add a property to the 'RootStore' model and how other models can access this data by getting a reference to the root store using 'getRootStore' or via the 'onAttachedToRootStore' hook.

```TypeScript
@model("myApp/RootStore")
class RootStore extends Model({...}) {
  myEnvData!: { ... }
}

const rootStore = new RootStore({...})
rootStore.myEnvData = { ... }
registerRootStore(rootStore)

// then on another model
class ... extends Model({ ... }) {
  // on some getter or method ...
  something() {
    const rootStore = getRootStore<RootStore>(someModel)
    const myEnvData = rootStore && rootStore.myEnvData
  }

  // or ...
  onAttachedToRootStore(rootStore) {
    const myEnvData = rootStore.myEnvData
  }
}
```

--------------------------------

### Wrapping Object Property with asMap in Mobx-keystone (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/mapsSetsDates.mdx

Demonstrates how to use the `asMap` wrapper to provide a `Map<string, V>` interface for a model property backed by a plain object (`{ [k: string]: V }`). Includes examples for a getter to access the wrapped map and a setter using `mapToObject` to update the underlying object.

```TypeScript
class ... {
  // given `myRecord: prop<{ [k: string]: V }>(() => ({}))`
  get myMap() {
    return asMap(this.myRecord)
  }

  // and if a setter is required
  @modelAction
  setMyMap(myMap: Map<string, V>) {
    this.myRecord = mapToObject(myMap)
  }
}
```

--------------------------------

### Defining a Model Property with ObjectMap in mobx-keystone (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/mapsSetsDates.mdx

Shows how to define a model property that uses the `ObjectMap` collection model. `ObjectMap` provides map-like functionality while being represented as a plain object in the snapshot. It includes examples for defining the property with or without a default value.

```TypeScript
class ... extends Model({
  myNumberMap: prop(() => objectMap<number>())
  // or if there's no default value
  myNumberMap: prop<ObjectMap<number>>()
}) {}
```

--------------------------------

### Wrapping Array Property with asMap in Mobx-keystone (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/mapsSetsDates.mdx

Shows how to use the `asMap` wrapper to provide a `Map<string, V>` interface for a model property backed by an array of key-value pairs (`[string, V][]`). Includes examples for a getter and a setter using `mapToArray`. Notes that `set` and `delete` operations will be slower due to array iteration.

```TypeScript
class ... {
  // given `myArrayMap: prop<[string, V][]>(() => [])`
  get myMap() {
    return asMap(this.myArrayMap)
  }

  // and if a setter is required
  @modelAction
  setMyMap(myMap: Map<string, V>) {
    this.myArrayMap = mapToArray(myMap)
  }
}
```

--------------------------------

### Defining ActionTrackingMiddleware Hooks in MobX-Keystone

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/actionMiddlewares/customMiddlewares.mdx

Describes the structure of the `ActionTrackingMiddleware` object used with `actionTrackingMiddleware`. It includes optional hooks for filtering actions and reacting to different stages of an action's lifecycle (start, resume, suspend, finish). The `onStart` and `onFinish` hooks can optionally return a value to override the action's result.

```TypeScript
interface ActionTrackingMiddleware {
  filter?(ctx: SimpleActionContext): boolean;
  onStart?(ctx: SimpleActionContext): void | ActionTrackingReturn;
  onResume?(ctx: SimpleActionContext): void;
  onSuspend?(ctx: SimpleActionContext): void;
  onFinish?(ctx: SimpleActionContext, ret: ActionTrackingReturn): void | ActionTrackingReturn;
}

interface ActionTrackingReturn {
  result: any; // Assuming ActionTackingResult type
  value: any;
}
```

--------------------------------

### Unit Testing MobX-Keystone Model with Context Override (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/contexts.mdx

This example shows how to unit test a model that depends on a context value. By using `usernameCtx.set(child, "RandomUsername")`, a specific context value is provided directly to the child instance, allowing it to be tested in isolation without needing a full parent tree structure.

```typescript
const child = new SomeDeepChild(...)
usernameCtx.set(child, "RandomUsername")
expect(child.someComputedThatRequiresUsername).toBe("RandomUsername is awesome!")
```

--------------------------------

### Saving Form Changes by Replacing Model (MobX-Keystone, TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/rootStores.mdx

Shows how to save the changes made to the cloned preferences model ('formPreferences') by replacing the original preferences object within the root store using the setter ('setUserPreferences'). This detaches the old object (stopping its reaction) and attaches the new one (starting its reaction and saving the changes).

```TypeScript
myRootStore.setUserPreferences(formPreferences)
```

--------------------------------

### Defining MobX-Keystone Context and Models (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/contexts.mdx

This snippet demonstrates how to create a context using `createContext`, how a parent model (`SomeParent`) provides a computed value to the context using `setComputed` in its `onInit` lifecycle hook, and how a child model (`SomeDeepChild`) consumes this context value in an action (`someActionThatRequiresUsername`) and a computed property (`someComputedThatRequiresUsername`) using `get`.

```typescript
const usernameCtx = createContext<string>()

@model("MyApp/SomeParent")
class SomeParent extends Model({
  username: prop<string>(),
  // ...
}) {
  onInit() {
    usernameCtx.setComputed(this, () => this.username)
  }
}

@model("MyApp/SomeDeepChild")
class SomeDeepChild extends Model({...}) {
  @modelAction
  someActionThatRequiresUsername() {
    const username = usernameCtx.get(this)
    // ...
  }

  @computed
  get someComputedThatRequiresUsername() {
    return usernameCtx.get(this) + " is awesome!"
  }
}
```

--------------------------------

### Wrapping Array Property with asSet in Mobx-keystone (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/mapsSetsDates.mdx

Illustrates how to use the `asSet` wrapper to provide a `Set<V>` interface for a model property backed by an array (`V[]`). Includes examples for a getter and a setter using `setToArray`. Notes that `delete` operations will be slower due to array iteration.

```TypeScript
class ... {
  // given `myArraySet: prop<V[]>(() => [])`
  get mySet() {
    return asSet(this.myArraySet)
  }

  // and if a setter is required
  @modelAction
  setMySet(mySet: Set<V>) {
    this.myArraySet = setToArray(mySet)
  }
}
```

--------------------------------

### Defining a Todo Data Model in MobX-Keystone (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/dataModels.mdx

This snippet demonstrates how to define a data model class named `Todo` using MobX-Keystone's `DataModel`. It shows how to declare properties like `text` and `done` using `prop`, including setting a default value for `done`. The example also includes defining model actions (`setDone`, `setText`) and a computed property (`asString`) using the respective decorators.

```TypeScript
// the model decorator marks this class as a model, an object with actions, etc.
// the string identifies this model type and must be unique across your whole application
@model("myCoolApp/Todo")
export class Todo extends DataModel({
  // here we define the type of the model data, which is observable and snapshotable
  // and also part of the required initialization data of the model

  // in this case we don't use runtime type checking
  text: prop<string>(), // a required string
  done: prop(false), // an optional boolean that will default to `false` when the input is `null` or `undefined`
  // if you want to make a property truly optional then use `x: prop<TYPE | undefined>()`

  // if we required runtime type checking we could do this
  // text: tProp(types.string),
  // done: tProp(types.boolean, false),
  // if you want to make an optional property then use `x: tProp(types.maybe(TYPE))`
}) {
  // the `modelAction` decorator marks the method as a model action, giving it access
  // to modify any model data and other superpowers such as action
  // middlewares, replication, etc.
  @modelAction
  setDone(done: boolean) {
    this.done = done
  }

  @modelAction
  setText(text: string) {
    this.text = text
  }

  @computed
  get asString() {
    return `${!this.done ? "TODO" : "DONE"} ${this.text}`
  }
}
```

--------------------------------

### Handling Instances in mobx-keystone (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/mstComparison.mdx

Illustrates the `mobx-keystone` method for defining model properties that expect instances. This approach simplifies assignments compared to `mobx-state-tree` as snapshots are primarily used with `getSnapshot` and `fromSnapshot`.

```TypeScript
@model("myApp/Todo")
class Todo extends Model({
  done: prop(false).withSetter(),
  text: prop<string>().withSetter(),
}) {}

@model("myApp/RootStore")
class RootStore extends Model({
  selected: prop<Todo | undefined>(undefined).withSetter(),
}) {}
```

--------------------------------

### Defining Item Interface in TypeScript

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/sandboxes.mdx

Defines the `Item` interface, which requires an optional `error` property of type string. This interface is implemented by all items stored in the `ItemStore` example.

```TypeScript
interface Item {
  error: string | undefined
}
```

--------------------------------

### Creating MobX-Keystone Data Model Instance (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/dataModels.mdx

Demonstrates how to create a new instance of a Todo data model using the `new` keyword. It shows how the constructor takes the initial data and how the wrapped data node is accessed via `.$`.

```TypeScript
const myTodo1 = new Todo({ done: true, text: "buy some milk" })
// `myTodo1.$` will hold the data object that can be inserted into a tree
```

--------------------------------

### Getting Children Objects in MobX-Keystone (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/treeLikeStructure.mdx

Returns an observable set containing all child objects (excluding primitives) of a given node. The search can be performed shallowly or deeply using the options parameter.

```typescript
getChildrenObjects(node: object, options?: { deep?: boolean }): ReadonlySet<object>
```

--------------------------------

### Getting Path Between mobx-keystone Nodes - getParentToChildPath Signature - TypeScript

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/treeLikeStructure.mdx

Provides the TypeScript signature for the `getParentToChildPath` function, which calculates the path from a given parent node to a specific child node within its tree.

```TypeScript
getParentToChildPath(fromParent: object, toChild: object): Path | undefined
```

--------------------------------

### Initializing ItemStore and Sandbox Context in TypeScript

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/sandboxes.mdx

Creates a new instance of `ItemStore` and a sandbox manager for it. It then sets the sandbox manager in the `sandboxCtx` context, associating it with the store instance. This allows methods like `canAddItem` to access the sandbox manager.

```TypeScript
const store = new ItemStore({})
const storeSandbox = sandbox(store)
sandboxCtx.setComputed(store, () => storeSandbox)
```

--------------------------------

### Creating a Model Instance and Sandbox (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/sandboxes.mdx

Creates an instance of the `EvenNumber` model and then creates a sandbox manager for that instance using the `sandbox` function. The sandbox manager allows testing changes without affecting the original instance.

```TypeScript
const num = new EvenNumber({ value: 0 })
const numSandbox = sandbox(num)
```

--------------------------------

### Loading User Preferences from Local Storage (MobX-Keystone, TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/rootStores.mdx

Demonstrates how to load a previously saved user preferences snapshot from local storage, parse it, and create a 'UserPreferences' model instance from the snapshot using 'fromSnapshot'. This instance is initially detached from any root store, allowing manipulation without triggering auto-save side effects.

```TypeScript
const myPreferencesObj = JSON.parse(localStorage.get("myPreferences"))

// this will create a `UserPrefernces` model instance, but won't save any changes yet
// since it is not yet part of a root store
// this means we can manipulate it without fear of overwriting the
// config in local storage
const myPreferences = fromSnapshot<UserPreferences>(myPreferencesObj)
```

--------------------------------

### Defining Union Types with types.or in TypeScript

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/runtimeTypeChecking.mdx

This example demonstrates how to create a type that can match any of several specified types using `types.or`. It shows a union type that accepts either a boolean or a number.

```typescript
const booleanOrNumberType = types.or(types.boolean, types.number)
```

--------------------------------

### Declaring Runtime Data in MobX-Keystone Models (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/classModels.mdx

Illustrates how to declare non-snapshotable runtime data within a MobX-Keystone class model. Shows examples of both non-observable properties and standard MobX observable properties with actions.

```TypeScript
@model("myApp/SomeModel")
class SomeModel extends Model({...}) {
  // non-observable runtime data
  x = 10;

  setX(x: number) {
    this.x = x
  }

  // or observable in the usual MobX way
  @observable
  y = 20;

  @action
  setY(y: number) {
    this.y = y
  }
}
```

--------------------------------

### Creating Class Model Instances (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/classModels.mdx

Shows how to create instances of a defined class model (`Todo`) by calling `new` with an object containing the initial property data. Illustrates how properties with default values can be omitted during instantiation.

```TypeScript
const myTodo1 = new Todo({ done: true, text: "buy some milk" })
// note how `done` can be skipped since it was declared with a default value
const myTodo2 = new Todo({ text: "buy some coffee" })
```

--------------------------------

### Adding First ItemA Instance and Checking Validity in TypeScript

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/sandboxes.mdx

Creates an instance of `ItemA`. It then uses `canAddItem` to check if this item can be added without errors (which should be true as it's the first `ItemA`). Finally, it adds the item and checks the store's errors array (which should be empty).

```TypeScript
const item1 = new ItemA({})
console.log(store.canAddItem(item1)) // => `true`
store.addItem(item1)
console.log(store.errors) // => `[]`
```

--------------------------------

### Resolving Path in MobX-Keystone (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/treeLikeStructure.mdx

Resolves a given path starting from a root object within the MobX-Keystone tree. It returns an object indicating whether the path was successfully resolved and the resulting value if found.

```typescript
resolvePath<T = any>(pathRootObject: object, path: Path): { resolved: true; value: T } | { resolved: false }
```

--------------------------------

### Creating a MobX-Keystone Patch Recorder (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/patches.mdx

This function creates a `PatchRecorder` instance for a target object, providing an abstraction over `onPatches` to manage recording and accessing patch events. It accepts optional configuration for initial recording state, patch filtering, and a callback for recorded patches.

```ts
patchRecorder(target: object, opts?: PatchRecorderOptions): PatchRecorder
```

```ts
const recorder = patchRecorder(todo, options)
```

--------------------------------

### Defining Array Types with types.array in TypeScript

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/runtimeTypeChecking.mdx

This example demonstrates how to create a type for an array where all elements must conform to a single specified type using `types.array`. It shows an array type that accepts only numbers.

```typescript
const numberArrayType = types.array(types.number)
```

--------------------------------

### Using withSandbox with Multiple Nodes (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/sandboxes.mdx

Creates an instance of the `NumberStore` model and its sandbox. It then uses `withSandbox` with an array containing two nested nodes (`store.a` and `store.b`), providing sandbox copies of both (`a` and `b`) to the callback function.

```TypeScript
const store = new NumberStore({
  a: new EvenNumber({ value: 0 }),
  b: new EvenNumber({ value: 2 }),
})

const storeSandbox = sandbox(store)
storeSandbox.withSandbox([store.a, store.b], (a, b) => {
  // ...
})
```

--------------------------------

### Handling Snapshots/Instances in mobx-state-tree (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/mstComparison.mdx

Shows the `mobx-state-tree` approach to assigning snapshots or instances to model properties. It highlights the need for union types (`SnapshotIn | Instance`) and the `cast` utility due to properties primarily expecting instances.

```TypeScript
const Todo = types
  .model({
    done: false,
    text: types.string,
  })
  .actions((self) => ({
    setText(text: string) {
      self.text = text
    },
    setDone(done: boolean) {
      self.done = done
    },
  })

const RootStore = types
  .model({
    selected: types.maybe(Todo),
  })
  .actions((self) => ({
    // note the usage of a union of the snapshot type and the instance type
    setSelected(todo: SnapshotIn<typeof Todo> | Instance<typeof Todo>) {
      // note the usage of cast to indicate that it is ok to use a snapshot when
      // the property actually expects an instance
      self.selected = cast(todo)
    },
  }))
```

--------------------------------

### Creating a Draft of a Model Instance - MobX-Keystone - TypeScript

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/drafts.mdx

This snippet demonstrates creating a draft specifically for an instance of the `Preferences` model obtained from a root store. This draft instance (`preferencesDraft`) provides the mutable `data` property and methods like `commit` and `reset` for managing changes.

```TypeScript
const preferencesDraft = draft(myRootStore.preferences)
```

--------------------------------

### Implementing Single Todo Selection with MobX-Keystone References (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/references.mdx

Defines MobX-Keystone models for Todo and TodoList, including rootRef and customRef definitions. Shows how to manage a single selected Todo using a reference (selectedRef) and how the reference automatically updates when the referenced object is removed from the list. Includes methods for selecting a todo and a computed property for accessing the selected todo.

```TypeScript
// we could use a root reference that makes use of `getRefId()` on models...
const todoRef = rootRef<Todo>("myApp/TodoRef", {
  // this works, but we will use `getRefId()` from the `Todo` class instead
  // getId(maybeTodo) {
  //   return maybeTodo instanceof Todo ? maybeTodo.id : undefined
  // },

  onResolvedValueChange(ref, newTodo, oldTodo) {
    if (oldTodo && !newTodo) {
      // if the todo value we were referencing disappeared then remove the reference
      // from its parent
      detach(ref)
    }
  },
})

// ... or a custom reference
const todoRef = customRef<Todo>("myApp/TodoRef", {
  // we could omit this since `getRefId()` is declared on the `Todo` class
  // getId(todo) {
  //   return todo.id
  // },

  resolve(ref) {
    // get the todo list where this ref is
    const todoList = findParent<TodoList>(ref, (n) => n instanceof TodoList)
    // if the ref is not yet attached then it cannot be resolved
    if (!todoList) return undefined
    // but if it is attached then try to find it
    return todoList.list.find((todo) => todo.id === ref.id)
  },

  onResolvedValueChange(ref, newTodo, oldTodo) {
    if (oldTodo && !newTodo) {
      // if the todo value we were referencing disappeared then remove the reference
      // from its parent
      detach(ref)
    }
  },
})

@model("myApp/Todo")
class Todo extends Model({
  id: prop<string>(),
  // ...
}) {
  getRefId() {
    // when `getId` is not specified in the custom reference it will use this as id
    return this.id
  }

  // ...
}

@model("myApp/TodoList")
class TodoList extends Model({
  list: prop<Todo[]>(() => []),
  selectedRef: prop<Ref<Todo> | undefined>(),
}) {
  // ...

  // not strictly needed, but neat
  @computed
  get selectedTodo() {
    return this.selectedRef ? this.selectedRef.current : undefined
  }

  @modelAction
  selectTodo(todo: Todo | undefined) {
    if (todo && !this.list.includes(todo)) throw new Error("unknown todo")

    this.selectedRef = todo ? todoRef(todo) : undefined
  }
}
```

--------------------------------

### Walking Tree in MobX-Keystone (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/treeLikeStructure.mdx

Traverses a tree starting from a target node, executing a predicate function for each visited node. The walk stops and returns the value if the predicate returns something other than undefined. The traversal mode (parent-first or children-first) can be specified.

```typescript
walkTree<T = void>(target: object, predicate: (node: any) => T | undefined, mode: WalkTreeMode): T | undefined
```

--------------------------------

### Illustrating mobx-keystone Tree Rule 1 - Disallowed Array Parent - TypeScript

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/treeLikeStructure.mdx

Shows an example where attempting to add the same array instance (`someArray`) as a child to two different parent models (`someModel` and `someOtherModel`) is not allowed because a non-primitive node can only have one parent.

```TypeScript
// given `someModel`, `someOtherModel`, `someArray`

// ok, `someArray` has now one parent and becomes a tree node object
someModel.setArray(someArray)

// but this would throw since `someArray` is already a tree node object which already has one parent
someOtherModel.setArray(someArray)
```

--------------------------------

### Calling an Async Model Flow

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/classModels.mdx

Shows how to instantiate a model containing an asynchronous flow and how to call the flow using `await`. This demonstrates the typical usage pattern for `@modelFlow` actions.

```js
// in either case it can be used like this
const myBookStore = new BookStore({})
await myBookStore.fetchMyBooksAsync("someToken")
```

--------------------------------

### Factory Pattern for Generic Models with prop

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/dataModels.mdx

Illustrates a factory function (`createModelClass`) that returns a `DataModel` class. This pattern allows creating models with generic properties (`TX`, `TY`) while still using `prop`, demonstrating how to instantiate and use these generated classes with different types (e.g., Number and String).

```TypeScript
function createModelClass<TX, TY>(modelName: string, initialX: TX, initialY: TY) {
  @model(`myApp/${modelName}`)
  class MyModel extends DataModel({
    x: prop<TX>(() => initialX),
    y: prop<TY>(() => initialY),
  }) {
    @modelAction
    setXY(x: TX, y: TY) {
      this.x = x
      this.y = y
    }
  }

  return MyModel
}

const NumberMyModel = createModelClass("NumberMyModel", 10, 20)
type NumberMyModel = InstanceType<typeof NumberMyModel>

const numberMyModelInstance = new NumberMyModel({}) // this will be of type `NumberMyModel`
numberMyModelInstance.setXY(50, 60)

const StringMyModel = createModelClass("StringMyModel", "10", "20")
type StringMyModel = InstanceType<typeof StringMyModel>

const stringMyModelInstance = new StringMyModel({}) // this will be of type`StringMyModel`
stringMyModelInstance.setXY("50", "60")
```

--------------------------------

### Defining a Model Property with ArraySet in mobx-keystone (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/mapsSetsDates.mdx

Demonstrates how to define a model property that uses the `ArraySet` collection model. `ArraySet` offers set-like functionality and is represented as an array in the snapshot. Examples for defining the property with or without a default value are provided.

```TypeScript
class ... extends Model({
  myNumberSet: prop(() => arraySet<number>())
  // or if there's no default value
  myNumberSet: prop<ArraySet<number>>()
}) {}
```

--------------------------------

### Using withSandbox to Test Changes (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/sandboxes.mdx

Demonstrates using the `withSandbox` method on the sandbox manager. It takes an array of nodes (here, the original `num` instance), provides a sandbox copy (`numCopy`) to the callback, modifies the copy, and returns an object indicating not to commit changes (`commit: false`) and returning the result of a computed property (`numCopy.isValid`).

```TypeScript
const isValid = numSandbox.withSandbox([num], (numCopy) => {
  numCopy.setValue(2)
  return { commit: false, return: numCopy.isValid }
})
```

--------------------------------

### Demonstrating Nested withSandbox Calls (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/sandboxes.mdx

Shows how `withSandbox` calls can be nested. The inner `withSandbox` call operates on a sandbox copy (`numCopy1`) obtained from the outer call. This allows for testing scenarios within scenarios.

```TypeScript
const isValid = numSandbox.withSandbox([num], (numCopy1) => {
  numCopy1.setValue(2)

  const isValid1 = numCopy1.isValid
  const isValid2 = numSandbox.withSandbox([numCopy1], (numCopy2) => {
    numCopy2.setValue(numCopy2.value * 2)
    return { commit: false, return: numCopy2.isValid }
  })

  return { commit: false, return: isValid1 && isValid2 }
})
```

--------------------------------

### Using toSnapshotProcessor for Snapshot Transformation with Mobx-Keystone - TypeScript

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/classModels.mdx

Explains how to use `toSnapshotProcessor` to modify the snapshot generated from a model instance before it's serialized. The example shows adding a derived `fullName` property to the output snapshot based on the `firstName` and `lastName` properties for backward compatibility.

```TypeScript
@model("name")
class Name extends Model(
  {
    firstName: prop<string>(),
    lastName: prop<string>()
  },
  {
    toSnapshotProcessor(sn, modelInstance) {
      // we want to also keep `fullName` for backwards compatibility
      return {
        ...sn,
        fullName: `${sn.firstName} ${sn.lastName}`
      }
    }
  }
) {
  // ...
}
```

--------------------------------

### Defining MobX-Keystone Patch Recorder Options Interface (TypeScript)

Source: https://github.com/xaviergonz/mobx-keystone/blob/master/apps/site/docs/patches.mdx

This TypeScript interface defines the configuration options available when creating a `PatchRecorder`. Options include setting the initial recording state, providing a filter function to selectively record patches, and specifying a callback to run after patches are recorded.

```ts
/**
 * Patch recorder options.
 */
export interface PatchRecorderOptions {
  /**
   * If the patch recorder is initially recording when created.
   */
  recording?: boolean

  /**
   * An optional callback filter to select wich patches to record/skip.
   * It will be executed before the event is added to the events list.
   *
   * @param patches Patches about to be recorded.
   * @param inversePatches Inverse patches about to be recorded.
   * @returns `true` to record the patch, `false` to skip it.
   */
  filter?(patches: Patch[], inversePatches: Patch[]): boolean

  /**
   * An optional callback run once a patch is recorded.
   * It will be executed after the event is added to the events list.
   *
   * @param patches Patches just recorded.
   * @param inversePatches Inverse patches just recorded.
   */
  onPatches?: OnPatchesListener
}
```
Tokens:
Raw