plcbundle-bun#

⚡ plcbundle library built exclusively for Bun.

Leverages Bun's native features:

• 🗜️ Native Bun.zstdDecompressSync() - zero-copy decompression
• 🔐 Native Bun.CryptoHasher - SHA-256 verification
• 🚀 Native Bun.file() - optimized file I/O
• 🧵 Native Worker threads - parallel processing
• 📦 Native Bun.resolveSync() - module resolution

Note: This is a Bun-native library. It does not work with Node.js.

Requirements#

• Bun >= 1.2.17

# Install Bun if you haven't already
curl -fsSL https://bun.sh/install | bash

Installation#

bun install

CLI Usage#

# Clone bundles from remote repository
bun src/cli.ts clone --remote https://plcbundle.atscan.net

# Clone specific range with multiple threads
bun src/cli.ts clone --remote https://plcbundle.atscan.net --bundles 1-100 --threads 8

# Show repository info
bun src/cli.ts info --dir ./bundles

# Detect/filter operations with custom function
bun src/cli.ts detect --detect ./examples/detect.ts --dir ./bundles

# Detect with range and threads
bun src/cli.ts detect --detect ./detect.ts --bundles 1-50 --threads 4

# Verify bundle integrity
bun src/cli.ts verify --bundle 42 --dir ./bundles

# Export operations from bundle
bun src/cli.ts export --bundle 1 --dir ./bundles > ops.jsonl

Library Usage#

import { PLCBundle } from './src';

// Initialize
const bundle = new PLCBundle('./bundles');

// Clone from remote (parallel downloads with Bun fetch)
await bundle.clone('https://plcbundle.atscan.net', {
  threads: 8,
  bundles: '1-100',
  verify: true,
  onProgress: (stats) => {
    console.log(`Downloaded ${stats.downloadedBundles}/${stats.totalBundles}`);
  }
});

// Get repository stats
const stats = await bundle.getStats();
console.log(`Last bundle: ${stats.lastBundle}`);

// Stream operations from a bundle (Bun native zstd)
for await (const op of bundle.streamOperations(1)) {
  console.log(op.did);
}

// Process bundles with callback
await bundle.processBundles(1, 10, (op, position, bundleNum) => {
  // Your processing logic here
  if (op.did.startsWith('did:plc:test')) {
    console.log(`Found: ${op.did}`);
  }
}, {
  threads: 4, // Uses Bun Workers
  onProgress: (stats) => {
    console.log(`Processed ${stats.totalOps} operations`);
  }
});

// Verify bundle (Bun native SHA-256)
const result = await bundle.verifyBundle(1);
console.log(result.valid ? 'Valid' : 'Invalid');

Detect Function Example#

Create a detect.ts file:

export function detect({ op }: { op: any }) {
  const labels = [];
  
  if (op.did.startsWith('did:plc:test')) {
    labels.push('test-account');
  }
  
  // Add your detection logic
  
  return labels;
}

Then use it:

bun src/cli.ts detect --detect ./detect.ts

Why Bun?#

This library uses Bun's native APIs for:

• Native zstd decompression - Built-in zstdDecompressSync()
• Optimized file I/O - Bun.file() with zero-copy operations
• Fast crypto - Native CryptoHasher for SHA-256
• Instant startup - No build step required
• Efficient parallelism - Lightweight Workers

Features#

• ⚡ Bun-native - leverages all native APIs
• 🔄 Multi-threaded - parallel downloads and processing
• 💾 Auto-save progress - every 5 seconds, no data loss
• ⏸️ Graceful shutdown - Ctrl+C saves state
• 🔁 Smart resume - picks up exactly where you left off
• ✅ Hash verification - SHA-256 integrity checks
• 📊 Real-time progress - live stats and reporting
• 🎯 Minimalist design - clean, maintainable code

Directory Structure#

src/
├── cmds/          # CLI commands
├── cli.ts         # CLI entry point
├── plcbundle.ts   # Core library (Bun-native)
├── types.ts       # TypeScript types
├── worker.ts      # Bun Worker for multi-threading
└── index.ts       # Library exports

examples/
└── detect.ts      # Example detect function

License#

MIT