Cast as Trophy"> Cast as Trophy

Build the type guards you want for the supported types you can! And enjoy your compile time errors when you forget to keeping something up to date! ;)

The rules of the supported types:

No.	Rule	Example
1.	Objects with string, number or boolean properties	{ s: string }
2.	Supported objects can be embedded	{ i: { s: string } }
3.	Arrays can be used for the supported types and objects	{ ia: Array<{ s: string }> }
4.	The supported types and objects can be optional with null and / or undefined	{ iau: Array<{ s: string }> \| undefined }

The library is not optimized for performance. And it is built for TypeScript (with strictNullChecks option turned on).

How to start?

You can install the library with NPM:

npm i --save cast-as-trophy

And create a caster for a not too complex object type:

import { createCaster } from "cast-as-trophy";

interface Example {
    s: string; // You need to call `addString("s")`
    n: number; // You need to call `addNumber("n")`
    b: boolean; // You need to call `addBoolean("b")`
}

const exampleCaster = createCaster<Example>()
    .addString("s") // Needed because of `s: string`
    .addNumber("n") // Needed because of `n: number`
    .addBoolean("b") // Needed because of `b: boolean`
    .build();

And check some values:

const test: unknown = {
    s: "test",
    n: 42,
    b: true,
};

if (exampleCaster.isType(test)) {
    // The `test` is type guarded! It has the proper type here.
    console.log(`Value of s: ${test.s}`);
}

How to use a caster?

1. isType<TYPE>(value: unknown) => value is TYPE

A simple old fashion type guard.

Input	Value to check
Result	Whether the value has the proper type (boolean, but the type guard way)
Exception	No

Example:

import { createCaster } from "cast-as-trophy";

interface Example {
    s: string;
}

const caster = createCaster<Example>().addString("s").build();

const myLittleObject: unknown = { s: "test" };

if (caster.isType(myLittleObject)) {
    // The type of the `myLittleObject` is now known.
    console.log(myLittleObject.s);
}

2. castTo<TYPE>(value: unknown) => TYPE

Returns the same object but with the narrowed type. (Throws error when the type of the input is not okay.)

Input	Value to convert
Result	Same value but with the narrowed type
Exception	When the type of the value is wrong

Example:

import { createCaster } from "cast-as-trophy";

interface Example {
    s: string;
}

const caster = createCaster<Example>().addString("s").build();

try {
    const value: Example = caster.castTo({ s: "test", n: 42 });
    // You can use `s` in the result, but there is no `n`
    console.log(`Value of s: ${value.s}`);
} catch {
    // Things can go wrong.
}

Warning:

• The returned object can contain additional values

3. copyTo<TYPE>(value: unknown) => TYPE

Returns a copy of checked part of the input with the narrowed type. (Throws error when the type of the input is not okay.)

Input	Value to convert
Result	Copy of input
Exception	When the type of the value is wrong

Example:

import { createCaster } from "cast-as-trophy";

interface Example {
    s: string;
}

const caster = createCaster<Example>().addString("s").build();

try {
    const value: Example = caster.copyTo({ s: "test", n: 42 });
    // You can use `s` in the result, but there is no `n`
    console.log(`Value of s: ${value.s}`);
} catch {
    // Things can go wrong.
}

Warning:

• The returned copy only contains the checked props (and nothing else)
• Creating a copy costs extra memory usage and CPU time (can cause possible performance issues)

4. asyncCastTo<TYPE>(value: unknown) => Promise<TYPE>

The asynchronous version of the castTo(...) method. It does the same but with promises. Can be useful if you work with large object and don't want to block your app.

Input	Value to convert
Result	Copy of the value with the checked type (a promise)
Exception	When the type of the value is wrong (in a promise like way)

Example:

import { createCaster } from "cast-as-trophy";

interface Example {
    s: string;
}

const caster = createCaster<Example>().addString("s").build();

function doAsyncStuffs(): Promise<void> {
    try {
        const value = await caster.asyncCastTo({ s: "test" });
        console.log(`Value of s: ${value.s}`);
    } catch {
        // Don't forget: error can be thrown...
    }
}

Warning:

• This method returns the same value but with the narrowed type, just like the original castTo(...)
• There can be a lot of async calls in the background which can cause performance issues too

5. asyncCopyTo<TYPE>(value: unknown) => Promise<TYPE>

The asynchronous version of the copyTo(...) method. It does the same but with promises. Can be useful if you work with large object and don't want to block your app.

Input	Value to convert
Result	Copy of the checked part of the input value with the checked type (a promise)
Exception	When the type of the value is wrong (in a promise like way)

Example:

import { createCaster } from "cast-as-trophy";

interface Example {
    s: string;
}

const caster = createCaster<Example>().addString("s").build();

function doAsyncStuffs(): Promise<void> {
    try {
        const value = await caster.asyncCopyTo({ s: "test" });
        console.log(`Value of s: ${value.s}`);
    } catch {
        // Don't forget: error can be thrown...
    }
}

Warning:

• This method creates a copy of the checked part of the input, just like the original copyTo(...)
• There can be a lot of async calls in the background which can cause performance issues too

Missing features on the casters

Async type guards and async assertions are not supported in TypeScript. (At least not yet. As far as I know.) So implementing a features like asyncIsType is unfortunatelly not an option.

How to build a caster?

You can do this with 3 easy steps:

1. Call the createCaster<...>(...) function with the proper generic type
2. Call the addXYZ(...) methods on the returned value.
3. Call the build() at the end of the process.

Example:

import { createCaster } from "cast-as-trophy";

interface Example {
    s: string;
    n: number;
    b: boolean;
}

const exampleCaster = createCaster<Example>().addString("s").addNumber("n").addBoolean("b").build();

Notes:

• The best way to build a caster is this kind of call chain you can see in the example
• The order of the addXYZ(...) methods is not important. Just be sure you called all of them!
• You can only call the build() method after you did all the necessary calls to add your props to the caster builder. Before that the build() will simply not be available. (If there is a property s: string and you haven't added yet then you need to add an addString("s") before you can call the build().)
• You will get compile errors related to never for the keys when you try to use the wrong addXYZ(...) method for a property.

Basic types

Methods to add a basic types (the input parameter is the key of the given property):

Method	Supported type
addString(KEY)	string
addNumber(KEY)	number
addBoolean(KEY)	boolean

Example:

import { createCaster } from "cast-as-trophy";

interface Example {
    s: string;
    n: number;
    b: boolean;
}

const result = createCaster<Example>().addString("s").addNumber("n").addBoolean("b").build();

Embedded

You can use the addCustom(..., ...) method to add a previously created caster for a given property. This means that you can embed the objects and the casters) into each other. The second parameter of the function is the caster you already have. (The first one is the key, as usual.)

Method	Supported type
addCustom(KEY, CASTER)	The embedded object type with a builded caster

Example:

import { createCaster } from "cast-as-trophy";

interface Inner {
    s: string;
}

interface Outer {
    i: Inner;
}

const innerCaster = createCaster<Inner>().addString("s").build();

const outerCaster = createCaster<Outer>().addCustom("i", innerCaster).build();

Arrays

You can use arrays of string, number, boolean and embedded objects of these. (Or object of object of these. And so on.)

Method	Supported type
addStringArray(KEY)	Array<string>
addNumberArray(KEY)	Array<number>
addBooleanArray(KEY)	Array<boolean>
addCustomArray(KEY, CASTER)	Array of the embedded object type with a builded caster

Example:

import { createCaster } from "cast-as-trophy";

interface Inner {
    sa: string[];
    na: number[];
    ba: boolean[];
}

interface Outer {
    ia: Inner[];
}

const innerCaster = createCaster<Inner>().addStringArray("sa").addNumberArray("na").addBooleanArray("ba").build();

const outerCaster = createCaster<Outer>().addCustomArray("ia", innerCaster).build();

Optional (null and undefined)

At last but not least you can make the previous types optional with null and / or undefined

Method	Supported type
addStringOrUndefined(KEY)	string \| undefined
addNumberOrUndefined(KEY)	number \| undefined
addBooleanOrUndefined(KEY)	boolean \| undefined
addCustomOrUndefined(KEY)	EmbeddedType \| undefined
addStringArrayOrUndefined(KEY)	Array<string> \| undefined
addNumberArrayOrUndefined(KEY)	Array<number> \| undefined
addBooleanArrayOrUndefined(KEY)	Array<boolean> \| undefined
addCustomArrayOrUndefined(KEY, CASTER)	Array<EmbeddedType> \| undefined
addStringOrNull(KEY)	string \| null
addNumberOrNull(KEY)	number \| null
addBooleanOrNull(KEY)	boolean \| null
addCustomOrNull(KEY)	EmbeddedType \| null
addStringArrayOrNull(KEY)	Array<string> \| null
addNumberArrayOrNull(KEY)	Array<number> \| null
addBooleanArrayOrNull(KEY)	Array<boolean> \| null
addCustomArrayOrNull(KEY, CASTER)	Array<EmbeddedType> \| null
addStringOrNullOrUndefined(KEY)	string \| null \| undefined
addNumberOrNullOrUndefined(KEY)	number \| null \| undefined
addBooleanOrNullOrUndefined(KEY)	boolean \| null \| undefined
addCustomOrNullOrUndefined(KEY)	EmbeddedType \| null \| undefined
addStringArrayOrNullOrUndefined(KEY)	Array<string> \| null \| undefined
addNumberArrayOrNullOrUndefined(KEY)	Array<number> \| null \| undefined
addBooleanArrayOrNullOrUndefined(KEY)	Array<boolean> \| null \| undefined
addCustomArrayOrNullOrUndefined(KEY, CASTER)	Array<EmbeddedType> \| null \| undefined

Example:

import { createCaster } from "cast-as-trophy";

interface Example {
    su: string | undefined;
    nn: number | null;
    bnu: boolean | null | undefined;
}

const result = createCaster<Example>()
    .addStringOrUndefined("su")
    .addNumberOrNull("nn")
    .addBooleanOrNullOrUndefined("bnu")
    .build();

Not supported features for the caster builders

Union types are not supported

Except null and undefined, you can make other types optional with them.

You can not use something like this: string | number | boolean.

Array of arrays is not supported

Only the first level of arrays is available.

Array of unions is not supported

You can not use unions of types in the arrays. So Array<string | number> is not supported. (The Array<string | undefined> is not supported too.)

Tuples are not supported

You can't use tuples like [string] or [number, number]. Only arrays are supported, like this: string[].

Pure undefined and null are not supported

You can not use pure undefined or null for a property. And you can not use undefined[] and null[] array types either.

Index types are not supported

You can not use index types.

Using other exotic types like functions, symbols, etc. are not supported

You can not build caster for object with exotic types in it. (Including unknown and never.)

Using custom type guards are not supported

You can not embed your custom type guards.

Alternatives

If this library is not flexible enough for you then a good alternative can be the https://www.npmjs.com/package/ts-looks-like package.