javascript-interface-library

javascript-interface-library

CI

various classification, validation and utility functions for JavaScript and TypeScript

From time to time, it’s necessary to classify and/or validate the values of user inputs, data read from input streams (like files or network connections) or arguments passed as part of a function call. While TypeScript type annotations already eliminate the need for many of these tests, there still exist lots of interfaces to the outer (non-TypeScript) world where value checking remains important.

These situations are, what the javascript-interface-library has been made for.

NPM users: please consider the Github README for the latest description of this package (as updating the docs would otherwise always require a new NPM package version)

Installation

Since v1.1.0, javascript-interface-library is a pure ECMAScript module (ESM) - UMD, CommonJS and AMD builds (and the global variable JIL) are no longer provided.

You may either install the package into your build environment using NPM with the command

npm install javascript-interface-library

and bundle it with your application - in that case, no code needs to be loaded from any third party at runtime.

For buildless setups, it is recommended to host the module yourself: simply download the ready-made file javascript-interface-library.esm.js (a single ESM file without any dependencies) and serve it from your own web server:

<script type="module">
  import { ValueIsOrdinal } from '/js/javascript-interface-library.esm.js'
</script>

Serving the file from your own origin keeps your visitors’ IP addresses away from third-party servers - which may be relevant for GDPR compliance: loading assets from public CDNs (such as unpkg, jsDelivr or cdnjs) or other third-party hosts discloses visitor IPs to those parties and may require consent. For quick experiments, however, importing the module directly is still the fastest way to get started:

<script type="module">
  import { ValueIsOrdinal } from 'https://rozek.github.io/javascript-interface-library/dist/javascript-interface-library.esm.js'
</script>

(please keep in mind that the latter also applies to imports from rozek.github.io - GitHub Pages is a third-party host as well)

Access

Import the functions and values you actually need

import { ValueIsListSatisfying, ValueIsOrdinal } from 'javascript-interface-library'

or import the complete module as a namespace

import * as JIL from 'javascript-interface-library'

All module functions and values are exported individually, thus allowing your bundler to perform some “tree-shaking” in order to include actually used functions or values (together with their dependencies) only. The package also declares itself free of side effects ("sideEffects": false in its package.json), so bundlers may safely drop any unused parts of it.

Usage within Svelte

For Svelte, it is recommended to import the package in a module context. From then on, its exports may be used as usual:

<script context="module">
  import { ValueIsListSatisfying, ValueIsOrdinal } from 'javascript-interface-library'
</script>

<script>
  console.log(ValueIsListSatisfying(
    [1,2,3,4], ValueIsOrdinal, 1,10
  ))
</script>

Usage as ECMAScript Module

import * as JIL from 'javascript-interface-library'

console.log(JIL.ValueIsListSatisfying(
  [1,2,3,4], JIL.ValueIsOrdinal, 1,10
))

API Reference

As shown above, the individual functions and values may either be accessed directly (when used as an ESM) or by prefixing them with their namespace JIL (in all other cases). The following documentation lists all module contents without namespace prefix only, and the shown function signatures are those used by TypeScript.

Object Functions

The JavaScript Object class provides a few useful functions (or “static methods”) for inspecting or converting a given object. Unfortunately, these functions are often used without prior checking whether the given target object actually inherits from the Object protoype or was built using Object.create(null) - and will fail whenever such a “vanilla” object is given.

JIL therefore contains the following functions which mimic their counterparts from the Object class, but succeed even if the given target object is “vanilla”.

Value Classification Functions

The following functions check whether a given argument satisfies a certain constraint (e.g., belongs to a certain category) and return either true (if the constrain is met) or false otherwise.

Argument Validation Functions

The following functions check whether a given argument satisfies a certain constraint (e.g., belongs to a certain category) and either return the given argument (sometimes after some normalization), if the constrain is met, or throw an error otherwise.

Unless stated otherwise, these functions exist in four different “flavours”, as indicated by their name prefixes:

For the sake of clarity, however, only the first “flavour” (namely allowXXX) is shown in the list below (provided that this flavour actually exists).

Utility Functions

Color Utilities

Build Instructions

You may easily build this package yourself.

Just install NPM according to the instructions for your platform and follow these steps:

  1. either clone this repository using git or download a ZIP archive with its contents to your disk and unpack it there
  2. open a shell and navigate to the root directory of this repository
  3. run npm install in order to install the complete build environment
  4. execute npm run build to create a new build (using Vite and vite-plugin-dts for the bundled type declarations)

The package comes with a complete test suite (based on Vitest): run npm test for watch mode or npm run test:run for a single pass. Both testing and building also run automatically in GitHub Actions on every push and pull request - and npm run agadoo checks whether the build result is still tree-shakeable.

License

MIT License

This site is open source. Improve this page.