microsoft-graph 2.34.0 → 2.35.0

package/dist/cjs/services/objectMapping.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Automated conversion of rows to objects and vice versa based on defined mapping rules.
+ * @module objectMapping
+ * @category Services
+ */
+import type { Cell } from "../models/Cell.ts";
+import type { ColumnName, ColumnOffset } from "../models/Column.ts";
+/**
+ * Defines rules for mapping between spreadsheet rows and object properties.
+ * @template T Object type to map to/from.
+ */
+export type ObjectMapping<T> = {
+    [K in keyof T]-?: {
+        /**
+         * Pattern to match a column heading for mapping to the object property.
+         * If a string is provided, it will be used as the column name.
+         */
+        columnPattern: RegExp;
+        /**
+         * Decodes a cell to an object property value.
+         * @param cell Cell to decode.
+         * @returns Decoded property value.
+         * @remarks If omitted, the cell's `value` (not `text`) will be used without conversion.
+         * @example
+         * (cell: Cell) => Number.parseFloat(cell.value.toString()) // Convert string number to number
+         */
+        decode?: (cell: Cell) => T[K];
+        /**
+         * Encodes an object property value to a cell.
+         * @param prop Property value to encode.
+         * @returns Encoded cell.
+         * @remarks If omitted, the cell will be created with the `value` property set to the property value.
+         * @example
+         * (prop: number) => ({ value: prop.toString(), ... }) // Convert number to string cell value
+         */
+        encode?: (prop: T[K]) => Cell;
+    };
+};
+/**
+ * Resolved mapping from object properties to column offsets and encode/decode functions.
+ * @template T Object type being mapped.
+ */
+export type ResolvedObjectMapping<T> = {
+    [K in keyof T]-?: {
+        columnOffset: ColumnOffset;
+        decode: (cell: Cell) => T[K];
+        encode: (prop: T[K]) => Cell;
+    };
+};
+/**
+ * Converts spreadsheet rows to objects using the first row as a header.
+ * @template T The object type to yield.
+ * @param rows Iterable or async iterable of cell arrays (rows).
+ * @param rules Mapping rules for converting columns to object properties.
+ * @yields Objects of type T, one for each data row.
+ */
+export declare function rowsToObjectsWithHeader<T>(rows: Iterable<Cell[]> | AsyncIterable<Cell[]>, rules: ObjectMapping<T>): AsyncIterable<T>;
+/**
+ * Creates a mapping from a header row to object properties based on provided rules.
+ * @template T The object type being mapped.
+ * @param headerRow The header row, used to determine column offsets.
+ * @param rules The mapping rules for converting cells to object properties.
+ * @returns The resolved mapping for use in row/object conversion.
+ * @throws {InvalidArgumentError} If a column matching a pattern is not found in the header row.
+ */
+export declare function createObjectMapping<T>(headerRow: (ColumnName | Cell)[], rules: ObjectMapping<T>): ResolvedObjectMapping<T>;
+/**
+ * Converts spreadsheet rows to objects using a provided mapping.
+ * @template T The object type to yield.
+ * @param rows Iterable or async iterable of cell arrays (rows).
+ * @param mapping The resolved mapping for row/object conversion.
+ * @yields Objects of type T, one for each row.
+ */
+export declare function rowsToObjects<T>(rows: Iterable<Cell[]> | AsyncIterable<Cell[]>, mapping: ResolvedObjectMapping<T>): AsyncIterable<T>;
+/**
+ * Converts objects to spreadsheet rows using a provided mapping.
+ * @template T The object type to convert.
+ * @param objects Iterable or async iterable of objects.
+ * @param mapping The resolved mapping for object/row conversion.
+ * @yields Arrays of partial cells, one for each object.
+ */
+export declare function objectsToRows<T>(objects: Iterable<T> | AsyncIterable<T>, mapping: ResolvedObjectMapping<T>): AsyncIterable<Partial<Cell>[]>;
+/**
+ * Converts a row of cells to an object using the provided mapping.
+ * @template T The object type to return.
+ * @param cells The array of cells representing a row.
+ * @param rules The resolved mapping for row/object conversion.
+ * @returns The object of type T.
+ * @throws {InvalidArgumentError} If a required column is missing in the row.
+ */
+export declare function rowToObject<T>(cells: Cell[], rules: ResolvedObjectMapping<T>): T;
+/**
+ * Converts an object to a row of cells using the provided mapping.
+ * @template T The object type to convert.
+ * @param record The object to convert.
+ * @param mapper The resolved mapping for object/row conversion.
+ * @returns An array of partial cells representing the row.
+ */
+export declare function objectToRow<T>(record: T, mapper: ResolvedObjectMapping<T>): Partial<Cell>[];
+//# sourceMappingURL=objectMapping.d.ts.map

package/dist/cjs/services/objectMapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"objectMapping.d.ts","sourceRoot":"","sources":["../../../src/services/objectMapping.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAa,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGpE;;;GAGG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;KAC7B,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG;QACjB;;;WAGG;QACH,aAAa,EAAE,MAAM,CAAC;QAEtB;;;;;;;WAOG;QACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAE9B;;;;;;;WAOG;QACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;KAC9B;CACD,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,IAAI;KACrC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG;QACjB,YAAY,EAAE,YAAY,CAAC;QAC3B,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7B,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;KAC7B;CACD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAuB,uBAAuB,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAW3I;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,UAAU,GAAG,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,qBAAqB,CAAC,CAAC,CAAC,CAsC1H;AAED;;;;;;GAMG;AACH,wBAAuB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAI3I;AAED;;;;;;GAMG;AACH,wBAAuB,aAAa,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAIlJ;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAe5E;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,CAW3F"}

package/dist/cjs/services/objectMapping.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Automated conversion of rows to objects and vice versa based on defined mapping rules.
+ * @module objectMapping
+ * @category Services
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rowsToObjectsWithHeader = rowsToObjectsWithHeader;
+exports.createObjectMapping = createObjectMapping;
+exports.rowsToObjects = rowsToObjects;
+exports.objectsToRows = objectsToRows;
+exports.rowToObject = rowToObject;
+exports.objectToRow = objectToRow;
+const InvalidArgumentError_ts_1 = __importDefault(require("../errors/InvalidArgumentError.js"));
+const cell_ts_1 = require("./cell.js");
+/**
+ * Converts spreadsheet rows to objects using the first row as a header.
+ * @template T The object type to yield.
+ * @param rows Iterable or async iterable of cell arrays (rows).
+ * @param rules Mapping rules for converting columns to object properties.
+ * @yields Objects of type T, one for each data row.
+ */
+async function* rowsToObjectsWithHeader(rows, rules) {
+    let mapping = null;
+    for await (const row of rows) {
+        if (!mapping) {
+            mapping = createObjectMapping(row, rules);
+            continue;
+        }
+        yield rowToObject(row, mapping);
+    }
+}
+/**
+ * Creates a mapping from a header row to object properties based on provided rules.
+ * @template T The object type being mapped.
+ * @param headerRow The header row, used to determine column offsets.
+ * @param rules The mapping rules for converting cells to object properties.
+ * @returns The resolved mapping for use in row/object conversion.
+ * @throws {InvalidArgumentError} If a column matching a pattern is not found in the header row.
+ */
+function createObjectMapping(headerRow, rules) {
+    const headStrings = headerRow.map((c) => (typeof c === "object" ? c.text : c));
+    const resolved = {};
+    for (const key in rules) {
+        if (!Object.prototype.hasOwnProperty.call(rules, key)) {
+            continue;
+        }
+        const rule = rules[key];
+        const offset = headStrings.findIndex((h) => rule.columnPattern.test(h));
+        if (offset === -1) {
+            throw new InvalidArgumentError_ts_1.default(`Column matching "${rule.columnPattern}" not found in header.`);
+        }
+        const columnOffset = offset;
+        const defaultDecode = (cell) => cell.value;
+        const defaultEncode = (prop) => ({
+            value: prop,
+            text: prop?.toString() ?? "",
+            format: cell_ts_1.generalCellFormat,
+            merge: {},
+            alignment: {},
+            borders: {},
+            fill: {},
+            font: {},
+        });
+        const decode = rule.decode ?? defaultDecode;
+        const encode = rule.encode ?? defaultEncode;
+        resolved[key] = {
+            columnOffset,
+            decode,
+            encode,
+        };
+    }
+    return resolved;
+}
+/**
+ * Converts spreadsheet rows to objects using a provided mapping.
+ * @template T The object type to yield.
+ * @param rows Iterable or async iterable of cell arrays (rows).
+ * @param mapping The resolved mapping for row/object conversion.
+ * @yields Objects of type T, one for each row.
+ */
+async function* rowsToObjects(rows, mapping) {
+    for await (const row of rows) {
+        yield rowToObject(row, mapping);
+    }
+}
+/**
+ * Converts objects to spreadsheet rows using a provided mapping.
+ * @template T The object type to convert.
+ * @param objects Iterable or async iterable of objects.
+ * @param mapping The resolved mapping for object/row conversion.
+ * @yields Arrays of partial cells, one for each object.
+ */
+async function* objectsToRows(objects, mapping) {
+    for await (const obj of objects) {
+        yield objectToRow(obj, mapping);
+    }
+}
+/**
+ * Converts a row of cells to an object using the provided mapping.
+ * @template T The object type to return.
+ * @param cells The array of cells representing a row.
+ * @param rules The resolved mapping for row/object conversion.
+ * @returns The object of type T.
+ * @throws {InvalidArgumentError} If a required column is missing in the row.
+ */
+function rowToObject(cells, rules) {
+    const record = {};
+    for (const key in rules) {
+        if (!Object.prototype.hasOwnProperty.call(rules, key)) {
+            continue;
+        }
+        const rule = rules[key];
+        const cell = cells[rule.columnOffset];
+        if (!cell) {
+            throw new InvalidArgumentError_ts_1.default(`Column at index ${rule.columnOffset} is missing for key "${key}".`);
+        }
+        record[key] = rule.decode(cell);
+    }
+    return record;
+}
+/**
+ * Converts an object to a row of cells using the provided mapping.
+ * @template T The object type to convert.
+ * @param record The object to convert.
+ * @param mapper The resolved mapping for object/row conversion.
+ * @returns An array of partial cells representing the row.
+ */
+function objectToRow(record, mapper) {
+    const row = [];
+    for (const key in mapper) {
+        if (!Object.prototype.hasOwnProperty.call(mapper, key)) {
+            continue;
+        }
+        const { columnOffset, encode } = mapper[key];
+        const prop = record[key];
+        row[columnOffset] = encode(prop);
+    }
+    return row;
+}

package/dist/cjs/tasks/insertWorkbookRangeRow.d.ts

@@ -1,6 +1,6 @@
 /**
  * Inserts a single row into a workbook range.
- * @module insertRow
+ * @module insertWorkbookRangeRow
  * @category Tasks
  * @experimental
  */
@@ -12,7 +12,7 @@ import type { WorkbookRangeRef } from "../models/WorkbookRange.ts";
  * @param row Array of cells to insert as a single row.
  * @experimental
  * @example
- * await insertRow(originRef, [{ value: "A1" }, { value: "B1" }, { value: "C1" }]);
+ * await insertWorkbookRangeRow(originRef, [{ value: "A1" }, { value: "B1" }, { value: "C1" }]);
  */
 export default function insertWorkbookRangeRow(originRef: WorkbookRangeRef, row: Partial<Cell>[]): Promise<void>;
 //# sourceMappingURL=insertWorkbookRangeRow.d.ts.map

package/dist/cjs/tasks/insertWorkbookRangeRow.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * Inserts a single row into a workbook range.
- * @module insertRow
+ * @module insertWorkbookRangeRow
  * @category Tasks
  * @experimental
  */
@@ -17,7 +17,7 @@ const insertWorkbookRangeRows_ts_1 = __importDefault(require("./insertWorkbookRa
  * @param row Array of cells to insert as a single row.
  * @experimental
  * @example
- * await insertRow(originRef, [{ value: "A1" }, { value: "B1" }, { value: "C1" }]);
+ * await insertWorkbookRangeRow(originRef, [{ value: "A1" }, { value: "B1" }, { value: "C1" }]);
  */
 async function insertWorkbookRangeRow(originRef, row) {
     await (0, insertWorkbookRangeRows_ts_1.default)(originRef, [row]);

package/dist/cjs/tasks/insertWorkbookRangeRows.d.ts

@@ -1,6 +1,6 @@
 /**
  * Inserts rows into a workbook range.
- * @module insertRows
+ * @module insertWorkbookRangeRows
  * @category Tasks
  * @experimental
  */
@@ -14,14 +14,14 @@ import type { WorkbookRangeRef } from "../models/WorkbookRange.ts";
  * @experimental
  * @example
  * // Basic example:
- * await insertRows(originRef, [
+ * await insertWorkbookRangeRows(originRef, [
  *   [{ value: "A1" }, { value: "B1" }, { value: "C1" }],
  *   [{ value: "A2" }, { value: "B2" }, { value: "C2" }],
  *  [{ value: "A3" }, { value: "B3" }, { value: "C3" }],
  * ])
  *
  * // Advanced example with cell formatting:
- * await insertRows(originRef, [
+ * await insertWorkbookRangeRows(originRef, [
  *   [{ value: "A1", format: { fontColor: "red" } }, { value: "B1" }, { value: "C1" }],
  *   [{ value: "A2" }, { value: "B2", format: { fontColor: "blue" } }, { value: "C2" }],
  *   [{ value: "A3" }, { value: "B3" }, { value: "C3", format: { fontColor: "green" } }],

package/dist/cjs/tasks/insertWorkbookRangeRows.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * Inserts rows into a workbook range.
- * @module insertRows
+ * @module insertWorkbookRangeRows
  * @category Tasks
  * @experimental
  */
@@ -23,14 +23,14 @@ const updateWorkbookRangeRows_ts_1 = __importDefault(require("./updateWorkbookRa
  * @experimental
  * @example
  * // Basic example:
- * await insertRows(originRef, [
+ * await insertWorkbookRangeRows(originRef, [
  *   [{ value: "A1" }, { value: "B1" }, { value: "C1" }],
  *   [{ value: "A2" }, { value: "B2" }, { value: "C2" }],
  *  [{ value: "A3" }, { value: "B3" }, { value: "C3" }],
  * ])
  *
  * // Advanced example with cell formatting:
- * await insertRows(originRef, [
+ * await insertWorkbookRangeRows(originRef, [
  *   [{ value: "A1", format: { fontColor: "red" } }, { value: "B1" }, { value: "C1" }],
  *   [{ value: "A2" }, { value: "B2", format: { fontColor: "blue" } }, { value: "C2" }],
  *   [{ value: "A3" }, { value: "B3" }, { value: "C3", format: { fontColor: "green" } }],

package/dist/cjs/tasks/iterateWorkbookRangeRows.d.ts

@@ -1,6 +1,6 @@
 /**
  * Iterate over the rows in a given worksheet range.
- * @module iterateRows
+ * @module iterateWorkbookRangeRows
  * @category Tasks
  * @experimental
  */

package/dist/cjs/tasks/iterateWorkbookRangeRows.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * Iterate over the rows in a given worksheet range.
- * @module iterateRows
+ * @module iterateWorkbookRangeRows
  * @category Tasks
  * @experimental
  */

package/dist/cjs/tasks/readWorkbookRangeFirstRow.d.ts

@@ -1,6 +1,6 @@
 /**
  * Read the first row from a given workbook range.
- * @module readFirstRow
+ * @module readWorkbookRangeFirstRow
  * @category Tasks
  * @experimental
  */
@@ -12,7 +12,7 @@ import type { WorkbookRangeRef } from "../models/WorkbookRange.ts";
  * @returns A promise that resolves to an array of cells in the first row.
  * @remarks Particularly useful for reading header rows.
  * @example
- * const firstRow = await readFirstRow(rangeRef);
+ * const firstRow = await readWorkbookRangeFirstRow(rangeRef);
  */
 export default function readWorkbookRangeFirstRow(rangeRef: WorkbookRangeRef, scope?: import("../models/Cell.ts").CellScope): Promise<Cell[]>;
 //# sourceMappingURL=readWorkbookRangeFirstRow.d.ts.map

package/dist/cjs/tasks/readWorkbookRangeFirstRow.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * Read the first row from a given workbook range.
- * @module readFirstRow
+ * @module readWorkbookRangeFirstRow
  * @category Tasks
  * @experimental
  */
@@ -20,7 +20,7 @@ const iterateWorkbookRangeRows_ts_1 = require("./iterateWorkbookRangeRows.js");
  * @returns A promise that resolves to an array of cells in the first row.
  * @remarks Particularly useful for reading header rows.
  * @example
- * const firstRow = await readFirstRow(rangeRef);
+ * const firstRow = await readWorkbookRangeFirstRow(rangeRef);
  */
 async function readWorkbookRangeFirstRow(rangeRef, scope = cell_ts_1.defaultCellScope) {
     const firstRowRef = (0, addressManipulation_ts_1.subRange)(rangeRef, 0, 1);

package/dist/cjs/tasks/readWorkbookRangeRows.d.ts

@@ -1,6 +1,6 @@
 /**
  * Read all rows from a given workbook range.
- * @module readRows
+ * @module readWorkbookRangeRows
  * @category Tasks
  * @experimental
  */
@@ -14,7 +14,7 @@ import type { WorkbookRangeRef } from "../models/WorkbookRange.ts";
  * @remarks Where practical, prefer using {@link iterateWorkbookRangeRows} for more efficient memory usage.
  * @experimental
  * @example
- * const rows = await readRows(rangeRef);
+ * const rows = await readWorkbookRangeRows(rangeRef);
  */
 export default function readWorkbookRangeRows(rangeRef: WorkbookRangeRef, scope?: import("../models/Cell.ts").CellScope): Promise<Cell[][]>;
 //# sourceMappingURL=readWorkbookRangeRows.d.ts.map

package/dist/cjs/tasks/readWorkbookRangeRows.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * Read all rows from a given workbook range.
- * @module readRows
+ * @module readWorkbookRangeRows
  * @category Tasks
  * @experimental
  */
@@ -17,7 +17,7 @@ const iterateWorkbookRangeRows_ts_1 = require("./iterateWorkbookRangeRows.js");
  * @remarks Where practical, prefer using {@link iterateWorkbookRangeRows} for more efficient memory usage.
  * @experimental
  * @example
- * const rows = await readRows(rangeRef);
+ * const rows = await readWorkbookRangeRows(rangeRef);
  */
 async function readWorkbookRangeRows(rangeRef, scope = cell_ts_1.defaultCellScope) {
     const rows = [];

package/dist/cjs/tasks/updateWorkbookRangeFirstRow.d.ts

@@ -1,6 +1,6 @@
 /**
  * Update first row in a given workbook range.
- * @module updateFirstRow
+ * @module updateWorkbookRangeFirstRow
  * @category Tasks
  * @experimental
  */
@@ -14,10 +14,10 @@ import type { WorkbookRangeRef } from "../models/WorkbookRange.ts";
  * @experimental
  * @example
  * // Basic example:
- * await updateFirstRow(rangeRef, [{ value: 1 }, { value: 2 }]);
+ * await updateWorkbookRangeFirstRow(rangeRef, [{ value: 1 }, { value: 2 }]);
  *
  * // Advanced example with cell formatting:
- * await updateRows(rangeRef, [
+ * await updateWorkbookRangeFirstRow(rangeRef, [
  *  { value: "Column A", style: { alignment: { horizontal: "Right" }, font: { bold: true } } },
  *  { value: "Column B", style: { alignment: { horizontal: "Right" }, font: { bold: true } } }
  * ]);

package/dist/cjs/tasks/updateWorkbookRangeFirstRow.js

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * Update first row in a given workbook range.
- * @module updateFirstRow
+ * @module updateWorkbookRangeFirstRow
  * @category Tasks
  * @experimental
  */
@@ -19,10 +19,10 @@ const updateWorkbookRangeRows_ts_1 = __importDefault(require("./updateWorkbookRa
  * @experimental
  * @example
  * // Basic example:
- * await updateFirstRow(rangeRef, [{ value: 1 }, { value: 2 }]);
+ * await updateWorkbookRangeFirstRow(rangeRef, [{ value: 1 }, { value: 2 }]);
  *
  * // Advanced example with cell formatting:
- * await updateRows(rangeRef, [
+ * await updateWorkbookRangeFirstRow(rangeRef, [
  *  { value: "Column A", style: { alignment: { horizontal: "Right" }, font: { bold: true } } },
  *  { value: "Column B", style: { alignment: { horizontal: "Right" }, font: { bold: true } } }
  * ]);

package/dist/cjs/tasks/updateWorkbookRangeRows.d.ts

@@ -9,18 +9,27 @@ import type { WorkbookRangeRef } from "../models/WorkbookRange.ts";
  * @experimental
  * @example
  * // Basic example:
- * await updateRows(rangeRef, [
+ * await updateWorkbookRangeRows(rangeRef, [
  *   [{ value: 1 }, { value: 2 }],
  *   [{ value: 3 }, { value: 4 }],
  *   [{ value: 5 }, { value: 6 }],
  * ]);
  *
  * // Advanced example with cell formatting:
- * await updateRows(rangeRef, [
- *   [{ value: "Column A", style: { alignment: { horizontal: "Right" }, font: { bold: true } } }, { value: "Column B", style: { alignment: { horizontal: "Right" }, font: { bold: true } }  }],
- *   [{ value: 1, format: accountingCellFormat }, { value: "A" }],
- *   [{ value: 2, format: accountingCellFormat }, { value: "B" }],
- * ]);
+ * await updateWorkbookRangeRows(rangeRef, [
+ * [
+ * 	{ value: "Column A", alignment: { horizontal: "Right" }, font: { bold: true, color: "#ffffff" as Color }, fill: { color: "#000000" as Color } },
+ * 	{ value: "Column B", alignment: { horizontal: "Right" }, font: { bold: true, color: "#ffffff" as Color }, fill: { color: "#000000" as Color } },
+ * ],
+ * [
+ * 	{ value: 1, format: accountingCellFormat },
+ * 	{ value: "A" },
+ * ],
+ * [
+ * 	{ value: 2, format: accountingCellFormat },
+ * 	{ value: "B" }],
+ * ],
+ * );
  */
 export default function updateWorkbookRangeRows(originRef: WorkbookRangeRef, cells: Iterable<Partial<Cell>[]> | AsyncIterable<Partial<Cell>[]>, maxCellsPerOperation?: number | null): Promise<void>;
 //# sourceMappingURL=updateWorkbookRangeRows.d.ts.map

package/dist/cjs/tasks/updateWorkbookRangeRows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"updateWorkbookRangeRows.d.ts","sourceRoot":"","sources":["../../../src/tasks/updateWorkbookRangeRows.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAWnE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAA8B,uBAAuB,CAAC,SAAS,EAAE,gBAAgB,EAAE,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,oBAAoB,GAAE,MAAM,GAAG,IAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB/M"}
+{"version":3,"file":"updateWorkbookRangeRows.d.ts","sourceRoot":"","sources":["../../../src/tasks/updateWorkbookRangeRows.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAWnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,wBAA8B,uBAAuB,CAAC,SAAS,EAAE,gBAAgB,EAAE,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,oBAAoB,GAAE,MAAM,GAAG,IAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB/M"}

package/dist/cjs/tasks/updateWorkbookRangeRows.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = updateWorkbookRangeRows;
 /**
  * Update rows in a given workbook range.
- * @module updateRows
+ * @module updateWorkbookRangeRows
  * @category Tasks
  * @experimental
  */
@@ -30,18 +30,27 @@ const stringCaseConversion_ts_1 = require("../services/stringCaseConversion.js")
  * @experimental
  * @example
  * // Basic example:
- * await updateRows(rangeRef, [
+ * await updateWorkbookRangeRows(rangeRef, [
  *   [{ value: 1 }, { value: 2 }],
  *   [{ value: 3 }, { value: 4 }],
  *   [{ value: 5 }, { value: 6 }],
  * ]);
  *
  * // Advanced example with cell formatting:
- * await updateRows(rangeRef, [
- *   [{ value: "Column A", style: { alignment: { horizontal: "Right" }, font: { bold: true } } }, { value: "Column B", style: { alignment: { horizontal: "Right" }, font: { bold: true } }  }],
- *   [{ value: 1, format: accountingCellFormat }, { value: "A" }],
- *   [{ value: 2, format: accountingCellFormat }, { value: "B" }],
- * ]);
+ * await updateWorkbookRangeRows(rangeRef, [
+ * [
+ * 	{ value: "Column A", alignment: { horizontal: "Right" }, font: { bold: true, color: "#ffffff" as Color }, fill: { color: "#000000" as Color } },
+ * 	{ value: "Column B", alignment: { horizontal: "Right" }, font: { bold: true, color: "#ffffff" as Color }, fill: { color: "#000000" as Color } },
+ * ],
+ * [
+ * 	{ value: 1, format: accountingCellFormat },
+ * 	{ value: "A" },
+ * ],
+ * [
+ * 	{ value: 2, format: accountingCellFormat },
+ * 	{ value: "B" }],
+ * ],
+ * );
  */
 async function updateWorkbookRangeRows(originRef, cells, maxCellsPerOperation = null) {
     let maxRowsPerOperation = maxCellsPerOperation;

package/dist/esm/services/objectMapping.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Automated conversion of rows to objects and vice versa based on defined mapping rules.
+ * @module objectMapping
+ * @category Services
+ */
+import type { Cell } from "../models/Cell.ts";
+import type { ColumnName, ColumnOffset } from "../models/Column.ts";
+/**
+ * Defines rules for mapping between spreadsheet rows and object properties.
+ * @template T Object type to map to/from.
+ */
+export type ObjectMapping<T> = {
+    [K in keyof T]-?: {
+        /**
+         * Pattern to match a column heading for mapping to the object property.
+         * If a string is provided, it will be used as the column name.
+         */
+        columnPattern: RegExp;
+        /**
+         * Decodes a cell to an object property value.
+         * @param cell Cell to decode.
+         * @returns Decoded property value.
+         * @remarks If omitted, the cell's `value` (not `text`) will be used without conversion.
+         * @example
+         * (cell: Cell) => Number.parseFloat(cell.value.toString()) // Convert string number to number
+         */
+        decode?: (cell: Cell) => T[K];
+        /**
+         * Encodes an object property value to a cell.
+         * @param prop Property value to encode.
+         * @returns Encoded cell.
+         * @remarks If omitted, the cell will be created with the `value` property set to the property value.
+         * @example
+         * (prop: number) => ({ value: prop.toString(), ... }) // Convert number to string cell value
+         */
+        encode?: (prop: T[K]) => Cell;
+    };
+};
+/**
+ * Resolved mapping from object properties to column offsets and encode/decode functions.
+ * @template T Object type being mapped.
+ */
+export type ResolvedObjectMapping<T> = {
+    [K in keyof T]-?: {
+        columnOffset: ColumnOffset;
+        decode: (cell: Cell) => T[K];
+        encode: (prop: T[K]) => Cell;
+    };
+};
+/**
+ * Converts spreadsheet rows to objects using the first row as a header.
+ * @template T The object type to yield.
+ * @param rows Iterable or async iterable of cell arrays (rows).
+ * @param rules Mapping rules for converting columns to object properties.
+ * @yields Objects of type T, one for each data row.
+ */
+export declare function rowsToObjectsWithHeader<T>(rows: Iterable<Cell[]> | AsyncIterable<Cell[]>, rules: ObjectMapping<T>): AsyncIterable<T>;
+/**
+ * Creates a mapping from a header row to object properties based on provided rules.
+ * @template T The object type being mapped.
+ * @param headerRow The header row, used to determine column offsets.
+ * @param rules The mapping rules for converting cells to object properties.
+ * @returns The resolved mapping for use in row/object conversion.
+ * @throws {InvalidArgumentError} If a column matching a pattern is not found in the header row.
+ */
+export declare function createObjectMapping<T>(headerRow: (ColumnName | Cell)[], rules: ObjectMapping<T>): ResolvedObjectMapping<T>;
+/**
+ * Converts spreadsheet rows to objects using a provided mapping.
+ * @template T The object type to yield.
+ * @param rows Iterable or async iterable of cell arrays (rows).
+ * @param mapping The resolved mapping for row/object conversion.
+ * @yields Objects of type T, one for each row.
+ */
+export declare function rowsToObjects<T>(rows: Iterable<Cell[]> | AsyncIterable<Cell[]>, mapping: ResolvedObjectMapping<T>): AsyncIterable<T>;
+/**
+ * Converts objects to spreadsheet rows using a provided mapping.
+ * @template T The object type to convert.
+ * @param objects Iterable or async iterable of objects.
+ * @param mapping The resolved mapping for object/row conversion.
+ * @yields Arrays of partial cells, one for each object.
+ */
+export declare function objectsToRows<T>(objects: Iterable<T> | AsyncIterable<T>, mapping: ResolvedObjectMapping<T>): AsyncIterable<Partial<Cell>[]>;
+/**
+ * Converts a row of cells to an object using the provided mapping.
+ * @template T The object type to return.
+ * @param cells The array of cells representing a row.
+ * @param rules The resolved mapping for row/object conversion.
+ * @returns The object of type T.
+ * @throws {InvalidArgumentError} If a required column is missing in the row.
+ */
+export declare function rowToObject<T>(cells: Cell[], rules: ResolvedObjectMapping<T>): T;
+/**
+ * Converts an object to a row of cells using the provided mapping.
+ * @template T The object type to convert.
+ * @param record The object to convert.
+ * @param mapper The resolved mapping for object/row conversion.
+ * @returns An array of partial cells representing the row.
+ */
+export declare function objectToRow<T>(record: T, mapper: ResolvedObjectMapping<T>): Partial<Cell>[];
+//# sourceMappingURL=objectMapping.d.ts.map