File I/O Operations

/**
 * Parse a buffer or array into CFB container object
 * @param file - Raw binary data (Buffer, Uint8Array, or number array)
 * @param options - Optional parsing configuration
 * @returns Parsed CFB container with file structure and data
 */
function parse(file: CFB$Blob, options?: CFB$ParsingOptions): CFB$Container;

type CFB$Blob = number[] | Uint8Array;

interface CFB$ParsingOptions extends CFB$CommonOptions {
  /** If true, include raw data in output */
  raw?: boolean;
}

interface CFB$CommonOptions {
  /** Data encoding */
  type?: 'base64' | 'binary' | 'buffer' | 'file' | 'array';
  /** If true, throw errors when features are not understood */
  WTF?: boolean;
}

const CFB = require('cfb');
const fs = require('fs');

// Parse from Buffer
const buffer = fs.readFileSync('document.xls');
const cfb = CFB.parse(buffer);

// Parse with raw data included
const cfbWithRaw = CFB.parse(buffer, { raw: true });
console.log('Has raw data:', !!cfbWithRaw.raw);

// Parse from Uint8Array
const uint8Array = new Uint8Array(buffer);
const cfbFromArray = CFB.parse(uint8Array);

/**
 * Read a blob, file, or binary string into CFB container
 * @param input - Input data (buffer, array, string, or file path)
 * @param options - Optional parsing configuration
 * @returns Parsed CFB container
 */
function read(input: CFB$Blob | string, options?: CFB$ParsingOptions): CFB$Container;

const CFB = require('cfb');

// Read from file (Node.js)
const cfb = CFB.read('document.xls', { type: 'file' });

// Read from buffer
const buffer = require('fs').readFileSync('document.xls');
const cfbFromBuffer = CFB.read(buffer);

// Read from base64 string
const base64Data = buffer.toString('base64');
const cfbFromBase64 = CFB.read(base64Data, { type: 'base64' });

// Read from binary string
const binaryString = buffer.toString('binary');
const cfbFromBinary = CFB.read(binaryString, { type: 'binary' });

/**
 * Generate container file data from CFB object
 * @param cfb - CFB container to serialize
 * @param options - Optional writing configuration
 * @returns Serialized container data (format depends on options.type)
 */
function write(cfb: CFB$Container, options?: CFB$WritingOptions): any;

interface CFB$WritingOptions extends CFB$CommonOptions {
  /** Output file type */
  fileType?: 'cfb' | 'zip' | 'mad';
  /** Override default root entry name (CFB only) */
  root?: string;
  /** Enable compression (ZIP only) */
  compression?: boolean;
}

const CFB = require('cfb');

// Create or modify a CFB container
const cfb = CFB.utils.cfb_new();
CFB.utils.cfb_add(cfb, 'MyData', Buffer.from('Hello World'));

// Write to buffer (default)
const buffer = CFB.write(cfb);

// Write to base64 string
const base64 = CFB.write(cfb, { type: 'base64' });

// Write to binary string
const binary = CFB.write(cfb, { type: 'binary' });

// Write as ZIP format
const zipData = CFB.write(cfb, { fileType: 'zip', compression: true });

/**
 * Write container file directly to filesystem
 * @param cfb - CFB container to write
 * @param filename - Target file path
 * @param options - Optional writing configuration
 */
function writeFile(cfb: CFB$Container, filename: string, options?: CFB$WritingOptions): void;

const CFB = require('cfb');

// Create a new CFB container
const cfb = CFB.utils.cfb_new();
CFB.utils.cfb_add(cfb, 'Document', Buffer.from('My document content'));
CFB.utils.cfb_add(cfb, 'Metadata', Buffer.from('Created by CFB library'));

// Write to file
CFB.writeFile(cfb, 'output.cfb');

// Write as ZIP file
CFB.writeFile(cfb, 'output.zip', { fileType: 'zip', compression: true });

// Write with custom root name
CFB.writeFile(cfb, 'custom.cfb', { root: 'MyRoot' });

interface CFB$Container {
  /** List of all file/storage paths in the container */
  FullPaths: string[];
  /** Array of file entries in the same order as FullPaths */
  FileIndex: CFB$Entry[];
  /** Raw binary data (only present when parsed with raw: true) */
  raw?: {
    header: CFB$Blob;
    sectors: CFB$Blob[];
  };
}

// Supported data types for input/output operations
type CFB$DataType = 'base64' | 'binary' | 'buffer' | 'file' | 'array';

// File types for output operations  
type CFB$FileType = 'cfb' | 'zip' | 'mad';

// File operations are fully supported
const cfb = CFB.read('document.xls', { type: 'file' });
CFB.writeFile(cfb, 'output.cfb');

// Buffer operations use native Buffer
const buffer = require('fs').readFileSync('input.cfb');
const cfb = CFB.parse(buffer);

// File operations not available, use blob/array operations
const fileInput = document.getElementById('fileInput');
fileInput.addEventListener('change', async (event) => {
  const file = event.target.files[0];
  const arrayBuffer = await file.arrayBuffer();
  const uint8Array = new Uint8Array(arrayBuffer);
  const cfb = CFB.parse(uint8Array);
});

// Use Uint8Array instead of Buffer
const data = new Uint8Array([/* binary data */]);
const cfb = CFB.parse(data);