nullable-oop v0.0.9

Nullable

A TypeScript/JavaScript class to handle null values more stable.

Why?

This package is all about code stability. null values can occur in every piece of code and are sometimes meant to be where they are. The problem with those values is that they may cause unexpected error messages. This class is useful to handle things that can be null, but need to be handled differently. The Nullable class also throws exceptions, but a Uncaught Error: Trying to get the contents of a Nullable when the value is not set to anything.

is clearly more understandable than a

Uncaught TypeError: Cannot read property "somePropertyName" of null . Aditionally, this class has a HasValue property one can use to determine id the Nullable is a valid object. Those extras make null values safer to handle.

Examples

var Nullable = require("nullable-oop");
function maybeDoSomething(nl) {
    nl = Nullable.create(nl); //To make sure an actual Nullable object is used.
    if(nl.HasValue){
        console.log("Parameter has a value! Its ", nl.Value);
    } else {
        console.log("Why didn't I get a value?");
    }
}

maybeDoSomething(); //Why didn't I get a value?
maybeDoSomething(2); // Parameter has a value! It's 2
maybeDoSomething(Nullable.create({ someString: "I am an object!" })); 
// Parameter has a value! It's { someString: "I am an object" }
maybeDoSomething(Nullable.create()); // Why didn't I get a value?

Notes for TypeScript usage

• In TypeScript, Nullable is a template class, meaning that you use it with the possible object types, e.g.
  • let stringOrNull: Nullable<string>;
  • let customClassOrNull: Nullable<CustomClass>;
  • or even let stringOrNumberOrNull: Nullable<string | number>;
• Although

    function doSomething(nl: Nullable<string>) { /*...*/ }

will prevent any TypeScript code from passing something other than a Nullable to a function, you should still implement the nl = Nullable.create(nl) line, due to the possibility of the function being called with a null value outside of your TypeScript code.

API

class Nullable<T> {
    private val;
    /**
     * public get HasValue: boolean
     * Getter to inform if the Nullable object has a valid object value.
     */
    get HasValue(): boolean;
    /**
     * public get Value: T
     * Getter for the object value of the Nullable.
     * If the current value is null, an error will be thrown. Therefore, it is recommendet to always first check using HasValue.
     */
    get Value(): T;
    /**
     * public set Value: void
     * Setter for the value of the Nullable.
     * Can only be a valid object value, or a TypeError is thrown.
     * To set the value to null, please use Nullable.clear() object method.
     */
    set Value(value: T);
    /**
     * public clear() : void
     * Clears the value of a Nullable and sets it to null.
     */
    clear(): void;
    /**
     * @param v: T_ | null | Nullable<T_>
     * If v is a valid object, a new Nullable object with v as value is returned.
     * If it is null, an empty Nullable will be returned.
     * If v is already a Nullable, it will be the return value.
     */
    static create<T_>(v: T_ | null | Nullable<T_>): Nullable<T_>;
    /**
     * constructor
     * @param value: T | null; defaults to null.
     * Is used as the value of the Nullable.
     *
     * **important**: Please do **not** use the constructor yourself. Use Nullable.create() instead.
     */
    constructor(value?: T | null);
}

If you would like me to continue this project, please star this repository on GitHub