# Getting Started

Welcome to WorkerBee, the powerful TypeScript library that makes building Hive blockchain bots as easy as writing regular web applications!

Install WorkerBee:

View WorkerBee package on npmjs 🡭

https://npmjs.com/package/@hiveio/workerbee

pnpm add @hiveio/workerbee

You can also use other package managers, such as: npm or yarn

Here's a simple example that initializes and starts the bot:

import { WorkerBee } from '@hiveio/workerbee';

const bot = new WorkerBee();

await bot.start();

// place your filtering conditions here

WorkerBee uses the Observer pattern, similar to modern reactive libraries. You define what you want to observe, and WorkerBee handles how to monitor the blockchain.

Build complex queries using method chaining, e.g.:

bot.observe
  .onPosts("alice")
  .onComments("bob")
  .subscribe({ /* your callback */ });

Instead of writing endless while loops and managing timers, just declare what you want to observe:

// ❌ Old way - manual polling
setInterval(async () => {
  const posts = await api.getPosts();
  // Check for new posts...
}, 3000);

// ✅ WorkerBee way - declarative observation
bot.observe.onPosts("author").subscribe({ /* react */ });

WorkerBee handles network errors, API limits, and blockchain reorganizations automatically:

bot.observe
  .onPosts("alice")
  .subscribe({
    next: (data) => { /* handle success */ },
    error: (error) => {
      // WorkerBee provides structured error information
      console.error(`Error type: ${error.type}, message: ${error.message}`);
    }
  });

Switch between live blockchain data and historical analysis without changing your code:

bot.providePastData('-7d')
  .onPosts("alice")
  .onComments("bob")
  .subscribe({ /* your callback */ });

WorkerBee's broadcast method goes beyond regular broadcasting by providing L1 blockchain validation:

// Assuming you have a signed transaction
await bot.broadcast(signedTransaction);

// With options for verification and timeout
await bot.broadcast(signedTransaction, {
  verifySignatures: true,
  expireInMs: 10000
});

Key Difference from Regular Broadcasting:

• Regular broadcast: Only ensures the transaction reaches the node and is valid
• WorkerBee broadcast: Guarantees the transaction was propagated and applied by witnesses in a block by verifying its actual presence in the blockchain

Options explained:

• verifySignatures: Checks if transaction signatures and their order/count remain unchanged after blockchain inclusion (detects tampering, not pre-broadcast validation)
• expireInMs: Maximum time to wait for the transaction to appear in a block (usually ~3 seconds). If timeout occurs, the transaction may still appear later in the blockchain, but an error is thrown

WorkerBee provides powerful async iterators for processing blockchain data in real-time:

// Simple iteration over new blocks (IGNORES ERRORS)
for await (const { number, id } of bot) {
  console.log(`Processing block #${number} with ID: ${id}`);
}

// Also ignores errors (equivalent to above)
for await (const block of bot.iterate()) {
  console.log(`Block: ${block.number}`);
}

// With error handling via callback
for await (const block of bot.iterate(console.error)) {
  console.log(`Block: ${block.number}`);
}

// With try-catch error handling
try {
  for await (const block of bot.iterate(true)) {
    console.log(`Block: ${block.number}`);
  }
} catch (error) {
  console.error("Iterator error:", error);
}

Error Handling Behavior:

• for await (const block of bot) - Ignores all errors (uses default async iterator)
• bot.iterate() (no arguments) - Ignores all errors
• bot.iterate(callback) - Errors are passed to the callback function
• bot.iterate(true) - Errors are thrown and can be caught with try-catch

Key Features:

• Real-time processing: Automatically waits for new blocks as they arrive
• Memory efficient: Uses promise queues to handle backpressure when processing is slower than block production
• Automatic cleanup: Properly unsubscribes from observers when iteration is interrupted
• Flexible error handling: Support for callbacks, boolean flags, or try-catch patterns