plcbundle-bun#

⚡ Zero-dependency plcbundle library written in TypeScript for Bun.

No external dependencies - just pure Bun runtime leveraging 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
📘 Fully typed TypeScript - complete type safety

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#

Global Installation (CLI)#

bun i -g @atscan/plcbundle-bun

After global installation, the plcbundle-bun command is available:

plcbundle-bun --help

Library Installation#

bun add @atscan/plcbundle-bun

Development#

git clone https://tangled.org/@atscan.net/plcbundle-bun
cd plcbundle-bun
bun install

CLI Usage#

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

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

# Show repository info
plcbundle-bun info --dir ./bundles

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

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

# Verify bundle integrity
plcbundle-bun verify --bundle 42 --dir ./bundles

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

Development CLI Usage#

When developing locally, run commands directly:

bun src/cli.ts clone --remote https://plcbundle.atscan.net
bun src/cli.ts info --dir ./bundles
bun src/cli.ts detect --detect ./examples/detect.ts

Library Usage#

import { PLCBundle } from "@atscan/plcbundle-bun";

// 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:

plcbundle-bun detect --detect ./detect.ts

Why Bun?#

This library uses Bun's native APIs for:

Zero dependencies - Only requires Bun runtime, nothing else
Full TypeScript - Complete type safety and IDE autocomplete
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, Bun runs TypeScript directly
Efficient parallelism - Lightweight Workers

Features#

📦 Zero dependencies - pure Bun runtime only
📘 TypeScript - fully typed with complete type safety
⚡ 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

Clone this repository