PearDrive (alpha)

A peer-to-peer file sharing and messaging module made easy

✨ Features

• 🔁 p2p messaging across secret networks
• 🔁 p2p file sharing
• 🪵 Extensive logging system with the option to log to a given file
• ⚙️ Node.js and bare runtime compatible for React Native, Pear runtime and standard Node.js environments
• ⚙️ TypeScript compatible

📦 Installation

This is just a simple (to use) npm module. So install it into your project using npm.

npm install peardrive-core-alpha

📖 Example

Separated into different code blocks for readability, but treat these code blocks as one single file that demonstrates basic use cases. Don't be afraid of the docs! There is way more powerful stuff in there!

Creating a peardrive network:

import PearDrive from "peardrive-core-alpha";

// These are only some of the peardrive config options. Check the docs for more

// The folder to use to store/send files on your peer in your peardrive network
const localDrivePath = "/localdrive/path";
// The path to store corestore data (needed to handle networking stuff)
const corestorePath = "/corestore/path";
// OPTIONAL: Have PearDrive's logging system log to the console
const logToConsole = true;
// OPTIONAL: Have PearDrive's logging system log to a given file path
const logToFile = true;
// OPTIONAL: File path to record logs
const logFilePath = "/log/file.txt";

const drive1 = new PearDrive({
  localDrivePath,
  corestorePath,
  logToConsole,
  logToFile,
  logFilePath,
});

await drive1.ready(); // Call this function right after initialization
await drive1.joinNetwork();

// This is the network key any peer needs in order to connect to your network
const p1NetworkKey = drive1.getSaveData().networkKey;

Joining an existing PearDrive network

// You need to retrieve the networkKey created by the first peer in order to
// connect to the same network. Keep this networkKey secret, anyone who has this
// key can join your network.

const localDrivePath2 = "/other/localdrive/path";
const corestorePath2 = "/other/corestore/path";

const drive2 = new PearDrive({
  localDrivePath: localDrivePath2,
  corestorePath: corestorePath2,
});

await drive2.ready();
await drive2.joinNetwork(p1NetworkKey);

Relays

PearDrive relays will automatically download all unique files found on the network as they appear. This is helpful if you want to create a backup NAS for your data.

const localDrivePath3 = "/relay/localdrive/path";
const corestorePath3 = "/relay/corestore/path";

const driveRelay = new PearDrive({
  localDrivePath: localDrivePath3,
  corecorePath: corestorePath3,
  relayMode: true, // The default is false
});

await driveRelay.ready();
await driveRelay.joinNetwork(p1NetworkKey);

// driveRelay will immediately begin downloading all files it sees on the
// network.

See PearDrive file system

// View files stored locally on a peer
const drive1LocalFiles = drive1.listLocalFiles();

// Get drive2's peer key from drive1
const drive2Key = drive1.listPeers()[0]; // Assuming drive2 is in 0 index

// List files stored on drive2, from drive1
const drive2Files = await drive1.listPeerFiles(drive2Key);

// List all files held by all other connected peers
const drive1AllPeerFiles = await drive1.listNetworkFiles();

Downloading files

// Download a file from any peer on the network
await drive1.downloadFile(drive2Files[0]);

// Download file from drive 2
await drive1.downloadFileFromPeer(drive2Key, drive2Files[0]);

// Download all files from network
await drive1.downloadAllFiles();

Error Handling

Due to the nature of PearDrive, there will always be things that can go wrong in the network, causing peers to disconnect if they aren't configured correctly, or a download to be incomplete, or a non-breaking issue with a peer's setup. You can hook into these errors to create callback functions to notify your app if these errors occur.

import * as C from "peardrive-core-alpha/constants.js";

drive1.on(C.EVENT.ERROR, (errorData) => {
  console.log(errorData);
});

🚧 Changelog

0.0.1

• Initial release

0.0.2

• Bug fixes

0.0.3

• Fix docstring documentation for joinNetwork
• Add "Network Nickname"

0.0.4

• Fix import

0.0.5 - 0.0.6

• Optimize tests / resolve testing issue which reduced performance
• Improve testing structure to give more detailed information on test failure
• Keep log files of all PearDrives run on test suite
• Add logger for file writing and terminal logging
• Add verbose logging information to PearDrive functions
• Fix PearDrive dependency compatibility for bare and node runtimes

0.0.7

• Fix bare / node compat
• If folder path doesn't exist (for localdrive), create it.

0.0.8

• Attempt to allow for automatic configuration of outer localdrive folders
• Fix import library mapping to allow for bare modules when PearDrive is used as a module

0.1.0

• RPC connection stability improvements
• Bug fixes

0.1.1

• RPC connection stability improvements
• Attempt to fix RPC timeout bug resulting in network-wide crash.
• More verbose logging for RPC connection status
• Obfuscate code output for private npm module deployment

0.1.2 / 0.1.3

• Improve logging sysyem to prevent errors that don't get logged
• Add custom error for errors occuring within the scope of PearDrive
• Improve docs
• Resolve linting issues for cleaner code
• Fix undeclared variable references in RPC callback functions
• Add deploy script to ensure proper build for release

0.1.4

• Add reconnect attempt to RPC 'close' hook
• Docstrings and more error handling

0.1.5

• Add typescript types declarations to build

0.2.1

• Add RPC events to constants
• Fix localdrive error causing crashes when using localdrive outside project
• Add custom messaging protocol with an optional payload object
• Fix relay bug
• Improve testing
• Fix RPC_UPDATE system so that no RPC_UPDATE can be triggered without also triggering RPC_UPDATE.UPDATE

0.2.2

• change RPC_UPDATE name to EVENT
• Add more events
• Add more thorough testing
• Ignore _private data and functions in generated docs
• Add error types and information for the error event that can be accessed through callback hooks
• Fix RPC DUPLICATE_CHANNEL bug
• Add graceful teardown for MyDrive and NetworkDrive to improve stability

0.2.4

• Fix inProgress downloads-related bugs
• Fix relay file downloads to prevent double downloads

0.2.5

• Add 'getPublicKey' function
• Update teardown order for closing PearDrive instance
• Fix and test custom messaging system

0.2.51

• Fix bare runtime compatibility
• Add 'getNetworkKey' function for keystring

0.2.53

• Add cache clearing for storage management

0.2.54

• Run test suite from dist build

1.0.0

• Make public (deprecated)

🚧 Coming Soon

• Store hyperdrive key data to restore hyperdrive connections on reconnect
• Fix RPC_UPDATE.PEER event not triggering consistently
• Add dir optional parameter to getNonLocalFiles
• Add payload optional argument to events to handle any data

❤️ Credits

• PearDrive Core developed by Jenna Baudelaire
• Project funded by Guy Swann