Skip to main content
Module

x/unknownutil/mod.ts

🦕 A lightweight utility pack for handling unknown type
lambdalisue/deno-unknownutil
Very Popular
Go to Latest
import * as unknownutil from "https://deno.land/x/unknownutil@v3.14.1/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.14.1/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.14.1/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.14.1/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.14.1/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.14.1/mod.ts";

const a: unknown = "Hello";

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

Classes

Represents an error that occurs when an assertion fails.

Functions

Asserts that the given value satisfies the provided predicate.

Ensures that the given value satisfies the provided predicate.

Return a type predicate function that returns true if the type of x is AllOf<T>.

Assume x is anyand always returntrueregardless of the type ofx`.

Return true if the type of x is unknown[].

Return a type predicate function that returns true if the type of x is T[].

Return true if the type of x is function (async function).

Return true if the type of x is bigint.

Return true if the type of x is boolean.

Return true if the type of x is function.

Return true if the type of x is instance of ctor.

Return a type predicate function that returns true if the type of x is a literal type of pred.

Return a type predicate function that returns true if the type of x is one of literal type in preds.

Return true if the type of x is null.

Return true if the type of x is null or undefined.

Return true if the type of x is number.

Return a type predicate function that returns true if the type of x is ObjectOf<T>.

Return a type predicate function that returns true if the type of x is OneOf<T>.

Return a type predicate function that returns true if the type of x is T or undefined.

Return true if the type of x is Primitive.

Return a type predicate function that returns true if the type of x is ReadonlyTupleOf<T>.

Return a type predicate function that returns true if the type of x is ReadonlyUniformTupleOf<T>.

Return true if the type of x is Record<PropertyKey, unknown>.

Return a type predicate function that returns true if the type of x is Record<K, T>.

Return true if the type of x is string.

Return true if the type of x is symbol.

Return true if the type of x is function (non async function).

Return a type predicate function that returns true if the type of x is TupleOf<T> or TupleOf<T, E>.

Return true if the type of x is undefined.

Return a type predicate function that returns true if the type of x is UniformTupleOf<T>.

Assume x is unknown and always return true regardless of the type of x.

Returns the input value if it satisfies the provided predicate, or undefined otherwise.

Sets the factory function used to generate assertion error messages.

Type Aliases

Object types that are predicated by predicate functions in the object T.

A type predicate function.

A type predicated by Predicate.

Readonly tuple type of types that are predicated by an array of predicate functions.

Readonly uniform tuple type of types that are predicated by a predicate function T and the length is N.

Synonym of Record<K, T>

Tuple type of types that are predicated by an array of predicate functions.

Uniform tuple type of types that are predicated by a predicate function and the length is N.