Ts-matches NPM

Typescript Matches

Bundle Phobia

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.ts";
// 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.ts";
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 matchNone.unsafeCast> | 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

Attribute	Description
array	A parser of Parser<_, unknown[]> or @see arrayOf
arrayOf	Testing that any array is good and filled with type passed in
some	That one of the matchers pass
tuple	That we match a tuple of parsers
regex	That we match the passed in regex
number	Number
natural	Number > 0 and is integer
isFunction	is a function
object	is an object paser (Parser<_, object>) or @see shape
string	is a string
shape	Matches a shape of an object, `shape({key: parser}, ["key"], {"key": "fallbackValue"} as const)` for optionals default fallbacks,`shape({key: parser}, ["key"])` for optionals no defaults, `shape({key: parser})` for every required
partial	Matches a shape of maybe attributes
literal	Matches an exact match
every	Matches every match passed in
guard	Custom function for testing
any	is something
boolean	is a boolean
nill	is a null or undefined
dictionary	sets of parserForKey, parserForValue to validate a dictionary/ mapped type
recursive	A way of doing a recursive parser, passing the self. Note this requires the type before while creating, cannot go from creation side.
deferred	A way of creating a type that we will be filling in later, will be using the typescript shape first to verify
literals	One the literals passed through

MatcherChain api

Attribute	Description
when	Create a matching case, when match return value
defaultTo	Fall through case, ensures all are caught
defaultToLazy	Fall through case, ensures all are caught in lazy fashion
unwrap	This assumes that all cases are matched (TS tries to throw errors for this)

Parser api

Attribute	Description
parse	Use this to turn a value into an either
usafeCast	Use this to get the value or throw an error
castPromise	Cast into a promise
optional	output type is now a null of value
defaultTo	instead of creating a optional we fallback to a value
refine	we want to add more tests to value, could change type to sub
validate	we want to add more tests to value
errorMessage	If validation would create an error, return error as string, else void
test	A guard for the type, returns true if type is valid (as a `x is type`)
rename	Set to a new name for the parser

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.