@narrative.io/data-collaboration-sdk-ts 2.5.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 = BooleanExpression | ColumnRef | Lit | 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;
@@ -30,7 +30,7 @@ export interface Deduplication {
 }
 export type ColumnRef = AttributeRef | DatasetColumnRef | RawRef;
 export type BooleanExpression = And | Between | Equals | NotEquals | Gt | Gte | In | IsNull | Like | Lt | Lte | Not | Or;
-export type Table = RosettaTable | DatasetTable | RawTable;
+export type Table = RosettaTable | DatasetTable | RawTable | ast.NqlPlaceholder<ast.NqlAstType>;
 export interface RosettaTable {
     type: "rosetta_stone";
     as?: string;
@@ -166,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(parseBooleanExpression, parseColumnRef, 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) {
@@ -214,6 +217,18 @@ function parseColumnRef(n) {
             return nqlOrFail(n);
     }
 }
+function parsePlaceholder(n) {
+    switch (n.type) {
+        case "placeholder": {
+            return n;
+        }
+        default:
+            return {
+                type: "nql",
+                nql: "",
+            };
+    }
+}
 function parseLit(n) {
     switch (n.type) {
         case "literal": {
@@ -416,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) {
@@ -448,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/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) {
@@ -191,7 +194,7 @@ export function compileExpression(n) {
         case "raw_ref":
             return compileRawRef(n.nql, n.as);
     }
-    return unreachable(n);
+    throw new Error("unreachable");
 }
 function compileAttributeRef(column, as, aliasParens) {
     const segments = column.split(".");

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.5.0",
+	"version": "2.6.0",
 	"main": "build/index.js",
 	"repository": "github:narrative-io/data-collaboration-sdk-ts",
 	"source": "src/index.ts",
@@ -42,4 +42,4 @@
 	"files": [
 		"build"
 	]
-}
+}