npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@hqoss/guards

v0.0.3

Published

A comprehensive, platform-agnostic collection of type guards for TypeScript and JavaScript

Downloads

4

Readme

Node.js CI Codacy Badge Codacy Badge GuardRails badge npm

🛡 Type Guards

A comprehensive, platform-agnostic collection of type guards for TypeScript and JavaScript.

Inspired by Elixir/Erlang Guards.

Type safety for chained ops

Table of contents

⏳ Install

npm install @hqoss/guards

⚠️ NOTE: The project is configured to target ES2018 and the library uses commonjs module resolution. Read more in the Node version support section.

📝 Usage

From https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures:

The latest ECMAScript standard defines nine types:

  • Six Data Types that are primitives, checked by typeof operator:
    • undefined: typeof instance === "undefined"
    • Boolean: typeof instance === "boolean"
    • Number: typeof instance === "number"
    • String: typeof instance === "string"
    • BigInt: typeof instance === "bigint"
    • Symbol: typeof instance === "symbol"
  • null: typeof instance === "object". Special primitive type having additional usage for it's value: if object is not inherited, then null is shown;
  • Object: typeof instance === "object". Special non-data but structural type for any constructed object instance also used as data structures: new Object, new Array, new Map, new Set, new WeakMap, new WeakSet, new Date and almost everything made with new keyword;
  • Function non data structure, though it also answers for typeof operator: typeof instance === "function". This answer is done as a special shorthand for Functions, though every Function constructor is derived from Object constructor.

Primitives

isBigInt

⚠️ NOTE: Currently not exposed because BigInt support requires targeting ES2020.

isBoolean

let val: boolean | number

if (isBoolean(val)) {
  // TypeScript will infer val: boolean
} else {
  // TypeScript will infer val: number
}

isNumber

⚠️ NOTE: Also answers true to NaN!

See also:

let val: number | string

if (isNumber(val)) {
  // TypeScript will infer val: number
} else {
  // TypeScript will infer val: string
}

isString

let val: string | number

if (isString(val)) {
  // TypeScript will infer val: string
} else {
  // TypeScript will infer val: number
}

isSymbol

let val: symbol | string

if (isSymbol(val)) {
  // TypeScript will infer val: symbol
} else {
  // TypeScript will infer val: string
}

isUndefined

let val: undefined | null

if (isUndefined(val)) {
  // TypeScript will infer val: undefined
} else {
  // TypeScript will infer val: null
}

Special

isNull

Answers true if and only if value === null.

Full TypeScript (type inference) support.

isFunction

Answers true if and only if typeof value === "function".

Full TypeScript (type inference) support.

isObject

⚠️ NOTE: This is a strict check, see details below.

Answers true if and only if:

  • isNull(value) === false; and
  • typeof value === "object"

To check for "plain" object (excluding array):

isObject(term) && !isArray(term)

To check for array:

isArray(term)

Full TypeScript (type inference) support.

isArray

Answers true if and only if Array.isArray(value) === true.

Full TypeScript (type inference) support.

isMap

Answers true if and only if (value instanceof Map) === true.

Full TypeScript (type inference) support.

isSet

Answers true if and only if (value instanceof Set) === true.

Full TypeScript (type inference) support.

isWeakMap

Answers true if and only if (value instanceof WeakMap) === true.

Full TypeScript (type inference) support.

isWeakSet

Answers true if and only if (value instanceof WeakSet) === true.

Full TypeScript (type inference) support.

isDate

Answers true if and only if (value instanceof Date) === true.

Full TypeScript (type inference) support.

Convenience

isNonEmptyArray

test("isNonEmptyArray", (t) => {
  t.is(convenience.isNonEmptyArray([1, 2]), true);
  t.is(convenience.isNonEmptyArray([1]), true);
  t.is(convenience.isNonEmptyArray([]), false);
});

Full TypeScript (type inference) support.

isValidNumber

test("isValidNumber", (t) => {
  t.is(convenience.isValidNumber(0), true);
  t.is(convenience.isValidNumber(42), true);
  t.is(convenience.isValidNumber(-42), true);
  t.is(convenience.isValidNumber(3.14), true);
  t.is(convenience.isValidNumber(-3.14), true);
  t.is(convenience.isValidNumber(Infinity), true);
  t.is(convenience.isValidNumber(-Infinity), true);
  t.is(convenience.isValidNumber(Number.MAX_SAFE_INTEGER), true);
  t.is(convenience.isValidNumber(-Number.MAX_SAFE_INTEGER), true);
  t.is(convenience.isValidNumber(NaN), false);
});

Full TypeScript (type inference) support.

isInteger

test("isInteger", (t) => {
  t.is(convenience.isInteger(0), true);
  t.is(convenience.isInteger(42), true);
  t.is(convenience.isInteger(-42), true);
  t.is(convenience.isInteger(3.14), false);
  t.is(convenience.isInteger(-3.14), false);
  t.is(convenience.isInteger(Infinity), false);
  t.is(convenience.isInteger(-Infinity), false);
  t.is(convenience.isInteger(Number.MAX_SAFE_INTEGER), true);
  t.is(convenience.isInteger(-Number.MAX_SAFE_INTEGER), true);
  t.is(convenience.isInteger(NaN), false);
});

Full TypeScript (type inference) support.

isPositiveInteger

test("isPositiveInteger", (t) => {
  t.is(convenience.isPositiveInteger(0), false);
  t.is(convenience.isPositiveInteger(42), true);
  t.is(convenience.isPositiveInteger(-42), false);
  t.is(convenience.isPositiveInteger(3.14), false);
  t.is(convenience.isPositiveInteger(-3.14), false);
  t.is(convenience.isPositiveInteger(Infinity), false);
  t.is(convenience.isPositiveInteger(-Infinity), false);
  t.is(convenience.isPositiveInteger(Number.MAX_SAFE_INTEGER), true);
  t.is(convenience.isPositiveInteger(-Number.MAX_SAFE_INTEGER), false);
  t.is(convenience.isPositiveInteger(NaN), false);
});

Full TypeScript (type inference) support.

isNonNegativeInteger

test("isNonNegativeInteger", (t) => {
  t.is(convenience.isNonNegativeInteger(0), true);
  t.is(convenience.isNonNegativeInteger(42), true);
  t.is(convenience.isNonNegativeInteger(-42), false);
  t.is(convenience.isNonNegativeInteger(3.14), false);
  t.is(convenience.isNonNegativeInteger(-3.14), false);
  t.is(convenience.isNonNegativeInteger(Infinity), false);
  t.is(convenience.isNonNegativeInteger(-Infinity), false);
  t.is(convenience.isNonNegativeInteger(Number.MAX_SAFE_INTEGER), true);
  t.is(convenience.isNonNegativeInteger(-Number.MAX_SAFE_INTEGER), false);
  t.is(convenience.isNonNegativeInteger(NaN), false);
});

Full TypeScript (type inference) support.

isNegativeInteger

test("isNegativeInteger", (t) => {
  t.is(convenience.isNegativeInteger(0), false);
  t.is(convenience.isNegativeInteger(42), false);
  t.is(convenience.isNegativeInteger(-42), true);
  t.is(convenience.isNegativeInteger(3.14), false);
  t.is(convenience.isNegativeInteger(-3.14), false);
  t.is(convenience.isNegativeInteger(Infinity), false);
  t.is(convenience.isNegativeInteger(-Infinity), false);
  t.is(convenience.isNegativeInteger(Number.MAX_SAFE_INTEGER), false);
  t.is(convenience.isNegativeInteger(-Number.MAX_SAFE_INTEGER), true);
  t.is(convenience.isNegativeInteger(NaN), false);
});

Full TypeScript (type inference) support.

API Docs

See full API Documentation here.

Core design principles

  • Code quality; This package may end up being used in mission-critical software, so it's important that the code is performant, secure, and battle-tested.

  • Developer experience; Developers must be able to use this package with no significant barriers to entry. It has to be easy-to-find, well-documented, and pleasant to use.

  • Modularity & Configurability; It's important that users can compose and easily change the ways in which they consume and work with this package.

Node version support

The project is configured to target ES2018. In practice, this means consumers should run on Node 12 or higher, unless additional compilation/transpilation steps are in place to ensure compatibility with the target runtime.

Please see https://node.green/#ES2018 for reference.

Why ES2018

Firstly, according to the official Node release schedule, Node 12.x entered LTS on 2019-10-21 and is scheduled to enter Maintenance on 2020-10-20. With the End-of-Life scheduled for April 2022, we are confident that most users will now be running 12.x or higher.

Secondly, the 7.3 release of V8 (ships with Node 12.x or higher) includes "zero-cost async stack traces".

From the release notes:

We are turning on the --async-stack-traces flag by default. Zero-cost async stack traces make it easier to diagnose problems in production with heavily asynchronous code, as the error.stack property that is usually sent to log files/services now provides more insight into what caused the problem.

Testing

Ava, Jest, and Tape were considered. Ava was chosen as it balances simplicity, speed, and modernity very well.

TODO

A quick and dirty tech debt tracker before we move to Issues.

  • [ ] Write a Contributing guide
  • [ ] Describe scripts and usage, add best practices
  • [ ] Describe security best practices, e.g. npm doctor, npm audit, npm outdated, ignore-scripts in .npmrc, etc.
  • [ ] Add "Why should I use this" section