data-exchange

data-exchange
=============

The main purpose of the library is to process data from transport format (e.g. simple object parsed from JSON) to typed JavaScript or TypeScript object and back.

Main features
-------------

* easy to use
* dumping data (convert local objects to remote ones)
* loading data (convert remote objects to local ones)
* nested schemas
* custom filters
* custom validation

Schemas
-------

Schemas are container for fields. There are two schema definition approach you can use.

$3

Base building block is schema with fields. There are two ways to define fields:

1. set fields property of the AbstractSchema class
2. override a createFields() method

The first way is suitable for most cases of use. The second one can be used to define more complex schema with custom cross field validators and/or some custom special logic in schema definition.

$3

From version 2.3 you can use the declarative approach to define your schemas.

Create object extending the DeclarativeSchema class and defined fields as its properties:

``typescript
class MyDeclarativeSchema extends DeclarativeSchema {
id = new Int({required: true});
name = new Str({required: true});
description = new Str({required: true, nullable: false});
}


class MyOtherSchema extends MyDeclarativeSchema {
ownerName = new Str({required: true, remoteName: "owner_name"})
}
`

The declarative schema is recommended because it is more intuitive and it can be easily extended by inheritance.

A field names are resolved by following algorithm:

* if name attribute is null, set it to property name (the name attribute can be set by explicit assign in constructor attr = new Str("some_explicit_name", {...}))
* if remoteName attribute is null, set it to property name
* if localName attribute is null, set it to property name

Fields
------

There are few types of fields delivered with the library.

* Primitive fields
* Str - strings
* Numeric - all numeric values
* Int - integer subset of numeric values (if value is float, it is rouned)
* Bool - logic value
* Date fields - fields with date and time values
* Date_ - only date (field class has underscore suffix to avoid name conflict with JS built-on Date type)
* Time - only time
* DateTime - both date and time
* Complex fields - fields containing fields
* Nested - nested schema
* List - list of items with same type.
* Dict - key value pairs stored in simple object.
* Map_ - key value pairs stored in the Map object.

Common fields constructor interface is

1. field name (can be omitted from version 2.3)
2. required arguments (e.g. another schema instance for Nested)
3. object with optional settings

Settings values common for all built-in fields are:

* required: boolean - true if value cannot be undefined
* nullable: boolean - true if value can be null
* defaultValue: unknown - default value if value is undefined
* localName: string - name of attribute in local object (default is name)
* remoteName: string - name of attribute in remote object (default is name)
* dumpOnly: boolean - if true, field will not be loaded
* loadOnly: boolean - if true, field will not be dumped
* filters: FilterSettings|FilterInterface[] - list of filters
* validators: ValidatorSettings|ValidatorInterface[] - list of validators
* skipIfUndefined: boolean|SkipIfUndefinedSettings - if true (default) a property will not be included in a result
object if the value should be undefined
* ~~dumpName - legacy name for the localName~~
* ~~loadName - legacy name for the remoteName~~

For Date like fields:

* formatter - instance of the date formatter (default is IsoFormatter with UTC as default timezone)
* ~~useUTC - if true (default), UTC version of Date object's methods is used (e.g. setUTCHours)~~

Date and time formatters
------------------------

At this time, only ISO format is supported (the IsoFormatter class).
Configuration object of the IsoFormatter has the following structure:

* defaultTimeZone?: string|null - time zone used for parsing when an input data has no timezone set. Default is Z
(e.g. 2021-02-03T12:31:01 -> 2021-02-03T12:31:01Z).

Validation and filtration
-------------------------

Fields support validation and filtration of values. There is no validators or filters delivered with the library but
custom validators and filters can be written by implementing ValidatorInterface and FilterInterface.

Order of the operations is:

1. Apply filters
2. Validate data
3. dump or load data

Important types
---------------

$3

* parseDate(inp: string): Date - parse date from string
* parseTime(inp: string): Date - parse time from string
* parseDateTime(inp: string): Date - parse date and time from string
* formatDate(date: Date): string - format date as string
* formatTime(date: Date): string - format time as string
* formatDateTime(date: Date): string - format date and time as string

$3

* validate(val: any, context?: any, result?: any, schema?: SchemaInterface) -> boolean - return true if value is
valid, return false otherwise
* getLastErrors() -> ErrorReportInterface[] - get errors of the last validation

$3

* filter(val: any) -> any - apply filtration to the val and return result

$3

* whenLoad: boolean - apply skipIfUndefined settings to load() method
* whenDump: boolean - apply skipIfUndefined settings to dump() method

$3

* inFilters: FilterInterface[] - filters applied in load() method
* outFilters: FilterInterface[] - filters applied in dump() method

$3

* inValidators: FilterInterface[] - validators applied in load() method
* outValidators: FilterInterface[] - validators applied in dump() method

$3

Examples
--------

Sample schema definition

`TypeScript
import { DeclarativeSchema, Int, Str, Date_, Nested, List } from "data-exchange"


class Ban
{
reason: string;

banned_at: Date;
}


class BanSchema extends DeclarativeSchema
{
reason = new Str({required: true});
banne_at = new Date_({required: true});

createObject(): Ban
{
return new Ban();
}
}


class UserSchema extends DeclarativeSchema
{
id = new Int({loadOnly: true, remoteName: "id_user", required: true});
name = new Str({required: true}) // field cannot be undefined or NULL
created_at = new DateTime({required: true, nullable: false}) // field cannot be undefined, but NULL is OK
favorite_numbers = new List(new Int(null, {required: true})) // list of integers
allowed_actions = new Dict(new Str(null, {required: true}), new Bool(null, {required: true})) // the key is string and value is boolean
some_mappoing = new Map_(new Date_(null, {required: true}), new Str(null, {required: true, nullable: true})) // the key is Date object and value is string
last_ban = new Nested(new BanSchema(), {required: true, nullable: false})
}


let data = {
id_user: 1,
name: "Karel Novak",
created_at: "2019-09-03T07:01:30.073Z",
favorite_numbers: [1, 13, 69],
allowed_actions: {"action_1": true, "action_2": false},
some_mapping: {"2021-09-09": "foo", "2021-09-10": "bar"},
last_ban: {
reason: "multiple accounts",
bannted_at: "2019-09-03T07:01:30.073Z"
}
}


let schema = new UserSchema();
let item = schema.load(data);

let dumpedData = schema.dump(item);

`

For more information see docstrings in code or examples in "sample" directory.

The load method has the second optional argument. It is target object where data is load into. If no
object is given, new empty object (by createObject()` call) is created.