@levi-gemcommerce/analytics 2.0.5-dev.1 → 2.1.0-test.0

package/dist/esm/core/gemxql/builder/build-gemxql-query.mjs

@@ -0,0 +1,42 @@
+import { getFirstMetricInOrderBy } from './filters/build-filter-conditions.mjs';
+import { isValidQueryInput } from './helpers/is-valid-query-input.mjs';
+import { buildTimeSeriesQuery as build$4 } from './clauses/time-series-query.mjs';
+import { buildConditionQuery as build$7 } from './clauses/condition-query.mjs';
+import { buildTimezoneQuery as build$6 } from './clauses/timezone-query.mjs';
+import { buildOrderByQuery as build$8 } from './clauses/order-by-query.mjs';
+import { buildOffsetQuery as build$a } from './clauses/offset-query.mjs';
+import { buildLimitQuery as build$9 } from './clauses/limit-query.mjs';
+import { buildGroupQuery as build$3 } from './clauses/group-query.mjs';
+import { buildTimeQuery as build$5 } from './clauses/time-query.mjs';
+import { buildShowQuery as build$2 } from './clauses/show-query.mjs';
+import { buildModeQuery as build } from './clauses/mode-query.mjs';
+import { buildFromQuery as build$1 } from './clauses/from-query.mjs';
+import './configs/keywords.mjs';
+import { DEFAULT_QUERY_LIMIT } from './configs/query-defaults.mjs';
+
+const buildGemXQlQuery = (params) => {
+    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 = [
+        build(mode),
+        build$1(sources),
+        build$2(metrics),
+        build$3(dimensions, groupWithClause),
+        build$4(timeDimension),
+        build$5({ dateRange, compareDateRange, timeDimension, overrideFilters }),
+        build$6(timezone),
+        build$7({ filters, overrideFilters, versionIds, extraConditions }),
+        build$8(orderBy, columns),
+        build$9(limit),
+        build$a(offset),
+    ]
+        .filter(Boolean)
+        .join(' ');
+    return isValidQueryInput(builtQuery) ? builtQuery : '';
+};
+
+export { buildGemXQlQuery };

package/dist/esm/core/gemxql/builder/clauses/condition-query.d.ts

@@ -1,5 +1,5 @@
-import type { GemXQlFilters, GemXQlVersionIds, IExtraCondition } from '../../types';
 import type { IBuildFilterConditionsParams, IBuildVersionIdConditionParams } from '../filters/build-filter-conditions';
+import type { GemXQlFilters, GemXQlVersionIds, IExtraCondition } from '../../types';
 export interface IBuildConditionQueryParams extends IBuildFilterConditionsParams, IBuildVersionIdConditionParams {
     extraConditions?: IExtraCondition[];
 }
@@ -7,6 +7,6 @@ export type IParseConditionQueryResult = {
     filters: GemXQlFilters;
     versionIds?: GemXQlVersionIds;
 };
-declare const build: ({ filters, overrideFilters, versionIds, extraConditions }: IBuildConditionQueryParams) => string;
+declare const build: ({ filters, overrideFilters, versionIds, extraConditions, }: IBuildConditionQueryParams) => string;
 declare const parse: (query: string) => IParseConditionQueryResult;
 export { build as buildConditionQuery, parse as parseConditionQuery };

package/dist/esm/core/gemxql/builder/clauses/condition-query.js

@@ -0,0 +1,57 @@
+import { generateFilterConditions, buildVersionIdCondition, filterConfigs } from '../filters/build-filter-conditions.js';
+import { buildExtraConditions } from '../filters/build-extra-conditions.js';
+import { OPERATOR_IS_ONE_OF, OPERATOR_IS } from '../../constants/operators.js';
+import '../../constants/row-reader-mode.js';
+import { CLAUSE_KEYWORD_BOUNDARY } from '../configs/keywords.js';
+
+const build = ({ filters, overrideFilters, versionIds, extraConditions, }) => {
+    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) => {
+    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 = {};
+    const versionIds = {};
+    const unquoteStr = (v) => 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,
+        versionIds: Object.keys(versionIds).length > 0 ? versionIds : undefined,
+    };
+};
+
+export { build as buildConditionQuery, parse as parseConditionQuery };

package/dist/esm/core/gemxql/builder/clauses/condition-query.mjs

@@ -0,0 +1,57 @@
+import { generateFilterConditions, buildVersionIdCondition, filterConfigs } from '../filters/build-filter-conditions.mjs';
+import { buildExtraConditions } from '../filters/build-extra-conditions.mjs';
+import { OPERATOR_IS_ONE_OF, OPERATOR_IS } from '../../constants/operators.mjs';
+import '../../constants/row-reader-mode.mjs';
+import { CLAUSE_KEYWORD_BOUNDARY } from '../configs/keywords.mjs';
+
+const build = ({ filters, overrideFilters, versionIds, extraConditions, }) => {
+    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) => {
+    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 = {};
+    const versionIds = {};
+    const unquoteStr = (v) => 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,
+        versionIds: Object.keys(versionIds).length > 0 ? versionIds : undefined,
+    };
+};
+
+export { build as buildConditionQuery, parse as parseConditionQuery };

package/dist/esm/core/gemxql/builder/clauses/from-query.js

@@ -0,0 +1,14 @@
+import { CLAUSE_KEYWORD_BOUNDARY } from '../configs/keywords.js';
+
+const build = (sources) => `FROM ${sources.join(', ')}`;
+const parse = (query) => {
+    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/dist/esm/core/gemxql/builder/clauses/from-query.mjs

@@ -0,0 +1,14 @@
+import { CLAUSE_KEYWORD_BOUNDARY } from '../configs/keywords.mjs';
+
+const build = (sources) => `FROM ${sources.join(', ')}`;
+const parse = (query) => {
+    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/dist/esm/core/gemxql/builder/clauses/group-query.js

@@ -0,0 +1,42 @@
+import { CLAUSE_KEYWORD_BOUNDARY } from '../configs/keywords.js';
+import '../../types/analytic-data.js';
+import '../../types/analytic-source.js';
+import '../../types/extra-condition.js';
+import '../../types/field-filters.js';
+import '../../types/field-operators.js';
+import { EGroupWithClause } from '../../types/group-with-clause.js';
+import '../../types/order-by.js';
+import '../../types/page-fields.js';
+import '../../types/row-reader-mode.js';
+import '../../types/time-dimension.js';
+
+const build = (dimensions, withClause = EGroupWithClause.ALL) => dimensions.length === 0 ? '' : `GROUP BY ${dimensions.join(', ')} ${withClause}`;
+const parse = (query) => {
+    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/dist/esm/core/gemxql/builder/clauses/group-query.mjs

@@ -0,0 +1,42 @@
+import { CLAUSE_KEYWORD_BOUNDARY } from '../configs/keywords.mjs';
+import '../../types/analytic-data.mjs';
+import '../../types/analytic-source.mjs';
+import '../../types/extra-condition.mjs';
+import '../../types/field-filters.mjs';
+import '../../types/field-operators.mjs';
+import { EGroupWithClause } from '../../types/group-with-clause.mjs';
+import '../../types/order-by.mjs';
+import '../../types/page-fields.mjs';
+import '../../types/row-reader-mode.mjs';
+import '../../types/time-dimension.mjs';
+
+const build = (dimensions, withClause = EGroupWithClause.ALL) => dimensions.length === 0 ? '' : `GROUP BY ${dimensions.join(', ')} ${withClause}`;
+const parse = (query) => {
+    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/dist/esm/core/gemxql/builder/clauses/limit-query.js

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

package/dist/esm/core/gemxql/builder/clauses/limit-query.mjs

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

package/dist/esm/core/gemxql/builder/clauses/mode-query.d.ts

@@ -1,4 +1,4 @@
-import type { EAnalyticMode } from '@/types';
+import type { EAnalyticMode } from '../../../../types';
 export interface IBuildModeQueryParams {
     mode: EAnalyticMode;
 }

package/dist/esm/core/gemxql/builder/clauses/mode-query.js

@@ -0,0 +1,7 @@
+const build = (mode) => `MODE ${mode}`;
+const parse = (query) => {
+    const match = query.match(/\bMODE\s+(\S+)/i);
+    return match?.[1];
+};
+
+export { build as buildModeQuery, parse as parseModeQuery };

package/dist/esm/core/gemxql/builder/clauses/mode-query.mjs

@@ -0,0 +1,7 @@
+const build = (mode) => `MODE ${mode}`;
+const parse = (query) => {
+    const match = query.match(/\bMODE\s+(\S+)/i);
+    return match?.[1];
+};
+
+export { build as buildModeQuery, parse as parseModeQuery };

package/dist/esm/core/gemxql/builder/clauses/offset-query.js

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

package/dist/esm/core/gemxql/builder/clauses/offset-query.mjs

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

package/dist/esm/core/gemxql/builder/clauses/order-by-query.js

@@ -0,0 +1,29 @@
+import { CLAUSE_KEYWORD_BOUNDARY } from '../configs/keywords.js';
+
+const build = (orderBy, columns) => {
+    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) => {
+    const match = query.match(new RegExp(`\\bORDER BY\\s+([\\s\\S]+?)(?=\\s+(?:${CLAUSE_KEYWORD_BOUNDARY})\\b|$)`, 'i'));
+    if (!match)
+        return undefined;
+    const orderBy = {};
+    (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 };
+        }
+    });
+    return Object.keys(orderBy).length > 0 ? orderBy : undefined;
+};
+
+export { build as buildOrderByQuery, parse as parseOrderByQuery };

package/dist/esm/core/gemxql/builder/clauses/order-by-query.mjs

@@ -0,0 +1,29 @@
+import { CLAUSE_KEYWORD_BOUNDARY } from '../configs/keywords.mjs';
+
+const build = (orderBy, columns) => {
+    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) => {
+    const match = query.match(new RegExp(`\\bORDER BY\\s+([\\s\\S]+?)(?=\\s+(?:${CLAUSE_KEYWORD_BOUNDARY})\\b|$)`, 'i'));
+    if (!match)
+        return undefined;
+    const orderBy = {};
+    (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 };
+        }
+    });
+    return Object.keys(orderBy).length > 0 ? orderBy : undefined;
+};
+
+export { build as buildOrderByQuery, parse as parseOrderByQuery };

package/dist/esm/core/gemxql/builder/clauses/show-query.js

@@ -0,0 +1,14 @@
+import { CLAUSE_KEYWORD_BOUNDARY } from '../configs/keywords.js';
+
+const build = (metrics) => `SHOW ${metrics.join(', ')}`;
+const parse = (query) => {
+    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/dist/esm/core/gemxql/builder/clauses/show-query.mjs

@@ -0,0 +1,14 @@
+import { CLAUSE_KEYWORD_BOUNDARY } from '../configs/keywords.mjs';
+
+const build = (metrics) => `SHOW ${metrics.join(', ')}`;
+const parse = (query) => {
+    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/dist/esm/core/gemxql/builder/clauses/time-query.d.ts

@@ -1,5 +1,5 @@
 import type { GemXQlFilters, GemXQlOverrideFilters } from '../../types';
-import type { AnalyticDateFilter } from '@/components';
+import type { AnalyticDateFilter } from '../../../../components';
 export interface IBuildTimeQueryParams {
     dateRange?: AnalyticDateFilter;
     compareDateRange?: AnalyticDateFilter;

package/dist/esm/core/gemxql/builder/clauses/time-query.js

@@ -0,0 +1,50 @@
+import { getDateRangeForQuery } from '../helpers/date-query-helpers.js';
+import { dayjsTz } from '../../../../utils/dayjs.js';
+import '../../../../utils/analytics.js';
+import '../../../../types/template.js';
+
+const buildOverrideTimeQuery = (key, value) => `DURING (${value}, ${key})`;
+const build = (data) => {
+    const { dateRange, compareDateRange, overrideFilters, timeDimension } = data;
+    const overrideTimeValue = timeDimension
+        ? overrideFilters?.[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) => {
+    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() },
+        };
+    }
+    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/dist/esm/core/gemxql/builder/clauses/time-query.mjs

@@ -0,0 +1,50 @@
+import { getDateRangeForQuery } from '../helpers/date-query-helpers.mjs';
+import { dayjsTz } from '../../../../utils/dayjs.mjs';
+import '../../../../utils/analytics.mjs';
+import '../../../../types/template.mjs';
+
+const buildOverrideTimeQuery = (key, value) => `DURING (${value}, ${key})`;
+const build = (data) => {
+    const { dateRange, compareDateRange, overrideFilters, timeDimension } = data;
+    const overrideTimeValue = timeDimension
+        ? overrideFilters?.[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) => {
+    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() },
+        };
+    }
+    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/dist/esm/core/gemxql/builder/clauses/time-series-query.js

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

package/dist/esm/core/gemxql/builder/clauses/time-series-query.mjs

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

package/dist/esm/core/gemxql/builder/clauses/timezone-query.js

@@ -0,0 +1,14 @@
+import { getInitialTimezone } from '../../../../utils/dayjs.js';
+import '../../../../utils/analytics.js';
+import '../../../../types/template.js';
+
+const build = (timezone) => {
+    const tz = timezone ?? getInitialTimezone();
+    return tz ? `TIMEZONE ${tz}` : '';
+};
+const parse = (query) => {
+    const match = query.match(/\bTIMEZONE\s+(\S+)/i);
+    return match?.[1];
+};
+
+export { build as buildTimezoneQuery, parse as parseTimezoneQuery };

package/dist/esm/core/gemxql/builder/clauses/timezone-query.mjs

@@ -0,0 +1,14 @@
+import { getInitialTimezone } from '../../../../utils/dayjs.mjs';
+import '../../../../utils/analytics.mjs';
+import '../../../../types/template.mjs';
+
+const build = (timezone) => {
+    const tz = timezone ?? getInitialTimezone();
+    return tz ? `TIMEZONE ${tz}` : '';
+};
+const parse = (query) => {
+    const match = query.match(/\bTIMEZONE\s+(\S+)/i);
+    return match?.[1];
+};
+
+export { build as buildTimezoneQuery, parse as parseTimezoneQuery };

package/dist/esm/core/gemxql/builder/configs/date-formats.js

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

package/dist/esm/core/gemxql/builder/configs/date-formats.mjs

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

package/dist/esm/core/gemxql/builder/configs/keywords.js

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