@js-ak/excel-toolbox 1.3.2 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/build/cjs/lib/template/template-fs.js +678 -197
  2. package/build/cjs/lib/template/utils/apply-replacements.js +26 -0
  3. package/build/cjs/lib/template/utils/check-row.js +6 -11
  4. package/build/cjs/lib/template/utils/column-index-to-letter.js +14 -3
  5. package/build/cjs/lib/template/utils/extract-xml-declaration.js +22 -0
  6. package/build/cjs/lib/template/utils/get-by-path.js +18 -0
  7. package/build/cjs/lib/template/utils/index.js +5 -0
  8. package/build/cjs/lib/template/utils/update-dimension.js +40 -0
  9. package/build/cjs/lib/template/utils/validate-worksheet-xml.js +217 -0
  10. package/build/cjs/lib/zip/create-with-stream.js +2 -2
  11. package/build/esm/lib/template/template-fs.js +678 -197
  12. package/build/esm/lib/template/utils/apply-replacements.js +22 -0
  13. package/build/esm/lib/template/utils/check-row.js +6 -11
  14. package/build/esm/lib/template/utils/column-index-to-letter.js +14 -3
  15. package/build/esm/lib/template/utils/extract-xml-declaration.js +19 -0
  16. package/build/esm/lib/template/utils/get-by-path.js +15 -0
  17. package/build/esm/lib/template/utils/index.js +5 -0
  18. package/build/esm/lib/template/utils/update-dimension.js +37 -0
  19. package/build/esm/lib/template/utils/validate-worksheet-xml.js +214 -0
  20. package/build/esm/lib/zip/create-with-stream.js +2 -2
  21. package/build/types/lib/template/template-fs.d.ts +24 -0
  22. package/build/types/lib/template/utils/apply-replacements.d.ts +13 -0
  23. package/build/types/lib/template/utils/check-row.d.ts +5 -10
  24. package/build/types/lib/template/utils/column-index-to-letter.d.ts +11 -3
  25. package/build/types/lib/template/utils/extract-xml-declaration.d.ts +14 -0
  26. package/build/types/lib/template/utils/get-by-path.d.ts +8 -0
  27. package/build/types/lib/template/utils/index.d.ts +5 -0
  28. package/build/types/lib/template/utils/update-dimension.d.ts +1 -0
  29. package/build/types/lib/template/utils/validate-worksheet-xml.d.ts +9 -0
  30. package/package.json +6 -4
@@ -0,0 +1,22 @@
1
+ import { getByPath } from "./get-by-path.js";
2
+ /**
3
+ * Replaces placeholders in the given content string with values from the replacements map.
4
+ *
5
+ * The function searches for placeholders in the format `${key}` within the content
6
+ * string, where `key` corresponds to a path in the replacements object.
7
+ * If a value is found for the key, it replaces the placeholder with the value.
8
+ * If no value is found, the original placeholder remains unchanged.
9
+ *
10
+ * @param content - The string containing placeholders to be replaced.
11
+ * @param replacements - An object where keys represent placeholder paths and values are the replacements.
12
+ * @returns A new string with placeholders replaced by corresponding values from the replacements object.
13
+ */
14
+ export const applyReplacements = (content, replacements) => {
15
+ if (!content) {
16
+ return "";
17
+ }
18
+ return content.replace(/\$\{([^}]+)\}/g, (match, path) => {
19
+ const value = getByPath(replacements, path);
20
+ return value !== undefined ? String(value) : match;
21
+ });
22
+ };
@@ -1,19 +1,14 @@
1
1
  /**
2
- * Validates that each key in the given row object is a valid cell reference.
2
+ * Validates an object representing a single row of data to ensure that its keys
3
+ * are valid Excel column references. Throws an error if any of the keys are
4
+ * invalid.
3
5
  *
4
- * This function checks that all keys in the provided row object are composed
5
- * only of column letters (A-Z, case insensitive). If a key is found that does
6
- * not match this pattern, an error is thrown with a message indicating the
7
- * invalid cell reference.
8
- *
9
- * @param row - An object representing a row of data, where keys are cell
10
- * references and values are strings.
11
- *
12
- * @throws {Error} If any key in the row is not a valid column letter.
6
+ * @param row An object with string keys that represent the cell references and
7
+ * string values that represent the values of those cells.
13
8
  */
14
9
  export function checkRow(row) {
15
10
  for (const key of Object.keys(row)) {
16
- if (!/^[A-Z]+$/i.test(key)) {
11
+ if (!/^[A-Z]+$/i.test(key) || !/^[A-Z]$|^[A-Z][A-Z]$|^[A-Z][A-Z][A-Z]$/i.test(key)) {
17
12
  throw new Error(`Invalid cell reference "${key}" in row. Only column letters (like "A", "B", "C") are allowed.`);
18
13
  }
19
14
  }
@@ -1,10 +1,21 @@
1
1
  /**
2
- * Converts a 0-based column index to an Excel-style letter (A, B, ..., Z, AA, AB, ...).
2
+ * Converts a zero-based column index to its corresponding Excel column letter.
3
3
  *
4
- * @param index - The 0-based column index.
5
- * @returns The Excel-style letter for the given column index.
4
+ * @throws Will throw an error if the input is not a positive integer.
5
+ * @param {number} index - The zero-based index of the column to convert.
6
+ * @returns {string} The corresponding Excel column letter.
7
+ *
8
+ * @example
9
+ * columnIndexToLetter(0); // returns "A"
10
+ * columnIndexToLetter(25); // returns "Z"
11
+ * columnIndexToLetter(26); // returns "AA"
12
+ * columnIndexToLetter(51); // returns "AZ"
13
+ * columnIndexToLetter(52); // returns "BA"
6
14
  */
7
15
  export function columnIndexToLetter(index) {
16
+ if (!Number.isInteger(index) || index < 0) {
17
+ throw new Error(`Invalid column index: ${index}. Must be a positive integer.`);
18
+ }
8
19
  let letters = "";
9
20
  while (index >= 0) {
10
21
  letters = String.fromCharCode((index % 26) + 65) + letters;
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Extracts the XML declaration from a given XML string.
3
+ *
4
+ * The XML declaration is a string that looks like `<?xml ...?>` and is usually
5
+ * present at the beginning of an XML file. It contains information about the
6
+ * XML version, encoding, and standalone status.
7
+ *
8
+ * This function returns `null` if the input string does not have a valid XML
9
+ * declaration.
10
+ *
11
+ * @param xmlString - The XML string to extract the declaration from.
12
+ * @returns The extracted XML declaration string, or `null`.
13
+ */
14
+ export function extractXmlDeclaration(xmlString) {
15
+ // const declarationRegex = /^<\?xml\s+[^?]+\?>/;
16
+ const declarationRegex = /^<\?xml\s+version\s*=\s*["'][^"']+["'](\s+(encoding|standalone)\s*=\s*["'][^"']+["'])*\s*\?>/;
17
+ const match = xmlString.match(declarationRegex);
18
+ return match ? match[0] : null;
19
+ }
@@ -0,0 +1,15 @@
1
+ /**
2
+ * Gets a value from an object by a given path.
3
+ *
4
+ * @param obj - The object to search.
5
+ * @param path - The path to the value, separated by dots.
6
+ * @returns The value at the given path, or undefined if not found.
7
+ */
8
+ export function getByPath(obj, path) {
9
+ return path.split(".").reduce((acc, key) => {
10
+ if (acc && typeof acc === "object" && key in acc) {
11
+ return acc[key];
12
+ }
13
+ return undefined;
14
+ }, obj);
15
+ }
@@ -1,11 +1,16 @@
1
+ export * from "./apply-replacements.js";
1
2
  export * from "./check-row.js";
2
3
  export * from "./check-rows.js";
3
4
  export * from "./check-start-row.js";
4
5
  export * from "./column-index-to-letter.js";
5
6
  export * from "./escape-xml.js";
7
+ export * from "./extract-xml-declaration.js";
8
+ export * from "./get-by-path.js";
6
9
  export * from "./get-max-row-number.js";
7
10
  export * from "./get-rows-above.js";
8
11
  export * from "./get-rows-below.js";
9
12
  export * from "./parse-rows.js";
10
13
  export * from "./to-excel-column-object.js";
14
+ export * from "./update-dimension.js";
15
+ export * from "./validate-worksheet-xml.js";
11
16
  export * from "./write-rows-to-stream.js";
@@ -0,0 +1,37 @@
1
+ export function updateDimension(xml) {
2
+ const cellRefs = [...xml.matchAll(/<c r="([A-Z]+)(\d+)"/g)];
3
+ if (cellRefs.length === 0)
4
+ return xml;
5
+ let minCol = Infinity, maxCol = -Infinity;
6
+ let minRow = Infinity, maxRow = -Infinity;
7
+ for (const [, colStr, rowStr] of cellRefs) {
8
+ const col = columnLetterToNumber(colStr);
9
+ const row = parseInt(rowStr, 10);
10
+ if (col < minCol)
11
+ minCol = col;
12
+ if (col > maxCol)
13
+ maxCol = col;
14
+ if (row < minRow)
15
+ minRow = row;
16
+ if (row > maxRow)
17
+ maxRow = row;
18
+ }
19
+ const newRef = `${columnNumberToLetter(minCol)}${minRow}:${columnNumberToLetter(maxCol)}${maxRow}`;
20
+ return xml.replace(/<dimension ref="[^"]*"/, `<dimension ref="${newRef}"`);
21
+ }
22
+ function columnLetterToNumber(letters) {
23
+ let num = 0;
24
+ for (let i = 0; i < letters.length; i++) {
25
+ num = num * 26 + (letters.charCodeAt(i) - 64);
26
+ }
27
+ return num;
28
+ }
29
+ function columnNumberToLetter(num) {
30
+ let letters = "";
31
+ while (num > 0) {
32
+ const rem = (num - 1) % 26;
33
+ letters = String.fromCharCode(65 + rem) + letters;
34
+ num = Math.floor((num - 1) / 26);
35
+ }
36
+ return letters;
37
+ }
@@ -0,0 +1,214 @@
1
+ export function validateWorksheetXml(xml) {
2
+ const createError = (message, details) => ({
3
+ error: {
4
+ details,
5
+ message,
6
+ },
7
+ isValid: false,
8
+ });
9
+ // 1. Проверка базовой структуры XML
10
+ if (!xml.startsWith("<?xml")) {
11
+ return createError("XML должен начинаться с декларации <?xml>");
12
+ }
13
+ if (!xml.includes("<worksheet") || !xml.includes("</worksheet>")) {
14
+ return createError("Не найден корневой элемент worksheet");
15
+ }
16
+ // 2. Проверка наличия обязательных элементов
17
+ const requiredElements = [
18
+ { name: "sheetViews", tag: "<sheetViews>" },
19
+ { name: "sheetFormatPr", tag: "<sheetFormatPr" },
20
+ { name: "cols", tag: "<cols>" },
21
+ { name: "sheetData", tag: "<sheetData>" },
22
+ { name: "mergeCells", tag: "<mergeCells" },
23
+ ];
24
+ for (const { name, tag } of requiredElements) {
25
+ if (!xml.includes(tag)) {
26
+ return createError(`Отсутствует обязательный элемент ${name}`);
27
+ }
28
+ }
29
+ // 3. Извлечение и проверка sheetData
30
+ const sheetDataStart = xml.indexOf("<sheetData>");
31
+ const sheetDataEnd = xml.indexOf("</sheetData>");
32
+ if (sheetDataStart === -1 || sheetDataEnd === -1) {
33
+ return createError("Некорректная структура sheetData");
34
+ }
35
+ const sheetDataContent = xml.substring(sheetDataStart + 10, sheetDataEnd);
36
+ const rows = sheetDataContent.split("</row>");
37
+ if (rows.length < 2) {
38
+ return createError("SheetData должен содержать хотя бы одну строку");
39
+ }
40
+ // Собираем информацию о всех строках и ячейках
41
+ const allRows = [];
42
+ const allCells = [];
43
+ let prevRowNum = 0;
44
+ for (const row of rows.slice(0, -1)) {
45
+ if (!row.includes("<row ")) {
46
+ return createError("Не найден тег row", `Фрагмент: ${row.substring(0, 50)}...`);
47
+ }
48
+ if (!row.includes("<c ")) {
49
+ return createError("Строка не содержит ячеек", `Строка: ${row.substring(0, 50)}...`);
50
+ }
51
+ // Извлекаем номер строки
52
+ const rowNumMatch = row.match(/<row\s+r="(\d+)"/);
53
+ if (!rowNumMatch) {
54
+ return createError("Не указан номер строки (атрибут r)", `Строка: ${row.substring(0, 50)}...`);
55
+ }
56
+ const rowNum = parseInt(rowNumMatch[1]);
57
+ // Проверка уникальности строк
58
+ if (allRows.includes(rowNum)) {
59
+ return createError("Найден дубликат номера строки", `Номер строки: ${rowNum}`);
60
+ }
61
+ allRows.push(rowNum);
62
+ // Проверка порядка строк (должны идти по возрастанию)
63
+ if (rowNum <= prevRowNum) {
64
+ return createError("Нарушен порядок следования строк", `Текущая строка: ${rowNum}, предыдущая: ${prevRowNum}`);
65
+ }
66
+ prevRowNum = rowNum;
67
+ // Извлекаем все ячейки в строке
68
+ const cells = row.match(/<c\s+r="([A-Z]+)(\d+)"/g) || [];
69
+ for (const cell of cells) {
70
+ const match = cell.match(/<c\s+r="([A-Z]+)(\d+)"/);
71
+ if (!match) {
72
+ return createError("Некорректный формат ячейки", `Ячейка: ${cell}`);
73
+ }
74
+ const col = match[1];
75
+ const cellRowNum = parseInt(match[2]);
76
+ // Проверяем соответствие номера строки
77
+ if (cellRowNum !== rowNum) {
78
+ return createError("Несоответствие номера строки в ячейке", `Ожидалось: ${rowNum}, найдено: ${cellRowNum} в ячейке ${col}${cellRowNum}`);
79
+ }
80
+ allCells.push({
81
+ col,
82
+ row: rowNum,
83
+ });
84
+ }
85
+ }
86
+ // 4. Проверка mergeCells
87
+ const mergeCellsStart = xml.indexOf("<mergeCells");
88
+ const mergeCellsEnd = xml.indexOf("</mergeCells>");
89
+ if (mergeCellsStart === -1 || mergeCellsEnd === -1) {
90
+ return createError("Некорректная структура mergeCells");
91
+ }
92
+ const mergeCellsContent = xml.substring(mergeCellsStart, mergeCellsEnd);
93
+ const countMatch = mergeCellsContent.match(/count="(\d+)"/);
94
+ if (!countMatch) {
95
+ return createError("Не указано количество объединенных ячеек (атрибут count)");
96
+ }
97
+ const mergeCellTags = mergeCellsContent.match(/<mergeCell\s+ref="([A-Z]+\d+:[A-Z]+\d+)"\s*\/>/g);
98
+ if (!mergeCellTags) {
99
+ return createError("Не найдены объединенные ячейки");
100
+ }
101
+ // Проверка соответствия заявленного количества и фактического
102
+ if (mergeCellTags.length !== parseInt(countMatch[1])) {
103
+ return createError("Несоответствие количества объединенных ячеек", `Ожидалось: ${countMatch[1]}, найдено: ${mergeCellTags.length}`);
104
+ }
105
+ // Проверка на дублирующиеся mergeCell
106
+ const mergeRefs = new Set();
107
+ const duplicates = new Set();
108
+ for (const mergeTag of mergeCellTags) {
109
+ const refMatch = mergeTag.match(/ref="([A-Z]+\d+:[A-Z]+\d+)"/);
110
+ if (!refMatch) {
111
+ return createError("Некорректный формат объединения ячеек", `Тег: ${mergeTag}`);
112
+ }
113
+ const ref = refMatch[1];
114
+ if (mergeRefs.has(ref)) {
115
+ duplicates.add(ref);
116
+ }
117
+ else {
118
+ mergeRefs.add(ref);
119
+ }
120
+ }
121
+ if (duplicates.size > 0) {
122
+ return createError("Найдены дублирующиеся объединения ячеек", `Дубликаты: ${Array.from(duplicates).join(", ")}`);
123
+ }
124
+ // Проверка пересекающихся объединений
125
+ const mergedRanges = Array.from(mergeRefs).map(ref => {
126
+ const [start, end] = ref.split(":");
127
+ return {
128
+ endCol: end.match(/[A-Z]+/)?.[0] || "",
129
+ endRow: parseInt(end.match(/\d+/)?.[0] || "0"),
130
+ startCol: start.match(/[A-Z]+/)?.[0] || "",
131
+ startRow: parseInt(start.match(/\d+/)?.[0] || "0"),
132
+ };
133
+ });
134
+ for (let i = 0; i < mergedRanges.length; i++) {
135
+ for (let j = i + 1; j < mergedRanges.length; j++) {
136
+ const a = mergedRanges[i];
137
+ const b = mergedRanges[j];
138
+ if (rangesIntersect(a, b)) {
139
+ return createError("Найдены пересекающиеся объединения ячеек", `Пересекаются: ${getRangeString(a)} и ${getRangeString(b)}`);
140
+ }
141
+ }
142
+ }
143
+ // 5. Проверка dimension и соответствия с реальными данными
144
+ const dimensionMatch = xml.match(/<dimension\s+ref="([A-Z]+\d+:[A-Z]+\d+)"\s*\/>/);
145
+ if (!dimensionMatch) {
146
+ return createError("Не указана область данных (dimension)");
147
+ }
148
+ const [startCell, endCell] = dimensionMatch[1].split(":");
149
+ const startCol = startCell.match(/[A-Z]+/)?.[0];
150
+ const startRow = parseInt(startCell.match(/\d+/)?.[0] || "0");
151
+ const endCol = endCell.match(/[A-Z]+/)?.[0];
152
+ const endRow = parseInt(endCell.match(/\d+/)?.[0] || "0");
153
+ if (!startCol || !endCol || isNaN(startRow) || isNaN(endRow)) {
154
+ return createError("Некорректный формат dimension", `Dimension: ${dimensionMatch[1]}`);
155
+ }
156
+ const startColNum = colToNumber(startCol);
157
+ const endColNum = colToNumber(endCol);
158
+ // Проверяем все ячейки на вхождение в dimension
159
+ for (const cell of allCells) {
160
+ const colNum = colToNumber(cell.col);
161
+ if (cell.row < startRow || cell.row > endRow) {
162
+ return createError("Ячейка находится вне указанной области (по строке)", `Ячейка: ${cell.col}${cell.row}, dimension: ${dimensionMatch[1]}`);
163
+ }
164
+ if (colNum < startColNum || colNum > endColNum) {
165
+ return createError("Ячейка находится вне указанной области (по столбцу)", `Ячейка: ${cell.col}${cell.row}, dimension: ${dimensionMatch[1]}`);
166
+ }
167
+ }
168
+ // 6. Дополнительная проверка: все mergeCell ссылаются на существующие ячейки
169
+ for (const mergeTag of mergeCellTags) {
170
+ const refMatch = mergeTag.match(/ref="([A-Z]+\d+:[A-Z]+\d+)"/);
171
+ if (!refMatch) {
172
+ return createError("Некорректный формат объединения ячеек", `Тег: ${mergeTag}`);
173
+ }
174
+ const [cell1, cell2] = refMatch[1].split(":");
175
+ const cell1Col = cell1.match(/[A-Z]+/)?.[0];
176
+ const cell1Row = parseInt(cell1.match(/\d+/)?.[0] || "0");
177
+ const cell2Col = cell2.match(/[A-Z]+/)?.[0];
178
+ const cell2Row = parseInt(cell2.match(/\d+/)?.[0] || "0");
179
+ if (!cell1Col || !cell2Col || isNaN(cell1Row) || isNaN(cell2Row)) {
180
+ return createError("Некорректные координаты объединения ячеек", `Объединение: ${refMatch[1]}`);
181
+ }
182
+ // Проверяем что объединяемые ячейки существуют
183
+ const cell1Exists = allCells.some(c => c.row === cell1Row && c.col === cell1Col);
184
+ const cell2Exists = allCells.some(c => c.row === cell2Row && c.col === cell2Col);
185
+ if (!cell1Exists || !cell2Exists) {
186
+ return createError("Объединение ссылается на несуществующие ячейки", `Объединение: ${refMatch[1]}, отсутствует: ${!cell1Exists ? `${cell1Col}${cell1Row}` : `${cell2Col}${cell2Row}`}`);
187
+ }
188
+ }
189
+ return { isValid: true };
190
+ }
191
+ // Вспомогательные функции для проверки пересечений
192
+ function rangesIntersect(a, b) {
193
+ const aStartColNum = colToNumber(a.startCol);
194
+ const aEndColNum = colToNumber(a.endCol);
195
+ const bStartColNum = colToNumber(b.startCol);
196
+ const bEndColNum = colToNumber(b.endCol);
197
+ // Проверяем пересечение по строкам
198
+ const rowsIntersect = !(a.endRow < b.startRow || a.startRow > b.endRow);
199
+ // Проверяем пересечение по колонкам
200
+ const colsIntersect = !(aEndColNum < bStartColNum || aStartColNum > bEndColNum);
201
+ return rowsIntersect && colsIntersect;
202
+ }
203
+ function getRangeString(range) {
204
+ return `${range.startCol}${range.startRow}:${range.endCol}${range.endRow}`;
205
+ }
206
+ // Функция для преобразования букв колонки в число
207
+ function colToNumber(col) {
208
+ let num = 0;
209
+ for (let i = 0; i < col.length; i++) {
210
+ num = num * 26 + (col.charCodeAt(i) - 64);
211
+ }
212
+ return num;
213
+ }
214
+ ;
@@ -52,9 +52,9 @@ export async function createWithStream(fileKeys, destination, output) {
52
52
  });
53
53
  const collectCompressed = new PassThrough();
54
54
  collectCompressed.on("data", chunk => {
55
- // // Count compressed bytes
55
+ // Count compressed bytes
56
56
  compSize += chunk.length;
57
- // // Save compressed chunk
57
+ // Save compressed chunk
58
58
  compressedChunks.push(chunk);
59
59
  });
60
60
  // Run all transforms in pipeline: read -> count size -> CRC -> deflate -> collect compressed
@@ -29,6 +29,30 @@ export declare class TemplateFs {
29
29
  * @experimental This API is experimental and might change in future versions.
30
30
  */
31
31
  constructor(fileKeys: Set<string>, destination: string);
32
+ /**
33
+ * Copies a sheet from the template to a new name.
34
+ *
35
+ * @param {string} sourceName - The name of the sheet to copy.
36
+ * @param {string} newName - The new name for the sheet.
37
+ * @returns {Promise<void>}
38
+ * @throws {Error} If the sheet with the source name does not exist.
39
+ * @throws {Error} If a sheet with the new name already exists.
40
+ * @experimental This API is experimental and might change in future versions.
41
+ */
42
+ copySheet(sourceName: string, newName: string): Promise<void>;
43
+ /**
44
+ * Replaces placeholders in the given sheet with values from the replacements map.
45
+ *
46
+ * The function searches for placeholders in the format `${key}` within the sheet
47
+ * content, where `key` corresponds to a path in the replacements object.
48
+ * If a value is found for the key, it replaces the placeholder with the value.
49
+ * If no value is found, the original placeholder remains unchanged.
50
+ *
51
+ * @param sheetName - The name of the sheet to be replaced.
52
+ * @param replacements - An object where keys represent placeholder paths and values are the replacements.
53
+ * @returns A promise that resolves when the substitution is complete.
54
+ */
55
+ substitute(sheetName: string, replacements: Record<string, unknown>): Promise<void>;
32
56
  /**
33
57
  * Inserts rows into a specific sheet in the template.
34
58
  *
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Replaces placeholders in the given content string with values from the replacements map.
3
+ *
4
+ * The function searches for placeholders in the format `${key}` within the content
5
+ * string, where `key` corresponds to a path in the replacements object.
6
+ * If a value is found for the key, it replaces the placeholder with the value.
7
+ * If no value is found, the original placeholder remains unchanged.
8
+ *
9
+ * @param content - The string containing placeholders to be replaced.
10
+ * @param replacements - An object where keys represent placeholder paths and values are the replacements.
11
+ * @returns A new string with placeholders replaced by corresponding values from the replacements object.
12
+ */
13
+ export declare const applyReplacements: (content: string, replacements: Record<string, unknown>) => string;
@@ -1,14 +1,9 @@
1
1
  /**
2
- * Validates that each key in the given row object is a valid cell reference.
2
+ * Validates an object representing a single row of data to ensure that its keys
3
+ * are valid Excel column references. Throws an error if any of the keys are
4
+ * invalid.
3
5
  *
4
- * This function checks that all keys in the provided row object are composed
5
- * only of column letters (A-Z, case insensitive). If a key is found that does
6
- * not match this pattern, an error is thrown with a message indicating the
7
- * invalid cell reference.
8
- *
9
- * @param row - An object representing a row of data, where keys are cell
10
- * references and values are strings.
11
- *
12
- * @throws {Error} If any key in the row is not a valid column letter.
6
+ * @param row An object with string keys that represent the cell references and
7
+ * string values that represent the values of those cells.
13
8
  */
14
9
  export declare function checkRow(row: Record<string, string>): void;
@@ -1,7 +1,15 @@
1
1
  /**
2
- * Converts a 0-based column index to an Excel-style letter (A, B, ..., Z, AA, AB, ...).
2
+ * Converts a zero-based column index to its corresponding Excel column letter.
3
3
  *
4
- * @param index - The 0-based column index.
5
- * @returns The Excel-style letter for the given column index.
4
+ * @throws Will throw an error if the input is not a positive integer.
5
+ * @param {number} index - The zero-based index of the column to convert.
6
+ * @returns {string} The corresponding Excel column letter.
7
+ *
8
+ * @example
9
+ * columnIndexToLetter(0); // returns "A"
10
+ * columnIndexToLetter(25); // returns "Z"
11
+ * columnIndexToLetter(26); // returns "AA"
12
+ * columnIndexToLetter(51); // returns "AZ"
13
+ * columnIndexToLetter(52); // returns "BA"
6
14
  */
7
15
  export declare function columnIndexToLetter(index: number): string;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Extracts the XML declaration from a given XML string.
3
+ *
4
+ * The XML declaration is a string that looks like `<?xml ...?>` and is usually
5
+ * present at the beginning of an XML file. It contains information about the
6
+ * XML version, encoding, and standalone status.
7
+ *
8
+ * This function returns `null` if the input string does not have a valid XML
9
+ * declaration.
10
+ *
11
+ * @param xmlString - The XML string to extract the declaration from.
12
+ * @returns The extracted XML declaration string, or `null`.
13
+ */
14
+ export declare function extractXmlDeclaration(xmlString: string): string | null;
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Gets a value from an object by a given path.
3
+ *
4
+ * @param obj - The object to search.
5
+ * @param path - The path to the value, separated by dots.
6
+ * @returns The value at the given path, or undefined if not found.
7
+ */
8
+ export declare function getByPath(obj: unknown, path: string): unknown;
@@ -1,11 +1,16 @@
1
+ export * from "./apply-replacements.js";
1
2
  export * from "./check-row.js";
2
3
  export * from "./check-rows.js";
3
4
  export * from "./check-start-row.js";
4
5
  export * from "./column-index-to-letter.js";
5
6
  export * from "./escape-xml.js";
7
+ export * from "./extract-xml-declaration.js";
8
+ export * from "./get-by-path.js";
6
9
  export * from "./get-max-row-number.js";
7
10
  export * from "./get-rows-above.js";
8
11
  export * from "./get-rows-below.js";
9
12
  export * from "./parse-rows.js";
10
13
  export * from "./to-excel-column-object.js";
14
+ export * from "./update-dimension.js";
15
+ export * from "./validate-worksheet-xml.js";
11
16
  export * from "./write-rows-to-stream.js";
@@ -0,0 +1 @@
1
+ export declare function updateDimension(xml: string): string;
@@ -0,0 +1,9 @@
1
+ interface ValidationResult {
2
+ isValid: boolean;
3
+ error?: {
4
+ message: string;
5
+ details?: string;
6
+ };
7
+ }
8
+ export declare function validateWorksheetXml(xml: string): ValidationResult;
9
+ export {};
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@js-ak/excel-toolbox",
3
- "version": "1.3.2",
3
+ "version": "1.4.0",
4
4
  "description": "excel-toolbox",
5
5
  "publishConfig": {
6
6
  "access": "public",
@@ -38,13 +38,14 @@
38
38
  "package.json"
39
39
  ],
40
40
  "scripts": {
41
- "build": "npm run build:cjs && npm run build:esm && npm run postbuild:esm && npm run postbuild:cjs",
41
+ "build": "npm run build:cjs && npm run build:esm && npm run postbuild:cjs && npm run postbuild:esm",
42
42
  "build:esm": "tsc -p tsconfig.esm.json",
43
43
  "build:cjs": "tsc -p tsconfig.cjs.json",
44
44
  "lint": "eslint . --ext .ts",
45
45
  "postbuild:esm": "node scripts/write-esm-package.js",
46
46
  "postbuild:cjs": "node scripts/write-cjs-package.js",
47
- "test": "npm run build && node ./build/esm/test/index.js"
47
+ "test": "vitest run",
48
+ "test:watch": "vitest"
48
49
  },
49
50
  "repository": {
50
51
  "type": "git",
@@ -75,7 +76,8 @@
75
76
  "globals": "16.0.0",
76
77
  "semantic-release": "24.0.0",
77
78
  "typescript": "5.8.3",
78
- "typescript-eslint": "8.29.0"
79
+ "typescript-eslint": "8.29.0",
80
+ "vitest": "3.1.1"
79
81
  },
80
82
  "dependencies": {
81
83
  "pako": "2.1.0"