@xan105/is v2.9.3

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

• 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

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>

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

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.

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"
  }
}

alias: isBuffer(value: unknown): boolean

isError(value: unknown): boolean

isRegExp(value: unknown): boolean

isPromise(value: unknown): boolean

isFunction(value: unknown): boolean

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

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

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 }));

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

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

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

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

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

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

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

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

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
  };
}

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

asBoolean(value: unknown): boolean | null

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

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

asError(value: unknown): Error | null

asRegExp(value: unknown): RegExp | null

asPromise(value: unknown): Promise | null

asFunction(value: unknown): any