@narrative.io/data-collaboration-sdk-ts 0.0.122 → 0.0.124

package/build/nql/AstParser.js

@@ -0,0 +1,538 @@
+import * as ast from "./Ast";
+export function parseSelect(n) {
+    const select = {
+        type: "select",
+        budget: n.budget,
+        columns: n.columns.map((col) => parseExpression(col)),
+        from: n.from !== null ? parseFrom(n.from) : [],
+        where: n.where !== null ? parseWhere(n.where) : null,
+    };
+    return select;
+}
+export function parseFrom(n) {
+    try {
+        switch (n.type) {
+            case "join":
+                return parseJoin(n);
+            case "table":
+                return [parseTable(n)];
+            default:
+                return [parseRawTable(n)];
+        }
+    }
+    catch (e) {
+        console.debug(`failed to parse 'from' clause`, e);
+        return [parseRawTable(n)];
+    }
+}
+export function parseWhere(n) {
+    try {
+        return parseBooleanExpression(n);
+    }
+    catch (e) {
+        console.debug(`failed to where from clause`, e);
+        return nqlOrFail(n);
+    }
+}
+export function parseExpression(n) {
+    const parse = oneOf(parseArithmetic, parseBooleanExpression, parseColumnRef, parseFunctionCall, parseLit, parseStringExpression);
+    return parse(n);
+}
+function parseBooleanExpression(n) {
+    switch (n.type) {
+        case "binary_op": {
+            switch (n.name) {
+                case "=":
+                    return parseEquals(n);
+                case "<>":
+                    return parseNotEquals(n);
+                case "<":
+                    return parseLt(n);
+                case "<=":
+                    return parseLte(n);
+                case ">":
+                    return parseGt(n);
+                case ">=":
+                    return parseGte(n);
+                case "AND":
+                    return parseAnd(n);
+                case "IN":
+                    return parseIn(n, false);
+                case "LIKE":
+                    return parseLike(n, false);
+                case "NOT IN":
+                    return parseIn(n, true);
+                case "NOT LIKE":
+                    return parseLike(n, true);
+                case "OR":
+                    return parseOr(n);
+                default:
+                    return nqlOrFail(n);
+            }
+        }
+        case "operator": {
+            switch (n.name) {
+                case "BETWEEN ASYMMETRIC":
+                    return parseBetween(n);
+                case "IS NULL":
+                    return parseIsNull(n, false);
+                case "IS NOT NULL":
+                    return parseIsNull(n, true);
+                case "NOT":
+                    return parseNot(n);
+                default:
+                    return nqlOrFail(n);
+            }
+        }
+        default:
+            return nqlOrFail(n);
+    }
+}
+function parseStringExpression(n) {
+    switch (n.type) {
+        case "binary_op": {
+            switch (n.name) {
+                case "||":
+                    return parseConcat(n);
+                default:
+                    return nqlOrFail(n);
+            }
+        }
+        default:
+            return nqlOrFail(n);
+    }
+}
+function parseConcat(n) {
+    const operands = parseOperands(n, "||");
+    const concat = {
+        type: "||",
+        as: n.as,
+        operands,
+    };
+    return concat;
+}
+function parseArithmetic(n) {
+    switch (n.type) {
+        case "binary_op": {
+            switch (n.name) {
+                case "+":
+                    return parseAdd(n);
+                case "/":
+                    return parseDivide(n);
+                case "*":
+                    return parseMultiply(n);
+                case "-":
+                    return parseSubtract(n);
+                default:
+                    return nqlOrFail(n);
+            }
+        }
+        case "operator": {
+            switch (n.name) {
+                case "-":
+                    return parseUnaryMinus(n);
+                default:
+                    return nqlOrFail(n);
+            }
+        }
+        default:
+            return nqlOrFail(n);
+    }
+}
+function parseAdd(n) {
+    const operands = parseOperands(n, "+");
+    const add = {
+        type: "+",
+        as: n.as,
+        operands,
+    };
+    return add;
+}
+function parseDivide(n) {
+    const operands = parseOperands(n, "/");
+    const divide = {
+        type: "/",
+        as: n.as,
+        operands,
+    };
+    return divide;
+}
+function parseMultiply(n) {
+    const operands = parseOperands(n, "*");
+    const mult = {
+        type: "*",
+        as: n.as,
+        operands,
+    };
+    return mult;
+}
+function parseSubtract(n) {
+    const operands = parseOperands(n, "-");
+    const sub = {
+        type: "-",
+        as: n.as,
+        operands,
+    };
+    return sub;
+}
+function parseUnaryMinus(n) {
+    const operand = parseExpression(n.args[0]);
+    const minus = {
+        type: "unary_-",
+        as: n.as,
+        operand,
+    };
+    return minus;
+}
+function parseBetween(n) {
+    const operand = parseExpression(n.args[0]);
+    const lower = parseExpression(n.args[1]);
+    const upper = parseExpression(n.args[2]);
+    const between = {
+        type: "between",
+        as: n.as,
+        operand,
+        lower,
+        upper,
+    };
+    return between;
+}
+function parseColumnRef(n) {
+    switch (n.type) {
+        case "column": {
+            if (n.schema === "narrative" && n.table === "rosetta_stone") {
+                const name = n.column.split(".")[0];
+                const attrRef = {
+                    type: "attribute_ref",
+                    as: n.as,
+                    name,
+                    column: n.column,
+                };
+                return attrRef;
+            }
+            if (n.schema === "company_data" && !isNaN(parseInt(n.table))) {
+                const datasetId = parseInt(n.table);
+                const datasetColumnRef = {
+                    type: "dataset_column_ref",
+                    as: n.as,
+                    datasetId,
+                    column: n.column,
+                };
+                return datasetColumnRef;
+            }
+            const rawRef = {
+                type: "raw_ref",
+                as: n.as,
+                nql: n.nql,
+            };
+            return rawRef;
+        }
+        default:
+            return nqlOrFail(n);
+    }
+}
+function parseFunctionCall(n) {
+    switch (n.type) {
+        case "function": {
+            const args = n.args.map((arg) => parseExpression(arg));
+            const fn = {
+                type: "function",
+                as: n.as,
+                args,
+                name: n.name,
+            };
+            return fn;
+        }
+        default:
+            return nqlOrFail(n);
+    }
+}
+function parseLit(n) {
+    switch (n.type) {
+        case "literal": {
+            const lit = {
+                type: "lit",
+                as: n.as,
+                value_type: n.value_type,
+                value: n.value,
+            };
+            return lit;
+        }
+        default:
+            return nqlOrFail(n);
+    }
+}
+function parseAnd(n) {
+    const operands = parseOperands(n, "and");
+    const and = {
+        type: "and",
+        as: n.as,
+        operands,
+    };
+    return and;
+}
+function parseOr(n) {
+    const operands = parseOperands(n, "or");
+    const or = {
+        type: "or",
+        as: n.as,
+        operands,
+    };
+    return or;
+}
+function parseEquals(n) {
+    const eq = {
+        type: "=",
+        left: parseExpression(n.left),
+        right: parseExpression(n.right),
+    };
+    return eq;
+}
+function parseNotEquals(n) {
+    const neq = {
+        type: "<>",
+        as: n.as,
+        left: parseExpression(n.left),
+        right: parseExpression(n.right),
+    };
+    return neq;
+}
+function parseGt(n) {
+    const gt = {
+        type: ">",
+        as: n.as,
+        left: parseExpression(n.left),
+        right: parseExpression(n.right),
+    };
+    return gt;
+}
+function parseGte(n) {
+    const gte = {
+        type: ">=",
+        as: n.as,
+        left: parseExpression(n.left),
+        right: parseExpression(n.right),
+    };
+    return gte;
+}
+function parseLt(n) {
+    const lt = {
+        type: "<",
+        as: n.as,
+        left: parseExpression(n.left),
+        right: parseExpression(n.right),
+    };
+    return lt;
+}
+function parseLte(n) {
+    const lte = {
+        type: "<=",
+        as: n.as,
+        left: parseExpression(n.left),
+        right: parseExpression(n.right),
+    };
+    return lte;
+}
+function parseIn(n, negated) {
+    const expression = parseExpression(n.left);
+    let values;
+    if (ast.isAstArray(n.right)) {
+        values = n.right.map((value) => parseExpression(value));
+    }
+    else {
+        values = nqlOrFail(n.right);
+    }
+    const _in = {
+        type: "in",
+        as: n.as,
+        negated,
+        expression,
+        values,
+    };
+    return _in;
+}
+function parseIsNull(n, negated) {
+    // IS NULL/IS NOT NULL is always supplied a single argument
+    const operand = parseExpression(n.args[0]);
+    const isNull = {
+        type: "is_null",
+        as: n.as,
+        negated,
+        operand,
+    };
+    return isNull;
+}
+function parseNot(n) {
+    const operand = parseBooleanExpression(n.args[0]);
+    const not = {
+        type: "not",
+        as: n.as,
+        operand,
+    };
+    return not;
+}
+function parseLike(n, negated) {
+    const value = parseExpression(n.left);
+    switch (n.right.type) {
+        case "literal": {
+            if (n.right.value_type.type === "string" && n.right.value !== null) {
+                const like = {
+                    type: "like",
+                    as: n.as,
+                    negated,
+                    value,
+                    pattern: n.right.value,
+                };
+                return like;
+            }
+            else {
+                // if the pattern is not a string literal, fail parsing of the entire expression
+                return nqlOrFail(n);
+            }
+        }
+        default:
+            return nqlOrFail(n);
+    }
+}
+/**
+ * Parses the operands of a binary expression and returns an array of Expressions.
+ *
+ * If the `left` or `right` arguments to `n` are of type `type`, then the operands are flattened
+ * to become operands for the top level expression.
+ *
+ * E.g., given
+ *       AND
+ *     /     \
+ *   OR     AND
+ *  /  \   /   \
+ * a   b  AND   c
+ *       /  \
+ *      d    e
+ * Returns an expression of the form:
+ *
+ * (a OR b) AND c AND d AND e
+ *
+ * A naive implementation would return:
+ *
+ * ((((A OR b) AND c) AND d) AND e)
+ *
+ * The practical reason for doing this is to simply the expression to eliminate the need to insert parentheses
+ * around every subtree.
+ * @param {ast.NqlBinaryOp} n - The binary operation to parse.
+ * @param {string} type - The type to match when collecting operands.
+ * @returns {Expression[]} - An array of Expression objects representing the operands.
+ */
+function parseOperands(n, type) {
+    const left = parseExpression(n.left);
+    const right = parseExpression(n.right);
+    const operands = [];
+    // NB: the `"operands" in left` check provides evidence to the typescript compile that we can call `.operands` on `left`
+    if (left.type === type && "operands" in left) {
+        operands.push(...left.operands);
+    }
+    else {
+        operands.push(left);
+    }
+    if (right.type === type && "operands" in right) {
+        operands.push(...right.operands);
+    }
+    else {
+        operands.push(right);
+    }
+    return operands;
+}
+function parseJoin(n) {
+    const left = parseFrom(n.left);
+    const right = parseFrom(n.right);
+    const condition = n.condition !== null ? parseBooleanExpression(n.condition) : null;
+    const join = {
+        type: "join",
+        condition,
+        conditionType: n.condition_type,
+        joinType: n.join_type,
+    };
+    right[0].join = join;
+    return left.concat(right);
+}
+function parseTable(n) {
+    if (n.schema === "narrative" && n.table === "rosetta_stone") {
+        const table = {
+            type: "rosetta_stone",
+            as: n.as,
+        };
+        return table;
+    }
+    if (n.schema === "company_data" && !isNaN(parseInt(n.table))) {
+        const datasetId = parseInt(n.table);
+        const table = {
+            type: "dataset",
+            as: n.as,
+            datasetId,
+        };
+        return table;
+    }
+    return parseRawTable(n);
+}
+function parseRawTable(n) {
+    const raw = nqlOrFail(n);
+    const as = "as" in n ? n.as : undefined;
+    const table = {
+        type: "raw_table",
+        as,
+        nql: raw.nql,
+    };
+    return table;
+}
+/**
+ * Selects the first successful expression from a list of parsers.
+ *
+ * @template A - The type of the input object that extends `ast.NqlAst`.
+ * @param {...Array<(a: A) => Expression>} fs - An array of functions that take an object of type `A` and return an `Expression`.
+ * @returns {(a: A) => Expression} - A function that takes an object of type `A` and returns the first successful `Expression` produced by one of the input functions.
+ *
+ * @example
+ * // Define two functions that take an NqlAst object and return an Expression
+ * const func1 = (a: NqlAst) => ...;
+ * const func2 = (a: NqlAst) => ...;
+ *
+ * // Create a function that selects the first successful expression between func1 and func2
+ * const selectExpression = oneOf(func1, func2);
+ *
+ * // Use the selectExpression function to get the result
+ * const result = selectExpression(myNqlAstObject);
+ *
+ * if (result.type !== 'nql') {
+ *   console.log('Successfully selected an expression:', result);
+ * } else {
+ *   console.error('All input functions failed.');
+ * }
+ */
+function oneOf(...fs) {
+    return (a) => {
+        const expressions = [];
+        for (const f of fs) {
+            expressions.push(f(a));
+        }
+        const successes = expressions.filter((e) => e.type !== "nql");
+        if (successes.length > 0) {
+            return successes[0];
+        }
+        else {
+            return expressions[0];
+        }
+    };
+}
+function nqlOrFail(n) {
+    if ("nql" in n) {
+        const as = "as" in n ? n.as : undefined;
+        const nql = {
+            type: "nql",
+            as,
+            nql: n.nql,
+        };
+        return nql;
+    }
+    else {
+        throw new Error(`no raw nql available for node '${n.type}'`);
+    }
+}

package/build/nql/DataRulesConverter.d.ts

@@ -1,6 +1,7 @@
 import { type ObjectAttribute } from "src/attributes/types";
 import { type Attribute } from "../attributes";
 import type { DataRulesAttributesField, ForecastBody, Nql } from "./types";
+import type { DataRules } from "../data-streams/types";
 /**
  * Convert an NQL object to a Forecast body.
  * @param {Nql} nqlObject - The NQL object to convert.
@@ -48,3 +49,17 @@ export declare function findAttributeProperties(attributes: Attribute[], name: s
  * buildField('person', ['name', 'age']);
  */
 export declare function buildField(attribute: string, properties: string[]): DataRulesAttributesField[];
+/**
+ * Generates the SQL FROM clause based on the given data rules.
+ *
+ * @param {DataRules} dataRules - The data rules specifying the datasets, attributes, and filters.
+ * @returns {string} The SQL FROM clause.
+ */
+export declare function generateFromClause(dataRules: DataRules): string;
+/**
+ * Converts the provided data rules into an SQL query.
+ *
+ * @param {DataRules} dataRules - The data rules specifying the datasets, attributes, and filters.
+ * @returns {string} The generated SQL query.
+ */
+export declare function dataRulesToSQL(dataRules: DataRules): string;

package/build/nql/DataRulesConverter.js

@@ -299,3 +299,152 @@ export function buildField(attribute, properties) {
         };
     });
 }
+/**
+ * Generates the SQL FROM clause based on the given data rules.
+ *
+ * @param {DataRules} dataRules - The data rules specifying the datasets, attributes, and filters.
+ * @returns {string} The SQL FROM clause.
+ */
+export function generateFromClause(dataRules) {
+    const fromClause = [];
+    // Handle Column Sets
+    if (dataRules.column_sets !== undefined) {
+        for (const columnSet of dataRules.column_sets) {
+            // eslint-disable-next-line @typescript-eslint/naming-convention
+            const { dataset_id } = columnSet;
+            fromClause.push(`company_data.${dataset_id}`);
+        }
+    }
+    // Handle Attributes
+    if (dataRules.attributes !== undefined) {
+        fromClause.push("narrative.rosetta_stone");
+    }
+    // Handle JOINs
+    if (dataRules.dataset_filter !== undefined) {
+        // eslint-disable-next-line @typescript-eslint/naming-convention
+        const { dataset_id, attribute } = dataRules.dataset_filter;
+        const joinClause = `JOIN company_data.${dataset_id} ON company_data.${dataset_id}."${attribute.field}" = narrative.rosetta_stone."${attribute.field}"`;
+        fromClause.push(joinClause);
+    }
+    return `FROM ${fromClause.join(", ")}`;
+}
+/**
+ * Converts the provided data rules into an SQL query.
+ *
+ * @param {DataRules} dataRules - The data rules specifying the datasets, attributes, and filters.
+ * @returns {string} The generated SQL query.
+ */
+export function dataRulesToSQL(dataRules) {
+    const selectClause = generateSelectClause(dataRules);
+    const fromClause = generateFromClause(dataRules);
+    const whereClause = generateWhereClause(dataRules);
+    let sql = `EXPLAIN ${selectClause} ${fromClause}`;
+    if (whereClause !== undefined) {
+        sql += ` ${whereClause} AND narrative.rosetta_stone._price_cpm_usd <= 2.0 LIMIT 50 USD PER CALENDAR_MONTH`;
+    }
+    return sql;
+}
+/**
+ * Generates the SQL SELECT clause based on the given data rules.
+ *
+ * @param {DataRules} dataRules - The data rules specifying the datasets, attributes, and filters.
+ * @returns {string} The SQL SELECT clause.
+ */
+function generateSelectClause(dataRules) {
+    let selectColumns = [];
+    const quoteField = (field) => field.includes(".")
+        ? `${field.split(".")[0]}.` + '"' + field.split(".")[1] + '"'
+        : `"${field}"`;
+    // Handle Column Sets
+    if (dataRules.column_sets !== undefined) {
+        for (const columnSet of dataRules.column_sets) {
+            // eslint-disable-next-line @typescript-eslint/naming-convention
+            const { dataset_id, fields } = columnSet;
+            const qualifiedFields = fields
+                .filter((f) => f.exported)
+                .map((f) => `company_data.${dataset_id}.${quoteField(f.field)}`);
+            selectColumns = [...selectColumns, ...qualifiedFields];
+        }
+    }
+    // Handle Attributes
+    if (dataRules.attributes !== undefined) {
+        for (const attributeSet of dataRules.attributes) {
+            const { fields } = attributeSet;
+            const qualifiedFields = fields
+                .filter((f) => f.exported)
+                .map((f) => `narrative.rosetta_stone.${quoteField(f.field)}`);
+            selectColumns = [...selectColumns, ...qualifiedFields];
+        }
+    }
+    return `SELECT ${selectColumns.join(", ")}`;
+}
+/**
+ * Converts a filter definition into an SQL condition.
+ *
+ * @param {string} columnName - The name of the column the filter applies to.
+ * @param {FilterDefinition} filter - The filter definition.
+ * @returns {string | null} The SQL condition, or null if the filter does not translate into a condition.
+ */
+function convertFilterToSQLCondition(columnName, filter) {
+    const quoteField = (field) => {
+        const parts = field.split(".");
+        if (parts.length > 1) {
+            const lastPart = parts.pop();
+            return `${parts.join(".")}.` + `"${lastPart}"`;
+        }
+        return field;
+    };
+    const quotedColumnName = quoteField(columnName);
+    switch (filter) {
+        // Define your conversion logic here for each filter type
+        case "include_all_values_including_nulls_filter":
+            return null;
+        case "include_only_if_not_null_filter":
+            return `${quotedColumnName} IS NOT NULL`;
+        default:
+            // Handle other complex filter types
+            return null;
+    }
+}
+/**
+ * Generates the SQL WHERE clause based on the given data rules.
+ *
+ * @param {DataRules} dataRules - The data rules specifying the datasets, attributes, and filters.
+ * @returns {string} The SQL WHERE clause.
+ */
+function generateWhereClause(dataRules) {
+    const whereConditions = [];
+    // Handle Column Sets
+    if (dataRules.column_sets !== undefined) {
+        for (const columnSet of dataRules.column_sets) {
+            // eslint-disable-next-line @typescript-eslint/naming-convention
+            const { dataset_id, fields } = columnSet;
+            for (const field of fields) {
+                if (field.filter !== undefined) {
+                    const condition = convertFilterToSQLCondition(`company_data.${dataset_id}.${field.field}`, field.filter);
+                    if (condition !== null) {
+                        whereConditions.push(condition);
+                    }
+                }
+            }
+        }
+    }
+    // Handle Attributes
+    if (dataRules.attributes !== undefined) {
+        for (const attributeSet of dataRules.attributes) {
+            const { fields } = attributeSet;
+            for (const field of fields) {
+                if (field.filter !== undefined) {
+                    const condition = convertFilterToSQLCondition(`narrative.rosetta_stone.${field.field}`, field.filter);
+                    if (condition != null) {
+                        whereConditions.push(condition);
+                    }
+                }
+            }
+        }
+    }
+    if (whereConditions.length === 0) {
+        return "";
+    }
+    return `WHERE ${whereConditions.join(" AND ")}`;
+}