Types Roadmap

[devanshj]

• Provide a hack-free safe degraded version of types. Because the currect depend on some likely typescript non-guarantees that might break, So if some users would like to trade safety over precise types and developer experience they can use that version. And we can also be less worried of making workarounds because we have already warned "Hey this might break" :P
  Two ways of going about this -

  • @cassionzen/usestatemachine/safe (temporary name)

  • declare module "@cassionzen/usestatemachine" {
      interface TypeOptions {
        safe: true
      }
    }

    Alternative names to "safe" - workaroundFree, hackFree,
    Current workarounds - InferNarrowestObject which is almost same as this and Definition.FromTypeParameter (TODO: document what's happening here)

  For milestone v1.0.0

• Support guard's that are actually typed as type guards. Meaning this should work -

  const eventHasFoo = (state: { event: { foo?: string | undefined  } }): state is { event: { foo: string } } =>
    typeof state.event.foo !== "undefined"
  // I always wanted to publish a library provides authoring predicates that infer guards, which I might :P
  // Meaning with that library the above can be replaced by something like
  // let eventHasFoo = P.doesHave("event.foo", P.isNotUndefined)
  // and if they write it in the machine itself (which they should) they'd also get completions and errors via contextual inferrence.
  
  useStateMachine({
    schema: { events: { X: t<{ foo?: string | undefined }> } },
    initial: "a",
    states: {
      a: { on: { X: { target: "b", gaurd: eventHasFoo } },
      b: {
        effect: ({ event }) => {
          let x: string = event.foo
          // without `gaurd: eventHasFoo` foo would have been `string | undefined`
        }
      }
    }
  })

  It's great the signature is ({ context, event }) => ... instead of (context, event) => ... like xstate, because latter is principally incorrect and consequently has some cons

  For milestone v1.1.0

• Provide (probably opt-in) linting

  • noInitialToDeadStateNodes

    // needs to be written once per (tsconfig) project
    declare module "@cassionzen/usestatemachine" {
      interface TypeOptions {
        noInitialToDeadStateNodes: true
      }
    }
    
    useStateMachine({
      initial: "b", // Error(noInitialToDeadStateNodes): "b" is a dead state node
      states: {
        a: { on: { X: "b" } },
        b: {}
      }
    })

  • noNonExhaustiveEventsSchema -

    useStateMachine({
      schema: {
        events: { // Error(noNonExhaustiveEventsSchema): `$$exhaustive` not set to `true`
          X: t<{ foo: string }>()
        }
      }
    })

  • noSchemalessDefintion

    useStateMachine({ // Error(noSchemalessDefintion): `schema` is not set
      initial: "a",
      states: { a: {} }
    })

  • more? I don't use state machines so I'm not sure what else we could come up with haha

  For milestone v1.2.0

• more?

[devanshj]

@cassiozen I want to provide a safe version in v1.0.0 itself. Which one of the two options you like? And what should we name it? "safe" is very ambiguous.

[cassiozen]

What if we flip? We make "safe" the default version and create an "edge" version form more experienced/adventurous users?

[cassiozen]

more?

We need nested states - hierarchical/recursive states are the next big feature I want to add.

[devanshj]

What if we flip? We make "safe" the default version and create an "edge" version form more experienced/adventurous users?

We could do that but the problem is that these features to the users are not "edge" but really basic and beginner-friendly, for TypeScript it's "edge".

What I mean when I say "really basic and beginner-friendly"? Example -

useStateMachine({
  schema: { events: { X: t<{ a: number }>(), Y: t<{ a: number }>(), Z: t<{ b: number }>() } },
  initial: "a",
  states: {
    a: { on: { X: "c" } },
    b: { on: { Z: "a" } },
    c: {
      entry: ({ event }) => {
        let x = event.a
        // event here is narrowed down to { type: "X", a: number } | { type: "Y", a: number }
      }
    }
  },
  on: { Y: "c" }
})

It's only because of txstate-like types we can do that narrowing, with the "safe" version beginners would go "Umm why does it not allow accessing property a in event, the compiler says it could not be present there? The compiler says the event can be { type: "Z", b: number } but that's not true!". Here they are right and the types are wrong. In fact only experienced users will be able to deal with "safe" version because they'd be more confident than the compiler.

So my suggestion would be to not flip it.

[devanshj]

We need nested states - hierarchical/recursive states are the next big feature I want to add.

Yep sure. The "more?" was only for more linter rules haha. Will add another top-level more xD

Also I'm thinking of this roadmap to only include typelevel features meaning once we have runtime hierarchical states it's obvious the types will have to support that. So it's not a "type-level" feature but rather a "runtime-level" feature

[devanshj]

@davidkpiano @Andarist Yall should keep an eye on what I'm doing here :P because all these things would eventually come to txstate too ;)

[cassiozen]

The "more?" was only for more linter rules haha

I think these lint rules already go a long way. I can't think of any others. The "more" that I referred to was for the 1.2.0 release (or later) 😁

So it's not a "type-level" feature but rather a "runtime-level" feature

Very true. The types need to support that, and I'll work on the "runtime" code.

[cassiozen]

Regarding the "safe" version: I'm having an internal debate about it. My initial thought is that it would be confusing for a beginner to understand why a "safe" version exists.

As an exercise: What's the worst that can happen? A new version of TypeScript breaks useStateMachine?

[devanshj]

What's the worst that can happen? A new version of TypeScript breaks useStateMachine?

Yep that. Or to be precise, the users using useStateMachine would have their builds failing when they upgrade TypeScript. And the worst is this happens and we don't have any workarounds to commit and publish a new version of useStateMachine.

In that case the users would have to switch to safe version (and maybe we'll have to make edge same as safe and publish) and the existing code will have to be edited with assertions. We could provide a few helpers that make it a little easier. So they'd have to do something like...

effect: ({ event }) => {
  let x = (event as XEvent | YEvent).a
}

Or with helpers...

effect: ({ event }) => {
  assertEventType(event, ["X", "Y"])
  let x = event.a
}

In theory one could write a codemod for this but would be quite a task :P

Edit: Rethinking about the codemod thing - I think it could be actually be a thing we can provide that edits your edge code to make you able to degrade to safe, in that case users would use edge version with confidence as they'd know the codemod has their back. Wdyt? Is this something worth exploring?

[cassiozen]

Let's go with the safe version then. Let's call it "boring"?
As in "@cassionzen/usestatemachine/boring"

[devanshj]

Ahahaha xD well... It's kinda better than safe at least, but sounds way too informal to me. Maybe "lite-typed" or something like that?

Other options that come to mind (will keep editing): imprecise-types, imprecisely-typed, meagerly-typed, degraded-types, safe-types, hackfree-types

[cassiozen]

I think "light-typed" is the best we could come up with

[devanshj]

Sounds good. We can always change it last minute if we come up with something better ;)

How about lightly-typed tho? light-typed feel grammatically incorrect to say. Or even light-types would work. And how about "lite" instead of "light", I think the former is more popular? (mobx-react-lite, caniuse-lite come to mind)

[cassiozen]

I don't really care if it's "lite" or "light" - both works for me.

lightly-typed sounds good.

[devanshj]

I think I like "lite-types" more. Wanna go with that or "lightly-typed"? I don't have a strong preference tho, just lightly-typed has more syllables :P

But then I think lite-types in not an adjective argh xD idk anymore whatever works for me