@niicojs/excel 0.1.0

package/src/types.ts

@@ -0,0 +1,165 @@
+/**
+ * Cell value types - what a cell can contain
+ */
+export type CellValue = number | string | boolean | Date | null | CellError;
+
+/**
+ * Represents an Excel error value
+ */
+export interface CellError {
+  error: ErrorType;
+}
+
+export type ErrorType = '#NULL!' | '#DIV/0!' | '#VALUE!' | '#REF!' | '#NAME?' | '#NUM!' | '#N/A' | '#GETTING_DATA';
+
+/**
+ * Discriminator for cell content type
+ */
+export type CellType = 'number' | 'string' | 'boolean' | 'date' | 'error' | 'empty';
+
+/**
+ * Style definition for cells
+ */
+export interface CellStyle {
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean | 'single' | 'double';
+  strike?: boolean;
+  fontSize?: number;
+  fontName?: string;
+  fontColor?: string;
+  fill?: string;
+  border?: BorderStyle;
+  alignment?: Alignment;
+  numberFormat?: string;
+}
+
+export interface BorderStyle {
+  top?: BorderType;
+  bottom?: BorderType;
+  left?: BorderType;
+  right?: BorderType;
+}
+
+export type BorderType = 'thin' | 'medium' | 'thick' | 'double' | 'dotted' | 'dashed';
+
+export interface Alignment {
+  horizontal?: 'left' | 'center' | 'right' | 'justify';
+  vertical?: 'top' | 'middle' | 'bottom';
+  wrapText?: boolean;
+  textRotation?: number;
+}
+
+/**
+ * Cell address with 0-indexed row and column
+ */
+export interface CellAddress {
+  row: number;
+  col: number;
+}
+
+/**
+ * Range address with start and end cells
+ */
+export interface RangeAddress {
+  start: CellAddress;
+  end: CellAddress;
+}
+
+/**
+ * Internal cell data representation
+ */
+export interface CellData {
+  /** Cell type: n=number, s=string (shared), str=inline string, b=boolean, e=error, d=date */
+  t?: 'n' | 's' | 'str' | 'b' | 'e' | 'd';
+  /** Raw value */
+  v?: number | string | boolean;
+  /** Formula (without leading =) */
+  f?: string;
+  /** Style index */
+  s?: number;
+  /** Formatted text (cached) */
+  w?: string;
+  /** Number format */
+  z?: string;
+  /** Array formula range */
+  F?: string;
+  /** Dynamic array formula flag */
+  D?: boolean;
+  /** Shared formula index */
+  si?: number;
+}
+
+/**
+ * Sheet definition from workbook.xml
+ */
+export interface SheetDefinition {
+  name: string;
+  sheetId: number;
+  rId: string;
+}
+
+/**
+ * Relationship definition
+ */
+export interface Relationship {
+  id: string;
+  type: string;
+  target: string;
+}
+
+/**
+ * Pivot table aggregation functions
+ */
+export type AggregationType = 'sum' | 'count' | 'average' | 'min' | 'max';
+
+/**
+ * Configuration for a value field in a pivot table
+ */
+export interface PivotValueConfig {
+  /** Source field name (column header) */
+  field: string;
+  /** Aggregation function */
+  aggregation: AggregationType;
+  /** Display name (e.g., "Sum of Sales") */
+  name?: string;
+}
+
+/**
+ * Configuration for creating a pivot table
+ */
+export interface PivotTableConfig {
+  /** Name of the pivot table */
+  name: string;
+  /** Source data range with sheet name (e.g., "Sheet1!A1:D100") */
+  source: string;
+  /** Target cell where pivot table will be placed (e.g., "Sheet2!A3") */
+  target: string;
+  /** Refresh the pivot table data when the file is opened (default: true) */
+  refreshOnLoad?: boolean;
+}
+
+/**
+ * Internal representation of a pivot cache field
+ */
+export interface PivotCacheField {
+  /** Field name (from header row) */
+  name: string;
+  /** Field index (0-based) */
+  index: number;
+  /** Whether this field contains numbers */
+  isNumeric: boolean;
+  /** Whether this field contains dates */
+  isDate: boolean;
+  /** Unique string values (for shared items) */
+  sharedItems: string[];
+  /** Min numeric value */
+  minValue?: number;
+  /** Max numeric value */
+  maxValue?: number;
+}
+
+/**
+ * Pivot field axis assignment
+ */
+export type PivotFieldAxis = 'row' | 'column' | 'filter' | 'value';

package/src/utils/address.ts

@@ -0,0 +1,118 @@
+import type { CellAddress, RangeAddress } from '../types';
+
+/**
+ * Converts a column index (0-based) to Excel column letters (A, B, ..., Z, AA, AB, ...)
+ * @param col - 0-based column index
+ * @returns Column letter(s)
+ */
+export const colToLetter = (col: number): string => {
+  let result = '';
+  let n = col;
+  while (n >= 0) {
+    result = String.fromCharCode((n % 26) + 65) + result;
+    n = Math.floor(n / 26) - 1;
+  }
+  return result;
+};
+
+/**
+ * Converts Excel column letters to a 0-based column index
+ * @param letters - Column letter(s) like 'A', 'B', 'AA'
+ * @returns 0-based column index
+ */
+export const letterToCol = (letters: string): number => {
+  const upper = letters.toUpperCase();
+  let col = 0;
+  for (let i = 0; i < upper.length; i++) {
+    col = col * 26 + (upper.charCodeAt(i) - 64);
+  }
+  return col - 1;
+};
+
+/**
+ * Parses an Excel cell address (e.g., 'A1', '$B$2') to row/col indices
+ * @param address - Cell address string
+ * @returns CellAddress with 0-based row and col
+ */
+export const parseAddress = (address: string): CellAddress => {
+  // Remove $ signs for absolute references
+  const clean = address.replace(/\$/g, '');
+  const match = clean.match(/^([A-Z]+)(\d+)$/i);
+  if (!match) {
+    throw new Error(`Invalid cell address: ${address}`);
+  }
+  const col = letterToCol(match[1].toUpperCase());
+  const row = parseInt(match[2], 10) - 1; // Convert to 0-based
+  return { row, col };
+};
+
+/**
+ * Converts row/col indices to an Excel cell address
+ * @param row - 0-based row index
+ * @param col - 0-based column index
+ * @returns Cell address string like 'A1'
+ */
+export const toAddress = (row: number, col: number): string => {
+  return `${colToLetter(col)}${row + 1}`;
+};
+
+/**
+ * Parses an Excel range (e.g., 'A1:B10') to start/end addresses
+ * @param range - Range string
+ * @returns RangeAddress with start and end
+ */
+export const parseRange = (range: string): RangeAddress => {
+  const parts = range.split(':');
+  if (parts.length === 1) {
+    // Single cell range
+    const addr = parseAddress(parts[0]);
+    return { start: addr, end: addr };
+  }
+  if (parts.length !== 2) {
+    throw new Error(`Invalid range: ${range}`);
+  }
+  return {
+    start: parseAddress(parts[0]),
+    end: parseAddress(parts[1]),
+  };
+};
+
+/**
+ * Converts a RangeAddress to a range string
+ * @param range - RangeAddress object
+ * @returns Range string like 'A1:B10'
+ */
+export const toRange = (range: RangeAddress): string => {
+  const start = toAddress(range.start.row, range.start.col);
+  const end = toAddress(range.end.row, range.end.col);
+  if (start === end) {
+    return start;
+  }
+  return `${start}:${end}`;
+};
+
+/**
+ * Normalizes a range so start is always top-left and end is bottom-right
+ */
+export const normalizeRange = (range: RangeAddress): RangeAddress => {
+  return {
+    start: {
+      row: Math.min(range.start.row, range.end.row),
+      col: Math.min(range.start.col, range.end.col),
+    },
+    end: {
+      row: Math.max(range.start.row, range.end.row),
+      col: Math.max(range.start.col, range.end.col),
+    },
+  };
+};
+
+/**
+ * Checks if an address is within a range
+ */
+export const isInRange = (addr: CellAddress, range: RangeAddress): boolean => {
+  const norm = normalizeRange(range);
+  return (
+    addr.row >= norm.start.row && addr.row <= norm.end.row && addr.col >= norm.start.col && addr.col <= norm.end.col
+  );
+};

package/src/utils/xml.ts

@@ -0,0 +1,147 @@
+import { XMLParser, XMLBuilder } from 'fast-xml-parser';
+
+// Parser options that preserve structure and attributes
+const parserOptions = {
+  ignoreAttributes: false,
+  attributeNamePrefix: '@_',
+  textNodeName: '#text',
+  preserveOrder: true,
+  commentPropName: '#comment',
+  cdataPropName: '#cdata',
+  trimValues: false,
+  parseTagValue: false,
+  parseAttributeValue: false,
+};
+
+// Builder options matching parser for round-trip compatibility
+const builderOptions = {
+  ignoreAttributes: false,
+  attributeNamePrefix: '@_',
+  textNodeName: '#text',
+  preserveOrder: true,
+  commentPropName: '#comment',
+  cdataPropName: '#cdata',
+  format: false,
+  suppressEmptyNode: false,
+  suppressBooleanAttributes: false,
+};
+
+const parser = new XMLParser(parserOptions);
+const builder = new XMLBuilder(builderOptions);
+
+/**
+ * Parses an XML string into a JavaScript object
+ * Preserves element order and attributes for round-trip compatibility
+ */
+export const parseXml = (xml: string): XmlNode[] => {
+  return parser.parse(xml);
+};
+
+/**
+ * Converts a JavaScript object back to an XML string
+ */
+export const stringifyXml = (obj: XmlNode[]): string => {
+  return builder.build(obj);
+};
+
+/**
+ * XML node type from fast-xml-parser with preserveOrder
+ * Each node is an object with a single key (the tag name)
+ * containing an array of child nodes, plus optional :@
+ * for attributes
+ */
+export interface XmlNode {
+  [tagName: string]: XmlNode[] | string | Record<string, string> | undefined;
+}
+
+/**
+ * Finds the first element with the given tag name in the XML tree
+ */
+export const findElement = (nodes: XmlNode[], tagName: string): XmlNode | undefined => {
+  for (const node of nodes) {
+    if (tagName in node) {
+      return node;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Finds all elements with the given tag name (immediate children only)
+ */
+export const findElements = (nodes: XmlNode[], tagName: string): XmlNode[] => {
+  return nodes.filter((node) => tagName in node);
+};
+
+/**
+ * Gets the children of an element
+ */
+export const getChildren = (node: XmlNode, tagName: string): XmlNode[] => {
+  const children = node[tagName];
+  if (Array.isArray(children)) {
+    return children;
+  }
+  return [];
+};
+
+/**
+ * Gets an attribute value from a node
+ */
+export const getAttr = (node: XmlNode, name: string): string | undefined => {
+  const attrs = node[':@'] as Record<string, string> | undefined;
+  return attrs?.[`@_${name}`];
+};
+
+/**
+ * Sets an attribute value on a node
+ */
+export const setAttr = (node: XmlNode, name: string, value: string): void => {
+  if (!node[':@']) {
+    node[':@'] = {};
+  }
+  (node[':@'] as Record<string, string>)[`@_${name}`] = value;
+};
+
+/**
+ * Gets the text content of a node
+ */
+export const getText = (node: XmlNode, tagName: string): string | undefined => {
+  const children = getChildren(node, tagName);
+  for (const child of children) {
+    if ('#text' in child) {
+      return child['#text'] as string;
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Creates a new XML element
+ */
+export const createElement = (tagName: string, attrs?: Record<string, string>, children?: XmlNode[]): XmlNode => {
+  const node: XmlNode = {
+    [tagName]: children || [],
+  };
+  if (attrs && Object.keys(attrs).length > 0) {
+    const attrObj: Record<string, string> = {};
+    for (const [key, value] of Object.entries(attrs)) {
+      attrObj[`@_${key}`] = value;
+    }
+    node[':@'] = attrObj;
+  }
+  return node;
+};
+
+/**
+ * Creates a text node
+ */
+export const createText = (text: string): XmlNode => {
+  return { '#text': text } as unknown as XmlNode;
+};
+
+/**
+ * Adds XML declaration to the start of an XML string
+ */
+export const addXmlDeclaration = (xml: string): string => {
+  return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${xml}`;
+};

package/src/utils/zip.ts

@@ -0,0 +1,61 @@
+import { unzip, zip, strFromU8, strToU8 } from 'fflate';
+
+export type ZipFiles = Map<string, Uint8Array>;
+
+/**
+ * Reads a ZIP file and returns a map of path -> content
+ * @param data - ZIP file as Uint8Array
+ * @returns Promise resolving to a map of file paths to contents
+ */
+export const readZip = (data: Uint8Array): Promise<ZipFiles> => {
+  return new Promise((resolve, reject) => {
+    unzip(data, (err, result) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      const files = new Map<string, Uint8Array>();
+      for (const [path, content] of Object.entries(result)) {
+        files.set(path, content);
+      }
+      resolve(files);
+    });
+  });
+};
+
+/**
+ * Creates a ZIP file from a map of path -> content
+ * @param files - Map of file paths to contents
+ * @returns Promise resolving to ZIP file as Uint8Array
+ */
+export const writeZip = (files: ZipFiles): Promise<Uint8Array> => {
+  return new Promise((resolve, reject) => {
+    const zipData: Record<string, Uint8Array> = {};
+    for (const [path, content] of files) {
+      zipData[path] = content;
+    }
+    zip(zipData, (err, result) => {
+      if (err) {
+        reject(err);
+        return;
+      }
+      resolve(result);
+    });
+  });
+};
+
+/**
+ * Reads a file from the ZIP as a UTF-8 string
+ */
+export const readZipText = (files: ZipFiles, path: string): string | undefined => {
+  const data = files.get(path);
+  if (!data) return undefined;
+  return strFromU8(data);
+};
+
+/**
+ * Writes a UTF-8 string to the ZIP files map
+ */
+export const writeZipText = (files: ZipFiles, path: string, content: string): void => {
+  files.set(path, strToU8(content));
+};