Package Exports

typescript-flat-serializer
typescript-flat-serializer/dist/index.js
typescript-flat-serializer/dist/index.mjs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (typescript-flat-serializer) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

typescript-flat-serializer

npm bundle size GitHub npm

A typescript library to serialize/deserialize classes to/from string in a flat format. Supports inheritance, circular reference and more

⚠️ This library is on pre-release ⚠️

Why

When I was developing a electron app I needed a serializer that fill some requirements to use with IPC:

After serialize I wanted that the object keep the methods (right prototype)
I needed inheritance
Supports circular reference is always good

Installation

npm install typescript-flat-serializer --save

You also need to set experimentalDecorators and emitDecoratorMetadata to true into the tsconfig.json file.

For example:

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

Usage

First let's create some models

import {TSFlatCollection, TSFlatObject} from "typescript-flat-serializer";

@TSFlatObject()
export abstract class Animal {
  protected constructor(public name: string) {
  }
}

// This decorator NEEDS to be placed on every class that you want to serialize. 
// Without this decorator the behavior will be like stringify/parse from JSON.
@TSFlatObject()
export class Dog extends Animal {
  // This decorator will take care of serialize/deserialize our collection
  @TSFlatCollection({collectionType: "set"})
  favoriteFoods: Set<Food>;

  constructor(name: string, public beautiful: boolean, favoriteFoods: Set<Food>) {
    super(name);
    this.favoriteFoods = favoriteFoods;
  }
}

@TSFlatObject()
export class Food extends Animal {
  constructor(name: string) {
    super(name);
  }
}

Now we only need to serialize/deserialize the animal.

import {parse, stringify} from "typescript-flat-serializer";


const foods = new Set([new Food('all')])
const animal: Animal = new Dog('Luffy', true, foods);

// Let's go serialize our animal
const str = stringify(animal)
// value of str: [{"name":"Luffy","beautiful":true,"favoriteFoods":"#_1_#","__class__":"Dog"},["#_2_#"],{"name":"all","__class__":"Food"}]

// And now we can deserialize the animal
const parsedAnimal = parse<Animal>(str);

You can find another examples of utilisation on tests.

API

Decorators

@TSFlatObject

Used to make a class serializable.

Example

@TSFlatObject()
export class Dog {
}

@TSFlatCollection

Used do make a Array|Set|Map|Dictionary

Example

@TSFlatObject()
export class Dog {
  @TSFlatCollection({collectionType: "map"})
  placesVisited: Map<string, boolean>
}

Parameters

collectionType Type: CollectionTypeString
Optional: false
Description: The way to specify the type of collection

@TSFlatProperty

Used modify the serialization/deserialization of a property.

Example

@TSFlatObject()
export class Dog {
  @TSFlatCollection({collectionType: "map"})
  @TSFlatProperty({
    beforeStringify: (m) => {
      m.set('Brazil', true);
    }
  })
  placesVisited: Map<string, boolean>
}

Parameters

options Type: TSFlatPropertyOptions
Optional: true
Description: The option to customize the serialization/deserialization of the target property.

Methods

stringify

Used to serialize a object.

stringify(obj: any, options?: StringifyOptions): string

Parameters

obj

Type: any
Optional: false
Description: The object that will be serialized

options

Type: StringifyOptions
Optional: true
Description: Custom options to the serialization

Return

string

parse

Used to deserialize a string into a object.

parse<T>(str: string): T

Return

T

Definitions

Types

CollectionTypeString

export type CollectionTypeString = 'array' | 'dictionary' | 'map' | 'set';

TSFlatPropertyOptions

export type PropertyTransformer = (property: any) => any;

export interface TSFlatPropertyMetadata {
    beforeStringify?: PropertyTransformer;
    afterParse?: PropertyTransformer;
}

export interface TSFlatPropertyOptions extends TSFlatPropertyMetadata {
}

stringifyOptions

export type StringifyOptions = {
  rFDCOptions?: RFDCOptions
}

export type CustomWayOfCloningObjectMap = Map<Type<any>, (obj: any) => any>;

export type RFDCOptions = {
  customWayOfCloningObject?: CustomWayOfCloningObjectMap
}

Important notes

Cloning

This library before the serialization makes a clone of the object. By default the cloning supports the types:

Object
Array
Number
String
null
Date
undefined
Buffer
TypedArray
Map
Set
Function
AsyncFunction
GeneratorFunction
arguments

To support other type, like DateTime of Luxon, you should do something like that:

const customWayOfCloningObject: CustomWayOfCloningObjectMap = new Map();
const rFDCOptions: RFDCOptions = {
  customWayOfCloningObject
}

customWayOfCloningObject.set(DateTime, (obj) => DateTime.fromMillis(obj.millisecond));

const str = stringify(obj, {rFDCOptions});