decodable-js

Overview

decodable-js is a TypeScript/JavaScript library inspired by Swift's Codable. It validates types in JSON data, strips unknown fields, and returns a clean object shaped exactly like your schema. Based on configuration, it can either throw on type mismatches or silently skip misaligned fields. It also supports optional fields and string↔number conversion.

The return type is fully inferred from the struct via the Decode<T> conditional type — no manual type annotations needed.

Installation

# npm
npm install decodable-js

# yarn
yarn add decodable-js

Usage

Basic — flat object

import { decodable, T } from 'decodable-js';

const struct = {
    age:     T.number,
    address: T.string,
    visible: T.boolean,
    salary:  T.number_$  // optional
}

const data = {
    age:     12,
    address: '123 Maple Street',
    visible: true,
    salary:  5000,
    secret:  'will be stripped'
}

const result = decodable({ data, struct })
// {
//   age: 12,
//   address: '123 Maple Street',
//   visible: true,
//   salary: 5000
// }

Nested objects

Struct mirrors the shape of your data at any depth — unknown fields are stripped at every level:

const struct = {
    user: {
        name: T.string,
        address: {
            city:    T.string,
            country: T.string,
        }
    }
}

const data = {
    user: {
        name: 'Emily Johnson',
        password: 'hidden',       // stripped
        address: {
            city:    'Austin',
            country: 'USA',
            zip:     '78701',     // stripped
        }
    }
}

const result = decodable({ data, struct })
// { user: { name: 'Emily Johnson', address: { city: 'Austin', country: 'USA' } } }

Arrays of primitives

Wrap the element type in an array:

const struct = { tags: [T.string], ids: [T.number] }
const data   = { tags: ['js', 'ts'], ids: [1, 2, 3] }

decodable({ data, struct })
// { tags: ['js', 'ts'], ids: [1, 2, 3] }

Arrays of objects

const struct = {
    users: [{ id: T.number, name: T.string }]
}

const data = {
    users: [
        { id: 1, name: 'Emily Johnson', secret: 'stripped' },
        { id: 2, name: 'Michael Smith', secret: 'stripped' },
    ]
}

decodable({ data, struct })
// { users: [{ id: 1, name: 'Emily Johnson' }, { id: 2, name: 'Michael Smith' }] }

Top-level array

Pass arrays as both data and struct:

const data   = [{ id: 1, name: 'Emily Johnson' }, { id: 2, name: 'Michael Smith' }]
const struct = [{ id: T.number, name: T.string }]

decodable({ data, struct })
// [{ id: 1, name: 'Emily Johnson' }, { id: 2, name: 'Michael Smith' }]

Deep nesting (object → array of objects → array of objects)

Nesting is recursive — any combination of objects and arrays works:

const struct = {
    company: {
        name: T.string,
        departments: [{
            title: T.string,
            employees: [{
                id:   T.number,
                tags: [{ label: T.string }]
            }]
        }]
    }
}

decodable({ data, struct })  // strips extra fields at every level

enableConvert — string ↔ number conversion

const struct = { numbers: [T.string] }
const data   = { numbers: [1, '2', '3'] }  // 1 will be converted

decodable({ data, struct, enableConvert: true })
// { numbers: ['1', '2', '3'] }

If a string cannot be converted to a number (e.g. 'abc'), an error is thrown. Use silentMode: true to skip such values instead.

silentMode — skip mismatches instead of throwing

const struct = { id: T.number, name: T.string }
const data   = { id: 'wrong', name: 'Emily Johnson' }

decodable({ data, struct, silentMode: true })
// { name: 'Emily Johnson' }  — 'id' skipped, no error thrown

onDrop — observe skipped fields

onDrop is called whenever a field is silently skipped in silentMode. Receives the dot-path and the offending value:

const dropped: string[] = []

decodable({
    data:       { id: 'wrong', name: 'Emily Johnson' },
    struct:     { id: T.number, name: T.string },
    silentMode: true,
    onDrop:     (path, value) => dropped.push(`${path}: ${value}`)
})

// dropped → ['id: wrong']

API Reference

decodable(options)

| Option | Type | Default | Description | |---|---|---|---| | data | object \| array | — | JSON data to decode | | struct | object \| array | — | Schema defining expected types | | enableConvert | boolean | false | Convert between strings and numbers when possible | | silentMode | boolean | false | Skip invalid fields instead of throwing | | onDrop | (path: string, value: unknown) => void | — | Called for each silently skipped field |

Type markers (T)

| Marker | Type | Description | |---|---|---| | T.number | number | Any number | | T.string | string | Any string | | T.boolean | boolean | true or false | | T.null | null | Exactly null | | T.object | Record<string, any> | Any object — contents are passed through without validation | | T.array | any[] | Any array — contents are passed through without validation |

Optional types

Append _$ to mark a field as optional (type | undefined). If the field is absent, it is omitted from the result. If present, its type must match.

| Marker | Equivalent | |---|---| | T.number_$ | number \| undefined | | T.string_$ | string \| undefined | | T.boolean_$ | boolean \| undefined | | T.null_$ | null \| undefined | | T.object_$ | Record<string, any> \| undefined | | T.array_$ | any[] \| undefined |

You can also create an optional wrapper for any custom type with T.optional():

T.optional(T.number)   // same as T.number_$
T.optional({ id: T.number, name: T.string })  // optional nested object

Error messages

Errors include the full field path so the problem is easy to locate:

"user.address.city" is type "number" but expected "string" (got: 42)
"users[1].id" is type "string" but expected "number" (got: "abc")
"profile" key not found

Author

Alex Shumihin — initial work and maintenance.

For feedback or issues, please open a GitHub issue or submit a pull request.