# @element-ts/oxygen

> 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.

Latest version **1.2.4** (published 2021-06-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install @element-ts/oxygen
pnpm add @element-ts/oxygen
yarn add @element-ts/oxygen
bun add @element-ts/oxygen
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.4 |
| Published | 2021-06-23 |
| First published | 2020-04-22 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 52.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Elijah Cobb |
| Maintainers | ejc |
| Keywords | type, check, checker, typescript, runtime, recursive |

## Links

- npm: https://www.npmjs.com/package/@element-ts/oxygen
- Repository: https://github.com/element-ts/oxygen
- Homepage: https://github.com/element-ts/oxygen#readme
- Issues: https://github.com/element-ts/oxygen/issues
- npm.io page: https://npm.io/package/@element-ts/oxygen

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.2.4 (latest) — 2021-06-23
- 1.2.3 — 2021-06-17
- 1.2.2 — 2021-03-26
- 1.2.1 — 2020-06-02
- 1.2.0 — 2020-06-02
- 1.1.3 — 2020-05-11
- 1.1.2 — 2020-05-11
- 1.1.1 — 2020-04-26
- 1.1.0 — 2020-04-26
- 1.0.1 — 2020-04-26
- 1.0.0 — 2020-04-22

## README

# 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? :)](https://www.buymeacoffee.com/elijahjcobb)

## 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.

```typescript
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()`.
```typescript
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.
```typescript
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.
```typescript
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.
```typescript
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.
```typescript
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.
```typescript
import {ORegex} from "@element-ts/oxygen";

ORegex.phone().conforms("+1 (123) 456-7890"); // true
ORegex.phone().conforms("qwqwd 1234"); // false
ORegex.email().conforms("john@gmail.com"); // 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.
```typescript
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!
```typescript
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](https://www.typescriptlang.org). 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](https://elijahcobb.com). I am a computer science student at
[Michigan Technological University](https://mtu.edu).

---
_Source: https://npm.io/package/@element-ts/oxygen · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._