@narrative.io/data-collaboration-sdk-ts 2.4.0 → 2.6.0

package/build/nql/Ast.d.ts

@@ -1,3 +1,119 @@
+/**
+ * A mapping of AST (Abstract Syntax Tree) node types to their corresponding TypeScript types.
+ * This object acts as a type registry for the various components of the NQL (Notation Query Language) AST.
+ */
+declare const NqlAstTypes: {
+    agg_function: NqlAggFunction;
+    binary_op: NqlBinaryOp;
+    case: NqlCase;
+    function: NqlFunction;
+    literal: NqlLit<NqlSimpleType>;
+    string_literal: NqlLit<NqlStringType>;
+    long_literal: NqlLit<NqlLongType>;
+    double_literal: NqlLit<NqlDoubleType>;
+    boolean_literal: NqlLit<NqlBooleanType>;
+    timestamp_literal: NqlLit<NqlTimestampType>;
+    column: NqlIdentColumn;
+    table: NqlIdentTable;
+    join: NqlJoin;
+    type_spec: NqlTypeSpec;
+    operator: NqlOp;
+    window: NqlWindow;
+    unknown: NqlUnknown;
+    select: NqlSelect;
+    create_materialized_view: NqlCreateMaterializedView;
+    explain: NqlExplain;
+    array: NqlArrayType;
+    binary: NqlBinaryType;
+    bool: NqlBooleanType;
+    double: NqlDoubleType;
+    long: NqlLongType;
+    interval: NqlIntervalType;
+    object: NqlObjectType;
+    other: NqlOtherType;
+    string: NqlStringType;
+    timestamp: NqlTimestampType;
+};
+/**
+ * Represents the logical operators that can be used to combine constraints in a NQL query.
+ */
+type NqlTemplateConstraintLogicalOperator = "ANY_OF" | "ALL_OF" | "NONE_OF";
+/**
+ * Defines a constraint that can be applied in a placeholder node. A constraint can consist of
+ * individual conditions or groups of nested conditions combined using a logical operator.
+ *
+ * @template T The type of conditions or nested constraint groups contained within this constraint.
+ */
+interface NqlTemplateConstraint<T> {
+    operator: NqlTemplateConstraintLogicalOperator;
+    constraints: (T | NqlTemplateConstraintGroup<T>)[];
+}
+/**
+ * Represents a group of constraints combined under a single logical operator. This allows for
+ * nested and complex logical expressions within a NQL query.
+ *
+ * @extends NqlTemplateConstraint<T> Inherits the structure of NqlConstraint for nested grouping.
+ * @template T The type of conditions or nested constraint groups contained within this constraint group.
+ */
+interface NqlTemplateConstraintGroup<T> extends NqlTemplateConstraint<T> {
+}
+/**
+ * Represents the keys from the NqlAstTypes object, used to identify the type of AST node.
+ */
+type NqlAstType = keyof typeof NqlAstTypes;
+/**
+ * Extracts the TypeScript type(s) associated with a given NQL AST type or array of AST types.
+ * This utility type dynamically maps one or more NqlAstType keys to their corresponding types.
+ *
+ * @template T A single NqlAstType or an array of NqlAstType values.
+ */
+type ExtractNqlType<T extends NqlAstType | NqlAstType[]> = T extends NqlAstType[] ? {
+    [K in keyof T]: T[K] extends NqlAstType ? (typeof NqlAstTypes)[T[K]] : never;
+} : T extends NqlAstType ? (typeof NqlAstTypes)[T] : never;
+/**
+ * Extracts the TypeScript type(s) associated with the expected type(s) of a `NqlPlaceholder`.
+ * This utility type conditionally checks if a given type `T` is a `NqlPlaceholder` with a generic
+ * type parameter `U`. If `T` is a `NqlPlaceholder`, it uses the `ExtractNqlType` utility to map
+ * `U` (the generic type parameter of the `NqlPlaceholder`) to its corresponding TypeScript type(s).
+ * If `T` is not a `NqlPlaceholder`, the type resolves to `never`.
+ *
+ * This type is useful for type inference and ensuring type safety when working with AST nodes
+ * that may be placeholders, enabling conditional type logic based on the structure of the AST.
+ *
+ * @template T - The type to check against `NqlPlaceholder`. This can be any type within the
+ *               `NqlAst` hierarchy, or more broadly, any type in the system.
+ *
+ * @returns The extracted TypeScript type(s) if `T` is a `NqlPlaceholder`, otherwise `never`.
+ *
+ * @example
+ * // Given a placeholder type with expected type 'string_literal':
+ * type PlaceholderStringLiteral = NqlPlaceholder<'string_literal'>;
+ *
+ * // The extracted type would be `NqlLit<NqlStringType>`:
+ * type ExtractedType = ExtractPlaceholderType<PlaceholderStringLiteral>;
+ *
+ * @example
+ * // When the type is not a `NqlPlaceholder`, `never` is returned:
+ * type NonPlaceholderType = NqlAst; // Assuming NqlAst is not a placeholder.
+ * type ExtractedType = ExtractPlaceholderType<NonPlaceholderType>; // `never`
+ */
+export type ExtractPlaceholderType<T> = T extends NqlPlaceholder<infer U> ? ExtractNqlType<U> : never;
+/**
+ * Represents a placeholder within a NQL query template. Placeholders are used to dynamically insert
+ * values, columns, or other AST nodes into a query based on certain constraints and expectations.
+ *
+ * @template T A single NqlAstType or an array of NqlAstType values indicating the expected type(s)
+ * for the AST node(s) that can fill this placeholder.
+ */
+interface NqlPlaceholder<T extends NqlAstType | NqlAstType[] = any> {
+    type: "placeholder";
+    identifier: string;
+    expectedType: T;
+    optional: boolean;
+    cardinality: "one" | "many";
+    constraints?: NqlTemplateConstraint<ExtractNqlType<T>>;
+    nql: string;
+}
 type Quantifier = "all" | "distinct";
 interface NqlAggFunction {
     nql: string;
@@ -77,10 +193,10 @@ interface NqlTimestampType {
     type: "timestamp";
 }
 type NqlSimpleType = NqlArrayType | NqlBinaryType | NqlBooleanType | NqlDoubleType | NqlLongType | NqlIntervalType | NqlObjectType | NqlOtherType | NqlStringType | NqlTimestampType;
-interface NqlLit {
+interface NqlLit<T = NqlSimpleType> {
     nql: string;
     as?: string;
-    value_type: NqlSimpleType;
+    value_type: T;
     value: string | null;
     type: "literal";
 }
@@ -180,5 +296,5 @@ interface NqlAstList extends Array<NqlAst> {
 export declare function isAstArray(n: NqlAst): n is NqlAstList;
 type NqlAst = {
     type: string;
-} & (NqlAstList | NqlAggFunction | NqlBinaryOp | NqlCase | NqlFunction | NqlLit | NqlIdent | NqlJoin | NqlTypeSpec | NqlOp | NqlWindow | NqlUnknown | NqlSelect | NqlCreateMaterializedView | NqlExplain);
-export type { NqlAst, NqlAstList, NqlAggFunction, NqlBinaryOp, NqlBudget, NqlCase, NqlFunction, NqlSimpleType, NqlLit, NqlIdent, NqlIdentColumn, NqlIdentTable, NqlJoin, NqlJoinType, NqlJoinConditionType, NqlTypeSpec, NqlOp, NqlWindow, NqlUnknown, NqlSelect, NqlCreateMaterializedView, NqlExplain, };
+} & (NqlAstList | NqlAggFunction | NqlBinaryOp | NqlCase | NqlFunction | NqlLit | NqlIdent | NqlJoin | NqlTypeSpec | NqlOp | NqlWindow | NqlUnknown | NqlSelect | NqlCreateMaterializedView | NqlExplain | NqlWhen | NqlElse | NqlPlaceholder);
+export type { NqlAst, NqlAstList, NqlAggFunction, NqlBinaryOp, NqlBudget, NqlCase, NqlFunction, NqlSimpleType, NqlLit, NqlIdent, NqlIdentColumn, NqlIdentTable, NqlJoin, NqlJoinType, NqlJoinConditionType, NqlTypeSpec, NqlOp, NqlWindow, NqlUnknown, NqlSelect, NqlCreateMaterializedView, NqlExplain, NqlAstType, NqlPlaceholder, };

package/build/nql/Ast.js

@@ -1,3 +1,39 @@
+/**
+ * A mapping of AST (Abstract Syntax Tree) node types to their corresponding TypeScript types.
+ * This object acts as a type registry for the various components of the NQL (Notation Query Language) AST.
+ */
+const NqlAstTypes = {
+    agg_function: null,
+    binary_op: null,
+    case: null,
+    function: null,
+    literal: null,
+    string_literal: null,
+    long_literal: null,
+    double_literal: null,
+    boolean_literal: null,
+    timestamp_literal: null,
+    column: null,
+    table: null,
+    join: null,
+    type_spec: null,
+    operator: null,
+    window: null,
+    unknown: null,
+    select: null,
+    create_materialized_view: null,
+    explain: null,
+    array: null,
+    binary: null,
+    bool: null,
+    double: null,
+    long: null,
+    interval: null,
+    object: null,
+    other: null,
+    string: null,
+    timestamp: null,
+};
 export function isAstArray(n) {
     return Array.isArray(n);
 }

package/build/nql/AstParser.d.ts

@@ -17,8 +17,8 @@ export interface Select {
     from: Table[] | Raw;
     where: BooleanExpression | Raw | null;
 }
-export type Output = ColumnRef | Lit | Raw;
-export type Expression = ArithmeticExpression | BooleanExpression | ColumnRef | Lit | FunctionCall | StringExpression | UnaryMinus | Raw;
+export type Output = ColumnRef | Lit | Raw | ast.NqlPlaceholder<ast.NqlAstType>;
+export type Expression = BooleanExpression | ColumnRef | Lit | Raw | ast.NqlPlaceholder<ast.NqlAstType>;
 export interface Raw {
     type: "nql";
     as?: string;
@@ -29,11 +29,8 @@ export interface Deduplication {
     expressions: Expression[];
 }
 export type ColumnRef = AttributeRef | DatasetColumnRef | RawRef;
-export type ArithmeticExpression = BinaryArithmeticExpression | UnaryMinus;
-export type BinaryArithmeticExpression = Add | Divide | Multiply | Subtract;
 export type BooleanExpression = And | Between | Equals | NotEquals | Gt | Gte | In | IsNull | Like | Lt | Lte | Not | Or;
-export type StringExpression = Concat;
-export type Table = RosettaTable | DatasetTable | RawTable;
+export type Table = RosettaTable | DatasetTable | RawTable | ast.NqlPlaceholder<ast.NqlAstType>;
 export interface RosettaTable {
     type: "rosetta_stone";
     as?: string;
@@ -80,37 +77,6 @@ export interface Lit {
     value_type: ast.NqlSimpleType;
     value: string | null;
 }
-export interface FunctionCall {
-    type: "function";
-    as?: string;
-    args: Expression[];
-    name: string;
-}
-export interface Add {
-    type: "+";
-    as?: string;
-    operands: Expression[];
-}
-export interface Divide {
-    type: "/";
-    as?: string;
-    operands: Expression[];
-}
-export interface Multiply {
-    type: "*";
-    as?: string;
-    operands: Expression[];
-}
-export interface Subtract {
-    type: "-";
-    as?: string;
-    operands: Expression[];
-}
-export interface UnaryMinus {
-    type: "unary_-";
-    as?: string;
-    operand: Expression;
-}
 export interface And {
     type: "and";
     as?: string;
@@ -190,12 +156,7 @@ export interface Like {
     value: Expression;
     pattern: string;
 }
-export interface Concat {
-    type: "||";
-    as?: string;
-    operands: Expression[];
-}
-export type Node = Select | Expression | Deduplication | Table | BooleanExpression | ArithmeticExpression | StringExpression | Join | AttributeRef | DatasetColumnRef | RawRef | Lit | FunctionCall | Add | Divide | Multiply | Subtract | UnaryMinus | And | Or | Not | Between | Equals | NotEquals | Lt | Lte | Gt | Gte | In | IsNull | Like | Concat | Raw | ast.NqlBinaryOp;
+export type Node = Select | Expression | Deduplication | Table | BooleanExpression | Join | AttributeRef | DatasetColumnRef | RawRef | Lit | And | Or | Not | Between | Equals | NotEquals | Lt | Lte | Gt | Gte | In | IsNull | Like | Raw | ast.NqlBinaryOp;
 export declare function parseStatement(n: ast.NqlAst): Statement | Raw;
 export declare function parseCreateMaterializedView(n: ast.NqlCreateMaterializedView): CreateMaterializedView;
 export declare function parseExplain(n: ast.NqlExplain): Explain | Raw;
@@ -205,3 +166,4 @@ export declare function parseWhere(n: ast.NqlAst): BooleanExpression | Raw;
 export declare function parseDeduplication(n: ast.NqlSelect): Deduplication | Raw | null;
 export declare function parseExpression(n: ast.NqlAst): Expression;
 export declare function parseOutput(n: ast.NqlAst): Output;
+export declare function extractPlaceholders(n: Node): Node[];

package/build/nql/AstParser.js

@@ -1,4 +1,5 @@
 import * as ast from "./Ast";
+import { traverseParsedAst } from "./AstTraverse";
 export function parseStatement(n) {
     switch (n.type) {
         case "create_materialized_view":
@@ -49,6 +50,8 @@ export function parseFrom(n) {
                 return parseJoin(n);
             case "table":
                 return [parseTable(n)];
+            case "placeholder":
+                return [n];
             default:
                 return [parseRawTable(n)];
         }
@@ -100,11 +103,11 @@ export function parseDeduplication(n) {
     return n.qualify !== null ? nqlOrFail(n.qualify) : null;
 }
 export function parseExpression(n) {
-    const parse = oneOf(parseArithmetic, parseBooleanExpression, parseColumnRef, parseFunctionCall, parseLit, parseStringExpression);
+    const parse = oneOf(parseBooleanExpression, parseColumnRef, parseLit, parseStringExpression, parsePlaceholder);
     return parse(n);
 }
 export function parseOutput(n) {
-    const parse = oneOf(parseColumnRef, parseLit);
+    const parse = oneOf(parseColumnRef, parseLit, parsePlaceholder);
     return parse(n);
 }
 function parseBooleanExpression(n) {
@@ -160,99 +163,12 @@ function parseBooleanExpression(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]);
@@ -301,20 +217,16 @@ function parseColumnRef(n) {
             return nqlOrFail(n);
     }
 }
-function parseFunctionCall(n) {
+function parsePlaceholder(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;
+        case "placeholder": {
+            return n;
         }
         default:
-            return nqlOrFail(n);
+            return {
+                type: "nql",
+                nql: "",
+            };
     }
 }
 function parseLit(n) {
@@ -519,7 +431,10 @@ function parseJoin(n) {
         conditionType: n.condition_type,
         joinType: n.join_type,
     };
-    right[0].join = join;
+    // ??? I'm not sure about this logic ??? - nj
+    if (right[0].type !== "placeholder") {
+        right[0].join = join;
+    }
     return left.concat(right);
 }
 function parseTable(n) {
@@ -551,6 +466,16 @@ function parseRawTable(n) {
     };
     return table;
 }
+export function extractPlaceholders(n) {
+    const placeholders = [];
+    const addPlaceholder = (n) => {
+        if (n.type === "placeholder") {
+            placeholders.push(n);
+        }
+    };
+    traverseParsedAst(n, addPlaceholder);
+    return placeholders;
+}
 /**
  * Selects the first successful expression from a list of parsers.
  *

package/build/nql/AstTraverse.js

@@ -1,17 +1,8 @@
 function findTraversalTargets(node) {
     switch (node.type) {
-        case "function":
-            return node.args;
-        case "+":
-        case "/":
-        case "*":
-        case "-":
         case "and":
         case "or":
-        case "||":
             return node.operands;
-        case "unary_-":
-            return [node.operand];
         case "is_null":
             return [node.operand];
         case "like":

package/build/nql/NqlBuilder.js

@@ -64,13 +64,15 @@ function compileTableRefs(tables) {
                 return aliased("narrative.rosetta_stone", table.as, false);
             case "raw_table":
                 return aliased(table.nql, table.as, false);
+            default:
+                throw new Error("unreachable");
         }
     }
     function compileTableRef(table) {
         let stmt = "";
         // NB: by convention the first table in list will never have a join associated with it,
         // hence the leading ' ' below does what we want.
-        if (table.join !== undefined) {
+        if ("join" in table && table.join !== undefined) {
             switch (table.join.joinType) {
                 case "comma": {
                     stmt += ",";
@@ -111,7 +113,8 @@ function compileTableRefs(tables) {
         if (
         // Prefer explicit `join !== undefined` to the use of the  `?` operator so that typescript
         // compile knows that the join is defined in the subsequent lexical scope.
-        table.join !== undefined &&
+        "join" in table &&
+            table.join !== undefined &&
             table.join.condition !== null &&
             table.join.conditionType !== "none") {
             switch (table.join.conditionType) {
@@ -150,7 +153,7 @@ export function compileOutput(n) {
         case "nql":
             return raw(n);
     }
-    return unreachable(n);
+    throw new Error("unreachable");
 }
 export function compileExpression(n) {
     switch (n.type) {
@@ -166,16 +169,6 @@ export function compileExpression(n) {
             return compileBinaryOperator(">", [n.left, n.right], n.as);
         case ">=":
             return compileBinaryOperator(">=", [n.left, n.right], n.as);
-        case "+":
-            return compileBinaryOperator("+", n.operands, n.as);
-        case "/":
-            return compileBinaryOperator("/", n.operands, n.as);
-        case "*":
-            return compileBinaryOperator("*", n.operands, n.as);
-        case "-":
-            return compileBinaryOperator("-", n.operands, n.as);
-        case "||":
-            return compileBinaryOperator("||", n.operands, n.as);
         case "and":
             return compileBinaryOperator("AND", n.operands, n.as);
         case "attribute_ref":
@@ -184,8 +177,6 @@ export function compileExpression(n) {
             return compileBetween(n.operand, n.lower, n.upper, n.as);
         case "dataset_column_ref":
             return compileDatasetColumnRef(n.datasetId, n.column, n.as);
-        case "function":
-            return compileFunctionCall(n.name, n.args, n.as);
         case "in":
             return compileIn(n.expression, n.values, n.negated, n.as);
         case "is_null":
@@ -202,10 +193,8 @@ export function compileExpression(n) {
             return raw(n);
         case "raw_ref":
             return compileRawRef(n.nql, n.as);
-        case "unary_-":
-            return compileUnaryMinus(n.operand, n.as);
     }
-    return unreachable(n);
+    throw new Error("unreachable");
 }
 function compileAttributeRef(column, as, aliasParens) {
     const segments = column.split(".");
@@ -237,35 +226,6 @@ function compileDatasetColumnRef(datasetId, column, as, aliasParen) {
     }, "");
     return aliased(`company_data.${quote(datasetId.toString())}.${formattedColumn}`, as, false);
 }
-function compileFunctionCall(name, args, as) {
-    // Calling convenions for functions are all over the place:
-    //   - CAST is invoked as CAST($value AS $type)
-    //   - EXTRACT is invoked as EXTRACT($part FROM $value)
-    //   - etc., etc., with many exceptions
-    // We'll likely wanto types for all the functions we know how to support, or have every function
-    // described by the API, including providing a template for its calling convention. For now the
-    // below will get us a to a v1.
-    // Useful reference: https://calcite.apache.org/docs/reference.html#arithmetic-operators-and-functions
-    const argsNql = args.map((e) => compileExpression(e));
-    let callNql;
-    switch (name) {
-        case "CAST":
-            callNql = `CAST(${argsNql[0]} AS ${argsNql[1]})`;
-            break;
-        case "EXTRACT":
-            callNql = `EXTRACT(${argsNql[0]} FROM ${argsNql[1]})`;
-            break;
-        case "TRIM":
-            callNql = `TRIM(${argsNql[0]} ${argsNql[1]} FROM ${argsNql[2]})`;
-            break;
-        default: {
-            // hope for the best. definitely does not work in all cases.
-            callNql =
-                argsNql.length > 0 ? `${name}(${argsNql.join(", ")})` : `${name}`;
-        }
-    }
-    return aliased(callNql, as);
-}
 function compileIn(expression, values, negated, as) {
     const op = !negated ? "IN" : "NOT IN";
     const compiledValues = isArray(values)
@@ -342,7 +302,7 @@ function quote(s) {
     return `${quoteChar}${s.replace(quoteChar, `\\${quoteChar}`)}${quoteChar}`;
 }
 function raw(n) {
-    return aliased(n.nql, n.as);
+    return aliased(n.nql, n.as, true);
 }
 function isArray(ns) {
     return Array.isArray(ns);

package/build/nql/Template.d.ts

@@ -0,0 +1,23 @@
+import type { NqlAst, NqlAstType, NqlPlaceholder } from "./Ast";
+/**
+ * Traverses an AST (Abstract Syntax Tree) or an array of AST nodes, and replaces all placeholder nodes
+ * found within the tree with the result of a provided callback function. This function operates recursively,
+ * handling various types of nodes including those with `args`, `left`, `right`, `condition`, `value`, `columns`,
+ * `from`, `where`, `having`, `group_by`, `order_by`, `windows`, and `with` properties. The callback is invoked
+ * with each placeholder node encountered, and the return value of the callback replaces the placeholder in the AST.
+ *
+ * @template T A union type of `NqlAstType` or an array of `NqlAstType`, indicating the expected type(s) of the placeholder's content.
+ * @param {NqlAst|NqlAst[]} node The root AST node or an array of AST nodes to traverse.
+ * @param {function(NqlPlaceholder<T>): NqlAst} callback A function that takes a placeholder node and returns an AST node to replace it.
+ *        This function is called for every placeholder node found in the AST.
+ * @returns {void} This function does not return a value; it modifies the AST nodes in place.
+ *
+ * @todo Validate that the replaced nodes adhere to the constraints of the placholder node (if any).
+ *
+ * @example
+ * // Given an AST node or array of nodes `ast` and a function `replacePlaceholder`:
+ * visitAndReplacePlaceholders(ast, replacePlaceholder);
+ * // This will traverse `ast`, calling `replacePlaceholder` for each placeholder node,
+ * // replacing them in place with the returned node from `replacePlaceholder`.
+ */
+export declare function visitAndReplacePlaceholders<T extends NqlAstType | NqlAstType[]>(node: NqlAst | NqlAst[], callback: (placeholderNode: NqlPlaceholder<T>) => NqlAst): void;

package/build/nql/Template.js

@@ -0,0 +1,170 @@
+function isAstNode(node) {
+    if (node === undefined) {
+        return false;
+    }
+    if (node === null) {
+        return false;
+    }
+    if (typeof node === "string") {
+        return false;
+    }
+    return !Array.isArray(node) && typeof node === "object" && "type" in node;
+}
+/**
+ * Traverses an AST (Abstract Syntax Tree) or an array of AST nodes, and replaces all placeholder nodes
+ * found within the tree with the result of a provided callback function. This function operates recursively,
+ * handling various types of nodes including those with `args`, `left`, `right`, `condition`, `value`, `columns`,
+ * `from`, `where`, `having`, `group_by`, `order_by`, `windows`, and `with` properties. The callback is invoked
+ * with each placeholder node encountered, and the return value of the callback replaces the placeholder in the AST.
+ *
+ * @template T A union type of `NqlAstType` or an array of `NqlAstType`, indicating the expected type(s) of the placeholder's content.
+ * @param {NqlAst|NqlAst[]} node The root AST node or an array of AST nodes to traverse.
+ * @param {function(NqlPlaceholder<T>): NqlAst} callback A function that takes a placeholder node and returns an AST node to replace it.
+ *        This function is called for every placeholder node found in the AST.
+ * @returns {void} This function does not return a value; it modifies the AST nodes in place.
+ *
+ * @todo Validate that the replaced nodes adhere to the constraints of the placholder node (if any).
+ *
+ * @example
+ * // Given an AST node or array of nodes `ast` and a function `replacePlaceholder`:
+ * visitAndReplacePlaceholders(ast, replacePlaceholder);
+ * // This will traverse `ast`, calling `replacePlaceholder` for each placeholder node,
+ * // replacing them in place with the returned node from `replacePlaceholder`.
+ */
+export function visitAndReplacePlaceholders(node, callback) {
+    if (Array.isArray(node)) {
+        // Using for...of for array iteration
+        for (const [i, childNode] of node.entries()) {
+            if (childNode.type === "placeholder") {
+                node[i] = callback(childNode);
+            }
+            else {
+                visitAndReplacePlaceholders(childNode, callback);
+            }
+        }
+    }
+    else if (isAstNode(node)) {
+        if ("args" in node) {
+            node.args = node.args.map((arg) => {
+                if (arg.type === "placeholder") {
+                    return callback(arg);
+                }
+                return arg;
+            });
+            for (const arg of node.args) {
+                visitAndReplacePlaceholders(arg, callback);
+            }
+        }
+        if ("left" in node) {
+            if (node.left.type === "placeholder") {
+                node.left = callback(node.left);
+            }
+            else {
+                visitAndReplacePlaceholders(node.left, callback);
+            }
+        }
+        if ("right" in node) {
+            if (node.right.type === "placeholder") {
+                node.right = callback(node.right);
+            }
+            else {
+                visitAndReplacePlaceholders(node.right, callback);
+            }
+        }
+        if ("condition" in node && node.condition) {
+            if (node.condition.type === "placeholder") {
+                node.condition = callback(node.condition);
+            }
+            else {
+                visitAndReplacePlaceholders(node.condition, callback);
+            }
+        }
+        if ("value" in node && isAstNode(node.value)) {
+            if (node.value.type === "placeholder") {
+                node.value = callback(node.value);
+            }
+            else {
+                visitAndReplacePlaceholders(node.value, callback);
+            }
+        }
+        if ("columns" in node) {
+            node.columns = node.columns.map((arg) => {
+                if (arg.type === "placeholder") {
+                    return callback(arg);
+                }
+                return arg;
+            });
+            for (const arg of node.columns) {
+                visitAndReplacePlaceholders(arg, callback);
+            }
+        }
+        if ("from" in node && node.from) {
+            if (node.from.type === "placeholder") {
+                node.from = callback(node.from);
+            }
+            else {
+                visitAndReplacePlaceholders(node.from, callback);
+            }
+        }
+        if ("where" in node && node.where) {
+            if (node.where.type === "placeholder") {
+                node.where = callback(node.where);
+            }
+            else {
+                visitAndReplacePlaceholders(node.where, callback);
+            }
+        }
+        if ("having" in node && node.having) {
+            if (node.having.type === "placeholder") {
+                node.having = callback(node.having);
+            }
+            else {
+                visitAndReplacePlaceholders(node.having, callback);
+            }
+        }
+        if ("group_by" in node && node.group_by) {
+            node.group_by = node.group_by.map((arg) => {
+                if (arg.type === "placeholder") {
+                    return callback(arg);
+                }
+                return arg;
+            });
+            for (const arg of node.group_by) {
+                visitAndReplacePlaceholders(arg, callback);
+            }
+        }
+        if ("order_by" in node && node.order_by) {
+            node.order_by = node.order_by.map((arg) => {
+                if (arg.type === "placeholder") {
+                    return callback(arg);
+                }
+                return arg;
+            });
+            for (const arg of node.order_by) {
+                visitAndReplacePlaceholders(arg, callback);
+            }
+        }
+        if ("windows" in node && node.windows) {
+            node.windows = node.windows.map((arg) => {
+                if (arg.type === "placeholder") {
+                    return callback(arg);
+                }
+                return arg;
+            });
+            for (const arg of node.windows) {
+                visitAndReplacePlaceholders(arg, callback);
+            }
+        }
+        if ("with" in node && node.with) {
+            node.with = node.with.map((arg) => {
+                if (arg.type === "placeholder") {
+                    return callback(arg);
+                }
+                return arg;
+            });
+            for (const arg of node.with) {
+                visitAndReplacePlaceholders(arg, callback);
+            }
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narrative.io/data-collaboration-sdk-ts",
-	"version": "2.4.0",
+	"version": "2.6.0",
 	"main": "build/index.js",
 	"repository": "github:narrative-io/data-collaboration-sdk-ts",
 	"source": "src/index.ts",
@@ -29,7 +29,7 @@
 		"@types/jest": "29.5.12",
 		"babel-jest": "29.7.0",
 		"jest": "29.7.0",
-		"lefthook": "1.6.11",
+		"lefthook": "1.6.12",
 		"ts-jest": "29.1.2"
 	},
 	"dependencies": {
@@ -42,4 +42,4 @@
 	"files": [
 		"build"
 	]
-}
+}