This PR implements the Builder API for creating tar archives, addressing issue #3. The implementation provides a complete solution for programmatically creating tar archives from various sources.

New Builder Class

The Builder API mirrors the functionality of Rust's tar::Builder and provides the following methods:

export class Builder {
  constructor(output?: string)           // Create builder with optional file output
  appendData(name: string, data: Uint8Array): void     // Add raw data
  appendFile(name: string, src: string): void          // Add file from disk  
  appendDirAll(name: string, src: string): void        // Add directory recursively
  finish(): Array<number> | null                       // Finalize archive
}

Usage Examples

Creating archives in memory:

import { Builder } from '@napi-rs/tar'

const builder = new Builder()
builder.appendData('hello.txt', Buffer.from('Hello, world!'))
builder.appendFile('package.json', './package.json')
builder.appendDirAll('src', './src')

const archiveData = builder.finish() // Returns Uint8Array

Creating archives to file:

const builder = new Builder('./output.tar')
builder.appendData('readme.txt', Buffer.from('Archive contents'))
builder.finish() // Returns null, data written to file

Key Features

• Dual output modes: Create archives in memory or write directly to files
• Multiple content sources: Add raw data, files from disk, or entire directories
• Unicode support: Handles international filenames correctly
• Large file support: Tested with multi-megabyte files
• Path handling: Supports subdirectory structures within archives
• Full compatibility: Archives created by Builder can be read by the existing Archive class

Implementation Details

The Rust implementation uses a BuilderOutput enum to handle both file and memory-based outputs:

pub enum BuilderOutput {
  File(File),
  Buffer(Cursor<Vec<u8>>),
}

This allows the same Builder interface to work seamlessly with both output modes while maintaining optimal performance.

Testing

Added comprehensive test coverage with 11 new tests covering:

• Basic archive creation with various content types
• File vs memory output modes
• Large data handling (1MB+ files)
• Unicode filename support
• Directory recursion
• Mixed content scenarios
• Empty archive handling
• End-to-end compatibility with Archive reader

All existing tests continue to pass, ensuring backward compatibility.

Documentation

Updated README with complete Builder API documentation and usage examples. TypeScript definitions are automatically generated from the Rust implementation.

Closes #3

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.