@element-ts/oxygen

oxygen

Welcome to the Oxygen wiki! This is a work in progress and will be constantly updated. Below you will find pages to this wiki but also feel free to view some nice features and information about the package.

Want to buy my next coffee? :)

Summary

Oxygen is a recursive run-time type checking package that is simple to use yet provides all the functionality you will ever need. Written by and for Typescript.

There are 6 different type checkers built into Oxygen. Below I will explain all of them. Every type extends OType. This provides you with a few functions below as shown below. Everything is not only type-checking during runtime, but it is also ALL generic. Most times you won't even realize the type system working underneath. For example, if you are checking a OStandartType.string and you call .verify() you will get back string | undefined. The type system is smart enough for all types to know what you are really meaning in your type definitions because it just infers the raw base type.

Functions

.conforms(value: any): boolean

This will check if the value passed in conforms to the OType it returns a boolean for whether or not the value conforms.

.verify(value: any): T | undefined

This function will check if the value conforms and if it does, it will return the value with the correct types in the type system by parsing out the raw type from the OType provided.

.force(value: any): T

This function is almost identical to verify(...) however it will returns T instead of T | undefined if the value does not conform, an error will be thrown.

Types

OStandardType

The standard type object contains types like: string, number, boolean, void, undefined, null.

import {OStandardType} from "@element-ts/oxygen";

OStandardType.number.conforms(42); // true
OStandardType.number.verify("Hello,  world!"); // number | undefined
OStandardType.number.verify({a: 1, b: 2}); // number (may throw error)
OStandardType.number.conforms("Hello, world!"); // false
OStandardType.string.conforms("Hello, world!"); // true
OStandardType.boolean.conforms(42); // false

OEnum

Now if you want to check some values you can do that too with the enum type. It will return true if the value exists in the accepted values provided by .any().

import {OEnum} from "@element-ts/oxygen";

OEnum.any(true, 42, "HI").conforms(false); // false
OEnum.any(true, 42, "HI").conforms(41); // false
OEnum.any(true, 42, "HI").conforms(true); // true
OEnum.any(true, 42, "HI").conforms("HI"); // true
OEnum.any(true, 42, "HI").conforms(42); // true

OOptional

The optional type will return true if the value is the correct type or if the value is undefined. Otherwise, it will return false.

import {OOptional, OStandardType} from "@element-ts/oxygen";

OOptional.maybe(OStandardType.string).conforms("Hello, world!"); // true
OOptional.maybe(OStandardType.string).conforms(undefined); // true
OOptional.maybe(OStandardType.string).conforms(42); // false

OUnion

The union type will return true if the value is any of the allowed types.

import {OStandardType, OUnion} from "@element-ts/oxygen";

OUnion.any(OStandardType.string, OStandardType.number).conforms("Hello, world!"); // true
OUnion.any(OStandardType.string, OStandardType.number).conforms(42); // true
OUnion.any(OStandardType.string, OStandardType.number).conforms(true); // false

OArrayType

The array type checks that the value is an array and that every value of the array is one of the accepted types. If any of the values do not conform, the entire array does not conform.

import {OArrayType, OStandardType} from "@element-ts/oxygen";

OArrayType.any(OStandardType.string).conforms(["a", "b", "c"]); // true
OArrayType.any(OStandardType.string).conforms(["a", 42, "c"]); // false
OArrayType.any(OStandardType.string, OStandardType.number).conforms(["a", 42, "c"]); // true

OObjectType

The object type checks that all keys in the type definition passed are keys in the value passed and that each key's value conforms. If a single key value pair does not conform, the entire object does not conform.

import {OObjectType, OStandardType} from "@element-ts/oxygen";

OObjectType.follow({
    name: OStandardType.string,
    age: OStandardType.number
}).conforms({
    name: "Elijah",
    age: 21
}); // true

OObjectType.follow({
    name: OStandardType.string,
    age: OStandardType.number
}).conforms({
    name: "Elijah",
    age: true
}); // false

OObjectType.follow({
    name: OStandardType.string,
    age: OStandardType.number
}).conforms({
    name: "Elijah"
}); // false

ORegex

The ability to handle regex checking in the oxygen type checking system. You can write your own regex with .custom() or use one of the predefined regex expressions.

import {ORegex} from "@element-ts/oxygen";

ORegex.phone().conforms("[phone]"); // true
ORegex.phone().conforms("qwqwd 1234"); // false
ORegex.email().conforms("[e-mail]"); // true
ORegex.domain().conforms("google.com"); // true
ORegex.url().conforms("https://google.com"); // true
ORegex.custom(/#?([\da-fA-F]{2})([\da-fA-F]{2})([\da-fA-F]{2})/g).conforms("#FAFAFA"); // true

OAny

This type is an extra type that literally always returns true. This can be used for example with OOptional to require that a value is defined and it does not matter the type of the variable.

import {OAny} from "@element-ts/oxygen";
OAny.any().conforms(1); // true
OAny.any().conforms(undefined); // true

Recursive

Keep in mind, every type checker's type input is of OType and every type checker is an OType. So you can super easily build recursive structures and Oxygen will type check all of it!

import {
    OArrayType,
    OEnum,
    OObjectType,
    OOptional,
    OStandardType,
    ORegex
} from "@element-ts/oxygen";

OObjectType.follow({
	name: OStandardType.string,
    email: ORegex.email(),
	age: OStandardType.number,
	favoriteNumbers: OArrayType.any(OStandardType.number),
	address: OObjectType.follow({
		street: OStandardType.string,
		city: OStandardType.string,
		country: OStandardType.string,
		zip: OStandardType.number
	}),
	isAdmin: OStandardType.boolean,
	parentId: OOptional.maybe(OStandardType.string),
	settings: OObjectType.follow({
		theme: OEnum.any("light", "dark", "default"),
		keepSession: OStandardType.boolean
	})
}).conforms({ /* the actual object */});

About

Language

All of Oxygen is written in TypeScript. If you do not know how to use TypeScript don't worry. It is completely compatible with JavaScript.

Why?

It was time for me to write my own type checker!

Author/Maintainer

My name is Elijah Cobb. I am a computer science student at Michigan Technological University.