type-csv-transformer

type-csv-transformer

CSV-friendly, declarative and type-safe object to class transformer.

Features

• Decorator and class based declarative transformations.
• Automatically converts nullish or boolean-ish values. (e.g. 'null', 'true')
• Works as middleware, following CSV parser you're using (like node-csv)
• Customizable, define your own conversion rules or custom transform methods.
• Tested, with high code coverage.

Installation

reflect-metadata package is required since we're highly rely on type reflection.

npm install type-csv-transformer reflect-metadata
# or
yarn add type-csv-transformer reflect-metadata

And be sure to reflect-metadata is imported before using type-csv-transformer

import "reflect-metadata";

Last, a little tsconfig.json tweak is needed.

{
    "compilerOptions": {
        ...
        "emitDecoratorMetadata": true,
        "experimentalDecorators": true,
        ...
    }
}

Usage

Simple

class Cat {
  @Column()
  name: string;

  @Column({ name: 'name' })
  hasName: boolean;

  @Column()
  age: number;

  @Column({ defaultValue: false })
  hasLongHair: boolean;

  @Column({ name: 'likes' })
  interest: string;

  @Column()
  birthday: Date;

  @Column({ name: 'hometown' })
  @Nullable()
  home: string | null;

  @Column()
  @Bool()
  isOddEyed: boolean;
}

const cat = {
  name: 'Toma',
  age: 10,
  likes: 'chicken',
  birthday: '2011-12-01',
  hometown: 'null',
  isOddEyed: 'false',
};
const catInstance = transform(Cat, cat);

expect(catInstance).toBeInstanceOf(Cat);
expect(catInstance).toEqual({
  name: cat.name,
  hasName: true,
  age: cat.age,
  hasLongHair: false,
  interest: cat.likes,
  birthday: new Date(cat.birthday),
  home: null,
  isOddEyed: false,
});

Advanced

class Cat {
  @Column()
  name: string;

  @Column({ name: 'name' })
  hasName: boolean;

  @Column()
  age: number;

  @Column({ defaultValue: false })
  hasLongHair: boolean;

  @Column({ name: 'likes' })
  interest: string;

  @Column()
  birthday: Date;

  @Column({ name: 'hometown' })
  @Nullable()
  home: string | null;

  @Column()
  @Bool()
  isOddEyed: boolean;
  
  @Column()
  @Transform<number>(value => value / 1000) // convert grams to kilograms
  weight: number;
}

const cat = {
  name: 'Toma',
  age: 10,
  likes: 'chicken',   
  birthday: '2011-12-01',
  hometown: 'NULL',
  isOddEyed: 'no',
  weight: 5600,
};
// this time, we're setting custom symbols
const catInstance = transform(Cat, cat, { nullSymbols: ['NULL'], trueSymbols: ['yes'], falseSymbols: ['no'] });

expect(catInstance).toBeInstanceOf(Cat);
expect(catInstance).toEqual({
  name: cat.name,
  hasName: true,
  age: cat.age,
  hasLongHair: false,
  interest: cat.likes,
  birthday: new Date(cat.birthday),
  home: null,
  isOddEyed: false,
  weight: 5.6,
});

This library is still in early stage. If this behavior does not fit into your use cases, feel free to open an issue!

API Reference

Decorators

@Column(options?)

@Column must be specified on every class properties you want to convert, otherwise transformer will ignore those properties.

ColumnOptions:

Property	Default	Description
name?: string	-	Specifies origin object's key. Used when it's not identical to class property name.
allowNull?: boolean	false	If set to false or by default, it will throw error when null values are given.
defaultValue?: unknown	-	Sets default value to assign when evaluation lead to null values.

@Nullable(options?)

Specifying @Nullable works like set ColumnOptions.allowNull=true. (You cannot use this decorator when ColumnOptions.allowNull=false.)

And it provides extra options to set nullish conversion symbols.

NullableOptions:

Property	Default	Description
symbols?: Array<string | number>	-	Sets nullish symbols. Overrides default symbols and global transform() behavior. Values cannot be null or empty array.

@Bool(options?)

@Bool is utility decorator that can transform boolean-ish values

BoolOptions:

Property	Default	Description
trueSymbols?: Array<string | number>	-	Sets boolean-ish symbols that matches to true. Overrides default symbols and global transform() behavior. Values cannot be null or empty array.
falseSymbols?: Array<string | number>	-	Sets boolean-ish symbols that matches to false. Overrides default symbols and global transform() behavior. Values cannot be null or empty array.

@Transform(transformFunction)

It provides custom transform method. Used when behaviors of @Nullable or @Bool does not work as expected or to handle other complex cases.

• transformFunction: (value: any) => unknown

There are some caveats when mixing other methods with @Transform.

• @Bool will be ignored when used together.
• @Transform will be ignored when transform leads to defaultValue of @Column.

Methods

transform(cls, object, options?)

Transforms object into class instance. Also provides extra options to control its behavior.

TransformerOptions:

Property	Default	Description
nullSymbols?: Array<string | number> | null	['null', 'None', '']	Sets nullish symbols.
trueSymbols?: Array<string | number> | null	['true', 'True', 1]	Sets boolean-ish symbols that matches to true.
falseSymbols?: Array<string | number> | null	['false', 'False', 0]	Sets boolean-ish symbols that matches to false.

Inspirations

At first, I was trying to handle CSVs with class-transformer. That attemp actually works but there're many extra codes and some unwanted behaviors. So I created the type-csv-transformer.

Still this library's concepts and implementations are inspired by class-transformer a lot, but there're some differences.

type-csv-transformer

• concentrates on more specific problems.
• provides many utilities to handle CSV easily.
• has much smaller bundle size.

Contributing

• Fork this repository
• Create new feature branch
• Write your codes and commit
• Make all tests and linter rules pass
• Push and make pull request