type-qs ->中文文档

problem

When we parse a search from location, we often get an object like {[key: string]: string|string[]|undefined}, but we really want an object like {[key:string]:number|boolean|Date|string|string[]...} which can describe more types about the values. Also we want to validate these values, if they are invalid we can replace them from an default.

resolve

Here is a tool type-qs which can do something like transforming value type and replacing value which is invalid. It use qs to parse your search to query first, then parse query with your template.

dependencies

1. qs
2. type-query-parser

differs with qs

the only differs with qs is the parse function.

parse(search: string, opt?: IParseOptions & { defaults?: any, template?: Template })

we add the template and defaults into options. So you can work with template to recompute your query and use defaults to replace the invalid query params.

if you set nothing about template, it works what qs.parse works.

example (more in test)

check and transform

1import {parse} from 'type-qs';
2import {Parsers} from 'type-qs/libs';
3
4...
5const template={
6    id:Parsers.natural(),           //get a natural number 0,1,2,3, ......
7    name:Parsers.string(true),      //get a string data with trim option: boolean, if true then the name will be trimmed
8    active:Parsers.boolean(),       //get a boolean data
9    role:Parsers.enum(['GUEST','USER','MASTER','ADMIN']),
10                                    //get a data which only can be one of 'GUEST'|'USER'|'MASTER'|'ADMIN'
11    page:Parsers.natural()          //get a natural number, check out the source page is not a natural number, but 'abc', then get an undefined
12};
13const query=parse('id=123456&name= jimmy &active=true&role=MASTER&page=abc',{template});
14...
15console.log(query);
16
17/*** result ***/
18{
19    id:123456,
20    name:'jimmy',
21    active:true,
22    role:'MASTER',
23    page:undefined
24}

check and transform with default values

1import {parse} from 'type-qs';
2import {Parsers} from 'type-qs/libs';
3
4...
5const template={
6    id:Parsers.natural(),           //get a natural number 0,1,2,3, ......
7    name:Parsers.string(true),      //get a string data with trim option: boolean, if true then the name will be trimmed
8    active:Parsers.boolean(),       //get a boolean data
9    role:Parsers.enum(['GUEST','USER','MASTER','ADMIN']),
10                                    //get a data which only can be one of 'GUEST'|'USER'|'MASTER'|'ADMIN'
11    page:Parsers.natural()          //get a natural number, check out the source page is not a natural number, then get an undefined
12};
13const defaults={
14    role:'GUEST',                   //notice now we change role=MASTERR in search, and it should be undefined, 
15                                    //but we give an defaults which contains a 'role' key
16    page:1
17};
18const query=parse('id=123456&name= jimmy &active=true&role=MASTERR&page=abc',{template,defaults});
19...
20console.log(query);
21
22/*** result ***/
23{
24    id:123456,
25    name:'jimmy',
26    active:true,
27    role:'GUEST',
28    page:1
29}

omit entries which we do not care

1import {parse} from 'type-qs';
2import {Parsers} from 'type-qs/libs';
3
4...
5const template={
6    ids:Parsers.array(),
7}
8
9const query=parse('ids=1%2C2%2C3&useless=123',{template,defaults:{useless:'123'}}); //the url like ids=1,2,3&useless=123
10...
11console.log(query);
12
13/*** result ***/
14{
15    ids:['1','2','3']
16}                                   //the 'useless' in url is omited, because the template has no key 'useless'

make array data type by numbers

1import {parse} from 'type-qs';
2import {Parsers} from 'type-qs/libs';
3
4...
5const template={
6    ids:Parsers.array(Parsers.natural()), //the param to Parses.array can be another Parser which use map array data to you want
7}
8
9const query=parse('ids=1%2C2%2C3',{template}); //the url like ids=1,2,3
10...
11console.log(query);
12
13/*** result ***/
14{
15    ids:[1,2,3]
16}                 

make a custom Parser function

1import {parse} from 'type-qs';
2
3
4const numberToBoolean=(value:string='')=>{
5    if(value.trim()==='1'){
6        return true;
7    }
8    if(value.trim()==='0'){
9        return false
10    }
11}
12
13const template={
14    active:numberToBoolean
15}
16
17const query=parse('active=1',{template});
18...
19console.log(query);
20
21/*** result ***/
22{
23    active:true
24}

use qs abilities

1import {parse,stringify} from 'type-qs';
2import {Parsers} from 'type-qs/libs';
3
4const source={
5    id:1,
6    more:{
7        active:true,
8        name:'Jimmy',
9        size:'ab'
10    }
11};
12
13const template={
14    id:Parsers.natural(),
15    more:{
16        active:Parsers.boolean(),
17        name:Parsers.string(),
18        size:Parsers.natural()
19    }
20};
21
22const defaults={
23    more:{
24        size:10
25    }
26};
27
28const search = stringify(source);                 //id=1&more%5Bactive%5D=true&more%5Bname%5D=Jimmy&more%5Bsize%5D=ab
29const result = parse(search,{template,defaults});
30...
31console.log(result);
32
33/*** result ***/
34{
35    id:1,
36    more:{
37        active:true,
38        name:'Jimmy',
39        size:10                                 //from defaults
40    }
41}                   

api

parse search to an object you want by template and defaults in opt.

types:

type Parser = (value?: string|string[]) => any|void; any function matches Parser is used to transform value to you want

type Template = { [key: string]: Template | Parser } | Parser[]; any object matches Template is used to structure result you want

type IParseOption is from qs, you can learn it with qs api

type {defaults?:any} the default value you provide, when the value is undefined, the value in defaults with same key will replace the undefined one.

function parse(search:string,opt?: IParseOptions & { defaults?: any,template?:Template })

stringify is from qs, you can earn it with qs api

function stringify(obj: any, opt?: IStringifyOptions): string

Parsers provide some Parser, which is helpful, also you can write yourself Parsers.

Parsers.number:

function Parsers.number() return a Parser
 
Parser:(value?:string)=>number|undefined

if the value isNaN (can not be a number), it will return an undefined value, 
else it will provide a number value (typeof returnValue==='number').

Parsers.natural:

function Parsers.natural() return a Parser
 
Parser:(value?:string)=>number|undefined

if the value can not be a natural number, it will return an undefined value, 
else it will provide a natural number value (typeof returnValue==='number').

Parsers.integer:

function Parsers.natural() return a Parser
 
Parser:(value?:string)=>number|undefined

if the value can not be a integer, it will return an undefined value, 
else it will provide a integer value (typeof returnValue==='number').

Parsers.string:

function Parsers.string(trim:boolean) return a Parser
 
Parser:(value?:string)=>string

the value will be a string, if you set trim:true the string value will be trimmed.

Parsers.boolean:

function Parsers.boolean() return a Parser
 
Parser:(value?:string)=>boolean|undefined

if the value trimmed is not 'true' or 'false', it will return an undefined value, 
else it will provide a boolean value (typeof returnValue==='boolean').

Parsers.enum:

function Parsers.enum(array:Array<any>) return a Parser
 
Parser:(value?:string)=>any|undefined

if the value trimmed is not included in array, it will return an undefined value, 
else it will return the one in array which matches value by '==' not '==='.

Parsers.array:

function Parsers.array(mapper?: (data: string) => any) return a Parser
 
Parser: (value?: string | Array<string>)=>Array<any>|Array<string>

if the value is string, it will transform to array by string.split, then the array will map with mapper, 
at last the mapped array will filter out the datas to a new array which data is not undefined.

Parsers.regExp:

function Parsers.regExp(regExp: RegExp) return a Parser
 
Parser:(value?:string)=>string|undefined

if the value 'regExp.test(value)' is passed, it will return value, else it will undefined.

Parsers.date:

function Parsers.date(...dateLikeReduces: Array<DateLikeReduce>) return a Parser
 
Parser:(value?:string)=>DateLike|undefined

type DateLike = string | number | Date;

type DateLikeReduce = (dateLike: DateLike) => DateLike

if the value trimmed can be a Date value, it will return a DateLike value, 
which might be produced by dateLikeReduces, else it will return undefined.

here is some dateLikeReduces provided, they can help you use it more quickly:

startOfDay(dateLike: DateLike)=>Date                // DateLike[2020-05-23 12:11:34] => new Date(2020-05-23 00:00:00:000)
endOfDay(dateLike: DateLike)=>Date                  // DateLike[2020-05-23 12:11:34] => new Date(2020-05-23 23:59:59:999)
toDateString(date: DateLike)=>string                // DateLike[2020-05-23 12:11:34] => '2020-05-23'
toDatetimeString(date: DateLike)=>string            // DateLike[2020-05-23 12:11:34] => '2020-05-23 12:11:34'
pattern(pat: string)=>formatDateLike(dateLike: DateLike)=>string
                                                    // pattern('YYYY-MM-DD HH:mm')=>formatter
                                                    // formatter(DateLike[2020-05-23 12:11:34])
                                                    // =>'2020-05-23 12:11'
                                                    
we can use like this:
import {parse,Parsers} from 'type-qs';
import {startOfDay,pattern,endOfDay,toDatetimeString} from 'type-qs/libs';

const template={
    start:Parsers.date(startOfDay,pattern('YYYY-MM-DD HH:mm:ss')),
    end:Parsers.date(endOfDay,toDatetimeString)
};

const data=parse('start=2020-01-01%2011%3A11%3A11&end=2020-12-13%2010%3A01%3A18',{template});

/*** result ***/
{
    start:'2020-01-01 00:00:00',
    end:'2020-12-13 23:59:59'
}

Parsers.datePattern:

function Parsers.datePattern(...dateLikeReduces: Array<DateLikeReduce>) return a Parser
 
Parser:(value?:string)=>string|undefined

it is just a wrap on Parsers.date, and returns a 'YYYY-MM-DD' formatted string value or undefined.

Parsers.datetimePattern:

function Parsers.datetimePattern(...dateLikeReduces: Array<DateLikeReduce>) return a Parser
 
Parser:(value?:string)=>string|undefined

it is just a wrap on Parsers.date, and returns a 'YYYY-MM-DD HH:mm:ss' formatted string value or undefined.

summary

if you like this tool, give me a little start, thank you.