tessl/npm-orbitdb--core

Distributed p2p database on IPFS with automatic peer synchronization and conflict-free writes

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Address Management

Name: tessl/npm-orbitdb--core
Author: tessl

OrbitDB uses unique addresses to identify and locate distributed databases across the network. These addresses enable database sharing and replication between peers.

Capabilities

Address Validation

Validates whether a string is a valid OrbitDB database address.

/**
 * Validates an OrbitDB database address
 * @param address An OrbitDB database address string or OrbitDBAddress object
 * @returns True if the address is valid, false otherwise
 */
function isValidAddress(address: string | OrbitDBAddress): boolean;

Usage Examples:

import { isValidAddress } from '@orbitdb/core';

// Valid OrbitDB addresses
const validAddress1 = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To';
const validAddress2 = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/my-database';

console.log(isValidAddress(validAddress1)); // true
console.log(isValidAddress(validAddress2)); // true

// Invalid addresses
console.log(isValidAddress('not-an-address')); // false
console.log(isValidAddress('/ipfs/QmHash')); // false
console.log(isValidAddress('')); // false

Address Parsing

Parses OrbitDB address strings into structured OrbitDBAddress objects.

/**
 * Parses an OrbitDB address string into an OrbitDBAddress object
 * @param address OrbitDB address string to parse
 * @returns Parsed OrbitDBAddress object
 * @throws Error if address is invalid
 */
function parseAddress(address: string): OrbitDBAddress;

Usage Examples:

import { parseAddress } from '@orbitdb/core';

// Parse a basic address
const address1 = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To';
const parsed1 = parseAddress(address1);
console.log(parsed1.root); // 'zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To'
console.log(parsed1.path); // ''

// Parse an address with path
const address2 = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/my-database';
const parsed2 = parseAddress(address2);
console.log(parsed2.root); // 'zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To'
console.log(parsed2.path); // 'my-database'

OrbitDBAddress Interface

The OrbitDBAddress class provides methods for working with parsed addresses.

interface OrbitDBAddress {
  /** The root hash of the database manifest */
  root: string;
  /** The path component of the address (database name) */
  path: string;
  
  /** Converts the address back to its string representation */
  toString(): string;
}

Usage Examples:

import { parseAddress } from '@orbitdb/core';

const address = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/users';
const parsed = parseAddress(address);

// Access components
console.log('Root:', parsed.root);
console.log('Path:', parsed.path);

// Convert back to string
console.log('Full address:', parsed.toString());

// Use in database operations
const orbitdb = await createOrbitDB({ ipfs });
const db = await orbitdb.open(parsed.toString());

Database Address Creation

When you create a database, OrbitDB automatically generates an address for it.

import { createHelia } from 'helia';
import { createOrbitDB } from '@orbitdb/core';

const ipfs = await createHelia();
const orbitdb = await createOrbitDB({ ipfs });

// Create a new database
const db = await orbitdb.open('my-database');

// Get the generated address
const address = db.address;
console.log('Database address:', address.toString());
console.log('Root hash:', address.root);
console.log('Database name:', address.path);

// Share this address with other peers
const addressString = address.toString();
// Other peers can open the same database using this address

Cross-Platform Address Handling

OrbitDB addresses work consistently across platforms and handle different path separators.

import { isValidAddress, parseAddress } from '@orbitdb/core';

// Unix-style paths
const unixAddress = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/path/to/db';
console.log(isValidAddress(unixAddress)); // true

// Windows-style paths (also supported)
const windowsAddress = '\\orbitdb\\zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To\\path\\to\\db';
console.log(isValidAddress(windowsAddress)); // true

// Both parse to the same result
const parsed1 = parseAddress(unixAddress);
const parsed2 = parseAddress(windowsAddress);
console.log(parsed1.toString() === parsed2.toString()); // true

Address-Based Database Operations

You can perform various operations using database addresses directly.

import { createOrbitDB, isValidAddress } from '@orbitdb/core';

const ipfs = await createHelia();
const orbitdb = await createOrbitDB({ ipfs });

// Function to safely open a database by address
async function openDatabaseByAddress(addressString) {
  if (!isValidAddress(addressString)) {
    throw new Error('Invalid OrbitDB address');
  }
  
  try {
    const db = await orbitdb.open(addressString);
    console.log(`Opened database: ${db.name}`);
    return db;
  } catch (error) {
    console.error('Failed to open database:', error.message);
    throw error;
  }
}

// Example usage
const address = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/shared-data';
const db = await openDatabaseByAddress(address);

Address Comparison and Equality

Compare addresses to check if they refer to the same database.

import { parseAddress } from '@orbitdb/core';

const address1 = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/db1';
const address2 = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/db1';
const address3 = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/db2';

const parsed1 = parseAddress(address1);
const parsed2 = parseAddress(address2);
const parsed3 = parseAddress(address3);

// Compare addresses
console.log(parsed1.toString() === parsed2.toString()); // true (same database)
console.log(parsed1.toString() === parsed3.toString()); // false (different databases)

// Compare components
console.log(parsed1.root === parsed3.root); // true (same manifest)
console.log(parsed1.path === parsed3.path); // false (different names)

Working with Database Manifests

The root hash in an OrbitDB address points to the database manifest, which contains metadata about the database.

import { createOrbitDB } from '@orbitdb/core';

const ipfs = await createHelia();
const orbitdb = await createOrbitDB({ ipfs });

// Create database with metadata
const db = await orbitdb.open('my-app-data', {
  meta: {
    description: 'Application data store',
    version: '1.0.0',
    created: new Date().toISOString()
  }
});

console.log('Database address:', db.address.toString());
console.log('Database metadata:', db.meta);

// The root hash identifies this specific database configuration
console.log('Manifest hash:', db.address.root);

Error Handling

Handle common address-related errors:

import { isValidAddress, parseAddress } from '@orbitdb/core';

function safeParseAddress(addressString) {
  try {
    if (!isValidAddress(addressString)) {
      throw new Error(`Invalid OrbitDB address format: ${addressString}`);
    }
    return parseAddress(addressString);
  } catch (error) {
    console.error('Address parsing failed:', error.message);
    return null;
  }
}

// Example usage
const validAddress = '/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To/test';
const invalidAddress = 'not-an-address';

const parsed1 = safeParseAddress(validAddress); // Returns OrbitDBAddress
const parsed2 = safeParseAddress(invalidAddress); // Returns null

Install with Tessl CLI