xjs-common 12.0.0-alpha.2 → 13.0.0-alpha.1

package/README.md

@@ -27,6 +27,7 @@ import { delay, int2array, UHttp, retry, MaybeArray, Loggable } from "xjs-common
     retry(async () => { }, { count: 2 });
 
     // utility types
+    let dateCtor: Ctor = Date; // constructor type like class type.
     let maybeArray: MaybeArray<number> = 0; // also number array is applicable.
     let logger: Loggable = console; // object implements log/warn/error is applicable.
 
@@ -124,18 +125,8 @@ this flag is true by default at the target higher than `ES2022`, [here is for mo
 ```ts
 import { Type, DType, UType, UObj } from "xjs-common";
 
-class Cls_A {
-    @DType.required
-    @DType.number
-    id: number;
-    @DType.string
-    strA: string;
-    @DType.recursive
-    objA: Cls_B;
-    p: number;
-    constructor() { }
-}
-class Cls_B {
+interface If_B { aryB: number[], boolB: boolean, q: number }
+class Cls_B implements If_B {
     @DType.array({ t: Type.number })
     aryB: number[];
     @DType.boolean
@@ -143,37 +134,51 @@ class Cls_B {
     q: number;
     constructor() { }
 }
+interface If_A { id: number, strA: string, objA: If_B, p: number }
+class Cls_A implements If_A {
+    @DType.required
+    @DType.number
+    id: number;
+    @DType.string
+    strA: string;
+    @DType.recursive(Cls_B)
+    objA: If_B;
+    p: number;
+    constructor(substance?: If_A) { Object.assign(this, substance); }
+}
 (() => {
-    const valid_b1 = Object.assign(new Cls_B(), { aryB: [1, 2, 3], boolB: true, q: 1 });
-    const valid1 = Object.assign(new Cls_A(), { id: 1, strA: "a", objA: valid_b1, p: 1 });
+    const valid_b1: If_B = { aryB: [1, 2, 3], boolB: true, q: 1 };
+    const valid_a1: If_A = { id: 1, strA: "a", objA: valid_b1, p: 1 };
 
     // remove non decorated fields.
-    const cropped = UObj.crop(valid1);
-    console.log(!!cropped.id && !cropped.p && !!cropped.objA.aryB && !cropped.objA.q) // true;
+    const cropped = UObj.crop(valid_a1, Cls_A);
+    console.log(!!cropped.id && !cropped.p); // true;
+    console.log(!!cropped.objA.aryB && !cropped.objA.q); // true
 
-    // validation. below are valid cases.
-    console.log(UType.validate(valid1)); // []
+    // passing class object instead of ctor is allowed.
+    UObj.crop(new Cls_A(valid_a1));
 
-    const valid2 = { id: 0 };
-    console.log(UType.validate(Object.assign(new Cls_A(), valid2))); // []
+    // validation. below are valid cases.
+    console.log(UType.validate({ id: 0 }, Cls_A)); // []
+    console.log(UType.validate(valid_a1, Cls_A)); // []
 
     // validation. below are invalid cases.
     const invalid1 = {};
-    console.log(UType.validate(Object.assign(new Cls_A(), invalid1))); // [ 'id' ]
+    console.log(UType.validate(invalid1, Cls_A)); // [ 'id' ]
 
-    const invalid3 = { id: 0, strA: [], objA: valid_b1 };
-    console.log(UType.validate(Object.assign(new Cls_A(), invalid3))); // [ 'strA' ]
+    const invalid2 = { id: 0, strA: [], objA: valid_b1 };
+    console.log(UType.validate(invalid2, Cls_A)); // [ 'strA' ]
 
-    const invalid4 = { id: "0", strA: "a", objA: valid_b1 };
-    console.log(UType.validate(Object.assign(new Cls_A(), invalid4))); // [ 'id' ]
+    const invalid3 = { id: "0", strA: "a", objA: valid_b1 };
+    console.log(UType.validate(invalid3, Cls_A)); // [ 'id' ]
 
-    const invalid_b1 = Object.assign(new Cls_B(), { aryB: [1, 2, 3], boolB: 1 });
-    const invalid5 = { id: 0, strA: "a", objA: invalid_b1 };
-    console.log(UType.validate(Object.assign(new Cls_A(), invalid5))); // [ 'objA.boolB' ]
+    const invalid_b1 = { aryB: [1, 2, 3], boolB: 1 };
+    const invalid4 = { id: 0, strA: "a", objA: invalid_b1 };
+    console.log(UType.validate(invalid4, Cls_A)); // [ 'objA.boolB' ]
 
-    const invalid_b2 = Object.assign(new Cls_B(), { aryB: ["1"], boolB: true });
-    const invalid6 = { id: 0, strA: "a", objA: invalid_b2 };
-    console.log(UType.validate(Object.assign(new Cls_A(), invalid6))); // [ 'objA.aryB' ]
+    const invalid_b2 = { aryB: ["1"], boolB: true };
+    const invalid5 = { id: 0, strA: "a", objA: invalid_b2 };
+    console.log(UType.validate(invalid5, Cls_A)); // [ 'objA.aryB.0' ]
 })();
 ```
 # Error definition

package/build/const/types.d.ts

@@ -1,3 +1,6 @@
+export type Ctor<T = any> = {
+    new (): T;
+};
 export type IndexSignature = string | number | symbol;
 export type NormalRecord<T = any> = Record<IndexSignature, T>;
 export type MaybeArray<T = any> = T | T[];

package/build/func/decorator/d-type.d.ts

@@ -1,30 +1,12 @@
-import { Type } from "../../const/types";
+import { Ctor, Type } from "../../const/types";
 export declare const smbl_tm: unique symbol;
-interface BasicTypeDesc {
+export interface TypeDesc {
     t?: Type;
     req?: boolean;
-}
-export interface TypeDesc extends BasicTypeDesc {
     ary?: TypeDesc;
-    rec?: boolean;
     rcd?: TypeDesc;
+    obj?: Ctor;
 }
-type ArrayTypeDesc = TypeDesc & {
-    t?: never;
-    rec?: never;
-    rcd?: never;
-};
-type ClassTypeDesc = TypeDesc & {
-    t?: never;
-    ary?: never;
-    rcd?: never;
-};
-type RecordTypeDesc = TypeDesc & {
-    t?: never;
-    arys?: never;
-    rec?: never;
-};
-type AnyTypeDesc = BasicTypeDesc | ArrayTypeDesc | ClassTypeDesc | RecordTypeDesc;
 export interface TypeMap {
     [k: string]: TypeDesc;
 }
@@ -37,10 +19,9 @@ export declare namespace DType {
     function number(target: Object, propKey: string): void;
     function boolean(target: Object, propKey: string): void;
     function required(target: Object, propKey: string): void;
-    function array(elmDesc?: AnyTypeDesc): (target: Object, propKey: string) => void;
+    function array(elmDesc?: TypeDesc | Ctor): (target: Object, propKey: string) => void;
     /** NOTE: this may allow array type because array is essentialy object type has properties. */
-    function record(elmDesc?: AnyTypeDesc): (target: Object, propKey: string) => void;
-    function recursive(target: Object, propKey: string): void;
+    function record(elmDesc?: TypeDesc | Ctor): (target: Object, propKey: string) => void;
+    function recursive(ctor: Ctor): (target: Object, propKey: string) => void;
     function keep(target: Object, propKey: string): void;
 }
-export {};

package/build/func/decorator/d-type.js

@@ -1,5 +1,6 @@
 import { Type } from "../../const/types";
 import { XjsErr } from "../../obj/xjs-err";
+import { UType } from "../u-type";
 const s_errCode = 30;
 export const smbl_tm = Symbol.for("xjs:typeMap");
 /**
@@ -32,16 +33,16 @@ export var DType;
     }
     DType.required = required;
     function array(elmDesc = {}) {
-        return (target, propKey) => setDesc(target, propKey, (td) => td.ary = elmDesc);
+        return (target, propKey) => setDesc(target, propKey, (td) => UType.isFunction(elmDesc) ? td.ary = { obj: elmDesc } : td.ary = elmDesc);
     }
     DType.array = array;
     /** NOTE: this may allow array type because array is essentialy object type has properties. */
     function record(elmDesc = {}) {
-        return (target, propKey) => setDesc(target, propKey, (td) => td.rcd = elmDesc);
+        return (target, propKey) => setDesc(target, propKey, (td) => UType.isFunction(elmDesc) ? td.rcd = { obj: elmDesc } : td.rcd = elmDesc);
     }
     DType.record = record;
-    function recursive(target, propKey) {
-        setDesc(target, propKey, (td) => td.rec = true);
+    function recursive(ctor) {
+        return (target, propKey) => setDesc(target, propKey, (td) => td.obj = ctor);
     }
     DType.recursive = recursive;
     function keep(target, propKey) {
@@ -50,10 +51,10 @@ export var DType;
     DType.keep = keep;
     function setDesc(target, propKey, setter) {
         const map = target[smbl_tm] ? Object.assign({}, target[smbl_tm]) : {};
-        map[propKey] ??= { t: null, req: false, rec: false, ary: null, rcd: null };
+        map[propKey] ??= { t: null, req: false, obj: null, ary: null, rcd: null };
         const td = map[propKey];
         setter(td);
-        const structualDescs = [[td.ary, "array"], [td.rec, "recursive flag"], [td.rcd, "record"]].filter(e => e[0]);
+        const structualDescs = [[td.ary, "array"], [td.obj, "recursive"], [td.rcd, "record"]].filter(e => e[0]);
         if (structualDescs.length > 0) {
             let ex1 = null, ex2 = null;
             if (td.t) {

package/build/func/u-array.d.ts

@@ -3,11 +3,11 @@ export declare namespace UArray {
     /**
      * compares two arrays to valuate equality.
      * if one side is null or undefined, it returns true when other side is the same.
-     * this function has compatibility to `AlmostArray` like `Uint8Array` etc.
+     * this function has compatibility {@link AlmostArray} like {@link Uint8Array} etc.
      * @param v1 it uses equal operator for comparing elements, so applying object element is not recommended.
      * @param v2 same as v1.
      * @param sort it uses {@link Array.sort()} on v1 and v2 if true. default is true.
-     * @param useStrictEqual check equality whether `Array` or not and it uses `===` operator for compareing elements if true, otherwise using `==` operator. default is true.
+     * @param useStrictEqual check equality whether {@link Array} or not and it uses `===` operator for compareing elements if true, otherwise using `==` operator. default is true.
      */
     function eq(v1: any[] | AlmostArray, v2: any[] | AlmostArray, op?: {
         sort?: boolean;
@@ -28,7 +28,7 @@ export declare namespace UArray {
     }): T[];
     /**
      * chop array to partial arrays which have specified length. the remainder is added to end of a result.
-     * this function has compatibility to `AlmostArray` like `Uint8Array` etc.
+     * this function has compatibility to {@link AlmostArray} like {@link Uint8Array} etc.
      */
     function chop<E>(array: E[], len: number): E[][];
     function chop<T extends AlmostArray>(array: T, len: number): T[];

package/build/func/u-array.js

@@ -4,11 +4,11 @@ export var UArray;
     /**
      * compares two arrays to valuate equality.
      * if one side is null or undefined, it returns true when other side is the same.
-     * this function has compatibility to `AlmostArray` like `Uint8Array` etc.
+     * this function has compatibility {@link AlmostArray} like {@link Uint8Array} etc.
      * @param v1 it uses equal operator for comparing elements, so applying object element is not recommended.
      * @param v2 same as v1.
      * @param sort it uses {@link Array.sort()} on v1 and v2 if true. default is true.
-     * @param useStrictEqual check equality whether `Array` or not and it uses `===` operator for compareing elements if true, otherwise using `==` operator. default is true.
+     * @param useStrictEqual check equality whether {@link Array} or not and it uses `===` operator for compareing elements if true, otherwise using `==` operator. default is true.
      */
     function eq(v1, v2, op = {}) {
         const { sort, useStrictEqual } = Object.assign({ sort: true, useStrictEqual: true }, op);

package/build/func/u-obj.d.ts

@@ -1,4 +1,4 @@
-import { MaybeArray, NonObject, NormalRecord, Type } from "../const/types";
+import { Ctor, MaybeArray, NonObject, NormalRecord, Type } from "../const/types";
 export declare namespace UObj {
     /**
      * assign properties to the object with specified property keys.
@@ -9,12 +9,19 @@ export declare namespace UObj {
      */
     function assignProperties<T extends NormalRecord, S extends NormalRecord>(t: T, s: S, keys?: (keyof S)[], keepDtypeClass?: boolean): T & Partial<S>;
     /**
-     * crop properties of the object. the properties is removed with `delete` operator.
-     * @param o object whose properties is removed.
-     * @param keys property names to be remained. if omit this, it removes the properties other than properties decorated {@link DType}.
-     * @param exclusive if true, it removes `keys` instead of remaining it.
+     * crop properties of the object other than specified. the properties are to be removed with `delete` operator.
+     * @param o object whose properties to be removed.
+     * @param keys property names to be remained.
+     * @param removeKeys if true, it removes `keys` instead of remaining it.
      */
-    function crop<T extends NormalRecord>(o: T, keys?: (keyof T)[], exclusive?: boolean): Partial<T>;
+    function crop<T extends NormalRecord>(o: T, keys: (keyof T)[], removeKeys?: boolean): Partial<T>;
+    /**
+     * crop properties that is not decorated with {@link DType}. the properties will be removed with `delete` operator.
+     * this treats constructual decorator such as {@link DType.recursive} recursively.
+     * @param o object whose properties to be removed. if this is class object decorated with {@link DType}, it can omits `ctor` parameter.
+     * @param ctor class constructor type whose properties are decorated with {@link DType}. **NOTE** that need to have public constructor without any parameter.
+     */
+    function crop<T extends NormalRecord>(o: T, ctor?: Ctor): Partial<T>;
     /**
      * manipulate properties of an object.
      * as default if the properties contains object, it also manipulates properties of that recursively.

package/build/func/u-obj.js

@@ -20,20 +20,22 @@ export var UObj;
         return t;
     }
     UObj.assignProperties = assignProperties;
-    /**
-     * crop properties of the object. the properties is removed with `delete` operator.
-     * @param o object whose properties is removed.
-     * @param keys property names to be remained. if omit this, it removes the properties other than properties decorated {@link DType}.
-     * @param exclusive if true, it removes `keys` instead of remaining it.
-     */
-    function crop(o, keys, exclusive) {
-        if (!keys && !o[smbl_tm])
-            return {};
-        const _keys = keys ?? Object.keys(o[smbl_tm]);
+    function crop(o, keys_or_ctor, removeKeys) {
+        const tm = Array.isArray(keys_or_ctor) ? null
+            : (!keys_or_ctor || o instanceof keys_or_ctor ? o[smbl_tm] : new keys_or_ctor()[smbl_tm]);
+        const _keys = tm ? Object.keys(tm) : (keys_or_ctor ?? []);
+        if (_keys.length === 0)
+            return removeKeys ? o : {};
         Object.keys(o).filter(k => {
-            if (!keys && o[smbl_tm]?.[k]?.rec && o[k])
-                crop(o[k]);
-            return !!exclusive === _keys.includes(k);
+            if (tm && tm[k] && o[k]) {
+                if (tm[k].obj)
+                    crop(o[k], tm[k]?.obj);
+                else {
+                    const vCtor = tm[k].ary?.obj ?? tm[k].rcd?.obj;
+                    Object.values(o[k]).forEach(v => crop(v, vCtor));
+                }
+            }
+            return !!removeKeys === _keys.includes(k);
         }).forEach(k => delete o[k]);
         return o;
     }

package/build/func/u-type.d.ts

@@ -1,4 +1,4 @@
-import { MaybeArray, Type } from "../const/types";
+import { Ctor, MaybeArray, Type } from "../const/types";
 export declare namespace UType {
     function isDefined(v: any): boolean;
     function isEmpty(v: any): boolean;
@@ -17,10 +17,11 @@ export declare namespace UType {
     function isArray(v: any, t: Type.object): v is object[];
     function isArray(v: any): v is any[];
     /**
-     * validate properties which attached decorators in {@link DType}.
-     * @param o object to be validated.
+     * validate properties decorated with {@link DType}.
+     * @param o object to be validated. if this is class object decorated with {@link DType}, it can omits `ctor` parameter.
+     * @param ctor class constructor type whose properties are decorated. **NOTE** that need to have public constructor without any parameter.
      * @returns invalid property keys. returns an empty array if `o` is valid.
      */
-    function validate(o: any): string[];
+    function validate(o: any, ctor?: Ctor): string[];
     function takeAsArray<T>(v: MaybeArray<T>): T[];
 }

package/build/func/u-type.js

@@ -29,14 +29,16 @@ export var UType;
     }
     UType.isArray = isArray;
     /**
-     * validate properties which attached decorators in {@link DType}.
-     * @param o object to be validated.
+     * validate properties decorated with {@link DType}.
+     * @param o object to be validated. if this is class object decorated with {@link DType}, it can omits `ctor` parameter.
+     * @param ctor class constructor type whose properties are decorated. **NOTE** that need to have public constructor without any parameter.
      * @returns invalid property keys. returns an empty array if `o` is valid.
      */
-    function validate(o) {
-        if (!o[smbl_tm])
+    function validate(o, ctor) {
+        const _o = (!ctor || o instanceof ctor) ? o : Object.assign(new ctor(), o);
+        if (!_o[smbl_tm])
             return [];
-        return Object.entries(o[smbl_tm]).flatMap(e => validateProp(e[0], o[e[0]], e[1]));
+        return Object.entries(_o[smbl_tm]).flatMap(e => validateProp(e[0], _o[e[0]], e[1]));
     }
     UType.validate = validate;
     function validateProp(k, prop, td) {
@@ -51,8 +53,8 @@ export var UType;
         if (td.rcd)
             return UType.isObject(prop)
                 ? Object.entries(prop).flatMap(e => validateProp(e[0], e[1], td.rcd)).map(joinKey) : [k];
-        if (td.rec)
-            return validate(prop).flatMap(joinKey);
+        if (td.obj)
+            return validate(prop, td.obj).flatMap(joinKey);
         return [];
     }
     function takeAsArray(v) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xjs-common",
-  "version": "12.0.0-alpha.2",
+  "version": "13.0.0-alpha.1",
   "description": "library modules for typescript that bundled general-purpose implementations.",
   "repository": {
     "type": "git",