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

Collection of libraries for building collaborative editing apps.

import type { IClock, IClockVector, ITimestampStruct, ITimespanStruct } from './types';
export declare class Timestamp implements ITimestampStruct {
    readonly sid: number;
    time: number;
    constructor(sid: number, time: number);
}
export declare class Timespan implements ITimespanStruct {
    readonly sid: number;
    time: number;
    span: number;
    constructor(sid: number, time: number, span: number);
}
/**
 * A factory function for creating a new timestamp.
 *
 * @param sid Session ID.
 * @param time Logical clock sequence number.
 * @returns A new timestamp.
 */
export declare const ts: (sid: number, time: number) => ITimestampStruct;
/**
 * A factory function for creating a new timespan.
 *
 * @param sid Session ID.
 * @param time Logical clock sequence number.
 * @param span Length of the timespan.
 * @returns A new timespan.
 */
export declare const tss: (sid: number, time: number, span: number) => ITimespanStruct;
/**
 * Advance a timestamp by a number of cycles.
 *
 * @param stamp A reference timestamp.
 * @param cycles Number of cycles to advance.
 * @returns A new timestamp.
 */
export declare const tick: (stamp: ITimestampStruct, cycles: number) => ITimestampStruct;
/**
 * Compares for equality two timestamps, time first.
 *
 * @returns True if timestamps are equal.
 */
export declare const equal: (ts1: ITimestampStruct, ts2: ITimestampStruct) => boolean;
/**
 * Compares two timestamps, time first.
 *
 * @returns 1 if current timestamp is larger, -1 if smaller, and 0 otherwise.
 */
export declare const compare: (ts1: ITimestampStruct, ts2: ITimestampStruct) => -1 | 0 | 1;
/**
 * Checks if the first timespan contains the second timespan.
 *
 * @param ts1 Start of container timespan.
 * @param span1 Length of container timespan.
 * @param ts2 Start of contained timespan.
 * @param span2 Length of contained timespan.
 * @returns Returns true if the first timespan contains the second timespan.
 */
export declare const contains: (ts1: ITimestampStruct, span1: number, ts2: ITimestampStruct, span2: number) => boolean;
/**
 * Checks if a timespan contains the `ts2` point.
 *
 * @param ts1 Start of container timespan.
 * @param span1 Length of container timespan.
 * @param ts2 A point in time.
 * @returns Returns true if the first timespan contains the `ts2` point.
 */
export declare const containsId: (ts1: ITimestampStruct, span1: number, ts2: ITimestampStruct) => boolean;
/**
 * Returns a human-readable string representation of the timestamp.
 *
 * @param id A timestamp.
 * @returns Human-readable string representation of the timestamp.
 */
export declare const printTs: (id: ITimestampStruct) => string;
/**
 * Advances a given timestamp by a number of cycles and then returns a timespan
 * starting from that position.
 *
 * @param ts A start timestamp.
 * @param tick Number of cycles to advance the starting timestamp.
 * @param span Length of the timespan.
 * @returns A new timespan.
 */
export declare const interval: (ts: ITimestampStruct, tick: number, span: number) => ITimespanStruct;
/**
 * Represents a *Logical Clock*, which can be advanced by a number of cycles.
 */
export declare class LogicalClock extends Timestamp implements IClock {
    /**
     * Returns a new timestamp, which is the current clock value, and advances the
     * clock by a number of cycles.
     *
     * @param cycles Number of cycles to advance the clock.
     * @returns A new timestamp, which is the current clock value.
     */
    tick(cycles: number): ITimestampStruct;
}
/**
 * Represents a clock vector, which is a local logical clock together with a set
 * of logical clocks of other peers.
 */
export declare class ClockVector extends LogicalClock implements IClockVector {
    /**
     * A set of logical clocks of other peers.
     */
    readonly peers: Map<number, ITimestampStruct>;
    /**
     * Advances local time every time we see any timestamp with higher time value.
     * This is an idempotent method which can be called every time a new timestamp
     * is observed, it advances the local time only if the observed timestamp is
     * greater than the current local time.
     *
     * @param id The time stamp we observed.
     * @param span Length of the time span.
     */
    observe(id: ITimestampStruct, span: number): void;
    /**
     * Returns a deep copy of the current vector clock with the same session ID.
     *
     * @returns A new vector clock, which is a clone of the current vector clock.
     */
    clone(): ClockVector;
    /**
     * Returns a deep copy of the current vector clock with a different session ID.
     *
     * @param sessionId The session ID of the new vector clock.
     * @returns A new vector clock, which is a fork of the current vector clock.
     */
    fork(sessionId: number): ClockVector;
    /**
     * Returns a human-readable string representation of the clock vector.
     *
     * @param tab String to use for indentation.
     * @returns Human-readable string representation of the clock vector.
     */
    toString(tab?: string): string;
}
/**
 * Implements a clock vector with a fixed session ID. The *server clock*
 * is used when the CRDT is powered by a central server.
 */
export declare class ServerClockVector extends LogicalClock implements IClockVector {
    /** A stub for other peers. Not used in the server clock. */
    readonly peers: Map<number, ITimespanStruct>;
    observe(ts: ITimespanStruct, span: number): void;
    clone(): ServerClockVector;
    fork(): ServerClockVector;
    /**
     * Returns a human-readable string representation of the clock vector.
     *
     * @returns Human-readable string representation of the clock vector.
     */
    toString(): string;
}