3.0.3 • Published 3 years ago

@tangle/complex-set

Licence

LGPL-3.0-or-later

Version

3.0.3

Deps

Size

27 kB

Vulns

Weekly

Summary Dependency Versions

@tangle/complex-set

A strategy for tracking a set over time, when it matters when a certain thing was added to a Set, and when it was removed

Example Usage

const ComplexSet = require('@tangle/complex-set')

const input = {
  add: [
    { id: '@ben', seq: 25 },
    { id: '@cherese', seq: 2 }
  ]
}

strategy.mapFromInput(input, [strategy.identity()])
// => {
//   '@ben': { 25: 1 },
//   'cherese: { 2: 1 }
// }

The raw transformations look like this:

{
  [id]: {
    [seq]: state
  }
}

where

id String - the thing being added / removed from the set
seq Integer - some Integer which is a unique representation of when. (e.g. logical clock or clock wall time). Must be >= 0
state Integer - an Integer representing whether it was an add or remove.
- state > 0 - add
- state <= 0 - remove

However there are convenience methods for making it easier to work with these.

API

`ComplexSet(idPattern) => complexSet`

Instantiates a strategy, complexSet.

idPattern String (optional)
- a pattern which is converted into a regexp validating the id field
- e.g. '^@\w+ would make only ids like @mixmix valid


complexSet.isValid(T) => Boolean
complexSet.schema
Access the JSON shcema that isValid was built with.
complexSet.concat(A, B) => C
complexSet.identity() => I
returns "identity transformation"
complexSet.mapFromInput(input, currentTips) => T
Takes a current transformation state, currentTips, an array of Ts that are the
tips of the graph, along with a human friendly (descriptive) input
and returns a transformation T which satisfies the
change requested in `input.
Format of input:
{
  add: [{ id: Id, seq: Integer }, ... ]
  remove: [{ id: Id, seq: Integer }, ... ]
}
where:

id is a unique identifier for something being added.
Id must pass the idPattern validator


seq is a "sequence", some whole number which represents a position in time
this could be a vector clock, or
a wall clock (UTC time)



You can provide EITHER add / remove OR both.
complexSet.mapToOutput(T) => t
Takes a transformation T and returns an output state t, which is more
"human readable"
Format of output t:
{
  Id: [Interval],
}
A series of Intervals is computed for each Id from all the add and remove
events, and these are ordered lowest to highest in terms of sequence.
Intervals will be of form:

{ start: Integer, end: Integer } - a "closed" interval
{ start: Integer, end: null }
an "open" interval
this will only ever occur as the last interval in a series




An Example transformation
When users were added / removed as permitted authors for an ssb-record.
// an example of a transformation
T = {
  // an example set where each @user was permitted at different intervals
  '@cherese': {
    200: 1, // seq=200, state=1=add
    1000: -1 // seq=1000, state=-1=remove
  },
  '@ben': {
    1000: 1, // seq=1000, state=1=add
    1100: 2, // seq=1100, state=2=add
    2000: -1 // seq=2000, state=-1=remove
  },
  '@mix': {
    300: -1 // seq=300, state=-1=remove
  }
}

// the reified state of that transformation
mapToOutput(T) = {
  '@cherese': [{ start: 200, end: 1000 }],
  '@ben': [{ start: 1000, end: 2000 }], // note how 1100 wasnt added
  // note @mix is not here
  // ids with no "add" states are ignored
}
simpleSet.isConflict() => False
simpleSet.isValidMerge() => True
simpleSet.merge(graph, mergeNode, field) => T
where:

graph is a @tangle/graph instance
mergeNode is the proposed merge-node
field String contains the the data fields node.data[field]

 would make only ids like __INLINE_CODE_10__ valid
default: __INLINE_CODE_11__



__INLINE_CODE_12__
__INLINE_CODE_13__
Access the JSON shcema that __INLINE_CODE_14__ was built with.
__INLINE_CODE_15__
__INLINE_CODE_16__
returns "identity transformation"
__INLINE_CODE_17__
Takes a current transformation state, __INLINE_CODE_18__, an array of Ts that are the
tips of the graph, along with a human friendly (descriptive) __INLINE_CODE_19__
and returns a transformation __INLINE_CODE_20__ which satisfies the
change requested in `input.
Format of input:
{
  add: [{ id: Id, seq: Integer }, ... ]
  remove: [{ id: Id, seq: Integer }, ... ]
}
where:

__INLINE_CODE_21__ is a unique identifier for something being added.
__INLINE_CODE_22__ must pass the __INLINE_CODE_23__ validator


__INLINE_CODE_24__ is a "sequence", some whole number which represents a position in time
this could be a vector clock, or
a wall clock (UTC time)



You can provide EITHER add / remove OR both.
__INLINE_CODE_25__
Takes a transformation __INLINE_CODE_26__ and returns an output state __INLINE_CODE_27__, which is more
"human readable"
Format of output __INLINE_CODE_28__:
{
  Id: [Interval],
}
A series of __INLINE_CODE_29__s is computed for each __INLINE_CODE_30__ from all the add and remove
events, and these are ordered lowest to highest in terms of sequence.
Intervals will be of form:

__INLINE_CODE_31__ - a "closed" interval
__INLINE_CODE_32__
an "open" interval
this will only ever occur as the last interval in a series




An Example transformation
When users were added / removed as permitted authors for an ssb-record.
// an example of a transformation
T = {
  // an example set where each @user was permitted at different intervals
  '@cherese': {
    200: 1, // seq=200, state=1=add
    1000: -1 // seq=1000, state=-1=remove
  },
  '@ben': {
    1000: 1, // seq=1000, state=1=add
    1100: 2, // seq=1100, state=2=add
    2000: -1 // seq=2000, state=-1=remove
  },
  '@mix': {
    300: -1 // seq=300, state=-1=remove
  }
}

// the reified state of that transformation
mapToOutput(T) = {
  '@cherese': [{ start: 200, end: 1000 }],
  '@ben': [{ start: 1000, end: 2000 }], // note how 1100 wasnt added
  // note @mix is not here
  // ids with no "add" states are ignored
}
__INLINE_CODE_33__
__INLINE_CODE_34__
__INLINE_CODE_35__
where:

__INLINE_CODE_36__ is a __INLINE_CODE_37__ instance
__INLINE_CODE_38__ is the proposed merge-node
__INLINE_CODE_39__ String contains the the data fields __INLINE_CODE_40__

__INLINE_CODE_13__

Access the JSON shcema that __INLINE_CODE_14__ was built with.

Takes a current transformation state, __INLINE_CODE_18__, an array of Ts that are the tips of the graph, along with a human friendly (descriptive) __INLINE_CODE_19__ and returns a transformation __INLINE_CODE_20__ which satisfies the change requested in `input.

Format of input:

{
  add: [{ id: Id, seq: Integer }, ... ]
  remove: [{ id: Id, seq: Integer }, ... ]
}

where:

__INLINE_CODE_21__ is a unique identifier for something being added.
- __INLINE_CODE_22__ must pass the __INLINE_CODE_23__ validator
__INLINE_CODE_24__ is a "sequence", some whole number which represents a position in time
- this could be a vector clock, or
- a wall clock (UTC time)

You can provide EITHER add / remove OR both.

__INLINE_CODE_25__

Takes a transformation __INLINE_CODE_26__ and returns an output state __INLINE_CODE_27__, which is more "human readable"

Format of output __INLINE_CODE_28__:

{
  Id: [Interval],
}

A series of __INLINE_CODE_29__s is computed for each __INLINE_CODE_30__ from all the add and remove events, and these are ordered lowest to highest in terms of sequence.

Intervals will be of form:

__INLINE_CODE_31__ - a "closed" interval
__INLINE_CODE_32__
- an "open" interval
- this will only ever occur as the last interval in a series

An Example transformation

When users were added / removed as permitted authors for an ssb-record.

// an example of a transformation
T = {
  // an example set where each @user was permitted at different intervals
  '@cherese': {
    200: 1, // seq=200, state=1=add
    1000: -1 // seq=1000, state=-1=remove
  },
  '@ben': {
    1000: 1, // seq=1000, state=1=add
    1100: 2, // seq=1100, state=2=add
    2000: -1 // seq=2000, state=-1=remove
  },
  '@mix': {
    300: -1 // seq=300, state=-1=remove
  }
}

// the reified state of that transformation
mapToOutput(T) = {
  '@cherese': [{ start: 200, end: 1000 }],
  '@ben': [{ start: 1000, end: 2000 }], // note how 1100 wasnt added
  // note @mix is not here
  // ids with no "add" states are ignored
}

__INLINE_CODE_33__

__INLINE_CODE_34__

__INLINE_CODE_35__

where:

__INLINE_CODE_36__ is a __INLINE_CODE_37__ instance
__INLINE_CODE_38__ is the proposed merge-node
__INLINE_CODE_39__ String contains the the data fields __INLINE_CODE_40__

would make only ids like __INLINE_CODE_10__ valid

default: __INLINE_CODE_11__

__INLINE_CODE_12__

__INLINE_CODE_13__

Access the JSON shcema that __INLINE_CODE_14__ was built with.

__INLINE_CODE_15__

__INLINE_CODE_16__

returns "identity transformation"

__INLINE_CODE_17__

Format of input:

{
  add: [{ id: Id, seq: Integer }, ... ]
  remove: [{ id: Id, seq: Integer }, ... ]
}

where:

__INLINE_CODE_21__ is a unique identifier for something being added.
- __INLINE_CODE_22__ must pass the __INLINE_CODE_23__ validator
__INLINE_CODE_24__ is a "sequence", some whole number which represents a position in time
- this could be a vector clock, or
- a wall clock (UTC time)

You can provide EITHER add / remove OR both.

__INLINE_CODE_25__

Takes a transformation __INLINE_CODE_26__ and returns an output state __INLINE_CODE_27__, which is more "human readable"

Format of output __INLINE_CODE_28__:

{
  Id: [Interval],
}

A series of __INLINE_CODE_29__s is computed for each __INLINE_CODE_30__ from all the add and remove events, and these are ordered lowest to highest in terms of sequence.

Intervals will be of form:

__INLINE_CODE_31__ - a "closed" interval
__INLINE_CODE_32__
- an "open" interval
- this will only ever occur as the last interval in a series

An Example transformation

When users were added / removed as permitted authors for an ssb-record.

// an example of a transformation
T = {
  // an example set where each @user was permitted at different intervals
  '@cherese': {
    200: 1, // seq=200, state=1=add
    1000: -1 // seq=1000, state=-1=remove
  },
  '@ben': {
    1000: 1, // seq=1000, state=1=add
    1100: 2, // seq=1100, state=2=add
    2000: -1 // seq=2000, state=-1=remove
  },
  '@mix': {
    300: -1 // seq=300, state=-1=remove
  }
}

// the reified state of that transformation
mapToOutput(T) = {
  '@cherese': [{ start: 200, end: 1000 }],
  '@ben': [{ start: 1000, end: 2000 }], // note how 1100 wasnt added
  // note @mix is not here
  // ids with no "add" states are ignored
}

__INLINE_CODE_36__ is a __INLINE_CODE_37__ instance
__INLINE_CODE_38__ is the proposed merge-node
__INLINE_CODE_39__ String contains the the data fields __INLINE_CODE_40__

Keywords

tangle strategy set