@justybase/spreadsheet-tasks 1.0.0

package/docs/API.md

@@ -0,0 +1,271 @@
+# API Documentation
+
+## Table of Contents
+
+- [XlsbWriter](#xlsbwriter)
+- [XlsxWriter](#xlsxwriter)
+- [XlsbReader](#xlsbreader)
+- [XlsxReader](#xlsxreader)
+- [ReaderFactory](#readerfactory)
+- [Types](#types)
+
+---
+
+## XlsbWriter
+
+High-performance writer for Excel Binary Workbook (.xlsb) format.
+
+### Constructor
+
+```typescript
+new XlsbWriter(filePath: string)
+```
+
+**Parameters:**
+- `filePath` - Path where the XLSB file will be created
+
+**Example:**
+```typescript
+const writer = new XlsbWriter('output.xlsb');
+```
+
+### Methods
+
+#### `addSheet(sheetName: string, hidden?: boolean): void`
+
+Adds a new worksheet to the workbook.
+
+**Parameters:**
+- `sheetName` - Name of the worksheet (max 31 characters, invalid characters will be sanitized)
+- `hidden` - Optional. If `true`, the sheet will be hidden (default: `false`)
+
+**Example:**
+```typescript
+writer.addSheet('Sales Data');
+writer.addSheet('Hidden Sheet', true);
+```
+
+#### `writeSheet(rows: any[][], headers?: string[] | null, doAutofilter?: boolean): void`
+
+Writes data to the current sheet.
+
+**Parameters:**
+- `rows` - 2D array of data to write
+- `headers` - Optional. Array of header strings (if not provided, first row is used as headers)
+- `doAutofilter` - Optional. If `true`, adds autofilter to headers (default: `true`)
+
+**Supported Data Types:**
+- `string` - Written as shared string
+- `number` - Written as number (integer or double)
+- `boolean` - Written as boolean
+- `Date` - Written as Excel date serial number
+- `null` / `undefined` - Written as empty cell
+
+**Example:**
+```typescript
+writer.writeSheet([
+    ['Product', 'Price', 'Quantity'],
+    ['Widget A', 19.99, 100],
+    ['Widget B', 29.99, 50]
+]);
+
+// With separate headers
+writer.writeSheet(
+    [['Widget A', 19.99, 100], ['Widget B', 29.99, 50]],
+    ['Product', 'Price', 'Quantity']
+);
+```
+
+#### `finalize(): Promise<void>`
+
+Finalizes and closes the workbook. Must be called after all data is written.
+
+**Example:**
+```typescript
+await writer.finalize();
+```
+
+---
+
+## XlsxWriter
+
+Writer for Excel Open XML Workbook (.xlsx) format. Has the same API as XlsbWriter.
+
+### Constructor
+
+```typescript
+new XlsxWriter(filePath: string)
+```
+
+### Methods
+
+All methods are identical to [XlsbWriter](#xlsbwriter):
+- `addSheet(sheetName: string, hidden?: boolean): void`
+- `writeSheet(rows: any[][], headers?: string[] | null, doAutofilter?: boolean): void`
+- `finalize(): Promise<void>`
+
+---
+
+## XlsbReader
+
+High-performance reader for Excel Binary Workbook (.xlsb) format.
+
+### Constructor
+
+```typescript
+new XlsbReader()
+```
+
+### Properties
+
+#### `fieldCount: number`
+
+Number of columns in the current row.
+
+#### `resultsCount: number`
+
+Number of sheets in the workbook.
+
+### Methods
+
+#### `open(path: string, readSharedStrings?: boolean): Promise<void>`
+
+Opens an XLSB file for reading.
+
+**Parameters:**
+- `path` - Path to the XLSB file
+- `readSharedStrings` - Optional. If `true`, reads shared strings table (default: `true`)
+
+**Example:**
+```typescript
+const reader = new XlsbReader();
+await reader.open('data.xlsb');
+```
+
+#### `getSheetNames(): string[]`
+
+Returns array of worksheet names.
+
+**Example:**
+```typescript
+const sheets = reader.getSheetNames();
+console.log(sheets); // ['Sheet1', 'Sheet2']
+```
+
+#### `read(): boolean`
+
+Reads the next row. Returns `true` if a row was read, `false` if end of sheet reached.
+
+**Example:**
+```typescript
+while (reader.read()) {
+    // Process row
+}
+```
+
+#### `getValue(columnIndex: number): any`
+
+Gets value at the specified column index in the current row.
+
+**Parameters:**
+- `columnIndex` - Zero-based column index
+
+**Returns:** Value at the column (string, number, boolean, Date, or null)
+
+**Example:**
+```typescript
+while (reader.read()) {
+    const name = reader.getValue(0);
+    const age = reader.getValue(1);
+    console.log(`${name}: ${age}`);
+}
+```
+
+---
+
+## XlsxReader
+
+Reader for Excel Open XML Workbook (.xlsx) format.
+
+### Constructor
+
+```typescript
+new XlsxReader()
+```
+
+### Properties
+
+Same as [XlsbReader](#xlsbreader):
+- `fieldCount: number`
+- `resultsCount: number`
+
+### Methods
+
+#### `open(path: string, readSharedStrings?: boolean): Promise<void>`
+
+Opens an XLSX file for reading.
+
+#### `close(): Promise<void>`
+
+Closes the reader and releases resources.
+
+#### `getSheetNames(): string[]`
+
+Returns array of worksheet names.
+
+#### `read(): Promise<boolean>`
+
+Reads the next row. Returns `true` if a row was read.
+
+> **Note:** Unlike XlsbReader, this method is async due to the XML parsing nature.
+
+#### `getValue(columnIndex: number): any`
+
+Gets value at the specified column index.
+
+---
+
+## ReaderFactory
+
+Factory class for creating appropriate reader based on file extension.
+
+### Methods
+
+#### `static create(filePath: string): XlsbReader | XlsxReader`
+
+Creates a reader instance based on file extension.
+
+**Parameters:**
+- `filePath` - Path to the Excel file
+
+**Returns:** `XlsbReader` for .xlsb files, `XlsxReader` for .xlsx files
+
+**Example:**
+```typescript
+const reader = ReaderFactory.create('data.xlsb');
+await reader.open('data.xlsb');
+```
+
+---
+
+## Types
+
+### Supported Cell Types
+
+| TypeScript Type | Excel Cell Type |
+|-----------------|-----------------|
+| `string` | Shared String |
+| `number` (integer) | RK Number |
+| `number` (float) | Double |
+| `boolean` | Boolean |
+| `Date` | Date Serial Number |
+| `null` / `undefined` | Empty Cell |
+
+### Sheet Name Restrictions
+
+Sheet names have the following restrictions:
+- Maximum 31 characters
+- Cannot contain: `\ / * ? [ ] :`
+- Cannot be empty
+
+Invalid characters are automatically removed when adding sheets.

package/docs/BENCHMARK.md

@@ -0,0 +1,129 @@
+# Benchmark Results
+
+## Overview
+
+This document presents comprehensive benchmark results comparing XlsbWriterNode's XLSB format performance against XLSX format.
+
+## Test Environment
+
+- **Platform:** Windows
+- **Node.js:** v20+
+- **Dataset:** 50,000 rows × 5 columns
+- **Iterations:** 20 (for statistical accuracy)
+- **Data Types:** Mixed (strings, numbers, dates)
+
+## Results Summary
+
+| Operation | XLSB | XLSX | XLSB Advantage |
+|-----------|------|------|----------------|
+| **Write** | 140.09 ms | 467.14 ms | **3.33x faster** |
+| **Read** | 118.24 ms | 276.23 ms | **2.34x faster** |
+| **File Size** | 1.49 MB | 2.83 MB | **47% smaller** |
+
+## Detailed Results
+
+### Write Performance
+
+```
+XlsbWriter:
+  Times: [259.8, 160.6, 134.6, 134.0, 146.1, 136.3, 133.0, 131.7, 146.1, 142.4, 
+          135.8, 132.2, 150.2, 140.7, 130.5, 129.3, 142.7, 139.1, 136.2, 195.9] ms
+  Average: 140.09 ms (±7.53 ms)
+  Size: 1.49 MB
+
+XlsxWriter:
+  Times: [483.3, 444.1, 471.2, 456.7, 496.0, 529.8, 488.2, 450.9, 458.7, 443.2, 
+          495.4, 454.9, 469.6, 493.0, 499.6, 452.0, 463.7, 439.5, 441.1, 453.3] ms
+  Average: 467.14 ms (±17.96 ms)
+  Size: 2.83 MB
+```
+
+### Read Performance
+
+```
+XlsbReader:
+  Times: [117.8, 136.3, 120.4, 132.1, 119.5, 118.7, 124.1, 113.7, 122.8, 113.8, 
+          121.7, 116.3, 121.7, 112.9, 117.0, 110.8, 117.8, 112.2, 121.3, 112.3] ms
+  Average: 118.24 ms (±3.56 ms)
+
+XlsxReader:
+  Times: [290.1, 269.8, 284.1, 268.0, 291.6, 281.8, 266.7, 284.3, 281.1, 257.2, 
+          271.6, 260.2, 272.7, 264.5, 290.2, 264.7, 303.2, 265.9, 272.7, 300.1] ms
+  Average: 276.23 ms (±9.44 ms)
+```
+
+## Visual Comparison
+
+### Write Speed (lower is better)
+
+```
+XLSB ██████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 140 ms
+XLSX ████████████████████████████████████████████████ 467 ms
+```
+
+### Read Speed (lower is better)
+
+```
+XLSB ████████████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 118 ms
+XLSX ████████████████████████████████████████████████ 276 ms
+```
+
+### File Size (lower is better)
+
+```
+XLSB ██████████████████████████░░░░░░░░░░░░░░░░░░░░░░ 1.49 MB
+XLSX ████████████████████████████████████████████████ 2.83 MB
+```
+
+## Why XLSB is Faster
+
+### 1. Binary Format vs XML
+
+- **XLSB** stores data in a compact binary format
+- **XLSX** uses XML, which requires parsing/generating text
+
+### 2. Compression Efficiency
+
+- XLSB's binary format compresses more efficiently
+- Smaller files = faster I/O operations
+
+### 3. No XML Overhead
+
+- No XML tags, attributes, or namespace declarations
+- Direct data encoding reduces processing time
+
+## Running Your Own Benchmarks
+
+To run benchmarks on your system:
+
+```bash
+npm run benchmark
+```
+
+Or use the TypeScript file directly:
+
+```bash
+npx ts-node benchmark-our.ts
+```
+
+## Recommendations
+
+| Scenario | Recommended Format |
+|----------|-------------------|
+| **Data processing pipelines** | XLSB |
+| **Backend Excel generation** | XLSB |
+| **Large datasets (>10K rows)** | XLSB |
+| **Storage-constrained environments** | XLSB |
+| **External sharing** | XLSX |
+| **Legacy system compatibility** | XLSX |
+| **Human-readable inspection needed** | XLSX |
+
+## Comparison with Other Libraries
+
+While this benchmark focuses on internal format comparison, note that XlsbWriterNode is designed for:
+
+- **Minimal dependencies** - Only uses essential zip libraries
+- **Memory efficiency** - Streaming architecture for large files
+- **Type safety** - Full TypeScript support
+
+For comparison with external libraries (like ExcelJS, xlsx-populate, etc.), results may vary based on specific use cases and dataset characteristics.

package/docs/PUBLISHING.md

@@ -0,0 +1,89 @@
+# Publishing to npm
+
+This document describes how to publish the `@justybase/spreadsheet-tasks` package to npm.
+
+## Automated Publishing (Recommended)
+
+The package is automatically published to npm when a new release is created on GitHub.
+
+### Prerequisites
+
+1. Ensure the `NPM_TOKEN` secret is set in the GitHub repository settings
+2. The token must have publishing permissions for the `@justybase` scope
+
+### Steps
+
+1. Create a new tag: `git tag v1.0.0`
+2. Push the tag: `git push origin v1.0.0`
+3. Create a new release on GitHub using the tag
+4. The publish workflow will automatically run and publish to npm
+
+You can also manually trigger the publish workflow from the Actions tab in GitHub.
+
+## Manual Publishing (Fallback)
+
+If the automated workflow fails or you need to publish manually:
+
+### Prerequisites
+
+1. You must be logged in to npm: `npm login`
+2. Your npm account must have access to publish under the `@justybase` scope
+3. For first-time publishing, you may need to create the scope on npm first
+
+### Steps
+
+1. Build the project:
+   ```bash
+   npm run build
+   ```
+
+2. Run tests to ensure everything works:
+   ```bash
+   npm test
+   ```
+
+3. Publish to npm:
+   ```bash
+   npm publish --access public
+   ```
+
+## First Time Publishing
+
+For the first time publishing a scoped package (`@justybase/spreadsheet-tasks`):
+
+1. **Option A**: Create the `@justybase` organization on npm
+   - Go to https://www.npmjs.com/
+   - Create a new organization named `justybase`
+   - Add your npm account as an owner
+
+2. **Option B**: Publish as an unscoped package
+   - Update `package.json` to change the name from `@justybase/spreadsheet-tasks` to `justybase-spreadsheet-tasks`
+   - This doesn't require an organization
+
+3. **Option C**: Use your personal npm scope
+   - Update `package.json` to use your npm username as the scope
+   - For example: `@yourusername/spreadsheet-tasks`
+
+## Troubleshooting
+
+### 404 Not Found Error
+
+This typically means one of the following:
+
+1. **First time publishing**: The scoped package doesn't exist yet and you need to create the scope/organization on npm
+2. **Invalid token**: The `NPM_TOKEN` is expired or doesn't have the right permissions
+3. **Scope access**: You don't have permission to publish under the `@justybase` scope
+
+### Token Expired or Revoked
+
+1. Create a new npm access token at https://www.npmjs.com/settings/[username]/tokens
+2. Select "Automation" token type
+3. Copy the token
+4. Update the `NPM_TOKEN` secret in GitHub repository settings
+
+### Permission Denied
+
+Ensure your npm account:
+1. Has 2FA enabled (required for publishing)
+2. Is a member of the `@justybase` organization (if using scoped packages)
+3. Has publishing permissions in the organization settings

package/examples/basic-read.ts

@@ -0,0 +1,109 @@
+/**
+ * Basic Read Example
+ * 
+ * This example demonstrates how to read data from XLSB and XLSX files
+ * using spreadsheet-tasks.
+ * 
+ * Run with: npx ts-node examples/basic-read.ts
+ */
+
+import { XlsbReader, XlsxReader, ReaderFactory } from '../dist';
+import * as path from 'path';
+
+async function readXlsbExample() {
+    console.log('=== Reading XLSB file ===\n');
+
+    const filePath = path.join(__dirname, 'output', 'basic.xlsb');
+
+    const reader = new XlsbReader();
+    await reader.open(filePath);
+
+    // Get sheet names
+    const sheetNames = reader.getSheetNames();
+    console.log('Sheet names:', sheetNames);
+    console.log('Number of sheets:', reader.resultsCount);
+    console.log('');
+
+    // Read all rows
+    let rowCount = 0;
+    while (reader.read()) {
+        const row: any[] = [];
+        for (let i = 0; i < reader.fieldCount; i++) {
+            row.push(reader.getValue(i));
+        }
+
+        if (rowCount === 0) {
+            console.log('Headers:', row);
+        } else {
+            console.log(`Row ${rowCount}:`, row);
+        }
+        rowCount++;
+    }
+
+    console.log(`\nTotal rows read: ${rowCount}\n`);
+}
+
+async function readXlsxExample() {
+    console.log('=== Reading XLSX file ===\n');
+
+    const filePath = path.join(__dirname, 'output', 'basic.xlsx');
+
+    const reader = new XlsxReader();
+    await reader.open(filePath);
+
+    // Get sheet names
+    const sheetNames = reader.getSheetNames();
+    console.log('Sheet names:', sheetNames);
+    console.log('');
+
+    // Read all rows
+    let rowCount = 0;
+    while (await reader.read()) {
+        const row: any[] = [];
+        for (let i = 0; i < reader.fieldCount; i++) {
+            row.push(reader.getValue(i));
+        }
+
+        if (rowCount === 0) {
+            console.log('Headers:', row);
+        } else {
+            console.log(`Row ${rowCount}:`, row);
+        }
+        rowCount++;
+    }
+
+    await reader.close();
+    console.log(`\nTotal rows read: ${rowCount}\n`);
+}
+
+async function useReaderFactory() {
+    console.log('=== Using ReaderFactory ===\n');
+
+    // ReaderFactory automatically selects the right reader based on file extension
+    const xlsbPath = path.join(__dirname, 'output', 'basic.xlsb');
+    const xlsxPath = path.join(__dirname, 'output', 'basic.xlsx');
+
+    // Read XLSB using factory
+    const xlsbReader = ReaderFactory.create(xlsbPath);
+    console.log('Reader for .xlsb:', xlsbReader.constructor.name);
+
+    // Read XLSX using factory
+    const xlsxReader = ReaderFactory.create(xlsxPath);
+    console.log('Reader for .xlsx:', xlsxReader.constructor.name);
+}
+
+async function main() {
+    try {
+        // Make sure to run basic-write.ts first to create the files
+        await readXlsbExample();
+        await readXlsxExample();
+        useReaderFactory();
+
+        console.log('\nAll files read successfully!');
+    } catch (error) {
+        console.error('Error:', error);
+        console.log('\nNote: Make sure to run basic-write.ts first to create the sample files.');
+    }
+}
+
+main();

package/examples/basic-write.ts

@@ -0,0 +1,84 @@
+/**
+ * Basic Write Example
+ * 
+ * This example demonstrates how to write data to XLSB and XLSX files
+ * using spreadsheet-tasks.
+ * 
+ * Run with: npx ts-node examples/basic-write.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 writeXlsbExample() {
+    console.log('Writing XLSB file...');
+
+    const filePath = path.join(outputDir, 'basic.xlsb');
+    const writer = new XlsbWriter(filePath);
+
+    // Add a sheet
+    writer.addSheet('Employees');
+
+    // Write data with headers
+    const data = [
+        ['Name', 'Department', 'Salary', 'Start Date', 'Active'],
+        ['Alice Johnson', 'Engineering', 85000, new Date('2020-03-15'), true],
+        ['Bob Smith', 'Marketing', 65000, new Date('2019-07-01'), true],
+        ['Charlie Brown', 'Sales', 72000, new Date('2021-01-10'), false],
+        ['Diana Ross', 'Engineering', 95000, new Date('2018-11-20'), true],
+        ['Eve Williams', 'HR', 55000, new Date('2022-05-05'), true],
+    ];
+
+    writer.writeSheet(data);
+
+    // Finalize the file
+    await writer.finalize();
+
+    console.log(`XLSB file created: ${filePath}`);
+}
+
+async function writeXlsxExample() {
+    console.log('Writing XLSX file...');
+
+    const filePath = path.join(outputDir, 'basic.xlsx');
+    const writer = new XlsxWriter(filePath);
+
+    // Add a sheet
+    writer.addSheet('Products');
+
+    // Write data - using separate headers parameter
+    const headers = ['Product ID', 'Name', 'Price', 'Quantity', 'In Stock'];
+    const data = [
+        ['P001', 'Widget A', 19.99, 150, true],
+        ['P002', 'Widget B', 29.99, 75, true],
+        ['P003', 'Gadget X', 49.99, 0, false],
+        ['P004', 'Gadget Y', 39.99, 200, true],
+        ['P005', 'Tool Z', 9.99, 500, true],
+    ];
+
+    writer.writeSheet(data, headers);
+
+    // Finalize the file
+    await writer.finalize();
+
+    console.log(`XLSX file created: ${filePath}`);
+}
+
+async function main() {
+    try {
+        await writeXlsbExample();
+        await writeXlsxExample();
+        console.log('\nAll files created successfully!');
+    } catch (error) {
+        console.error('Error:', error);
+    }
+}
+
+main();