value-semantics/dist/value-semantics.d.ts

Mimic value semantics for JavaScript objects with deep cloning and equality functions

declare type ClassDecorator_<I> = (constructor: Constructor<I>, context: ClassDecoratorContext) => Constructor<I> | void;

/**
 * Creates a deep clone of a provided value.
 * @param source - The value to be cloned.
 * @returns The cloned value.
 * @public
 */
export declare function clone<T>(source: T): T;

/**
 * Class field decorators which allow the class' `clone` implementations to be customized.
 * @public
 */
export declare namespace clone {
    export function include<C, V>(_target: undefined, context: ClassFieldDecoratorContext<C, V>): void;
    export function exclude<C, V>(_target: undefined, context: ClassFieldDecoratorContext<C, V>): void;
    export function constructorParam<C, V>(_target: undefined, context: ClassFieldDecoratorContext<C, V>): void;
}

declare type Constructor<Instance> = {
    new (...args: any[]): Instance;
};

/**
 * Class decorators which allow the class' `equals` and `clone` implementations to be customized.
 * @public
 */
export declare namespace customize {
    const clone: typeof customizeClone;
    const equals: typeof customizeEquals;
    export function value<I extends object>(options?: CustomizeValueOptions): ClassDecorator_<I>;
    export function value<I extends object>(// Clone Semantics
    cloneSemantics: 'deep', options?: CustomizeValueOptions): ClassDecorator_<I>;
    export function value<I extends object>(cloneSemantics: 'returnOriginal' | 'errorOnClone', options?: CustomizeEqualsOptions): ClassDecorator_<I>;
    export function value<I extends object>(// Equals Semantics
    equalsSemantics: 'value', options?: CustomizeValueOptions): ClassDecorator_<I>;
    export function value<I extends object>(equalsSemantics: 'ref', options?: CustomizeCloneOptions): ClassDecorator_<I>;
    export function value<I extends object>(// Clone then Equals Semantics
    cloneSemantics: 'deep', equalsSemantics: 'value', options?: CustomizeValueOptions): ClassDecorator_<I>;
    export function value<I extends object>(cloneSemantics: 'deep', equalsSemantics: 'ref', options?: CustomizeCloneOptions): ClassDecorator_<I>;
    export function value<I extends object>(cloneSemantics: 'returnOriginal' | 'errorOnClone', equalsSemantics: 'value', options?: CustomizeEqualsOptions): ClassDecorator_<I>;
    export function value<I extends object>(cloneSemantics: 'returnOriginal' | 'errorOnClone', equalsSemantics: 'ref'): ClassDecorator_<I>;
    export function value<I extends object>(// Equals then Clone Semantics
    equalsSemantics: 'value', cloneSemantics: 'deep', options?: CustomizeValueOptions): ClassDecorator_<I>;
    export function value<I extends object>(equalsSemantics: 'value', cloneSemantics: 'returnOriginal' | 'errorOnClone', options?: CustomizeEqualsOptions): ClassDecorator_<I>;
    export function value<I extends object>(equalsSemantics: 'ref', cloneSemantics: 'deep', options?: CustomizeCloneOptions): ClassDecorator_<I>;
    export function value<I extends object>(equalsSemantics: 'ref', cloneSemantics: 'returnOriginal' | 'errorOnClone'): ClassDecorator_<I>;
}

declare function customizeClone<I extends object>(options?: CustomizeCloneOptions): ClassDecorator_<I>;

declare function customizeClone<I extends object>(semantics: 'deep', options?: CustomizeCloneOptions): ClassDecorator_<I>;

declare function customizeClone<I extends object>(semantics: 'returnOriginal' | 'errorOnClone'): ClassDecorator_<I>;

declare type CustomizeCloneOptions = {
    runConstructor?: boolean;
    propDefault?: 'include' | 'exclude';
};

declare function customizeEquals<I extends object>(options?: CustomizeEqualsOptions): ClassDecorator_<I>;

declare function customizeEquals<I extends object>(semantics: 'value', options?: CustomizeEqualsOptions): ClassDecorator_<I>;

declare function customizeEquals<I extends object>(semantics: 'ref'): ClassDecorator_<I>;

declare type CustomizeEqualsOptions = {
    propDefault?: 'include' | 'exclude';
};

declare type CustomizeValueOptions = CustomizeCloneOptions;

/**
 * Compares two values for value-equality.
 * @param lhs - The first value to compare.
 * @param rhs - The second value to compare.
 * @returns Whether the two values are value-equal.
 * @public
 */
export declare function equals(lhs: unknown, rhs: unknown): boolean;

/**
 * Class field decorators which allow the class' `equals` implementations to be customized.
 * @public
 */
export declare namespace equals {
    export function include<C, V>(_target: undefined, context: ClassFieldDecoratorContext<C, V>): void;
    export function exclude<C, V>(_target: undefined, context: ClassFieldDecoratorContext<C, V>): void;
}

export declare namespace value {
    export function include<C, V>(target: undefined, context: ClassFieldDecoratorContext<C, V>): void;
    export function exclude<C, V>(target: undefined, context: ClassFieldDecoratorContext<C, V>): void;
}

export { }