@polyglot-sql/sdk 0.4.4 → 0.5.1

package/dist/index.d.cts

@@ -593,6 +593,18 @@ declare type AnalyzeListChainedRows = {
     expression: Expression | null;
 };
 
+/**
+ * Return compact query analysis facts for a SELECT or set operation.
+ */
+export declare function analyzeQuery(sql: string, options?: AnalyzeQueryOptions): QueryAnalysisResult;
+
+export declare interface AnalyzeQueryOptions {
+    /** Dialect used for parsing and dialect-aware rendering */
+    dialect?: Dialect | string;
+    /** Optional schema used for qualification and type annotation */
+    schema?: Schema;
+}
+
 /**
  * AnalyzeSample
  */
@@ -1817,6 +1829,16 @@ declare type ColumnPrefix = {
     expression: Expression;
 };
 
+export declare interface ColumnReferenceFact {
+    sourceName?: string;
+    sourceAlias?: string;
+    sourceKind: QueryAnalysisSourceKind;
+    table?: string;
+    column: string;
+    unqualified: boolean;
+    confidence: ReferenceConfidence;
+}
+
 /**
  * Columns
  */
@@ -3021,7 +3043,7 @@ declare type DataDeletionProperty = {
  * Types that do not match any known variant fall through to `Custom { name }`,
  * preserving the original type name for round-trip fidelity.
  */
-declare type DataType = {
+export declare type DataType = {
     "data_type": "boolean";
 } | {
     "data_type": "tiny_int";
@@ -3158,6 +3180,23 @@ declare type DataType = {
     "data_type": "unknown";
 };
 
+/**
+ * Result of a standalone data type parse operation
+ */
+export declare interface DataTypeResult {
+    success: boolean;
+    dataType?: DataType;
+    error?: string;
+    /** 1-based line number where the error occurred */
+    errorLine?: number;
+    /** 1-based column number where the error occurred */
+    errorColumn?: number;
+    /** Start byte offset of the error range */
+    errorStart?: number;
+    /** End byte offset of the error range (exclusive) */
+    errorEnd?: number;
+}
+
 /**
  * DATE_ADD / DATE_SUB function
  */
@@ -3366,10 +3405,13 @@ declare const _default: {
     isInitialized: typeof isInitialized;
     transpile: typeof transpile;
     parse: typeof parse;
+    parseDataType: typeof parseDataType;
     tokenize: typeof tokenize;
     generate: typeof generate;
+    generateDataType: typeof generateDataType;
     format: typeof format;
     annotateTypes: typeof annotateTypes;
+    analyzeQuery: typeof analyzeQuery;
     getDialects: typeof getDialects;
     getVersion: typeof getVersion;
     lineage: typeof lineage;
@@ -6702,6 +6744,39 @@ declare type GeneratedAsRowColumnConstraint = {
     hidden: Expression | null;
 };
 
+/**
+ * Generate SQL from a standalone DataType AST node.
+ *
+ * @param dataType - The DataType object to render
+ * @param dialect - The target dialect
+ * @returns The generated data type SQL
+ *
+ * @example
+ * ```typescript
+ * const parsed = parseDataType("VARCHAR(255)", Dialect.DuckDB);
+ * const rendered = generateDataType(parsed.dataType!, Dialect.PostgreSQL);
+ * // rendered.sql = "VARCHAR(255)"
+ * ```
+ */
+export declare function generateDataType(dataType: DataType, dialect?: Dialect): GenerateDataTypeResult;
+
+/**
+ * Result of a standalone data type generation operation
+ */
+export declare interface GenerateDataTypeResult {
+    success: boolean;
+    sql?: string;
+    error?: string;
+    /** 1-based line number where the error occurred */
+    errorLine?: number;
+    /** 1-based column number where the error occurred */
+    errorColumn?: number;
+    /** Start byte offset of the error range */
+    errorStart?: number;
+    /** End byte offset of the error range (exclusive) */
+    errorEnd?: number;
+}
+
 /**
  * GenerateDateArray
  */
@@ -10227,6 +10302,21 @@ declare type Paren = {
  */
 export declare function parse(sql: string, dialect?: Dialect): ParseResult;
 
+/**
+ * Parse a standalone SQL data type.
+ *
+ * @param sql - The data type string to parse
+ * @param dialect - The dialect to use
+ * @returns The parsed DataType AST node
+ *
+ * @example
+ * ```typescript
+ * const result = parseDataType("DECIMAL(10, 2)", Dialect.DuckDB);
+ * console.log(result.dataType);
+ * ```
+ */
+export declare function parseDataType(sql: string, dialect?: Dialect): DataTypeResult;
+
 /**
  * ParseDatetime
  */
@@ -10590,11 +10680,15 @@ export declare class Polyglot {
      * Per-dialect builds only support same-dialect and to/from Generic transpilation.
      * Use {@link Polyglot.getDialects} to check available dialects.
      */
-    transpile(sql: string, read: Dialect, write: Dialect): TranspileResult;
+    transpile(sql: string, read: Dialect, write: Dialect, options?: TranspileOptions): TranspileResult;
     /**
      * Parse SQL into an AST.
      */
     parse(sql: string, dialect?: Dialect): ParseResult;
+    /**
+     * Parse a standalone SQL data type.
+     */
+    parseDataType(sql: string, dialect?: Dialect): DataTypeResult;
     /**
      * Tokenize SQL into a token stream.
      */
@@ -10603,6 +10697,10 @@ export declare class Polyglot {
      * Generate SQL from an AST.
      */
     generate(ast: any, dialect?: Dialect): TranspileResult;
+    /**
+     * Generate SQL from a standalone DataType AST node.
+     */
+    generateDataType(dataType: DataType, dialect?: Dialect): GenerateDataTypeResult;
     /**
      * Format SQL.
      */
@@ -10624,6 +10722,10 @@ export declare class Polyglot {
      * Parse SQL and annotate the AST with inferred type information.
      */
     annotateTypes(sql: string, dialect?: Dialect, schema?: Schema): AnnotateTypesResult;
+    /**
+     * Return compact query analysis facts for a SELECT or set operation.
+     */
+    analyzeQuery(sql: string, options?: AnalyzeQueryOptions): QueryAnalysisResult;
 }
 
 /**
@@ -10759,6 +10861,17 @@ declare type ProjectionDef = {
     expression: Expression;
 };
 
+export declare interface ProjectionFact {
+    index: number;
+    name?: string;
+    isStar: boolean;
+    starTable?: string;
+    transformKind: TransformKind;
+    castType?: string;
+    typeHint?: string;
+    upstream: ColumnReferenceFact[];
+}
+
 /**
  * Properties
  */
@@ -10887,6 +11000,22 @@ declare type Quantile = {
     quantile: Expression | null;
 };
 
+export declare interface QueryAnalysis {
+    shape: QueryShape;
+    ctes: string[];
+    projections: ProjectionFact[];
+    relations: RelationFact[];
+    setOperations: SetOperationFact[];
+}
+
+export declare interface QueryAnalysisResult {
+    success: boolean;
+    analysis?: QueryAnalysis;
+    error?: string;
+}
+
+export declare type QueryAnalysisSourceKind = 'root' | 'table' | 'derived_table' | 'cte' | 'virtual' | 'unknown';
+
 /**
  * QueryBand
  */
@@ -10916,6 +11045,8 @@ export declare interface QueryPlan {
     leaves: PlanStep[];
 }
 
+export declare type QueryShape = 'select' | 'set_operation';
+
 /**
  * QueryTransform
  */
@@ -11048,6 +11179,8 @@ declare type Reference = {
     options: Array<Expression>;
 };
 
+export declare type ReferenceConfidence = 'resolved' | 'ambiguous' | 'unknown';
+
 /**
  * Union of all reference expression types (identifiers, columns, tables)
  */
@@ -11271,6 +11404,13 @@ declare type RegrValy = {
     expression: Expression;
 };
 
+export declare interface RelationFact {
+    name: string;
+    alias?: string;
+    kind: QueryAnalysisSourceKind;
+    columns: string[];
+}
+
 /**
  * RemoteWithConnectionModelProperty
  */
@@ -12141,11 +12281,24 @@ declare type SetOperation = {
     on: Expression | null;
 };
 
+export declare interface SetOperationBranchFact {
+    index: number;
+    projections: ProjectionFact[];
+}
+
 /**
  * Union of all set operation expression types
  */
 declare type SetOperationExpression = ExpressionByType<'union'> | ExpressionByType<'intersect'> | ExpressionByType<'except'>;
 
+export declare interface SetOperationFact {
+    kind: 'union' | 'intersect' | 'except' | string;
+    all: boolean;
+    distinct: boolean;
+    outputColumns: string[];
+    branches: SetOperationBranchFact[];
+}
+
 export declare type SetOperationType = 'union' | 'union_all' | 'intersect' | 'except';
 
 /**
@@ -13561,6 +13714,8 @@ declare type TransformFunc = {
     transform: Expression;
 };
 
+export declare type TransformKind = 'direct' | 'cast' | 'aggregation' | 'constant' | 'expression' | 'star';
+
 /**
  * TransformModelProperty
  */
@@ -13619,11 +13774,17 @@ declare type TranslateCharacters = {
  * // result.sql[0] = "SELECT COALESCE(a, b)"
  * ```
  */
-export declare function transpile(sql: string, read: Dialect, write: Dialect): TranspileResult;
+export declare function transpile(sql: string, read: Dialect, write: Dialect, options?: TranspileOptions): TranspileResult;
+
+export declare interface TranspileOptions {
+    /** Pretty-print the generated SQL */
+    pretty?: boolean;
+    /** How unsupported target-dialect constructs should be handled */
+    unsupportedLevel?: UnsupportedLevel;
+    /** Maximum number of unsupported diagnostics to include in raised errors */
+    maxUnsupported?: number;
+}
 
-/**
- * Transpilation options
- */
 /**
  * Result of a transpilation operation
  */
@@ -14171,6 +14332,11 @@ declare type UnpivotColumns = {
     expressions: Array<Expression>;
 };
 
+/**
+ * Transpilation options
+ */
+export declare type UnsupportedLevel = 'ignore' | 'warn' | 'raise' | 'immediate';
+
 /**
  * UPDATE statement
  */

package/dist/index.d.ts

@@ -593,6 +593,18 @@ declare type AnalyzeListChainedRows = {
     expression: Expression | null;
 };
 
+/**
+ * Return compact query analysis facts for a SELECT or set operation.
+ */
+export declare function analyzeQuery(sql: string, options?: AnalyzeQueryOptions): QueryAnalysisResult;
+
+export declare interface AnalyzeQueryOptions {
+    /** Dialect used for parsing and dialect-aware rendering */
+    dialect?: Dialect | string;
+    /** Optional schema used for qualification and type annotation */
+    schema?: Schema;
+}
+
 /**
  * AnalyzeSample
  */
@@ -1817,6 +1829,16 @@ declare type ColumnPrefix = {
     expression: Expression;
 };
 
+export declare interface ColumnReferenceFact {
+    sourceName?: string;
+    sourceAlias?: string;
+    sourceKind: QueryAnalysisSourceKind;
+    table?: string;
+    column: string;
+    unqualified: boolean;
+    confidence: ReferenceConfidence;
+}
+
 /**
  * Columns
  */
@@ -3021,7 +3043,7 @@ declare type DataDeletionProperty = {
  * Types that do not match any known variant fall through to `Custom { name }`,
  * preserving the original type name for round-trip fidelity.
  */
-declare type DataType = {
+export declare type DataType = {
     "data_type": "boolean";
 } | {
     "data_type": "tiny_int";
@@ -3158,6 +3180,23 @@ declare type DataType = {
     "data_type": "unknown";
 };
 
+/**
+ * Result of a standalone data type parse operation
+ */
+export declare interface DataTypeResult {
+    success: boolean;
+    dataType?: DataType;
+    error?: string;
+    /** 1-based line number where the error occurred */
+    errorLine?: number;
+    /** 1-based column number where the error occurred */
+    errorColumn?: number;
+    /** Start byte offset of the error range */
+    errorStart?: number;
+    /** End byte offset of the error range (exclusive) */
+    errorEnd?: number;
+}
+
 /**
  * DATE_ADD / DATE_SUB function
  */
@@ -3366,10 +3405,13 @@ declare const _default: {
     isInitialized: typeof isInitialized;
     transpile: typeof transpile;
     parse: typeof parse;
+    parseDataType: typeof parseDataType;
     tokenize: typeof tokenize;
     generate: typeof generate;
+    generateDataType: typeof generateDataType;
     format: typeof format;
     annotateTypes: typeof annotateTypes;
+    analyzeQuery: typeof analyzeQuery;
     getDialects: typeof getDialects;
     getVersion: typeof getVersion;
     lineage: typeof lineage;
@@ -6702,6 +6744,39 @@ declare type GeneratedAsRowColumnConstraint = {
     hidden: Expression | null;
 };
 
+/**
+ * Generate SQL from a standalone DataType AST node.
+ *
+ * @param dataType - The DataType object to render
+ * @param dialect - The target dialect
+ * @returns The generated data type SQL
+ *
+ * @example
+ * ```typescript
+ * const parsed = parseDataType("VARCHAR(255)", Dialect.DuckDB);
+ * const rendered = generateDataType(parsed.dataType!, Dialect.PostgreSQL);
+ * // rendered.sql = "VARCHAR(255)"
+ * ```
+ */
+export declare function generateDataType(dataType: DataType, dialect?: Dialect): GenerateDataTypeResult;
+
+/**
+ * Result of a standalone data type generation operation
+ */
+export declare interface GenerateDataTypeResult {
+    success: boolean;
+    sql?: string;
+    error?: string;
+    /** 1-based line number where the error occurred */
+    errorLine?: number;
+    /** 1-based column number where the error occurred */
+    errorColumn?: number;
+    /** Start byte offset of the error range */
+    errorStart?: number;
+    /** End byte offset of the error range (exclusive) */
+    errorEnd?: number;
+}
+
 /**
  * GenerateDateArray
  */
@@ -10227,6 +10302,21 @@ declare type Paren = {
  */
 export declare function parse(sql: string, dialect?: Dialect): ParseResult;
 
+/**
+ * Parse a standalone SQL data type.
+ *
+ * @param sql - The data type string to parse
+ * @param dialect - The dialect to use
+ * @returns The parsed DataType AST node
+ *
+ * @example
+ * ```typescript
+ * const result = parseDataType("DECIMAL(10, 2)", Dialect.DuckDB);
+ * console.log(result.dataType);
+ * ```
+ */
+export declare function parseDataType(sql: string, dialect?: Dialect): DataTypeResult;
+
 /**
  * ParseDatetime
  */
@@ -10590,11 +10680,15 @@ export declare class Polyglot {
      * Per-dialect builds only support same-dialect and to/from Generic transpilation.
      * Use {@link Polyglot.getDialects} to check available dialects.
      */
-    transpile(sql: string, read: Dialect, write: Dialect): TranspileResult;
+    transpile(sql: string, read: Dialect, write: Dialect, options?: TranspileOptions): TranspileResult;
     /**
      * Parse SQL into an AST.
      */
     parse(sql: string, dialect?: Dialect): ParseResult;
+    /**
+     * Parse a standalone SQL data type.
+     */
+    parseDataType(sql: string, dialect?: Dialect): DataTypeResult;
     /**
      * Tokenize SQL into a token stream.
      */
@@ -10603,6 +10697,10 @@ export declare class Polyglot {
      * Generate SQL from an AST.
      */
     generate(ast: any, dialect?: Dialect): TranspileResult;
+    /**
+     * Generate SQL from a standalone DataType AST node.
+     */
+    generateDataType(dataType: DataType, dialect?: Dialect): GenerateDataTypeResult;
     /**
      * Format SQL.
      */
@@ -10624,6 +10722,10 @@ export declare class Polyglot {
      * Parse SQL and annotate the AST with inferred type information.
      */
     annotateTypes(sql: string, dialect?: Dialect, schema?: Schema): AnnotateTypesResult;
+    /**
+     * Return compact query analysis facts for a SELECT or set operation.
+     */
+    analyzeQuery(sql: string, options?: AnalyzeQueryOptions): QueryAnalysisResult;
 }
 
 /**
@@ -10759,6 +10861,17 @@ declare type ProjectionDef = {
     expression: Expression;
 };
 
+export declare interface ProjectionFact {
+    index: number;
+    name?: string;
+    isStar: boolean;
+    starTable?: string;
+    transformKind: TransformKind;
+    castType?: string;
+    typeHint?: string;
+    upstream: ColumnReferenceFact[];
+}
+
 /**
  * Properties
  */
@@ -10887,6 +11000,22 @@ declare type Quantile = {
     quantile: Expression | null;
 };
 
+export declare interface QueryAnalysis {
+    shape: QueryShape;
+    ctes: string[];
+    projections: ProjectionFact[];
+    relations: RelationFact[];
+    setOperations: SetOperationFact[];
+}
+
+export declare interface QueryAnalysisResult {
+    success: boolean;
+    analysis?: QueryAnalysis;
+    error?: string;
+}
+
+export declare type QueryAnalysisSourceKind = 'root' | 'table' | 'derived_table' | 'cte' | 'virtual' | 'unknown';
+
 /**
  * QueryBand
  */
@@ -10916,6 +11045,8 @@ export declare interface QueryPlan {
     leaves: PlanStep[];
 }
 
+export declare type QueryShape = 'select' | 'set_operation';
+
 /**
  * QueryTransform
  */
@@ -11048,6 +11179,8 @@ declare type Reference = {
     options: Array<Expression>;
 };
 
+export declare type ReferenceConfidence = 'resolved' | 'ambiguous' | 'unknown';
+
 /**
  * Union of all reference expression types (identifiers, columns, tables)
  */
@@ -11271,6 +11404,13 @@ declare type RegrValy = {
     expression: Expression;
 };
 
+export declare interface RelationFact {
+    name: string;
+    alias?: string;
+    kind: QueryAnalysisSourceKind;
+    columns: string[];
+}
+
 /**
  * RemoteWithConnectionModelProperty
  */
@@ -12141,11 +12281,24 @@ declare type SetOperation = {
     on: Expression | null;
 };
 
+export declare interface SetOperationBranchFact {
+    index: number;
+    projections: ProjectionFact[];
+}
+
 /**
  * Union of all set operation expression types
  */
 declare type SetOperationExpression = ExpressionByType<'union'> | ExpressionByType<'intersect'> | ExpressionByType<'except'>;
 
+export declare interface SetOperationFact {
+    kind: 'union' | 'intersect' | 'except' | string;
+    all: boolean;
+    distinct: boolean;
+    outputColumns: string[];
+    branches: SetOperationBranchFact[];
+}
+
 export declare type SetOperationType = 'union' | 'union_all' | 'intersect' | 'except';
 
 /**
@@ -13561,6 +13714,8 @@ declare type TransformFunc = {
     transform: Expression;
 };
 
+export declare type TransformKind = 'direct' | 'cast' | 'aggregation' | 'constant' | 'expression' | 'star';
+
 /**
  * TransformModelProperty
  */
@@ -13619,11 +13774,17 @@ declare type TranslateCharacters = {
  * // result.sql[0] = "SELECT COALESCE(a, b)"
  * ```
  */
-export declare function transpile(sql: string, read: Dialect, write: Dialect): TranspileResult;
+export declare function transpile(sql: string, read: Dialect, write: Dialect, options?: TranspileOptions): TranspileResult;
+
+export declare interface TranspileOptions {
+    /** Pretty-print the generated SQL */
+    pretty?: boolean;
+    /** How unsupported target-dialect constructs should be handled */
+    unsupportedLevel?: UnsupportedLevel;
+    /** Maximum number of unsupported diagnostics to include in raised errors */
+    maxUnsupported?: number;
+}
 
-/**
- * Transpilation options
- */
 /**
  * Result of a transpilation operation
  */
@@ -14171,6 +14332,11 @@ declare type UnpivotColumns = {
     expressions: Array<Expression>;
 };
 
+/**
+ * Transpilation options
+ */
+export declare type UnsupportedLevel = 'ignore' | 'warn' | 'raise' | 'immediate';
+
 /**
  * UPDATE statement
  */