SafeAny provides a type-safe alternative to TypeScript any. It enforces a complete type test.

We first explain why we need an alternative to TypeScript any type. Then we introduce how to use SafeAny.

Type any was introduced in TypeScript for gradual typing. In particular to progressively type an existing JavaScript project.

In a pure TypeScript project, any is only used to bypass the compiler. By using any you tell the compiler to keep away and to blindly trust you.

For instance, the following code compiles with strict null checks:

const x: any = null
const fullname = x.fullname

Object | null | undefined provides a type-safe replacement in most of the cases where any is involved.

However, this latter type does not allow to structurally test an object.

The following code is invalid:

const x: Object | null | undefined = ...
if (x !== null && typeof x === "object") {
    if (typeof x.fullname === "string") {
        //> error: Property 'fullname' does not exist
    }
}

A compiler-compliant alternative could be:

const x: Object | null | undefined = ...
if (x !== null && typeof x === "object") {
    const y: {fullname?: Object | null} = x as {fullname?: Object | null}

    if (typeof y.fullname === "string") {
        const fullname = y.fullname
    }
}

This is a simple test. Imagine a test over a complex object structure with nested objects... Futhermore, the test is error-prone. If you forget to null-check x, the compiler does not blame you since there is a type-assertion. Is that really better than any? I guess no.

SafeAny provides a way to defensively test whether an object is valid, without any type-assertion or compiler tricks.

If you wish to test if an object x is structurally equivalent to an object of type T, then x must be typed as SafeAny<T>. You can assign everyting to x.

As an example assume that we receive a well-formed json string. The sender claims that the json string represents a Person. The following sample enables to test its claim:

type Person = {fullname: string, birthYear: number}

const x: SafeAny<Person> = JSON.parse(untrustedJson)
if (typeof x === "object" && x !== null &&
   typeof x.fullname === "string" && typeof x.birthYear === "number") {

   // x is a Person
}

More examples are available here.

If you use SafeAny in at least one exported interface, you have to place this package as production dependency.

npm install safe-any

In contrast, if SafeAny is only internally used, you can place this package as a dev dependency.

npm install --save-dev safe-any

If T1 and T2 have at least one common property name, then a source of type SafeAny<T1 | T2> is assignable to a target of type SafeAny<T1> or SafeAny<T2>.