What is the difference between optional and maybe, Instance, SnapshopIn and Out?

[OnkelTem]

I have the following type:

type Foo = {
  name: string
  height?: number
}

and I want to create objects of that type: {name: 'A'}, {name: 'B', height: 123}.

In addition, I would want to get some default for Foo's height, like 0.

But currently I can't get anything of that working, and here is why.

Example 1

import { Instance, types } from 'mobx-state-tree'

type Foo = {
  name: string
  height?: number
}

const FooModel1 = types.model('Foo', {
  name: types.string,
  height: types.optional(types.number, 0),
})

type FooType1 = Instance<typeof FooModel1>

const foo1: FooType1 = {
  name: 'John',
}
/* ERROR:
Type '{ name: string; }' is not assignable to type 'ModelInstanceTypeProps<{ name: ISimpleType<string>; height: IOptionalIType<ISimpleType<number>, [undefined]>; }> & IStateTreeNode<...>'.
  Property 'height' is missing in type '{ name: string; }' but required in type 'ModelInstanceTypeProps<{ name: ISimpleType<string>; height: IOptionalIType<ISimpleType<number>, [undefined]>; }>'.(2322)
*/

The height prop was declared as optional, and yet FooType1 requires it. What is the point of its optionality then?

Now let's switch to maybe:

Example 2

import { Instance, types } from 'mobx-state-tree'

type Foo = {
  name: string
  height?: number
}

const FooModel2 = types.model('Foo', {
  name: types.string,
  height: types.maybe(types.number),
})

type FooType2 = Instance<typeof FooModel2>

const foo2_1: FooType2 = {
  name: 'John',
}
/* ERROR:
Type '{ name: string; }' is not assignable to type 'ModelInstanceTypeProps<{ name: ISimpleType<string>; height: IMaybe<ISimpleType<number>>; }> & IStateTreeNode<IModelType<{ name: ISimpleType<string>; height: IMaybe<...>; }, {}, _NotCustomized, _NotCustomized>>'.
  Property 'height' is missing in type '{ name: string; }' but required in type 'ModelInstanceTypeProps<{ name: ISimpleType<string>; height: IMaybe<ISimpleType<number>>; }>'.(2322)
*/

const foo2_2: FooType2 = {
  name: 'John',
  height: undefined
}

So I still can't create {name: 'John'} and have to pass height, even if it is undefined. In addition, with maybe I'm losing the fallback value of 0.

Any clues?

Maybe I should use SnapshotIn/Out somehow?

[thegedge]

First, I'll cover the three main types for MST models:

• SnapshotIn is the input type needed by MyModelType.create to construct an instance
• Instance is an instance of an MST type. You can usually assign an MST instance into an interface with simple javascript types, but a plain old javascript object (POJO) usually can't be assigned to an MST instance type (as you noticed, and we'll discuss below).
• SnapshotOut the type of getSnapshot(instance)

Second, here's what the docs say about optional types:

types.optional(type, defaultValue, optionalValues?) marks a value as being optional (in e.g. a model). If a value is not provided/undefined (or set to any of the primitive values passed as an optional optionalValues array) the defaultValue will be used instead. If defaultValue is a function, it will be evaluated. This can be used to generate, for example, IDs or timestamps upon creation.

A bit implicit, but the optionality is on the input, not the instance/output. This means that SnapshotIn<typeof FooModel1> would be the same as your Foo interface. Instance<typeof FooModel1> removes the optionality of height though, since we either get a number in the input, or we set it to 0.

So that's for the first part. The second part is maybe. I'll take some of the code you mentioned and post it here:

const foo2_1: FooType2 = {
  name: 'John',
}
/* ERROR:
Type '{ name: string; }' is not assignable to type 'ModelInstanceTypeProps<{ name: ISimpleType<string>; height: IMaybe<ISimpleType<number>>; }> & IStateTreeNode<IModelType<{ name: ISimpleType<string>; height: IMaybe<...>; }, {}, _NotCustomized, _NotCustomized>>'.
  Property 'height' is missing in type '{ name: string; }' but required in type 'ModelInstanceTypeProps<{ name: ISimpleType<string>; height: IMaybe<ISimpleType<number>>; }>'.(2322)
*/

const foo2_2: FooType2 = {
  name: 'John',
  height: undefined
}

So the problem here is that you're trying to coerce a POJO into an instance of FooModel2. POJOs are different from MST instances. You might be able to do some weird things to make the types happy, but we've generally constructed the Instancetype to make that difficult, because it's almost always a mistake! The MST instance in your second example can be assigned to the Foo interface from your first code snippet though, because it does have all of those properties.

I believe foo2_1 and foo2_2 would match SnapshotIn<typeof FooModel2>. I can't recall if they would match SnapshotOut<typeof FooModel2> though, because I'm fairly certain even with types.maybe the keys aren't optional (in other words, we always set the keys for getSnapshot(instance), even if they weren't included in the input).

Let me know if you have any more questions, and whether or not there's something you think we could do to make all of this clearer.

[coolsoftwaretyler]

Thanks for the really detailed response @thegedge. I'm going to mark this as the answer since it's accurate and thorough, but @OnkelTem, please don't let that discourage you from asking any follow-ups. :)