Nimble Package Maestros

    typed
    TypeScript icon, indicating that this package has built-in type declarations

    4.1.2 • Public • Published

    NPM Codecov npm bundle size GitHub issues npm Libraries.io SourceRank

    typed

    typed is yet another runtime type checking library for JavaScript / TypeScript. It is heavily inspired by superstruct and zod, but it focuses on being lightweight (1kb gzipped), fast, and easy to use.

    Installation

    npm install typed

    Usage

    import * as t from "typed";
    
    const post = t.object({
      id: t.number(),
      title: t.string(),
    });
    
    const postList = t.array(post);
    
    // Get the actual type of the postList
    type PostList = t.Infer<typeof postList>;
    
    // Some json data from somewhere
    const data = {} as any;
    
    const result = postList(data);
    
    if (result.ok) {
      // Do something with the data
      result.data;
    } else {
      // Handle the error
      result.error;
    }
    
    // Or you can just unwrap the value directly. It will throw if the data is invalid.
    const parsed = t.unwrap(result);
    
    // Or if you don't want it to throw, you can use `unwrapOr`
    const parsed = t.unwrapOr(result, {
      /* a default value */
    });

    Fetch example

    One of the more common use cases for including a library like this one is to validate data from a remote API.

    import * as t from "typed";
    
    const post = t.object({
      id: t.number(),
      title: t.string(),
    });
    
    const postList = t.array(post);
    
    // If everything goes ok, posts will be correctly typed as `Post[]`.
    // If not, an error will be thrown.
    const posts = await fetch("https://jsonplaceholder.typicode.com/posts")
      .then((res) => res.json())
      .then(postList)
      .then(t.unwrap);

    Custom Types

    There's a chance you'll want to define more complex types to deal with your data. You can do this in a few ways:

    • Using the map function.
    • Using the chain function.
    • Creating a struct from scratch.

    Using the map function

    The map function allows you to convert one "base" type into another. It always starts from a base type.

    import * as t from "typed";
    
    // Suppose we have this geolocation struct.
    const latLng = t.object({
      lat: t.number(),
      lng: t.number(),
    });
    
    // `asNumber` means we can pass a string and it will be converted to a number.
    const latLngPair = t.tuple([t.asNumber(), t.asNumber()]);
    
    // And we'd like to have a type that takes a string a returns a `LatLng`.
    const asLatLng = t.map(t.string(), (str) => {
      // Here `str` is guaranteed to be a string.
    
      // Here we validate our splited string against a tuple of two numbers.
      const result = latLngPair(str.split(","));
    
      // If it succeeds we return a `LatLng` struct. If not, forwards the error.
      return t.isOk(result) ? latLng(result.data) : result;
    });
    
    // Now we can use `asLatLng` to validate a string.
    const str = "42.123,42.123";
    
    const result = asLatLng(str); // `result` will be a `LatLng` struct.

    Using the chain function

    The chain function is useful when you don't want to change the type of your data, but further process it.

    For example, if you have a string that you want to trim and lowercase it, then chain is the function you want to use.

    import * as t from "typed";
    
    const trim = (value: string) => value.trim();
    const lower = (value: string) => value.toLowerCase();
    
    const trimLower = t.chain(
      t.string(),
      trim,
      lower /* whatever else function you want as longs as it at takes the same type and returns the same type */,
    );
    
    const result = trimLower("  Hello World  "); // { ok: true, value: "hello world" }

    Creating a struct from scratch

    A struct is nothing more than a function that takes whatever input and returns a Result. The convention in typed is to have factory functions that return a struct just to be able to customize error messages. This was not the case in previous versions of typed, but it is now.

    import * as t from "typed";
    
    const regex =
      (regex: RegExp, msg = "Expecting value to match regex"): t.Struct<string> =>
      (input) => {
        if (typeof input !== "string" || !regex.test(input)) {
          return t.err(new t.StructError(msg, { input }));
        }
        return t.ok(input);
      };

    You can browse the typed source code to see how structs are implemented if you're curious.

    Notes

    typed will deep clone non primitive values as it validates them. So if you pass an object or array to a struct, it will be cloned. This is to say that typed will get rid of any extra properties on your data, so it'll exactly match the shape you defined.

    Benchmarks

    A quick benchmark comparing typed with superstruct and zod:

    $ npm run benchmark
    
    zod x 19,588 ops/sec ±0.25% (94 runs sampled)
    superstruct x 6,398 ops/sec ±0.32% (98 runs sampled)
    typed x 91,797 ops/sec ±0.08% (99 runs sampled)
    Fastest is typed

    The data used in the benchmarks is from SpaceX's GraphQL API.

    Install

    npm i typed

    DownloadsWeekly Downloads

    177

    Version

    4.1.2

    License

    MIT

    Unpacked Size

    27.5 kB

    Total Files

    27

    Last publish

    Collaborators

    • brielov