@ts-awesome/model-reader

Typescript contracts and json to model reader

Downloads in past

Stats

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

Readme

@ts-awesome/model-reader
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 {
  @readable
  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
  @readable
  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
  @readable([SomeModel])
  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.name.trim());
  console.log(data.value + 10);
  console.log(data.date.toDateString());
}

  • 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
License
May be freely distributed under the MIT license.
Copyright (c) 2022 Volodymyr Iatsyshyn and other contributors