Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/yamamotok/dataobject
Decorator-based utility for transformation (serialization/deserialization) between plain object and class instance, developed for TypeScript projects. An alternative to class-validator and class-transformer.
https://github.com/yamamotok/dataobject
custom-transformation dataobject deserialization json marshaller npm-package serialization transformation transformer typescript
Last synced: 27 days ago
JSON representation
Decorator-based utility for transformation (serialization/deserialization) between plain object and class instance, developed for TypeScript projects. An alternative to class-validator and class-transformer.
- Host: GitHub
- URL: https://github.com/yamamotok/dataobject
- Owner: yamamotok
- License: mit
- Created: 2021-01-06T02:13:07.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2023-10-17T07:24:08.000Z (about 1 year ago)
- Last Synced: 2024-11-22T22:35:55.038Z (about 1 month ago)
- Topics: custom-transformation, dataobject, deserialization, json, marshaller, npm-package, serialization, transformation, transformer, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@yamamotok/dataobject
- Size: 612 KB
- Stars: 1
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
DataObject
------------
[](https://codecov.io/gh/yamamotok/dataobject)
[](https://badge.fury.io/js/%40yamamotok%2Fdataobject)
## Main features
- Transformation from a Class instance to a plain JavaScript object. (Serialization)
- Transformation from plain a JavaScript object to a Class instance. (Deserialization)
- Designed for TypeScript project, using [TypeScript decorators](https://www.typescriptlang.org/docs/handbook/decorators.html).
## Key concept
- DataObject always takes **whitelist** approach. It means that;
+ Only `@property` decorated property will be output (serialized) into plain JavaScript object.
+ Only `@property` decorated property will be taken (deserialized) into class instance.
## Limitation
- Currently, Class inheritance is not supported.
## Quick examples
```typescript
class User {
@property()
@required()
userId!: string;
@property()
name: string = '';
@property()
postalAddress?: Address;
@property()
@context('factory', 'toPlain')
metadata: Record = {};
@property()
tags: Set = new Set();
static factory = createFactory(User);
static toPlain = createToPlain(User);
}
class Address {
@property()
@required()
country!: string;
@property()
@required()
@context('!public')
@validator(isPostalCode)
postalCode!: string;
static factory = createFactory(Address);
static toPlain = createToPlain(Address);
}
function isPostalCode(code: string) {
return /^[\d]{7}$/.test(code);
}
const source = {
userId: 'e7cebd38-9e3a-4487-9485-b3e3be03cd32',
name: 'test user',
postalAddress: {
country: 'jp',
postalCode: '1234567',
},
metadata: {
lastLogin: 1622940893174,
},
tags: ['loyal', 'active'],
};
// Transformation from plain object to class instance. (deserialization)
const created = User.factory(source);
// Transformation from class instance to plain object. (serialization)
const plain = User.toPlain(created, 'public');
```
## Decorators
### @property decorator & "toPlain" and "factory" static methods
To enable a Class to work as "DataObject", you should do first;
- Implement at least one `@property` decorated property.
- Implement `factory` static method by using `createFactory` utility.
- Implement `toPlain` static method by using `createToPlain` utility.
The simplest class looks like;
```typescript
class Entity {
@property()
id?: string;
static factory = createFactory(Entity);
static toPlain = createToPlain(Entity);
}
```
### Value transformation for each types
DataObject will look up at types given through TypeScript type system for transformation.
It is also possible to tell its type explicitly. Also, you can set your own transformer.
#### string, number, boolean (primitives)
```typescript
@property
name: string;
```
- In toPlain, value will be output as-is.
- In factory, input value will be type-coerced.
```typescript
@property
code: number;
```
- In toPlain, value will be output as-is.
- In factory, input value will be type-coerced. If the result is `NaN`, Error will be thrown.
```typescript
@property
active: boolean;
```
- In toPlain, value will be output as-is.
- In factory, input value will be type-coerced.
#### Custom class
```typescript
@property
active: CustomClass; // CustomClass is a "DataObject" which has factory and toPlain static methods.
```
- In toPlain, value will be transformed with using `CustomClass#toPlain()`.
- In factory, value will be transformed with using `CustomClass#factory()`.
#### array and Set
```typescript
@property
list: string[];
```
- In toPlain, each value in array will be output as-is.
- In factory, each value in array will be taken as-is. (no type coercion)
- Other types are same.
```typescript
@property({ type: () => CustomClass })
list: CustomClass[];
```
- Need to set `type` option to `@property` decorator.
- In toPlain, each value in array will be transformed with using `CustomClass#toPlain()`.
A special attribute `__type: CustomClass` will be added.
- In factory, each value in array will be transformed with using `CustomClass#factory()`.
```typescript
@property({ type: () => [CustomClass, AnotherCustomClass] })
list: Array; // Union type also works
```
- Need to set `type` option to `@property` decorator.
- In toPlain, each value in array will be transformed with using `CustomClass#toPlain()` or `AnotherCustomClass#toPlain()`.
A special attribute `__type: CustomClass` or `__type: AnotherCustomClass` will be added.
- In factory, each value in array will be transformed with using `CustomClass#factory()` or `AnotherCustomClass#factory()`
according to a special attribute `__type`.
```typescript
@property()
list: Set;
@property({ type: () => CustomClass })
list: Set;
```
- Same as array
#### object and Map
```typescript
@property
dict: Record;
```
- In toPlain, each value in object will be output as-is.
- In factory, each value in object will be taken as-is. (no type coercion)
- Other type pairs (e.g. `Record`) are same.
```typescript
@property{ type: () => CustomClass }
dict: Map;
```
- Need to set `type` options to `@property` decorator.
- In toPlain, each value in array will be transformed with using `CustomClass#toPlain()`.
A special attribute `__type: CustomClass` will be added.
- In factory, each value in array will be transformed with using `CustomClass#factory()`.
```typescript
@property{ type: () => CustomClass, isMap: true }
dict: Record;
```
- Need to set `type` and `isMap` options to `@property` decorator if you want to use object like ES6 Map.
- In toPlain, each value in array will be transformed with using `CustomClass#toPlain()`.
A special attribute `__type: CustomClass` will be added.
- In factory, each value in array will be transformed with using `CustomClass#factory()`.
```typescript
@property{ type: () => [CustomClass, AnotherCustomClass] }
dict: Map;
```
- Union type works same as array of union types.
#### undefined
- If the value given to factory was `undefined`, the value is not taken in.
#### Custom transformation
You can use your own transformer by setting `transformer` option.
```typescript
@property({ transformer: jsDateTransformer })
timestamp: Date = new Date();
```
Please check `src/bundle/jsDateTransformer` for actual transformer implementation, which transformed JavaScript
`Date` object to ISO date string and vice-versa.
### @required
In case a property has been decorated with `@required`,
factory will check if the property really exists in given source.
```typescript
@property()
@required()
id!: string;
```
Error will be thrown if it is missing.
### @context
You can make transformation work only in specific contexts.
- factory method has "factory" context as default.
- toPlain method has "toPlain" context as default.
```typescript
class Entity {
@property()
@context('!response')
id: string;
@property('response')
get name(): string { ... }
}
Entity.toPlain(instance, 'response');
```
You can specify custom context to both toPlain and factory. Exclusion (heading `!`) is available.
With above example, toPlain will output only `name` into resulted object.
### @spread
You can spread the value in `toPlain` process with using `@spread` decorator.
Also, you can give context option which works same as `@context`.
```typescript
class Entity {
@property()
id: string = 'my-id'
@property
@spread
details?: Record = { item: 'value' }
}
Entity.toPlain(instance);
```
With above example, `details` is spread, and the result should look like;
```typescript
{ id: "my-id", item: "value" }
```
### @validator
You can set validator function which is invoked in 'factory'.
Validator function should return `true` or nothing (`undefined`) in case of success.
In case of failure, it should return false or Error, or should throw Error.
If some validation failed, 'factory' will throw `ValidationError`.
You can check what properties failed by checking the error thrown.
```typescript
class Entity {
@property()
@validator((v: string) => v.length <= 4)
id?: string;
static factory = createFactory(Entity);
static toPlain = createToPlain(Entity);
}
try {
const entity = Entity.factory({ id: 'a_little_too_long' });
} catch (err) {
// err should be instance of ValidationError
// err.causes[0].key should be 'id'
// err.causes[0].error should be 'id validation failed'
}
```
Be noted the validator will be applied after value transformation finished,
that means the argument validator takes is already transformed value.
## License (MIT)
Copyright (c) 2021 Keisuke Yamamoto