Typescript Matches

Living Documentation https://runkit.com/blu-j/ts-matches

Uses

• Schema Validation (parsers: like matches.string)
• Schema Switching
• Pattern matching
• Switches as expressions

Related Libs

• https://github.com/Blu-J/ts-matches-json-schema/ A library to be able to serialize + deserialize the types from json schema <-> ts-matches

Tech Used

Wiki Pattern Matching

Also useful for casting and boundary verifications. So using this as a json validator. The benefit comes that the parser becomes a validator, also the types are given back to typescript, where something like ajv cannot do or alot of validators.

Examples

The easiest and most useful feature is using the matcher as a validation. Here I want to validate that the shape is correct or throw an error

import matches from "https://deno.land/x/ts_matches/mod";
// could also use matches.shape here as well
const goldFishMatcher = matches.object({
  type: t.literal("gold-fish"),
  position: t.tuple(t.number, t.number),
  age: t.natural,
  name: t.string,
});
// For this example I'm making the shape less known
const input: object = {
  type: "gold-fish",
  position: [2, 3],
  age: 5,
  name: "Nemo",
};
// The matcher will know that the type returned is always the correct shape, and the type will reflect that
const checkedInput = goldFishMatcher.unsafeCast(input);

A variation is to use the guard version.

import matches from "ts-matches";
const goldFishMatcher = matches.object({
  type: t.literal("gold-fish"),
  position: t.tuple(t.number, t.number),
  age: t.natural,
  name: t.string,
});
// For this example I'm making the shape less known
const input: object = {
  type: "gold-fish",
  position: [2, 3],
  age: 5,
  name: "Nemo",
};
if (!goldFishMatcher.test(input)) {
  return;
}
/// After this point typescript will know the shape will be intersecting the shape we defined in the matcher

This is useful on a boundary layer, like fetching a value. In that case we have no idea what the shape is, so we should do a check on that.

import matches from "https://deno.land/x/ts_matches/mod";
fetch("fishes.com/gold-fishes/12")
  .then((x) => x.json())
  .then(
    matches.object({
      type: t.literal("gold-fish"),
      position: t.tuple(t.number, t.number),
      age: t.natural,
      name: t.string,
    }).unsafeCast
  );

And when we get the value out it will either be the type that we want, or it will throw an error. The other use case is a pattern matching.

import matches from "matches";
const getText = (x: unknown): string =>
  matches(x)
    .when(matches.string, (value) => `Found string: ${value}`)
    .when(matches.number, (value) => `Found number + 1: ${value + 1}`)
    .defaultTo("no found type yet");

And here we can use the type checking and what do in that case. With destructuring, lots of abilities are there

import matches from "matches";
const matchNone = matches.tuple(matches.literal("none"));
const matchSome = matches.tuple(matches.literal("some"), matches.any);
type option = ReturnType | typeof matchSome._TYPE;
const matchInteger = matches.every(
  matchSome,
  matches.tuple(matches.any, matches.number)
);
const testValue = ["some", 3];
const currentValue = matches(testValue)
  .when(matchNone, () => 0)
  .when(matchInteger, ([, value]) => value + 1)
  .when(matchSome, () => 0)
  .defaultTo(0);

We can also use the matches to match on literals, or return literals

import matches from "matches";
const currentValue = matches("5" as const)
  .when("5", "6", "At 5 or 6")
  .unwrap(0);

API

Given that the default export is matches Then the type of matches is unkown -> matcherChain, and also has the properties on that function that return a parser or a function that creates a parser

MatcherChain api

Parser api

Parser.parserErrorAsString ( validationError: parserError ): string This is the exposed transform of the parserError to a string. Override this if you want to make the errors different.

And of of any matcher we two functions, refine and unsafe cast. Refine is useful when we want to check a condition, like is even. And the matcher is also a function which creates an either of our value as well.

Deploying

Use the npm version minor | major and push the tags up, Then publish via npm