❓ What is that ?
This thing allows you to don't have to worry about changing server-side structures!
Sometimes when server change JSON structures or frontend start using different API
These situations can make some problems in frontend applications
Because mostly use the same structure from server when develop user interfaces
But with serializy you can describe structure which you will use and which server wants to see
Sounds interesting, yeah ? :-)
Scroll down and take a look at the examples ;-)
💡 How to use
Nothing to hard, just create a class or simple object which will contain all your structure declarations (using field()
, fieldArray()
).
And send this class/object to the model()
function as argument
Like in example:
likeCoffee = languages =
Creating declaration using class is not necessarily, you can create just a simple object:
const DeveloperDeclaration = likeCoffee: languages:
const DeveloperModel =
And when you get server structure just create instance of your declared model:
const ServerStructure = LIKE_COFFEE: true LaNgUagEs: 'GoLang' 'Python' const developer = ServerStructure/* developer object will be { likeCoffee: true, languages: ['GoLang', 'Python'] }*/
But what if you need to change your client model and send it to the server ?
You can use .deserialize()
of the each created instance of declared model:
developerlikeCoffee = falsedeveloperlanguages developer/*{ LIKE_COFFEE: false, LaNgUagEs: ['GoLang', 'Python', 'JavaScript']}*/
Also your created structure declaration (like DeveloperModel
) have methods:
.serialize(serverModel)
- to convert server-side structure to client-side.deserialize(clientModel)
- to convert client-side structure to server-side
In addition, structure declarations have methods:.getUsagePropertyNames()
- returns array of usage property names declared in model.getOriginalPropertyNames()
- returns array of original property names declared in model.getPropertiesMap(reverseNames?: boolean)
- returns map where key is usage property name and value is original property name.reverseNames
- just changing sides key/value
📚 Documentation
Serializy have exports: field()
, fieldArray()
, model()
field(...options: FieldOptions)
[Source]
🔹 This function needed for transforming property of the original structure to usage property.
Syntax: field(...options: FieldOptions)
or field(...options: FieldOptions)(propertyOptions: Partial<CommonPropertyOptions>)
Property options it is configuration object which can allows to change various behaviour of this property. Currently object have:
optional: boolean // true - will say to serializy that this property // can be not contains in original/usage structure // By default: false
For example, you've got object { FirsT_naMe: 'John' }
and you need to convert property "FirsT_naMe"
to the "firstName"
, you can just write:
const Struct =
Or you've got object with string value of number like { Age: '19' }
but you need to use type number, you can just write:
const Struct =
Options:
-
field(originalPropertyName: string, originalType?: string, usageType?: string)
This type of the field declaration allows you to describe simple properties which are mostly primitive values.
Arguments:
-originalPropertyName: string
- name of the property in original structure. Original property with this name will be assigned to usage property.
-originalType?: string
- type of the original property.
-usageType?: string
- needed type of the usage property.note:
originalType
andusageType
should be one of the following strings ('boolean'
,'number'
,'string'
,'object'
,'any'
)Examples:
const Model =const structure =SomeProp: 12345Any: foo: 'bar'console // '12345'console // { SomeProp: 12345, Any: { foo: 'bar' } }
-
field(originalPropertyName: string, modelDeclaration: ModelDeclaration)
This type of the field declaration allows you to describe complex structures to usage structures
Arguments:
-originalPropertyName: string
- name of the property in original structure. Original property with this name will be assigned to usage property.
-modelDeclaration: ModelDeclaration
- model declaration needed for convert original object into usage object.
modelDeclaration
should beobject
/model(DeclarationsClass)
And keys/properties should have values created viafield()
,fieldArray()
functionExamples:
const FooModel ===const fooBarStruct =FooStruct: Foo: 12345console // { fooStruct: { foo: '12345' } }console // { FooStruct: { Foo: 12345 } }
-
field(customSerializer: function, customDeserializer?: function)
You can attach custom serializer/deserializer for specific cases.
Arguments:
-customSerializer: function
- this function should return value of the usage property. Takes one argument - original structure
-customDeserializer?: function
- this function should return object which will been merged to the original structure. Takes one argument - usage structureExamples:
const Model =const structure =foo: 'foo'bar: 'bar'baz: 'baz'console // { barBaz: 'bar/baz', foo: 'foo' }console // { foo: 'foo', bar: 'bar', baz: 'baz' }
-
field({ name: 'property_name', type: 'original_type', usageType: 'usage_type' }: object)
This is just another way to describe property.
Properties:
-name: string
- key name in the original structure
-type?: PropertyType
- type of the original property
-usageType?: PropertyType
- type for usage property
-arrayType?: boolean
- property have array type or not
-optional?: boolean
- same from property options but have more priorityExamples:
const Model =const structure =SomeProp: 12345console // '12345' because usageType - 'string'console // { SomeProp: 12345 }
fieldArray()
[Source]
🔹 This is the same thing like field()
but it needs to describe array of data
const Struct =
Argument variations:
-
fieldArray(originalPropertyName: string, originalType?: string, usageType?: string)
-originalPropertyName
- name of property which should be exist in original structure
-originalType?: string
- type of the original property.
-usageType?: string
- needed type of the usage property. -
fieldArray(originalPropertyName: string, modelDeclaration: ModelDeclaration)
-originalPropertyName
- name of property which should be exist in original structure
modelDeclaration
should beobject
/model(DeclarationsClass)
And keys/properties should have values created viafield()
,fieldArray()
function
model()
[Source]
🔹 This function allows to make model from structure declaration.
Syntax:
// YourStructDeclaration can be: YourStructDeclaration = foo: foo = // config contains properties: const config = warnings: boolean // - disable/enable most warnings based on this declaration
Examples:
const Struct =
📄 Examples
All examples are located here
📢 Integrations
kinka-serializy - integration serializy with http web-client kinka
axios-serializy - integration serializy with http web-client axios
📝 License
Licensed under the MIT License.