bodevops-features 1.0.0 → 1.0.8

package/dist/types/gg-sheet/types.d.ts

@@ -0,0 +1,250 @@
+/**
+ * Google Sheet Feature Library - Type Definitions
+ * @description Type definitions for Google Sheet operations including reading, writing, and exporting data.
+ * @module gg-sheet/types
+ */
+/**
+ * Configuration options for Google Sheet client initialization.
+ * Supports either a path to a service account key file or a direct credentials object.
+ */
+export interface IGoogleSheetConfig {
+    /** Path to the service account JSON key file */
+    keyFilePath?: string;
+    /** Service account credentials object (alternative to keyFilePath) */
+    credentials?: IGoogleServiceAccountCredentials;
+    /** OAuth scopes for Google Sheets API access */
+    scopes?: string[];
+}
+/**
+ * Google Service Account credentials structure.
+ * This matches the structure of the downloaded JSON key file from Google Cloud Console.
+ */
+export interface IGoogleServiceAccountCredentials {
+    /** The type of account, typically "service_account" */
+    type: string;
+    /** The unique identifier for the project */
+    project_id: string;
+    /** The private key identifier */
+    private_key_id: string;
+    /** The private key in PEM format */
+    private_key: string;
+    /** The service account email address */
+    client_email: string;
+    /** The unique client identifier */
+    client_id: string;
+    /** The authentication URI */
+    auth_uri: string;
+    /** The token URI for obtaining access tokens */
+    token_uri: string;
+    /** The authentication provider certificate URL */
+    auth_provider_x509_cert_url: string;
+    /** The client certificate URL */
+    client_x509_cert_url: string;
+}
+/**
+ * Information about a sheet (tab) within a Google Spreadsheet.
+ */
+export interface ISheetChildrenInfo {
+    /** The title/name of the sheet tab */
+    title: string;
+    /** The unique identifier of the sheet within the spreadsheet */
+    sheetId: number;
+    /** The total number of rows in the sheet */
+    rowCount: number;
+    /** The total number of columns in the sheet */
+    columnCount: number;
+}
+/**
+ * Structure for updating a single cell in a sheet.
+ */
+export interface ISheetValUpdateCell {
+    /** Row index (0-based) */
+    row: number;
+    /** Column index (0-based) */
+    col: number;
+    /** The content to write to the cell */
+    content: string;
+}
+/**
+ * Export type enumeration for sheet export operations.
+ */
+export declare enum ETypeExport {
+    /** Append data to the end of existing data */
+    Append = "Append",
+    /** Overwrite all existing data starting from row 1 */
+    Overwrite = "Overwrite"
+}
+/**
+ * Information about a Google Spreadsheet.
+ */
+export interface ISpreadsheetInfo {
+    /** The title of the spreadsheet */
+    spreadsheetTitle: string;
+    /** Array of sheet tabs within the spreadsheet */
+    sheets: ISheetChildrenInfo[];
+}
+/**
+ * Parameters for getting sheet information.
+ */
+export interface IGetSheetInfoParams {
+    /** The URL of the Google Spreadsheet */
+    sheetUrl: string;
+}
+/**
+ * Parameters for reading values from a sheet.
+ */
+export interface IGetValuesParams {
+    /** The URL of the Google Spreadsheet */
+    sheetUrl: string;
+    /** The name of the specific sheet tab to read from */
+    sheetName: string;
+    /** Optional limit on the number of rows to read */
+    endRow?: number;
+}
+/**
+ * Parameters for finding a row index by column value.
+ */
+export interface IGetIdxRowParams {
+    /** The URL of the Google Spreadsheet */
+    sheetUrl: string;
+    /** The name of the specific sheet tab */
+    sheetName: string;
+    /** The column name to search in (e.g., "A", "B", "AB") */
+    colName: string;
+    /** The value to search for */
+    value: string;
+}
+/**
+ * Parameters for exporting data to a sheet.
+ */
+export interface IExportParams {
+    /** The URL of the Google Spreadsheet */
+    sheetUrl: string;
+    /** The name of the specific sheet tab to write to */
+    sheetName: string;
+    /** Array of column headers */
+    listCols: string[];
+    /** Matrix of data values to export (each inner array is a row) */
+    valsExport: string[][];
+    /** Export type: Append or Overwrite */
+    typeExport: ETypeExport;
+}
+/**
+ * Parameters for updating multiple cells at specific positions.
+ */
+export interface IUpdateMultiCellsParams {
+    /** The URL of the Google Spreadsheet */
+    sheetUrl: string;
+    /** The name of the specific sheet tab */
+    sheetName: string;
+    /** Array of cell updates with row, column, and content */
+    cells: ISheetValUpdateCell[];
+    /**
+     * Row offset for data rows.
+     * - 0: Header at row 1, data starts at row 2 (default)
+     * - 1: Header at row 1, skip row 2, data starts at row 3
+     */
+    rowOffset?: number;
+}
+/**
+ * Structure for column-value pair when updating multiple columns in a row.
+ */
+export interface IColValuePair {
+    /** The content to write */
+    content: string;
+    /** Column index (0-based) */
+    col: number;
+}
+/**
+ * Parameters for updating multiple columns in a single row.
+ */
+export interface IUpdateMultiColsByRowParams {
+    /** The URL of the Google Spreadsheet */
+    sheetUrl: string;
+    /** The name of the specific sheet tab */
+    sheetName: string;
+    /** The row index to update (0-based) */
+    row: number;
+    /** Array of column-value pairs to update */
+    values: IColValuePair[];
+    /** Row offset for data rows (default: 0) */
+    rowOffset?: number;
+}
+/**
+ * Structure for row-value pair when updating multiple rows in a column.
+ */
+export interface IRowValuePair {
+    /** The content to write */
+    content: string;
+    /** Row index (0-based) */
+    row: number;
+}
+/**
+ * Parameters for updating multiple rows in a single column.
+ */
+export interface IUpdateMultiRowsByColParams {
+    /** The URL of the Google Spreadsheet */
+    sheetUrl: string;
+    /** The name of the specific sheet tab */
+    sheetName: string;
+    /** The column index to update (0-based) */
+    col: number;
+    /** Array of row-value pairs to update */
+    values: IRowValuePair[];
+    /** Row offset for data rows (default: 0) */
+    rowOffset?: number;
+}
+/**
+ * Parameters for updating a range of rows and columns.
+ */
+export interface IUpdateMultiRowsMultiColsParams {
+    /** The URL of the Google Spreadsheet */
+    sheetUrl: string;
+    /** The name of the specific sheet tab */
+    sheetName: string;
+    /** Matrix of values to write (rows x columns) */
+    values: string[][];
+    /** Starting row index (0-based, default: 0) */
+    startRow?: number;
+    /** Ending row index (0-based, optional) */
+    endRow?: number;
+    /** Starting column index (0-based, default: 0) */
+    startCol?: number;
+    /** Row offset for data rows (default: 0) */
+    rowOffset?: number;
+}
+/**
+ * Parameters for deleting a row from a sheet.
+ */
+export interface IDeleteRowParams {
+    /** The URL of the Google Spreadsheet */
+    sheetUrl: string;
+    /** The name of the specific sheet tab */
+    sheetName: string;
+    /** The row index to delete (0-based) */
+    row: number;
+    /** Row offset for data rows (default: 0) */
+    rowOffset?: number;
+}
+/**
+ * Parameters for converting raw sheet values to typed objects.
+ */
+export interface IConvertValueSheetParams<T> {
+    /** Raw values from the sheet (2D array) */
+    values: string[][] | null | undefined;
+    /**
+     * Row offset to skip before the header row.
+     * - 0: First row is the header (default)
+     * - 1: First row is skipped, second row is header
+     */
+    rowOffset?: number;
+}
+/**
+ * Result structure for column and value extraction.
+ */
+export interface IListColsAndValsExport {
+    /** Array of column headers */
+    listCols: string[];
+    /** Matrix of data values */
+    valsExport: string[][];
+}

package/dist/types/gg-sheet/utils.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Google Sheet Feature Library - Utility Functions
+ * @description Helper functions for sheet operations, column conversion, and data transformation.
+ * @module gg-sheet/utils
+ */
+import { IListColsAndValsExport } from './types';
+/**
+ * Extracts the spreadsheet ID from a Google Sheets URL.
+ *
+ * @param sheetUrl - The full URL of the Google Spreadsheet
+ * @returns The spreadsheet ID or null if not found
+ *
+ * @example
+ * ```typescript
+ * const id = getSheetIdFromUrl({
+ *   sheetUrl: 'https://docs.google.com/spreadsheets/d/1abc123def/edit'
+ * });
+ * // Returns: '1abc123def'
+ * ```
+ */
+export declare function getSheetIdFromUrl({ sheetUrl }: {
+    sheetUrl: string;
+}): string | null;
+/**
+ * Converts a 0-based column index to a column letter (e.g., 0 → A, 25 → Z, 26 → AA).
+ *
+ * @param columnIndex - The 0-based column index
+ * @returns The column letter(s) (e.g., "A", "B", "AA", "AB")
+ *
+ * @example
+ * ```typescript
+ * convertIndexToColumnName({ columnIndex: 0 });  // "A"
+ * convertIndexToColumnName({ columnIndex: 25 }); // "Z"
+ * convertIndexToColumnName({ columnIndex: 26 }); // "AA"
+ * convertIndexToColumnName({ columnIndex: 701 }); // "ZZ"
+ * ```
+ */
+export declare function convertIndexToColumnName({ columnIndex }: {
+    columnIndex: number;
+}): string;
+/**
+ * Converts a column letter to a 0-based column index (e.g., A → 0, Z → 25, AA → 26).
+ *
+ * @param columnName - The column letter(s) (e.g., "A", "B", "AA")
+ * @returns The 0-based column index
+ * @throws Error if the column name contains invalid characters
+ *
+ * @example
+ * ```typescript
+ * convertColumnNameToIndex({ columnName: 'A' });  // 0
+ * convertColumnNameToIndex({ columnName: 'Z' });  // 25
+ * convertColumnNameToIndex({ columnName: 'AA' }); // 26
+ * convertColumnNameToIndex({ columnName: 'ZZ' }); // 701
+ * ```
+ */
+export declare function convertColumnNameToIndex({ columnName }: {
+    columnName: string;
+}): number;
+/**
+ * Converts raw sheet values (2D array) into an array of typed objects.
+ * Uses the first row (or row at rowOffset) as keys for the objects.
+ *
+ * @param values - Raw 2D array from sheet
+ * @param rowOffset - Number of rows to skip before the header row (default: 0)
+ * @returns Array of typed objects, or null if values is null/undefined
+ *
+ * @example
+ * ```typescript
+ * const rawData = [
+ *   ['name', 'age', 'email'],
+ *   ['John', '30', 'john@example.com'],
+ *   ['Jane', '25', 'jane@example.com']
+ * ];
+ *
+ * interface Person { name: string; age: string; email: string; }
+ *
+ * const people = convertValueSheet<Person>({ values: rawData });
+ * // Returns: [
+ * //   { name: 'John', age: '30', email: 'john@example.com' },
+ * //   { name: 'Jane', age: '25', email: 'jane@example.com' }
+ * // ]
+ * ```
+ */
+export declare function convertValueSheet<T>({ values, rowOffset, }: {
+    values: string[][] | null | undefined;
+    rowOffset?: number;
+}): T[] | null;
+/**
+ * Gets the index of a column key in the list of keys.
+ *
+ * @param key - The key to find
+ * @param listKeys - Array of all keys
+ * @returns The index of the key, or -1 if not found
+ *
+ * @example
+ * ```typescript
+ * interface Person { id: string; name: string; email: string; }
+ * const keys: (keyof Person)[] = ['id', 'name', 'email'];
+ *
+ * getIndexCol({ key: 'name', listKeys: keys }); // 1
+ * getIndexCol({ key: 'email', listKeys: keys }); // 2
+ * ```
+ */
+export declare function getIndexCol<T>({ key, listKeys }: {
+    key: keyof T;
+    listKeys: (keyof T)[];
+}): number;
+/**
+ * Extracts column headers and data values from a result set for export.
+ * Takes an object mapping field keys to column names and an array of items.
+ *
+ * @param colsForSheet - Object mapping field keys to column header names
+ * @param resultItems - Array of items to export
+ * @returns Object containing listCols (headers) and valsExport (data matrix)
+ *
+ * @example
+ * ```typescript
+ * const colsMapping = { id: 'ID', name: 'Full Name', email: 'Email Address' };
+ * const items = [
+ *   { id: '1', name: 'John Doe', email: 'john@example.com' },
+ *   { id: '2', name: 'Jane Doe', email: 'jane@example.com' }
+ * ];
+ *
+ * const { listCols, valsExport } = getListColsAndValsExport({
+ *   colsForSheet: colsMapping,
+ *   resultItems: items
+ * });
+ * // listCols: ['ID', 'Full Name', 'Email Address']
+ * // valsExport: [['1', 'John Doe', 'john@example.com'], ['2', 'Jane Doe', 'jane@example.com']]
+ * ```
+ */
+export declare function getListColsAndValsExport<T extends Record<string, unknown>>({ colsForSheet, resultItems, }: {
+    colsForSheet: Record<keyof T, string>;
+    resultItems: T[];
+}): IListColsAndValsExport;
+/**
+ * Validates that a sheet URL is in the correct format.
+ *
+ * @param sheetUrl - The URL to validate
+ * @returns True if the URL is valid, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isValidSheetUrl({ sheetUrl: 'https://docs.google.com/spreadsheets/d/1abc123/edit' }); // true
+ * isValidSheetUrl({ sheetUrl: 'https://example.com/sheet' }); // false
+ * ```
+ */
+export declare function isValidSheetUrl({ sheetUrl }: {
+    sheetUrl: string;
+}): boolean;
+/**
+ * Calculates the actual row index in the sheet based on the data row index and offset.
+ * This accounts for header row(s) and any additional offset rows.
+ *
+ * @param dataRowIndex - The 0-based index in the data (not counting headers)
+ * @param rowOffset - Additional rows to skip after the header (default: 0)
+ * @returns The 1-based row number in the actual sheet
+ *
+ * @example
+ * ```typescript
+ * // With rowOffset=0: header at row 1, data starts at row 2
+ * calculateActualRow({ dataRowIndex: 0, rowOffset: 0 }); // 2 (first data row)
+ * calculateActualRow({ dataRowIndex: 5, rowOffset: 0 }); // 7 (sixth data row)
+ *
+ * // With rowOffset=1: header at row 1, skip row 2, data starts at row 3
+ * calculateActualRow({ dataRowIndex: 0, rowOffset: 1 }); // 3 (first data row)
+ * ```
+ */
+export declare function calculateActualRow({ dataRowIndex, rowOffset, }: {
+    dataRowIndex: number;
+    rowOffset?: number;
+}): number;

package/dist/types/index.d.ts

@@ -1 +1,22 @@
+/**
+ * BoDevOps Features Library
+ * @description A collection of framework-agnostic utilities for Google Drive, Google Sheets, and iDrive e2.
+ * @module bodevops-features
+ *
+ * @example
+ * ```typescript
+ * import { GGDrive, GGSheet } from 'bodevops-features';
+ *
+ * // Google Drive operations
+ * const driveClient = new GGDrive.GoogleDriveClient({
+ *   keyFilePath: './service-account.json'
+ * });
+ *
+ * // Google Sheet operations
+ * const sheetClient = new GGSheet.GoogleSheetClient({
+ *   keyFilePath: './service-account.json'
+ * });
+ * ```
+ */
 export * as GGDrive from './gg-drive';
+export * as GGSheet from './gg-sheet';

package/package.json

@@ -1,44 +1,50 @@
-{
-  "name": "bodevops-features",
-  "version": "1.0.0",
-  "description": "BoDevOps features library - utilities for Google Drive, Google Sheets, and iDrive e2",
-  "main": "dist/cjs/index.js",
-  "module": "dist/esm/index.js",
-  "types": "dist/types/index.d.ts",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/HaiSonMin"
-  },
-  "exports": {
-    ".": {
-      "require": "./dist/cjs/index.js",
-      "import": "./dist/esm/index.js",
-      "types": "./dist/types/index.d.ts"
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "rollup -c && tsc --emitDeclarationOnly --outDir dist/types",
-    "prepublishOnly": "npm run build"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "keywords": [
-    "gg-drive",
-    "gg-sheet",
-    "idrive-e2"
-  ],
-  "author": "BoDevOps",
-  "license": "MIT",
-  "devDependencies": {
-    "@rollup/plugin-commonjs": "^25.0.7",
-    "@rollup/plugin-node-resolve": "^15.2.3",
-    "@rollup/plugin-typescript": "^11.1.6",
-    "rollup": "^4.9.6",
-    "tslib": "^2.6.2",
-    "typescript": "^5.3.3"
-  }
-}
+{
+  "name": "bodevops-features",
+  "version": "1.0.8",
+  "description": "BoDevOps features library - utilities for Google Drive, Google Sheets, and iDrive e2",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HaiSonMin"
+  },
+  "exports": {
+    ".": {
+      "require": "./dist/cjs/index.js",
+      "import": "./dist/esm/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rollup -c && tsc --emitDeclarationOnly --outDir dist/types",
+    "pub": "npm run build && npm publish",
+    "check": "tsc --noEmit",
+    "check:watch": "tsc --noEmit --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "gg-drive",
+    "gg-sheet",
+    "idrive-e2"
+  ],
+  "author": "BoDevOps",
+  "license": "MIT",
+  "dependencies": {
+    "googleapis": "^130.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "rollup": "^4.9.6",
+    "tslib": "^2.6.2",
+    "typescript": "^5.3.3"
+  }
+}