@avstantso/core 1.2.2 → 1.3.0

package/dist/_global/deep-ops.d.ts

@@ -0,0 +1,505 @@
+declare namespace AVStantso {
+    type TypeMap = DeepOps.TypeMap;
+    namespace TypeMap {
+        type Wildcard = DeepOps.TypeMap.Wildcard;
+        type Derive<TOverrides extends Partial<TypeMap>, TTypeMap extends TypeMap = TypeMap> = DeepOps.TypeMap.Derive<TOverrides, TTypeMap>;
+    }
+    /**
+     * @summary Deep operations
+     */
+    export namespace DeepOps {
+        /**
+         * @summary Deep operation node type to walk
+         */
+        type NodeType = keyof typeof AVStantso.LowLevel.TypeGroup;
+        namespace NodeType {
+            /**
+             * @summary Deep operation node type to walk: supports recursion next
+             */
+            type Nextable = Exclude<NodeType, 'scalar' | 'atomic'>;
+        }
+        /**
+         * @summary Deep operation node type tuple type
+         */
+        type NodeTypes = AVStantso.LowLevel.TypeGroups;
+        /**
+         * @summary Deep operation recursion generics types map
+         */
+        type TypeMap = {
+            walker?: Function;
+            nodes?: NodeType;
+        };
+        namespace TypeMap {
+            /**
+             * @summary Types map wildcard
+             */
+            type Wildcard = {
+                [K in keyof TypeMap]-?: any;
+            };
+            /**
+             * @summary Derive types map from previous
+             */
+            type Derive<TOverrides extends Partial<TypeMap>, TTypeMap extends TypeMap = TypeMap> = Omit<TTypeMap, keyof TOverrides> & TOverrides extends infer R extends Omit<TTypeMap, keyof TOverrides> & TOverrides ? {
+                [K in keyof R]-?: R[K];
+            } : never;
+        }
+        /**
+         * @summary Walk rules types.\
+         * Walk rules by node types
+         */
+        namespace Walk {
+            /**
+             * @summary Class map for walk rules.
+             */
+            export type ClassMap<TTypeMap extends TypeMap = TypeMap> = ReadonlyMap<AVStantso.TS.Class, boolean | TTypeMap['walker']>;
+            /**
+             * @summary Walk scalar (not objects and functions) types rule.\
+             * Process falsy values too (`undefined`, `null`).\
+             * If `null`, translated to `true` for inclusive / to `false` for exclusive behaviour.\
+             * If truthy, recursion will walk `string`, `number` etc.\
+             * If value is general `CustomWalker`:
+             * - All will be walked custom
+             * If value is record object:
+             * - Unexists / `null` — see `null` above
+             * - Exists as `CustomWalker` will be walked custom
+             * - Exists as thruthy will be walked
+             * - Exists as falsy will be NOT walked
+             */
+            export type Scalar<TTypeMap extends TypeMap = TypeMap> = null | boolean | TTypeMap['walker'] | Partial<Record<LowLevel.JSType.Scalar, boolean | TTypeMap['walker']>>;
+            /**
+             * @summary Walk atomic ({@link AtomicObjects}) objects rule.\
+             * These objects are similar to scalars.\
+             * If `null`, translated to `true` for inclusive / to `false` for exclusive behaviour.\
+             * If truthy, recursion will walk `{}`.\
+             * If value is general `CustomWalker`:
+             * - All will be walked custom
+             * If value is Map object:
+             * - Unexists / `null` — see `null` above
+             * - Exists as `CustomWalker` will be walked custom
+             * - Exists as thruthy will be walked
+             * - Exists as falsy will be NOT walked
+             * @see AtomicObjects
+             */
+            export type Atomic<TTypeMap extends TypeMap = TypeMap> = null | boolean | TTypeMap['walker'] | ClassMap<TypeMap>;
+            /**
+             * @summary Walk plain (`Object.isPlainObject`) objects rule.\
+             * If `null`, translated to `true` for inclusive / to `false` for exclusive behaviour.\
+             * If truthy, recursion will walk `{}`.\
+             * If value is general `CustomWalker`:
+             * - All will be walked custom
+             */
+            export type Plain<TTypeMap extends TypeMap = TypeMap> = null | boolean | TTypeMap['walker'];
+            /**
+             * @summary Walk rich (not `Object.isPlainObject`) objects rule.\
+             * If `null`, translated to `true` for inclusive / to `false` for exclusive behaviour.\
+             * If truthy, recursion will walk `Array`, `Set`, `Map`, classes instances etc.\
+             * If value is general `CustomWalker`:
+             * - All will be walked custom
+             * If value is Map object:
+             * - Unexists / `null` — see `null` above
+             * - Exists as `CustomWalker` will be walked custom
+             * - Exists as thruthy will be walked
+             * - Exists as falsy will be NOT walked
+             */
+            export type Rich<TTypeMap extends TypeMap = TypeMap> = null | boolean | TTypeMap['walker'] | ClassMap<TTypeMap>;
+            /**
+             * @summary Walk functions rule.\
+             * If `null`, translated to `true` for inclusive / to `false` for exclusive behaviour.\
+             * If truthy, recursion will walk functions, async/arrow/generator functions, classes etc.\
+             * If value is general `CustomWalker`:
+             * - All will be walked custom
+             * If value is record object:
+             * - Unexists / `null` — see `null` above
+             * - Exists as `CustomWalker` will be walked custom
+             * - Exists as thruthy will be walked
+             * - Exists as falsy will be NOT walked
+             */
+            export type Funcs<TTypeMap extends TypeMap = TypeMap> = null | boolean | TTypeMap['walker'] | Partial<Record<TS.Func.Type, boolean | TTypeMap['walker']>>;
+            type InclusiveExclusive<TNodeType extends NodeType, TWalk> = [
+                `walk${Capitalize<TNodeType>}Inc`,
+                `walk${Capitalize<TNodeType>}Exc`
+            ] extends [infer I extends string, infer E extends string] ? [
+                {
+                    [K in I]?: TWalk;
+                } & {
+                    [K in E]?: never;
+                },
+                {
+                    [K in I]?: never;
+                } & {
+                    [K in E]?: TWalk;
+                }
+            ] extends [infer WI, infer WE] ? {
+                [K in keyof WI]: WI[K];
+            } | {
+                [K in keyof WE]: WE[K];
+            } : never : never;
+            type _Static<TTypeMap extends TypeMap, NTA extends readonly NodeType[] = NodeTypes, R = never> = NTA extends readonly [infer C extends NodeType, ...infer Rest extends readonly NodeType[]] ? _Static<TTypeMap, Rest, R | (C extends TypeMap['nodes'] ? InclusiveExclusive<C, Walk<TTypeMap>[C]> : never)> : R;
+            /**
+             * @summary Walk static (not extensible) rules pack alternatives.
+             */
+            export type Static<TTypeMap extends TypeMap = TypeMap> = _Static<TTypeMap> & {};
+            export namespace Static {
+                type _United<TTypeMap extends TypeMap, NTA extends readonly NodeType[] = NodeTypes, R = unknown> = NTA extends readonly [
+                    infer C extends NodeType,
+                    ...infer Rest extends readonly NodeType[]
+                ] ? _United<TTypeMap, Rest, R & (C extends TypeMap['nodes'] ? {
+                    [K in `walk${Capitalize<C>}${'Inc' | 'Exc'}`]: Walk<TTypeMap>[C];
+                } : unknown)> : {
+                    [K in keyof R]: R[K];
+                };
+                /**
+                 * @summary Walk static (not extensible) rules pack (alternatives is united).
+                 */
+                export type United<TTypeMap extends TypeMap = TypeMap> = _United<TTypeMap>;
+                export {};
+            }
+            export {};
+        }
+        type Walk<TTypeMap extends TypeMap = TypeMap> = {
+            scalar: Walk.Scalar<TTypeMap>;
+            atomic: Walk.Atomic<TTypeMap>;
+            plain: Walk.Plain<TTypeMap>;
+            rich: Walk.Rich<TTypeMap>;
+            func: Walk.Funcs<TTypeMap>;
+        };
+        /**
+         * @summary Deep operation options (extensible `interface`).\
+         * Used in pair with `Walk.Static<XXX>` (not extensible)
+         * @see Walk.Static
+         */
+        interface Options {
+            /**
+             * @summary If truthy, walks enumirale and own properties,\
+             * if falsy — enumirale properties only
+             */
+            ownProps?: boolean;
+        }
+    }
+    export namespace Code {
+        /**
+         * @summary Deep operations utils
+         */
+        namespace DeepOps {
+            /**
+             * @summary Deep operations utils common
+             */
+            namespace Common {
+                /**
+                 * @summary Deep operations common options
+                 */
+                type Options<TTypeMap extends TypeMap = TypeMap> = AVStantso.DeepOps.Options & AVStantso.DeepOps.Walk.Static<TTypeMap>;
+                /**
+                 * @summary Deep copy operations commons:
+                 * - `Clone`
+                 * - `Merge`
+                 */
+                namespace CopyOps {
+                    /**
+                     * @summary Deep copy operations common options
+                     * - `Clone`
+                     * - `Merge`
+                     */
+                    interface Options {
+                        /**
+                         * @summary If `true`, copies reference of function instead cloning
+                         */
+                        copyFuncs?: boolean;
+                    }
+                }
+                /**
+                 * @summary Options option
+                 */
+                namespace Option {
+                    /**
+                     * @summary Option value callback
+                     * @param node Node value the option is being resolved for
+                     * @param key Node's key/index within its parent, if any (`undefined` at the root)
+                     */
+                    type Callback<R> = (node: unknown, key?: TS.Key) => R;
+                }
+                type Option<T> = T | Option.Callback<T>;
+            }
+            /**
+             * @summary `DeepOps` typeguards
+             */
+            namespace Is {
+                /**
+                 * @summary `DeepOps` options typeguards
+                 */
+                interface Options {
+                    /**
+                     * @summary {@link DeepOps.Common.Options} typeguard
+                     */
+                    common<TTypeMap extends TypeMap = TypeMap>(candidate: unknown): candidate is DeepOps.Common.Options<TTypeMap>;
+                    /**
+                     * @summary {@link DeepOps.Clone.Options} typeguard
+                     */
+                    clone(candidate: unknown): candidate is DeepOps.Clone.Options;
+                    /**
+                     * @summary {@link DeepOps.Merge.Options} typeguard
+                     */
+                    merge(candidate: unknown): candidate is DeepOps.Merge.Options;
+                }
+            }
+            interface Is {
+                /**
+                 * @summary `DeepOps` options typeguards
+                 */
+                options: Is.Options;
+            }
+            /**
+             * @summary Deep feeze operation
+             * @template T Argument type
+             * @param obj Data for freeze
+             * @param options Options for freeze
+             */
+            namespace Freeze {
+                /**
+                 * Typemap for freeze
+                 */
+                type TypeMap = TypeMap.Derive<{
+                    walker<T extends object | Function>(node: T): Readonly<T>;
+                    nodes: 'plain' | 'rich' | 'func';
+                }>;
+                /**
+                 * Options for freeze
+                 */
+                type Options = Common.Options<TypeMap>;
+            }
+            interface Freeze {
+                /**
+                 * @summary `symbol` for custom freeze.\
+                 * Same symbol of {@link _CodeReg.Administration.symbolFreeze}
+                 */
+                symbol: symbol;
+                /**
+                 * @summary Deep feeze operation
+                 * @template T Argument type
+                 * @param obj Data for freeze
+                 * @param options Options for freeze
+                 */
+                <T>(obj: T, options?: Freeze.Options): Readonly<T>;
+            }
+            /**
+             * @summary Deep clone operation
+             * @template T Argument type
+             * @param obj Data for clone
+             * @param options Options for clone
+             */
+            namespace Clone {
+                /**
+                 * Typemap for clone
+                 */
+                type TypeMap = TypeMap.Derive<{
+                    walker<T>(node: T): T;
+                }>;
+                /**
+                 * @summary Deep clone operation options
+                 */
+                interface Options extends Common.CopyOps.Options {
+                }
+                namespace Options {
+                    /**
+                     * @summary Deep clone operation merged options
+                     */
+                    type Merged = Options & Common.Options<TypeMap>;
+                }
+            }
+            interface Clone {
+                /**
+                 * @summary `symbol` for custom clone.
+                 */
+                symbol: symbol;
+                /**
+                 * @summary Deep clone operation
+                 * @template T Argument type
+                 * @param obj Data for clone
+                 * @param options Options for clone
+                 */
+                <T>(obj: T, options?: Clone.Options.Merged): T;
+            }
+            /**
+             * @summary Deep merge operation
+             * @template T Target argument type
+             * @template S Source arguments type
+             * @param target Data target for merge
+             * @param sources Data sources for merge
+             * @param options Options for merge
+             */
+            namespace Merge {
+                /**
+                 * Typemap for merge
+                 */
+                type TypeMap = TypeMap.Derive<{
+                    walker<T, S extends TS.ArrR>(target: T, ...sources: S): T;
+                }>;
+                /**
+                 * @summary Deep merge operation options
+                 */
+                interface Options extends Common.CopyOps.Options {
+                    /**
+                     * If resolved as truthy: node for merge must exists in source node
+                     */
+                    onlyExists?: Common.Option<boolean>;
+                    /**
+                     * If resolved as truthy: array nodes will merjed as `[...new Set( XXX )]`
+                     */
+                    isUniqueArrItems?: Common.Option<boolean>;
+                    /**
+                     * If resolved as truthy: source `null` will delete target key
+                     */
+                    nullAsDelete?: Common.Option<boolean>;
+                    /**
+                     * If resolved as truthy: array nodes will be merged by concatenation
+                     * (`[...target, ...source]`), instead of the default by-index merge
+                     */
+                    concatArrays?: Common.Option<boolean>;
+                }
+                namespace Options {
+                    /**
+                     * @summary Deep merge operation merged options
+                     */
+                    type Merged = Options & Common.Options<TypeMap>;
+                }
+            }
+            interface Merge {
+                /**
+                 * @summary `symbol` for custom merge.
+                 */
+                symbol: symbol;
+                /**
+                 * @summary Deep merge operation
+                 * @template T Target argument type
+                 * @template S Source argument type
+                 * @param target Data target for merge
+                 * @param source Data source for merge
+                 * @param options Options for merge
+                 */
+                <T, S>(target: T, source: S, options: Merge.Options.Merged): T & Partial<S>;
+                /**
+                 * @summary Deep merge operation
+                 * @template T Target argument type
+                 * @template S0 Source0 argument type
+                 * @template S1 Source1 argument type
+                 * @param target Data target for merge
+                 * @param source0 Data source0 for merge
+                 * @param source1 Data source1 for merge
+                 * @param options Options for merge
+                 */
+                <T, S0, S1>(target: T, source0: S0, source1: S1, options: Merge.Options.Merged): T & Partial<S0 & S1>;
+                /**
+                 * @summary Deep merge operation
+                 * @template T Target argument type
+                 * @template S0 Source0 argument type
+                 * @template S1 Source1 argument type
+                 * @template S2 Source2 argument type
+                 * @param target Data target for merge
+                 * @param source0 Data source0 for merge
+                 * @param source1 Data source1 for merge
+                 * @param source2 Data source2 for merge
+                 * @param options Options for merge
+                 */
+                <T, S0, S1, S2>(target: T, source0: S0, source1: S1, source2: S2, options: Merge.Options.Merged): T & Partial<S0 & S1 & S2>;
+                /**
+                 * @summary Deep merge operation
+                 * @template T Target argument type
+                 * @template S0 Source0 argument type
+                 * @template S1 Source1 argument type
+                 * @template S2 Source2 argument type
+                 * @template S3 Source3 argument type
+                 * @param target Data target for merge
+                 * @param source0 Data source0 for merge
+                 * @param source1 Data source1 for merge
+                 * @param source2 Data source2 for merge
+                 * @param source3 Data source3 for merge
+                 * @param options Options for merge
+                 */
+                <T, S0, S1, S2, S3>(target: T, source0: S0, source1: S1, source2: S2, source3: S3, options: Merge.Options.Merged): T & Partial<S0 & S1 & S2 & S3>;
+                /**
+                 * @summary Deep merge operation
+                 * @template T Target argument type
+                 * @template S0 Source0 argument type
+                 * @template S1 Source1 argument type
+                 * @template S2 Source2 argument type
+                 * @template S3 Source3 argument type
+                 * @template S4 Source4 argument type
+                 * @param target Data target for merge
+                 * @param source0 Data source0 for merge
+                 * @param source1 Data source1 for merge
+                 * @param source2 Data source2 for merge
+                 * @param source3 Data source3 for merge
+                 * @param source4 Data source4 for merge
+                 * @param options Options for merge
+                 */
+                <T, S0, S1, S2, S3, S4>(target: T, source0: S0, source1: S1, source2: S2, source3: S3, source4: S4, options: Merge.Options.Merged): T & Partial<S0 & S1 & S2 & S3 & S4>;
+                /**
+                 * @summary Deep merge operation
+                 * @template T Target argument type
+                 * @template S Source arguments type
+                 * @param target Data target for merge
+                 * @param sources Data sources for merge
+                 * @param options Options for merge
+                 */
+                <T, S extends TS.ArrR>(target: T, ...params: [...[...sources: S], ...[options: Merge.Options.Merged]]): T & unknown;
+            }
+        }
+        interface DeepOps {
+            /**
+             * @summary Deep walk node types
+             */
+            NodeTypes: TS.Key2Key<AVStantso.DeepOps.NodeType>;
+            /**
+             * @summary `DeepOps` typeguards
+             */
+            is: DeepOps.Is;
+            /**
+             * @summary Deep feeze operation.\
+             * Default walks logic:
+             * - plain objects (`{}`)
+             * - `Array`, `Set`, 'Map', class instances
+             * - functions, except `class` and `generator` kinds
+             * @template T Argument type
+             * @param obj Data for freeze
+             * @param options Options for freeze
+             */
+            freeze: DeepOps.Freeze;
+            /**
+             * @summary Deep clone operation.\
+             * Default walks logic:
+             * - scalars (`string`, `number`, etc.)
+             * - atomics (`Date`, `Buffer`, etc.)
+             * - plain objects (`{}`)
+             * - `Array`, `Set`, 'Map'. Not class instances
+             * - functions, except `class` and `generator` kinds
+             * @template T Argument type
+             * @param obj Data for clone
+             * @param options Options for clone
+             */
+            clone: DeepOps.Clone;
+            /**
+             * @summary Deep merge operation\
+             * Default walks logic:
+             * - scalars (`string`, `number`, etc.)
+             * - atomics (`Date`, `Buffer`, etc.)
+             * - plain objects (`{}`)
+             * - `Array`, `Set`, 'Map'. Not class instances
+             * - functions, except `class` and `generator` kinds
+             * @template T Target argument type
+             * @template S Source arguments type
+             * @param target Data target for merge
+             * @param sources Data sources for merge
+             * @param options Options for merge
+             */
+            merge: DeepOps.Merge;
+        }
+    }
+    export interface Code {
+        /**
+         * @summary Deep operations utils
+         */
+        DeepOps: Code.DeepOps;
+    }
+    export const DeepOps: Code.DeepOps;
+    export {};
+}

package/dist/_global/func.d.ts

@@ -13,7 +13,12 @@ declare namespace AVStantso {
     } & {
         [x: string]: PropertyDescriptor;
     } & {};
+    const runtimeFuncTypes: readonly ["plain", "async", "generator", "class", "arrow", "bound"];
     export namespace TS.Func {
+        /**
+         * Runtime function type
+         */
+        type Type = typeof runtimeFuncTypes[number];
         /**
          * @summary `getOwnPropertyDescriptors` of basic function type
          */
@@ -58,6 +63,14 @@ declare namespace AVStantso {
          * @summary Functions utilities
          */
         interface Func {
+            /**
+             * @summary Types of runtime function Key2Key record
+             */
+            Types: TS.Key2Key<TS.Func.Type>;
+            /**
+             * @summary Determines a type of runtime function
+             */
+            determineType(func: Function | TS.Func): TS.Func.Type;
             /**
              * @summary `getOwnPropertyDescriptors` of basic function
              */
@@ -227,14 +240,14 @@ declare namespace AVStantso {
              * dd.z = 16;
              * expect(isExt(dd)).toBe(true);
              */
-            isExt(f: Function): boolean;
+            isExt(f: Function | TS.Func): boolean;
             /**
              * @summary `DEV` dynamic function named as `name`. No affect in `PROD`.
              * @param name Name
              * @param func Implementation
              * @returns In `DEV` — Named function; In `PROD` — `func`
              */
-            Dynamic<N extends string, F extends Function>(name: N, func: F): F;
+            Dynamic<N extends string, F extends Function | TS.Func>(name: N, func: F): F;
         }
     }
     export interface Code {

package/dist/_global/index.d.ts

@@ -7,3 +7,5 @@ import './catch';
 import './atomic-objects';
 import './metadata-literals';
 import './X';
+import './low-level';
+import './deep-ops';

package/dist/_global/low-level.d.ts

@@ -0,0 +1,116 @@
+declare namespace AVStantso {
+    const jstype: "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function";
+    const JSStucturalTypes: readonly ["object", "function"];
+    enum TypeGroupEnum {
+        /**
+         * `foo === null || !JSStucturalTypes.includes(typeof foo)`
+         */
+        scalar = 0,
+        /**
+         * `AVStantso.AtomicObjects.is(foo)`
+         */
+        atomic = 1,
+        /**
+         * `typeof foo === 'object' && Object.isPlainObject(foo)`
+         */
+        plain = 2,
+        /**
+         * `typeof foo === 'object' && !Object.isPlainObject(foo)`
+         */
+        rich = 3,
+        /**
+         * `typeof foo === 'function'`
+         */
+        func = 4
+    }
+    const TypeGroups: readonly ["scalar", "atomic", "plain", "rich", "func"];
+    /**
+     * @summary Low level types and utils
+     */
+    export namespace LowLevel {
+        /**
+         * @summary JavaScript native types union
+         */
+        type JSType = typeof jstype;
+        namespace JSType {
+            /**
+             * @summary JavaScript native scalar types + `null`
+             */
+            type Scalar = Exclude<JSType, typeof JSStucturalTypes[number]> | 'null';
+        }
+        /**
+         * The group of value type
+         */
+        type TypeGroup = TypeGroupEnum;
+        namespace TypeGroup {
+            /**
+             * A type union for a group of value type
+             */
+            type Union<TG extends TypeGroup> = TG extends TypeGroupEnum.scalar ? string | number | bigint | boolean | symbol | undefined | null : TG extends TypeGroupEnum.func ? Function : object;
+            namespace Union {
+                /**
+                 * A type union for a group of value type\
+                 * for `scalar`
+                 */
+                type Scalar = Union<TypeGroupEnum.scalar>;
+                /**
+                 * A type union for a group of value type\
+                 * for `atomic`
+                 */
+                type Atomic = Union<TypeGroupEnum.atomic>;
+                /**
+                 * A type union for a group of value type\
+                 * for `plain`
+                 */
+                type Plain = Union<TypeGroupEnum.plain>;
+                /**
+                 * A type union for a group of value type\
+                 * for `rich`
+                 */
+                type Rich = Union<TypeGroupEnum.rich>;
+                /**
+                 * A type union for a group of value type\
+                 * for `func`
+                 */
+                type Func = Union<TypeGroupEnum.func>;
+            }
+        }
+        /**
+         * The group of value types array
+         */
+        type TypeGroups = typeof TypeGroups;
+    }
+    export namespace Code {
+        /**
+         * @summary Low level utils
+         */
+        namespace LowLevel {
+        }
+        interface LowLevel {
+            /**
+             * @summary Array of JavaScript structural types
+             */
+            JSStucturalTypes: typeof JSStucturalTypes;
+            /**
+             * The group of value type enum
+             */
+            TypeGroup: typeof TypeGroupEnum;
+            /**
+             * The group of value types array
+             */
+            TypeGroups: typeof TypeGroups;
+            /**
+             * Classify the type group of value
+             */
+            typeGroupOf(a: unknown): TypeGroupEnum;
+        }
+    }
+    export interface Code {
+        /**
+         * @summary Low level utils
+         */
+        LowLevel: Code.LowLevel;
+    }
+    export const LowLevel: Code.LowLevel;
+    export {};
+}

package/dist/export.d.ts

@@ -1,4 +1,5 @@
 import Func = AVStantso.Func;
 import X = AVStantso.X;
 import Generic = AVStantso.Generic;
-export { Func, X, Generic };
+import DeepOps = AVStantso.DeepOps;
+export { Func, X, Generic, DeepOps };