@justybase/spreadsheet-tasks 1.0.0

package/examples/large-dataset.ts

@@ -0,0 +1,216 @@
+/**
+ * Large Dataset Example
+ * 
+ * This example demonstrates how to efficiently handle large datasets
+ * using spreadsheet-tasks. It shows the performance benefits of XLSB format.
+ * 
+ * Run with: npx ts-node examples/large-dataset.ts
+ */
+
+import { XlsbWriter, XlsxWriter, XlsbReader, XlsxReader } from '../dist';
+import * as path from 'path';
+import * as fs from 'fs';
+
+// Ensure output directory exists
+const outputDir = path.join(__dirname, 'output');
+if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+}
+
+// Configuration
+const ROW_COUNT = 100000; // 100K rows
+
+/**
+ * Generate test data with various data types
+ */
+function generateTestData(rowCount: number): any[][] {
+    const data: any[][] = [];
+
+    // Headers
+    data.push(['ID', 'Name', 'Email', 'Amount', 'Date', 'Active', 'Score']);
+
+    const names = ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank', 'Grace', 'Henry'];
+    const domains = ['gmail.com', 'yahoo.com', 'outlook.com', 'company.com'];
+
+    for (let i = 0; i < rowCount; i++) {
+        const name = names[i % names.length];
+        const domain = domains[i % domains.length];
+
+        data.push([
+            i + 1,                                          // ID (number)
+            `${name} ${i}`,                                 // Name (string)
+            `${name.toLowerCase()}${i}@${domain}`,          // Email (string)
+            Math.round(Math.random() * 10000 * 100) / 100,  // Amount (decimal)
+            new Date(2020, i % 12, (i % 28) + 1),          // Date
+            i % 3 !== 0,                                    // Active (boolean)
+            Math.floor(Math.random() * 100),                // Score (integer)
+        ]);
+    }
+
+    return data;
+}
+
+/**
+ * Write large dataset to XLSB file
+ */
+async function writeLargeXlsb(data: any[][]): Promise<{ time: number; size: number }> {
+    const filePath = path.join(outputDir, 'large-dataset.xlsb');
+
+    const startTime = performance.now();
+
+    const writer = new XlsbWriter(filePath);
+    writer.addSheet('Data');
+    writer.writeSheet(data);
+    await writer.finalize();
+
+    const endTime = performance.now();
+    const stats = fs.statSync(filePath);
+
+    return {
+        time: endTime - startTime,
+        size: stats.size,
+    };
+}
+
+/**
+ * Write large dataset to XLSX file
+ */
+async function writeLargeXlsx(data: any[][]): Promise<{ time: number; size: number }> {
+    const filePath = path.join(outputDir, 'large-dataset.xlsx');
+
+    const startTime = performance.now();
+
+    const writer = new XlsxWriter(filePath);
+    writer.addSheet('Data');
+    writer.writeSheet(data);
+    await writer.finalize();
+
+    const endTime = performance.now();
+    const stats = fs.statSync(filePath);
+
+    return {
+        time: endTime - startTime,
+        size: stats.size,
+    };
+}
+
+/**
+ * Read large XLSB file
+ */
+async function readLargeXlsb(): Promise<{ time: number; rowCount: number }> {
+    const filePath = path.join(outputDir, 'large-dataset.xlsb');
+
+    const startTime = performance.now();
+
+    const reader = new XlsbReader();
+    await reader.open(filePath);
+
+    let rowCount = 0;
+    while (reader.read()) {
+        rowCount++;
+        // Access values to simulate real-world usage
+        for (let i = 0; i < reader.fieldCount; i++) {
+            const _ = reader.getValue(i);
+        }
+    }
+
+    const endTime = performance.now();
+
+    return {
+        time: endTime - startTime,
+        rowCount,
+    };
+}
+
+/**
+ * Read large XLSX file
+ */
+async function readLargeXlsx(): Promise<{ time: number; rowCount: number }> {
+    const filePath = path.join(outputDir, 'large-dataset.xlsx');
+
+    const startTime = performance.now();
+
+    const reader = new XlsxReader();
+    await reader.open(filePath);
+
+    let rowCount = 0;
+    while (await reader.read()) {
+        rowCount++;
+        // Access values to simulate real-world usage
+        for (let i = 0; i < reader.fieldCount; i++) {
+            const _ = reader.getValue(i);
+        }
+    }
+
+    await reader.close();
+    const endTime = performance.now();
+
+    return {
+        time: endTime - startTime,
+        rowCount,
+    };
+}
+
+function formatBytes(bytes: number): string {
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+async function main() {
+    console.log('='.repeat(60));
+    console.log('Large Dataset Performance Test');
+    console.log('='.repeat(60));
+    console.log(`Row count: ${ROW_COUNT.toLocaleString()}`);
+    console.log('');
+
+    // Generate test data
+    console.log('Generating test data...');
+    const data = generateTestData(ROW_COUNT);
+    console.log(`Data generated: ${data.length.toLocaleString()} rows\n`);
+
+    // Write tests
+    console.log('--- WRITE TESTS ---\n');
+
+    console.log('Writing XLSB...');
+    const xlsbWrite = await writeLargeXlsb(data);
+    console.log(`  Time: ${xlsbWrite.time.toFixed(2)} ms`);
+    console.log(`  Size: ${formatBytes(xlsbWrite.size)}\n`);
+
+    console.log('Writing XLSX...');
+    const xlsxWrite = await writeLargeXlsx(data);
+    console.log(`  Time: ${xlsxWrite.time.toFixed(2)} ms`);
+    console.log(`  Size: ${formatBytes(xlsxWrite.size)}\n`);
+
+    // Read tests
+    console.log('--- READ TESTS ---\n');
+
+    console.log('Reading XLSB...');
+    const xlsbRead = await readLargeXlsb();
+    console.log(`  Time: ${xlsbRead.time.toFixed(2)} ms`);
+    console.log(`  Rows: ${xlsbRead.rowCount.toLocaleString()}\n`);
+
+    console.log('Reading XLSX...');
+    const xlsxRead = await readLargeXlsx();
+    console.log(`  Time: ${xlsxRead.time.toFixed(2)} ms`);
+    console.log(`  Rows: ${xlsxRead.rowCount.toLocaleString()}\n`);
+
+    // Summary
+    console.log('='.repeat(60));
+    console.log('SUMMARY');
+    console.log('='.repeat(60));
+    console.log('');
+    console.log('Write Performance:');
+    console.log(`  XLSB: ${xlsbWrite.time.toFixed(2)} ms (${formatBytes(xlsbWrite.size)})`);
+    console.log(`  XLSX: ${xlsxWrite.time.toFixed(2)} ms (${formatBytes(xlsxWrite.size)})`);
+    console.log(`  XLSB is ${(xlsxWrite.time / xlsbWrite.time).toFixed(2)}x faster`);
+    console.log(`  XLSB is ${((1 - xlsbWrite.size / xlsxWrite.size) * 100).toFixed(0)}% smaller`);
+    console.log('');
+    console.log('Read Performance:');
+    console.log(`  XLSB: ${xlsbRead.time.toFixed(2)} ms`);
+    console.log(`  XLSX: ${xlsxRead.time.toFixed(2)} ms`);
+    console.log(`  XLSB is ${(xlsxRead.time / xlsbRead.time).toFixed(2)}x faster`);
+    console.log('');
+}
+
+main().catch(console.error);

package/examples/multiple-sheets.ts

@@ -0,0 +1,126 @@
+/**
+ * Multiple Sheets Example
+ * 
+ * This example demonstrates how to work with multiple worksheets
+ * in a single workbook.
+ * 
+ * Run with: npx ts-node examples/multiple-sheets.ts
+ */
+
+import { XlsbWriter, XlsxWriter } from '../dist';
+import * as path from 'path';
+import * as fs from 'fs';
+
+// Ensure output directory exists
+const outputDir = path.join(__dirname, 'output');
+if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+}
+
+async function createMultiSheetXlsb() {
+    console.log('Creating multi-sheet XLSB file...');
+
+    const filePath = path.join(outputDir, 'multi-sheet.xlsb');
+    const writer = new XlsbWriter(filePath);
+
+    // Sheet 1: Sales Summary
+    writer.addSheet('Sales Summary');
+    writer.writeSheet([
+        ['Region', 'Q1', 'Q2', 'Q3', 'Q4', 'Total'],
+        ['North', 125000, 142000, 138000, 165000, 570000],
+        ['South', 98000, 105000, 112000, 128000, 443000],
+        ['East', 156000, 167000, 178000, 195000, 696000],
+        ['West', 189000, 198000, 205000, 225000, 817000],
+    ]);
+
+    // Sheet 2: Monthly Details
+    writer.addSheet('Monthly Details');
+    writer.writeSheet([
+        ['Month', 'Revenue', 'Expenses', 'Profit'],
+        ['January', 45000, 32000, 13000],
+        ['February', 52000, 35000, 17000],
+        ['March', 48000, 33000, 15000],
+        ['April', 55000, 36000, 19000],
+        ['May', 61000, 38000, 23000],
+        ['June', 58000, 37000, 21000],
+    ]);
+
+    // Sheet 3: Hidden configuration sheet
+    writer.addSheet('Config', true); // hidden = true
+    writer.writeSheet([
+        ['Setting', 'Value'],
+        ['Version', '1.0.0'],
+        ['LastUpdated', new Date()],
+        ['AutoRefresh', true],
+    ]);
+
+    // Sheet 4: Products
+    writer.addSheet('Products');
+    writer.writeSheet([
+        ['SKU', 'Product Name', 'Category', 'Price', 'Stock'],
+        ['SKU-001', 'Laptop Pro 15', 'Electronics', 1299.99, 45],
+        ['SKU-002', 'Wireless Mouse', 'Accessories', 29.99, 500],
+        ['SKU-003', 'USB-C Hub', 'Accessories', 49.99, 200],
+        ['SKU-004', 'Monitor 27"', 'Electronics', 399.99, 75],
+        ['SKU-005', 'Mechanical Keyboard', 'Accessories', 129.99, 150],
+    ]);
+
+    await writer.finalize();
+    console.log(`Created: ${filePath}`);
+    console.log('Sheets: Sales Summary, Monthly Details, Config (hidden), Products\n');
+}
+
+async function createMultiSheetXlsx() {
+    console.log('Creating multi-sheet XLSX file...');
+
+    const filePath = path.join(outputDir, 'multi-sheet.xlsx');
+    const writer = new XlsxWriter(filePath);
+
+    // Sheet 1: Employees
+    writer.addSheet('Employees');
+    writer.writeSheet([
+        ['ID', 'Name', 'Department', 'Hire Date', 'Salary'],
+        [1, 'John Doe', 'Engineering', new Date('2020-01-15'), 85000],
+        [2, 'Jane Smith', 'Marketing', new Date('2019-06-01'), 72000],
+        [3, 'Bob Johnson', 'Sales', new Date('2021-03-10'), 68000],
+        [4, 'Alice Brown', 'HR', new Date('2018-09-22'), 62000],
+        [5, 'Charlie Wilson', 'Engineering', new Date('2022-02-28'), 90000],
+    ]);
+
+    // Sheet 2: Departments
+    writer.addSheet('Departments');
+    writer.writeSheet([
+        ['Department', 'Manager', 'Budget', 'Headcount'],
+        ['Engineering', 'Sarah Connor', 2500000, 45],
+        ['Marketing', 'Mike Ross', 1200000, 22],
+        ['Sales', 'Lisa Chen', 1800000, 35],
+        ['HR', 'Tom Hardy', 800000, 12],
+        ['Finance', 'Emma Watson', 600000, 8],
+    ]);
+
+    // Sheet 3: Projects
+    writer.addSheet('Projects');
+    writer.writeSheet([
+        ['Project Name', 'Status', 'Start Date', 'End Date', 'Budget'],
+        ['Website Redesign', 'In Progress', new Date('2024-01-01'), new Date('2024-06-30'), 150000],
+        ['Mobile App v2', 'Planning', new Date('2024-04-01'), new Date('2024-12-31'), 300000],
+        ['CRM Integration', 'Completed', new Date('2023-06-01'), new Date('2024-01-31'), 200000],
+        ['Data Migration', 'On Hold', new Date('2024-03-01'), new Date('2024-09-30'), 100000],
+    ]);
+
+    await writer.finalize();
+    console.log(`Created: ${filePath}`);
+    console.log('Sheets: Employees, Departments, Projects\n');
+}
+
+async function main() {
+    try {
+        await createMultiSheetXlsb();
+        await createMultiSheetXlsx();
+        console.log('All multi-sheet files created successfully!');
+    } catch (error) {
+        console.error('Error:', error);
+    }
+}
+
+main();

package/examples/streaming-example.ts

@@ -0,0 +1,181 @@
+/**
+ * Streaming Example
+ * 
+ * This example demonstrates how to use the streaming API to write
+ * large datasets efficiently without loading all data into memory.
+ * 
+ * Run with: npx ts-node examples/streaming-example.ts
+ */
+
+import { XlsbWriter } from '../dist/XlsbWriter';
+import * as path from 'path';
+
+async function streamingExample() {
+    console.log('=== XlsbWriter Streaming Example ===\n');
+
+    const outputPath = path.join(__dirname, '..', 'output', 'streaming-example.xlsb');
+    console.log(`Output file: ${outputPath}\n`);
+
+    const writer = new XlsbWriter(outputPath);
+
+    // Example 1: Generate large dataset without loading all into memory
+    console.log('Example 1: Generating 100,000 rows using streaming...');
+    const startTime1 = Date.now();
+    const initialMemory = process.memoryUsage().heapUsed / 1024 / 1024;
+
+    writer.startSheet('LargeDataset', 5, ['ID', 'Name', 'Value', 'Date', 'Active']);
+
+    for (let i = 0; i < 100_000; i++) {
+        writer.writeRow([
+            i + 1,
+            `User_${i + 1}`,
+            Math.random() * 10000,
+            new Date(2024, 0, 1 + (i % 365)),
+            i % 2 === 0
+        ]);
+
+        // Log progress every 20,000 rows
+        if ((i + 1) % 20_000 === 0) {
+            const currentMemory = process.memoryUsage().heapUsed / 1024 / 1024;
+            const memoryDelta = (currentMemory - initialMemory).toFixed(2);
+            console.log(`  Processed ${(i + 1).toLocaleString()} rows | Memory delta: ${memoryDelta} MB`);
+        }
+    }
+
+    writer.endSheet();
+    const elapsed1 = Date.now() - startTime1;
+    const finalMemory = process.memoryUsage().heapUsed / 1024 / 1024;
+    const totalMemoryUsed = (finalMemory - initialMemory).toFixed(2);
+
+    console.log(`✓ Completed in ${elapsed1}ms`);
+    console.log(`  Total memory delta: ${totalMemoryUsed} MB\n`);
+
+    // Example 2: Multiple sheets with streaming
+    console.log('Example 2: Creating multiple sheets with streaming...');
+    const startTime2 = Date.now();
+
+    // Sheet 2: Customer data
+    writer.startSheet('Customers', 4, ['CustomerID', 'Email', 'SignupDate', 'Premium']);
+    for (let i = 0; i < 10_000; i++) {
+        writer.writeRow([
+            1000 + i,
+            `customer${i}@example.com`,
+            new Date(2020 + (i % 5), i % 12, (i % 28) + 1),
+            i % 3 === 0
+        ]);
+    }
+    writer.endSheet();
+
+    // Sheet 3: Transactions
+    writer.startSheet('Transactions', 3, ['TransactionID', 'Amount', 'Timestamp']);
+    for (let i = 0; i < 50_000; i++) {
+        writer.writeRow([
+            i + 1,
+            parseFloat((Math.random() * 5000).toFixed(2)),
+            new Date(2024, i % 12, (i % 28) + 1, i % 24, i % 60)
+        ]);
+    }
+    writer.endSheet();
+
+    const elapsed2 = Date.now() - startTime2;
+    console.log(`✓ Multiple sheets completed in ${elapsed2}ms\n`);
+
+    // Example 3: Mixed data types without autofilter
+    console.log('Example 3: Mixed data types (no autofilter)...');
+    writer.startSheet('MixedTypes', 6, undefined, { doAutofilter: false });
+
+    for (let i = 0; i < 1000; i++) {
+        writer.writeRow([
+            i,
+            `Text ${i}`,
+            Math.PI * i,
+            new Date(),
+            i % 2 === 0,
+            null  // null values are supported
+        ]);
+    }
+    writer.endSheet();
+    console.log('✓ Completed\n');
+
+    // Finalize the workbook
+    console.log('Finalizing workbook...');
+    await writer.finalize();
+    console.log('✓ Done!\n');
+
+    console.log('=== Summary ===');
+    console.log('Total sheets created: 4');
+    console.log('Total rows written: ~161,000');
+    console.log(`File saved to: ${outputPath}`);
+}
+
+// Memory comparison function
+async function compareMemoryUsage() {
+    console.log('\n=== Memory Usage Comparison ===\n');
+
+    const rowCount = 50_000;
+    const cols = 5;
+
+    // Test 1: Streaming mode
+    console.log('Test 1: Streaming mode');
+    const streamingFile = path.join(__dirname, '..', 'output', 'streaming-test.xlsb');
+    const writer1 = new XlsbWriter(streamingFile);
+
+    const streamStart = Date.now();
+    const streamMemStart = process.memoryUsage().heapUsed / 1024 / 1024;
+
+    writer1.startSheet('Data', cols, ['Col1', 'Col2', 'Col3', 'Col4', 'Col5']);
+    for (let i = 0; i < rowCount; i++) {
+        writer1.writeRow([i, `Text${i}`, Math.random() * 1000, new Date(), i % 2 === 0]);
+    }
+    writer1.endSheet();
+    await writer1.finalize();
+
+    const streamEnd = Date.now();
+    const streamMemEnd = process.memoryUsage().heapUsed / 1024 / 1024;
+    const streamTime = streamEnd - streamStart;
+    const streamMem = (streamMemEnd - streamMemStart).toFixed(2);
+
+    console.log(`  Time: ${streamTime}ms`);
+    console.log(`  Memory delta: ${streamMem} MB\n`);
+
+    // Test 2: Batch mode (traditional writeSheet)
+    console.log('Test 2: Batch mode (traditional writeSheet)');
+    const batchFile = path.join(__dirname, '..', 'output', 'batch-test.xlsb');
+    const writer2 = new XlsbWriter(batchFile);
+
+    const batchStart = Date.now();
+    const batchMemStart = process.memoryUsage().heapUsed / 1024 / 1024;
+
+    // Generate all rows in memory first
+    const rows: any[][] = [];
+    for (let i = 0; i < rowCount; i++) {
+        rows.push([i, `Text${i}`, Math.random() * 1000, new Date(), i % 2 === 0]);
+    }
+
+    writer2.addSheet('Data');
+    writer2.writeSheet(rows, ['Col1', 'Col2', 'Col3', 'Col4', 'Col5']);
+    await writer2.finalize();
+
+    const batchEnd = Date.now();
+    const batchMemEnd = process.memoryUsage().heapUsed / 1024 / 1024;
+    const batchTime = batchEnd - batchStart;
+    const batchMem = (batchMemEnd - batchMemStart).toFixed(2);
+
+    console.log(`  Time: ${batchTime}ms`);
+    console.log(`  Memory delta: ${batchMem} MB\n`);
+
+    console.log('=== Results ===');
+    console.log(`Streaming is ${(parseFloat(batchMem) / parseFloat(streamMem)).toFixed(1)}x more memory efficient`);
+    console.log(`Speed difference: ${Math.abs(streamTime - batchTime)}ms ${streamTime < batchTime ? 'faster' : 'slower'}`);
+}
+
+// Run examples
+(async () => {
+    try {
+        await streamingExample();
+        await compareMemoryUsage();
+    } catch (error) {
+        console.error('Error:', error);
+        process.exit(1);
+    }
+})();

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@justybase/spreadsheet-tasks",
+  "version": "1.0.0",
+  "description": "High-performance TypeScript library for reading and writing Excel files in XLSB and XLSX formats. XLSB is 3.3x faster to write and 2.1x faster to read than XLSX.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs",
+    "examples"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && npm run test:smoke && npm run test:unit && npm run test:integration",
+    "test:smoke": "npm run build && npx ts-node tests/smoke.test.ts",
+    "test:unit": "npx ts-node tests/unit/bigbuffer.test.ts && npx ts-node tests/unit/biff-reader-writer.test.ts && npx ts-node tests/unit/xlsb-writer.test.ts",
+    "test:integration": "npm run build && npx ts-node tests/integration/xlsb-writer.test.ts && npx ts-node tests/integration/xlsx-writer.test.ts",
+    "test:xlsb": "npm run build && npx ts-node tests/integration/xlsb-writer.test.ts",
+    "test:xlsx": "npm run build && npx ts-node tests/integration/xlsx-writer.test.ts",
+    "benchmark": "npm run build && npx ts-node benchmarks/performance.bench.ts",
+    "benchmark:comparison": "npm run build && npx ts-node benchmarks/comparison.bench.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "excel",
+    "xlsb",
+    "xlsx",
+    "spreadsheet",
+    "binary",
+    "workbook",
+    "reader",
+    "writer",
+    "typescript",
+    "performance"
+  ],
+  "author": "Krzysztof Dusko",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KrzysztofDusko/XlsbWriterNode.git"
+  },
+  "homepage": "https://github.com/KrzysztofDusko/XlsbWriterNode#readme",
+  "bugs": {
+    "url": "https://github.com/KrzysztofDusko/XlsbWriterNode/issues"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "dependencies": {
+    "adm-zip": "^0.5.16",
+    "archiver": "^7.0.1",
+    "yauzl": "^3.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "@types/adm-zip": "^0.5.6",
+    "@types/archiver": "^7.0.0",
+    "@types/node": "^22.10.5",
+    "@types/yauzl": "^2.10.3",
+    "eslint": "^9.17.0",
+    "exceljs": "^4.4.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.19.1"
+  }
+}