otrie/dist/Utils.d.ts

Observable Path Trie Store

export type StateValue = string | boolean | number | null | undefined | object | Array<StateValue> | StateRecord | bigint;
export type StateRecord = {
    [key: string]: StateValue;
};
export type Action = SetAction | DeleteAction | BatchAction;
/** Details about a single or a batch change. */
export interface StateChange<T extends StateValue = StateValue> {
    /** A node value before the change. */
    oldValue: T | undefined;
    /** A node value after the change. */
    value: T;
    /**
     * All changed paths relative to the observed node (starting from the observed node path).
     * The order of the paths may not correlate with the order of the applied changes.
     *
     * It can be a single path for an atomic change or a set of paths for a batch.
     * If multiple paths are present only non-overlapping paths are reported
     * and for 2 overlapping paths the shorter one is reported.
     * An empty array of paths will be returned if the node value is changed because its parent was overwritten
     * and the node value is undefined now.
     *
     * Examples:
     * For two changes in the batch ["a", "b", "c"] and ["a", "b"] only one shorter path will be reported: [["a", "b"]].
     * For the state `{a: {b: {c: 1}}}` after `set(['a', 'b', 'c'], 2)` operation the following paths will be reported:
     *  - For an observer at path ['a', 'b', 'c'] => [[]].
     *  - For an observer at path ['a', 'b'] => [['c']].
     *  - For an observer at path [] => [['b', 'c']].
     *  - For an observer at path [] => [['a', 'b', 'c']].
     *  For the state `{a: {b: {c: 1}}}` after `set(['a', 'b'], {})` operation the following paths will be reported:
     *   - For an observer at path ['a', 'b', 'c'] => []. (no paths -> parent was modified, not node 'c').
     *   - For an observer at path ['a', 'b'] => [[]].
     *   - For an observer at path [] => ['b'].
     *   - For an observer at path [] => ['a', 'b'].
     */
    paths: Array<string[]>;
}
export interface SetAction {
    type: 'set';
    path: string[];
    value: StateValue;
}
export interface DeleteAction {
    type: 'delete';
    path: string[];
}
export interface BatchAction {
    type: 'batch';
    actions: Array<Action>;
}
export declare function apply(state: StateRecord, action: Action): StateRecord;
/**
 * Sets a new state to the path.
 * Allows to re-set a root path, but requires the new root state to be a record.
 * Never modifies existing state: optimally deep-clones the existing state on the modified path and returns a new cloned state.
 * Returns the original state if there are no changes as the result of the call or if the root path was reset.
 * Setting an undefined value is equal to a call of `deleteInPath`.
 */
export declare function setInPath(state: StateRecord, path: ReadonlyArray<string>, newValue: StateValue): StateRecord;
/**
 * Deletes a value in the path.
 * Returns a new changed state.
 * If there is no value to delete, does nothing and returns the original state.
 * The method will throw an error
 */
export declare function deleteInPath(state: StateRecord, path: ReadonlyArray<string>): StateRecord;
/**
 * Clones `state` and patches the record in the cloned state specified by the `path` with `patchValue` .
 * The result is always a cloned object.
 */
export declare function deepCloneOnPath(originalState: Readonly<StateRecord>, path: ReadonlyArray<string>, patchValue: StateValue | undefined): StateRecord;
/**
 * Extracts all paths from actions into a single array of paths.
 * Returns a sorted array of unique actions if `mode` is `unique-and-sorted`
 * or all paths in the original order if `mode` is `as-is`.
 */
export declare function extractPaths(action: Action, mode: 'unique-and-sorted' | 'as-is'): Array<string[]>;
/** Returns true if `path` has a prefix equal to `prefixPath` or is equal to `prefixPath`. */
export declare function isPathPrefix(path: string[], prefixPath: string[]): boolean;
/** Sorts paths by string value and next by length. */
export declare function sortPaths(paths: Array<string[]>): Array<string[]>;
/**
 * Remove child subpaths from the list of paths.
 * Keeps only short parent paths.
 */
export declare function selectUniquePathPrefixes(paths: Array<string[]>): Array<string[]>;
/**
 * Selects unique paths from the given path array.
 * The returned array contains sorted paths.
 */
export declare function selectUniquePaths(paths: Array<string[]>): Array<string[]>;