Lightweight, lightning-fast, type safe JSON decoder for TypeScript. 

Lightweight, lightning-fast, type safe JSON decoder for TypeScript

art.deineka

json-decoder

    map: <T2>(func: (t: T) => T2) => Result<T2>;

export declare type Result<T> = Ok<T> | Err<T>;

export declare const ok: <T>(value: T) => Result<T>;

export declare const err: <T>(message: string) => Result<T>;

    decodeAsync: (a: unknown) => Promise<T>;

    map: <T2>(func: (t: T) => T2) => Decoder<T2>;

    then: <T2>(nextDecoder: Decoder<T2>) => Decoder<T2>;

    validate: (func: (t: T) => boolean, errMessage?: string) => Decoder<T>;

export declare const decoder: <T>(decode: (a: unknown) => Result<T>) => Decoder<T>;

export declare const stringDecoder: Decoder<string>;

export declare const numberDecoder: Decoder<number>;

export declare const boolDecoder: Decoder<boolean>;

export declare const nullDecoder: Decoder<null>;

export declare const undefinedDecoder: Decoder<undefined>;

export declare const arrayDecoder: <T>(itemDecoder: Decoder<T>) => Decoder<T[]>;

export declare const oneOfDecoders: <T>(...decoders: Decoder<T>[]) => Decoder<T>;

declare type LastElem<T extends number> = [-1, 0, 1, 2, 3, 4, 5][T];

declare type LastElemType<T extends unknown[]> = T[LastElem<T["length"]>];

declare type LastDecoder<T extends Decoder<unknown>[]> = LastElemType<T> extends Decoder<infer R> ? R : T[0];

export declare const allOfDecoders: <TDecoders extends Decoder<unknown>[], R = LastDecoder<TDecoders>>(...decoders: TDecoders) => Decoder<R>;

export declare const exactDecoder: <T>(value: T) => Decoder<T>;

export declare const objectDecoder: <T>(decoderMap: DecoderMap<T>) => Decoder<T>;

export declare const anyDecoder: Decoder<unknown>;

export declare const valueDecoder: <T>(value: T) => Decoder<T>;

var __values = (this && this.__values) || function (o) {

    var m = typeof Symbol === "function" && o[Symbol.iterator], i = 0;

            if (o && i >= o.length) o = void 0;

            return { value: o && o[i++], done: !o };

var __read = (this && this.__read) || function (o, n) {

    var m = typeof Symbol === "function" && o[Symbol.iterator];

        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);

    catch (error) { e = { error: error }; }

            if (r && !r.done && (m = i["return"])) m.call(i);

        finally { if (e) throw e.error; }

exports.ok = function (value) { return ({

    map: function (func) { return exports.ok(func(value)); }

exports.err = function (message) { return ({

    map: function (func) { return exports.err(message); }

exports.decoder = function (decode) { return ({

        return new Promise(function (accept, reject) {

                    return accept(res.value);

                    return reject(new Error(res.message));

        return exports.decoder(function (b) {

                        return exports.ok(func(res.value));

                        return exports.err(error.message);

        return exports.allOfDecoders(exports.decoder(decode), nextDecoder);

    validate: function (func, errMessage) {

        if (errMessage === void 0) { errMessage = "validation failed"; }

        return exports.decoder(decode).map(function (t) {

                throw new Error(errMessage);

exports.stringDecoder = exports.decoder(function (a) {

        : exports.err("expected string, got " + typeof a);

exports.numberDecoder = exports.decoder(function (a) {

        : exports.err("expected number, got " + typeof a);

exports.boolDecoder = exports.decoder(function (a) {

        : exports.err("expected boolean, got " + typeof a);

exports.anyDecoder = exports.decoder(function (a) { return exports.ok(a); });

exports.valueDecoder = function (value) {

    return exports.decoder(function (a) { return exports.ok(value); });

  "description": "Lightweight, lightning-fast, type safe JSON decoder for TypeScript",

    "url": "git+https://github.com/venil7/json-decoder.git"

  "author": "Art Deineka, @darkest_ruby",

    "url": "https://github.com/venil7/json-decoder/issues"

  "homepage": "https://github.com/venil7/json-decoder#readme",

# TypeScript JSON Decoder: `json-decoder`

**`json-decoder`** is a type safe compositional JSON decoder for `TypeScript`. It is heavily inspired by [Elm](https://package.elm-lang.org/packages/elm/json/latest/) and [ReasonML](https://github.com/glennsl/bs-json) JSON decoders. The code is loosely based on [ts.data.json](https://github.com/joanllenas/ts.data.json) but is a full rewrite, and does not rely on unsafe `any` type.

[![Build Status](https://travis-ci.org/venil7/json-decoder.svg?branch=master)](https://travis-ci.org/venil7/json-decoder) [![TypeScript](https://badges.frapsoft.com/typescript/code/typescript.svg?v=101)](https://github.com/ellerbrock/typescript-badges/)

The decoder comprises of small basic building blocks (listed below), that can be composed into JSON decoders of any complexity, including deeply nested structures, heterogenous arrays, etc. If a type can be expressed as `TypeScript` `interface` or `type` (including algebraic data types) - it can be safely decoded and type checked with `json-decoder`.

Below is a list of basic decoders supplied with `json-decoder`:

  let result: Result<string> = stringDecoder.decode("some string"); //Ok("some string");

  let result: Result<string> = stringDecoder.decode(123.45); //Err("string expected");

  let result: Result<number> = numberDecoder.decode(123.45); //Ok(123.45);

  let result: Result<number> = numberDecoder.decode("some string"); //Err("number expected");

  let result: Result<boolean> = boolDecoder.decode(true); //Ok(true);

  let result: Result<boolean> = boolDecoder.decode(null); //Err("bool expected");

- `nullDecoder` - decodes a `null` value:

  let result: Result<null> = nullDecoder.decode(null); //Ok(null);

  let result: Result<null> = boolDecoder.decode(false); //Err("null expected");

- `undefinedDecoder` - decodes an `undefined` value:

  let result: Result<null> = nullDecoder.decode(undefined); //Ok(undefined);

  let result: Result<null> = boolDecoder.decode(null); //Err("undefined expected");

- `arrayDecoder<T>(decoder: Decoder<T>)` - decodes an array, requires one parameter of array item decoder:

  let result: Result<number[]> = arrayDecoder.decode([1,2,3]); //Ok([1,2,3]);

  let result: Result<number[]> = arrayDecoder.decode("some string"); //Err("array expected");

  let result: Result<number[]> = arrayDecoder.decode([true, false, null]); //Err("array: number expected");

- `objectDecoder<T>(decoderMap: DecoderMap<T>)` - decodes an object, requires a decoder map parameter. Decoder map is a composition of decoders, one for each field of an object, that themselves can be object decoders if neccessary.

  type Pet = {name: string, age: number};

  let petDecoder = objectDecoder<Person>({

  let result: Result<Pet> = petDecoder.decode({name: "Varia", age: 0.5}); //Ok({name: "Varia", age: 0.5});

  let result: Result<Pet> = petDecoder.decode({name: "Varia", type: "cat"}); //Err("name: string expected");

    type: stringDecoder, //<-- error: field type is not defined in Pet

- `exactDecoder<T>(value: T)` - decodes a value that is passed as a parameter. Any other value will result in `Err`:

  let result: Result<"cat"> = catDecoder.decode("cat"); //Ok("cat");

  let result: Result<"cat"> = catDecoder.decode("dog"); //Err("cat expected");

- `oneOfDecoders<T1|T2...Tn>(...decoders: Decoder<T1|T2...Tn>[])` - takes a number decoders as parameter and tries to decode a value with each in sequence, returns as soon as one succeeds, errors otherwise. Useful for algebraic data types.

  let petDecoder = oneOfDecoders<"cat"|"dog"> = oneOfDecoders(catDecoder, dogDecoder);

  let result: Result<"cat"|"dog"> = petDecoder.decode("cat"); //Ok("cat");

  let result: Result<"cat"|"dog"> = petDecoder.decode("dog"); //Ok("dog");

let emailDecoder : Decoder<number> = stringDecoder.validate(/^\S+@\S+$/.test, "not an email");

let integer = emailDecoder.decode("joe@example.com"); //Ok("joe@example.com")

let float = emailDecoder.decode("joe"); //Err("not an email")

let email = emailDecoder.decode("joe@example.com"); //Ok("joe@example.com")

let notEmail = emailDecoder.decode("joe"); //Err("not an email")

		{
		"name": "json-decoder",
		"version": "1.1.1",
		"version": "1.2.0",
		"description": "Lightweight, lightning-fast, type safe JSON decoder for TypeScript",
		@@ -10,3 +10,4 @@ "main": "dist/decoder.js",
		"build": "tsc",
		"clean": "rm -rf ./dist"
		"clean": "rm -rf ./dist",
		"publish": "npm publish"
		},
		@@ -13,0 +14,0 @@ "repository": {

		@@ -41,2 +41,3 @@ export declare const OK = "OK";
		export declare const anyDecoder: Decoder<unknown>;
		export declare const valueDecoder: <T>(value: T) => Decoder<T>;
		export {};

		@@ -225,1 +225,4 @@ "use strict";
		exports.anyDecoder = exports.decoder(function (a) { return exports.ok(a); });
		exports.valueDecoder = function (value) {
		return exports.decoder(function (a) { return exports.ok(value); });
		};

		@@ -183,4 +183,4 @@ # TypeScript JSON Decoder: `json-decoder`
		let emailDecoder : Decoder<number> = stringDecoder.validate(/^\S+@\S+$/.test, "not an email");
		let integer = emailDecoder.decode("joe@example.com"); //Ok("joe@example.com")
		let float = emailDecoder.decode("joe"); //Err("not an email")
		let email = emailDecoder.decode("joe@example.com"); //Ok("joe@example.com")
		let notEmail = emailDecoder.decode("joe"); //Err("not an email")

		@@ -187,0 +187,0 @@ ```

Improved metrics