Merge pull request #33 from JS-AK/feat/template/updates

feat: updated TemplateFs TemplateMemory

Author: JS-AK

docs/merge-sheets-to-base-file.md

@@ -1,134 +1,169 @@
-# Merging Sheets into Base File
+# mergeSheetsToBaseFile
 
-This document explains how to merge sheets from multiple Excel files into a base file using the Excel Toolbox library.
+Merges rows from multiple sheets into a single sheet of a base Excel file while preserving formatting and structure.
 
-## Overview
+> ⚠️ **Experimental API**
+> Interface may change in future releases.
 
-The merge functionality allows you to:
+---
 
-- Combine rows from multiple sheets into a single base sheet
-- Maintain cell formatting and merged cells
-- Insert gaps between merged sections
-- Remove unwanted sheets from the output file
+## 📦 Functions
 
-## Basic Usage
+### `mergeSheetsToBaseFile`
 
-### Asynchronous Merge
+Asynchronously merges rows from specified sheets of one or more Excel files into a sheet of a base Excel file.
 
-```typescript
-import { mergeSheetsToBaseFile } from '@js-ak/excel-toolbox';
-
-const result = await mergeSheetsToBaseFile({
-  baseFile: baseFileBuffer,
-  baseSheetIndex: 1, // Optional, defaults to 1
-  additions: [
-    {
-      file: sourceFileBuffer,
-      sheetIndexes: [1, 2], // Sheets to merge from source file
-      isBaseFile: false // Optional, set to true if source is the base file
-    }
-  ],
-  gap: 1, // Optional, number of empty rows between sections
-  sheetNamesToRemove: [], // Optional, names of sheets to remove
-  sheetsToRemove: [] // Optional, indices of sheets to remove
-});
+```ts
+mergeSheetsToBaseFile(options: MergeSheetsOptions): Promise<Buffer>
 ```
 
-### Synchronous Merge
+- Input: `options: MergeSheetsOptions` — configuration for merging
+- Output: `Promise<Buffer>` — the resulting `.xlsx` file as a buffer
+- Throws if:
+  - Required files or sheets are missing
+  - Sheet indices are invalid
+  - XML structure is malformed
+  - Merged cells conflict
 
-```typescript
-import { mergeSheetsToBaseFileSync } from '@js-ak/excel-toolbox';
+---
 
-const result = mergeSheetsToBaseFileSync({
-  baseFile: baseFileBuffer,
-  baseSheetIndex: 1,
-  additions: [
-    {
-      file: sourceFileBuffer,
-      sheetIndexes: [1, 2]
-    }
-  ],
-  gap: 1
-});
+### `mergeSheetsToBaseFileSync`
+
+Synchronous version of `mergeSheetsToBaseFile`.
+
+```ts
+mergeSheetsToBaseFileSync(options: MergeSheetsOptions): Buffer
 ```
 
-## Parameters
+- Input: `options: MergeSheetsOptions`
+- Output: `Buffer` — resulting Excel file
+- Same error conditions as async version
+
+---
+
+## ⚙️ Parameters
+
+### `MergeSheetsOptions`
+
+```ts
+interface MergeSheetsOptions {
+  baseFile: Buffer;
+  baseSheetIndex?: number; // default: 1
+  additions: Array<{
+    file: Buffer;
+    sheetIndexes: number[];
+    isBaseFile?: boolean;
+  }>;
+  gap?: number; // default: 0
+  sheetNamesToRemove?: string[];
+  sheetsToRemove?: number[];
+}
+```
 
-### Base File Configuration
+- `baseFile` — buffer of the base Excel file
+- `baseSheetIndex` — 1-based index of the sheet to merge into
+- `additions` — list of files and sheets to merge
+- `gap` — number of empty rows to insert between sections
+- `sheetNamesToRemove` — optional sheet names to remove
+- `sheetsToRemove` — optional sheet indices (1-based) to remove
 
-- `baseFile`: Buffer containing the base Excel file
-- `baseSheetIndex`: 1-based index of the sheet to merge into (default: 1)
+---
 
-### Additions Configuration
+## 🧩 Features
 
-- `additions`: Array of objects specifying files and sheets to merge
-  - `file`: Buffer containing the source Excel file
-  - `sheetIndexes`: Array of 1-based sheet indices to merge
-  - `isBaseFile`: Optional boolean indicating if source is the base file
+### ✅ Merged Cell Support
 
-### Optional Parameters
+- Preserves existing merged cells
+- Adjusts merge ranges on row shifts
+- Handles overlapping cells gracefully
 
-- `gap`: Number of empty rows to insert between merged sections (default: 0)
-- `sheetNamesToRemove`: Array of sheet names to remove from output
-- `sheetsToRemove`: Array of 1-based sheet indices to remove from output
+### 📐 Row Shifting
 
-## Features
+- Automatically shifts incoming rows
+- Updates row numbers and references
+- Supports configurable row gaps
 
-### Merged Cells Support
+### 🗂️ Sheet Management
 
-The merge process automatically handles merged cells by:
+- Removes sheets by name or index
+- Cleans up `workbook.xml`, `workbook.xml.rels`, `[Content_Types].xml`
+- Preserves valid sheet references
 
-- Preserving existing merged cells in the base sheet
-- Adjusting merged cell references when rows are shifted
-- Maintaining merge cell count and references
+---
 
-### Row Shifting
+## ❌ Errors
 
-- Rows from source sheets are automatically shifted to maintain proper row numbers
-- Cell references are updated to reflect new row positions
-- Gaps between sections are properly maintained
+Throws when:
 
-### Sheet Management
+- `baseFile` or required `sheetIndexes` are missing
+- Sheets in `additions` don’t exist
+- Sheet merges produce invalid or overlapping ranges
+- Sheet names or indices for removal are invalid
+- Input files are corrupt or malformed
 
-- Can remove specific sheets by name or index
-- Updates workbook.xml, workbook.xml.rels, and [Content_Types].xml accordingly
-- Maintains proper sheet relationships and references
+---
 
-## Error Handling
+## 💡 Best Practices
 
-The merge process will throw errors for:
+1. Specify `baseSheetIndex` when using multi-sheet base files
+2. Use `gap` for readability in merged output
+3. Clean unused sheets to minimize output size
+4. Validate all inputs prior to merge
+5. Catch and log merge errors during integration
 
-- Missing base file or sheet
-- Invalid sheet indices
-- Missing source files or sheets
-- Invalid XML structure
-- Duplicate merged cells
-- Overlapping merge ranges
+---
 
-## Best Practices
+## 🧪 Usage Examples
 
-1. Always specify a valid `baseSheetIndex` if your base file has multiple sheets
-2. Use `gap` parameter to improve readability of merged data
-3. Remove unnecessary sheets to reduce file size
-4. Validate input files before merging
-5. Handle errors appropriately in your application
+### Async Merge
 
-## Example
+```ts
+import { mergeSheetsToBaseFile } from '@js-ak/excel-toolbox';
 
-```typescript
-// Merge two sheets from source file into base file
 const result = await mergeSheetsToBaseFile({
   baseFile: baseFileBuffer,
+  baseSheetIndex: 1,
   additions: [
     {
       file: sourceFileBuffer,
-      sheetIndexes: [1, 2]
+      sheetIndexes: [1, 2],
     }
   ],
   gap: 1,
-  sheetsToRemove: [3, 4] // Remove sheets 3 and 4 from output
+  sheetsToRemove: [3, 4]
 });
 
-// Save the result
 await fs.writeFile('merged.xlsx', result);
 ```
+
+---
+
+### Sync Merge
+
+```ts
+import { mergeSheetsToBaseFileSync } from '@js-ak/excel-toolbox';
+
+const result = mergeSheetsToBaseFileSync({
+  baseFile: baseFileBuffer,
+  baseSheetIndex: 1,
+  additions: [
+    {
+      file: sourceFileBuffer,
+      sheetIndexes: [1, 2],
+    }
+  ],
+  gap: 1,
+});
+
+fs.writeFileSync('merged.xlsx', result);
+```
+
+---
+
+## 🧼 Cleanup & Validation
+
+- Sheet removals affect XML metadata and relationships
+- Output file is fully valid `.xlsx`
+- Sheet relationships are adjusted during merge
+
+---

docs/template-fs.md

@@ -115,6 +115,29 @@ Streams and inserts rows into a worksheet, useful for handling large datasets.
 
 ---
 
+### `removeSheets`
+
+Removes specified sheets from the workbook by either their names or 1-based indexes.
+
+- Input:
+  - `data: object` — configuration object
+    - `sheetNames?: string[]` — array of sheet names to remove
+    - `sheetIndexes?: number[]` — array of 1-based sheet indexes to remove
+- Output: `Promise<void>`
+- Preconditions:
+  - Instance not destroyed
+  - Sheets exist
+- Postconditions:
+  - Specified sheets removed from workbook
+  - Workbook relationships updated
+  - Content types updated
+- Throws if:
+  - The instance has been destroyed
+  - Any specified sheet does not exist
+  - Any specified sheet index is invalid
+
+---
+
 ### `save`
 
 Generates a new Excel file and returns it as a `Buffer`.

docs/template-memory.md

@@ -162,7 +162,7 @@ Merges multiple worksheets into a single base worksheet.
   - `baseSheetIndex?: number` — 1-based index of the base sheet to merge into (optional, default is 1).
   - `baseSheetName?: string` — name of the base sheet to merge into (optional).
   - `gap?: number` - number of empty rows to insert between merged sections (default: `0`).
-- Output: `void`
+- Output: `Promise<void>`
 - Preconditions:
   - Instance not destroyed
   - Valid sheet names/indexes
@@ -185,7 +185,7 @@ Removes worksheets from the workbook.
 - Input:
   - `sheetNames?: string[]` - names of sheets to remove
   - `sheetIndexes?: number[]` - 1-based indexes of sheets to remove
-- Output: `void`
+- Output: `Promise<void>`
 - Preconditions:
   - Instance not destroyed
   - Sheets exist