‏hucre: موتور اسپردشیت برای TypeScript

hucre یه کتابخانه‌ی اسپردشیت کاملاً خالص TypeScript‌ه که هیچ وابستگی خارجی نداره و می‌تونه توی مرورگر، Node.js، Deno، Bun، و حتی Edge Runtimeها مثل Cloudflare Workers اجرا بشه. با حجم حدود ۱۸ کیلوبایت gzip‌شده، خوندن و نوشتن فرمت‌های XLSX، CSV، ODS، JSON، NDJSON و XML رو پشتیبانی می‌کنه.

شروع کار باهاش خیلی سادست. با readXlsx می‌شه یه فایل اکسل رو خوند و با writeXlsx یه workbook جدید ساخت:

import { readXlsx, writeXlsx } from "hucre"

const workbook = await readXlsx(buffer)
console.log(workbook.sheets[0].rows)

const xlsx = await writeXlsx({
  sheets: [
    {
      name: "Products",
      columns: [
        { header: "Name", key: "name", width: 25 },
        { header: "Price", key: "price", width: 12, numFmt: "$#,##0.00" },
      ],
      data: [{ name: "Widget", price: 9.99, stock: 142 }],
    },
  ],
})

یکی از نقاط قوت hucre اینه که tree-shaking داره؛ یعنی می‌تونی فقط همون بخشی رو که نیاز داری ایمپورت کنی. مثلاً hucre/csv فقط ~۲ کیلوبایت gzip‌شده‌ست. این رویکرد باعث می‌شه حجم نهایی bundle پروژه‌ات خیلی کمتر بشه.

یکی از قابلیت‌های مهمش استریمینگ (Streaming) هست — یعنی پردازش فایل‌های بزرگ ردیف به ردیف، بدون اینکه کل فایل توی حافظه لود بشه. streamXlsxRows یه async generator برمی‌گردونه که ردیف‌ها رو یکی‌یکی تحویل می‌ده. برای نوشتن هم XlsxStreamWriter اجازه می‌ده ردیف‌ها رو به‌صورت تدریجی اضافه کنی و اگه تعداد ردیف‌ها از سقف اکسل (۱,۰۴۸,۵۷۶) رد بشه، به‌صورت خودکار شیت جدید می‌سازه.

در مقایسه با رقباي جاوااسکریپت مثل SheetJS CE و ExcelJS، hucre در چند زمینه برتری داره: ESM‌ نیتیو، پشتیبانی از Edge runtime، بدون eval (یعنی CSP-compliant)، استریمینگ کامل هم برای خوندن هم نوشتن، sparkline، و فرمت‌بندی شرطی کامل — همه رایگان. SheetJS برخی امکانات رو پشت پرداخت قفل کرده و از npm هم حذف شده.

امکانات نوشتن hucre خیلی گسترده‌ست: استایل سلول، عرض خودکار ستون‌ها (با پشتیبانی از کاراکترهای CJK)، سلول‌های ادغام‌شده، freeze pane، فیلتر خودکار، validation داده، هایپرلینک، تصویر، کامنت، جداول، فرمت‌بندی شرطی، named range، تنظیمات چاپ، محافظت از شیت، rich text، فرمول، sparkline و حتی checkbox‌های native اکسل ۲۰۲۴.

نکات کلیدی:

• بدون وابستگی خارجی، حجم ~۱۸ کیلوبایت gzip
• پشتیبانی از XLSX، CSV، ODS، JSON، NDJSON، XML
• استریمینگ کامل برای خوندن و نوشتن فایل‌های بزرگ
• tree-shaking برای کاهش حجم bundle
• سازگار با Edge Runtime، مرورگر، Node.js، Deno و Bun
• قابلیت‌هایی مثل sparkline و فرمت‌بندی شرطی که در رقبا پولیه