npm package: @fulminate/serializer
Description: An easy way of serializing objects.
Author: Sergey Orlov
Latest version: 1.2.5

# Fulminate Serializer

FS simplifies the process of serialization for objects of any kind. The original idea of this package was to create an easy way of serializing objects that arrive from TypeORM.

## Installation

`npm install --save @fulminate/serializer`

## Basic Usage

### TypeScript

```javascript
import { Serializer } from "@fulminate/serializer";

let obj = {
    "id": 1,
    "title": "Foo",
    "description": "Bar",
}

let serializer : Serializer = new Serializer();

console.dir(serializer.serialize(obj, [
   "title",
   "description",
]));

// Output:
// Object { title: "Foo", description: "Bar" }
```

### JavaScript

```javascript
var serializer = require("@fulminate/serializer").Serializer;

var obj = {
    "id": 1,
    "title": "Foo",
    "description": "Bar"
}

console.dir(serializer.serialize(obj, ["title", "description"]));

// Output:
// Object { title: "Foo", description: "Bar" }
```

## Advanced Usage

* **input**: object/array of objects to serialize
* **serializationFields** _(optional, defaults to **[]**)_: array of strings that represents object properties to be used
* **isWhiteList** _(optional, defaults to **true**)_: boolean that defines if properties from the first argument should show (true) or hide (false) given properties
* **toJson** _(optional, defaults to **false**)_: boolean that defines if `JSON.stringify()` should be applied on the output.
* **serializeChilren** _(optional, defaults to **true**)_: boolean that defines if child objects of given input should also be serialized (
to serialize child objects, provide `.`-separated field names to serializationFields array). Bear in mind that currently serializer can only 
go one level deep (`e.g. ["user.credentials.socialNetworks"] will only apply serialization to user and credentials, but NOT socialNetworks`).

### Example of using children serialization

```javascript
import {Serializer} from "@fulminate/serializer";
let object = {
  db: {
    name: "database",
    port: 3306,
    host: "localhost",
    user: "root",
    pass: "",
  },
  name: "Ostap",
  surname: "Bender",
};

let objectArray = [object, object, object];
console.dir(new Serializer().serialize(object, ["db.port", "name"], false));
console.dir(new Serializer().serialize(objectArray, ["db.port", "db.user", "name"], false));

// Output: { db: { name: 'database', host: 'localhost', user: 'root', pass: '' },
//             surname: 'Bender' }
//         [ { db: { name: 'database', host: 'localhost', pass: '' },
//             surname: 'Bender' },
//           { db: { name: 'database', host: 'localhost', pass: '' },
//             surname: 'Bender' },
//           { db: { name: 'database', host: 'localhost', pass: '' },
//             surname: 'Bender' } ]

```

### TypeScript (with Express, TypeORM and RoutingControllers)

Read more about:
* [TypeORM](https://typeorm.github.io/)
* [Routing Controllers](https://github.com/pleerock/routing-controllers)

#### UserController.ts

```javascript
import { Serializer } from "@fulminate/serializer";
import { JsonController, Get } from "routing-controllers";
import { getConnectionManager, Repository } from "typeorm";
import { User } from "/* PATH_TO_USER_MODEL */";

@JsonController()
export class UserController {
    private userRepository : Repository<User>;
    private serializer : Serializer;

    constructor() {
        this.userRepository = getConnectionManager().get().getRepository(User);
        this.serializer = new Serializer();
    }

    @Get("/users")
    async getAll() {
        return this.serializer.serialize(await this.userRepository.find(), User.SHORT_RESPONSE);
    }
}
```

#### User.ts

```javascript
import { ColumnTypes } from "typeorm/metadata/types/ColumnTypes";
import { Entity, Column, PrimaryGeneratedColumn } from "typeorm";

@Entity("account_users", {
    engine: "InnoDB",
})
export class User {
    public static readonly SHORT_RESPONSE : Array<string> = [
        "id",
        "username",
    ];

    @PrimaryGeneratedColumn()
    id : number;

    @Column(ColumnTypes.STRING, {
        unique: true,
        length: 30,
    })
    username : string;

    @Column(ColumnTypes.STRING, {
        length: 50,
    })
    password : string;
}
```

On the page, you will see:

```json
[
    {
        "__comment": {
            "title": "This will NOT appear in your JSON output, it is just a comment to deliver a message to you personally",
            "message": "Assuming you have users in your DB you will see results for each of them serialized"
        }
    },
    {
        "id": "ID_OF_SERIALIZED_USER",
        "username": "USERNAME_OF_SERIALIZED_USER"
    }
]
```

## ToDo

* Unit testing
* Recursive object serialization