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.
AbstractSchema
class (legacy)
Extending the Base building block is schema with fields. There are two ways to define fields:
- set
fields
property of theAbstractSchema
class - 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.
Declarative approach (recommended)
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:
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 isnull
, set it to property name (thename
attribute can be set by explicit assign in constructorattr = new Str("some_explicit_name", {...})
) - if
remoteName
attribute isnull
, set it to property name - if
localName
attribute isnull
, 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 theMap
object.
-
Common fields constructor interface is
- field name (can be omitted from version
2.3
) - required arguments (e.g. another schema instance for
Nested
) - 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 isname
) -
remoteName: string
- name of attribute in remote object (default isname
) -
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 beundefined
dumpName - legacy name for the localNameloadName - legacy name for the remoteName
For Date like fields:
-
formatter
- instance of the date formatter (default isIsoFormatter
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 isZ
(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:
- Apply filters
- Validate data
- dump or load data
Important types
DateTimeFormatter (interface)
-
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
ValidatorInterface
-
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
FilterInterface
-
filter(val: any) -> any
- apply filtration to theval
and return result
SkipIfUndefinedSettings
-
whenLoad: boolean
- applyskipIfUndefined
settings toload()
method -
whenDump: boolean
- applyskipIfUndefined
settings todump()
method
FilterSettings
-
inFilters: FilterInterface[]
- filters applied inload()
method -
outFilters: FilterInterface[]
- filters applied indump()
method
FilterSettings
-
inValidators: FilterInterface[]
- validators applied inload()
method -
outValidators: FilterInterface[]
- validators applied indump()
method
ValidatorSettings
Examples
Sample schema definition
import { DeclarativeSchema, Int, Str, Date_, Nested, List } from "data-exchange"
class Ban
{
reason: string;
banned_at: Date;
}
class BanSchema extends DeclarativeSchema<Ban>
{
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.