possible-js

Purpose

It's a tiny library to make working with TypeScripts --strictNullChecks more user-friendly. This library is designed to protect against both null and undefined values, but has the ability to support custom checks as well.

Installation

yarn add possible-js

Usage

Given this potentially undefined button...

import { ofPossible } from 'possible-js';

const btnOrUndefined = document.getElementById('btn');

... get it...

// if button is present, get it, or fail fast.
const button = ofPossible(btnOrUndefined).getOrThrow();

// if button is present, get it, or return a new one.
const button = ofPossible(btnOrUndefined).getOrReturn(new HTMLButtonElement());

... or, do something with it...

// if button is present, click it, or fail fast.
ofPossible(btnOrUndefined).doOrThrow(b => b.click());

// if button is present, click it, or do nothing.
ofPossible(btnOrUndefined).doOrIgnore(b => b.click());

... or, map its properties...

// if button is present, return its dimensions, or fail fast.
const dim = ofPossible(btnOrUndefined).mapOrThrow(b => ({ w: b.offsetWidth, h: b.offsetHeight }));

// if button is present, return its dimensions, or return a default value.
const dim = ofPossible(btnOrUndefined).mapOrReturn(b => ({ w: b.offsetWidth, h: b.offsetHeight }), { w: 0, h: 0 });

... or, pipe multiple functions...

import { ofPossible, mapOrThrow, doOrThrow } from 'possible-js';

ofPossible(btnOrUndefined).pipe(
  mapOrThrow(b => b.parentElement),                  // if button is present find its parent, or fail fast
  mapOrThrow(p => p.nextElementSibling),             // if parent is present find its sibling, or fail fast
  mapOrThrow(s => s.firstElementChild),              // if sibling is present, find its first child, or fail fast
  doOrThrow(c => c.innerHTML = '<span>hello</span>') // if first child is present insert html, or fail fast
);

... or, use a custom check before performing one of the above actions

// if button is present and its text is equal to 'SUBMIT', click it, otherwise throw an error.
ofPossible(btnOrUndefined).doOrThrow(b => b.click(), { checkFn: b => !!b && b.innerText === 'SUBMIT' });