entangle.ts/dist/shared/Notation.d.ts

A declarative, event-driven framework for orchestrating business logic in TypeScript & Node.js applications.

/**
 * A type-safe, fluent builder for creating dot-notation accessors for nested objects.
 * It provides compile-time safety and autocompletion for object properties and array indices.
 *
 * @template TRoot The type of the root object where the search begins.
 * @template TCurrent The type of the value at the current point in the notation chain.
 */
export declare class Notation<TRoot, TCurrent> {
    /**
     * The internal notation string, built step-by-step.
     * @private
     */
    private readonly _notation;
    private constructor();
    /**
     * Starts building a new type-safe notation path.
     * @template TData The type of the data object this notation will operate on.
     */
    static create<TData>(currentNotation?: string): Notation<TData, TData>;
    /**
     * Appends a property access to the notation path.
     * The compiler will only allow keys that exist on the current type.
     * @param prop The key of the property to access.
     * @returns A new Notation instance focused on the type of the accessed property.
     */
    property<K extends keyof TCurrent>(prop: K): Notation<TRoot, TCurrent[K]>;
    /**
     * Appends an index access to the notation path.
     * This method should be used when the current focus is an array.
     * @param i The index of the array to access.
     * @returns A new Notation instance focused on the type of the array element.
     */
    index(i: number): Notation<TRoot, TCurrent extends (infer U)[] ? U : never>;
    /**
     * @returns The raw, built notation string (e.g., 'user.profile.name').
     */
    get(): NotationString;
    /**
     * Safely executes the notation against a root data object.
     * The return type is safely inferred from the chain of calls.
     * @param data The root object to retrieve the value from. It must match the TRoot type.
     * @returns The resolved value, or `undefined` if the path is not found.
     */
    getData(data?: TRoot): TCurrent | undefined;
}
declare const notationBrand: unique symbol;
/**
 * Represents a type-safe, built notation string.
 * It is structurally different from a regular string to prevent accidental misuse,
 * ensuring that only strings generated by the Notation builder can be used where
 * a NotationString is required.
 */
export type NotationString = string & {
    [notationBrand]: never;
};
export {};