Options
All
  • Public
  • Public/Protected
  • All
Menu

A shared data type provides a custom algorithmic abstract data type for atomic, mutable subject property values in the domain. The implementation must be able to guarantee convergence of values in remote clones after local updates and remote operations.

Within the supporting framework of m-ld, a shared data type defines a Conflict-free Shared Data Type (CRDT). That support comprises the following features which may simplify the requirements on the implementation:

  1. Operations will only be applied once. The implementation therefore does not need to ensure that operations are idempotent (though it still needs to ensure they are commutative).

  2. Operations will be applied in causal order. The implementation does not need to maintain clock information for processes, unless this is needed for some aspect of the merge algorithm beyond causal ordering per se.

  3. Data state is maintained in memory for 'active' shared data which is being operated on, for example a user typing into a document. The methods of this class allow state to be mutated without copying.

Type parameters

  • Data

    data type

  • Operation

    operation type; must be JSON-serialisable

  • Revert

    reversion local metadata type; must be JSON-serialisable

Hierarchy

Implemented by

Index

Properties

Readonly @id

@id: string

The identity of the datatype itself. Used in the internal representation, which is visible to query filters; but a canonical json-rql Value is substituted in retrieval and updates.

Methods

apply

  • apply(state: Data, reversions: [Operation, undefined | Revert][], operation?: Operation): [Data, Expression | Expression[], undefined | Revert]
  • Applies an operation to some state. The implementation is welcome to mutate the passed state and return it as the new state. Doing so is encouraged if the state is memory-intensive, as only a single copy will be maintained in memory across multiple operations and updates.

    Parameters

    • state: Data

      the existing state of the shared value

    • reversions: [Operation, undefined | Revert][]

      any reversions (voiding) to apply before the new operation, provided in reverse order of original application

    • Optional operation: Operation

    Returns [Data, Expression | Expression[], undefined | Revert]

    the new state (can be the input), an update expression to notify the app, and local metadata required to revert the operation (if applicable).

cut

  • cut(prefix: Operation, operation: Operation): Operation | undefined
  • Cuts the prefix from the given operation and returns an operation which can be safely applied to a state that has the prefix already applied, e.g.

    • If the operation type is a list of sequential operations, the result can be a slice of the given operation at the prefix length.
    • If this datatype's operations are idempotent, the operation can be returned as-is.

    Parameters

    • prefix: Operation
    • operation: Operation

    Returns Operation | undefined

Optional fromJSON

  • fromJSON(json: any): Data
  • Deserialises data. If this method is not provided, the data must be directly deserialisable from JSON.

    see

    toJSON

    Parameters

    • json: any

    Returns Data

fuse

  • fuse(operation: [Operation, undefined | Revert], suffix: [Operation, undefined | Revert]): [Operation, undefined | Revert]
  • Fuses local operations into a single operation. Operations are be provided in contiguous application order. Reversion metadata may not be included in the parameters; if so, it's not required in the return.

    Parameters

    • operation: [Operation, undefined | Revert]
    • suffix: [Operation, undefined | Revert]

    Returns [Operation, undefined | Revert]

getDataId

  • A shared data type MUST always generate a new unique identity as its lexical value, for which mutable state will exist. This will only be called once per logical instance.

    Returns UUID

Optional toJSON

  • toJSON(data: Data): any
  • Convert data to a representation that can be stringified to JSON. If this method is not provided, the data itself must be JSON serialisable. The implementation should include a version if the format is likely to change.

    see

    fromJSON

    Parameters

    • data: Data

    Returns any

Optional toValue

  • toValue(data: Data): Value
  • Provides a value to appear when the data is retrieved. The datatype should always accept the returned value forms in its validate method. If the value's type should be anything other than this datatype's @id, a ValueObject should be returned including the desired @type, even if it's a built-in type like xs:string. The value object will be compacted as normal in the application API.

    If the returned value is an expanded ValueObject, its datatype MUST be a fully expanded IRI.

    If this method is not provided, the data itself MUST be a valid API value.

    Parameters

    • data: Data

    Returns Value

update

  • update(state: Data, update: Expression): [Data, Operation, undefined | Revert]
  • Intercepts update of data. The implementation is welcome to mutate the passed state and return it as the new state. Doing so is encouraged if the state is memory-intensive, as only a single copy will be maintained in memory across multiple operations and updates. The backend may later revert the returned operation in case of rollback.

    Parameters

    • state: Data

      the new state of the shared value

    • update: Expression

      the json-rql expression used to perform the update

    Returns [Data, Operation, undefined | Revert]

    the new state of the data, an operation which can be applied, and any additional local metadata required to revert the operation (if applicable). If the revert is not supplied, it is assumed that no metadata is required to revert the operation.

validate

  • validate(value: Value): Data | undefined
  • Parses a value provided by the app. This may give the application some leeway in type strictness; but note that the value provided back to the app will always be that returned by {@link Datatype#toValue}, if provided, or the Data itself if not.

    If the provided value is an expanded ValueObject, its datatype will be a fully pre-expanded IRI.

    throws

    TypeError if a validation message is indicated

    Parameters

    Returns Data | undefined

    the valid data, or undefined if the data is not valid

Legend

  • Constructor
  • Property
  • Method
  • Property
  • Method
  • Inherited property
  • Inherited method
  • Static property
  • Static method
  • Protected method

Generated using TypeDoc. Delivered by Vercel. @m-ld/m-ld - v0.10.1-edge.4 Source code licensed MIT. Privacy policy