json-joy/lib/json-crdt/model/api/nodes.d.ts

Collection of libraries for building collaborative editing apps.

import { type ITimestampStruct } from '../../../json-crdt-patch/clock';
import type { Path } from '@jsonjoy.com/json-pointer';
import { ObjNode, ArrNode, BinNode, ConNode, VecNode, ValNode, StrNode } from '../../nodes';
import { NodeEvents } from './NodeEvents';
import { ExtNode } from '../../extensions/ExtNode';
import type { Extension } from '../../extensions/Extension';
import type { ExtApi } from '../../extensions/types';
import type { JsonNode, JsonNodeView } from '../../nodes';
import type * as types from './proxy';
import type { ModelApi } from './ModelApi';
import type { Printable } from 'tree-dump/lib/types';
import type { JsonNodeApi } from './types';
import type { VecNodeExtensionData } from '../../schema/types';
export type ApiPath = string | number | Path | undefined;
/**
 * A generic local changes API for a JSON CRDT node.
 *
 * @category Local API
 */
export declare class NodeApi<N extends JsonNode = JsonNode> implements Printable {
    node: N;
    readonly api: ModelApi<any>;
    constructor(node: N, api: ModelApi<any>);
    /** @ignore */
    private ev;
    /**
     * Event target for listening to node changes. You can subscribe to `"view"`
     * events, which are triggered every time the node's view changes.
     *
     * ```ts
     * node.events.on('view', () => {
     *   // do something...
     * });
     * ```
     */
    get events(): NodeEvents<N>;
    /**
     * Find a child node at the given path starting from this node.
     *
     * @param path Path to the child node to find.
     * @returns JSON CRDT node at the given path.
     */
    find(path?: ApiPath): JsonNode;
    /**
     * Find a child node at the given path starting from this node and wrap it in
     * a local changes API.
     *
     * @param path Path to the child node to find.
     * @returns Local changes API for the child node at the given path.
     */
    in(path?: ApiPath): ValApi<ValNode<any>>;
    asVal(): ValApi;
    asStr(): StrApi;
    asBin(): BinApi;
    asArr(): ArrApi;
    asVec(): VecApi;
    asObj(): ObjApi;
    asCon(): ConApi;
    /**
     * Returns the API object of the extension if the node is an extension node.
     * When the `ext` parameter is provided, it checks if the node is an instance
     * of the given extension and returns the object's TypeScript type. Otherwise,
     * it returns the API object of the extension, but without any type checking.
     *
     * @param ext Extension of the node
     * @returns API of the extension
     */
    asExt(): JsonNodeApi<VecNodeExtensionData<N>> | ExtApi<any> | undefined;
    asExt<EN extends ExtNode<any, any>, EApi extends ExtApi<EN>>(ext: Extension<any, any, EN, EApi, any, any>): EApi;
    val(path?: ApiPath): ValApi;
    str(path?: ApiPath): StrApi;
    bin(path?: ApiPath): BinApi;
    arr(path?: ApiPath): ArrApi;
    vec(path?: ApiPath): VecApi;
    obj(path?: ApiPath): ObjApi;
    con(path?: ApiPath): ConApi;
    view(): JsonNodeView<N>;
    proxy(): types.ProxyNode<N>;
    toString(tab?: string): string;
}
/**
 * Represents the local changes API for the `con` JSON CRDT node {@link ConNode}.
 *
 * @category Local API
 */
export declare class ConApi<N extends ConNode<any> = ConNode<any>> extends NodeApi<N> {
    /**
     * Returns a proxy object for this node.
     */
    proxy(): types.ProxyNodeCon<N>;
}
/**
 * Local changes API for the `val` JSON CRDT node {@link ValNode}.
 *
 * @category Local API
 */
export declare class ValApi<N extends ValNode<any> = ValNode<any>> extends NodeApi<N> {
    /**
     * Get API instance of the inner node.
     * @returns Inner node API.
     */
    get(): JsonNodeApi<N extends ValNode<infer T> ? T : JsonNode>;
    /**
     * Sets the value of the node.
     *
     * @param json JSON/CBOR value or ID (logical timestamp) of the value to set.
     * @returns Reference to itself.
     */
    set(json: JsonNodeView<N>): void;
    /**
     * Returns a proxy object for this node. Allows to access the value of the
     * node by accessing the `.val` property.
     */
    proxy(): types.ProxyNodeVal<N>;
}
type UnVecNode<N> = N extends VecNode<infer T> ? T : never;
/**
 * Local changes API for the `vec` JSON CRDT node {@link VecNode}.
 *
 * @category Local API
 */
export declare class VecApi<N extends VecNode<any> = VecNode<any>> extends NodeApi<N> {
    /**
     * Get API instance of a child node.
     *
     * @param key Object key to get.
     * @returns A specified child node API.
     */
    get<K extends keyof UnVecNode<N>>(key: K): JsonNodeApi<UnVecNode<N>[K]>;
    /**
     * Sets a list of elements to the given values.
     *
     * @param entries List of index-value pairs to set.
     * @returns Reference to itself.
     */
    set(entries: [index: number, value: unknown][]): void;
    push(...values: unknown[]): void;
    /**
     * Get the length of the vector without materializing it to a view.
     *
     * @returns Length of the vector.
     */
    length(): number;
    /**
     * Returns a proxy object for this node. Allows to access vector elements by
     * index.
     */
    proxy(): types.ProxyNodeVec<N>;
}
type UnObjNode<N> = N extends ObjNode<infer T> ? T : never;
/**
 * Local changes API for the `obj` JSON CRDT node {@link ObjNode}.
 *
 * @category Local API
 */
export declare class ObjApi<N extends ObjNode<any> = ObjNode<any>> extends NodeApi<N> {
    /**
     * Get API instance of a child node.
     *
     * @param key Object key to get.
     * @returns A specified child node API.
     */
    get<K extends keyof UnObjNode<N>>(key: K): JsonNodeApi<UnObjNode<N>[K]>;
    /**
     * Sets a list of keys to the given values.
     *
     * @param entries List of key-value pairs to set.
     * @returns Reference to itself.
     */
    set(entries: Partial<JsonNodeView<N>>): void;
    /**
     * Deletes a list of keys from the object.
     *
     * @param keys List of keys to delete.
     * @returns Reference to itself.
     */
    del(keys: string[]): void;
    /**
     * Returns a proxy object for this node. Allows to access object properties
     * by key.
     */
    proxy(): types.ProxyNodeObj<N>;
}
/**
 * Local changes API for the `str` JSON CRDT node {@link StrNode}. This API
 * allows to insert and delete bytes in the UTF-16 string by referencing its
 * local character positions.
 *
 * @category Local API
 */
export declare class StrApi extends NodeApi<StrNode> {
    /**
     * Inserts text at a given position.
     *
     * @param index Position at which to insert text.
     * @param text Text to insert.
     * @returns Reference to itself.
     */
    ins(index: number, text: string): void;
    /**
     * Deletes a range of text at a given position.
     *
     * @param index Position at which to delete text.
     * @param length Number of UTF-16 code units to delete.
     * @returns Reference to itself.
     */
    del(index: number, length: number): void;
    /**
     * Given a character index in local coordinates, find the ID of the character
     * in the global coordinates.
     *
     * @param index Index of the character or `-1` for before the first character.
     * @returns ID of the character after which the given position is located.
     */
    findId(index: number | -1): ITimestampStruct;
    /**
     * Given a position in global coordinates, find the position in local
     * coordinates.
     *
     * @param id ID of the character.
     * @returns Index of the character in local coordinates. Returns -1 if the
     *          the position refers to the beginning of the string.
     */
    findPos(id: ITimestampStruct): number | -1;
    /**
     * Get the length of the string without materializing it to a view.
     *
     * @returns Length of the string.
     */
    length(): number;
    /**
     * Returns a proxy object for this node.
     */
    proxy(): types.ProxyNodeStr;
}
/**
 * Local changes API for the `bin` JSON CRDT node {@link BinNode}. This API
 * allows to insert and delete bytes in the binary string by referencing their
 * local index.
 *
 * @category Local API
 */
export declare class BinApi extends NodeApi<BinNode> {
    /**
     * Inserts octets at a given position.
     *
     * @param index Position at which to insert octets.
     * @param data Octets to insert.
     * @returns Reference to itself.
     */
    ins(index: number, data: Uint8Array): void;
    /**
     * Deletes a range of octets at a given position.
     *
     * @param index Position at which to delete octets.
     * @param length Number of octets to delete.
     * @returns Reference to itself.
     */
    del(index: number, length: number): void;
    /**
     * Get the length of the binary blob without materializing it to a view.
     *
     * @returns Length of the binary blob.
     */
    length(): number;
    /**
     * Returns a proxy object for this node.
     */
    proxy(): types.ProxyNodeBin;
}
type UnArrNode<N> = N extends ArrNode<infer T> ? T : never;
/**
 * Local changes API for the `arr` JSON CRDT node {@link ArrNode}. This API
 * allows to insert and delete elements in the array by referencing their local
 * index.
 *
 * @category Local API
 */
export declare class ArrApi<N extends ArrNode<any> = ArrNode<any>> extends NodeApi<N> {
    /**
     * Get API instance of a child node.
     *
     * @param index Index of the element to get.
     * @returns Child node API for the element at the given index.
     */
    get(index: number): JsonNodeApi<UnArrNode<N>>;
    /**
     * Inserts elements at a given position.
     *
     * @param index Position at which to insert elements.
     * @param values JSON/CBOR values or IDs of the values to insert.
     * @returns Reference to itself.
     */
    ins(index: number, values: Array<JsonNodeView<N>[number]>): void;
    /**
     * Deletes a range of elements at a given position.
     *
     * @param index Position at which to delete elements.
     * @param length Number of elements to delete.
     * @returns Reference to itself.
     */
    del(index: number, length: number): void;
    /**
     * Get the length of the array without materializing it to a view.
     *
     * @returns Length of the array.
     */
    length(): number;
    /**
     * Returns a proxy object that allows to access array elements by index.
     *
     * @returns Proxy object that allows to access array elements by index.
     */
    proxy(): types.ProxyNodeArr<N>;
}
export {};