@litert/typeguard 1.3.0-dev.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litert/typeguard",
-  "version": "1.3.0-dev.0",
+  "version": "1.4.0",
   "description": "An easy and powerful data validation code generator by JavaScript.",
   "main": "lib/index.js",
   "scripts": {
@@ -12,7 +12,7 @@
     "clean": "rm -rf lib examples test",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "eslint --ext ts src",
-    "prepare": "husky install"
+    "prepare": "husky install || echo 'skipped husky install'"
   },
   "keywords": [
     "litert",
@@ -34,18 +34,16 @@
   "types": "lib/index.d.ts",
   "typings": "lib/index.d.ts",
   "devDependencies": {
-    "@commitlint/cli": "^17.0.3",
-    "@commitlint/config-conventional": "^17.0.3",
-    "@types/mocha": "^9.1.1",
-    "@types/node": "^18.0.0",
-    "@typescript-eslint/eslint-plugin": "^5.30.3",
-    "@typescript-eslint/parser": "^5.30.3",
-    "eslint": "^8.19.0",
-    "husky": "^8.0.1",
-    "mocha": "^10.0.0",
-    "typescript": "^4.7.4"
+    "@commitlint/cli": "^17.6.5",
+    "@commitlint/config-conventional": "^17.6.5",
+    "@litert/eslint-plugin-rules": "^0.1.3",
+    "@types/mocha": "^10.0.1",
+    "@types/node": "^20.3.1",
+    "husky": "^8.0.3",
+    "mocha": "^10.2.0",
+    "typescript": "~5.0.0"
   },
   "engines": {
-    "node": ">=8.0.0"
+    "node": ">=14.0.0"
   }
 }

package/src/examples/quick-start.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2022 Angus Fenying <fenying@litert.org>
+ * Copyright 2023 Angus Fenying <fenying@litert.org>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -170,3 +170,7 @@ executeTest(
         { 'a': '123312312', 'b': 'ccc' },
     ]
 );
+
+console.log(tgc.compile({
+    rule: '@enum(1, 2, 3, "ss\\"")',
+}).toString());

package/src/lib/BuiltInTypeCompiler.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2022 Angus Fenying <fenying@litert.org>
+ * Copyright 2023 Angus Fenying <fenying@litert.org>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -502,7 +502,7 @@ implements I.IBuiltInTypeCompiler {
             }
             case B.STRUCT: {
 
-                return this._lang.isStrucutre(ctx.vName, true);
+                return this._lang.isStructure(ctx.vName, true);
             }
             case B.NUMERIC: {
 
@@ -738,7 +738,7 @@ implements I.IBuiltInTypeCompiler {
 
                 if (fromString) {
 
-                    ctx.untrap();
+                    ctx.popUp();
 
                     return this._lang.and([
                         this._lang.or([
@@ -891,7 +891,7 @@ implements I.IBuiltInTypeCompiler {
 
                 if (fromString) {
 
-                    ctx.untrap();
+                    ctx.popUp();
 
                     return this._lang.and([
                         this._lang.or([

package/src/lib/BuiltInTypes.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2022 Angus Fenying <fenying@litert.org>
+ * Copyright 2023 Angus Fenying <fenying@litert.org>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

package/src/lib/Common.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 Angus Fenying <fenying@litert.org>
+ * Copyright 2023 Angus Fenying <fenying@litert.org>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,6 +15,7 @@
  */
 
 export type ITypeChecker<T> = (v: unknown, errorTraces?: string[]) => v is T;
+export type IPreDefinedTypeChecker<T> = (v: unknown, ...args: any[]) => v is T;
 
 /**
  * @deprecated Use `ITypeChecker` instead.
@@ -167,7 +168,7 @@ export interface ILanguageBuilder {
      */
     modOf(a: string, b: string): string;
 
-    literal(val: string | boolean | number): string;
+    literal(val: string | boolean | number | null): string;
 
     /**
      * Get the statement checking if a string expression includes a given
@@ -249,7 +250,7 @@ export interface ILanguageBuilder {
      * @param expr      The expression to be checked.
      * @param positive  Assert positive or negative.
      */
-    isStrucutre(expr: string, positive: boolean): string;
+    isStructure(expr: string, positive: boolean): string;
 
     /**
      * Get the statement checking if an expression is an integer value.
@@ -306,7 +307,7 @@ export interface ILanguageBuilder {
     stringLength(expr: string): string;
 
     /**
-     * Get the statement of the keys list of an dicitionary.
+     * Get the statement of the keys list of an dictionary.
      *
      * @param expr The expression of dictionary.
      */

package/src/lib/Compiler.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2022 Angus Fenying <fenying@litert.org>
+ * Copyright 2023 Angus Fenying <fenying@litert.org>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -215,7 +215,7 @@ class Compiler implements C.ICompiler {
                 break;
         }
 
-        throw new TypeError('Unknwn rules.');
+        throw new TypeError('Unknown rules.');
     }
 
     private _compileStringRule(ctx: I.IContext, rule: string): string {
@@ -313,7 +313,7 @@ class Compiler implements C.ICompiler {
             ]);
         }
 
-        if (rule.startsWith(I.PREDEF_TYPE_SYMBOL)) {
+        if (rule.startsWith(I.PRE_DEF_TYPE_SYMBOL)) {
 
             return this._usePredefinedType(ctx, rule.slice(1));
         }
@@ -360,19 +360,20 @@ class Compiler implements C.ICompiler {
 
     private _usePredefinedType(
         ctx: I.IContext,
-        typeName: string
+        typeExpr: string
     ): string {
 
-        this._validateTypeName(typeName);
+        const expr = I.decodePreDefinedCallExpr(typeExpr);
 
-        ctx.referredTypes[typeName] = true;
+        ctx.referredTypes[expr.name] = true;
 
         return this._lang.call(
             this._lang.fieldIndex(
                 ctx.typeSlotName,
-                this._lang.literal(typeName)
+                this._lang.literal(expr.name)
             ),
-            ctx.vName
+            ctx.vName,
+            ...expr.args.map(i => this._lang.literal(i))
         );
     }
 
@@ -383,7 +384,7 @@ class Compiler implements C.ICompiler {
 
         const assertRule = /^:([-\w]+):/.exec(rule);
 
-        const offset = assertRule ? assertRule[1].length + 2 : 2;
+        const offset = (assertRule?.[1]?.length ?? 0) + 2;
 
         switch ((assertRule?.[1]) ?? rule.slice(0, 2)) {
             case '==':
@@ -546,7 +547,7 @@ class Compiler implements C.ICompiler {
 
         if (!rules.length) {
 
-            throw new TypeError('Unknwon type "[]".');
+            throw new TypeError('Unknown type "[]".');
         }
 
         /**
@@ -617,6 +618,10 @@ class Compiler implements C.ICompiler {
 
                 return this._compileModifierTYPE(ctx, rules.slice(1));
             }
+            case M.ENUM: {
+
+                return this._compileModifierEnum(ctx, rules.slice(1));
+            }
         }
 
         throw new TypeError(`Unknown modifier "${rules[0]}".`);
@@ -630,7 +635,7 @@ class Compiler implements C.ICompiler {
 
         const result = this._compileModifiedRule(ctx, rules);
 
-        ctx.untrap();
+        ctx.popUp();
 
         return result;
     }
@@ -645,7 +650,7 @@ class Compiler implements C.ICompiler {
 
             result.push(this._compile(ctx, r));
 
-            ctx.untrap();
+            ctx.popUp();
         }
 
         return this._lang.or(result);
@@ -687,6 +692,7 @@ class Compiler implements C.ICompiler {
                 [CLOSURE_PARAM],
                 [CLOSURE_ARG],
                 this._lang.series([
+                    // eslint-disable-next-line @litert/rules/disable-for-each-method
                     this._lang.forEach(
                         CLOSURE_PARAM, vIter, ctx.vName, this._lang.ifThen(
                             this._lang.not(this._compile(ctx, rules)),
@@ -698,7 +704,7 @@ class Compiler implements C.ICompiler {
             ));
         }
 
-        ctx.untrap();
+        ctx.popUp();
 
         return this._lang.and(result);
     }
@@ -819,6 +825,7 @@ class Compiler implements C.ICompiler {
                 [CLOSURE_PARAM],
                 [CLOSURE_ARG],
                 this._lang.series([
+                    // eslint-disable-next-line @litert/rules/disable-for-each-method
                     this._lang.forEach(
                         CLOSURE_PARAM, vIter, ctx.vName, this._lang.ifThen(
                             this._lang.not(this._compile(ctx, rules.slice(1))),
@@ -830,7 +837,7 @@ class Compiler implements C.ICompiler {
             ));
         }
 
-        ctx.untrap();
+        ctx.popUp();
 
         return this._lang.and(result);
     }
@@ -946,7 +953,7 @@ class Compiler implements C.ICompiler {
                 tupleLength++;
             }
 
-            ctx.untrap();
+            ctx.popUp();
         }
 
         if (tupleLength >= 0) {
@@ -975,23 +982,13 @@ class Compiler implements C.ICompiler {
         return this._lang.and(result);
     }
 
-    private _validateTypeName(name: unknown): void {
-
-        if (typeof name !== 'string' || !I.RE_VALID_CUSTOM_TYPE_NAME.test(name)) {
-
-            throw new TypeError(`Invalid name ${
-                JSON.stringify(name)
-            } for a pre-defined type.`);
-        }
-    }
-
     private _compileModifierTYPE(ctx: I.IContext, rules: any[]): string {
 
-        this._validateTypeName(rules[0]);
+        I.validateTypeName(rules[0]);
 
         if (this._defTypes[rules[0]]) {
 
-            throw new Error(`Dplicated name ${JSON.stringify(rules[0])} for a pre-defined type.`);
+            throw new Error(`Duplicated name ${JSON.stringify(rules[0])} for a pre-defined type.`);
         }
 
         this._defTypes[rules[0]] = this.compile({
@@ -1015,7 +1012,7 @@ class Compiler implements C.ICompiler {
 
         const ret = this._compile(ctx, rules);
 
-        ctx.untrap();
+        ctx.popUp();
 
         return ret;
     }
@@ -1033,7 +1030,7 @@ class Compiler implements C.ICompiler {
 
         const ret = this._compile(ctx, rules);
 
-        ctx.untrap();
+        ctx.popUp();
 
         return ret;
     }
@@ -1057,7 +1054,7 @@ class Compiler implements C.ICompiler {
         ctx.tracePath = `${ctx.tracePath}[${this._lang.stringTemplateVar(vKey)}]`;
 
         const result = this._lang.and([
-            this._lang.isStrucutre(vCArg, true),
+            this._lang.isStructure(vCArg, true),
             this._lang.closure(
                 [vCParam],
                 [vCArg],
@@ -1073,11 +1070,41 @@ class Compiler implements C.ICompiler {
             )
         ]);
 
-        ctx.untrap();
+        ctx.popUp();
 
         return result;
     }
 
+    private _compileModifierEnum(ctx: I.IContext, rules: any[]): string {
+
+        if (rules.length === 0) {
+
+            throw new SyntaxError(`At least one enum candidate is required for $.enum`);
+        }
+
+        const ret: string[] = [];
+
+        for (const r of rules) {
+
+            switch (typeof r) {
+
+                case 'string':
+                case 'number':
+                case 'boolean':
+                    ret.push(this._lang.eq(ctx.vName, this._lang.literal(r)));
+                    break;
+                default:
+                    if (r === null) {
+                        ret.push(this._lang.eq(ctx.vName, this._lang.literal(null)));
+                        break;
+                    }
+                    throw new SyntaxError(`Invalid literal value ${JSON.stringify(rules)} for $.enum.`);
+            }
+        }
+
+        return this._lang.or(ret);
+    }
+
     private _compileModifierDICT(ctx: I.IContext, rules: any[]): string {
 
         if (rules.length < 2 || !Array.isArray(rules[0])) {
@@ -1094,7 +1121,7 @@ class Compiler implements C.ICompiler {
             rules.slice(1)
         ]);
 
-        const type = `${I.PREDEF_TYPE_SYMBOL}${this._lang.varName(id)}`;
+        const type = `${I.PRE_DEF_TYPE_SYMBOL}${this._lang.varName(id)}`;
 
         for (const key of rules[0]) {
 
@@ -1119,7 +1146,7 @@ class Compiler implements C.ICompiler {
         const result: string[] = [
             this._addTraceOr(
                 ctx,
-                this._lang.isStrucutre(ctx.vName, true),
+                this._lang.isStructure(ctx.vName, true),
                 '!object'
             )
         ];
@@ -1212,7 +1239,7 @@ class Compiler implements C.ICompiler {
                 this._compile(ctx, rule)
             ));
 
-            ctx.untrap();
+            ctx.popUp();
         }
 
         if (strict && keys.length) {
@@ -1247,7 +1274,7 @@ class Compiler implements C.ICompiler {
         }
 
         const result: string[] = [
-            this._lang.isStrucutre(ctx.vName, true)
+            this._lang.isStructure(ctx.vName, true)
         ];
 
         ctx.trap();
@@ -1364,7 +1391,7 @@ class Compiler implements C.ICompiler {
                 ));
             }
 
-            ctx.untrap();
+            ctx.popUp();
         }
 
         if (keys.length) {
@@ -1389,7 +1416,7 @@ class Compiler implements C.ICompiler {
             ])
         ));
 
-        ctx.untrap();
+        ctx.popUp();
 
         return this._lang.and(result);
     }
@@ -1411,9 +1438,9 @@ class Compiler implements C.ICompiler {
  */
 export function createCompiler(lang: C.ILanguageBuilder): C.ICompiler {
 
-    const bitc = new BuiltInTypeCompiler(lang);
+    const ret = new BuiltInTypeCompiler(lang);
 
     return new Compiler(
-        lang, bitc, new FilterCompiler(lang, bitc)
+        lang, ret, new FilterCompiler(lang, ret)
     );
 }

package/src/lib/Context.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2022 Angus Fenying <fenying@litert.org>
+ * Copyright 2023 Angus Fenying <fenying@litert.org>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -71,7 +71,7 @@ export class Context implements i.IContext {
         }
     }
 
-    public untrap(): void {
+    public popUp(): void {
 
         const prev = this.stack.pop();
 

package/src/lib/FilterCompiler.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2022 Angus Fenying <fenying@litert.org>
+ * Copyright 2023 Angus Fenying <fenying@litert.org>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -22,7 +22,7 @@ implements I.IFilterCompiler {
 
     public constructor(
         private readonly _lang: C.ILanguageBuilder,
-        private readonly _bitc: I.IBuiltInTypeCompiler
+        private readonly _memCompiler: I.IBuiltInTypeCompiler
     ) {}
 
     public compile(rule: string, ctx: I.IContext): string {
@@ -51,7 +51,7 @@ implements I.IFilterCompiler {
                 ret.push(this._lang.isNumber(vName, true));
                 break;
             default:
-                ret.push(this._bitc.compile(filter[0], ctx, []));
+                ret.push(this._memCompiler.compile(filter[0], ctx, []));
                 break;
         }
 

package/src/lib/InlineCompiler.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2022 Angus Fenying <fenying@litert.org>
+ * Copyright 2023 Angus Fenying <fenying@litert.org>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -50,7 +50,7 @@ export interface IInlineCompiler {
      * @param name      The name of the pre-defined type (without prefix `@`)
      * @param checker   The checker callback of the pre-defined type.
      */
-    addPredefinedType<T>(name: string, checker: C.ITypeChecker<T>): this;
+    addPredefinedType<T>(name: string, checker: C.IPreDefinedTypeChecker<T>): this;
 
     /**
      * Check if a pre-defined type is compiled.
@@ -91,12 +91,12 @@ implements IInlineCompiler {
 
         const result = this._compiler.compile(options);
 
-        this._preapreDefinedTypes(result.referredTypes, options.stopOnEntry);
+        this._prepareDefinedTypes(result.referredTypes, options.stopOnEntry);
 
         return this._wrapCheckerCode(result, options.stopOnEntry);
     }
 
-    private _preapreDefinedTypes(
+    private _prepareDefinedTypes(
         types: string[],
         stopOnEntry?: boolean
     ): void {
@@ -118,7 +118,7 @@ implements IInlineCompiler {
 
             this._defTypes[x] = this._wrapCheckerCode(info, stopOnEntry);
 
-            this._preapreDefinedTypes(info.referredTypes);
+            this._prepareDefinedTypes(info.referredTypes);
 
             delete this._missingTypes[x];
         }
@@ -126,10 +126,7 @@ implements IInlineCompiler {
 
     public addPredefinedType(name: string, checker: C.ITypeChecker<any>): this {
 
-        if (!I.RE_VALID_CUSTOM_TYPE_NAME.test(name)) {
-
-            throw new TypeError(`Invalid name ${ JSON.stringify(name) } for a pre-defined type.`);
-        }
+        I.validateTypeName(name);
 
         this._defTypes[name] = checker;
 

package/src/lib/Internal.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2022 Angus Fenying <fenying@litert.org>
+ * Copyright 2023 Angus Fenying <fenying@litert.org>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,7 +24,7 @@ export const FILTER_PREFIX = '|';
 
 export const IMPLICIT_SYMBOL = '?';
 
-export const PREDEF_TYPE_SYMBOL = '@';
+export const PRE_DEF_TYPE_SYMBOL = '@';
 
 export const NEGATIVE_SYMBOL = '!';
 
@@ -95,7 +95,7 @@ export interface IContext extends IContextData {
 
     trap(subjChanged?: boolean): void;
 
-    untrap(): void;
+    popUp(): void;
 }
 
 export interface IFilterCompiler {
@@ -126,4 +126,73 @@ export interface IBuiltInTypeCompiler {
     isElemental(type: string): boolean;
 }
 
-export const RE_VALID_CUSTOM_TYPE_NAME = /^[-:.\w]+$/;
+const RE_VALID_CUSTOM_TYPE_NAME = /^[-:.\w]+$/;
+
+export interface IPreDefinedCallExpr {
+
+    name: string;
+
+    args: any[];
+}
+
+export function validateTypeName(name: string): void {
+
+    if (typeof name !== 'string' || !RE_VALID_CUSTOM_TYPE_NAME.test(name)) {
+
+        throw new TypeError(`Invalid name ${
+            JSON.stringify(name)
+        } for a pre-defined type.`);
+    }
+}
+
+export function decodePreDefinedCallExpr(input: string): IPreDefinedCallExpr {
+
+    let expr = input;
+
+    expr = expr.replace(/\\['"]/g, (i) => `\\u00${i.charCodeAt(1).toString(16)}`);
+
+    const r = /^([-:.\w]+)\s*(\((.*)\))?$/.exec(expr);
+
+    if (!r) {
+
+        throw new SyntaxError(`Invalid type expression: ${input}`);
+    }
+
+    const fn = r[1];
+
+    expr = r[3];
+
+    if (!expr) {
+
+        return { name: fn, args: [] };
+    }
+
+    const args = [];
+
+    while (expr) {
+
+        const m = /^\s*([-]?\d+(\.\d+)?|[-]?0x[a-fA-F0-9]+|true|false|null|"[^"]+"|'[^']+')\s*(,|$)/i.exec(expr);
+
+        if (!m) {
+
+            throw new SyntaxError(`Invalid type expression "${expr}" in "${input}"`);
+        }
+
+        expr = expr.slice(m[0].length);
+
+        if (m[1].startsWith("'") && m[1].endsWith("'")) {
+            args.push(JSON.parse(`"${m[1].slice(1, -1)}"`));
+        }
+        else if (m[1].startsWith('0x')) {
+            args.push(parseInt(m[1].slice(2), 16));
+        }
+        else if (m[1].startsWith('-0x')) {
+            args.push(-parseInt(m[1].slice(3), 16));
+        }
+        else {
+            args.push(JSON.parse(m[1]));
+        }
+    }
+
+    return { name: fn, args };
+}

package/src/lib/Modifiers.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2022 Angus Fenying <fenying@litert.org>
+ * Copyright 2023 Angus Fenying <fenying@litert.org>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -43,3 +43,5 @@ export const EQUAL: string = `${I.MODIFIER_PREFIX}equal`;
 export const TAG: string = `${I.MODIFIER_PREFIX}tag`;
 
 export const TYPE: string = `${I.MODIFIER_PREFIX}type`;
+
+export const ENUM: string = `${I.MODIFIER_PREFIX}enum`;

package/src/lib/index.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2022 Angus Fenying <fenying@litert.org>
+ * Copyright 2023 Angus Fenying <fenying@litert.org>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

package/src/lib/langs/JavaScript.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2022 Angus Fenying <fenying@litert.org>
+ * Copyright 2023 Angus Fenying <fenying@litert.org>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -227,7 +227,7 @@ implements C.ILanguageBuilder {
         return `typeof ${vn} ${this._equal(positive)} "string"`;
     }
 
-    public isStrucutre(vn: string, positive: boolean = true): string {
+    public isStructure(vn: string, positive: boolean = true): string {
 
         return positive ?
             `(typeof ${vn} === "object" && ${vn} !== null && !Array.isArray(${vn}))` :

package/src/test/00-all.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2022 Angus Fenying <fenying@litert.org>
+ * Copyright 2023 Angus Fenying <fenying@litert.org>
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.