twilio-sdk-type-validator

Twilio SDK Type Validator

Provides runtime type validation functionality for class methods and functions.

Usage

Most of the time, using a decorator is the most convenient way to apply type checking to a class method:

import { validateTypesAsync } from "twilio-sdk-type-validator";

class TestClass {
  @validateTypes("number")
  someMethod(value) {
    console.log(`value is a number: ${value}`);
  }
}

Or if it is an async method, you could use an async version of the decorator, in which case the type error will be thrown as a rejected promise:

import { validateTypesAsync } from "twilio-sdk-type-validator";

class TestClass {
  @validateTypesAsync("number")
  async someMethod(value) {
    console.log(`value is a number: ${value}`);
  }
}

Each argument passed into the decorator should be a valid rule that corresponds to the respective argument of the method being decorated. If an argument requires more than one check, you can pass an array of rules which will get applied following the OR logic:

import { validateTypesAsync } from "twilio-sdk-type-validator";

class TestClass {
  @validateTypes(["number", "string"])
  someMethod(value) {
    console.log(`value is either a number or a string: ${value}`);
  }

  @validateTypes("string", ["number", "boolean"])
  someOtherMethod(value, secondValue) {
    console.log(`value is a string: ${value}`);
    console.log(`secondValue is either a number or a boolean: ${secondValue}`);
  }
}

For functions outside of classes, you can utilize runtimeTypeValidation function instead. It accepts two arguments, first being the array of rules (each element of the array corresponding to a rule (or an array of rules) for a respective argument), with the second being the arguments to validate.

Here's an example of the two methods from previous example rewritten using the runtimeTypeValidation function:

import { runtimeTypeValidation } from "twilio-sdk-type-validator";

function someFunction(value) {
  runtimeTypeValidation(["number"], [value]);

  console.log(`value is a number: ${value}`);
}

function someOtherFunction(value, secondValue) {
  runtimeTypeValidation(
    ["string", ["number", "boolean"]],
    [value, secondValue]
  );

  console.log(`value is a string: ${value}`);
  console.log(`secondValue is either a number or a boolean: ${secondValue}`);
}

Rules

Type validator comes with a few prebuilt rules. They come in two shapes: rule factories and rule constants.

Rule factories are functions which generate an object describing the validation rule. Every single rule factory accepts one or multiple arguments. If multiple arguments are passed, then they will be applied following the OR logic. The rule factory objectSchema is an exception. The rule factories are:

• type
• literal
• custom
• objectSchema

Rule constants are pre-made rule objects which don't require any parameters. The rule constants are:

• nonEmptyString
• nonNegativeInteger
• pureObject

type

Validates against either a primitive type (typeof x) or a constructor function (instanceof x).

Note

Using the type rule factory itself could be omitted if a string representing a primitive type or a constructor function is passed as a rule itself.

Examples

Single primitive type

@validateTypes(type("number"))
// OR
@validateTypes("number")

Multiple primitive types for the same argument

@validateTypes(["number", "string"])
// OR
@validateTypes(type("number", "string"))
// OR
@validateTypes([type("number"), type("string")])

Single constructor function (class)

@validateTypes(FormData)

Multiple constructor functions (classes) for the same argument

@validateTypes([FormData, Blob])
// OR
@validateTypes(type(FormData, Blob))
// OR
@validateTypes([type(FormData), type(Blob)])

literal

Validates against a literal value (compared using the strict equality operator ===).

Examples

Single literal

@validateTypes(literal("foobar"))

Multiple literals for the same argument

@validateTypes(literal("foobar", 15))
// OR
@validateTypes([literal("foobar"), literal(15)])

custom

Validates against a custom rule. The custom rule is represented as a function that returns a tuple of type [boolean, string] where the boolean is whether the check has passed and the string is the description of the rule. The value to validate gets passed as the first argument.

Examples

Validate that a number is greater than 15

@validateTypes(
  custom((value) => [
    typeof value === "number" && value > 15,
    "a number greater than 15",
  ])
)

nonEmptyString

Validates a non-empty string.

Example

@validateTypes(nonEmptyString)

nonNegativeInteger

Validates a non-negative integer. I.E., it should contain no decimal point and be greater than or equal to 0.

Example

@validateTypes(nonNegativeInteger)

pureObject

Validates an object that is not null and is not an array.

Example

@validateTypes(pureObject)

objectSchema

Validates an object against a schema. The first argument is a short description of the object (which will appear in runtime type errors) with the second argument being the schema itself. The rule will validates every key of the schema object against a rule (or a set of rules) defined as values.

Examples

A simple object schema

@validateTypes(
  objectSchema("network configuration", {
    port: "number",
    protocol: literal("http", "https"),
    retries: custom((value) => [
      typeof value === "number" && value > 0 && value < 16,
      "a value between 0 (exclusive) and 15 (inclusive)"
    ])
  })
)

A nested object schema

@validateTypes(
  objectSchema("root object", {
    foo: ["boolean", "number"],
    bar: objectSchema("child object", {
      baz: "number",
    }),
  })
)