ts-predicates

A set of functions that ensure type safety both during typechecking AND during runtime.

Examples

``
lang=ts
const a = {} as Record;
const b = { number: "2" } as Record;
const c = { number: 2 } as Record;

if (hasFieldOfType("number", predicates.number, a)) {
a.number + 1;
console.log("A has a number prop");
}else{
a.number +1; // typescript error
}

if (hasFieldOfType("number", predicates.number, b)) {
b.number + 1;
console.log("B has a number prop");
}

if (hasFieldOfType("number", predicates.number, c)) {
c.number + 1;
console.log("C has a number prop");
}
console.log("utils finished");
`

You can test multiple fields at once:

`
lang=ts
const a = {};
if (
!hasShape(
{
string: predicates.string,
undefined: predicates.undefined,
},
a
)
) {
throw new Error("wrong shape!");
}
`

You can infer object type from its shape:

`
lang=ts
const shape = {
text: predicates.string,
number: predicates.number,
} as const;

type the_shape = ShapeToType
`

Dealing with nested/recursive types

In order to use recursive shapes/types, a little bit of syntax overhead is necessary.

Let's assume an example where we have a list of json objects. Some of them are
images, and some of them are containers. Containers can contain other containers
and images. For runtime type safety this would be enough:

`
lang=ts
const ImagePrimitiveShape = {
type: predicates.const("image"),
src: predicates.string,
};

type ImagePrimitiveType = ShapeToType;

type BlockPrimitiveType = {
type: "block";
content: Primitive[];
};

const BlockPrimitiveShape = {
type: predicates.const("block"),
content: predicates.lazy(() =>
predicates.array(
predicates.or(
predicates.shape(ImagePrimitiveShape),
predicates.shape(BlockPrimitiveShape)
)
)
),
};

type Primitive = ImagePrimitiveType | BlockPrimitiveType;
`

But, this would throw a compile error:

`
typescript [7022]: 'BlockPrimitiveShape' implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer.
`

In order to fix the compile error, we need to make the BlockPrimitiveShape
const a little bit more verbose by manually specifying the type of the shape:

`
lang=ts
const BlockPrimitiveShape: {
readonly type: ConstPredicate<"block">;
readonly content: LazyPredicate<
(BlockPrimitiveType | ImagePrimitiveType)[]
>;
} = {
type: predicates.const("block"),
content: predicates.lazy(() =>
predicates.array(
predicates.or(
predicates.shape(ImagePrimitiveShape),
predicates.shape(BlockPrimitiveShape)
)
)
),
};
`

This results in a shapes+types combo than can check recursive types both at compile- and runtime:

`
lang=ts
if (hasShape(BlockPrimitiveShape, input)) {
input.type; // "block"
const element = input.content[0];
element.type; // "image" | "block"
if (element.type === "block") {
element.content; // Primitive[]
const nested_element = element.content[0];
nested_element.type; // "block" | "image"
}
}
``