@justybase/spreadsheet-tasks 1.2.0 → 1.3.1

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.XlsxWriter = exports.XlsbWriter = exports.ReaderFactory = exports.XlsxReader = exports.XlsbReader = exports.BiffReaderWriter = exports.ExcelReaderAbstract = exports.BigBuffer = void 0;
+exports.getFormat = exports.unwrapCell = exports.isFormattedCell = exports.F = exports.XlsxWriter = exports.XlsbWriter = exports.ReaderFactory = exports.XlsxReader = exports.XlsbReader = exports.BiffReaderWriter = exports.ExcelReaderAbstract = exports.BigBuffer = void 0;
 // Core classes
 var BigBuffer_1 = require("./BigBuffer");
 Object.defineProperty(exports, "BigBuffer", { enumerable: true, get: function () { return BigBuffer_1.BigBuffer; } });
@@ -20,4 +20,10 @@ var XlsbWriter_1 = require("./XlsbWriter");
 Object.defineProperty(exports, "XlsbWriter", { enumerable: true, get: function () { return XlsbWriter_1.XlsbWriter; } });
 var XlsxWriter_1 = require("./XlsxWriter");
 Object.defineProperty(exports, "XlsxWriter", { enumerable: true, get: function () { return XlsxWriter_1.XlsxWriter; } });
+// Formatting
+var Formats_1 = require("./Formats");
+Object.defineProperty(exports, "F", { enumerable: true, get: function () { return Formats_1.F; } });
+Object.defineProperty(exports, "isFormattedCell", { enumerable: true, get: function () { return Formats_1.isFormattedCell; } });
+Object.defineProperty(exports, "unwrapCell", { enumerable: true, get: function () { return Formats_1.unwrapCell; } });
+Object.defineProperty(exports, "getFormat", { enumerable: true, get: function () { return Formats_1.getFormat; } });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,eAAe;AACf,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAClB,6DAA4D;AAAnD,0HAAA,mBAAmB,OAAA;AAC5B,uDAAsD;AAA7C,oHAAA,gBAAgB,OAAA;AAEzB,UAAU;AACV,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AACnB,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AACnB,iDAAgD;AAAvC,8GAAA,aAAa,OAAA;AAEtB,UAAU;AACV,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AACnB,2CAA0C;AAAjC,wGAAA,UAAU,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,eAAe;AACf,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAClB,6DAA4D;AAAnD,0HAAA,mBAAmB,OAAA;AAC5B,uDAAsD;AAA7C,oHAAA,gBAAgB,OAAA;AAEzB,UAAU;AACV,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AACnB,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AACnB,iDAAgD;AAAvC,8GAAA,aAAa,OAAA;AAEtB,UAAU;AACV,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AACnB,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AAEnB,aAAa;AACb,qCAAqF;AAA7D,4FAAA,CAAC,OAAA;AAAE,0GAAA,eAAe,OAAA;AAAE,qGAAA,UAAU,OAAA;AAAE,oGAAA,SAAS,OAAA"}

package/examples/formats-demo.ts

@@ -0,0 +1,225 @@
+import { XlsbWriter } from '../src/XlsbWriter';
+import { XlsxWriter } from '../src/XlsxWriter';
+import { F, FormattedCell } from '../src/Formats';
+import * as fs from 'fs';
+
+const OUTPUT_DIR = './test-output';
+
+if (!fs.existsSync(OUTPUT_DIR)) {
+    fs.mkdirSync(OUTPUT_DIR, { recursive: true });
+}
+
+const demoDate = new Date(2026, 5, 1, 14, 34, 20); // June 1, 2026 14:34:20
+const demoValue = 100000;
+
+// ========== XLSB Format Demo ==========
+async function createXlsbFormatDemo() {
+    const wb = new XlsbWriter(`${OUTPUT_DIR}/formats_demo_xlsb.xlsb`);
+
+    // Sheet 1: Number formats
+    wb.addSheet('Number Formats');
+    wb.writeSheet([
+        ['Format Name', 'Value'],
+        ['No formatting', demoValue],
+        ['Thousands separator', { value: demoValue, format: F.THOUSANDS_SEP }],
+        ['Currency PLN', { value: demoValue, format: F.CURRENCY_PLN }],
+        ['Currency EUR', { value: demoValue, format: F.CURRENCY_EUR }],
+        ['Percentage', { value: 1000, format: F.PERCENTAGE }],
+        ['Scientific', { value: demoValue, format: F.SCIENTIFIC }],
+        ['Two decimals', { value: demoValue, format: F.TWO_DECIMALS }],
+        ['Text', { value: demoValue, format: F.TEXT }],
+        ['Leading zeros', { value: demoValue, format: F.LEADING_ZEROS }],
+    ], ['Format Name', 'Value']);
+
+    // Sheet 2: Date & DateTime formats
+    const dateRows: any[] = [
+        ['Format Name', 'Value'],
+        [],
+        ['--- Date Formats ---', ''],
+        ['No formatting (number)', demoDate.getTime()],
+        ['Short (dd.mm.yyyy)', { value: demoDate, format: F.DATE_SHORT }],
+        ['Long (d mmmm yyyy)', { value: demoDate, format: F.DATE_LONG }],
+        ['Day-Month-Year (dd-mm-yyyy)', { value: demoDate, format: F.DATE_DAY_MONTH_YEAR }],
+        ['ISO (yyyy-mm-dd)', { value: demoDate, format: F.DATE_ISO }],
+        ['Month Year (mmmm yyyy)', { value: demoDate, format: F.DATE_MONTH_YEAR }],
+        ['Weekday', { value: demoDate, format: F.DATE_WEEKDAY }],
+        ['Day Month (d mmmm)', { value: demoDate, format: F.DATE_DAY_MONTH }],
+        ['Year only (yyyy)', { value: demoDate, format: F.DATE_YEAR_ONLY }],
+        [],
+        ['--- DateTime Formats ---', ''],
+        ['Short DT (dd.mm.yyyy hh:mm)', { value: demoDate, format: F.DATETIME_SHORT }],
+        ['Long DT (d mmmm yyyy hh:mm:ss)', { value: demoDate, format: F.DATETIME_LONG }],
+        ['Time only (hh:mm)', { value: demoDate, format: F.TIME_HH_MM }],
+        ['Time only (hh:mm:ss)', { value: demoDate, format: F.TIME_HH_MM_SS }],
+        ['Time 12h', { value: demoDate, format: F.TIME_12H }],
+        ['24h DT (dd.mm.yyyy hh:mm:ss)', { value: demoDate, format: F.DATETIME_24H }],
+        ['ISO DT', { value: demoDate, format: F.DATETIME_ISO }],
+        ['Milliseconds (hh:mm:ss.000)', { value: demoDate, format: F.TIME_MS }],
+    ];
+
+    wb.addSheet('Date Formats');
+    wb.writeSheet(dateRows, ['Format Name', 'Value']);
+
+    await wb.finalize();
+    console.log(`✅ XLSB format demo: ${OUTPUT_DIR}/formats_demo_xlsb.xlsb`);
+}
+
+// ========== XLSX Format Demo ==========
+async function createXlsxFormatDemo() {
+    const wb = new XlsxWriter(`${OUTPUT_DIR}/formats_demo_xlsx.xlsx`);
+
+    wb.addSheet('Number Formats');
+    wb.writeSheet([
+        ['Format Name', 'Value'],
+        ['No formatting', demoValue],
+        ['Thousands separator', { value: demoValue, format: F.THOUSANDS_SEP }],
+        ['Currency PLN', { value: demoValue, format: F.CURRENCY_PLN }],
+        ['Currency EUR', { value: demoValue, format: F.CURRENCY_EUR }],
+        ['Percentage', { value: 1000, format: F.PERCENTAGE }],
+        ['Scientific', { value: demoValue, format: F.SCIENTIFIC }],
+        ['Two decimals', { value: demoValue, format: F.TWO_DECIMALS }],
+        ['Text', { value: demoValue, format: F.TEXT }],
+        ['Leading zeros', { value: demoValue, format: F.LEADING_ZEROS }],
+    ], ['Format Name', 'Value']);
+
+    wb.addSheet('Date Formats');
+    wb.writeSheet([
+        ['Format Name', 'Value'],
+        [],
+        ['--- Date Formats ---', ''],
+        ['Short (dd.mm.yyyy)', { value: demoDate, format: F.DATE_SHORT }],
+        ['Long (d mmmm yyyy)', { value: demoDate, format: F.DATE_LONG }],
+        ['ISO (yyyy-mm-dd)', { value: demoDate, format: F.DATE_ISO }],
+        ['Month Year (mmmm yyyy)', { value: demoDate, format: F.DATE_MONTH_YEAR }],
+        ['Weekday', { value: demoDate, format: F.DATE_WEEKDAY }],
+        ['Year only (yyyy)', { value: demoDate, format: F.DATE_YEAR_ONLY }],
+        [],
+        ['--- DateTime Formats ---', ''],
+        ['Short DT (dd.mm.yyyy hh:mm)', { value: demoDate, format: F.DATETIME_SHORT }],
+        ['Long DT (d mmmm yyyy hh:mm:ss)', { value: demoDate, format: F.DATETIME_LONG }],
+        ['Time only (hh:mm)', { value: demoDate, format: F.TIME_HH_MM }],
+        ['Time only (hh:mm:ss)', { value: demoDate, format: F.TIME_HH_MM_SS }],
+        ['Time 12h', { value: demoDate, format: F.TIME_12H }],
+        ['24h DT (dd.mm.yyyy hh:mm:ss)', { value: demoDate, format: F.DATETIME_24H }],
+        ['ISO DT', { value: demoDate, format: F.DATETIME_ISO }],
+        ['Milliseconds (hh:mm:ss.000)', { value: demoDate, format: F.TIME_MS }],
+    ], ['Format Name', 'Value']);
+
+    await wb.finalize();
+    console.log(`✅ XLSX format demo: ${OUTPUT_DIR}/formats_demo_xlsx.xlsx`);
+}
+
+// ========== Streaming API Demo ==========
+async function createStreamingFormatDemo() {
+    const wb = new XlsbWriter(`${OUTPUT_DIR}/formats_streaming_demo.xlsb`);
+
+    wb.startSheet('Number Formats', 2, ['Format', 'Value']);
+    wb.writeRow(['No formatting', 123456.78]);
+    wb.writeRow(['Thousands separator', { value: 123456.78, format: F.THOUSANDS_SEP }]);
+    wb.writeRow(['Currency PLN', { value: 123456.78, format: F.CURRENCY_PLN }]);
+    wb.writeRow(['Currency EUR', { value: 123456.78, format: F.CURRENCY_EUR }]);
+    wb.writeRow(['Percentage', { value: 0.25, format: F.PERCENTAGE }]);
+    wb.writeRow(['Scientific', { value: 123456.78, format: F.SCIENTIFIC }]);
+    wb.writeRow(['Two decimals', { value: 123456.78, format: F.TWO_DECIMALS }]);
+    wb.writeRow(['Text', { value: '123456.78', format: F.TEXT }]);
+    wb.writeRow(['Leading zeros', { value: 42, format: F.LEADING_ZEROS }]);
+    wb.endSheet();
+
+    wb.startSheet('Date Formats', 2, ['Format', 'Value']);
+    wb.writeRow(['Short date', { value: demoDate, format: F.DATE_SHORT }]);
+    wb.writeRow(['Long date', { value: demoDate, format: F.DATE_LONG }]);
+    wb.writeRow(['Short datetime', { value: demoDate, format: F.DATETIME_SHORT }]);
+    wb.writeRow(['Long datetime', { value: demoDate, format: F.DATETIME_LONG }]);
+    wb.writeRow(['Time only', { value: demoDate, format: F.TIME_HH_MM_SS }]);
+    wb.writeRow(['Time 12h', { value: demoDate, format: F.TIME_12H }]);
+    wb.writeRow(['ISO', { value: demoDate, format: F.DATETIME_ISO }]);
+    wb.writeRow(['Milliseconds', { value: demoDate, format: F.TIME_MS }]);
+    wb.endSheet();
+
+    await wb.finalize();
+    console.log(`✅ XLSB streaming format demo: ${OUTPUT_DIR}/formats_streaming_demo.xlsb`);
+}
+
+// ========== Real-world Scenario Demo ==========
+async function createSalesReportDemo() {
+    const wb = new XlsxWriter(`${OUTPUT_DIR}/sales_report_demo.xlsx`);
+
+    wb.addSheet('Sales');
+    wb.writeSheet([
+        ['Product', 'Price', 'Cost', 'Margin', 'Sale Date', 'Qty', 'Total'],
+        ['Laptop Dell XPS 15', { value: 5499.99, format: F.CURRENCY_PLN }, { value: 4200.00, format: F.CURRENCY_PLN }, { value: 0.30, format: F.PERCENTAGE }, { value: new Date(2026, 5, 1), format: F.DATE_SHORT }, { value: 5, format: F.THOUSANDS_SEP }, { value: 27499.95, format: F.CURRENCY_PLN }],
+        ['Monitor LG 27"', { value: 1299.00, format: F.CURRENCY_PLN }, { value: 950.00, format: F.CURRENCY_PLN }, { value: 0.37, format: F.PERCENTAGE }, { value: new Date(2026, 5, 2), format: F.DATE_SHORT }, 3, { value: 3897.00, format: F.CURRENCY_PLN }],
+        ['Mechanical keyboard', { value: 349.99, format: F.CURRENCY_PLN }, { value: 200.00, format: F.CURRENCY_PLN }, { value: 0.75, format: F.PERCENTAGE }, { value: new Date(2026, 5, 3), format: F.DATE_SHORT }, 10, { value: 3499.90, format: F.CURRENCY_PLN }],
+        ['Wireless mouse', { value: 199.00, format: F.CURRENCY_PLN }, { value: 120.00, format: F.CURRENCY_PLN }, { value: 0.66, format: F.PERCENTAGE }, { value: new Date(2026, 5, 4), format: F.DATE_SHORT }, 8, { value: 1592.00, format: F.CURRENCY_PLN }],
+        ['SSD Drive 1TB', { value: 599.00, format: F.CURRENCY_PLN }, { value: 380.00, format: F.CURRENCY_PLN }, { value: 0.58, format: F.PERCENTAGE }, { value: new Date(2026, 5, 5), format: F.DATE_SHORT }, 2, { value: 1198.00, format: F.CURRENCY_PLN }],
+    ], ['Product', 'Price', 'Cost', 'Margin', 'Sale Date', 'Qty', 'Total']);
+
+    wb.addSheet('Summary');
+    wb.writeSheet([
+        ['Total Sales', { value: 37486.85, format: F.CURRENCY_PLN }],
+    ], ['Description', 'Value']);
+
+    await wb.finalize();
+    console.log(`✅ Sales report demo: ${OUTPUT_DIR}/sales_report_demo.xlsx`);
+}
+
+// ========== All-in-one comprehensive demo ==========
+async function createComprehensiveDemo() {
+    const wb = new XlsbWriter(`${OUTPUT_DIR}/comprehensive_formats_demo.xlsb`);
+
+    wb.addSheet('All Formats');
+    const rows: any[] = [['Category', 'Format Name', 'Value', 'Format Code']];
+
+    // Number formats
+    const numVal = 1234567.89;
+    rows.push(['Numeric', 'No formatting', numVal, 'Raw number']);
+    rows.push(['Numeric', 'Thousands separator', { value: numVal, format: F.THOUSANDS_SEP }, '#,##0']);
+    rows.push(['Numeric', 'Currency PLN', { value: numVal, format: F.CURRENCY_PLN }, '#,##0.00 "zł"']);
+    rows.push(['Numeric', 'Currency EUR', { value: numVal, format: F.CURRENCY_EUR }, '#,##0.00 €']);
+    rows.push(['Numeric', 'Percentage', { value: 0.125, format: F.PERCENTAGE }, '0%']);
+    rows.push(['Numeric', 'Scientific', { value: numVal, format: F.SCIENTIFIC }, '0.00E+00']);
+    rows.push(['Numeric', 'Two decimals', { value: numVal, format: F.TWO_DECIMALS }, '#,##0.00']);
+    rows.push(['Numeric', 'Text', { value: numVal, format: F.TEXT }, '@']);
+    rows.push(['Numeric', 'Leading zeros', { value: 42, format: F.LEADING_ZEROS }, '000000000']);
+
+    // Date formats
+    const dt = new Date(2026, 11, 24, 15, 45, 30); // Dec 24, 2026 15:45:30
+    rows.push([]);
+    rows.push(['Date', 'Short date', { value: dt, format: F.DATE_SHORT }, 'dd.mm.yyyy']);
+    rows.push(['Date', 'Long date', { value: dt, format: F.DATE_LONG }, 'd mmmm yyyy']);
+    rows.push(['Date', 'Day-Month-Year', { value: dt, format: F.DATE_DAY_MONTH_YEAR }, 'dd-mm-yyyy']);
+    rows.push(['Date', 'ISO date', { value: dt, format: F.DATE_ISO }, 'yyyy-mm-dd']);
+    rows.push(['Date', 'Month Year', { value: dt, format: F.DATE_MONTH_YEAR }, 'mmmm yyyy']);
+    rows.push(['Date', 'Weekday', { value: dt, format: F.DATE_WEEKDAY }, 'dddd, d mmmm yyyy']);
+    rows.push(['Date', 'Day Month', { value: dt, format: F.DATE_DAY_MONTH }, 'd mmmm']);
+    rows.push(['Date', 'Year only', { value: dt, format: F.DATE_YEAR_ONLY }, 'yyyy']);
+
+    // DateTime formats
+    rows.push([]);
+    rows.push(['DateTime', 'Short DT', { value: dt, format: F.DATETIME_SHORT }, 'dd.mm.yyyy hh:mm']);
+    rows.push(['DateTime', 'Long DT', { value: dt, format: F.DATETIME_LONG }, 'd mmmm yyyy hh:mm:ss']);
+    rows.push(['DateTime', 'Time hh:mm', { value: dt, format: F.TIME_HH_MM }, 'hh:mm']);
+    rows.push(['DateTime', 'Time hh:mm:ss', { value: dt, format: F.TIME_HH_MM_SS }, 'hh:mm:ss']);
+    rows.push(['DateTime', 'Time 12h', { value: dt, format: F.TIME_12H }, 'h:mm AM/PM']);
+    rows.push(['DateTime', '24h DT', { value: dt, format: F.DATETIME_24H }, 'dd.mm.yyyy hh:mm:ss']);
+    rows.push(['DateTime', 'ISO DT', { value: dt, format: F.DATETIME_ISO }, 'yyyy-mm-dd"T"hh:mm:ss']);
+    rows.push(['DateTime', 'Milliseconds', { value: dt, format: F.TIME_MS }, 'hh:mm:ss.000']);
+
+    wb.writeSheet(rows);
+    await wb.finalize();
+    console.log(`✅ Comprehensive format demo: ${OUTPUT_DIR}/comprehensive_formats_demo.xlsb`);
+}
+
+async function main() {
+    console.log('=== SpreadSheet Tasks Format Demo ===\n');
+    await createXlsbFormatDemo();
+    await createXlsxFormatDemo();
+    await createStreamingFormatDemo();
+    await createSalesReportDemo();
+    await createComprehensiveDemo();
+    console.log('\n✅ All format demos generated!');
+    console.log('📁 Open these files in Excel to verify formatting:');
+    console.log(`   ${OUTPUT_DIR}/`);
+}
+
+main().catch(console.error);

package/examples/formats-verify.ts

@@ -0,0 +1,74 @@
+import { XlsbReader } from '../src/XlsbReader';
+import { XlsxReader } from '../src/XlsxReader';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const OUTPUT_DIR = './test-output';
+
+async function verifyFile(filePath: string, label: string) {
+    console.log(`\n--- Verifying: ${label} ---`);
+    const ext = path.extname(filePath).toLowerCase();
+
+    let reader: XlsbReader | XlsxReader;
+    if (ext === '.xlsb') {
+        reader = new XlsbReader();
+    } else {
+        reader = new XlsxReader();
+    }
+
+    await reader.open(filePath);
+
+    const sheetNames = reader.getSheetNames();
+    console.log(`  Sheets: ${sheetNames.join(', ')}`);
+    console.log(`  Rows: ${reader.rowCount}, Cols: ${reader.fieldCount}`);
+
+    const allRows: any[][] = [];
+    const isAsync = ext !== '.xlsb';
+    while (isAsync ? await (reader as XlsxReader).read() : (reader as XlsbReader).read()) {
+        const row: any[] = [];
+        for (let i = 0; i < reader.fieldCount; i++) {
+            row.push(reader.getValue(i));
+        }
+        allRows.push(row);
+    }
+
+    const printCount = Math.min(allRows.length, 15);
+    for (let r = 0; r < printCount; r++) {
+        const row = allRows[r];
+        const vals = row.map((v: any) => {
+            if (v === null || v === undefined) return '';
+            if (v instanceof Date) return v.toISOString();
+            if (typeof v === 'number') return v.toString();
+            return String(v).substring(0, 40);
+        });
+        console.log(`    [${vals.join(', ')}]`);
+    }
+    if (allRows.length > printCount) {
+        console.log(`    ... (${allRows.length - printCount} more rows)`);
+    }
+
+    reader.close();
+    console.log(`  ✅ ${label} - ${allRows.length} rows read`);
+}
+
+async function main() {
+    const files = [
+        { file: `${OUTPUT_DIR}/formats_demo_xlsb.xlsb`, label: 'XLSB Format Demo' },
+        { file: `${OUTPUT_DIR}/formats_demo_xlsx.xlsx`, label: 'XLSX Format Demo' },
+        { file: `${OUTPUT_DIR}/formats_streaming_demo.xlsb`, label: 'XLSB Streaming Demo' },
+        { file: `${OUTPUT_DIR}/sales_report_demo.xlsx`, label: 'Sales Report Demo' },
+        { file: `${OUTPUT_DIR}/comprehensive_formats_demo.xlsb`, label: 'Comprehensive Demo' },
+    ];
+
+    for (const f of files) {
+        if (fs.existsSync(f.file)) {
+            await verifyFile(f.file, f.label);
+        } else {
+            console.log(`\n--- Skipping: ${f.label} (file not found) ---`);
+        }
+    }
+
+    console.log('\n✅ All verifications complete!');
+}
+
+main().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justybase/spreadsheet-tasks",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "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",
@@ -62,9 +62,9 @@
     "@types/node": "^22.10.5",
     "@types/yauzl": "^2.10.3",
     "eslint": "^9.17.0",
-    "exceljs": "^4.4.0",
+    "exceljs": "^3.4.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.7.2",
     "typescript-eslint": "^8.19.1"
   }
-}
+}