@rimbu/deep/dist/esm/selector.d.mts

Tools to use handle plain JS objects as immutable objects

import type { IsAnyFunc, IsArray } from '@rimbu/base';
import { type Path, type Protected } from './internal.mjs';
/**
 * Type defining the allowed selectors on an object of type `T`.
 * Selectors can be:
 * - a path string into type `T`.
 * - a function receiving a `Protected` version of type `T`, and returning an arbitrary value.
 * - a tuple of `Selectors` for type `T`
 * - an object where the property values are `Selectors` for type `T`.
 * @typeparam T - the source value type.
 */
export type Selector<T> = Path.Get<T> | ((value: Protected<T>) => any) | readonly Selector<T>[] | {
    readonly [key: string | symbol]: Selector<T>;
};
export declare namespace Selector {
    /**
     * Type defining the shape of allowed selectors, used to improve compiler checking.
     * @typeparam SL - the selector type
     */
    type Shape<SL> = IsAnyFunc<SL> extends true ? SL : IsArray<SL> extends true ? readonly [...(SL extends readonly unknown[] ? SL : never)] : SL extends {
        readonly [key: string | number | symbol]: unknown;
    } ? {
        readonly [K in keyof SL]: Selector.Shape<SL[K]>;
    } : SL;
    /**
     * Type defining the result type of applying the SL selector type to the T value type.
     * @typeparam T - the source value type
     * @typeparam SL - the selector type
     */
    type Result<T, SL> = Selector<T> extends SL ? never : SL extends (...args: any[]) => infer R ? R : SL extends string ? Path.Result<T, SL> : {
        readonly [K in keyof SL]: Selector.Result<T, SL[K]>;
    };
}
/**
 * Returns the result of applying the given `selector` shape to the given `source` value.
 * @typeparam T - the patch value type
 * @typeparam SL - the selector shape type
 * @param source - the source value to select from
 * @param selector - a shape indicating the selection from the source values
 * @example
 * ```ts
 * const item = { a: { b:  1, c: 'a' } };
 * Deep.select(item, { q: 'a.c', y: ['a.b', 'a.c'], z: (v) => v.a.b + 1 });
 * // => { q: 'a', y: [1, 'a'], z: 2 }
 * ```
 */
export declare function select<T, SL extends Selector<T>>(source: T, selector: Selector.Shape<SL>): Selector.Result<T, SL>;