@levi-gemcommerce/analytics 2.1.0-test.0 → 3.0.1-dev.3

package/src/core/gemxql/builder/build-gemxql-query.ts

@@ -0,0 +1,81 @@
+import type { IBuildConditionQueryParams } from './clauses/condition-query';
+import type { IBuildFromQueryParams } from './clauses/from-query';
+import type { IBuildGroupQueryParams } from './clauses/group-query';
+import type { IBuildLimitQueryParams } from './clauses/limit-query';
+import type { IBuildModeQueryParams } from './clauses/mode-query';
+import type { IBuildOffsetQueryParams } from './clauses/offset-query';
+import type { IBuildOrderByQueryParams } from './clauses/order-by-query';
+import type { IBuildShowQueryParams } from './clauses/show-query';
+import type { IBuildTimeQueryParams } from './clauses/time-query';
+import type { IBuildTimeSeriesQueryParams } from './clauses/time-series-query';
+import type { IBuildTimezoneQueryParams } from './clauses/timezone-query';
+
+import { buildConditionQuery } from './clauses/condition-query';
+import { buildFromQuery } from './clauses/from-query';
+import { buildGroupQuery } from './clauses/group-query';
+import { buildLimitQuery } from './clauses/limit-query';
+import { buildModeQuery } from './clauses/mode-query';
+import { buildOffsetQuery } from './clauses/offset-query';
+import { buildOrderByQuery } from './clauses/order-by-query';
+import { buildShowQuery } from './clauses/show-query';
+import { buildTimeQuery } from './clauses/time-query';
+import { buildTimeSeriesQuery } from './clauses/time-series-query';
+import { buildTimezoneQuery } from './clauses/timezone-query';
+import { DEFAULT_QUERY_LIMIT } from './configs';
+import { getFirstMetricInOrderBy } from './filters/build-filter-conditions';
+import { isValidQueryInput } from './helpers/is-valid-query-input';
+
+export type IBuildGemXQlQueryParams = IBuildModeQueryParams &
+  IBuildFromQueryParams &
+  IBuildShowQueryParams &
+  IBuildGroupQueryParams &
+  IBuildTimeQueryParams &
+  IBuildTimeSeriesQueryParams &
+  IBuildTimezoneQueryParams &
+  IBuildOrderByQueryParams &
+  IBuildConditionQueryParams &
+  IBuildLimitQueryParams &
+  IBuildOffsetQueryParams & {
+    extraOrderByFields?: string[];
+  };
+
+export const buildGemXQlQuery = (params: IBuildGemXQlQueryParams) => {
+  const {
+    mode,
+    metrics,
+    dimensions,
+    dateRange,
+    compareDateRange,
+    filters,
+    overrideFilters,
+    versionIds,
+    extraConditions,
+    orderBy,
+    sources,
+    timeDimension,
+    groupWithClause,
+    timezone,
+    limit = DEFAULT_QUERY_LIMIT,
+    offset,
+    extraOrderByFields,
+  } = params;
+  const columns = [...dimensions, ...getFirstMetricInOrderBy(orderBy, metrics), ...(extraOrderByFields ?? [])];
+
+  const builtQuery = [
+    buildModeQuery(mode),
+    buildFromQuery(sources),
+    buildShowQuery(metrics),
+    buildGroupQuery(dimensions, groupWithClause),
+    buildTimeSeriesQuery(timeDimension),
+    buildTimeQuery({ dateRange, compareDateRange, timeDimension, overrideFilters }),
+    buildTimezoneQuery(timezone),
+    buildConditionQuery({ filters, overrideFilters, versionIds, extraConditions }),
+    buildOrderByQuery(orderBy, columns),
+    buildLimitQuery(limit),
+    buildOffsetQuery(offset),
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return isValidQueryInput(builtQuery) ? builtQuery : '';
+};

package/src/core/gemxql/builder/clauses/condition-query.ts

@@ -0,0 +1,74 @@
+import type { GemXQlFilters, GemXQlVersionIds, IExtraCondition } from '../../types';
+import type { IBuildFilterConditionsParams, IBuildVersionIdConditionParams } from '../filters/build-filter-conditions';
+
+import { OPERATOR_IS, OPERATOR_IS_ONE_OF } from '../../constants';
+import { CLAUSE_KEYWORD_BOUNDARY } from '../configs';
+import { buildExtraConditions } from '../filters/build-extra-conditions';
+import { buildVersionIdCondition, filterConfigs, generateFilterConditions } from '../filters/build-filter-conditions';
+
+export interface IBuildConditionQueryParams extends IBuildFilterConditionsParams, IBuildVersionIdConditionParams {
+  extraConditions?: IExtraCondition[];
+}
+
+export type IParseConditionQueryResult = {
+  filters: GemXQlFilters;
+  versionIds?: GemXQlVersionIds;
+};
+
+const build = ({ filters, overrideFilters, versionIds, extraConditions }: IBuildConditionQueryParams) => {
+  const conditions = generateFilterConditions(filters, overrideFilters);
+  const versionIdConditions = buildVersionIdCondition(versionIds);
+  const builtExtraConditions = buildExtraConditions(extraConditions);
+
+  const allConditions = [...conditions, ...versionIdConditions, ...builtExtraConditions];
+
+  return allConditions.length > 0 ? `WHERE ${allConditions.join(' AND ')}` : '';
+};
+
+const parse = (query: string): IParseConditionQueryResult => {
+  const match = query.match(new RegExp(`\\bWHERE\\s+([\\s\\S]+?)(?=\\s+(?:${CLAUSE_KEYWORD_BOUNDARY})\\b|$)`, 'i'));
+  if (!match) return { filters: {} };
+
+  const conditions = (match[1] ?? '').trim().split(/\s+AND\s+/i);
+  const filters: Record<string, unknown> = {};
+  const versionIds: Record<string, string> = {};
+
+  const unquoteStr = (v: string): string => v.replace(/^'(.*)'$/s, '$1').replace(/''/g, "'");
+
+  conditions.forEach((condition) => {
+    const trimmed = condition.trim();
+
+    const inMatch = trimmed.match(/^(\S+)\s+IN\s+\((.+)\)$/i);
+    if (inMatch) {
+      const field = inMatch[1] ?? '';
+      const valuesStr = inMatch[2] ?? '';
+      const values = valuesStr.split(',').map((v) => unquoteStr(v.trim()));
+      const config = filterConfigs.find((c) => c.fieldName === field || c.multiField === field);
+      if (config?.operator) {
+        filters[config.multiField] = values;
+        filters[config.operator] = OPERATOR_IS_ONE_OF;
+      }
+      return;
+    }
+
+    const eqMatch = trimmed.match(/^(\S+)\s+=\s+(.+)$/);
+    if (eqMatch) {
+      const field = eqMatch[1] ?? '';
+      const value = unquoteStr(eqMatch[2] ?? '');
+      const config = filterConfigs.find((c) => c.fieldName === field || c.singleField === field);
+      if (config) {
+        filters[config.singleField] = value;
+        if (config.operator) filters[config.operator] = OPERATOR_IS;
+      } else if (field) {
+        versionIds[field] = value;
+      }
+    }
+  });
+
+  return {
+    filters: filters as GemXQlFilters,
+    versionIds: Object.keys(versionIds).length > 0 ? versionIds : undefined,
+  };
+};
+
+export { build as buildConditionQuery, parse as parseConditionQuery };

package/src/core/gemxql/builder/clauses/from-query.ts

@@ -0,0 +1,18 @@
+import { CLAUSE_KEYWORD_BOUNDARY } from '../configs';
+
+export interface IBuildFromQueryParams {
+  sources: string[];
+}
+
+const build = (sources: string[]) => `FROM ${sources.join(', ')}`;
+
+const parse = (query: string): string[] => {
+  const match = query.match(new RegExp(`\\bFROM\\s+([\\s\\S]+?)(?=\\s+(?:${CLAUSE_KEYWORD_BOUNDARY})\\b|$)`, 'i'));
+  if (!match) return [];
+  return (match[1] ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+};
+
+export { build as buildFromQuery, parse as parseFromQuery };

package/src/core/gemxql/builder/clauses/group-query.ts

@@ -0,0 +1,43 @@
+import { EGroupWithClause } from '../../types';
+import { CLAUSE_KEYWORD_BOUNDARY } from '../configs';
+
+export interface IBuildGroupQueryParams {
+  dimensions: string[];
+  groupWithClause?: EGroupWithClause;
+}
+
+const build = (dimensions: string[], withClause = EGroupWithClause.ALL) =>
+  dimensions.length === 0 ? '' : `GROUP BY ${dimensions.join(', ')} ${withClause}`;
+
+const parse = (query: string): { dimensions: string[]; groupWithClause?: EGroupWithClause } => {
+  const match = query.match(new RegExp(`\\bGROUP BY\\s+([\\s\\S]+?)(?=\\s+(?:${CLAUSE_KEYWORD_BOUNDARY})\\b|$)`, 'i'));
+  if (!match) return { dimensions: [] };
+
+  let content = (match[1] ?? '').trim();
+
+  // Detect the trailing with-clause token (e.g. `WITH GROUP_TOTALS, TOTALS` or `TOTALS`).
+  // Derive tokens from the enum and check longest-first so `ALL` is not mistaken for `TOTALS`.
+  const clauseTokens = Object.values(EGroupWithClause)
+    .filter((token) => token !== EGroupWithClause.NONE)
+    .sort((a, b) => b.length - a.length);
+
+  let groupWithClause = EGroupWithClause.NONE;
+  const upperContent = content.toUpperCase();
+  for (const token of clauseTokens) {
+    if (upperContent.endsWith(token)) {
+      groupWithClause = token;
+      content = content.slice(0, content.length - token.length).trim();
+      break;
+    }
+  }
+
+  return {
+    dimensions: content
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean),
+    groupWithClause,
+  };
+};
+
+export { build as buildGroupQuery, parse as parseGroupQuery };

package/src/core/gemxql/builder/clauses/index.ts

@@ -0,0 +1,11 @@
+export * from './condition-query';
+export * from './from-query';
+export * from './group-query';
+export * from './limit-query';
+export * from './mode-query';
+export * from './offset-query';
+export * from './order-by-query';
+export * from './show-query';
+export * from './time-query';
+export * from './time-series-query';
+export * from './timezone-query';

package/src/core/gemxql/builder/clauses/limit-query.ts

@@ -0,0 +1,15 @@
+export interface IBuildLimitQueryParams {
+  limit?: number;
+}
+
+const build = (limit?: number) => {
+  if (!limit) return '';
+  return `LIMIT ${limit}`;
+};
+
+const parse = (query: string): number | undefined => {
+  const match = query.match(/\bLIMIT\s+(\d+)/i);
+  return match ? parseInt(match[1] ?? '0', 10) : undefined;
+};
+
+export { build as buildLimitQuery, parse as parseLimitQuery };

package/src/core/gemxql/builder/clauses/mode-query.ts

@@ -0,0 +1,14 @@
+import type { EAnalyticMode } from '@/types';
+
+export interface IBuildModeQueryParams {
+  mode: EAnalyticMode;
+}
+
+const build = (mode: EAnalyticMode) => `MODE ${mode}`;
+
+const parse = (query: string): EAnalyticMode | undefined => {
+  const match = query.match(/\bMODE\s+(\S+)/i);
+  return match?.[1] as EAnalyticMode | undefined;
+};
+
+export { build as buildModeQuery, parse as parseModeQuery };

package/src/core/gemxql/builder/clauses/offset-query.ts

@@ -0,0 +1,15 @@
+export interface IBuildOffsetQueryParams {
+  offset?: number;
+}
+
+const build = (offset?: number) => {
+  if (!offset || offset < 0) return '';
+  return `OFFSET ${offset}`;
+};
+
+const parse = (query: string): number | undefined => {
+  const match = query.match(/\bOFFSET\s+(\d+)/i);
+  return match ? parseInt(match[1] ?? '0', 10) : undefined;
+};
+
+export { build as buildOffsetQuery, parse as parseOffsetQuery };

package/src/core/gemxql/builder/clauses/order-by-query.ts

@@ -0,0 +1,37 @@
+import type { EOrderDirectionType, OrderByFields } from '../../types';
+
+import { CLAUSE_KEYWORD_BOUNDARY } from '../configs';
+
+export interface IBuildOrderByQueryParams {
+  orderBy?: OrderByFields;
+}
+
+const build = (orderBy?: OrderByFields, columns?: string[]) => {
+  if (!orderBy) return '';
+
+  const orderByQuery = Object.values(orderBy)
+    .filter((item) => columns?.includes(item.field))
+    .map((item) => `${item.field} ${item.direction}`)
+    .join(', ');
+
+  return orderByQuery ? `ORDER BY ${orderByQuery}` : '';
+};
+
+const parse = (query: string): OrderByFields | undefined => {
+  const match = query.match(new RegExp(`\\bORDER BY\\s+([\\s\\S]+?)(?=\\s+(?:${CLAUSE_KEYWORD_BOUNDARY})\\b|$)`, 'i'));
+  if (!match) return undefined;
+
+  const orderBy: OrderByFields = {};
+  (match[1] ?? '').split(',').forEach((item) => {
+    const parts = item.trim().split(/\s+/);
+    if (parts.length === 2) {
+      const field = parts[0] ?? '';
+      const direction = parts[1] ?? '';
+      if (field) orderBy[field] = { field, direction: direction as EOrderDirectionType };
+    }
+  });
+
+  return Object.keys(orderBy).length > 0 ? orderBy : undefined;
+};
+
+export { build as buildOrderByQuery, parse as parseOrderByQuery };

package/src/core/gemxql/builder/clauses/show-query.ts

@@ -0,0 +1,18 @@
+import { CLAUSE_KEYWORD_BOUNDARY } from '../configs';
+
+export interface IBuildShowQueryParams {
+  metrics: string[];
+}
+
+const build = (metrics: string[]) => `SHOW ${metrics.join(', ')}`;
+
+const parse = (query: string): string[] => {
+  const match = query.match(new RegExp(`\\bSHOW\\s+([\\s\\S]+?)(?=\\s+(?:${CLAUSE_KEYWORD_BOUNDARY})\\b|$)`, 'i'));
+  if (!match) return [];
+  return (match[1] ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+};
+
+export { build as buildShowQuery, parse as parseShowQuery };

package/src/core/gemxql/builder/clauses/time-query.ts

@@ -0,0 +1,67 @@
+import type { GemXQlFilters, GemXQlOverrideFilters } from '../../types';
+import type { AnalyticDateFilter } from '@/components';
+
+import { dayjsTz } from '@/utils';
+import { getDateRangeForQuery } from '../helpers/date-query-helpers';
+
+export interface IBuildTimeQueryParams {
+  dateRange?: AnalyticDateFilter;
+  compareDateRange?: AnalyticDateFilter;
+  overrideFilters?: GemXQlOverrideFilters;
+  timeDimension?: string;
+}
+
+export type IParseTimeQueryResult = {
+  dateRange?: Pick<AnalyticDateFilter, 'startDate' | 'endDate'>;
+  compareDateRange?: Pick<AnalyticDateFilter, 'startDate' | 'endDate'>;
+  timeDimension?: string;
+  overrideFilters?: GemXQlFilters;
+};
+
+const buildOverrideTimeQuery = (key: string, value: string) => `DURING (${value}, ${key})`;
+
+const build = (data: IBuildTimeQueryParams) => {
+  const { dateRange, compareDateRange, overrideFilters, timeDimension } = data;
+  const overrideTimeValue = timeDimension
+    ? (overrideFilters as Record<string, string | undefined>)?.[timeDimension]
+    : undefined;
+
+  if (timeDimension && overrideTimeValue) {
+    return buildOverrideTimeQuery(timeDimension, overrideTimeValue);
+  }
+  if (!dateRange) return '';
+
+  const { dateGTE, dateLTE } = getDateRangeForQuery(dateRange);
+  const { dateGTE: compareDateGTE, dateLTE: compareDateLTE } = compareDateRange
+    ? getDateRangeForQuery(compareDateRange)
+    : {};
+  const compareToClause = compareDateRange ? `COMPARE TO ${compareDateGTE} UNTIL ${compareDateLTE}` : '';
+
+  return `SINCE ${dateGTE} UNTIL ${dateLTE} ${compareToClause}`;
+};
+
+const parse = (query: string): IParseTimeQueryResult => {
+  const duringMatch = query.match(/\bDURING\s+\(([^,]+),\s*([^)]+)\)/i);
+  if (duringMatch) {
+    const value = duringMatch[1] ?? '';
+    const key = duringMatch[2] ?? '';
+    return {
+      timeDimension: key.trim(),
+      overrideFilters: { [key.trim()]: value.trim() } as GemXQlFilters,
+    };
+  }
+
+  const sinceMatch = query.match(/\bSINCE\s+(\S+)\s+UNTIL\s+(\S+)/i);
+  if (!sinceMatch) return {};
+
+  const dateRange = { startDate: dayjsTz(sinceMatch[1] ?? ''), endDate: dayjsTz(sinceMatch[2] ?? '') };
+
+  const compareMatch = query.match(/\bCOMPARE TO\s+(\S+)\s+UNTIL\s+(\S+)/i);
+  const compareDateRange = compareMatch
+    ? { startDate: dayjsTz(compareMatch[1] ?? ''), endDate: dayjsTz(compareMatch[2] ?? '') }
+    : undefined;
+
+  return { dateRange, compareDateRange };
+};
+
+export { build as buildTimeQuery, parse as parseTimeQuery };

package/src/core/gemxql/builder/clauses/time-series-query.ts

@@ -0,0 +1,15 @@
+export interface IBuildTimeSeriesQueryParams {
+  timeDimension?: string;
+}
+
+const build = (time?: string) => {
+  if (!time) return '';
+  return `TIMESERIES ${time}`;
+};
+
+const parse = (query: string): string | undefined => {
+  const match = query.match(/\bTIMESERIES\s+(\S+)/i);
+  return match?.[1];
+};
+
+export { build as buildTimeSeriesQuery, parse as parseTimeSeriesQuery };

package/src/core/gemxql/builder/clauses/timezone-query.ts

@@ -0,0 +1,17 @@
+import { getInitialTimezone } from '@/utils';
+
+export interface IBuildTimezoneQueryParams {
+  timezone?: string;
+}
+
+const build = (timezone?: string) => {
+  const tz = timezone ?? getInitialTimezone();
+  return tz ? `TIMEZONE ${tz}` : '';
+};
+
+const parse = (query: string): string | undefined => {
+  const match = query.match(/\bTIMEZONE\s+(\S+)/i);
+  return match?.[1];
+};
+
+export { build as buildTimezoneQuery, parse as parseTimezoneQuery };

package/src/core/gemxql/builder/configs/date-formats.ts

@@ -0,0 +1 @@
+export const DATE_QUERY_FORMAT = 'YYYY-MM-DDTHH:mm:ss';

package/src/core/gemxql/builder/configs/index.ts

@@ -0,0 +1,3 @@
+export * from './date-formats';
+export * from './keywords';
+export * from './query-defaults';

package/src/core/gemxql/builder/configs/keywords.ts

@@ -0,0 +1,16 @@
+export const CLAUSE_KEYWORDS = [
+  'MODE',
+  'FROM',
+  'SHOW',
+  'GROUP BY',
+  'TIMESERIES',
+  'SINCE',
+  'DURING',
+  'TIMEZONE',
+  'WHERE',
+  'ORDER BY',
+  'LIMIT',
+  'OFFSET',
+] as const;
+
+export const CLAUSE_KEYWORD_BOUNDARY = CLAUSE_KEYWORDS.join('|');

package/src/core/gemxql/builder/configs/query-defaults.ts

@@ -0,0 +1 @@
+export const DEFAULT_QUERY_LIMIT = 1000;

package/src/core/gemxql/builder/filters/build-extra-conditions.ts

@@ -0,0 +1,69 @@
+import type {
+  IExtraCondition,
+  IExtraConditionEq,
+  IExtraConditionGroup,
+  IExtraConditionIn,
+  IExtraConditionLike,
+} from '../../types';
+
+import { EComparisonOperator, EGroupOperator } from '../../types';
+
+const DEFAULT_GROUP_OPERATOR = EGroupOperator.OR;
+
+// Serializes a value as a single-quoted DSL string literal. Numbers are passed through unquoted.
+const quoteValue = (v: string | number): string =>
+  typeof v === 'number' ? String(v) : `'${String(v).replace(/'/g, "''")}'`;
+
+const joinFieldClauses = (parts: string[], groupOperator: EGroupOperator = DEFAULT_GROUP_OPERATOR): string => {
+  if (!parts.length) return '';
+  if (parts.length === 1) return parts[0] ?? '';
+  return `(${parts.join(` ${groupOperator} `)})`;
+};
+
+const buildEq = ({ fields, value, groupOperator }: IExtraConditionEq) => {
+  if (!fields.length) return '';
+  return joinFieldClauses(
+    fields.map((field) => `${field} = ${quoteValue(value)}`),
+    groupOperator,
+  );
+};
+
+const buildIn = ({ fields, values, groupOperator }: IExtraConditionIn) => {
+  if (!fields.length || !values.length) return '';
+  return joinFieldClauses(
+    fields.map((field) => `${field} IN (${values.map(quoteValue).join(', ')})`),
+    groupOperator,
+  );
+};
+
+const buildLike = ({ fields, value, groupOperator }: IExtraConditionLike) => {
+  const trimmed = value.trim();
+  if (!trimmed || !fields.length) return '';
+  return joinFieldClauses(
+    fields.map((field) => `${field} LIKE '%${trimmed.replace(/'/g, "''")}%'`),
+    groupOperator,
+  );
+};
+
+const buildGroup = ({ conditions, groupOperator }: IExtraConditionGroup): string => {
+  const parts = conditions.map(buildExtraCondition).filter(Boolean);
+  return joinFieldClauses(parts, groupOperator);
+};
+
+export const buildExtraCondition = (condition: IExtraCondition): string => {
+  switch (condition.operator) {
+    case EComparisonOperator.EQ:
+      return buildEq(condition);
+    case EComparisonOperator.IN:
+      return buildIn(condition);
+    case EComparisonOperator.LIKE:
+      return buildLike(condition);
+    case EComparisonOperator.GROUP:
+      return buildGroup(condition);
+  }
+};
+
+export const buildExtraConditions = (conditions?: IExtraCondition[]): string[] => {
+  if (!conditions?.length) return [];
+  return conditions.map(buildExtraCondition).filter(Boolean);
+};