@narrative.io/data-collaboration-sdk-ts 0.0.51 → 0.0.52

package/build/index.d.ts

@@ -16,12 +16,14 @@ import { type PingStatus } from './ping/types';
 import { type Product, ProductsApi } from './products';
 import { CompanyInfoApi, type CompanyInfo } from './company-info';
 import { InstallationsApi, type Installation } from './installations';
-import { NqlApi, type NqlCompileResult, type NqlQuery, type NqlResult } from './nql';
+import { NqlApi, type NqlCompileResult, type NqlResult } from './nql';
 import { DataStreamsApi, type DataStream } from './data-streams';
 import { ForecastApi, type ForecastRequest, type ForecastResponse, type CostForecastRequest, type CostForecastResponse, type JobState } from './forecast';
 import { ContractsApi, type ContractDetails, type CustomerContract, type PaymentMethod, type ContractRateView } from './contracts';
+import { getNqlObject, buildNql } from './nql/NQLParser';
+import type { Nql, NqlQueryInput } from './nql/types';
 declare class NarrativeApi extends BaseApi {
 }
 interface NarrativeApi extends BaseApi, HealthCheckApi, DatasetApi, RosettaStoneApi, AttributeApi, PingApi, CompanyInfoApi, InstallationsApi, UploadsApi, ResourceApi, NqlApi, DataStreamsApi, ForecastApi, ContractsApi {
 }
-export { NarrativeApi, AttributeApi, HealthCheckApi, DatasetApi, PingApi, ProductsApi, CompanyInfoApi, InstallationsApi, UploadsApi, ResourceApi, NqlApi, DataStreamsApi, ForecastApi, ContractsApi, type Resource, type UploadsResponse, type PingStatus, type Attribute, type Environment, type Config, type ApiRecords, type Dataset, type HealthCheckResult, type SampleRecords, type DatasetTableSummary, type DatasetTableSummaryAPIResponse, type Product, type MonetaryAmount, type CompanyInfo, type Installation, type FilePerSnapshotResponse, type BucketCreationRequest, type UpdateAccessTypeRequest, type NqlQuery, type NqlResult, type NqlCompileResult, type DataStream, type ForecastRequest, type ForecastResponse, type CostForecastRequest, type CostForecastResponse, type JobState, type ContractDetails, type CustomerContract, type PaymentMethod, type ContractRateView };
+export { NarrativeApi, AttributeApi, HealthCheckApi, DatasetApi, PingApi, ProductsApi, CompanyInfoApi, InstallationsApi, UploadsApi, ResourceApi, NqlApi, DataStreamsApi, ForecastApi, ContractsApi, type Resource, type UploadsResponse, type PingStatus, type Attribute, type Environment, type Config, type ApiRecords, type Dataset, type HealthCheckResult, type SampleRecords, type DatasetTableSummary, type DatasetTableSummaryAPIResponse, type Product, type MonetaryAmount, type CompanyInfo, type Installation, type FilePerSnapshotResponse, type BucketCreationRequest, type UpdateAccessTypeRequest, type NqlQueryInput, type NqlResult, type NqlCompileResult, type DataStream, type ForecastRequest, type ForecastResponse, type CostForecastRequest, type CostForecastResponse, type JobState, type ContractDetails, type CustomerContract, type PaymentMethod, type ContractRateView, type Nql, getNqlObject, buildNql };

package/build/index.js

@@ -14,7 +14,8 @@ import { NqlApi } from './nql';
 import { DataStreamsApi } from './data-streams';
 import { ForecastApi } from './forecast';
 import { ContractsApi } from './contracts';
+import { getNqlObject, buildNql } from './nql/NQLParser';
 class NarrativeApi extends BaseApi {
 }
 applyMixins(NarrativeApi, [BaseApi, HealthCheckApi, DatasetApi, RosettaStoneApi, AttributeApi, PingApi, CompanyInfoApi, InstallationsApi, UploadsApi, ResourceApi, NqlApi, DataStreamsApi, ForecastApi, ContractsApi]);
-export { NarrativeApi, AttributeApi, HealthCheckApi, DatasetApi, PingApi, ProductsApi, CompanyInfoApi, InstallationsApi, UploadsApi, ResourceApi, NqlApi, DataStreamsApi, ForecastApi, ContractsApi };
+export { NarrativeApi, AttributeApi, HealthCheckApi, DatasetApi, PingApi, ProductsApi, CompanyInfoApi, InstallationsApi, UploadsApi, ResourceApi, NqlApi, DataStreamsApi, ForecastApi, ContractsApi, getNqlObject, buildNql };

package/build/nql/NQLParser.d.ts

@@ -0,0 +1,87 @@
+import { type Nql, type NqlBudget, type NqlField, type NqlPreSelectExpression, type NqlTable, type NqlWhere } from './types';
+/**
+ * Retrieves the WHERE clause from the given NQL (Nested Query Language) string and returns a parsed NqlWhereClause object.
+ *
+ * @param {string} nql - The NQL string to extract the WHERE clause from.
+ * @returns {NqlWhereClause} - The parsed NqlWhereClause object representing the WHERE clause.
+ * @throws {Error} - Throws an error if no WHERE clause is found in the NQL string.
+ */
+export declare function getWhere(nql: string): NqlWhere;
+/**
+ * Retrieves the tables from the given NQL (Nested Query Language) string and returns an array of parsed NqlTable objects.
+ *
+ * @param {string} nql - The NQL string to extract the tables from.
+ * @returns {NqlTable[]} - An array of parsed NqlTable objects representing the tables.
+ * @throws {Error} - Throws an error if no FROM clause is found in the NQL string.
+ */
+export declare function getFrom(nql: string): NqlTable[];
+/**
+ * Parses the pre-select expression from the given NQL (Natural Query Language) string.
+ *
+ * @function getPreSelect
+ * @param {string} nql - The NQL string to parse.
+ * @returns {NqlPreSelectExpression | undefined} - The parsed pre-select expression object, or `undefined` if no valid pre-select expression is found.
+ * @throws {Error} If the NQL string is invalid.
+ */
+export declare function getPreSelect(nql: string): NqlPreSelectExpression;
+/**
+ * Builds a pre-select expression for an NQL (Natural Query Language) query based on the provided pre-select expression.
+ *
+ * @param {NqlPreSelectExpression} preSelect - The pre-select expression.
+ * @returns {string} - The built pre-select expression string.
+ * @throws {Error} - If the provided pre-select expression is invalid.
+ */
+export declare function buildPreSelect(preSelect: NqlPreSelectExpression): string;
+/**
+ * Extracts and parses the selected fields from the given NQL (Natural Query Language) string.
+ *
+ * @function getSelect
+ * @param {string} nql - The NQL string containing the SELECT statement.
+ * @returns {NqlField[]} - An array of parsed NqlField objects representing the selected fields.
+ * @throws {Error} - If no selected fields are found or if a field is invalid.
+ */
+export declare function getSelect(nql: string): NqlField[];
+/**
+ * Builds a SELECT clause for an NQL (Natural Query Language) query based on the provided fields.
+ *
+ * @param {NqlField[]} fields - An array of NqlField objects representing the selected fields.
+ * @returns {string} - The built SELECT clause string.
+ * @throws {Error} - If any of the provided fields are invalid.
+ */
+export declare function buildSelect(fields: NqlField[]): string;
+/**
+ * Parses a string in NQL format and returns an NqlBudgetType object.
+ *
+ * @function getLimit
+ * @param {string} nql - The NQL string to parse.
+ * @returns {NqlBudget} - The parsed budget object.
+ * @throws {Error} If the NQL string is invalid.
+ */
+export declare function getLimit(nql: string): NqlBudget;
+/**
+ * Builds a LIMIT clause for an NQL (Narrative Query Language) query based on the provided budget object.
+ *
+ * @param {NqlBudget} budget - The budget object containing the limit values.
+ * @returns {string} - The LIMIT clause string.
+ * @throws {Error} - If the provided budget object is invalid.
+ */
+export declare function buildLimit(budget: NqlBudget): string;
+/**
+ * Builds an NQL (Nested Query Language) string based on the provided Nql object.
+ *
+ * @param {Nql} nql - The Nql object containing the clauses for building the NQL string.
+ * @returns {string} - The constructed NQL string.
+ * @throws {Error} - Throws an error if the provided Nql object is invalid.
+ */
+export declare function buildNql(nql: Nql): string;
+export declare function buildFrom(from: NqlTable): string;
+export declare function buildWhere(where: NqlWhere): string;
+export declare function buildField(field: NqlField | string | number | boolean): string;
+/**
+ * Parses the given NQL string and returns an Nql object.
+ *
+ * @param {string} nql - The NQL string to parse.
+ * @returns {Nql} - The parsed Nql object.
+ * @throws {Error} - If the provided NQL string is invalid.
+ */
+export declare function getNqlObject(nql: string): Nql;

package/build/nql/NQLParser.js

@@ -0,0 +1,335 @@
+import { NqlBooleanExpressionObj, NqlBudgetObj, NqlFieldObj, NqlFilterExpressionObj, NqlObj, NqlPreSelectExpressionObj, NqlTableObject, NqlWhereObj } from './types';
+/**
+ * Retrieves the WHERE clause from the given NQL (Nested Query Language) string and returns a parsed NqlWhereClause object.
+ *
+ * @param {string} nql - The NQL string to extract the WHERE clause from.
+ * @returns {NqlWhereClause} - The parsed NqlWhereClause object representing the WHERE clause.
+ * @throws {Error} - Throws an error if no WHERE clause is found in the NQL string.
+ */
+export function getWhere(nql) {
+    const regex = /\bWHERE\b(.*?)\bLIMIT\b/i;
+    const match = nql.trim().replace(/\n/g, ' ').match(regex);
+    if (match != null && match[1] !== '') {
+        const booleanExpressions = getBooleanExpressionsFromWhere(match[1]);
+        const filterExpressions = getFilterExpressionsFromWhere(match[1]);
+        return NqlWhereObj.parse({
+            booleanExpressions,
+            filterExpressions
+        });
+    }
+    else {
+        throw new Error('No WHERE clause found');
+    }
+}
+/**
+ * Retrieves the tables from the given NQL (Nested Query Language) string and returns an array of parsed NqlTable objects.
+ *
+ * @param {string} nql - The NQL string to extract the tables from.
+ * @returns {NqlTable[]} - An array of parsed NqlTable objects representing the tables.
+ * @throws {Error} - Throws an error if no FROM clause is found in the NQL string.
+ */
+export function getFrom(nql) {
+    const regex = /\bFROM\b(.*?)\bWHERE\b/i;
+    const match = nql.trim().replace(/\n/g, ' ').match(regex);
+    if (match != null && match[1] !== '') {
+        const tables = match[1].split(',').map((t) => {
+            const [database, table] = t.trim().split('.');
+            return NqlTableObject.parse({
+                database,
+                table
+            });
+        });
+        return tables;
+    }
+    else {
+        throw new Error('No FROM clause found');
+    }
+}
+/**
+ * Extracts boolean expressions from the WHERE clause string and returns an array of parsed NqlBooleanExpression objects.
+ *
+ * @param {string} where - The WHERE clause string.
+ * @returns {NqlBooleanExpression[]} - An array of parsed NqlBooleanExpression objects representing the boolean expressions.
+ */
+function getBooleanExpressionsFromWhere(where) {
+    const booleanRegex = /\b(OR|AND)\b/ig;
+    const matches = [];
+    let boolMatch;
+    while ((boolMatch = booleanRegex.exec(where)) !== null) {
+        matches.push(boolMatch[1].trim().toUpperCase());
+    }
+    return NqlBooleanExpressionObj.array().parse(matches);
+}
+/**
+ * Extracts filter expressions from the WHERE clause string and returns an array of parsed NqlFilterExpression objects.
+ *
+ * @param {string} where - The WHERE clause string.
+ * @returns {NqlFilterExpression[]} - An array of parsed NqlFilterExpression objects representing the filter expressions.
+ */
+function getFilterExpressionsFromWhere(where) {
+    let matches = [];
+    const hasBoolean = /\b(?:OR|AND)\b/ig.test(where);
+    if (!hasBoolean) {
+        matches.push(getFilterExpressionFromString(where));
+    }
+    else {
+        const expressions = where.split(/\b(?:OR|AND)\b/ig).map((t) => t.trim());
+        matches = matches.concat(expressions.map((e) => getFilterExpressionFromString(e)));
+    }
+    return NqlFilterExpressionObj.array().parse(matches);
+}
+/**
+ * Parses a field string into an NqlField object or returns the original field string if parsing fails.
+ *
+ * @param {string} fieldStr - The field string to parse.
+ * @returns {NqlField | string} - The parsed NqlField object or the original field string if parsing fails.
+ */
+function parseFieldFromString(fieldStr) {
+    const [database, table, ...f] = fieldStr.trim().split('.');
+    const field = {
+        table: {
+            database,
+            table
+        },
+        field: f.join('.')
+    };
+    try {
+        return NqlFieldObj.parse(field);
+    }
+    catch {
+        return parseString(fieldStr.trim());
+    }
+}
+/**
+ * Parses a string value as a number or boolean if valid, or keeps it as a string.
+ * @param {string} value - The string value to parse.
+ * @returns {string | number | boolean} - The parsed value, or the original string if parsing fails.
+ */
+function parseString(value) {
+    // Attempt to parse as a number
+    const parsedNumber = Number(value);
+    if (!isNaN(parsedNumber)) {
+        return parsedNumber;
+    }
+    // Attempt to parse as a boolean
+    if (value.toLowerCase() === 'true') {
+        return true;
+    }
+    if (value.toLowerCase() === 'false') {
+        return false;
+    }
+    // Return as string if it is neither a number nor boolean
+    return value;
+}
+/**
+ * Parses a field string into an NqlField object or a plain string if parsing fails.
+ *
+ * @param {string} fieldStr - The field string to parse.
+ * @returns {NqlField | string} - The parsed NqlField object or the original field string if parsing fails.
+ */
+function getFilterExpressionFromString(str) {
+    const comparison = ['<=', '>=', '!=', '=', '>', '<'];
+    const containsComparison = comparison.find((character) => str.includes(character));
+    if (containsComparison !== undefined) {
+        const result = str.split(containsComparison);
+        const left = parseFieldFromString(result[0]);
+        const operator = containsComparison.trim().toUpperCase();
+        const right = parseFieldFromString(result[1]);
+        return NqlFilterExpressionObj.parse({
+            left,
+            operator,
+            right
+        });
+    }
+    const strComparison = [' IN ', ' NOT IN ', ' LIKE ', ' NOT LIKE '];
+    const containsStrComparison = strComparison.find((character) => str.toLowerCase().includes(character.toLowerCase()));
+    if (containsStrComparison !== undefined) {
+        const result = str.split(containsStrComparison);
+        const left = parseFieldFromString(result[0]);
+        const operator = containsStrComparison.trim().toUpperCase();
+        const right = parseFieldFromString(result[1]);
+        return NqlFilterExpressionObj.parse({
+            left,
+            operator,
+            right
+        });
+    }
+    const unaryOperators = [' IS NULL', ' IS NOT NULL'];
+    const containsUnaryOperator = unaryOperators.find((character) => str.toLowerCase().includes(character.toLowerCase()));
+    if (containsUnaryOperator !== undefined) {
+        const result = str.split(containsUnaryOperator);
+        const field = parseFieldFromString(result[0]);
+        const operator = containsUnaryOperator.trim().toUpperCase();
+        return NqlFilterExpressionObj.parse({
+            field,
+            operator
+        });
+    }
+    throw new Error('Invalid filter expression');
+}
+/**
+ * Parses the pre-select expression from the given NQL (Natural Query Language) string.
+ *
+ * @function getPreSelect
+ * @param {string} nql - The NQL string to parse.
+ * @returns {NqlPreSelectExpression | undefined} - The parsed pre-select expression object, or `undefined` if no valid pre-select expression is found.
+ * @throws {Error} If the NQL string is invalid.
+ */
+export function getPreSelect(nql) {
+    /**
+     * A regular expression pattern to match the pre-select expression.
+     * The expression is located before the first occurrence of the word 'SELECT'.
+     * The match is case-insensitive.
+     */
+    const regex = /^(.*?)(?=SELECT)/i;
+    const match = nql.trim().replace(/\n/g, ' ').match(regex);
+    return match != null && match[1] !== '' ? NqlPreSelectExpressionObj.parse(match[1].toUpperCase().trim()) : undefined;
+}
+/**
+ * Builds a pre-select expression for an NQL (Natural Query Language) query based on the provided pre-select expression.
+ *
+ * @param {NqlPreSelectExpression} preSelect - The pre-select expression.
+ * @returns {string} - The built pre-select expression string.
+ * @throws {Error} - If the provided pre-select expression is invalid.
+ */
+export function buildPreSelect(preSelect) {
+    NqlPreSelectExpressionObj.parse(preSelect);
+    return preSelect ?? '';
+}
+/**
+ * Extracts and parses the selected fields from the given NQL (Natural Query Language) string.
+ *
+ * @function getSelect
+ * @param {string} nql - The NQL string containing the SELECT statement.
+ * @returns {NqlField[]} - An array of parsed NqlField objects representing the selected fields.
+ * @throws {Error} - If no selected fields are found or if a field is invalid.
+ */
+export function getSelect(nql) {
+    const regex = /SELECT\b(.*?)\bFROM/i;
+    const match = nql.trim().replace(/\n/g, ' ').match(regex);
+    if (match != null && match[1] !== '') {
+        const fields = match[1].trim().split(',');
+        return fields.map((f) => {
+            const trimmedFields = f.trim().split('.');
+            if (trimmedFields.length < 3) {
+                throw new Error('Invalid field');
+            }
+            const [database, table, ...field] = trimmedFields;
+            const t = NqlTableObject.parse({ database, table });
+            return NqlFieldObj.parse({ table: t, field: field.join('.') });
+        });
+    }
+    else {
+        throw new Error('No selected fields found');
+    }
+}
+/**
+ * Builds a SELECT clause for an NQL (Natural Query Language) query based on the provided fields.
+ *
+ * @param {NqlField[]} fields - An array of NqlField objects representing the selected fields.
+ * @returns {string} - The built SELECT clause string.
+ * @throws {Error} - If any of the provided fields are invalid.
+ */
+export function buildSelect(fields) {
+    fields.forEach((f) => NqlFieldObj.parse(f));
+    return 'SELECT ' + fields.map((f) => `${f.table.database}.${f.table.table}.${f.field}`).join(', ');
+}
+/**
+ * Parses a string in NQL format and returns an NqlBudgetType object.
+ *
+ * @function getLimit
+ * @param {string} nql - The NQL string to parse.
+ * @returns {NqlBudget} - The parsed budget object.
+ * @throws {Error} If the NQL string is invalid.
+ */
+export function getLimit(nql) {
+    const regex = /LIMIT\s+(\d+)\s+(\w+)\s+PER\s+(\w+)$/i;
+    const match = nql.trim().replace(/\n/g, ' ').match(regex);
+    if (match != null) {
+        const [, value, currency, period] = match;
+        const result = {
+            value: parseInt(value, 10),
+            currency: currency.toUpperCase(),
+            period: period.toUpperCase()
+        };
+        return NqlBudgetObj.parse(result);
+    }
+    else {
+        throw new Error('Invalid budget');
+    }
+}
+/**
+ * Builds a LIMIT clause for an NQL (Narrative Query Language) query based on the provided budget object.
+ *
+ * @param {NqlBudget} budget - The budget object containing the limit values.
+ * @returns {string} - The LIMIT clause string.
+ * @throws {Error} - If the provided budget object is invalid.
+ */
+export function buildLimit(budget) {
+    NqlBudgetObj.parse(budget);
+    return `LIMIT ${budget.value} ${budget.currency} PER ${budget.period}`;
+}
+/**
+ * Builds an NQL (Nested Query Language) string based on the provided Nql object.
+ *
+ * @param {Nql} nql - The Nql object containing the clauses for building the NQL string.
+ * @returns {string} - The constructed NQL string.
+ * @throws {Error} - Throws an error if the provided Nql object is invalid.
+ */
+export function buildNql(nql) {
+    // Validate our object
+    NqlObj.parse(nql);
+    // Build the NQL string from each of the clasues
+    const explain = buildPreSelect(nql.explain);
+    const limit = buildLimit(nql.limit);
+    const select = buildSelect(nql.select);
+    const from = buildFrom(nql.from[0]);
+    const where = buildWhere(nql.where);
+    const clauses = [explain, select, from, where, limit];
+    // Remove any empty clausess and join what's left together
+    return clauses.filter((c) => c !== '').join(' ');
+}
+export function buildFrom(from) {
+    NqlTableObject.parse(from);
+    return `FROM ${from.database}.${from.table}`;
+}
+export function buildWhere(where) {
+    NqlWhereObj.parse(where);
+    let str = 'WHERE';
+    where.filterExpressions.forEach((f, i) => {
+        if ('field' in f) {
+            str += ` ${buildField(f.field)} ${f.operator}`;
+        }
+        else {
+            str += ` ${buildField(f.left)} ${f.operator} ${buildField(f.right)}`;
+        }
+        if (where.booleanExpressions[i] != null) {
+            str += ` ${where.booleanExpressions[i]}`;
+        }
+    });
+    return str;
+}
+export function buildField(field) {
+    try {
+        const f = NqlFieldObj.parse(field);
+        return `${f.table.database}.${f.table.table}.${f.field}`;
+    }
+    catch {
+        return String(field);
+    }
+}
+/**
+ * Parses the given NQL string and returns an Nql object.
+ *
+ * @param {string} nql - The NQL string to parse.
+ * @returns {Nql} - The parsed Nql object.
+ * @throws {Error} - If the provided NQL string is invalid.
+ */
+export function getNqlObject(nql) {
+    const explain = getPreSelect(nql);
+    const limit = getLimit(nql);
+    const where = getWhere(nql);
+    const from = getFrom(nql);
+    const select = getSelect(nql);
+    return NqlObj.parse({ where, from, explain, select, limit });
+}