Typescript contracts and json to model reader

Downloads in past


201.0.34 months ago2 years agoMinified + gzip package size for @ts-awesome/model-reader in KB


Typescript contracts and json to model reader
Key features:
  • ensure correct native types
  • support for convertor
  • support for reader methods
  • support for auto type detection

Model declaration

Simple way to make model readable is to decorate properties with @readable
import {readble} from '@ts-awesome/model-reader'

class SomeModel {
  public a!: number;
  // @readable can try and guess type if it available in runtime 
  // or report and error
  // supported: string, number, boolean, Date, any readable model
  public b!: string;

  // if property is optional, it needs explicit type declaration
  @readable(String, true)
  public c?: string;
  // if property is nullable, it needs explicit type declaration
  @readable(String, true)
  public d!: string | null;
  // recursive references also work
  @readable(SomeModel, true)
  public e!: SomeModel | null;
  // and arrays
  public f!: SomeModel[];
  // and optional arrays
  @readable([SomeModel], true)
  public g?: SomeModel[] | null;

For advanced use cases class can provide a reader function
class SomeModel {
  static [ReaderSymbol](raw: unknown): SomeModel {
    // you have all the freedome and reader as a help
    return new SomeModel();

Model read

import reader from '@ts-awesome/model-reader';

const source = {
  a: 1,
  b: 'some',
  d: null,
  e: null,
  f: [],
  g: null,

const model = reader(source, SomeModel);
const array = reader([source, source], [SomeModel]);

model instanceof SomeModel // yes
array[0] instanceof SomeModel // yes

Why do we event need this ?

Short answer:

Because JavaScript/JSON is non-typed dynamic language.

Long answer:

There are cases when app obtains data from external sources (eg api, json files). App has not control over that data structure and can only hope that data has correct types.
Common practice is to create interfaces for such external data, so TypeScript can do static verifications. But interface in this case is only an assumption.
As an illustration:
  • Developer gets specs and writes following code:

interface ExternalData {
  name: string;
  value: number;
  date: Date;

function process(data: ExternalData) {
  console.log(data.value + 10);

  • Sometime later api developer changes response format:
* if `name` can be `string|number|undefined` then app will crash from time to time
* if `value` can be `string|number` then app will produce weird results
* if `date` becomes ISO string app will crash with `toDateString` is not a function
Processing this data with model reader as soon as possible will help to detect such problems early, and so it is easier to identify the issue
May be freely distributed under the MIT license.
Copyright (c) 2022 Volodymyr Iatsyshyn and other contributors