import { Primitive } from './Types.js';

/**
 * Clones an object or array.
 *
 * > Note: This works only for flat objects not for objects which are instances of classes.
 *
 * > Note: Cycles in `obj` are not supported for now.
 *
 * @example
 * ```ts
 * import clone from "apprt-core/clone";
 *
 * const src = {x: 1, y: { a: 2 } };
 * const copy = clone(src);
 * src === copy // -> false
 * src.y === copy.y // -> false
 * copy.y.a // -> 2
 * ```
 * @typeParam T the type of the input object to clone
 * @param obj Object or array to clone.
 */
declare function clone<T extends Record<any, any> | any[] | Primitive>(obj: T): T;
/**
 * Context given to the valueTransformer function of the transform method.
 *
 * It provides some metadata for the current value to transform.
 * The `remove()` method can be used to complete hide the current value from the target instance.
 */
interface TransformContext {
    /**
     * The parent objects of the current value.
     */
    readonly parents: readonly any[];
    /**
     * The property path from the root object to the current value.
     *
     * Entries represent the path taken (property names, indices) to reach the current value.
     *
     * This array has the same length and the same order as {@link parents}.
     */
    readonly path: readonly (string | number | symbol)[];
    /**
     * Can be used by a value transformer to inform the transformer method about removing the current value.
     */
    remove(): symbol;
    /**
     * Can be used by a value transformer to inform the transformer method about keeping the current value untouched.
     * This is helpful to supports complex class instances or skipping the default clone behavior.
     */
    keepAsIs(): symbol;
}
/**
 * The type of a transform function accepted by {@link transform}.
 *
 * The function receives the current value and its context, and may return a new value
 * to replace `value`.
 *
 * Returning `value` from this function will cause `value` to be _cloned_.
 * Special values to remove a value or to keep it as is are accessible via the provided {@link TransformContext}.
 */
type TransformFunc = (value: any, ctx: TransformContext) => any | symbol;
/**
 * This method creates a clone of the given value.
 * and allows customization of the value by a valueTransformer function.
 *
 * By default this works only for flat objects and not for objects which are instances of classes.
 * But a `valueTransformer` is able to transform input classes to target classes or keep them as is.
 *
 * > Note: Cycles in `value` are not supported for now.
 *
 * @example simple clone
 *
 * ```ts
 * import {transform} from "apprt-core/clone";
 * const input = { x: 1, c: {a: 1} };
 * const copyOfInput = transform(input);
 * ```
 *
 * @example transformation
 * ```ts
 * import {transform} from "apprt-core/clone";
 * const input = { x: 1, c: { a: 1 } };
 * const transformedCopy = transform(input, (value, ctx) => {
 *     if (ctx.path[ctx.path.length - 1] === "c") {
 *         // value is { a: 1 }
 *         // change c to be a number
 *         return value.a;
 *     }
 *     return value;
 * });
 * // -> transformedCopy === { x: 1, c: 1 }
 * ```
 */
declare function transform<Input = any, Output = Input>(value: Input, valueTransformer?: TransformFunc): Output;

export { clone, clone as default, transform };
export type { TransformContext, TransformFunc };