{"_id":"@bilig/excel-import","name":"@bilig/excel-import","dist-tags":{"latest":"0.14.14"},"versions":{"0.14.14":{"name":"@bilig/excel-import","version":"0.14.14","description":"CSV/XLSX workbook snapshot import and supported XLSX export helpers for bilig.","keywords":["bilig","excel","export","import","spreadsheet","xlsx"],"homepage":"https://github.com/proompteng/bilig/tree/main/packages/excel-import#readme","bugs":{"url":"https://github.com/proompteng/bilig/issues"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/proompteng/bilig.git","directory":"packages/excel-import"},"type":"module","sideEffects":false,"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.json"},"dependencies":{"@bilig/core":"0.14.14","@bilig/formula":"0.14.14","@bilig/protocol":"0.14.14","fast-xml-parser":"5.7.3","fflate":"0.3.11","xlsx":"https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz","xlsx-js-style":"1.2.0"},"engines":{"node":">=24.0.0"},"_id":"@bilig/excel-import@0.14.14","_integrity":"sha512-JkLEggpXbFlcn7NsSNgOMd5JFE5BIPC24wC0KzKHcRnKpKnCIlzYa9sUyf5iTAfzEcc0WEPjh5aha91/aUedUw==","_resolved":"/Users/gregkonush/github.com/bilig4/build/npm-packages-runtime/bilig-excel-import-0.14.14.tgz","_from":"file:build/npm-packages-runtime/bilig-excel-import-0.14.14.tgz","_nodeVersion":"26.0.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-JkLEggpXbFlcn7NsSNgOMd5JFE5BIPC24wC0KzKHcRnKpKnCIlzYa9sUyf5iTAfzEcc0WEPjh5aha91/aUedUw==","shasum":"1661a6190e8c929acc26144cbcf14de74cde14d9","tarball":"https://registry.npmjs.org/@bilig/excel-import/-/excel-import-0.14.14.tgz","fileCount":198,"unpackedSize":1398295,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHi/JvGu5mLMsPLVc4SnBowG6tEeJfGQ0wV1FcUguHLtAiBdxrahx6Nt6+XBbTs5Kt39SBKuCe/lDma6UaBje3zQMA=="}]},"_npmUser":{"name":"kalmyk","email":"gkonushev@gmail.com"},"directories":{},"maintainers":[{"name":"kalmyk","email":"gkonushev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/excel-import_0.14.14_1778806916677_0.9602578070628582"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-15T01:01:56.544Z","0.14.14":"2026-05-15T01:01:56.890Z","modified":"2026-05-15T01:01:57.114Z"},"maintainers":[{"name":"kalmyk","email":"gkonushev@gmail.com"}],"description":"CSV/XLSX workbook snapshot import and supported XLSX export helpers for bilig.","homepage":"https://github.com/proompteng/bilig/tree/main/packages/excel-import#readme","keywords":["bilig","excel","export","import","spreadsheet","xlsx"],"repository":{"type":"git","url":"git+https://github.com/proompteng/bilig.git","directory":"packages/excel-import"},"bugs":{"url":"https://github.com/proompteng/bilig/issues"},"license":"MIT","readme":"# @bilig/excel-import\n\nCSV/XLSX-to-`WorkbookSnapshot` import helpers and supported-subset XLSX export helpers for bilig.\n\n## Package Status\n\nThis package is part of the `bilig` runtime npm package set. Install it with\n`@bilig/headless` when a Node project needs XLSX import, WorkPaper calculation,\nand XLSX export from the same public package path.\n\n```sh\npnpm add @bilig/headless @bilig/excel-import\n```\n\nFor a clean first-time smoke test in an empty project:\n\n```sh\nmkdir bilig-xlsx-smoke && cd bilig-xlsx-smoke\nnpm init -y\npnpm add @bilig/headless @bilig/excel-import\npnpm dlx tsx smoke.ts\n```\n\nUse this `smoke.ts`:\n\n```ts\nimport { WorkPaper } from '@bilig/headless'\nimport { exportXlsx, importXlsx } from '@bilig/excel-import'\n\nconst source = WorkPaper.buildFromSheets({\n  Inputs: [\n    ['Metric', 'Value'],\n    ['Customers', 20],\n    ['Average revenue', 1200],\n  ],\n  Summary: [\n    ['Metric', 'Value'],\n    ['Revenue', '=Inputs!B2*Inputs!B3'],\n  ],\n})\n\nconst xlsxBytes = exportXlsx(source.exportSnapshot())\nsource.dispose()\n\nconst imported = importXlsx(xlsxBytes, 'revenue-model.xlsx')\nconst workbook = WorkPaper.buildFromSnapshot(imported.snapshot, {\n  evaluationTimeoutMs: 30_000,\n  useColumnIndex: true,\n})\n\nconst inputs = requireSheet(workbook, 'Inputs')\nconst summary = requireSheet(workbook, 'Summary')\nconst before = numberValue(workbook.getCellValue({ sheet: summary, row: 1, col: 1 }))\nworkbook.setCellContents({ sheet: inputs, row: 1, col: 1 }, 32)\nconst after = numberValue(workbook.getCellValue({ sheet: summary, row: 1, col: 1 }))\nconst roundTrip = importXlsx(exportXlsx(workbook.exportSnapshot()), 'revenue-model-edited.xlsx')\nworkbook.dispose()\n\nif (before !== 24000 || after !== 38400 || roundTrip.snapshot.sheets.length !== 2) {\n  throw new Error(`Unexpected XLSX roundtrip: ${JSON.stringify({ before, after, sheets: roundTrip.snapshot.sheets.length })}`)\n}\n\nconsole.log({ before, after, sheets: roundTrip.snapshot.sheets.map((sheet) => sheet.name) })\n\nfunction requireSheet(workpaper: ReturnType<typeof WorkPaper.buildFromSnapshot>, sheetName: string): number {\n  const sheet = workpaper.getSheetId(sheetName)\n  if (sheet === undefined) {\n    throw new Error(`Expected sheet \"${sheetName}\" to exist`)\n  }\n  return sheet\n}\n\nfunction numberValue(cell: unknown): number {\n  const value = typeof cell === 'object' && cell !== null && 'value' in cell ? cell.value : undefined\n  if (typeof value === 'number') {\n    return value\n  }\n  throw new Error(`Expected numeric cell value, got ${JSON.stringify(cell)}`)\n}\n```\n\nRepository development:\n\n```sh\npnpm install\npnpm --filter @bilig/excel-import build\npnpm exec vitest run packages/excel-import/src/__tests__/excel-import.test.ts\n```\n\n## XLSX To WorkPaper\n\n```ts\nimport { readFileSync, writeFileSync } from 'node:fs'\nimport { WorkPaper } from '@bilig/headless'\nimport { exportXlsx, importXlsx } from '@bilig/excel-import'\n\nconst imported = importXlsx(new Uint8Array(readFileSync('model.xlsx')), 'model.xlsx')\nconst workbook = WorkPaper.buildFromSnapshot(imported.snapshot, {\n  evaluationTimeoutMs: 30_000,\n  useColumnIndex: true,\n})\n\nconst firstSheetName = imported.snapshot.sheets[0]?.name\nconst firstSheet = firstSheetName === undefined ? undefined : workbook.getSheetId(firstSheetName)\nif (firstSheet === undefined) throw new Error('Workbook has no sheets')\n\nworkbook.setCellContents({ sheet: firstSheet, row: 1, col: 1 }, 150_000)\nconst recalculated = workbook.getCellDisplayValue({ sheet: firstSheet, row: 1, col: 1 })\n\nwriteFileSync('model-edited.xlsx', exportXlsx(workbook.exportSnapshot()))\nworkbook.dispose()\n\nconsole.log({ recalculated })\n```\n\nUse `WorkPaper.buildFromSnapshot()` for imported XLSX files. It preserves the\nworkbook metadata that Excel formulas need, including defined names, table\nmetadata, and structured-reference translations. `WorkPaper.buildFromSheets()`\nis intentionally metadata-free. Use `workbook.exportSnapshot()` with\n`exportXlsx()` when exporting a WorkPaper after edits.\n\nLiteral Excel error cells such as `#N/A`, `#DIV/0!`, `#REF!`, and `#VALUE!`\nare imported as their display text instead of SheetJS numeric error codes.\n\nHidden XLSX rows and columns are preserved in workbook metadata and exported\nback into worksheet XML, including hidden column states attached to width\nmetadata.\n\nWorkbook calculation properties such as iterative calculation, iteration count\nand delta, forced recalculation, concurrent calculation, and manual calculation\nmode are preserved from XLSX `<calcPr>` metadata on roundtrip.\n\nWorksheet protection elements preserve non-default XML attributes from source\nworkbooks, so protected sheets are not normalized into a different\n`<sheetProtection sheet=\"1\"/>` state during no-op roundtrips.\n\nWorksheet printer settings preserve binary `xl/printerSettings/*.bin` parts,\nworksheet relationships, and `pageSetup` relationship links during no-op XLSX\nroundtrips.\n\nWorksheet `<sheetPr>` properties preserve non-tabColor code names,\n`outlinePr`, and `pageSetUpPr` metadata during no-op XLSX roundtrips.\n\nWorkbook sheet visibility preserves hidden and very hidden worksheet state\nduring no-op XLSX roundtrips.\n\nCell hyperlinks preserve external URL targets, internal workbook targets,\ntooltips, and display text during no-op XLSX roundtrips.\n\n## CSV Import\n\n```ts\nimport { importCsv } from '@bilig/excel-import'\n\nconst imported = importCsv('Account;Amount\\n4000;125,50', 'ledger.csv', {\n  delimiter: ';',\n  decimalSeparator: ',',\n})\n```\n\nCSV import auto-detects comma, semicolon, and tab delimiters. Semicolon and tab\nexports that contain decimal-comma values are parsed as locale accounting CSV by\ndefault; pass explicit options when the source format is known. Integer-looking\nfields with leading zeros are kept as text so account numbers, routing numbers,\ninvoice IDs, and similar identifiers are not silently changed.\n","readmeFilename":"README.md","_rev":"1-931fed619bb7ee5e07ff1029ef6305ef"}