README

Tymo

An ECMAScript data type/schema system which based on data type validation.

Tymo is a js runtime data type/schema system, which contains 4 parts: Rule, Type, Schema and Model. You can use Tymo to:

define your own data type
validate data structure
formulate data by type
watch data change
formulate data from backend to frontend

Install

npm i tymo

Usage

import Ty from 'tymo'

const { Ty } = require('tymo')

<script src="/node_modules/tymo/dist/bundle.js"></script>
<script>
const { Ty } = window['tymo']
</script>

If you want to use some sub modules, you can use files in dist dir.

import Dict from 'tymo/src/dict.js' // ES6 module
// or
const Dict = require('tymo/dist/dict.js') // commonjs module

Concepts

Before we develop, we should learn about four concepts.

Rule

A rule is a Behavior Definition of an automic data. For example, var a = 10 and we know a is a number. But how do you know a is a number which will be stored/computed as number type by V8? And how do you know a variable is a what behavior definition? The explanation of a variable's behaviour definition is called rule.

We use native prototypes or interface:

String
Number: should be a finite number, not match NaN "123" and Infinity
Boolean: should be one of true or false
Object: should be a normal object like {}, not match instance of class, array and Object self
Array: should be a normal array like [], not match instance of class inherited from Array and Array self
Function
RegExp: should be a string match regexp
Symbol: should be a symbol
NaN
Infinity
Date
Promise

But these do not contains all of what we want, we want more. Now you can use Rule to define a behavior definition of a variable.

And we extended by using Rule interface of Tymo so that we now have:

Int
Float
Numeric: number or number string
Null
Undefined
Any

And to use Rule conveniently, we provide functions to generate rules:

asynchronous(async fn:type)
validate(fn:boolean, msg)
match(...types)
ifexist(type)
ifnotmatch(type, defaultValue)
determine(fn:type)
shouldexist(fn, type)
shouldnotexist(fn)
implement(Interface)
equal(value)
lambda(inputType:Tuple, outputType:Any)

After you learn the usage of Rule, you can define your own rule.

// example
import { Rule } from 'tymo'
export const NumberString = new Rule('NumberString', value => typeof value === 'string' && /^\-?[0-9]+(\.{0,1}[0-9]+){0,1}$/.test(value))

Type

A type is a data nature, quality or characteristic. You call a data as some type data, it means you know what genera it belongs to. For example, you call a boy as a Person, because you know the boy has what a Person should contains: a head, two hands and may talk. In summary, type contains the data behavior definition, the data structure and the ability to maintain data change as defined. So a type has the ability to check and trace data's characteristic, and throw out warn to user if the data is not of current type.

To create a type, you can use Type:

new Type(pattern)

And we have define some data structure:

new Dict({ ... })
new List([ ... ])
new Tuple([ ... ])
new Enum([ ... ])

+-------------+----------+----------+--
|    Tymo     |    JS    |  Python  |
+=============+==========+==========+==
|    Dict     |  Object  |   dict   |
+-------------+----------+----------+-------------------
|    List     |  Array   |   list   |  mutable array
+-------------+----------+----------+--------------------
|    Enum     |   Set    |   set    |
+-------------+----------+----------+-------------------
|    Tuple    |          |   tuple  |  immutable determined array
+-------------+----------+----------+------------------------------

The output of these constructors are all types which can be used in our system. And these 4 types are extended from Type. Later I will tell you how to create type by using these constructors.

And to use Type conveniently, we provide functions to generate types:

type(pattern)
dict({ ... })
list([ ... ])
tuple([ ... ])
enumerate([ ... ])

Pattern

To define a type, you should provide data behavior definition and data structure, these make up a pattern. A pattern is what passed into Type constructors.

const SomePattern = {
  name: String,
  age: Number,
  code: NumberString, // Rule
  books: BooksListType, // Type
}
const SomeType = new Dict(SomePattern)

Pattern is the design of type to implement the type's ability. You can use js native prototypes/class/value or rule or type in a Pattern. And different type constructor need different pattern form.

Schema

A schema is to describe data structure interaction logic. In javascript, we use object to reflect data set which contains fields, so in Tymo you should use object to define schema.

A schema do not care the real data, it create a abstract data structure. The definition of schema ensure the structure of a model in Tymo. As defined, a data field should follow the schema rules.

Model

A model is a data container which provide features about data operation. We always use a model in our business code to use data. Js native data is very weak, we provide a model that you can watch data change and based on schema, so that you can make your business logic more clear.

watch data change
computed property
validate
extract formdata

Model is used to create controllable data, it always used in bussiness code and we do not know how developers will use a model. So it is designed to be simple and principle.

+---------------------+
|  Native Prototypes  |
+=====================+
|                     |
|  String             |
|  Number             |
|  Array              |  -----------+
|  Object             |             |
|  Function           |             |        +----------------+
|  Symbol             |             |        |  Type          |           +----------------+
|  ...                |             |        +================+           |  Schema        |
|                     |             |        |                |           +================+         +-------------+
+---------------------+             |        |  Dict          |           |                |         |             |
                                    +----->  |  List          |  ------>  |  Property1     |  ---->  |    Model    |
+---------------------+             |        |  Tuple         |           |  Property2     |         |             |
|  Rule               |             |        |  Enum          |           |  Property3     |         +-------------+
+=====================+             |        |  ....          |           |                |
|                     |             |        |                |           +----------------+
|  Any                |             |        +----------------+
|  Null               |             |
|  Undefined          |  -----------+
|  Int                |
|  Float              |
|  Numeric            |
|  ...                |
|                     |
+---------------------+

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Usage no npm install needed!