npm package: @hopets/peardrive-core
Description: > A peer-to-peer file sharing and messaging module made easy
Author: Jenna Baudelaire
Latest version: 1.0.0

# 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.

```bash
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:

```javascript
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

```javascript
// 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.

```javascript
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

```javascript
// 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

```javascript
// 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.

```javascript
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](https://github.com/HopeTS)
- Project funded by [Guy Swann](https://bitcoinaudible.com/)