js-pulsarcast/docs/api.md at master · JGAntunes/js-pulsarcast · GitHub

Classes

A Javascript implementation of Pulsarcast

See design and specs at https://github.com/JGAntunes/pulsarcast

A DAG node representing an Event descriptor

A representation of an event tree for a given topic

A DAG node representing a Topic descriptor

Typedefs

SerializedEvent : Object: Serialized event representation
ReadableEvent : Object: Human readable event representation
SerializedTopic : Object: Serialized topic representation
ReadableTopic : Object: Human readable topic representation

External

CID: CID (Content Identifier)
Libp2pNode: Libp2p node
PeerId: Peer identifier object

Pulsarcast

A Javascript implementation of Pulsarcast

See design and specs at https://github.com/JGAntunes/pulsarcast

Kind: global class

Pulsarcast
- new Pulsarcast(libp2p, [options])
- .libp2p : Libp2pNode
- .started : boolean
- .peers : Map.<string, Peer>
- .topics : Map.<string, TopicNode>
- .subscriptions : Set.<string>
- .eventTrees : Map.<string, EventTree>
- .me : Peer
- .start(callback) ⇒ void
- .stop(callback) ⇒ void
- .publish(topicB58Str, message, callback) ⇒ void
- .subscribe(topicB58Str, [options], callback) ⇒ void
- .unsubscribe(topicB58Str, callback)
- .createTopic(topicName, [options], callback) ⇒ void

new Pulsarcast(libp2p, [options])

Create a new PulsarCast node.

Param	Type	Default	Description
libp2p	`Libp2pNode`
[options]	`object`	`{}`	PulsarCast options

pulsarcast.libp2p : `Libp2pNode`

Local ref to the libp2p node.

Kind: instance property of Pulsarcast

pulsarcast.started : `boolean`

Node current status info.

Kind: instance property of Pulsarcast

pulsarcast.peers : `Map.<string, Peer>`

Map of peers.

Kind: instance property of Pulsarcast

pulsarcast.topics : `Map.<string, TopicNode>`

Map of topics.

Kind: instance property of Pulsarcast

pulsarcast.subscriptions : `Set.<string>`

List of our subscriptions

Kind: instance property of Pulsarcast

pulsarcast.eventTrees : `Map.<string, EventTree>`

Map of the event dissemination trees.

Kind: instance property of Pulsarcast

pulsarcast.me : `Peer`

This node peer object.

Kind: instance property of Pulsarcast

pulsarcast.start(callback) ⇒ `void`

Start the PulsarCast node

Kind: instance method of Pulsarcast

Param	Type
callback	`function`

pulsarcast.stop(callback) ⇒ `void`

Stop the PulsarCast node

Kind: instance method of Pulsarcast

Param	Type
callback	`function`

pulsarcast.publish(topicB58Str, message, callback) ⇒ `void`

Publish a message in the specified topic

Kind: instance method of Pulsarcast

Param	Type	Description
topicB58Str	`string`	topic base58 string
message	`Buffer`	message to publish
callback	`function`

pulsarcast.subscribe(topicB58Str, [options], callback) ⇒ `void`

Subscribe to a specific topic

Kind: instance method of Pulsarcast

Param	Type	Default	Description
topicB58Str	`string`		topic base58 string
[options]	`object`	`{}`
[options.subscribeToMeta]	`object`	`true`	optionally subscribe to this topic meta updates (updates to the topic descriptor)
callback	`function`

pulsarcast.unsubscribe(topicB58Str, callback)

Unsubscribe from a specific topic

Kind: instance method of Pulsarcast

Param	Type	Default	Description
topicB58Str	`string`		topic base58 string
[options.unsubscribeFromMeta]	`object`	`true`	optionally unsubscribe from this topic meta updates (updates to the topic descriptor)
callback	`function`

pulsarcast.createTopic(topicName, [options], callback) ⇒ `void`

Create a topic

Kind: instance method of Pulsarcast

Param	Type	Default	Description
topicName	`string`		topic name
[options]	`object`	`{}`	Topic creation options
[options.parent]	`string`	`null`	Parent topic base58 string
[options.subTopics]	`object.<string, string>`	`{}`	Sub topics map, with names as keys and base58 strings as values
[options.metadata]	`object`	`{}`	Metadata options
[options.metadata.allowedPublishers]	`array.<string>`		Allowed publishers (defaults to only this node)
[options.metadata.requestToPublish]	`boolean`	`true`	Allow other nodes to request to publish
[options.metadata.eventLinking]	`string`	`"LAST_SEEN"`	Method used for linking events
callback	`function`

EventNode

A DAG node representing an Event descriptor

Kind: global class

EventNode
- new EventNode(topicCID, author, payload, [options])
- instance
  - .topicCID : CID
  - .author : PeerId
  - .payload : Buffer
  - .publisher : PeerId
  - .parent : CID
  - .metadata : object
  - .isPublished : boolean
  - .getReadableFormat() ⇒ ReadableEvent
  - .getCID(callback) ⇒ void
  - .serialize() ⇒ SerializedEvent
  - .serializeCBOR(callback) ⇒ void
- static
  - .deserialize(event) ⇒ EventNode
  - .deserializeCBOR(event, callback) ⇒ void

new EventNode(topicCID, author, payload, [options])

Create a new EventNode.

Param	Type	Default	Description
topicCID	`string` \| `CID`		Topic CID or base58 string for this event
author	`PeerId`
payload	`Buffer`		Message to publish
[options]	`object`	`{}`
[options.parent]	`string`		Parent event base58 string
[options.publisher]	`string`		Base58 string id of the publisher node
[options.metadata]	`object`	`{}`	Metadata options

eventNode.topicCID : `CID`

Topic CID

Kind: instance property of EventNode

eventNode.author : `PeerId`

Author PeerId

Kind: instance property of EventNode

eventNode.payload : `Buffer`

The payload of the event

Kind: instance property of EventNode

eventNode.publisher : `PeerId`

Publisher PeerId

Kind: instance property of EventNode

eventNode.parent : `CID`

Parent event

Kind: instance property of EventNode

eventNode.metadata : `object`

Event metadata

Kind: instance property of EventNode
Properties

Name	Type
created	`Date`
protocolVersion	`string`

eventNode.isPublished : `boolean`

Is the event published

Kind: instance property of EventNode

eventNode.getReadableFormat() ⇒ `ReadableEvent`

Return an object representing en event in readable format with string representations of the buffers

Kind: instance method of EventNode

eventNode.getCID(callback) ⇒ `void`

Get the event CID

Kind: instance method of EventNode

Param	Type
callback	`function`

eventNode.serialize() ⇒ `SerializedEvent`

Serialize this event

Kind: instance method of EventNode

eventNode.serializeCBOR(callback) ⇒ `void`

Serialize this event to a CBOR buffer representation

Kind: instance method of EventNode

Param	Type
callback	`function`

EventNode.deserialize(event) ⇒ `EventNode`

Deserialize a given event and create an EventNode

Kind: static method of EventNode

Param	Type
event	`SerializedEvent`

EventNode.deserializeCBOR(event, callback) ⇒ `void`

Deserialize a given CBOR buffer representing an event and create an EventNode

Kind: static method of EventNode

Param	Type
event	`SerializedEvent`
callback	`function`

EventTree

A representation of an event tree for a given topic

Kind: global class

EventTree
- new EventTree(topicNode)
- .topicNode : TopicNode
- .eventMap : Map.<string, EventNode>
- .mostRecent : EventNode
- .addNew(eventNode, [options], callback) ⇒ void
- .add(eventNode, callback) ⇒ void
- .get(eventCID) ⇒ EventNode

new EventTree(topicNode)

Create a new EventTree.

Param	Type
topicNode	`TopicNode`

eventTree.topicNode : `TopicNode`

Topic node

Kind: instance property of EventTree

eventTree.eventMap : `Map.<string, EventNode>`

Event map used to keep track of events for a given topic. Indexed by CID base58 string

Kind: instance property of EventTree

eventTree.mostRecent : `EventNode`

The most recent event for this topic

Kind: instance property of EventTree

eventTree.addNew(eventNode, [options], callback) ⇒ `void`

Adds a newly created event to the event tree and links it correctly

Kind: instance method of EventTree

Param	Type	Default	Description
eventNode	`EventNode`
[options]	`object`	`{}`
[options.parent]	`string`	`null`	Parent base58 string to link the event to, if the topic allows custom linking
callback	`function`		Returns the updated event node

eventTree.add(eventNode, callback) ⇒ `void`

Adds an event to the topic tree, updating the most recent event ref

Kind: instance method of EventTree

Param	Type	Description
eventNode	`EventNode`
callback	`function`	Returns the event node

eventTree.get(eventCID) ⇒ `EventNode`

Get an event from this tree

Kind: instance method of EventTree

Param	Type
eventCID	`CID`

TopicNode

A DAG node representing a Topic descriptor

Kind: global class

TopicNode
- new TopicNode(name, author, [options])
- instance
  - .name : string
  - .author : PeerId
  - .subTopics : object.<string, CID>
  - .parent : CID
  - .subTopics : object.<string, CID>
  - .metadata : object
  - .getReadableFormat() ⇒ ReadableTopic
  - .getCID(callback) ⇒ void
  - .serialize() ⇒ SerializedTopic
  - .serializeCBOR(callback) ⇒ void
- static
  - .deserialize(topic) ⇒ TopicNode
  - .deserializeCBOR(topic, callback) ⇒ void

new TopicNode(name, author, [options])

Create a new TopicNode.

Param	Type	Default	Description
name	`string`
author	`PeerId`
[options]	`object`	`{}`
[options.parent]	`string`	`null`	Parent topic base58 string
[options.subTopics]	`object.<string, string>`	`{}`	Sub topics map, with names as keys and base58 strings as values
[options.metadata]	`object`	`{}`	Metadata options
[options.metadata.allowedPublishers]	`array.<string>`		Allowed publishers (defaults to only this node)
[options.metadata.requestToPublish]	`boolean`	`true`	Allow other nodes to request to publish
[options.metadata.eventLinking]	`string`	`"LAST_SEEN"`	Method used for linking events

topicNode.name : `string`

Topic human readable name.

Kind: instance property of TopicNode

topicNode.author : `PeerId`

Author PeerId

Kind: instance property of TopicNode

topicNode.subTopics : `object.<string, CID>`

Sub topics

Kind: instance property of TopicNode

topicNode.parent : `CID`

Parent topic

Kind: instance property of TopicNode

topicNode.subTopics : `object.<string, CID>`

Sub topics

Kind: instance property of TopicNode

topicNode.metadata : `object`

Topic metadata

Kind: instance property of TopicNode
Properties

Name	Type
allowedPublishers	`boolean`
requestToPublish	`boolean`
eventLinking	`string`
created	`Date`
protocolVersion	`string`

topicNode.getReadableFormat() ⇒ `ReadableTopic`

Return an object representing a topic in readable format with string representations of the buffers

Kind: instance method of TopicNode

topicNode.getCID(callback) ⇒ `void`

Get the topic CID

Kind: instance method of TopicNode

Param	Type
callback	`function`

topicNode.serialize() ⇒ `SerializedTopic`

Serialize this topic

Kind: instance method of TopicNode

topicNode.serializeCBOR(callback) ⇒ `void`

Serialize this topic to a CBOR buffer representation

Kind: instance method of TopicNode

Param	Type
callback	`function`

TopicNode.deserialize(topic) ⇒ `TopicNode`

Deserialize a given topic and create a TopicNode

Kind: static method of TopicNode

Param	Type
topic	`SerializedTopic`

TopicNode.deserializeCBOR(topic, callback) ⇒ `void`

Deserialize a given CBOR buffer representing a topic and create a TopicNode

Kind: static method of TopicNode

Param	Type
topic	`SerializedTopic`
callback	`function`

SerializedEvent : `Object`

Serialized event representation

Kind: global typedef
Properties

Name	Type	Description
topic	`Object`	The topic DAG link
author	`Buffer`	The event author
payload	`Buffer`	Event payload
publisher	`Buffer`	The event publisher
parent	`Object`	The event parent DAG link
metadata	`object`	Event metadata object
metadata.version	`string`	Pulsarcast protocol version used for this event
metadata.created	`string`	Date in ISO string format

ReadableEvent : `Object`

Human readable event representation

Kind: global typedef
Properties

Name	Type	Description
topicCID	`string`
author	`string`	The event author base58 id
payloadSize	`number`	Event payload size in bytes
publisher	`string`	The event publisher base58 id
parent	`string`	The event parent base58 id
isPublished	`boolean`
metadata	`object`	Event metadata object
metadata.version	`string`	Pulsarcast protocol version used for this event
metadata.created	`string`	Date in ISO string format

SerializedTopic : `Object`

Serialized topic representation

Kind: global typedef
Properties

Name	Type	Description
name	`string`	The topic name
author	`Buffer`	The topic author
parent	`Object`	The topic parent DAG link
#	`object.<string, {'/': Buffer}>`	The topic sub topics, were the keys are names and the values DAG links
metadata	`object`	Topic metadata object
metadata.created	`string`	Date in ISO string format
metadata.allowedPublishers	`Array.<Buffer>`	Array of peer ids allowed to publish
metadata.requestToPublish	`Array.<Buffer>`	Array of peer ids allowed to request to publish
metadata.version	`string`	Pulsarcast protocol version used for this topic
metadata.eventLinking	`string`	Event linking method used for this topic

ReadableTopic : `Object`

Human readable topic representation

Kind: global typedef
Properties

Name	Type	Description
name	`string`	The topic name
author	`string`	The topic author base58 id
parent	`string`	The topic parent base58 id
#	`object.<string, string>`	The topic sub topics, where the keys are names and the values base58 representations of the topic
metadata	`object`	Topic metadata object
metadata.created	`string`	Date in ISO string format
metadata.allowedPublishers	`Array.<string>`	Array of base58 peer ids allowed to publish
metadata.requestToPublish	`Array.<string>`	Array of base58 peer ids allowed to request to publish
metadata.version	`string`	Pulsarcast protocol version used for this topic
metadata.eventLinking	`string`	Event linking method used for this topic

CID

CID (Content Identifier)

Kind: global external
See: https://github.com/multiformats/js-cid#api

Libp2pNode

Libp2p node

Kind: global external
See: https://github.com/libp2p/js-libp2p#api

PeerId

Peer identifier object

Kind: global external
See: https://github.com/libp2p/js-libp2p#ap://github.com/libp2p/js-peer-id#api