# plcbundle-bun

⚡ **Zero-dependency** [plcbundle](https://tangled.org/@atscan.net/plcbundle/blob/main/docs/specification.md) library written in **TypeScript** for **[Bun](https://bun.sh)**.

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](https://bun.sh) >= 1.2.17

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

## Installation

### Global Installation (CLI)

```bash
bun i -g @atscan/plcbundle-bun
```

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

```bash
plcbundle-bun --help
```

### Library Installation

```bash
bun add @atscan/plcbundle-bun
```

### Development

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

## CLI Usage

```bash
# 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:

```bash
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

```typescript
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:

```typescript
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:

```bash
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