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

@bahmutov/spok

v1.2.7

Published

Checks a given object against a given set of specifications to keep you from writing boilerplate tests.

Downloads

53,532

Readme

spok

Checks a given object against a given set of specifications to keep you from writing boilerplate tests.

var test = require('tape')
var spok = require('spok')

// this would be returned from a function you are testing
var object = {
  one: 1,
  two: 2,
  three: 3,
  four: 4,
  helloWorld: 'hello world',
  anyNum: 999,
  anotherNum: 888,
  anArray: [1, 2],
  anotherArray: [1, 2, 3],
  anObject: {},
}

// custom specification
function hasThreeElements(a) {
  return a.length === 3
}

test('my object meets the specifications', function(t) {
  spok(t, object, {
    $topic: 'spok-example',
    one: spok.ge(1),
    two: 2,
    three: spok.range(2, 4),
    four: spok.lt(5),
    helloWorld: spok.startsWith('hello'),
    anyNum: spok.type('number'),
    anotherNum: spok.number,
    anArray: spok.array,
    anotherArray: hasThreeElements,
    anObject: spok.ne(undefined),
  })
  t.end()
})

shot

Installation

npm install spok

Why not just deepEqual?

deepEqual works great for most cases, but in some cases you need more control, i.e.

  • values don't exactly match, but are in a given range
  • you want to provide a predicate to determine if a value is correct or not
  • you only want to check a subset of values contained in the object

Adjusting Print Details

By default spok prints the specification that a particular assertion satisified, i.e. satisfies: spok.range(2, 4). You can turn that off via spok.printSpec = false.

On the other hand if you want more details about the satisified spec do spok.printDescription = true instead to get spok to print things like satisfies: spok.range(2, 4) 2 <= value <= 4.

Specs and descriptions are printed in gray so you can focus on the actual values of the test output.

Table of Contents generated with DocToc

spok provides a few common specification functions. However you can write your own functions as well, just return true if specification was satisfied and false if not (see example above).

If you write a specification function that would be useful to others please add it along with a test and provide a PR.

spok.* comparison function names are derived from bash comparison operators to make them easier to remember.

API

spok

Checks the given specifications against the object.

When the tests are run the actual values are printed to verify visually while each provided specification is validated and a test failure caused if one of them fails.

Parameters

  • t Object which has assertion functions equal and deepEqual (to compare objects) - use tap, tape, assert or any other library that has those and thus is compatible
  • obj Object the object to verify the specifications against
  • specifications Object the specifications to verify

spok.range

Specififies that the given number is within the given range, i.e. min<= x <=max.

var spec = {
  x: spok.range(1, 2), // specifies that x should be >=1 and <=2
}

Parameters

spok.gt

Specififies that a number is greater than the given criteria.

var spec = {
  x: spok.gt(1), // specifies that x should be >1
}

Parameters

spok.ge

Specififies that a number is greater or equal the given criteria.

var spec = {
  x: spok.ge(1), // specifies that x should be >=1
}

Parameters

spok.lt

Specififies that a number is less than the given criteria.

var spec = {
  x: spok.lt(1), // specifies that x should be < 1
}

Parameters

spok.le

Specififies that a number is less or equal the given criteria.

var spec = {
  x: spok.le(1), // specifies that x should be <=1
}

Parameters

spok.ne

Specifies that the value is not equal another.

var spec = {
  x: spok.ne(undefined), // specifies that x should be defined
}

Parameters

  • value Any criteria

spok.gtz

Specifies that the value is greater than zero

var spec = {
  x: spok.gtz,
}

spok.gez

Specifies that the value is greater or equal zero

var spec = {
  x: spok.gez,
}

spok.ltz

Specifies that the value is less than zero

var spec = {
  x: spok.ltz,
}

spok.lez

Specifies that the value is less or equal zero

var spec = {
  x: spok.lez,
}

spok.type

Specifies that the input is of a given type.

var spec = {
  x: spok.type('number'), // specifies that x should be a Number
}

Parameters

spok.array

Specifies that the input is an array.

var spec = {
  x: spok.array, // specifies that x should be an Array
}

spok.arrayElements

Specifies that the input is an array with a specific number of elements

var spec = { x: spok.arrayElements(2) // specifies that x should be an Array with 2 elements }

Parameters

spok.arrayElementsRange

Specifies that the input is an array with a number of elements in a given range

var spec = { x: spok.arrayElementsRange(2, 4) // specifies that x should be an Array with 2-4 elements }

Parameters

  • min Number min number of elements
  • max Number max number of elements

spok.number

Specifies that the input of type number and isNaN(x) returns false.

var spec = {
  x: spok.number, // specifies that x should be a Number
}

spok.string

Specifies that the input is a string.

var spec = {
  x: spok.string  // specifies that x should be a String
}

spok.function

Specifies that the input is a function.

var spec = {
  x: spok.function  // specifies that x should be a function
}

spok.definedObject

Specifies that the input is an object and it is not null.

var spec = {
  x: spok.definedObject, // specifies that x is a non-null object
}

spok.startsWith

Specifies that the string starts with the specified substring.

NOTE: only available with node.js which has an ES6 startsWith function

var spec = {
  x: spok.startsWith('hello'), // specifies that x should start with 'hello'
}

Parameters

  • what String substring the given string should start with

spok.endsWith

Specifies that the string ends with the specified substring.

NOTE: only available with node.js which has an ES6 endsWith function

var spec = {
  x: spok.endsWith('hello'), // specifies that x should start with 'hello'
}

Parameters

  • what String substring the given string should start with

spok.test

Specifies that the string needs to match the given regular expression.

var spec = {
  x: spok.test(/hello$/), // specifies that x should match /hello$/
}

Parameters

  • regex RegExp regular expression against which the string is checked via test

spok.defined

Specifies that a value is defined, i.e. it is neither null nor undefined.

var spec = {
  x: spok.defined,
}

spok.notDefined

Specifies that a value is notDefined, i.e. it is either null or notDefined.

var spec = {
  x: spok.notDefined,
}

License

MIT