/mod.ts | unknownutil@v3.12.0

import * as unknownutil from "https://deno.land/x/unknownutil@v3.12.0/mod.ts";

A utility pack for handling unknown type.

Usage

It provides is module for type predicate functions and assert, ensure, and maybe helper functions.

is*

Type predicate function is a function which returns true if a given value is expected type. For example, isString (or is.String) returns true if a given value is string.

import { is } from "https://deno.land/x/unknownutil@v3.12.0/mod.ts";

const a: unknown = "Hello";
if (is.String(a)) {
  // 'a' is 'string' in this block
}

Additionally, is*Of (or is.*Of) functions return type predicate functions to predicate types of x more precisely like:

import {
  is,
  PredicateType,
} from "https://deno.land/x/unknownutil@v3.12.0/mod.ts";

const isArticle = is.ObjectOf({
  title: is.String,
  body: is.String,
  refs: is.ArrayOf(
    is.OneOf([
      is.String,
      is.ObjectOf({
        name: is.String,
        url: is.String,
      }),
    ]),
  ),
});

type Article = PredicateType<typeof isArticle>;

const a: unknown = {
  title: "Awesome article",
  body: "This is an awesome article",
  refs: [{ name: "Deno", url: "https://deno.land/" }, "https://github.com"],
};
if (isArticle(a)) {
  // a is narrowed to the type of `isArticle`
  console.log(a.title);
  console.log(a.body);
  for (const ref of a.refs) {
    if (is.String(ref)) {
      console.log(ref);
    } else {
      console.log(ref.name);
      console.log(ref.url);
    }
  }
}

assert

The assert function does nothing if a given value is expected type. Otherwise, it throws an AssertError exception like:

import {
  assert,
  is,
} from "https://deno.land/x/unknownutil@v3.12.0/mod.ts";

const a: unknown = "Hello";

// `assert` does nothing or throws an `AssertError`
assert(a, is.String);
// a is now narrowed to string

// With custom message
assert(a, is.String, { message: "a must be a string" });

ensure

The ensure function return the value as-is if a given value is expected type. Otherwise, it throws an AssertError exception like:

import {
  ensure,
  is,
} from "https://deno.land/x/unknownutil@v3.12.0/mod.ts";

const a: unknown = "Hello";

// `ensure` returns `string` or throws an `AssertError`
const _: string = ensure(a, is.String);

// With custom message
const __: string = ensure(a, is.String, { message: "a must be a string" });

maybe

The maybe function return the value as-is if a given value is expected type. Otherwise, it returns undefined that suites with nullish coalescing operator (??) like:

import {
  is,
  maybe,
} from "https://deno.land/x/unknownutil@v3.12.0/mod.ts";

const a: unknown = "Hello";

// `maybe` returns `string | undefined` so it suites with `??`
const _: string = maybe(a, is.String) ?? "default value";

Classes

AssertError

Represents an error that occurs when an assertion fails.

Variables

v default
v defaultAssertMessageFactory
v is

Functions

f assert	Asserts that the given value satisfies the provided predicate.
f ensure	Ensures that the given value satisfies the provided predicate.
f isAllOf	Return a type predicate function that returns `true` if the type of `x` is `AllOf<T>`.
f isAny	Always return `true` regardless of the type of `x`.
f isArray	Return `true` if the type of `x` is `unknown[]`.
f isArrayOf	Return a type predicate function that returns `true` if the type of `x` is `T[]`.
f isAsyncFunction	Return `true` if the type of `x` is `function` (async function).
f isBigInt	Return `true` if the type of `x` is `bigint`.
f isBoolean	Return `true` if the type of `x` is `boolean`.
f isFunction	Return `true` if the type of `x` is `function`.
f isInstanceOf	Return `true` if the type of `x` is instance of `ctor`.
f isLiteralOf	Return a type predicate function that returns `true` if the type of `x` is a literal type of `pred`.
f isLiteralOneOf	Return a type predicate function that returns `true` if the type of `x` is one of literal type in `preds`.
f isNull	Return `true` if the type of `x` is `null`.
f isNullish	Return `true` if the type of `x` is `null` or `undefined`.
f isNumber	Return `true` if the type of `x` is `number`.
f isObjectOf	Return a type predicate function that returns `true` if the type of `x` is `ObjectOf<T>`. If `is.OptionalOf()` is specified in the predicate function, the property becomes optional. When `options.strict` is `true`, the number of keys of `x` must be equal to the number of keys of `predObj`. Otherwise, the number of keys of `x` must be greater than or equal to the number of keys of `predObj`.
f isOneOf	Return a type predicate function that returns `true` if the type of `x` is `OneOf<T>`.
f isOptionalOf	Return a type predicate function that returns `true` if the type of `x` is `T` or `undefined`.
f isPrimitive	Return `true` if the type of `x` is Primitive.
f isRecord	Return `true` if the type of `x` is `RecordOf<unknown>`.
f isRecordOf	Return a type predicate function that returns `true` if the type of `x` is `RecordOf<T>`.
f isString	Return `true` if the type of `x` is `string`.
f isSymbol	Return `true` if the type of `x` is `symbol`.
f isSyncFunction	Return `true` if the type of `x` is `function` (non async function).
f isTupleOf	Return a type predicate function that returns `true` if the type of `x` is `TupleOf<T>`.
f isUndefined	Return `true` if the type of `x` is `undefined`.
f isUniformTupleOf	Return a type predicate function that returns `true` if the type of `x` is `UniformTupleOf<T>`.
f isUnknown	Always return `true` regardless of the type of `x`.
f maybe	Returns the input value if it satisfies the provided predicate, or `undefined` otherwise.
f setAssertMessageFactory	Sets the factory function used to generate assertion error messages.

Type Aliases

T AllOf
T AssertMessageFactory
T ObjectOf
T OneOf
T OptionalPredicate
T Predicate	A type predicate function
T PredicateType	A type predicated by Predicate
T Primitive
T RecordOf	Synonym of `Record<string \| number \| symbol, T>`
T TupleOf
T UniformTupleOf