Refinement and validation - where are docs?

[OnkelTem]

I can't find anything on refinement or validation. Or rather - the existing API docs are no better than reading source code.
Are there any examples please?

For instance, I have a model like:

const productWeightModel = types.model({
  weight: types.union(
    types.model({
      net: types.number,
    }),
    types.model({
      gross: types.number,
      tareWeight: types.number,
    })
  ),
})

And I want to validate that weight.gross > weight.tareWeight.

How can I do that?

[coolsoftwaretyler]

Hey @OnkelTem - yeah sorry about the docs. Does this example help?

import { types } from "mobx-state-tree";

const GrossWeightModel = types.model({
  gross: types.number,
  tareWeight: types.number,
});

const NetWeightModel = types.model({
  net: types.number,
});

// Refinement to enforce `gross > tareWeight`
const ValidWeight = types.refinement(
  types.union(NetWeightModel, GrossWeightModel),
  (weight) => {
    if ("gross" in weight) {
      return weight.gross > weight.tareWeight;
    }
    return true; // Net weight model is always valid
  }
);

const ProductWeightModel = types.model({
  weight: ValidWeight,
});

const validProduct = ProductWeightModel.create({
  weight: { gross: 10, tareWeight: 5 },
});
// ✅ Works fine

const invalidProduct = ProductWeightModel.create({
  weight: { gross: 5, tareWeight: 10 },
});
// ❌ Throws an error: "Error while converting ... Gross weight must be greater than tare weight"

CodeSandbox

If you like that, I'd be happy to accept a PR to the docs site adding it. :)

[OnkelTem]

Thank you, studying...

[OnkelTem]

Thank you one more time, it's very insightful!

In my real app tare is an entity. I don't quite understand why it makes error here:

export const tareModel = types.model("Tare", {
  id: types.identifier,
  name: types.string,
  weight: types.number,
});

const GrossWeightModel = types.model({
  gross: types.number,
  tare: types.reference(tareModel),
});

const NetWeightModel = types.model({
  net: types.number,
});

// Refinement to enforce `gross > tareWeight`
const ValidWeight = types.refinement(
  types.union(NetWeightModel, GrossWeightModel),
  (weight) => {
    if ("gross" in weight) {
      return weight.gross > weight.tare.weight;
     // Error: Property 'weight' does not exist on type 'string | number'. 
     //        Property 'weight' does not exist on type 'string'.typescript(2339)
    }
    return true; // Net weight model is always valid
  }
);
...

Do you have an idea why it happens?

CodeSandbox

[OnkelTem]

I updated the sandbox and added more run-time things to get things actually created.

I added a store to get references work:

const storeModel = types
  .model({
    tares: types.array(tareModel),
    products: types.array(ProductWeightModel),
  })
  .actions((self) => ({
    addTare(tare: Instance<typeof tareModel>) {
      self.tares.push(tare);
    },
    addProduct(product: Instance<typeof ProductWeightModel>) {
      self.products.push(product);
    },
  }));

and finally I tried to instantiate a few models:

const store = storeModel.create();

store.addTare(
  tareModel.create({
    id: "1",
    name: "pot",
    weight: 400,
  })
);

store.addProduct(
  ProductWeightModel.create({
    weight: { gross: 10, tare: 1 },
  })
);

but the last thing made this error:

[mobx-state-tree] Error while converting `{"weight":{"gross":10,"tare":1}}` to `AnonymousModel`:
  at path "/weight" snapshot `{"gross":10,"tare":1}` is not assignable to type: `(AnonymousModel | AnonymousModel)` (Value does not respect the refinement predicate), expected an instance of `(AnonymousModel | AnonymousModel

I suspect that's because references are late guys. We can't use them in refinements or something.