@basmilius/http-client 1.13.0 → 2.2.0

package/src/decorator/dto/arrayProxy.ts

@@ -0,0 +1,65 @@
+import { markDtoDirty, trackDto, triggerDto } from './helper';
+import { PARENT, PARENT_KEY, PROXY } from './symbols';
+import type DtoInstance from './instance';
+
+export default {
+    /**
+     * Trap for when a property is deleted from the target. This
+     * will mark the parent dto as dirty and trigger an update.
+     */
+    deleteProperty(target: unknown[], key: string | symbol): boolean {
+        Reflect.deleteProperty(target, key);
+
+        if (ignored(target, key)) {
+            return true;
+        }
+
+        const dto = target[PARENT] as DtoInstance<unknown>;
+        dto && triggerDto(dto, target[PARENT_KEY], dto[target[PARENT_KEY]]);
+        dto && markDtoDirty(dto, target[PARENT_KEY]);
+
+        return true;
+    },
+
+    /**
+     * Trap for when a property of the target is being accessed. The
+     * property access is being tracked for further updates.
+     */
+    get(target: unknown[], key: string | symbol, receiver: any): unknown {
+        if (key === PROXY) {
+            return true;
+        }
+
+        if (ignored(target, key)) {
+            return Reflect.get(target, key, receiver);
+        }
+
+        const dto = target[PARENT] as DtoInstance<unknown>;
+        dto && trackDto(dto, target[PARENT_KEY]);
+
+        return Reflect.get(target, key);
+    },
+
+    /**
+     * Trap for when a property of the target is being updated. This
+     * will mark the parent dto as dirty and trigger an update.
+     */
+    set(target: unknown[], key: string | symbol, value: unknown, receiver: any) {
+        if (ignored(target, key)) {
+            return Reflect.set(target, key, value, receiver);
+        }
+
+        const dto = target[PARENT] as DtoInstance<unknown>;
+        dto && triggerDto(dto, target[PARENT_KEY], dto[target[PARENT_KEY]]);
+        dto && markDtoDirty(dto, target[PARENT_KEY]);
+
+        return Reflect.set(target, key, value);
+    }
+} satisfies ProxyHandler<unknown[]>;
+
+/**
+ * Checks if the given key should be ignored by the proxy.
+ */
+function ignored(target: unknown[], key: string | symbol): key is symbol {
+    return typeof key === 'symbol' || typeof target[key] === 'function' || key === 'length';
+}

package/src/decorator/dto/classProxy.ts

@@ -0,0 +1,49 @@
+import type { Constructor } from '@basmilius/utils';
+import { customRef, markRaw } from 'vue';
+import { ARGS, DIRTY, TRACK, TRIGGER } from './symbols';
+import type DtoInstance from './instance';
+import arrayProxy from './arrayProxy';
+import instanceProxy from './instanceProxy';
+import refProxy from './refProxy';
+
+export default {
+    /**
+     * Trap for when a dto is being constructed. Reactivity is provided
+     * to all arguments and a proxied custom ref is returned that references
+     * the actual dto instance.
+     */
+    construct(target: Constructor, argsArray: any[], newTarget: Function): DtoInstance<unknown> {
+        // note(Bas): This will apply reactivity to any array arguments.
+        argsArray = argsArray.map(arg => {
+            if (!Array.isArray(arg)) {
+                return arg;
+            }
+
+            return new Proxy(arg, arrayProxy);
+        });
+
+        const ref = customRef((track, trigger) => {
+            const instance = markRaw(Reflect.construct(target, argsArray, newTarget));
+            instance[ARGS] = argsArray;
+            instance[DIRTY] = false;
+            instance[TRACK] = track;
+            instance[TRIGGER] = trigger;
+
+            const proxied = new Proxy(instance, instanceProxy);
+
+            return {
+                // note(Bas): track that the dto itself is being accessed.
+                get: () => {
+                    track();
+                    return proxied;
+                },
+
+                // note(Bas): setter is never used, but we don't want to
+                //  cause any errors.
+                set: () => void 0
+            };
+        });
+
+        return new Proxy(ref, refProxy) as unknown as DtoInstance<unknown>;
+    }
+} satisfies ProxyHandler<Constructor>;

package/src/decorator/dto/clone.ts

@@ -0,0 +1,24 @@
+import { assertDto, isDto } from './helper';
+import { ARGS, DESCRIPTORS, NAME } from './symbols';
+import { DTO_CLASS_MAP } from './map';
+import type DtoInstance from './instance';
+
+/**
+ * Returns a clone of the dto.
+ */
+export default function <T>(this: DtoInstance<T>): DtoInstance<T> {
+    const instance = this;
+    assertDto(instance);
+
+    const clazz = DTO_CLASS_MAP[instance[NAME]];
+    const clone = new clazz(...instance[ARGS]);
+
+    Object.entries(this[DESCRIPTORS])
+        .filter(([, descriptor]) => !!descriptor.set)
+        .map(([name]) => name)
+        .forEach(key => clone[key] = isDto(this[key])
+            ? this[key].clone()
+            : this[key]);
+
+    return clone as DtoInstance<T>;
+}

package/src/decorator/dto/constant.ts

@@ -0,0 +1,7 @@
+export const ENABLE_CIRCULAR_LOGGING = false;
+export const ENABLE_DIRTY_LOGGING = false;
+export const ENABLE_REACTIVE_LOGGING = false;
+export const ENABLE_GET_LOGGING = false;
+export const ENABLE_SET_LOGGING = false;
+export const ENABLE_SERIALIZATION_LOGGING = false;
+export const OVERRIDE_CONSOLE_LOG = false;

package/src/decorator/dto/fill.ts

@@ -0,0 +1,18 @@
+import { isDto } from './helper';
+import { DESCRIPTORS } from './symbols';
+import type DtoInstance from './instance';
+
+/**
+ * Fills the dto with the given data.
+ */
+export default function (this: DtoInstance<unknown>, data: Record<string, unknown>): void {
+    for (let key in data) {
+        const descriptor = this[DESCRIPTORS][key];
+
+        if (isDto(this[key]) && typeof data[key] === 'object') {
+            this[key].fill(data[key] as Record<string, unknown>);
+        } else if (descriptor && descriptor.set) {
+            this[key] = data[key];
+        }
+    }
+}

package/src/decorator/dto/helper/areEqual.ts

@@ -0,0 +1,13 @@
+import isDto from './isDto';
+
+/**
+ * Checks if the two given values are equal. When both values are a
+ * dto, the check is done by firstly converthing them to JSON.
+ */
+export default function (a: unknown, b:  unknown): boolean {
+    if (!isDto(a) || !isDto(b)) {
+        return a === b;
+    }
+
+    return JSON.stringify(a) === JSON.stringify(b);
+}

package/src/decorator/dto/helper/assertDto.ts

@@ -0,0 +1,11 @@
+import type DtoInstance from '../instance';
+import isDto from './isDto';
+
+/**
+ * Asserts that the given object is a dto.
+ */
+export default function (obj: unknown): asserts obj is DtoInstance<never> {
+    if (!isDto(obj)) {
+        throw new Error('@dto assert given object is not a class decorated with @Dto.');
+    }
+}

package/src/decorator/dto/helper/circularProtect.ts

@@ -0,0 +1,35 @@
+import { ENABLE_CIRCULAR_LOGGING } from '../constant';
+import type DtoInstance from '../instance';
+
+type CircularMap = WeakMap<DtoInstance<unknown>, (string | symbol)[]>;
+const CIRCULAR_MAP = Symbol();
+
+export default function <T extends (...args: any[]) => unknown>(fn: T, arg1: number = 0, arg2?: number): T {
+    return function (...args: any[]): unknown {
+        const hasMap = CIRCULAR_MAP in fn;
+        const map: CircularMap = fn[CIRCULAR_MAP] ??= new WeakMap();
+        const primary = args[arg1];
+        const secondary = arg2 !== undefined ? args[arg2] : 'self';
+
+        if (typeof primary !== 'object') {
+            return fn.call(this, ...args);
+        }
+
+        if (!map.has(primary)) {
+            map.set(primary, []);
+        }
+
+        if (map.get(primary).includes(secondary)) {
+            ENABLE_CIRCULAR_LOGGING && console.log(`%c@dto %ccircular protect %cdetected a circular reference`, 'color: #0891b2', 'color: #059669', 'color: #1d4ed8', {fn, primary, secondary});
+            return;
+        }
+
+        map.get(primary).push(secondary);
+
+        const result = fn.call(this, ...args);
+
+        !hasMap && (delete fn[CIRCULAR_MAP]);
+
+        return result;
+    } as T;
+}

package/src/decorator/dto/helper/cloneDto.ts

@@ -0,0 +1,9 @@
+import assertDto from './assertDto';
+
+/**
+ * Clones the given dto.
+ */
+export default function <T>(obj: T): T {
+    assertDto(obj);
+    return obj.clone() as T;
+}

package/src/decorator/dto/helper/executeIfDtoDirtyAndMarkClean.ts

@@ -0,0 +1,16 @@
+import type DtoInstance from '../instance';
+import isDto from './isDto';
+import isDtoDirty from './isDtoDirty';
+import markDtoClean from './markDtoClean';
+
+/**
+ * Executes the given function if the given dto is marked dirty.
+ */
+export default async function <T, R = void>(obj: T, fn: (dto: T & DtoInstance<T>) => Promise<R>): Promise<void> {
+    if (!isDto(obj) || !isDtoDirty(obj)) {
+        return;
+    }
+
+    await fn(obj);
+    markDtoClean(obj);
+}

package/src/decorator/dto/helper/index.ts

@@ -0,0 +1,37 @@
+import areEqual from './areEqual';
+import assertDto from './assertDto';
+import circularProtect from './circularProtect';
+import cloneDto from './cloneDto';
+import executeIfDtoDirtyAndMarkClean from './executeIfDtoDirtyAndMarkClean';
+import instance from './instance';
+import isDto from './isDto';
+import isDtoClean from './isDtoClean';
+import isDtoDirty from './isDtoDirty';
+import markDtoClean from './markDtoClean';
+import markDtoDirty from './markDtoDirty';
+import relateDtoTo from './relateDtoTo';
+import relateValueTo from './relateValueTo';
+import trackDto from './trackDto';
+import triggerDto from './triggerDto';
+import unrelateDtoFrom from './unrelateDtoFrom';
+import unrelateValueFrom from './unrelateValueFrom';
+
+export {
+    areEqual,
+    assertDto,
+    circularProtect,
+    cloneDto,
+    executeIfDtoDirtyAndMarkClean,
+    instance,
+    isDto,
+    isDtoClean,
+    isDtoDirty,
+    markDtoClean,
+    markDtoDirty,
+    relateDtoTo,
+    relateValueTo,
+    trackDto,
+    triggerDto,
+    unrelateDtoFrom,
+    unrelateValueFrom
+};

package/src/decorator/dto/helper/instance.ts

@@ -0,0 +1,5 @@
+import type DtoInstance from '../instance';
+
+export default function <T>(dto: DtoInstance<T>): DtoInstance<T> {
+    return (dto as any)?.value ?? dto;
+}

package/src/decorator/dto/helper/isDto.ts

@@ -0,0 +1,9 @@
+import { NAME } from '../symbols';
+import type DtoInstance from '../instance';
+
+/**
+ * Checks if the given object is a dto.
+ */
+export default function (obj: unknown): obj is DtoInstance<unknown> {
+    return obj && typeof obj === 'object' && !!obj[NAME];
+}

package/src/decorator/dto/helper/isDtoClean.ts

@@ -0,0 +1,10 @@
+import { DIRTY } from '../symbols';
+import assertDto from './assertDto';
+
+/**
+ * Checks if the given dto is clean.
+ */
+export default function (obj: unknown): boolean {
+    assertDto(obj);
+    return !obj[DIRTY];
+}

package/src/decorator/dto/helper/isDtoDirty.ts

@@ -0,0 +1,10 @@
+import { DIRTY } from '../symbols';
+import assertDto from './assertDto';
+
+/**
+ * Checks if the given dto is dirty.
+ */
+export default function (obj: unknown): boolean {
+    assertDto(obj);
+    return obj[DIRTY];
+}

package/src/decorator/dto/helper/markDtoClean.ts

@@ -0,0 +1,29 @@
+import { ENABLE_DIRTY_LOGGING } from '../constant';
+import { CHILDREN, DIRTY, NAME } from '../symbols';
+import assertDto from './assertDto';
+import circularProtect from './circularProtect';
+import isDtoDirty from './isDtoDirty';
+import triggerDto from './triggerDto';
+
+/**
+ * Marks the given dto clean.
+ */
+const markDtoClean: (obj: unknown) => void = circularProtect(function (obj: unknown): void {
+    assertDto(obj);
+
+    if (obj[DIRTY]) {
+        obj[DIRTY] = false;
+        ENABLE_DIRTY_LOGGING && console.log(`%c@dto %c${obj[NAME]} %cdirty`, 'color: #0891b2', 'color: #059669', 'color: #1d4ed8', 'marked clean', {obj});
+        triggerDto(obj, DIRTY, false, true);
+    }
+
+    if (!obj[CHILDREN] || obj[CHILDREN].length === 0) {
+        return;
+    }
+
+    obj[CHILDREN]
+        .filter(isDtoDirty)
+        .forEach(markDtoClean);
+});
+
+export default markDtoClean;

package/src/decorator/dto/helper/markDtoDirty.ts

@@ -0,0 +1,26 @@
+import { ENABLE_DIRTY_LOGGING } from '../constant';
+import { DIRTY, NAME, PARENT, PARENT_KEY } from '../symbols';
+import assertDto from './assertDto';
+import circularProtect from './circularProtect';
+import triggerDto from './triggerDto';
+
+/**
+ * Marks the given dto dirty.
+ */
+const markDtoDirty: (obj: unknown, key?: string | number) => void = circularProtect(function (obj: unknown, key?: string | number): void {
+    assertDto(obj);
+
+    if (!obj[DIRTY]) {
+        obj[DIRTY] = true;
+        ENABLE_DIRTY_LOGGING && console.log(`%c@dto %c${obj[NAME]} %cdirty`, 'color: #0891b2', 'color: #059669', 'color: #1d4ed8', 'marked dirty', {obj, key});
+        triggerDto(obj, DIRTY, true, false);
+    }
+
+    if (!obj[PARENT]) {
+        return;
+    }
+
+    markDtoDirty(obj[PARENT], obj[PARENT_KEY]);
+});
+
+export default markDtoDirty;

package/src/decorator/dto/helper/relateDtoTo.ts

@@ -0,0 +1,13 @@
+import { CHILDREN, PARENT, PARENT_KEY } from '../symbols';
+import type DtoInstance from '../instance';
+
+/**
+ * Creates a parent-child relationship between the given two dtos.
+ */
+export default function (dto: DtoInstance<unknown>, parent: DtoInstance<unknown>, key: string): void {
+    parent[CHILDREN] ??= [];
+    !parent[CHILDREN].includes(dto) && parent[CHILDREN].push(dto);
+
+    dto[PARENT] !== parent && (dto[PARENT] = parent);
+    dto[PARENT_KEY] !== key && (dto[PARENT_KEY] = key);
+}

package/src/decorator/dto/helper/relateValueTo.ts

@@ -0,0 +1,22 @@
+import { PARENT, PARENT_KEY } from '../symbols';
+import type DtoInstance from '../instance';
+import isDto from './isDto';
+import relateDtoTo from './relateDtoTo';
+
+/**
+ * Creates relationships between the given value and dto.
+ */
+export default function (dto: DtoInstance<unknown>, key: string, value: unknown): void {
+    if (isDto(value)) {
+        relateDtoTo(value, dto, key);
+    } else if (Array.isArray(value)) {
+        if (value.some(isDto)) {
+            value
+                .filter(isDto)
+                .forEach(val => relateDtoTo(val, dto, key));
+        }
+
+        value[PARENT] = dto;
+        value[PARENT_KEY] = key;
+    }
+}

package/src/decorator/dto/helper/trackDto.ts

@@ -0,0 +1,13 @@
+import { ENABLE_REACTIVE_LOGGING } from '../constant';
+import { NAME, TRACK } from '../symbols';
+import type DtoInstance from '../instance';
+
+/**
+ * Tracking for when a dto property is being accessed.
+ */
+export default function trackDto(dto: DtoInstance<unknown>, key: string): void {
+    const track = dto[TRACK];
+    track(dto, key);
+
+    ENABLE_REACTIVE_LOGGING && console.log(`%c@dto %c${dto[NAME]} %ctrack`, 'color: #0891b2', 'color: #059669', 'color: #1d4ed8', key, {dto});
+}

package/src/decorator/dto/helper/triggerDto.ts

@@ -0,0 +1,18 @@
+import { ENABLE_REACTIVE_LOGGING } from '../constant';
+import { NAME, PARENT, PARENT_KEY, TRIGGER } from '../symbols';
+import type DtoInstance from '../instance';
+import circularProtect from './circularProtect';
+
+/**
+ * Trigger for when a dto property is being updated.
+ */
+const triggerDto: (dto: DtoInstance<unknown>, key: string | symbol, value: unknown, oldValue?: unknown) => void = circularProtect(function (dto: DtoInstance<unknown>, key: string | symbol, value: unknown, oldValue?: unknown): void {
+    const trigger = dto[TRIGGER];
+    trigger(dto, key, value, oldValue);
+
+    ENABLE_REACTIVE_LOGGING && console.log(`%c@dto %c${dto[NAME]} %ctrigger`, 'color: #0891b2', 'color: #059669', 'color: #1d4ed8', key, {dto, value, oldValue});
+
+    dto[PARENT] && triggerDto(dto[PARENT], dto[PARENT_KEY], dto[PARENT][dto[PARENT_KEY]]);
+}, 0, 1);
+
+export default triggerDto;

package/src/decorator/dto/helper/unrelateDtoFrom.ts

@@ -0,0 +1,15 @@
+import { CHILDREN, PARENT, PARENT_KEY } from '../symbols';
+import type DtoInstance from '../instance';
+
+/**
+ * Removes a parent-child relationship between the given two dtos.
+ */
+export default function (dto: DtoInstance<unknown>, parent: DtoInstance<unknown>): void {
+    if (CHILDREN in parent) {
+        const index = parent[CHILDREN].indexOf(dto);
+        parent[CHILDREN].splice(index, 1);
+    }
+
+    dto[PARENT] = undefined;
+    dto[PARENT_KEY] = undefined;
+}

package/src/decorator/dto/helper/unrelateValueFrom.ts

@@ -0,0 +1,22 @@
+import { PARENT, PARENT_KEY } from '../symbols';
+import type DtoInstance from '../instance';
+import isDto from './isDto';
+import unrelateDtoFrom from './unrelateDtoFrom';
+
+/**
+ * Removes relationships between the given value and dto.
+ */
+export default function (dto: DtoInstance<unknown>, value: unknown): void {
+    if (isDto(value)) {
+        unrelateDtoFrom(value, dto);
+    } else if (Array.isArray(value)) {
+        if (value.some(isDto)) {
+            value
+                .filter(isDto)
+                .forEach(val => unrelateDtoFrom(val, dto));
+        }
+
+        value[PARENT] = undefined;
+        value[PARENT_KEY] = undefined;
+    }
+}

package/src/decorator/dto/index.ts

@@ -0,0 +1,78 @@
+import { type Constructor, getPrototypeChain, setObjectMethod, setObjectValue } from '@basmilius/utils';
+import { OVERRIDE_CONSOLE_LOG } from './constant';
+import { instance, isDto } from './helper';
+import { DTO_CLASS_MAP } from './map';
+import { DESCRIPTORS, NAME, PROPERTIES } from './symbols';
+import classProxy from './classProxy';
+import clone from './clone';
+import fill from './fill';
+import type DtoInstance from './instance';
+import toJSON from './toJSON';
+
+/**
+ * Provides reactivity to the decorated class.
+ */
+export default function <T extends Constructor>(clazz: T): T {
+    validate(clazz);
+
+    const descriptors = Object.freeze(getPrototypeChain(clazz));
+    const properties = Object.keys(descriptors);
+
+    setObjectValue(clazz.prototype, DESCRIPTORS, descriptors);
+    setObjectValue(clazz.prototype, NAME, clazz.name);
+    setObjectValue(clazz.prototype, PROPERTIES, properties);
+    setObjectValue(clazz, Symbol.hasInstance, (instance: unknown) => typeof instance === 'object' && instance?.[NAME] === clazz.name);
+
+    setObjectMethod(clazz, 'clone', clone<T>);
+    setObjectMethod(clazz, 'fill', fill);
+    setObjectMethod(clazz, 'toJSON', toJSON);
+
+    return proxy(clazz);
+}
+
+export type {
+    DtoInstance
+};
+
+function proxy<T extends Constructor>(clazz: T): T {
+    const proxied = new Proxy(clazz, classProxy) as T;
+
+    DTO_CLASS_MAP[clazz.name] = proxied as unknown as Constructor<DtoInstance<unknown>>;
+
+    return proxied;
+}
+
+function validate(clazz: Function): void {
+    const parent = Object.getPrototypeOf(clazz.prototype);
+
+    if (NAME in parent) {
+        throw new Error(`⛔️ @dto ${clazz.name} cannot extend parent class which is also decorated with @dto ${parent[NAME]}.`);
+    }
+}
+
+if (OVERRIDE_CONSOLE_LOG) {
+    const _error = console.error.bind(console);
+    const _info = console.info.bind(console);
+    const _log = console.log.bind(console);
+    const _warn = console.warn.bind(console);
+
+    const override = (fn: Function) => (...args: unknown[]) => {
+        for (let i = args.length - 1; i >= 0; --i) {
+            const arg = args[i];
+
+            if (!isDto(arg)) {
+                continue;
+            }
+
+            const dto = instance(arg);
+            args.splice(i, 1, `📦 ${dto[NAME]}`, dto.toJSON());
+        }
+
+        return fn(...args);
+    };
+
+    console.error = override(_error);
+    console.info = override(_info);
+    console.log = override(_log);
+    console.warn = override(_warn);
+}

package/src/decorator/dto/instance.ts

@@ -0,0 +1,33 @@
+import type { Descriptors } from '@basmilius/utils';
+import type { ARGS, CHILDREN, DESCRIPTORS, DIRTY, NAME, PARENT, PARENT_KEY, PROPERTIES, TRACK, TRIGGER } from './symbols';
+
+export default interface DtoInstance<T> extends Function {
+    [ARGS]: any[];
+    [CHILDREN]?: DtoInstance<unknown>[];
+    [DESCRIPTORS]: Descriptors;
+    [DIRTY]: boolean;
+    [NAME]: string;
+    [PARENT]?: DtoInstance<unknown>;
+    [PARENT_KEY]?: string;
+    [PROPERTIES]: string[];
+    [TRACK]: (instance: DtoInstance<unknown>, key: string) => void;
+    [TRIGGER]: (instance: DtoInstance<unknown>, key: string | symbol, value: unknown, oldValue?: unknown) => void;
+
+    /**
+     * Clones the DTO starting with the original arguments
+     * and replaces them with the current values.
+     */
+    clone(): DtoInstance<T>;
+
+    /**
+     * Fills the DTO with the given data.
+     */
+    fill(data: Record<string, unknown>): void;
+
+    /**
+     * Gets all getters of the DTO and returns them as
+     * an object, so {@see JSON.stringify} knows what
+     * to do with our DTO.
+     */
+    toJSON(): Record<string, unknown>;
+}