From 1535777e26ed406c126d989dde20f6863854698b Mon Sep 17 00:00:00 2001 From: Vivek Singh <47470314+heyitsvi@users.noreply.github.com> Date: Mon, 15 Apr 2024 13:49:58 +0530 Subject: [PATCH] Add comments to code blocks (#89) * add mising comments * add Hyperbee to blocks in README * fix cap typo --------- Co-authored-by: Vivek Singh Co-authored-by: Vivek Singh --- README.md | 3 ++- guide/making-a-pear-desktop-app.md | 10 ++++----- guide/making-a-pear-terminal-app.md | 33 +++++++++++++++++++++-------- 3 files changed, 31 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index d467f53..a023e62 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,8 @@ The essential building blocks for building powerful P2P applications using Pear. | Name | Description | Stability | |------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------| -| [Hypercore](./building-blocks/hypercore.md) | A distributed, secure append-only log for creating fast and scalable applications without a backend, as it is entirely P2P. | **stable** | +| [Hypercore](./building-blocks/hypercore.md) | A distributed, secure append-only log for creating fast and scalable applications without a backend, as it is entirely P2P. | **stable** | +| [Hyperbee](./building-blocks/hyperbee.md)| An append-only B-tree running on a Hypercore. Allows sorted iteration and more.| **stable** | | [Hyperdrive](./building-blocks/hyperdrive.md)| A secure, real-time distributed file system that simplifies P2P file sharing and provides an efficient way to store and access data.| **stable** | | [Autobase](./building-blocks/autobase.md) | A "virtual Hypercore" layer over many Hypercores owned by many different peers. | **experimental** | | [Hyperdht](./building-blocks/hyperdht.md) | The Distributed Hash Table (DHT) powering Hyperswarm. | **stable** | diff --git a/guide/making-a-pear-desktop-app.md b/guide/making-a-pear-desktop-app.md index 55f5a0f..4ed7c33 100644 --- a/guide/making-a-pear-desktop-app.md +++ b/guide/making-a-pear-desktop-app.md @@ -187,14 +187,14 @@ Replace `app.js` with ``` js /* global Pear */ -import Hyperswarm from 'hyperswarm' -import crypto from 'hypercore-crypto' -import b4a from 'b4a' -const { teardown } = Pear +import Hyperswarm from 'hyperswarm' // Module for P2P networking and connecting peers +import crypto from 'hypercore-crypto' // Cryptographic functions for generating the key in app +import b4a from 'b4a' // Module for buffer-to-string and vice-versa conversions +const { teardown } = Pear // Cleanup function const swarm = new Hyperswarm() -// Unnannounce the public key before exiting the process +// Unannounce the public key before exiting the process // (This is not a requirement, but it helps avoid DHT pollution) teardown(() => swarm.destroy()) diff --git a/guide/making-a-pear-terminal-app.md b/guide/making-a-pear-terminal-app.md index 91a3cc6..ec661e8 100644 --- a/guide/making-a-pear-terminal-app.md +++ b/guide/making-a-pear-terminal-app.md @@ -22,27 +22,37 @@ npm i bare-readline bare-tty hyperswarm b4a hypercore-crypto Replace `index.js` with ``` js -import Hyperswarm from 'hyperswarm' -import b4a from 'b4a' -import crypto from 'hypercore-crypto' -import readline from 'bare-readline' -import tty from 'bare-tty' +/* global Pear */ +import Hyperswarm from 'hyperswarm' // Module for P2P networking and connecting peers +import b4a from 'b4a' // Module for buffer-to-string and vice-versa conversions +import crypto from 'hypercore-crypto' // Cryptographic functions for generating the key in app +import readline from 'bare-readline' // Module for reading user input in terminal +import tty from 'bare-tty' // Module to control terminal behavior -const { teardown, config } = Pear -const key = config.args.pop() -const shouldCreateSwarm = !key + +const { teardown, config } = Pear // Import configuration options and cleanup functions from Pear +const key = config.args.pop() // Retrieve a potential chat room key from command-line arguments +const shouldCreateSwarm = !key // Flag to determine if a new chat room should be created const swarm = new Hyperswarm() + +// Unannounce the public key before exiting the process +// (This is not a requirement, but it helps avoid DHT pollution) +teardown(() => swarm.destroy()) + const rl = readline.createInterface({ input: new tty.ReadStream(0), output: new tty.WriteStream(1) }) +// When there's a new connection, listen for new messages, and output them to the terminal swarm.on('connection', peer => { const name = b4a.toString(peer.remotePublicKey, 'hex').substr(0, 6) console.log(`[info] New peer joined, ${name}`) peer.on('data', message => appendMessage({ name, message })) peer.on('error', e => console.log(`Connection error: ${e}`)) }) + +// When there's updates to the swarm, update the peers count swarm.on('update', () => { console.log(`[info] Number of connections is now ${swarm.connections.size}`) }) @@ -53,7 +63,7 @@ if (shouldCreateSwarm) { await joinChatRoom(key) } -rl.input.setMode(tty.constants.MODE_RAW) +rl.input.setMode(tty.constants.MODE_RAW) // Enable raw input mode for efficient key reading rl.on('data', line => { sendMessage(line) rl.prompt() @@ -61,7 +71,9 @@ rl.on('data', line => { rl.prompt() async function createChatRoom () { + // Generate a new random topic (32 byte string) const topicBuffer = crypto.randomBytes(32) + // Create a new chat room for the topic await joinSwarm(topicBuffer) const topic = b4a.toString(topicBuffer, 'hex') console.log(`[info] Created new chat room: ${topic}`) @@ -74,16 +86,19 @@ async function joinChatRoom (topicStr) { } async function joinSwarm (topicBuffer) { + // Join the swarm with the topic. Setting both client/server to true means that this app can act as both. const discovery = swarm.join(topicBuffer, { client: true, server: true }) await discovery.flushed() } function sendMessage (message) { + // Send the message to all peers (that you are connected to) const peers = [...swarm.connections] for (const peer of peers) peer.write(message) } function appendMessage ({ name, message }) { + // Output chat msgs to terminal console.log(`[${name}] ${message}`) } ```