ga4-export-fixer 0.4.2-dev.0 → 0.4.2-dev.1

package/helpers/aggregation.js

@@ -2,7 +2,18 @@
 Handling event and session parameters
 */
 
-// filter the event_params array by the selected parameters
+/**
+ * Generates a SQL expression that filters the `event_params` array by the given parameter names.
+ *
+ * When filterType is 'include', only parameters whose key matches one of the given names are kept.
+ * When filterType is 'exclude', parameters whose key matches are removed. If the params array is
+ * empty with 'exclude', the original `event_params` column is returned unfiltered.
+ *
+ * @param {string[]} params - Array of event parameter names to include or exclude.
+ * @param {'include'|'exclude'} filterType - Whether to include or exclude the listed parameters.
+ * @returns {string} SQL expression that produces a filtered event_params array.
+ * @throws {Error} If params is not an array of strings, or if filterType is not 'include' or 'exclude'.
+ */
 const filterEventParams = (params, filterType) => {
   if (!Array.isArray(params) || !params.every(p => typeof p === 'string')) {
     throw new Error("filterEventParams: 'params' must be an array of strings (empty array allowed).");
@@ -131,8 +142,8 @@ Aggregation
  * Throws an error if required parameters are missing or an unsupported aggregation type is requested.
  *
  * @param {string} column - The name of the column to aggregate.
- * @param {string} aggregateType - Type of aggregation ('max', 'min', 'first', 'last', or 'any').
- * @param {string} timestampColumn - Column to use for ordering when aggregateType is 'first' or 'last'.
+ * @param {'max'|'min'|'first'|'last'|'any'} aggregateType - Type of aggregation.
+ * @param {string} [timestampColumn] - Column to use for ordering. Required when aggregateType is 'first' or 'last'.
  * @returns {string} A SQL expression for the requested aggregation.
  * @throws {Error} If required parameters are missing or an unsupported aggregateType is provided.
  *
@@ -182,7 +193,20 @@ const aggregateValue = (column, aggregateType, timestampColumn) => {
   throw new Error(`aggregateValue: Unsupported aggregateType '${aggregateType}'. Supported values are 'max', 'min', 'first', 'last', and 'any'.`);
 };
 
-// perform aggregations on an array of values
+/**
+ * Generates SQL aggregation expressions for an array of column specifications.
+ *
+ * Each item in the array is passed to {@link aggregateValue} and optionally aliased.
+ * The results are joined with commas for use in a SELECT clause.
+ *
+ * @param {Object[]} values - Array of aggregation specifications.
+ * @param {string} values[].column - The column to aggregate.
+ * @param {'max'|'min'|'first'|'last'|'any'} values[].aggregateType - Type of aggregation.
+ * @param {string} [values[].timestampColumn] - Column for ordering. Required for 'first'/'last'.
+ * @param {string} [values[].alias] - Optional output alias (appended as `AS alias`).
+ * @returns {string} Comma-separated SQL aggregation expressions.
+ * @throws {Error} If values is not an array.
+ */
 const aggregateValues = (values) => {
   if (Array.isArray(values)) {
     return values.map(value => {

package/helpers/dateTime.js

@@ -2,9 +2,11 @@
 Date and time
 */
 
+/**
+ * SQL expression that casts the GA4 `event_date` string column to a DATE using YYYYMMDD format.
+ */
 const eventDate = `cast(event_date as date format 'YYYYMMDD')`;
 
-// get the most accurate event timestamp
 /**
  * Returns a SQL expression for the event timestamp in microseconds.
  *
@@ -28,7 +30,6 @@ const getEventTimestampMicros = (customTimestampParameter) => {
   return 'event_timestamp';
 };
 
-// datetime in the local time zone
 /**
  * Returns a SQL expression representing the event's local datetime (in the specified time zone),
  * derived from the default event_timestamp field.
@@ -37,7 +38,7 @@ const getEventTimestampMicros = (customTimestampParameter) => {
  * - No custom timestamp parameter from event_params is used; the extraction is strictly from event_timestamp.
  * - The returned expression converts event_timestamp to a TIMESTAMP, then extracts the DATETIME in the desired time zone.
  *
- * @param {Object} config - Optional configuration with a timezone property (defaults to 'Etc/UTC').
+ * @param {Object} [config] - Optional configuration with a timezone property (defaults to 'Etc/UTC').
  * @param {string} [config.timezone] - IANA time zone string (e.g., 'Europe/Helsinki'). Defaults to 'Etc/UTC'.
  * @returns {string} SQL expression for the local datetime of the event.
  *

package/helpers/ga4Transforms.js

@@ -1,9 +1,8 @@
 const { unnestEventParam } = require('./params');
 
-/*
-Common identifiers
-*/
-
+/**
+ * SQL expression that builds a session ID by concatenating `user_pseudo_id` with the `ga_session_id` event parameter.
+ */
 const sessionId = `concat(user_pseudo_id, (select value.int_value from unnest(event_params) where key = 'ga_session_id'))`;
 
 /*
@@ -58,7 +57,7 @@ Check if GA4 data is "final" and is not expected to change anymore
  * @param {'EXPORT_TYPE'|'DAY_THRESHOLD'} detectionMethod - The method to use for finality determination.
  *        'EXPORT_TYPE': Uses patterns in _table_suffix (e.g., 'intraday_%', 'fresh_%').
  *        'DAY_THRESHOLD': Uses date difference between the current date and event_date.
- * @param {number} [dayThreshold=3] - (Only for 'DAY_THRESHOLD') Number of days after which data is considered final.
+ * @param {number} [dayThreshold] - (Only for 'DAY_THRESHOLD') Number of days after which data is considered final. Required when detectionMethod is 'DAY_THRESHOLD'.
  * @returns {string} SQL expression that evaluates to TRUE if the data is final, otherwise FALSE.
  *
  * @throws {Error} If an unsupported detectionMethod is provided.
@@ -141,6 +140,15 @@ const isGa4ExportColumn = (columnName) => {
   return ga4ExportColumns.includes(columnName);
 };
 
+/**
+ * Generates a SQL CASE expression that determines the GA4 export type from a table suffix.
+ *
+ * Returns 'intraday' for suffixes like 'intraday_%', 'fresh' for 'fresh_%',
+ * and 'daily' for 8-digit date suffixes (YYYYMMDD).
+ *
+ * @param {string} tableSuffix - SQL expression or column reference for the table suffix (e.g., '_table_suffix').
+ * @returns {string} SQL CASE expression that evaluates to 'intraday', 'fresh', or 'daily'.
+ */
 const getGa4ExportType = (tableSuffix) => {
   return `case
       when ${tableSuffix} like 'intraday_%' then 'intraday'

package/helpers/params.js

@@ -2,7 +2,20 @@
 Unnesting parameters
 */
 
-// unnest any parameter from the selected params array
+/**
+ * Generates a SQL subquery to extract a value from a parameter array by key.
+ *
+ * When a dataType is provided, the value is extracted from the corresponding typed column
+ * (e.g., `value.string_value`, `value.int_value`). When omitted, a coalesce across all
+ * value columns is returned, cast as a string.
+ *
+ * @param {string} keyName - The parameter key to look up in the array.
+ * @param {string} paramsArray - The SQL expression for the parameter array to unnest (e.g., 'event_params').
+ * @param {string} [dataType] - Optional data type: 'string', 'int', 'int64', 'double', 'float', or 'float64'.
+ *                               If omitted, returns the value converted to a string.
+ * @returns {string} SQL subquery expression that extracts the parameter value.
+ * @throws {Error} If keyName or paramsArray is not a non-empty string, or if dataType is unsupported.
+ */
 const unnestParam = (keyName, paramsArray, dataType) => {
   if (typeof keyName !== 'string' || keyName.trim() === '') {
     throw new Error("unnestParam: 'keyName' is required and must be a non-empty string.");
@@ -30,14 +43,30 @@ const unnestParam = (keyName, paramsArray, dataType) => {
   }
 };
 
-// event_params and session_params
-
-// unnest a param from the event_params array
+/**
+ * Extracts a value from the `event_params` array by key.
+ *
+ * Supported types: 'string', 'int', 'int64', 'double', 'float', 'float64'.
+ * If omitted, returns the value converted to a string.
+ *
+ * @param {string} keyName - The event parameter key to look up.
+ * @param {string} [dataType] - Optional data type for the extracted value.
+ * @returns {string} SQL subquery expression that extracts the event parameter value.
+ */
 const unnestEventParam = (keyName, dataType) => {
   return unnestParam(keyName, 'event_params', dataType);
 };
 
-// unnest a param from the session_params array
+/**
+ * Extracts a value from the `session_params` array by key.
+ *
+ * Supported types: 'string', 'int', 'int64', 'double', 'float', 'float64'.
+ * If omitted, returns the value converted to a string.
+ *
+ * @param {string} keyName - The session parameter key to look up.
+ * @param {string} [dataType] - Optional data type for the extracted value.
+ * @returns {string} SQL subquery expression that extracts the session parameter value.
+ */
 const unnestSessionParam = (keyName, dataType) => {
   return unnestParam(keyName, 'session_params', dataType);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ga4-export-fixer",
-  "version": "0.4.2-dev.0",
+  "version": "0.4.2-dev.1",
   "description": "",
   "main": "index.js",
   "files": [