@polyglot-sql/sdk 0.1.10 → 0.1.12

package/dist/index.cjs

@@ -1507,6 +1507,38 @@ class WasmWindowDefBuilder {
   }
 }
 if (Symbol.dispose) WasmWindowDefBuilder.prototype[Symbol.dispose] = WasmWindowDefBuilder.prototype.free;
+function annotate_types$1(sql, dialect, schema_json) {
+  let deferred4_0;
+  let deferred4_1;
+  try {
+    const retptr = wasm$3.__wbindgen_add_to_stack_pointer(-16);
+    const ptr0 = passStringToWasm0(sql, wasm$3.__wbindgen_export, wasm$3.__wbindgen_export2);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(dialect, wasm$3.__wbindgen_export, wasm$3.__wbindgen_export2);
+    const len1 = WASM_VECTOR_LEN;
+    const ptr2 = passStringToWasm0(schema_json, wasm$3.__wbindgen_export, wasm$3.__wbindgen_export2);
+    const len2 = WASM_VECTOR_LEN;
+    wasm$3.annotate_types(retptr, ptr0, len0, ptr1, len1, ptr2, len2);
+    var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+    var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+    deferred4_0 = r0;
+    deferred4_1 = r1;
+    return getStringFromWasm0(r0, r1);
+  } finally {
+    wasm$3.__wbindgen_add_to_stack_pointer(16);
+    wasm$3.__wbindgen_export4(deferred4_0, deferred4_1, 1);
+  }
+}
+function annotate_types_value$1(sql, dialect, schema_json) {
+  const ptr0 = passStringToWasm0(sql, wasm$3.__wbindgen_export, wasm$3.__wbindgen_export2);
+  const len0 = WASM_VECTOR_LEN;
+  const ptr1 = passStringToWasm0(dialect, wasm$3.__wbindgen_export, wasm$3.__wbindgen_export2);
+  const len1 = WASM_VECTOR_LEN;
+  const ptr2 = passStringToWasm0(schema_json, wasm$3.__wbindgen_export, wasm$3.__wbindgen_export2);
+  const len2 = WASM_VECTOR_LEN;
+  const ret = wasm$3.annotate_types_value(ptr0, len0, ptr1, len1, ptr2, len2);
+  return takeObject(ret);
+}
 function ast_add_where$1(ast_json, condition_json, use_or) {
   let deferred3_0;
   let deferred3_1;
@@ -1933,6 +1965,30 @@ function lineage_sql$1(sql, column, dialect, trim_selects) {
     wasm$3.__wbindgen_export4(deferred4_0, deferred4_1, 1);
   }
 }
+function lineage_sql_with_schema$1(sql, column, schema_json, dialect, trim_selects) {
+  let deferred5_0;
+  let deferred5_1;
+  try {
+    const retptr = wasm$3.__wbindgen_add_to_stack_pointer(-16);
+    const ptr0 = passStringToWasm0(sql, wasm$3.__wbindgen_export, wasm$3.__wbindgen_export2);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(column, wasm$3.__wbindgen_export, wasm$3.__wbindgen_export2);
+    const len1 = WASM_VECTOR_LEN;
+    const ptr2 = passStringToWasm0(schema_json, wasm$3.__wbindgen_export, wasm$3.__wbindgen_export2);
+    const len2 = WASM_VECTOR_LEN;
+    const ptr3 = passStringToWasm0(dialect, wasm$3.__wbindgen_export, wasm$3.__wbindgen_export2);
+    const len3 = WASM_VECTOR_LEN;
+    wasm$3.lineage_sql_with_schema(retptr, ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3, trim_selects);
+    var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+    var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+    deferred5_0 = r0;
+    deferred5_1 = r1;
+    return getStringFromWasm0(r0, r1);
+  } finally {
+    wasm$3.__wbindgen_add_to_stack_pointer(16);
+    wasm$3.__wbindgen_export4(deferred5_0, deferred5_1, 1);
+  }
+}
 function parse$2(sql, dialect) {
   let deferred3_0;
   let deferred3_1;
@@ -2816,6 +2872,8 @@ async function __polyglot_init_wasm() {
   __wbg_wasmsetopbuilder_free = __vite__wasmModule.__wbg_wasmsetopbuilder_free;
   __wbg_wasmupdatebuilder_free = __vite__wasmModule.__wbg_wasmupdatebuilder_free;
   __wbg_wasmwindowdefbuilder_free = __vite__wasmModule.__wbg_wasmwindowdefbuilder_free;
+  annotate_types = __vite__wasmModule.annotate_types;
+  annotate_types_value = __vite__wasmModule.annotate_types_value;
   ast_add_where = __vite__wasmModule.ast_add_where;
   ast_get_aggregate_functions = __vite__wasmModule.ast_get_aggregate_functions;
   ast_get_column_names = __vite__wasmModule.ast_get_column_names;
@@ -2841,6 +2899,7 @@ async function __polyglot_init_wasm() {
   get_dialects = __vite__wasmModule.get_dialects;
   get_dialects_value = __vite__wasmModule.get_dialects_value;
   lineage_sql = __vite__wasmModule.lineage_sql;
+  lineage_sql_with_schema = __vite__wasmModule.lineage_sql_with_schema;
   parse$1 = __vite__wasmModule.parse;
   parse_value = __vite__wasmModule.parse_value;
   plan$1 = __vite__wasmModule.plan;
@@ -2999,6 +3058,8 @@ let __wbg_wasmselectbuilder_free;
 let __wbg_wasmsetopbuilder_free;
 let __wbg_wasmupdatebuilder_free;
 let __wbg_wasmwindowdefbuilder_free;
+let annotate_types;
+let annotate_types_value;
 let ast_add_where;
 let ast_get_aggregate_functions;
 let ast_get_column_names;
@@ -3024,6 +3085,7 @@ let generate_value;
 let get_dialects;
 let get_dialects_value;
 let lineage_sql;
+let lineage_sql_with_schema;
 let parse$1;
 let parse_value;
 let plan$1;
@@ -3184,6 +3246,8 @@ const wasm$2 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProper
   __wbindgen_export2,
   __wbindgen_export3,
   __wbindgen_export4,
+  annotate_types,
+  annotate_types_value,
   ast_add_where,
   ast_get_aggregate_functions,
   ast_get_column_names,
@@ -3209,6 +3273,7 @@ const wasm$2 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProper
   get_dialects,
   get_dialects_value,
   lineage_sql,
+  lineage_sql_with_schema,
   memory,
   parse: parse$1,
   parse_value,
@@ -3361,6 +3426,8 @@ const wasmModule = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.definePr
   WasmSetOpBuilder,
   WasmUpdateBuilder,
   WasmWindowDefBuilder,
+  annotate_types: annotate_types$1,
+  annotate_types_value: annotate_types_value$1,
   ast_add_where: ast_add_where$1,
   ast_get_aggregate_functions: ast_get_aggregate_functions$1,
   ast_get_column_names: ast_get_column_names$1,
@@ -3386,6 +3453,7 @@ const wasmModule = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.definePr
   get_dialects: get_dialects$1,
   get_dialects_value: get_dialects_value$1,
   lineage_sql: lineage_sql$1,
+  lineage_sql_with_schema: lineage_sql_with_schema$1,
   parse: parse$2,
   parse_value: parse_value$1,
   plan: plan$2,
@@ -3435,6 +3503,16 @@ function isExpressionValue(value) {
 function makeExpr(type, data) {
   return { [type]: data };
 }
+function getInferredType(expr) {
+  const data = getExprData(expr);
+  if (data && typeof data === "object" && "inferred_type" in data) {
+    const it = data["inferred_type"];
+    if (it != null) {
+      return it;
+    }
+  }
+  return void 0;
+}
 function isType(type) {
   return (expr) => type in expr;
 }
@@ -4013,6 +4091,7 @@ const index$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.definePrope
   getExprType,
   getFunctions,
   getIdentifiers,
+  getInferredType,
   getLiterals,
   getNodeDepth,
   getParent,
@@ -4992,6 +5071,16 @@ function lineage(column, sql, dialect = "generic", trimSelects = false) {
   const resultJson = lineage_sql$1(sql, column, dialect, trimSelects);
   return JSON.parse(resultJson);
 }
+function lineageWithSchema(column, sql, schema, dialect = "generic", trimSelects = false) {
+  const resultJson = lineage_sql_with_schema$1(
+    sql,
+    column,
+    JSON.stringify(schema),
+    dialect,
+    trimSelects
+  );
+  return JSON.parse(resultJson);
+}
 function getSourceTables(column, sql, dialect = "generic") {
   const resultJson = source_tables$1(sql, column, dialect);
   return JSON.parse(resultJson);
@@ -5177,6 +5266,30 @@ function getDialects() {
 function getVersion() {
   return wasm.version();
 }
+function annotateTypes(sql, dialect = "generic", schema) {
+  try {
+    const schemaJson = schema ? JSON.stringify(schema) : "";
+    if (typeof wasm.annotate_types_value === "function") {
+      return decodeWasmPayload(
+        wasm.annotate_types_value(sql, dialect, schemaJson)
+      );
+    }
+    if (typeof wasm.annotate_types === "function") {
+      return JSON.parse(
+        wasm.annotate_types(sql, dialect, schemaJson)
+      );
+    }
+    return {
+      success: false,
+      error: "annotate_types not available in this WASM build"
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: `WASM annotate_types failed: ${errorMessage(error)}`
+    };
+  }
+}
 class Polyglot {
   static instance = null;
   constructor() {
@@ -5244,6 +5357,12 @@ class Polyglot {
   getVersion() {
     return getVersion();
   }
+  /**
+   * Parse SQL and annotate the AST with inferred type information.
+   */
+  annotateTypes(sql, dialect = "generic", schema) {
+    return annotateTypes(sql, dialect, schema);
+  }
 }
 const index = {
   init,
@@ -5253,9 +5372,11 @@ const index = {
   tokenize,
   generate,
   format,
+  annotateTypes,
   getDialects,
   getVersion,
   lineage,
+  lineageWithSchema,
   getSourceTables,
   diff,
   hasChanges,
@@ -5279,6 +5400,7 @@ exports.WindowDefBuilder = WindowDefBuilder;
 exports.abs = abs;
 exports.alias = alias;
 exports.and = and;
+exports.annotateTypes = annotateTypes;
 exports.ast = index$1;
 exports.avg = avg;
 exports.boolean = boolean;
@@ -5312,6 +5434,7 @@ exports.func = func;
 exports.generate = generate;
 exports.getColumns = getColumns;
 exports.getDialects = getDialects;
+exports.getInferredType = getInferredType;
 exports.getSourceTables = getSourceTables;
 exports.getVersion = getVersion;
 exports.greatest = greatest;
@@ -5330,6 +5453,7 @@ exports.isSelect = isSelect;
 exports.least = least;
 exports.length = length;
 exports.lineage = lineage;
+exports.lineageWithSchema = lineageWithSchema;
 exports.lit = lit;
 exports.ln = ln;
 exports.lower = lower;

package/dist/index.d.cts

@@ -49,6 +49,10 @@ declare type AggFunc = {
      * LIMIT inside aggregate (e.g., ARRAY_AGG(x ORDER BY y LIMIT 2))
      */
     limit?: Expression | null;
+    /**
+     * Inferred data type from type annotation
+     */
+    inferred_type?: DataType | null;
 };
 
 /**
@@ -93,6 +97,10 @@ declare type AggregateFunction = {
      * IGNORE NULLS / RESPECT NULLS
      */
     ignore_nulls?: boolean | null;
+    /**
+     * Inferred data type from type annotation
+     */
+    inferred_type?: DataType | null;
 };
 
 /**
@@ -146,6 +154,10 @@ declare type Alias = {
      * Trailing comments that appeared after the alias
      */
     trailing_comments: Array<string>;
+    /**
+     * Inferred data type from type annotation
+     */
+    inferred_type?: DataType | null;
 };
 
 /** Create an expr AS name alias expression. */
@@ -614,6 +626,51 @@ declare type Annotated = {
     trailing_comments: Array<string>;
 };
 
+/**
+ * Parse SQL and annotate the AST with inferred type information.
+ *
+ * Parses the given SQL and runs bottom-up type inference, populating the
+ * `inferred_type` field on value-producing AST nodes (columns, operators,
+ * functions, casts, etc.). Use `ast.getInferredType(expr)` to read the
+ * inferred type from any expression node.
+ *
+ * @param sql - The SQL string to parse and annotate
+ * @param dialect - The dialect to use for parsing (default: Generic)
+ * @param schema - Optional schema for column type resolution
+ *
+ * @example
+ * ```typescript
+ * import { annotateTypes, ast, Dialect } from '@polyglot-sql/sdk';
+ *
+ * const result = annotateTypes(
+ *   "SELECT a + b FROM t",
+ *   Dialect.PostgreSQL,
+ *   { tables: { t: { a: "INT", b: "DOUBLE" } } }
+ * );
+ *
+ * if (result.success) {
+ *   // Walk the AST and inspect inferred types
+ *   ast.walk(result.ast![0], (node) => {
+ *     const dt = ast.getInferredType(node);
+ *     if (dt) {
+ *       console.log(ast.getExprType(node), "=>", dt);
+ *     }
+ *   });
+ * }
+ * ```
+ */
+export declare function annotateTypes(sql: string, dialect?: Dialect, schema?: Schema): AnnotateTypesResult;
+
+/**
+ * Result of an annotateTypes operation
+ */
+export declare interface AnnotateTypesResult {
+    success: boolean;
+    /** The AST with `inferred_type` fields populated on value-producing nodes */
+    ast?: Expression[];
+    error?: string;
+}
+
 /**
  * Anonymous
  */
@@ -834,6 +891,7 @@ export declare namespace ast {
         ExpressionType,
         getExprData,
         getExprType,
+        getInferredType,
         isExpressionValue,
         makeExpr,
         Alias,
@@ -1139,6 +1197,10 @@ declare type BinaryFunc = {
      * Original function name for round-trip preservation (e.g., NVL vs IFNULL)
      */
     original_name?: string | null;
+    /**
+     * Inferred data type from type annotation
+     */
+    inferred_type?: DataType | null;
 };
 
 /**
@@ -1165,6 +1227,10 @@ declare type BinaryOp = {
      * Comments after the right operand
      */
     trailing_comments: Array<string>;
+    /**
+     * Inferred data type from type annotation
+     */
+    inferred_type?: DataType | null;
 };
 
 /**
@@ -1270,6 +1336,10 @@ declare type Case = {
      * Comments from the CASE keyword (emitted after END)
      */
     comments?: Array<string>;
+    /**
+     * Inferred data type from type annotation
+     */
+    inferred_type?: DataType | null;
 };
 
 /**
@@ -1339,6 +1409,10 @@ declare type Cast = {
      * DEFAULT value ON CONVERSION ERROR (Oracle): CAST(x AS type DEFAULT val ON CONVERSION ERROR)
      */
     default?: Expression | null;
+    /**
+     * Inferred data type from type annotation
+     */
+    inferred_type?: DataType | null;
 };
 
 /** Create a CAST(expr AS type) expression. */
@@ -1465,6 +1539,13 @@ declare type ClusterBy = {
     expressions: Array<Ordered>;
 };
 
+/**
+ * BigQuery CLUSTER BY property in CREATE TABLE statements.
+ */
+declare type ClusterByColumnsProperty = {
+    columns: Array<Identifier>;
+};
+
 /**
  * ClusteredByProperty
  */
@@ -1528,6 +1609,10 @@ declare type Column = {
      * Source position span
      */
     span?: Span | null;
+    /**
+     * Inferred data type from type annotation
+     */
+    inferred_type?: DataType | null;
 };
 
 /**
@@ -3138,9 +3223,11 @@ declare const _default: {
     tokenize: typeof tokenize;
     generate: typeof generate;
     format: typeof format;
+    annotateTypes: typeof annotateTypes;
     getDialects: typeof getDialects;
     getVersion: typeof getVersion;
     lineage: typeof lineage;
+    lineageWithSchema: typeof lineageWithSchema;
     getSourceTables: typeof getSourceTables;
     diff: typeof diff;
     hasChanges: typeof hasChanges;
@@ -3326,12 +3413,6 @@ declare type Detach = {
     exists: boolean;
 };
 
-/**
- * Polyglot SQL Dialect Translator
- *
- * A WebAssembly-powered SQL dialect translator that can convert SQL
- * between different database dialects (PostgreSQL, MySQL, BigQuery, etc.)
- */
 /**
  * Supported SQL dialects
  */
@@ -5092,8 +5173,12 @@ declare type Expression = {
     "on_commit_property": OnCommitProperty;
 } | {
     "partitioned_by_property": PartitionedByProperty;
+} | {
+    "partition_by_property": PartitionByProperty;
 } | {
     "partitioned_by_bucket": PartitionedByBucket;
+} | {
+    "cluster_by_columns_property": ClusterByColumnsProperty;
 } | {
     "partition_by_truncate": PartitionByTruncate;
 } | {
@@ -5186,6 +5271,8 @@ declare type Expression = {
     "include_property": IncludeProperty;
 } | {
     "properties": Properties;
+} | {
+    "options_property": OptionsProperty;
 } | {
     "input_output_format": InputOutputFormat;
 } | {
@@ -6209,6 +6296,10 @@ declare type Function_2 = {
      * Source position span
      */
     span?: Span | null;
+    /**
+     * Inferred data type from type annotation
+     */
+    inferred_type?: DataType | null;
 };
 
 /**
@@ -6531,6 +6622,27 @@ declare function getFunctions(node: Expression): Expression[];
  */
 declare function getIdentifiers(node: Expression): Expression[];
 
+/**
+ * Get the inferred data type from an Expression, if it has been type-annotated.
+ *
+ * After calling `annotateTypes()`, value-producing expressions (columns, operators,
+ * functions, casts, etc.) carry an `inferred_type` field with their resolved SQL type.
+ *
+ * @example
+ * ```typescript
+ * const result = annotateTypes("SELECT 1 + 2", Dialect.Generic);
+ * if (result.success) {
+ *   const addExpr = result.ast![0]; // the SELECT
+ *   // Navigate to the "1 + 2" expression and check its type:
+ *   const dt = getInferredType(someExpr);
+ *   // dt => { data_type: "int", length: null, integer_spelling: false }
+ * }
+ * ```
+ *
+ * @returns The inferred DataType, or `undefined` if not annotated or not a value-producing expression.
+ */
+export declare function getInferredType(expr: Expression): DataType | undefined;
+
 /**
  * Get all literals in the AST (via WASM)
  */
@@ -8521,6 +8633,10 @@ declare type LikeOp = {
      * Quantifier: ANY, ALL, or SOME
      */
     quantifier: string | null;
+    /**
+     * Inferred data type from type annotation
+     */
+    inferred_type?: DataType | null;
 };
 
 /**
@@ -8597,6 +8713,36 @@ export declare interface LineageResult {
     error?: string;
 }
 
+/**
+ * Trace the lineage of a column through a SQL query using schema metadata.
+ *
+ * When a schema is provided, columns are fully qualified and type-annotated.
+ * Each `LineageNode.expression` will have its `inferred_type` field populated
+ * with the resolved SQL data type. Use `ast.getInferredType(node.expression)`
+ * to read it.
+ *
+ * @param column - Column name to trace
+ * @param sql - SQL string to analyze
+ * @param schema - ValidationSchema-compatible schema object
+ * @param dialect - Dialect for parsing/qualification (default: 'generic')
+ * @param trimSelects - Trim SELECT to only target column (default: false)
+ *
+ * @example
+ * ```typescript
+ * import { lineageWithSchema, ast } from '@polyglot-sql/sdk';
+ *
+ * const result = lineageWithSchema("name", "SELECT name FROM users", {
+ *   tables: { users: { name: "TEXT", id: "INT" } }
+ * });
+ *
+ * if (result.success) {
+ *   const dt = ast.getInferredType(result.lineage!.expression);
+ *   // dt => { data_type: "text" }
+ * }
+ * ```
+ */
+export declare function lineageWithSchema(column: string, sql: string, schema: Schema, dialect?: string, trimSelects?: boolean): LineageResult;
+
 /**
  * List
  */
@@ -9470,6 +9616,21 @@ declare type Operator = {
     comments?: Array<string>;
 };
 
+/**
+ * Key/value pair in a BigQuery OPTIONS (...) clause.
+ */
+declare type OptionEntry = {
+    key: Identifier;
+    value: Expression;
+};
+
+/**
+ * Typed BigQuery OPTIONS (...) property for CREATE TABLE and related DDL.
+ */
+declare type OptionsProperty = {
+    entries: Array<OptionEntry>;
+};
+
 /** Chain multiple conditions with OR. */
 export declare function or(...conditions: ExprInput[]): Expr;
 
@@ -9793,6 +9954,13 @@ declare type PartitionByListProperty = {
     create_expressions: Expression | null;
 };
 
+/**
+ * BigQuery PARTITION BY property in CREATE TABLE statements.
+ */
+declare type PartitionByProperty = {
+    expressions: Array<Expression>;
+};
+
 /**
  * PartitionByRangeProperty
  */
@@ -10091,6 +10259,10 @@ export declare class Polyglot {
      * Get library version.
      */
     getVersion(): string;
+    /**
+     * Parse SQL and annotate the AST with inferred type information.
+     */
+    annotateTypes(sql: string, dialect?: Dialect, schema?: Schema): AnnotateTypesResult;
 }
 
 /**
@@ -12129,6 +12301,10 @@ declare type Subquery = {
      * Trailing comments after the closing paren
      */
     trailing_comments: Array<string>;
+    /**
+     * Inferred data type from type annotation
+     */
+    inferred_type?: DataType | null;
 };
 
 /**
@@ -13265,6 +13441,10 @@ declare type UnaryFunc = {
      * Original function name for round-trip preservation (e.g., CHAR_LENGTH vs LENGTH)
      */
     original_name?: string | null;
+    /**
+     * Inferred data type from type annotation
+     */
+    inferred_type?: DataType | null;
 };
 
 /**
@@ -13277,6 +13457,10 @@ declare type UnaryOp = {
      * The operand expression.
      */
     this: Expression;
+    /**
+     * Inferred data type from type annotation
+     */
+    inferred_type?: DataType | null;
 };
 
 /**
@@ -13801,6 +13985,10 @@ declare type VarArgFunc = {
      * Original function name for round-trip preservation (e.g., COALESCE vs IFNULL)
      */
     original_name?: string | null;
+    /**
+     * Inferred data type from type annotation
+     */
+    inferred_type?: DataType | null;
 };
 
 /**
@@ -14577,6 +14765,10 @@ declare type WindowFunction = {
      * Oracle KEEP clause: KEEP (DENSE_RANK FIRST|LAST ORDER BY ...)
      */
     keep?: Keep | null;
+    /**
+     * Inferred data type from type annotation
+     */
+    inferred_type?: DataType | null;
 };
 
 /**