@litert/typeguard 1.1.0 → 1.3.0

package/src/lib/Compiler.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2021 Angus.Fenying <fenying@litert.org>
+ * Copyright 2022 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,15 +22,14 @@ import * as B from './BuiltInTypes';
 import { BuiltInTypeCompiler } from './BuiltInTypeCompiler';
 import { FilterCompiler } from './FilterCompiler';
 
-class Compiler
-implements C.ICompiler {
+class Compiler implements C.ICompiler {
 
     private _defTypes: Record<string, C.ICompileResult>;
 
     public constructor(
-        private _lang: C.ILanguageBuilder,
-        private _builtInTypes: I.IBuiltInTypeCompiler,
-        private _filters: I.IFilterCompiler
+        private readonly _lang: C.ILanguageBuilder,
+        private readonly _builtInTypes: I.IBuiltInTypeCompiler,
+        private readonly _filters: I.IFilterCompiler
     ) {
         this._defTypes = {};
     }
@@ -45,12 +44,43 @@ implements C.ICompiler {
         return null;
     }
 
+    private _addTrace(ctx: I.IContext): string {
+
+        if (!ctx.vTraceName) {
+
+            return this._lang.literalFalse;
+        }
+
+        return this._lang.addTrace(
+            ctx.vTraceName,
+            ctx.vTracePrefix,
+            ctx.tracePath
+        );
+    }
+
+    private _addTraceOr(ctx: I.IContext, expr: string, subPath: string = ''): string {
+
+        if (!ctx.vTraceName) {
+
+            return expr;
+        }
+
+        return this._lang.orAddTrace(
+            expr,
+            ctx.vTraceName,
+            ctx.vTracePrefix,
+            `${ctx.tracePath}${subPath}`
+        );
+    }
+
     public compile(options: C.ICompileOptions): C.ICompileResult {
 
         const referredTypes: Record<string, true> = {};
 
         const ctx: I.IContext = new Context(
             this._lang.varName('entry'),
+            options.traceErrors ? this._lang.varName('failedAsserts') : '',
+            options.traceErrors ? this._lang.varName('tracePrefix') : '',
             this._lang.varName('types'),
             referredTypes
         );
@@ -71,12 +101,28 @@ implements C.ICompiler {
                 source: '',
                 arguments: [{
                     'name': ctx.vName,
-                    'type': 'unknown'
+                    'type': 'unknown',
+                    'initial': ''
                 }],
                 typeSlotName: ctx.typeSlotName,
                 referredTypes: []
             };
 
+            if (ctx.vTraceName) {
+
+                ret.arguments.push({
+                    'name': ctx.vTraceName,
+                    'type': 'string[]',
+                    'initial': '[]'
+                });
+
+                ret.arguments.push({
+                    'name': ctx.vTracePrefix,
+                    'type': 'string',
+                    'initial': this._lang.literal('data')
+                });
+            }
+
             ret.source = this._compile(
                 ctx,
                 options.rule
@@ -164,6 +210,9 @@ implements C.ICompiler {
             case 'undefined':
 
                 return this._lang.isUndefined(ctx.vName, true);
+
+            default:
+                break;
         }
 
         throw new TypeError('Unknwn rules.');
@@ -197,53 +246,65 @@ implements C.ICompiler {
         let regResult: RegExpMatchArray | null = /\[\s*(\d*|\d+\s*,\s*\d*)\s*\]$/.exec(rule);
 
         /**
-         * For rules like `xxx[123]` or `xxx[1,5]`.
+         * For rules like `xxx[123]` or `xxx[1,5]` or `xxx[1,]`.
          */
         if (regResult) {
 
             if (regResult[1]) {
 
-                let range = regResult[1].split(',').map((x) => parseInt(x.trim()));
+                const range = regResult[1].split(',').map((x) => parseInt(x.trim()));
 
                 if (range.length === 1) {
 
+                    /**
+                     * For rules like `xxx[123]`.
+                     */
                     return this._compileModifiedRule(ctx, [
                         M.ARRAY,
                         range[0],
-                        rule.substr(0, regResult.index)
+                        rule.slice(0, regResult.index)
                     ]);
                 }
                 else if (Number.isNaN(range[1])) {
 
+                    /**
+                     * For rules like `xxx[1,]`.
+                     */
                     return this._compileModifiedRule(ctx, [
                         M.ARRAY,
                         [range[0]],
-                        rule.substr(0, regResult.index)
+                        rule.slice(0, regResult.index)
                     ]);
                 }
                 else {
 
+                    /**
+                     * For rules like `xxx[1,5]`.
+                     */
                     return this._compileModifiedRule(ctx, [
                         M.ARRAY,
                         range,
-                        rule.substr(0, regResult.index)
+                        rule.slice(0, regResult.index)
                     ]);
                 }
             }
             else {
 
+                /**
+                 * For rules like `xxx[]`.
+                 */
                 return this._compileModifiedRule(ctx, [
                     M.LIST,
-                    rule.substr(0, regResult.index)
+                    rule.slice(0, regResult.index)
                 ]);
             }
         }
 
-        /**
-         * For rules like `xxx{}`.
-         */
         if (rule.endsWith(I.MAP_SUFFIX)) {
 
+            /**
+             * For rules like `xxx{}`.
+             */
             return this._lang.and([
                 this._compileModifiedRule(ctx, [
                     M.MAP,
@@ -324,7 +385,7 @@ implements C.ICompiler {
 
         const offset = assertRule ? assertRule[1].length + 2 : 2;
 
-        switch ((assertRule?.[1]) ?? rule.substr(0, 2)) {
+        switch ((assertRule?.[1]) ?? rule.slice(0, 2)) {
             case '==':
             case 'equal':
 
@@ -576,7 +637,7 @@ implements C.ICompiler {
 
     private _compileModifierOR(ctx: I.IContext, rules: any[]): string {
 
-        let result: string[] = [];
+        const result: string[] = [];
 
         for (const r of rules) {
 
@@ -597,7 +658,7 @@ implements C.ICompiler {
         );
     }
 
-    private _compileModifierLIST(ctx: I.IContext, rules: any[]): string {
+    private _compileModifierLIST(ctx: I.IContext, rules: any[], traceOffset: number = 0): string {
 
         const result: string[] = [];
 
@@ -615,6 +676,10 @@ implements C.ICompiler {
         const CLOSURE_PARAM = this._lang.varName(ctx.vCursor++);
 
         ctx.vName = this._lang.varName(ctx.vCursor++);
+        const vIter = this._lang.varName(ctx.vCursor++);
+        ctx.tracePath = `${ctx.tracePath}[${this._lang.numberTemplateVar(
+            traceOffset ? this._lang.add(traceOffset, vIter) : vIter
+        )}]`;
 
         if (rules[0] !== B.ANY) {
 
@@ -623,9 +688,9 @@ implements C.ICompiler {
                 [CLOSURE_ARG],
                 this._lang.series([
                     this._lang.forEach(
-                        CLOSURE_PARAM, ctx.vName, this._lang.ifThen(
+                        CLOSURE_PARAM, vIter, ctx.vName, this._lang.ifThen(
                             this._lang.not(this._compile(ctx, rules)),
-                            this._lang.returnValue(this._lang.literal(false))
+                            this._lang.returnValue(this._addTrace(ctx))
                         )
                     ),
                     this._lang.returnValue(this._lang.literal(true))
@@ -638,7 +703,7 @@ implements C.ICompiler {
         return this._lang.and(result);
     }
 
-    private _compileModifierARRAY(ctx: I.IContext, rules: any[]): string {
+    private _compileModifierARRAY(ctx: I.IContext, rules: any[], traceOffset: number = 0): string {
 
         let a: number = 0;
         let b: number = -1;
@@ -718,6 +783,10 @@ implements C.ICompiler {
         const CLOSURE_PARAM = this._lang.varName(ctx.vCursor++);
 
         ctx.vName = this._lang.varName(ctx.vCursor++);
+        const vIter = this._lang.varName(ctx.vCursor++);
+        ctx.tracePath = `${ctx.tracePath}[${this._lang.numberTemplateVar(
+            traceOffset ? this._lang.add(traceOffset, vIter) : vIter
+        )}]`;
 
         switch (b) {
             case -1: {
@@ -751,9 +820,9 @@ implements C.ICompiler {
                 [CLOSURE_ARG],
                 this._lang.series([
                     this._lang.forEach(
-                        CLOSURE_PARAM, ctx.vName, this._lang.ifThen(
+                        CLOSURE_PARAM, vIter, ctx.vName, this._lang.ifThen(
                             this._lang.not(this._compile(ctx, rules.slice(1))),
-                            this._lang.returnValue(this._lang.literal(false))
+                            this._lang.returnValue(this._addTrace(ctx))
                         )
                     ),
                     this._lang.returnValue(this._lang.literal(true))
@@ -783,6 +852,7 @@ implements C.ICompiler {
 
         const types = rules.slice();
         let tupleLength = 0;
+        let tupleLengthMin = 0;
 
         while (1) {
 
@@ -819,10 +889,11 @@ implements C.ICompiler {
                     if (type !== 'any') {
 
                         result.push(this._compileModifierLIST(
-                            ctx, type
+                            ctx, type, i
                         ));
                     }
 
+                    tupleLengthMin = tupleLength;
                     tupleLength = -1;
                 }
                 else if (!/^\d+$/.test(dots.slice(3))) {
@@ -833,22 +904,27 @@ implements C.ICompiler {
 
                     const length = parseInt(dots.slice(3));
 
-                    if (length <= 3) {
+                    if (length === 0) {
 
-                        const vName = ctx.vName;
+                        throw new TypeError(`Invalid syntax for tuple: ${dots}`);
+                    }
+                    else if (length === 1) {
 
-                        for (let j = 0; j < length; j++) {
+                        const vName = ctx.vName;
 
-                            ctx.vName = this._lang.arrayIndex(vName, i++);
-                            result.push(this._compile(ctx, type));
-                        }
+                        ctx.tracePath = `${ctx.tracePath}[${i}]`;
+                        ctx.vName = this._lang.arrayIndex(vName, i++);
+                        result.push(this._addTraceOr(
+                            ctx,
+                            this._compile(ctx, type),
+                        ));
                     }
                     else {
 
                         ctx.vName = this._lang.arraySlice(ctx.vName, i, i + length);
 
                         result.push(this._compileModifierARRAY(
-                            ctx, [length, type]
+                            ctx, [length, type], i
                         ));
 
                         i += length;
@@ -861,8 +937,12 @@ implements C.ICompiler {
 
                 ctx.trap(true);
 
+                ctx.tracePath = `${ctx.tracePath}[${i}]`;
                 ctx.vName = this._lang.arrayIndex(ctx.vName, i++);
-                result.push(this._compile(ctx, type));
+                result.push(this._addTraceOr(
+                    ctx,
+                    this._compile(ctx, type),
+                ));
                 tupleLength++;
             }
 
@@ -871,9 +951,24 @@ implements C.ICompiler {
 
         if (tupleLength >= 0) {
 
-            result.splice(1, -1, this._lang.eq(
-                this._lang.arrayLength(ctx.vName),
-                tupleLength
+            result.splice(1, -1, this._addTraceOr(
+                ctx,
+                this._lang.eq(
+                    this._lang.arrayLength(ctx.vName),
+                    tupleLength
+                ),
+                '.length'
+            ));
+        }
+        else if (tupleLengthMin >= 0) {
+
+            result.splice(1, -1, this._addTraceOr(
+                ctx,
+                this._lang.gte(
+                    this._lang.arrayLength(ctx.vName),
+                    tupleLengthMin
+                ),
+                '.length'
             ));
         }
 
@@ -882,7 +977,7 @@ implements C.ICompiler {
 
     private _validateTypeName(name: unknown): void {
 
-        if (typeof name !== 'string' || !/^[-:.\w]+$/.test(name)) {
+        if (typeof name !== 'string' || !I.RE_VALID_CUSTOM_TYPE_NAME.test(name)) {
 
             throw new TypeError(`Invalid name ${
                 JSON.stringify(name)
@@ -900,7 +995,8 @@ implements C.ICompiler {
         }
 
         this._defTypes[rules[0]] = this.compile({
-            rule: rules.slice(1)
+            rule: rules.slice(1),
+            traceErrors: !!ctx.vTraceName
         });
 
         return this._usePredefinedType(ctx, rules[0]);
@@ -951,24 +1047,25 @@ implements C.ICompiler {
 
         ctx.trap(true);
 
-        const CLOSURE_ARG = ctx.vName;
+        const vCArg = ctx.vName;
 
-        const CLOSURE_PARAM = this._lang.varName(ctx.vCursor++);
+        const vCParam = this._lang.varName(ctx.vCursor++);
 
-        const FOR_IN_KEY = this._lang.varName(ctx.vCursor++);
+        const vKey = this._lang.varName(ctx.vCursor++);
 
         ctx.vName = this._lang.varName(ctx.vCursor++);
+        ctx.tracePath = `${ctx.tracePath}[${this._lang.stringTemplateVar(vKey)}]`;
 
         const result = this._lang.and([
-            this._lang.isStrucutre(CLOSURE_ARG, true),
+            this._lang.isStrucutre(vCArg, true),
             this._lang.closure(
-                [CLOSURE_PARAM],
-                [CLOSURE_ARG],
+                [vCParam],
+                [vCArg],
                 this._lang.series([
                     this._lang.forIn(
-                        CLOSURE_PARAM, FOR_IN_KEY, ctx.vName, this._lang.ifThen(
+                        vCParam, vKey, ctx.vName, this._lang.ifThen(
                             this._lang.not(this._compile(ctx, rules)),
-                            this._lang.returnValue(this._lang.literal(false))
+                            this._lang.returnValue(this._addTrace(ctx))
                         )
                     ),
                     this._lang.returnValue(this._lang.literal(true))
@@ -988,7 +1085,7 @@ implements C.ICompiler {
             throw new SyntaxError(`Invalid dict ${JSON.stringify(rules)}.`);
         }
 
-        let tmp: Record<string, string> = {};
+        const tmp: Record<string, string> = {};
 
         const id = `${Date.now()}${Math.floor(Math.random() * Number.MAX_SAFE_INTEGER)}`;
 
@@ -999,7 +1096,7 @@ implements C.ICompiler {
 
         const type = `${I.PREDEF_TYPE_SYMBOL}${this._lang.varName(id)}`;
 
-        for (let key of rules[0]) {
+        for (const key of rules[0]) {
 
             if (typeof key !== 'string') {
 
@@ -1020,7 +1117,11 @@ implements C.ICompiler {
         const strict = !!ctx.flags[I.EFlags.STRICT];
 
         const result: string[] = [
-            this._lang.isStrucutre(ctx.vName, true)
+            this._addTraceOr(
+                ctx,
+                this._lang.isStrucutre(ctx.vName, true),
+                '!object'
+            )
         ];
 
         const keys: string[] = [];
@@ -1104,8 +1205,12 @@ implements C.ICompiler {
             keys.push(k);
 
             ctx.vName = this._lang.fieldIndex(ctx.vName, this._lang.literal(k));
+            ctx.tracePath = `${ctx.tracePath}[${this._lang.literal(k)}]`;
 
-            result.push(this._compile(ctx, rule));
+            result.push(this._addTraceOr(
+                ctx,
+                this._compile(ctx, rule)
+            ));
 
             ctx.untrap();
         }

package/src/lib/Context.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2021 Angus.Fenying <fenying@litert.org>
+ * Copyright 2022 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.
@@ -18,18 +18,18 @@ import * as i from './Internal';
 
 export class Context implements i.IContext {
 
-    public trace: boolean;
-
-    public tracePoint: number;
-
     public vCursor: number;
 
     public stack: i.IContextData[];
 
     public flags: Record<string, i.EFlagValue>;
 
+    public tracePath: string = '';
+
     public constructor(
         public vName: string,
+        public vTraceName: string,
+        public vTracePrefix: string,
         public readonly typeSlotName: string,
         public readonly referredTypes: Record<string, boolean>
     ) {
@@ -38,17 +38,14 @@ export class Context implements i.IContext {
         this.vCursor = 0;
 
         this.flags = {};
-
-        this.tracePoint = 0;
-
-        this.trace = false;
     }
 
     public trap(subjChanged: boolean = false): void {
 
         this.stack.push({
             vName: this.vName,
-            flags: this.flags
+            flags: this.flags,
+            tracePath: this.tracePath,
         });
 
         const prevFlags = this.flags;
@@ -83,7 +80,8 @@ export class Context implements i.IContext {
             throw new Error('Failed to pop stack.');
         }
 
-        this.vName = prev.vName;
         this.flags = prev.flags;
+        this.vName = prev.vName;
+        this.tracePath = prev.tracePath;
     }
 }

package/src/lib/FilterCompiler.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2021 Angus.Fenying <fenying@litert.org>
+ * Copyright 2022 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.
@@ -21,8 +21,8 @@ export class FilterCompiler
 implements I.IFilterCompiler {
 
     public constructor(
-        private _lang: C.ILanguageBuilder,
-        private _bitc: I.IBuiltInTypeCompiler
+        private readonly _lang: C.ILanguageBuilder,
+        private readonly _bitc: I.IBuiltInTypeCompiler
     ) {}
 
     public compile(rule: string, ctx: I.IContext): string {
@@ -36,7 +36,7 @@ implements I.IFilterCompiler {
             throw new TypeError('Only number is allowed as filter arguments.');
         }
 
-        let ret: string[] = [];
+        const ret: string[] = [];
 
         switch (filter[0]) {
             case 'array.length':

package/src/lib/InlineCompiler.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2021 Angus.Fenying <fenying@litert.org>
+ * Copyright 2022 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.
@@ -17,6 +17,7 @@
 import { createCompiler } from './Compiler';
 import { createJavaScriptLanguageBuilder } from './langs/JavaScript';
 import * as C from './Common';
+import * as I from './Internal';
 
 export interface IInlineCompileOptions extends C.ICompileOptions {
 
@@ -34,14 +35,22 @@ export interface IInlineCompiler {
      *
      * @param options The options of compilation.
      */
-    compile<T>(options: IInlineCompileOptions): C.TypeChecker<T>;
+    compile<T>(options: IInlineCompileOptions): C.ITypeChecker<T>;
 
     /**
      * Get the type-checker of a pre-defined type.
      *
      * @param name The name of the pre-defined type.
      */
-    getPredefinedType<T>(name: string): C.TypeChecker<T>;
+    getPredefinedType<T>(name: string): C.ITypeChecker<T>;
+
+    /**
+     * Register a pre-defined type checker.
+     *
+     * @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;
 
     /**
      * Check if a pre-defined type is compiled.
@@ -59,11 +68,11 @@ export interface IInlineCompiler {
 class InlineCompiler
 implements IInlineCompiler {
 
-    private _defTypes: Record<string, C.TypeChecker<any>>;
+    private _defTypes: Record<string, C.ITypeChecker<any>>;
 
     private _missingTypes: Record<string, boolean>;
 
-    private _compiler: C.ICompiler;
+    private readonly _compiler: C.ICompiler;
 
     public constructor() {
 
@@ -78,7 +87,7 @@ implements IInlineCompiler {
         );
     }
 
-    public compile<T>(options: IInlineCompileOptions): C.TypeChecker<T> {
+    public compile<T>(options: IInlineCompileOptions): C.ITypeChecker<T> {
 
         const result = this._compiler.compile(options);
 
@@ -92,7 +101,7 @@ implements IInlineCompiler {
         stopOnEntry?: boolean
     ): void {
 
-        for (let x of types) {
+        for (const x of types) {
 
             if (this._defTypes[x]) {
 
@@ -115,6 +124,18 @@ 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.`);
+        }
+
+        this._defTypes[name] = checker;
+
+        return this;
+    }
+
     public detectUndefinedTypes(): string[] {
 
         return Object.keys(this._missingTypes);
@@ -125,7 +146,7 @@ implements IInlineCompiler {
         return !!this._defTypes[name];
     }
 
-    public getPredefinedType(name: string): C.TypeChecker<any> {
+    public getPredefinedType(name: string): C.ITypeChecker<any> {
 
         if (!this._defTypes[name]) {
 
@@ -138,13 +159,18 @@ implements IInlineCompiler {
     private _wrapCheckerCode(
         info: C.ICompileResult,
         stopOnEntry: boolean = false
-    ): C.TypeChecker<any> {
+    ): C.ITypeChecker<any> {
 
         const soe = stopOnEntry ? 'debugger;' : '';
 
         return (new Function(
             info.typeSlotName,
-            `return function(${info.arguments[0].name}) {${soe}
+            `return function(${
+                info.arguments
+                    .map((a) => a.initial ? `${a.name} = ${a.initial}` : a.name)
+                    .join(',')
+            }) {
+                ${soe}
 
                 return ${info.source};
             };`

package/src/lib/Internal.ts

@@ -1,5 +1,5 @@
 /**
- * Copyright 2021 Angus.Fenying <fenying@litert.org>
+ * Copyright 2022 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.
@@ -72,16 +72,18 @@ export enum EFlagValue {
 
 export interface IContextData {
 
+    flags: Record<string, EFlagValue>;
+
     vName: string;
 
-    flags: Record<string, EFlagValue>;
+    tracePath: string;
 }
 
 export interface IContext extends IContextData {
 
-    trace: boolean;
+    vTraceName: string;
 
-    tracePoint: number;
+    vTracePrefix: string;
 
     vCursor: number;
 
@@ -123,3 +125,5 @@ export interface IBuiltInTypeCompiler {
 
     isElemental(type: string): boolean;
 }
+
+export const RE_VALID_CUSTOM_TYPE_NAME = /^[-:.\w]+$/;