About

Collection of various checks for asserting types and values at runtime.

📦 Scoped @xan105 packages are for my own personal use but feel free to use them.

Example

Check Windows/Linux 64-bit/32-bit executable

import { is64bit, is32bit } from "@xan105/is";
const is64 = await is64bit("path/to/executable");
const is32 = await is32bit("path/to/executable");

Check is PNG file

import { isPNG } from "@xan105/is";
const is = await isPNG("path/to/img");

Check winver

import * as check from "@xan105/is";
check.isWin10orGreater();
check.isWin11();
check.isWindows();
check.isWin64(); //64-bits
//etc...

Check Linux

import * as check from "@xan105/is";
check.isDebian();
check.isDebianLike(); //Debian + derivatives (eg: Ubuntu)
check.isGnome();
check.isWayland();

Check type

import * as check from "@xan105/is";

check.isStringNotEmpty("hello world");
check.isIntegerWithinRange(1,0,2);
check.isArrayOfString(["a","b"]);
//etc...

Check Object like

import { isObjLike, isString, isNumber } from "@xan105/is";

const family = {
  name: "Xan",
  age: 26,
  child: {
    name: "Xanette",
    age: 15
  }
};

isObjLike(family,{
  name: isString,
  age: isNumber,
  child: {
    name: isString,
    age: isNumber
  }
});

Assertion

Perform the same check but throw an error instead.

import { shouldWin10orGreater } from "@xan105/is/assert";
shouldWin10orGreater();

import { assert } from "@xan105/is";

assert.shouldStringNotEmpty("hello world");
assert.shouldIntegerWithinRange(1,0,2, "Custom error message");
assert.shouldArrayOfString(["a","b"], new Error("custom error", { cause: err }));
//etc...

Opt

Return the given value when the condition is true otherwise null.

import { asString, asInteger } from "@xan105/is/opt";

function(option = {}){
  const options = {
    param1: asString(option.param1) || "hello world",
    param2: asInteger(option.param2) ?? 0
  };
}

Install / Runtime

📦 Package manager

npm install @xan105/is

Compatibility

Node ✔️

🌐 CDN / HTTPS Bundle

import ... from "https://esm.sh/@xan105/is"

Please see https://esm.sh/ for more details.

API

⚠️ This module is only available as an ECMAScript module (ESM)

💡 assert and opt are under their respective namespace.

import { assert } from "@xan105/is";
assert.shouldWin10orGreater();

import { shouldWin10orGreater } from "@xan105/is/assert";
shouldWin10orGreater();

Named export

binary

`is64bit(filePath: string): Promise<boolean>`

Check if it's a 64-bits (x86_64) Windows or Linux binary.

`is32bit(filePath: string): Promise<boolean>`

Same as above but for a 32-bits (x86) Windows or Linux binary.

`isPNG(filePath: string): Promise<boolean>`

`isJPG(filePath: string): Promise<boolean>`

`isICO(filePath: string): Promise<boolean>`

`isGIF(filePath: string): Promise<boolean>`

`isWEBP(filePath: string): Promise<boolean>`

`isQOI(filePath: string): Promise<boolean>`

type: array

`isArray(value: unknown): boolean`

`isArrayNotEmpty(value: unknown): boolean`

`isArrayOfString(value: unknown): boolean`

`isSizeArrayOfString(value: unknown, length: number): boolean`

`isArrayOfStringNotEmpty(value: unknown): boolean`

`isSizeArrayOfStringNotEmpty(value: unknown, length: number): boolean`

`isArrayOfNumber(value: unknown): boolean`

`isArrayOfStringLike(value: unknown, pattern: RegExp): boolean`

`isSizeArrayOfStringLike(value: unknown, length: number, pattern: RegExp): boolean`

`isSizeArrayOfNumber(value: unknown, length: number): boolean`

`isArrayOfNumberWithinRange(value: unknown, min: number, max: number): boolean`

`isSizeArrayOfNumberWithinRange(value: unknown, length: number, min: number, max: number): boolean`

`isArrayOfInteger(value: unknown): boolean`

`isSizeArrayOfInteger(value: unknown, length: number): boolean`

`isArrayOfIntegerPositive(value: unknown): boolean`

`isSizeArrayOfIntegerPositive(value: unknown, length: number): boolean`

`isArrayOfIntegerPositiveOrZero(value: unknown): boolean`

`isSizeArrayOfIntegerPositiveOrZero(value: unknown, length: number): boolean`

`isArrayOfIntegerWithinRange(value: unknown, min: number, max: number): boolean`

`isSizeArrayOfIntegerWithinRange(value: unknown, length: number, min: number, max: number): boolean`

`isArrayOfObj(value: unknown): boolean`

`isSizeArrayOfObj(value: unknown, length: number): boolean`

`isArrayOfObjWithProperties(value: unknown, prop: string[]): boolean`

`isSizeArrayOfObjWithProperties(value: unknown, length: number, prop: string[]): boolean`

`isArrayOfObjLike(value: unknown, schema: object): boolean`

`isArrayOfSomeObjLike(value: unknown, schema: object): boolean`

Same as isArrayOfObjLike() but at least one element in the array must pass the test instead of all

`isSizeArrayOfObjLike(value: unknown, length: number, schema: object): boolean`

`isArrayOfUint8Array(value: unknown): boolean`

alias: isArrayOfBuffer(value: unknown): boolean

`isSizeArrayOfUint8Array(value: unknown, length: number): boolean`

alias: isSizeArrayOfBuffer

type: number

`isBigInt(value: unknown): boolean`

`isBigIntPositive(value: unknown): boolean`

`isBigIntPositiveOrZero(value: unknown): boolean`

`isBigIntWithinRange(value: unknown, min: bigint, max: bigint): boolean`

`isInteger(value: unknown): boolean`

`isIntegerPositive(value: unknown): boolean`

`isIntegerPositiveOrZero(value: unknown): boolean`

`isIntegerWithinRange(value: unknown, min: number, max: number): boolean`

`isNumber(value: unknown): boolean`

`isNumberWithinRange(value: unknown, min: number, max: number): boolean`

type: object

`isObj(value: unknown): boolean`

as in a "plain obj" and not a JS obj so {}, new Object() and Object.create(null).

`isObjNotEmpty(value: unknown): boolean`

`isObjWithProperties(value: unknown, prop: string[]): boolean`

`isObjLike(value: unknown, schema: object): boolean`

Check if an obj is like the specified schema.
Where schema is an obj containing a set of required property name and its corresponding check function.
If the obj has these properties and they are validated by said corresponding function then this will return true otherwise false.

Example:

const family = {
  name: "Xan",
  age: 26,
  child: {
    name: "Xanette",
    age: 15,
    height: 164,
    weight: 42
  }
};

isObjLike(family,{
  name: isString,
  age: isNumber,
  child: {
    name: isStringNotEmpty,
    age: [ isIntegerWithinRange, [0,100] ],
    height: isNumber,
    weight: [ isNumber, [] ]
  }
});

The check funtion should only return a boolean.
Otherwise or if the function throws then false will be assumed.
NB: Function that use @xan105/error will bypass this and still throw (this is by design).

The check funtion should be defined as follow: something: [function, [args,...] ]
If you don't have any args then an empty array: something: [function, [] ]
Or you can pass the function as is (shortcut): something: function
Note that something: [function] is invalid !

💡 You can flag a property to be optional by using {optional: true}.
If the property is missing it will be skipped.
eg: something: [function, [], {optional: true}]

`isObjWithinObj(value: unknown): boolean`

Plain object assigned as property within another:

{
  foo: {
    bar: "foo"
  },
  bar: {
    foo: "bar"
  }
}

type: string

`isString(value: unknown): boolean`

`isStringNotEmpty(value: unknown): boolean`

`isStringLike(value: unknown, pattern: RegExp): boolean`

`isHexString(value: unknown): boolean`

type: other

`isBoolean(value: unknown): boolean`

`isUint8Array(value: unknown): boolean`

alias: isBuffer(value: unknown): boolean

`isError(value: unknown): boolean`

`isRegExp(value: unknown): boolean`

`isPromise(value: unknown): boolean`

`isFunction(value: unknown): boolean`

os: Windows

`isWindows(): boolean`

`isWindowsX86(): boolean`

alias: isWin32(): boolean

`isWindowsX64(): boolean`

alias: isWin64(): boolean

`isWin11orGreater(): boolean`

`isWin10orGreater(): boolean`

`isWin8orGreater(): boolean`

`isWin7orGreater(): boolean`

`isWin11orLesser(): boolean`

`isWin10orLesser(): boolean`

`isWin8orLesser(): boolean`

`isWin7orLesser(): boolean`

`isWin11(): boolean`

`isWin10(): boolean`

`isWin8(): boolean`

`isWin7(): boolean`

os: Linux

`isLinux(): boolean`

`isArch(): Promise<boolean>`

`isArchLike(): Promise<boolean>`

`isManjaro(): Promise<boolean>`

`isDebian(): Promise<boolean>`

`isDebianLike(): Promise<boolean>`

`isUbuntu(): Promise<boolean>`

`isUbuntuLike(): Promise<boolean>`

`isMint(): Promise<boolean>`

`isPopOS(): Promise<boolean>`

`isElementaryOS(): Promise<boolean>`

`isDeepin(): Promise<boolean>`

`isRaspberryPiOS(): Promise<boolean>`

alias: isRaspbian(): Promise<boolean>

`isFedora(): Promise<boolean>`

`isFedoraLike(): Promise<boolean>`

`isOpenSUSE(): Promise<boolean>`

`isSlackware(): Promise<boolean>`

`isGentoo(): Promise<boolean>`

`isGnome(): boolean`

`isKDE(): boolean`

`isXFCE(): boolean`

`isMate(): boolean`

`isCinnamon(): boolean`

`isWayland(): boolean`

misc

`isIP(value: string): boolean`

`isIPv4(value: string): boolean`

`isIPv6(value: string): boolean`

`isDeno(): boolean`

`isNode(): boolean`

`isBrowser(): boolean`

assert

Perform the same checks as above but throw an error instead.
This replace the cumbersome and often repetitive "if(unexpected) throw Error" pattern.

💡 Every assertion has an optional error parameter to override the default Error.
You can either use

an instance of/inherit from the Error class
or a string to just change the default message.

eg:

assert.shouldIntegerWithinRange(1,0,2, "Custom error message");
assert.shouldArrayOfString(["a","b"], new Error("custom error", { cause: err }));

binary

`should64bit (filePath: string, error?: Error | string): Promise<void>`

`should32bit (filePath: string, error?: Error | string): Promise<void>`

`shouldPNG(filePath: string, error?: Error | string): Promise<void>`

`shouldJPG(filePath: string, error?: Error | string): Promise<void>`

`shouldICO(filePath: string, error?: Error | string): Promise<void>`

`shouldGIF(filePath: string, error?: Error | string): Promise<void>`

`shouldWEBP(filePath: string, error?: Error | string): Promise<void>`

`shouldQOI(filePath: string, error?: Error | string): Promise<void>`

type: array

`shouldArray(value: unknown, error?: Error | string): void`

`shouldArrayNotEmpty(value: unknown, error?: Error | string): void`

`shouldArrayOfString(value: unknown, error?: Error | string): void`

`shouldSizeArrayOfString(value: unknown, length: number, error?: Error | string): void`

`shouldArrayOfStringNotEmpty(value: unknown, error?: Error | string): void`

`shouldSizeArrayOfStringNotEmpty(value: unknown, length: number, error?: Error | string): void`

`shouldArrayOfStringLike(value: unknown, pattern: RegExp, error?: Error | string | null): void`

`shouldSizeArrayOfStringLike(value: unknown, length: number, pattern: RegExp, error?: Error | string | null): void`

`shouldArrayOfNumber(value: unknown, error?: Error | string): void`

`shouldSizeArrayOfNumber(value: unknown, length: number, error?: Error | string): void`

`shouldArrayOfNumberWithinRange(value: unknown, min: number, max: number, error?: Error | string): void`

`shouldSizeArrayOfNumberWithinRange(value: unknown, length: number, min: number, max: number, error?: Error | string): void`

`shouldArrayOfInteger(value: unknown, error?: Error | string): void`

`shouldSizeArrayOfInteger(value: unknown, length: number, error?: Error | string): void`

`shouldArrayOfIntegerPositive(value: unknown, error?: Error | string): void`

`shouldSizeArrayOfIntegerPositive(value: unknown, length: number, error?: Error | string): void`

`shouldArrayOfIntegerPositiveOrZero(value: unknown, error?: Error | string): void`

`shouldSizeArrayOfIntegerPositiveOrZero(value: unknown, length: number, error?: Error | string): void`

`shouldArrayOfIntegerWithinRange(value: unknown, min: number, max: number, error?: Error | string): void`

`shouldSizeArrayOfIntegerWithinRange(value: unknown, length: number, min: number, max: number, error?: Error | string): void`

`shouldArrayOfObj(value: unknown, error?: Error | string): void`

`shouldSizeArrayOfObj(value: unknown, length: number, error?: Error | string): void`

`shouldArrayOfObjWithProperties(value: unknown, prop: string[], error?: Error | string): void`

`shouldSizeArrayOfObjWithProperties(value: unknown, length: number, prop: string[], error?: Error | string): void`

`shouldArrayOfObjLike(value: unknown, schema: object, error?: Error | string): void`

`shouldArrayOfSomeObjLike(value: unknown, schema: object, error?: Error | string): void`

`shouldSizeArrayOfObjLike(value: unknown, length: number, schema: object, error?: Error | string): void`

`shouldArrayOfUint8Array(value: unknown, error?: Error | string): void`

alias: shouldArrayOfBuffer(value: unknown, error?: Error | string): void

`shouldSizeArrayOfUint8Array(value: unknown, length: number, error?: Error | string): void`

alias: shouldSizeArrayOfBuffer(value: unknown, length: number, error?: Error | string): void

type: number

`shouldBigInt(value: unknown, error?: Error | string): void`

`shouldBigIntPositive(value: unknown, error?: Error | string): void`

`shouldBigIntPositiveOrZero(value: unknown, error?: Error | string): void`

`shouldBigIntWithinRange(value: unknown, min: bigint, max: bigint, error?: Error | string): void`

`shouldInteger(value: unknown, error?: Error | string): void`

`shouldIntegerPositive(value: unknown, error?: Error | string): void`

`shouldIntegerPositiveOrZero(value: unknown, error?: Error | string): void`

`shouldIntegerWithinRange(value: unknown, min: number, max: number, error?: Error | string): void`

`shouldNumber(value: unknown, error?: Error | string): void`

`shouldNumberWithinRange(value: unknown, min: number, max: number, error?: Error | string): void`

type: object

`shouldObj(value: unknown, error?: Error | string): void`

`shouldObjNotEmpty(value: unknown, error?: Error | string): void`

`shouldObjWithProperties(value: unknown, prop: string[], error?: Error | string): void`

`shouldObjLike(value: unknown, schema: object, error?: Error | string): void`

`shouldObjWithinObj(value: unknown, error?: Error | string | null): void`

type: string

`shouldString(value: unknown, error?: Error | string): void`

`shouldStringNotEmpty(value: unknown, error?: Error | string): void`

`shouldStringLike(value: unknown, pattern: RegExp, error?: Error | string | null): void`

`shouldHexString(value: unknown, error?: Error | string): void`

type: other

`shouldBoolean(value: unknown, error?: Error | string): void`

`shouldUint8Array(value: unknown, error?: Error | string): void`

alias: #### shouldBuffer(value: unknown, error?: Error | string): void

`shouldError(value: unknown, error?: Error | string): void`

`shouldRegExp(value: unknown, error?: Error | string): void`

`shouldPromise(value: unknown, error?: Error | string | null): void`

`shouldFunction(value: unknown, error?: Error | string | null): void`

os: Windows

`shouldWindows(error?: Error | string): void`

`shouldWindowsX86(error?: Error | string): void`

alias: shouldWin32(error?: Error | string): void

`shouldWindowsX64(error?: Error | string): void`

alias: shouldWin64(error?: Error | string): void

`shouldWin11orGreater(error?: Error | string): void`

`shouldWin10orGreater(error?: Error | string): void`

`shouldWin8orGreater(error?: Error | string): void`

`shouldWin7orGreater(error?: Error | string): void`

`shouldWin11orLesser(error?: Error | string): void`

`shouldWin10orLesser(error?: Error | string): void`

`shouldWin8orLesser(error?: Error | string): void`

`shouldWin7orLesser(error?: Error | string): void`

`shouldWin11(error?: Error | string): void`

`shouldWin10(error?: Error | string): void`

`shouldWin8(error?: Error | string): void`

`shouldWin7(error?: Error | string): void`

os: Linux

`shouldLinux(error?: Error | string): void`

`shouldArch(error?: Error | string): Promise<void>`

`shouldArchLike(error?: Error | string): Promise<void>`

`shouldManjaro(error?: Error | string): Promise<void>`

`shouldDebian(error?: Error | string): Promise<void>`

`shouldDebianLike(error?: Error | string): Promise<void>`

`shouldUbuntu(error?: Error | string): Promise<void>`

`shouldUbuntuLike(error?: Error | string): Promise<void>`

`shouldMint(error?: Error | string): Promise<void>`

`shouldPopOS(error?: Error | string): Promise<void>`

`shouldElementaryOS(error?: Error | string): Promise<void>`

`shouldDeepin(error?: Error | string): Promise<void>`

`shouldRaspberryPiOS(error?: Error | string): Promise<void>`

alias: shouldRaspbian(error?: Error | string): Promise<void>

`shouldFedora(error?: Error | string): Promise<void>`

`shouldFedoraLike(error?: Error | string): Promise<void>`

`shouldOpenSUSE(error?: Error | string): Promise<void>`

`shouldSlackware(error?: Error | string): Promise<void>`

`shouldGentoo(error?: Error | string): Promise<void>`

`shouldGnome(error?: Error | string): void`

`shouldKDE(error?: Error | string): void`

`shouldXFCE(error?: Error | string): void`

`shouldMate(error?: Error | string): void`

`shouldCinnamon(error?: Error | string): void`

`shouldWayland(error?: Error | string): void`

misc

`shouldIP(value: string, error?: Error | string): void`

`shouldIPv4(value: string, error?: Error | string): void`

`shouldIPv6(value: string, error?: Error | string): void`

`shouldDeno(error?: Error | string): boolean`

`shouldNode(error?: Error | string): boolean`

`shouldBrowser(error?: Error | string): boolean`

opt

Return the given value when the condition is true otherwise null.
Works great with operator such as || and ??

eg:

function(option = {}){
  const options = {
    param1: asString(option.param1) || "hello world",
    param2: asInteger(option.param2) ?? 0
  };
}

type: array

`asArray(value: unknown): [] | null`

`asArrayNotEmpty(value: unknown): [] | null`

`asArrayOfString(value: unknown): string[] | null`

`asSizeArrayOfString(value: unknown, length: number): string[] | null`

`asArrayOfStringNotEmpty(value: unknown): string[] | null`

`asSizeArrayOfStringNotEmpty(value: unknown, length: number): string[] | null`

`asArrayOfStringLike(value: unknown, pattern: RegExp): string[] | null;

`asSizeArrayOfStringLike(value: unknown, length: number, pattern: RegExp): string[] | null;

`asArrayOfNumber(value: unknown): number[] | null`

`asSizeArrayOfNumber(value: unknown, length: number): number[] | null`

`asArrayOfNumberWithinRange(value: unknown, min: number, max: number): number[] | null`

`asSizeArrayOfNumberWithinRange(value: unknown, length: number, min: number, max: number): number[] | null`

`asArrayOfInteger(value: unknown): number[] | null`

`asSizeArrayOfInteger(value: unknown, length: number): number[] | null`

`asArrayOfIntegerPositive(value: unknown): number[] | null`

`asSizeArrayOfIntegerPositive(value: unknown, length: number): number[] | null`

`asArrayOfIntegerPositiveOrZero(value: unknown): number[] | null`

`asSizeArrayOfIntegerPositiveOrZero(value: unknown, length: number): number[] | null`

`asArrayOfIntegerWithinRange(value: unknown, min: number, max: number): number[] | null`

`asSizeArrayOfIntegerWithinRange(value: unknown, length: number, min: number, max: number): number[] | null`

`asArrayOfObj(value: unknown): object[] | null`

`asSizeArrayOfObj(value: unknown, length: number): object[] | null`

`asArrayOfObjWithProperties(value: unknown, prop: string[]): object[] | null`

`asSizeArrayOfObjWithProperties(value: unknown, length: number, prop: string[]): object[] | null`

`asArrayOfObjLike(value: unknown, schema: object): object[] | null`

`asArrayOfSomeObjLike(value: unknown, schema: object): object[] | null`

This will return every element matching the given schema.
Unlike asArrayOfObjLike which return the array only if all elements pass the test.

`asSizeArrayOfObjLike(value: unknown, length: number, schema: object): object[] | null`

`asArrayOfUint8Array(value: unknown): Uint8Array[] | Buffer[] | null`

alias: asArrayOfBuffer(value: unknown): Uint8Array[] | Buffer[] | null

`asSizeArrayOfUint8Array(value: unknown, length: number): Uint8Array[] | Buffer[] | null`

alias: asSizeArrayOfBuffer(value: unknown, length: number): Uint8Array[] | Buffer[] | null

type: number

`asBigInt(value: unknown): bigint | null`

`asBigIntPositive(value: unknown): bigint | null`

`asBigIntPositiveOrZero(value: unknown): bigint | null`

`asBigIntWithinRange(value: unknown, min: bigint, max: bigint): bigint | null`

`asInteger(value: unknown): number | null`

`asIntegerPositive(value: unknown): number | null`

`asIntegerPositiveOrZero(value: unknown): number | null`

`asIntegerWithinRange(value: unknown, min: number, max: number): number | null`

`asNumber(value: unknown): number | null`

`asNumberWithinRange(value: unknown, min: number, max: number): number | null`

type: object

`asObj(value: unknown): object | null`

`asObjNotEmpty(value: unknown): object | null`

`asObjWithProperties(value: unknown, prop: string[]): object | null`

`asObjLike(value: unknown, schema: object): object | null`

`asObjWithinObj(value: unknown): object | null`

type: string

`asString(value: unknown): string | null`

`asStringNotEmpty(value: unknown): string | null`

`asHexString(value: unknown): string | null`

type: other

`asBoolean(value: unknown): boolean | null`

`asUint8Array(value: unknown): Uint8Array | Buffer | null`

alias: asBuffer(value: unknown): Uint8Array | Buffer | null