https://github.com/icapps/jsonade
Json de/serialization made for consistency
https://github.com/icapps/jsonade
serializer
Last synced: about 1 year ago
JSON representation
Json de/serialization made for consistency
- Host: GitHub
- URL: https://github.com/icapps/jsonade
- Owner: icapps
- License: isc
- Created: 2017-11-07T09:55:18.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2022-04-06T06:29:08.000Z (about 4 years ago)
- Last Synced: 2025-04-24T23:17:44.389Z (about 1 year ago)
- Topics: serializer
- Language: JavaScript
- Size: 2.07 MB
- Stars: 8
- Watchers: 4
- Forks: 1
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Jsonade
De/serialize json for consistency!
[](https://badge.fury.io/js/jsonade)
[](https://david-dm.org/icapps/jsonade.svg)
[](https://travis-ci.org/icapps/jsonade)
[](https://coveralls.io/github/icapps/jsonade) [](https://greenkeeper.io/)
- [Installation](#installation)
- [Serializer](#serializer)
- [Serializer instance](#serializer-instance)
- [ErrorSerializer](#errorserializer)
- [Examples](#examples)
## Installation
``` shell
npm install jsonade
```
## Serializer
### `constructor`
```javascript
const mySerializer = new Serializer(resource, configuration, options);
```
#### Arguments
`resource (string)`: Name of the resource being serialized
`configuration (Object)`: Configuration for serialisation
`options (Object)`: Extra options for the serializer (optional)
Configuration:
- `attributes (Array)`: attributes to serialize
Options:
- `case`: Convert the case of the keys of `data`
- `Undefined`: Doesn't convert the case
- `camelCase`: Converts keys to camelCase
- `snake_case`: Converts keys to snake_case
- `kebab-case`: Converts keys to kebab-case
#### Returns
Returns an instance of a custom serializer, ready to use for serializing data.
## Serializer instance
### `serialize`
```javascript
mySerializer.serialize(data, configuration);
```
#### Arguments
`data (Object|Array)`: Dataset to serialize.
`configuration (Object)`: Configuration for serialisation
- `totalCount (Number) *optional`: When serializing an array, the totalCount is part of the meta object. If no totalCount is configured, the length of the provided dataset is used.
Besides `totalCount`, `configuration ` may be used to extend the `meta` response object with arbitrary keys. The `type` key however, cannot be overwritten.
#### Returns
Returns a serialized data respresentation of the given data.
## ErrorSerializer
### `serialize`
#### Arguments
`error (Object|Array)`: Error(s) to serialize.
```javascript
const errors = ErrorSerializer.serialize([error]);
```
#### Returns
- `errors (Object)`: object containing multiple errors.
Every error can have these properties:
| key | |
|---|---|
| status | required |
| title | required |
| id | optional |
| code | optional, application specific |
| detail | optional |
| meta | optional |
##### Example
```json
{
"errors": [
{
"id": "ba4b9f14-5b83-4dfd-ac46-1c3868e1b3ec",
"status": 400,
"code": "2006",
"title": "Article not found",
"detail": "Article with id 892bb574-090d-4d63-a5b5-cb928d5f5c5f not found",
"meta": {
"stack": "NotFoundError: ..."
}
}
]
}
```
## Examples
### Basic example
#### Create a serializer
```javascript
const { Serializer } = require('jsonade');
const userSerializer = new Serializer('user', {
attributes: ['firstName', 'lastName', 'address'],
address: {
attributes: ['street', 'number'],
},
});
```
#### Serialize a single resource
```javascript
const data = {
firstName: 'John',
lastName: 'Doe',
age: 27,
address: {
street: 'Markt',
number: '100',
city: 'Zonnedorp',
country: 'Belgium',
},
};
const result = userSerializer.serialize(data);
// result:
// {
// meta: {
// type: 'user'
// },
// data: {
// firstName: 'John',
// lastName: 'Doe',
// address: {
// street: 'Markt',
// number: '100',
// }
// }
// }
```
#### Serialize a list of resources
```javascript
const data = [
{
firstName: 'John',
lastName: 'Doe',
age: 27,
address: {
street: 'Markt',
number: '100',
city: 'Zonnedorp',
country: 'Belgium',
},
}, {
firstName: 'Jessie',
lastName: 'Doe',
age: 26,
address: {
street: 'Marketstreet',
number: '101',
city: 'Sunvillage',
country: 'United Kingdom',
},
}
];
const result = userSerializer.serialize(data, { totalCount: 91 });
// result:
// {
// meta: {
// type: 'user',
// count: 2,
// totalCount: 91
// },
// data: [
// {
// firstName: 'John',
// lastName: 'Doe',
// address: {
// street: 'Markt',
// number: '100'
// }
// },
// { ... },
// ]
// }
```
#### Extend the meta object
```javascript
const data = [
{
firstName: 'John',
lastName: 'Doe',
age: 25,
address: {
street: 'Markt',
number: '100',
city: 'Zonnedorp',
country: 'Belgium',
},
}, {
firstName: 'Jessie',
lastName: 'Doe',
age: 27,
address: {
street: 'Marketstreet',
number: '101',
city: 'Sunvillage',
country: 'United Kingdom',
},
}
];
const result = userSerializer.serialize(data, { totalCount: 91, averageAge: 26 });
// result:
// {
// meta: {
// type: 'user',
// count: 2,
// totalCount: 91
// averageAge: 26
// },
// data: [
// {
// firstName: 'John',
// lastName: 'Doe',
// address: {
// street: 'Markt',
// number: '100'
// }
// },
// { ... },
// ]
// }
```
### Example using a nested serializer
```javascript
const { Serializer } = require('jsonade');
const addressSerializer = new Serializer('address', {
attributes: ['street', 'number'],
});
const userSerializer = new Serializer('user', {
attributes: ['firstName', 'lastName', 'address'],
address: addresssSerializer,
});
const data = {
firstName: 'John',
lastName: 'Doe',
age: 27,
address: {
street: 'Markt',
number: '100',
city: 'Zonnedorp',
country: 'Belgium',
},
};
const result = userSerializer.serialize(data);
// result:
// {
// meta: {
// type: 'user'
// },
// data: {
// firstName: 'John',
// lastName: 'Doe',
// address: {
// street: 'Markt',
// number: '100'
// }
// }
// }
```
### Example using a case option
```javascript
const { Serializer } = require('jsonade');
const userSerializer = new Serializer(
'user',
{ attributes: ['firstName', 'lastName', 'age', 'greeting'] },
{ case: 'snake_case' },
);
const data = {
firstName: 'John',
lastName: 'Doe',
age: '27',
};
const result = userSerializer.serialize(data);
// result:
// {
// meta: {
// type: 'user'
// },
// data: {
// first_name: 'John',
// last_name: 'Doe',
// age: '27 years old'
// greeting: 'Hello, I\'m John Doe',
// }
// }
```
### Example using a function to transform one property
```javascript
const { Serializer } = require('jsonade');
const userSerializer = new Serializer('user', {
attributes: ['firstName', 'lastName', 'age', 'greeting'],
age: val => `${val} years old`,
greeting: (v, data) => `Hello, I'm ${data.firstName} ${data.lastName}`,
});
const data = {
firstName: 'John',
lastName: 'Doe',
age: '27',
};
const result = userSerializer.serialize(data);
// result:
// {
// meta: {
// type: 'user'
// },
// data: {
// firstName: 'John',
// lastName: 'Doe',
// age: '27 years old'
// greeting: 'Hello, I\'m John Doe',
// }
// }
```
### Example serializing an error
```javascript
const { ErrorSerializer } = require('jsonade');
const errorResponse = ErrorSerializer.serialize(ex);
```
## License
This project is licensed under the ISC License - see the [LICENSE.md](LICENSE.md) file for details