json-joy/lib/json-crdt-patch/PatchBuilder.d.ts

Collection of libraries for building collaborative editing apps.

import { type IClock, type ITimestampStruct, type ITimespanStruct, Timestamp } from './clock';
import { Patch } from './Patch';
/**
 * Utility class that helps in Patch construction.
 *
 * @category Patch
 */
export declare class PatchBuilder {
    clock: IClock;
    /** The patch being constructed. */
    patch: Patch;
    /**
     * Creates a new PatchBuilder instance.
     *
     * @param clock Clock to use for generating timestamps.
     */
    constructor(clock: IClock);
    /**
     * Retrieve the sequence number of the next timestamp.
     *
     * @returns The next timestamp sequence number that will be used by the builder.
     */
    nextTime(): number;
    /**
     * Returns the current {@link Patch} instance and resets the builder.
     *
     * @returns A new {@link Patch} instance containing all operations created
     *          using this builder.
     */
    flush(): Patch;
    /**
     * Create a new "obj" LWW-Map object.
     *
     * @returns ID of the new operation.
     */
    obj(): ITimestampStruct;
    /**
     * Create a new "arr" RGA-Array object.
     *
     * @returns ID of the new operation.
     */
    arr(): ITimestampStruct;
    /**
     * Create a new "vec" LWW-Array vector.
     *
     * @returns ID of the new operation.
     */
    vec(): ITimestampStruct;
    /**
     * Create a new "str" RGA-String object.
     *
     * @returns ID of the new operation.
     */
    str(): ITimestampStruct;
    /**
     * Create a new "bin" RGA-Binary object.
     *
     * @returns ID of the new operation.
     */
    bin(): ITimestampStruct;
    /**
     * Create a new immutable constant JSON value. Can be anything, including
     * nested arrays and objects.
     *
     * @param value JSON value
     * @returns ID of the new operation.
     */
    const(value: unknown): ITimestampStruct;
    /**
     * Create a new "val" LWW-Register object. Can be anything, including
     * nested arrays and objects.
     *
     * @param val Reference to another object.
     * @returns ID of the new operation.
     * @todo Rename to `newVal`.
     */
    val(): ITimestampStruct;
    /**
     * Set value of document's root LWW-Register.
     *
     * @returns ID of the new operation.
     */
    root(val: ITimestampStruct): ITimestampStruct;
    /**
     * Set fields of an "obj" object.
     *
     * @returns ID of the new operation.
     */
    insObj(obj: ITimestampStruct, data: [key: string, value: ITimestampStruct][]): ITimestampStruct;
    /**
     * Set elements of a "vec" object.
     *
     * @returns ID of the new operation.
     */
    insVec(obj: ITimestampStruct, data: [index: number, value: ITimestampStruct][]): ITimestampStruct;
    /**
     * Set value of a "val" object.
     *
     * @returns ID of the new operation.
     * @todo Rename to "insVal".
     */
    setVal(obj: ITimestampStruct, val: ITimestampStruct): ITimestampStruct;
    /**
     * Insert a substring into a "str" object.
     *
     * @returns ID of the new operation.
     */
    insStr(obj: ITimestampStruct, ref: ITimestampStruct, data: string): ITimestampStruct;
    /**
     * Insert binary data into a "bin" object.
     *
     * @returns ID of the new operation.
     */
    insBin(obj: ITimestampStruct, ref: ITimestampStruct, data: Uint8Array): ITimestampStruct;
    /**
     * Insert elements into an "arr" object.
     *
     * @returns ID of the new operation.
     */
    insArr(arr: ITimestampStruct, ref: ITimestampStruct, data: ITimestampStruct[]): ITimestampStruct;
    /**
     * Delete a span of operations.
     *
     * @param obj Object in which to delete something.
     * @param what List of time spans to delete.
     * @returns ID of the new operation.
     */
    del(obj: ITimestampStruct, what: ITimespanStruct[]): ITimestampStruct;
    /**
     * Operation that does nothing just skips IDs in the patch.
     *
     * @param span Length of the operation.
     * @returns ID of the new operation.
     *
     */
    nop(span: number): ITimestampStruct;
    /**
     * Run the necessary builder commands to create an arbitrary JSON object.
     */
    jsonObj(obj: object): ITimestampStruct;
    /**
     * Run the necessary builder commands to create an arbitrary JSON array.
     */
    jsonArr(arr: unknown[]): ITimestampStruct;
    /**
     * Run builder commands to create a JSON string.
     */
    jsonStr(str: string): ITimestampStruct;
    /**
     * Run builder commands to create a binary data type.
     */
    jsonBin(bin: Uint8Array): ITimestampStruct;
    /**
     * Run builder commands to create a JSON value.
     */
    jsonVal(value: unknown): ITimestampStruct;
    /**
     * Run builder commands to create a tuple.
     */
    jsonVec(vector: unknown[]): ITimestampStruct;
    /**
     * Run the necessary builder commands to create any arbitrary JSON value.
     */
    json(json: unknown): ITimestampStruct;
    /**
     * Given a JSON `value` creates the necessary builder commands to create
     * JSON CRDT Patch operations to construct the value. If the `value` is a
     * timestamp, it is returned as-is. If the `value` is a JSON primitive is
     * a number, boolean, or `null`, it is converted to a "con" data type. Otherwise,
     * the `value` is converted using the {@link PatchBuilder.json} method.
     *
     * @param value A JSON value for which to create JSON CRDT Patch construction operations.
     * @returns ID of the root constructed CRDT object.
     */
    constOrJson(value: unknown): ITimestampStruct;
    /**
     * Creates a "con" data type unless the value is already a timestamp, in which
     * case it is returned as-is.
     *
     * @param value Value to convert to a "con" data type.
     * @returns ID of the new "con" object.
     */
    maybeConst(value: unknown | Timestamp): Timestamp;
    /**
     * Add padding "noop" operation if clock's time has jumped. This method checks
     * if clock has advanced past the ID of the last operation of the patch and,
     * if so, adds a "noop" operation to the patch to pad the gap.
     */
    pad(): void;
}