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

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

OrbitDB

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

OrbitDB is a serverless, distributed, peer-to-peer database that uses IPFS as its data storage and Libp2p Pubsub to automatically sync databases with peers. It's an eventually consistent database that uses Merkle-CRDTs for conflict-free database writes and merges, making it excellent for decentralized applications, blockchain applications, and local-first web applications.

Package Information

Package Name: @orbitdb/core
Package Type: npm
Language: JavaScript/TypeScript (ES Modules)
Installation: npm install @orbitdb/core helia

Core Imports

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

For specific components:

import { 
  createOrbitDB,
  Documents,
  Events, 
  KeyValue,
  KeyValueIndexed,
  useDatabaseType,
  isValidAddress,
  parseAddress,
  Log,
  Entry,
  DefaultAccessController,
  Database,
  KeyStore,
  useAccessController,
  IPFSAccessController,
  OrbitDBAccessController,
  Identities,
  isIdentity,
  useIdentityProvider,
  PublicKeyIdentityProvider,
  IPFSBlockStorage,
  LevelStorage,
  LRUStorage,
  MemoryStorage,
  ComposedStorage
} from "@orbitdb/core";

Basic Usage

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

// Create OrbitDB instance
const ipfs = await createHelia();
const orbitdb = await createOrbitDB({ ipfs });

// Create/open a database (defaults to Events type)
const db = await orbitdb.open("my-database");

// Add data
const hash = await db.add("Hello OrbitDB!");

// Listen for updates
db.events.on("update", async (entry) => {
  const all = await db.all();
  console.log(all);
});

// Close when done
await db.close();
await orbitdb.stop();

Architecture

OrbitDB is built around several key components:

Core Factory: createOrbitDB function that creates OrbitDB instances with IPFS integration
Database Types: Pre-built database implementations (Events, Documents, KeyValue, KeyValueIndexed)
OpLog: Immutable, cryptographically verifiable operation log implementing Merkle-CRDTs
Access Controllers: Pluggable access control system for database permissions
Identity System: Cryptographic identity management for database operations
Storage Backends: Flexible storage system supporting multiple backends (IPFS, Level, Memory, etc.)

Capabilities

OrbitDB Factory

Creates and manages OrbitDB instances with IPFS integration and peer synchronization.

function createOrbitDB(params: {
  ipfs: IPFS;
  id?: string;
  identity?: Identity | { provider: IdentityProvider };
  identities?: Identities;
  directory?: string;
}): Promise<OrbitDB>;

interface OrbitDB {
  open(name: string, options?: DatabaseOptions): Promise<Database>;
  stop(): Promise<void>;
  ipfs: IPFS;
  directory: string;
  keystore: KeyStore;
  identities: Identities;
  identity: Identity;
  peerId: PeerId;
}

OrbitDB Factory

Database Types

Built-in database implementations for different data models and use cases.

interface Events {
  add(value: any): Promise<string>;
  get(hash: string): any;
  iterator(): AsyncIterable<any>;
  all(): Promise<any[]>;
}

interface Documents {
  put(doc: object): Promise<string>;
  del(key: string): Promise<string>;
  get(key: string): object | null;
  query(findFn: (doc: object) => boolean): object[];
  iterator(): AsyncIterable<object>;
  all(): Promise<object[]>;
}

interface KeyValue {
  put(key: string, value: any): Promise<string>;
  del(key: string): Promise<string>;
  get(key: string): any;
  iterator(): AsyncIterable<{ key: string; value: any }>;
  all(): Promise<object>;
}

Database Types

Address Management

Utilities for working with OrbitDB database addresses.

function isValidAddress(address: string | OrbitDBAddress): boolean;
function parseAddress(address: string): OrbitDBAddress;

interface OrbitDBAddress {
  toString(): string;
  root: string;
  path: string;
}

Address Management

OpLog System

Immutable, cryptographically verifiable operation log implementing Merkle-CRDTs.

interface Log {
  append(entry: Entry): Promise<string>;
  join(log: Log): Promise<Log>;
  heads: Entry[];
  entries: Entry[];
  length: number;
}

interface Entry {
  hash: string;
  payload: {
    op: string;
    key: string | null;
    value: any;
  };
  identity: string;
  sig: string;
  clock: Clock;
}

OpLog System

Access Controllers

Pluggable access control system for managing database permissions.

function useAccessController(accessController: AccessController): void;

interface IPFSAccessController {
  type: 'ipfs';
  canAppend(entry: Entry, identityProvider: IdentityProvider): Promise<boolean>;
  grant(capability: string, identity: string): Promise<void>;
}

interface OrbitDBAccessController {
  type: 'orbitdb';
  canAppend(entry: Entry, identityProvider: IdentityProvider): Promise<boolean>;
}

Access Controllers

Identity System

Cryptographic identity management for database operations and peer authentication.

interface Identities {
  createIdentity(options?: IdentityOptions): Promise<Identity>;
  verifyIdentity(identity: Identity): Promise<boolean>;
  keystore: KeyStore;
}

interface Identity {
  id: string;
  publicKey: string;
  signatures: object;
  type: string;
  provider: IdentityProvider;
}

function isIdentity(identity: any): identity is Identity;
function useIdentityProvider(provider: IdentityProvider): void;

Identity System

Storage Backends

Flexible storage system supporting multiple backends for different use cases.

interface IPFSBlockStorage {
  put(hash: string, data: Uint8Array): Promise<void>;
  get(hash: string): Promise<Uint8Array>;
  del(hash: string): Promise<void>;
}

interface LevelStorage {
  put(key: string, value: any): Promise<void>;
  get(key: string): Promise<any>;
  del(key: string): Promise<void>;
}

interface MemoryStorage {
  put(key: string, value: any): Promise<void>;
  get(key: string): Promise<any>;
  del(key: string): Promise<void>;
}

Storage Backends

Common Types

interface DatabaseOptions {
  type?: string;
  Database?: DatabaseConstructor;
  AccessController?: AccessControllerConstructor;
  directory?: string;
  meta?: object;
  headsStorage?: Storage;
  entryStorage?: Storage;
  indexStorage?: Storage;
  referencesCount?: number;
  syncAutomatically?: boolean;
  onUpdate?: (entry: Entry) => void;
  encryption?: {
    encryptFn: (data: any) => any;
    decryptFn: (data: any) => any;
  };
}

interface Database {
  address: OrbitDBAddress;
  name: string;
  identity: Identity;
  meta: object;
  log: Log;
  sync: Sync;
  peers: Set<string>;
  events: EventEmitter;
  access: AccessController;
  close(): Promise<void>;
  drop(): Promise<void>;
  addOperation(op: Operation): Promise<string>;
}

interface Clock {
  id: string;
  time: number;
}

interface PeerId {
  toString(): string;
}

interface Sync {
  add(heads: Entry[]): Promise<void>;
  start(): Promise<void>;
  stop(): Promise<void>;
  peers: Set<string>;
}

interface Operation {
  op: string;
  key: string | null;
  value: any;
}

interface AccessController {
  type: string;
  address: string;
  write: string[];
  canAppend(entry: Entry, identityProvider: IdentityProvider): Promise<boolean>;
}

Workspace: tessl
Visibility: Public
Created: 7 months ago
Last updated: 3 months ago
Describes: pkg:npm/@orbitdb/core@3.0.x
Publish Source: CLI
Badge