DEV Community: Shane Osbourne

Typescript and JSDoc, shared names for Types + Values

Shane Osbourne — Mon, 18 Sep 2023 21:05:58 +0000

(written by a human, no AI content)

I saw this pattern recently, taking advantage of the fact that Typescript doesn't mind if you re-use the same name for a value and a type.

import * as z from "zod"

// Define a schema
export const User = z.object({
    name: z.string()
})

// export an inferred type for use elsewhere
// but, using the same name, `User` 🤯
export type User = z.infer<typeof User>

So we have...

export const User ...
export type User...

... it might seem odd, but Typescript is more than happy with this - after all, types and values are distinct! So, providing that you're happy with any potential confusion in the future , it's a pattern you can use right away!

Why would you though? Well, it might make more sense in the context of a consumer - consider the following in a separate module:

import { User } from "./zod"

function signIn(user: User) {
    console.log(user);
}

Here we have a single import: User. We know the module exports both a type and a value with that name - but when seen in type parameter position like this, Typescript will just use the type User without issue. A naming 'collision' just doesn't occur.

In that very same file, we could also do:

// same file, different context
const parsed = User.safeParse({ name: "Shane" })

which is nice - because now we're just in regular JavaScript territory here, using the value called User. Typescript understands that we're not in a type position, so everything 'just works' and we didn't need to think of a separate name for it, like UserSchema or similar. 🥰

JSDoc

All of the examples above were in Typescript - but if you're using JSDoc this works almost identically.

First, instead of exporting both of these...

export const User ...
export type User ...

we'll need to replace the second one - since export type ... is only supported in Typescript.

To do this, albeit in a less-than-ideal way, we can use a @typedef

import * as z from "zod"

export const User = z.object({
    name: z.string()
})

/**
 * @typedef {import("zod").infer<typeof User>} User
 */

Using infer from Zod, we're achieving the exact same inference as we did in Typescript - it's just that it's inside a comment this time instead!🥹.

@typedef isn't ideal for all situations (for another time...), but in this case it has exactly the effect we're looking for.

Considering a consumer in JS, as we did with the Typescript example, it would look like this:

import { User } from "./jsdoc-zod";

/**
 * @param {User} user
 */
function signIn(user) {
    console.log(user);
}

Again, note we're only importing User - which is both a type and a value in the other module. Typescript still has no issue understanding that within a @param block, we are referring to the type and not the value.

That means the previous "in the same file" example works just as it did before, presented here as a single snippet:

import { User } from "./jsdoc-zod";

/**
 * @param {User} user - works as expected in type position 🥰
 */
function signIn(user) {
    console.log(user);
}

// works as expected as a value too 🥰
const parsed = User.safeParse({ name: "shane" })

Conclusion

It's becoming table-stakes for any schema parsing library like Zod to support rich type inference. Having types derived from runtime validation code is a powerful pattern, one that I can see growing in popularity.

This post highlights how you can use a single name for a value and a type - and how it can be done in JSDoc along with Typescript.

Cancel a Promise when using XState

Shane Osbourne — Sun, 23 Aug 2020 21:06:36 +0000

Skip to the code: Cancelling Promises with XState and a comparison with Observables

tl;dr - if you want or need cancellation in side-effecting code that uses promises, you're going to need to roll your own solution.

Ideally with XState you'd want to tie the teardown of a service to a transition, like

{
   loading: {
      on: { CANCEL: 'idle' },
      invoke: { src: "loadData", onDone: "loaded" }
   }
}

where moving to the idle state would naturally tear-down the invoked service.

But that's actually not the case when using Promise-based APIs since by design they don't contain any notion of 'clean up' or 'tear down' logic.

{
   services: {
       loadData: () => {
          /** 
           * Oops! a memory-leak awaits if this does 
           * not complete within 2 seconds - eg: if we 
           * transition to another state
           */
          return new Promise((resolve) => {
              setTimeout(() => resolve({name: "shane"}), 2000);
          })
       }
   }
}

Solution

If you absolutely must use promises in your application, you'll want to forward a CANCEL message to your service, and then it can reply with CANCELLED when it's done running any tear-down logic.

{
  id: 'data-fetcher',
  initial: 'loading',
  strict: true,
  context: {
    data: undefined,
    error: undefined,
  },
  states: {
    loading: {
      on: {
        /** Allow the running service to see a `CANCEL` message */
        CANCEL: { actions: forwardTo('loadDataService') },
        CANCELLED: { target: 'idle' }
      },
      invoke: {
        src: 'loadDataService',
        onDone: {
          target: 'loaded',
          actions: ['assignData'],
        },
        onError: {
          target: 'idle',
          actions: ['assignError'],
        },
      },
    },
    idle: {
      on: { LOAD: 'loading' },
    },
    loaded: {
      on: { LOAD: 'loading' },
    },
  },
}

And now we can just cancel an in-flight setTimeout call to show how you'd receive that message inside your service.

{
  services: {
    'loadDataService': () => (send, receive) => {
      let int;
      // 1: listen for the incoming `CANCEL` event that we forwarded
      receive((evt) => {
        if (int && evt.type === 'CANCEL') {
          // 2: Perform the 'clean up' or 'tear down'
          clearTimeout(int);
          // 3: Now let the machine know we're finished
          send({ type: 'CANCELLED' });
        }
      });

      // Just a fake 3-second delay on a service.
      // DO NOT return the promise, or this technique will not work
      let p = new Promise((resolve) => {
        int = setTimeout(() => {
          resolve({ name: 'shane'});
        }, 3000);
      })

      // consume some data, sending it back to signal that
      // the service is complete (if not cancelled before)
      p.then((d) => send(doneInvoke('loadUserService', d)));
    },
  },
  actions: {
    clearAll: assign({ data: undefined, error: undefined }),
    assignData: assign({ data: (ctx, evt) => evt.data }),
    assignError: assign({ error: (ctx, evt) => evt.data.message }),
  },
}

Just use Observables, if you can

Since the Observable interface encapsulates the idea of tearing-down resources, you can simply transition out of the state that invoked the service.

Bonus: the entire machine is just simpler overall too:

export const observableDataMachine = Machine(
  {
    id: 'data-fetcher',
    initial: 'loading',
    strict: true,
    context: {
      data: undefined,
      error: undefined,
    },
    states: {
      loading: {
        entry: ['clearAll'],
        on: {
          // this transition alone is enough
          CANCEL: 'idle',
        },
        invoke: {
          src: 'loadDataService',
          onDone: {
            target: 'loaded',
            actions: 'assignData',
          },
          onError: {
            target: 'idle',
            actions: ['assignError'],
          },
        },
      },
      idle: {
        on: { LOAD: 'loading' },
      },
      loaded: {
        on: { LOAD: 'loading' },
      },
    },
  },
  {
    services: {
      'loadDataService': () => {
        return timer(3000).pipe(mapTo(doneInvoke(SERVICE_NAME, { name: 'shane' })));
      },
    },
    actions: {
      clearAll: assign({ data: undefined, error: undefined }),
      assignData: assign({ data: (ctx, evt) => evt.data }),
      assignError: assign({ error: (ctx, evt) => evt.data.message }),
    },
  },
);

Type `Assertions` vs `Declarations` - the dangers of `as` in Typescript

Shane Osbourne — Sun, 10 May 2020 19:47:10 +0000

Since this has caught me out a number of time recently, I decided it's time to add another resource to any future search results :)

/**
 * Let's say you're declaring the 'shape' of messages
 * that your application can accept in a union like so...
 */
type Msg =
    | { kind: "sign-in"; email: string; password: string }
    | { kind: "sign-out" };

Type 'Assertions'

The dangerous kind. Typescript allows the following snippet and does not warn us that the email and password fields are absent.

It's very easy to imagine the bugs introduced later when handling a sign-in message and expecting email and password to exist.

/**
 * Ooops! These `As Expressions` force Typescript to believe *us* that
 * `msg1` & `msg2` are members of the `Msg` union above. 
 */
const msg1 = { kind: "sign-in" } as Msg;
const msg2 = <Msg>{ kind: "sign-in" };

So, even though { kind: "sign-in" } is NOT actually a valid Msg - it only could be if the email & password were also present - that doesn't stop Typescript from allowing it in any future place that accepts Msg.

This means that when you attempt to narrow the Msg union later - such as in a switch statement - you could run into errors when you expect email and password to actually exist.

Use with caution, and only when you think you know more than
Typescript (see: hardly ever 🤣)

Type 'Declarations'

The safer way. Use this instead when you want Typescript to actually error when the element in question does not satify the type exactly.

/**
 * Better! Typescript will warn us here that `msg3` is invalid.
 * Adding the `email` and `password` fields would remove the error 😀
 */
const msg3: Msg = { kind: "sign-in" }; // Error!

2 ways to create a Union from an Array in Typescript

Shane Osbourne — Fri, 27 Dec 2019 21:09:37 +0000

Let's say we have a simple interface used to describe an object.

interface Person {
    name: string;
    age: number;
    address: string;
};

// This is a valid 'Person' since the object contains all of the
// keys from the interface above and the types allline up.
const person: Person = {name: "shane", age: 21, address: "England"}

Sometimes though, we may need to derive a NEW interface based on the old one, but restricted to certain keys.

We often do this in API responses when limiting the data that's returned.

As a simple example, let's look at how to create a new interface with only the name & age fields from the Person interface.

Deriving a new type

Of course in such a simple example with only 3 fields, we can and probably should just make a new interface like this:

interface Person2 {
    name: string;
    age: number;
};

But as we all know, interfaces get much, much larger in real codebases - so we really want to re-use the name and age fields & their types.

One way to do this would be to pick the fields you want to keep

type Person2 = Pick<Person, "name" | "age">

This gives us exactly what we wanted from above, since Pick uses the elements of the "name" | "age" union to create a new mapped type. It's the same as if we wrote the following manually:

type Person2 = {[K in "name" | "age"]: Person[K]}

The really important part here being that we're deriving a new type, rather than hard-coding a new one. That means subsequent changes to the underlying Person interface will be reflected throughout our codebase.

For example, if the user property changes in Person to be an object rather than a string - that change would propagate through to our new Person2 type.

Mapped types are pretty amazing

As you can probably tell from above, deriving new types from existing ones is an extremely powerful concept - one you'll end up using more and more as you increase your Typescript knowledge.

Now, looking back at the code samples above, what would happen if you wanted to replace the union "name" | "age" with a dynamic array instead?

You can imagine a function that takes an array of keys as strings, and returns an object with only those keys present.

// Here's the goal: we want Typescript
// to know that `p` here is not only a subset of `Person`
// but also it ONLY contains the keys "name" & "age"
const p = getPerson(["name", "age"]);

The first approach might be to accept string[] for the fields, and then return a Partial<Person>

function getPerson(fields: string[]): Partial<Person> {
   // implementation omitted for brevity
   return {} as any;
}

There are 2 main problems with this:

The fields argument can contain ANY strings here, but we want to narrow that to only allow keys from the Person interface.
The return type of Partial<Person> loses type information as it makes all fields optional.

Hard-code it first

To understand how to solve both of those problems, let's rewrite the function signature to include exactly the types we wanted in our example.

function getPerson(fields: ("name" | "age")[]): Pick<Person, "name" | "age"> {
   // implementation omitted for brevity
   return {} as any;
}

Although it's becoming a bit of a token-soup now, looking at the fields argument first you can see that it's not string[] that we want (since that type include EVERY string) it's actually just "an array of keys that exist in person".

This is all about understanding how Typescript can create & consume union types & how to combine them with Array types.

// This is a "union" of 3 string literals
type KeyUnion = ("name" | "age" | "person");

// This is an Array type, where it's elements are 
// restricted to those that are found in the union 
// "name" | "age" | "person"
type KeyArray = ("name" | "age" | "person")[];

// Sometimes it's easier to understand in this style
type KeyArray = Array<"name" | "age" | "person">;

// Finally you can substitute the strings for the
// type alias created above
type Keys = KeyUnion[]

That's a good primer on some basic union/array types - those bits are required to understand why the next bit will work.

Now though, we want to avoid the hard-coded string literals altogether.

It would be extremely tedious to have to maintain a list of strings that refer to keys on an interface and luckily Typescript has plenty of convenience types to help us here.

// Before: hard-coded keys
type KeyUnion = ("name" | "age" | "person");

// After: a 'derived' union type based on 
// the Person interface
type KeyUnion = keyof Person;

Whilst those 2 are equivalent, it's clear which is the best to use. So, applying this piece back to our function, we get the following:

function getPerson(fields: (keyof Person)[]): Pick<Person, keyof Person> {
   // implementation omitted for brevity
   return {} as any;
}

Not there yet.

This DOES provide type safety for the function call site - you won't be able to call getPerson with a key that doesn't exist in the interface any more.

// Type 'string' is not assignable to type '"name" | "age" | "address"'
getPerson(["name", "age", "location"])

Above, TS correctly prevents this, since the 3rd element in the array is not a valid key on Person.

But, the return type is now off.

If we return to mapped types for a moment, we'll easily see why <Pick, keyof Person> is not what we want here.

// this creates a new type with ALL the keys in Person
Pick<Person, keyof Person>

// it's exactly the same as this, it's a 1:1 mapping
{[K in keyof Person]: Person[K]}

// Or, for even more clarity (not valid typescript though), it's like doing this
{[for K in "name" | "age" | "person"]: Person[K]}

So now it's clear, we do still want Pick, but we need to create a union type based on the array of keys passed in - essentially we need the following...

const keys = ["name"]
// -> should produce Pick<Person, "name">

const keys = ["name", "age"]
// -> should produce Pick<Person, "name" | "age">

const keys = ["name", "age", "address"]
// -> should produce Pick<Person, "name" | "age" | "address">

First way to create a union from an array

As a standalone example, providing we give a type assertion like this, we can easily get a union of string literals from the following:

const keys: (keyof Person)[] = ["name", "age"]

By restricting the type with (keyof Person)[] (rather than just string[]) it means that we can ask Typescript nicely to derive a union from this.

// creates the union ("name" | "age")
type Keys = typeof keys[number]

It turns out that using typeof keys[number] on any array will force Typescript to produce a union of all possible types within.

In our case, since we indicated that our array can only contain keys from an interface, Typescript uses this information to give us the union we need.

For clarity, the following would NOT work

const keys = ["name", "age"]

// only creates the union `string` since there's no 
// type assertion after `keys` 
type Keys = typeof keys[number]

Second way to create a union from an array

Union types in Typescript really are the key to unlocking so many advanced use-cases that it's always worth exploring ways to work with them.

To complete our function from above, we'll actually be going with the first example, but it's worth knowing this other trick in case you come across a similar situation.

const assertions

Using a relatively new feature, you can instruct TS to view arrays (and other types) as literal (and readonly) types.

You see, Typescript infers that the keys variable below has the type string[] which is technically correct, but for our use-case, it means that valuable information is lost if we create a union from it.

// to TS, this is just `string[]`...
const keys = ["name", "age"];

// ... which means this union 
// type ends up with just `string`, 
// which includes every single string ever :(
type Keys = typeof keys[number];

But, with a const assertion, we get a very different result. You're basically telling Typescript to not allow widening of any literal types.

So "name" stays as "name", and not string - which means, if we circle back to the previous example, we can now ask Typescript to create a union of all elements.

// now, TS thinks this is `readonly ["name", "age"]`
const keys = ["name", "age"] as const;

// this is now the union we wanted, "name" | "age"
type Keys = typeof keys[number];

Finishing the implementation

Finally, let's put the knowledge to work.

To recap, we wanted to use Typescript to annotate a function such that when we call the function with an array of strings, it validates that the strings all match key names on an interface, and then use those dynamic values to create a narrowed return type derived from the original interface.

// only accept keys from `Person`
// then use them to narrow a new type. 
function getPerson<T extends (keyof Person)[]> (fields: T): Pick<Person, T[number]> {
   // implementation omitted for brevity
   return {} as any;
}