squirreling 0.10.2 → 0.11.0

package/src/plan/plan.js

@@ -1,34 +1,93 @@
+import { derivedAlias } from '../expression/alias.js'
 import { parseSql } from '../parse/parse.js'
 import { findAggregate } from '../validation/aggregates.js'
-import { columnNotFoundError, tableNotFoundError } from '../validation/planErrors.js'
-import { extractColumns } from './columns.js'
+import { ColumnNotFoundError, TableNotFoundError } from '../validation/planErrors.js'
+import { extractColumns, fromAlias, inferStatementColumns } from './columns.js'
 
 /**
- * @import { AsyncDataSource, ExprNode, DerivedColumn, JoinClause, PlanSqlOptions, ScanOptions, SelectColumn, SelectStatement } from '../types.js'
+ * @import { AsyncDataSource, ExprNode, DerivedColumn, JoinClause, PlanSqlOptions, ScanOptions, SelectColumn, SelectStatement, SetOperationStatement, Statement } from '../types.js'
  * @import { QueryPlan } from './types.d.ts'
  */
 
 /**
- * Builds a query plan from a SELECT statement AST.
+ * Builds a query plan from a statement AST.
  * Resolves CTEs at plan time so no planning occurs during execution.
  *
  * @param {PlanSqlOptions} options
  * @returns {QueryPlan} the root of the query plan tree
  */
 export function planSql({ query, functions, tables }) {
-  const select = typeof query === 'string' ? parseSql({ query, functions }) : query
-
-  // Build CTE plans in order (each CTE can reference preceding CTEs)
-  /** @type {Map<string, QueryPlan>} */
-  const ctePlans = new Map()
-  if (select.with) {
-    for (const cte of select.with.ctes) {
-      const ctePlan = planSelect({ select: cte.query, ctePlans, tables })
+  /** @type {Statement} */
+  const stmt = typeof query === 'string' ? parseSql({ query, functions }) : query
+  return planStatement({ stmt, tables })
+}
+
+/**
+ * Plans a Statement (SelectStatement, SetOperationStatement, or WithStatement).
+ *
+ * @param {object} options
+ * @param {Statement} options.stmt
+ * @param {Map<string, QueryPlan>} [options.ctePlans]
+ * @param {Map<string, string[]>} [options.cteColumns]
+ * @param {Record<string, AsyncDataSource>} [options.tables]
+ * @param {string[]} [options.parentColumns] - columns needed by the parent query (for subquery pushdown)
+ * @returns {QueryPlan}
+ */
+function planStatement({ stmt, ctePlans, cteColumns, tables, parentColumns }) {
+  if (stmt.type === 'with') {
+    // Build CTE plans in order (each CTE can reference preceding CTEs)
+    ctePlans ??= new Map()
+    cteColumns ??= new Map()
+    for (const cte of stmt.ctes) {
+      const ctePlan = planStatement({ stmt: cte.query, ctePlans, cteColumns, tables })
       ctePlans.set(cte.name.toLowerCase(), ctePlan)
+      cteColumns.set(cte.name.toLowerCase(), inferStatementColumns({ stmt: cte.query, cteColumns, tables }))
     }
+    return planStatement({ stmt: stmt.query, ctePlans, cteColumns, tables, parentColumns })
+  }
+  if (stmt.type === 'compound') {
+    return planSetOperation({ compound: stmt, ctePlans, cteColumns, tables })
+  }
+  return planSelect({ select: stmt, ctePlans, cteColumns, tables, parentColumns })
+}
+
+/**
+ * Plans a SetOperationStatement (UNION/INTERSECT/EXCEPT).
+ *
+ * @param {object} options
+ * @param {SetOperationStatement} options.compound
+ * @param {Map<string, QueryPlan>} [options.ctePlans]
+ * @param {Map<string, string[]>} [options.cteColumns]
+ * @param {Record<string, AsyncDataSource>} [options.tables]
+ * @returns {QueryPlan}
+ */
+function planSetOperation({ compound, ctePlans, cteColumns, tables }) {
+  const left = planStatement({ stmt: compound.left, ctePlans, cteColumns, tables })
+  const right = planStatement({ stmt: compound.right, ctePlans, cteColumns, tables })
+  const leftColumns = inferStatementColumns({ stmt: compound.left, cteColumns, tables })
+  const rightColumns = inferStatementColumns({ stmt: compound.right, cteColumns, tables })
+
+  if (leftColumns.length !== rightColumns.length || leftColumns.some((col, idx) => col !== rightColumns[idx])) {
+    throw new Error(`Set operation operands must have identical columns, got left [${leftColumns.join(', ')}] and right [${rightColumns.join(', ')}]`)
+  }
+
+  /** @type {QueryPlan} */
+  let plan = {
+    type: 'SetOperation',
+    operator: compound.operator,
+    all: compound.all,
+    left,
+    right,
   }
 
-  return planSelect({ select, ctePlans, tables })
+  if (compound.orderBy.length) {
+    plan = { type: 'Sort', orderBy: compound.orderBy, child: plan }
+  }
+  if (compound.limit !== undefined || compound.offset) {
+    plan = { type: 'Limit', limit: compound.limit, offset: compound.offset, child: plan }
+  }
+
+  return plan
 }
 
 /**
@@ -36,28 +95,28 @@ export function planSql({ query, functions, tables }) {
  *
  * @param {object} options
  * @param {SelectStatement} options.select
- * @param {Map<string, QueryPlan>} options.ctePlans
+ * @param {Map<string, QueryPlan>} [options.ctePlans]
+ * @param {Map<string, string[]>} [options.cteColumns]
  * @param {Record<string, AsyncDataSource>} [options.tables]
+ * @param {string[]} [options.parentColumns] - columns needed by the parent query (for subquery pushdown)
  * @returns {QueryPlan}
  */
-function planSelect({ select, ctePlans, tables }) {
+function planSelect({ select, ctePlans, cteColumns, tables, parentColumns }) {
   // Check for aggregation
   const hasAggregate = select.columns.some(col =>
-    col.kind === 'derived' && findAggregate(col.expr)
+    col.type === 'derived' && findAggregate(col.expr)
   )
   const useGrouping = hasAggregate || select.groupBy.length > 0
   const needsBuffering = useGrouping || select.orderBy.length > 0
 
   // Source alias for FROM clause
-  const sourceAlias = select.from.kind === 'table'
-    ? select.from.alias ?? select.from.table
-    : select.from.alias
+  const sourceAlias = fromAlias(select.from)
 
   // Determine scan hints for direct table scans (WHERE and LIMIT/OFFSET are
   // included so they are only applied to fresh scans, not CTE/subquery plans)
   /** @type {ScanOptions} */
   const hints = {}
-  const perTableColumns = extractColumns(select)
+  const perTableColumns = extractColumns({ select, parentColumns })
   hints.columns = perTableColumns.get(sourceAlias)
   if (!select.joins.length) {
     hints.where = select.where
@@ -69,11 +128,11 @@ function planSelect({ select, ctePlans, tables }) {
 
   // Start with the data source (FROM clause)
   /** @type {QueryPlan} */
-  let plan = planFrom({ select, ctePlans, hints, tables })
+  let plan = planFrom({ select, ctePlans, cteColumns, hints, tables })
 
   // Add JOINs
   if (select.joins.length) {
-    plan = planJoin({ left: plan, joins: select.joins, leftTable: sourceAlias, ctePlans, perTableColumns, tables })
+    plan = planJoin({ left: plan, joins: select.joins, leftTable: sourceAlias, ctePlans, cteColumns, perTableColumns, tables })
   }
 
   // Whether FROM resolved to our own direct table scan
@@ -118,7 +177,7 @@ function planSelect({ select, ctePlans, tables }) {
       /** @type {Map<string, ExprNode>} */
       const aliases = new Map()
       for (const col of select.columns) {
-        if (col.kind === 'derived' && col.alias) {
+        if (col.type === 'derived' && col.alias) {
           aliases.set(col.alias, col.expr)
         }
       }
@@ -133,9 +192,16 @@ function planSelect({ select, ctePlans, tables }) {
     // So the order is: Sort -> Project -> Distinct -> Limit
 
     // Fast path for SELECT *
-    const isPassthrough = select.columns.length === 1 && select.columns[0].kind === 'star'
+    const isPassthrough = select.columns.length === 1 && select.columns[0].type === 'star'
     if (!isPassthrough) {
-      plan = { type: 'Project', columns: select.columns, child: plan }
+      // When parent only needs specific columns, drop unneeded projections
+      let projectColumns = select.columns
+      if (parentColumns) {
+        projectColumns = select.columns.filter(col =>
+          col.type === 'star' || parentColumns.includes(col.alias ?? derivedAlias(col.expr))
+        )
+      }
+      plan = { type: 'Project', columns: projectColumns, child: plan }
     }
 
     if (select.distinct) {
@@ -153,24 +219,35 @@ function planSelect({ select, ctePlans, tables }) {
 /**
  * @param {object} options
  * @param {SelectStatement} options.select
- * @param {Map<string, QueryPlan>} options.ctePlans
+ * @param {Map<string, QueryPlan>} [options.ctePlans]
+ * @param {Map<string, string[]>} [options.cteColumns]
  * @param {ScanOptions} options.hints
  * @param {Record<string, AsyncDataSource>} [options.tables]
  * @returns {QueryPlan}
  */
-function planFrom({ select, ctePlans, hints, tables }) {
-  if (select.from.kind === 'table') {
-    const ctePlan = ctePlans.get(select.from.table.toLowerCase())
+function planFrom({ select, ctePlans, cteColumns, hints, tables }) {
+  if (select.from.type === 'table') {
+    const ctePlan = ctePlans?.get(select.from.table.toLowerCase())
     if (ctePlan) {
       return ctePlan
     }
     validateScan({ ...select.from, hints, tables })
     return { type: 'Scan', table: select.from.table, hints }
   } else {
-    if (select.from.query.with) {
-      throw new Error('WITH clause is not supported inside subqueries')
+    const subPlan = planStatement({ stmt: select.from.query, ctePlans, cteColumns, tables, parentColumns: hints.columns })
+    // Validate that requested columns exist in subquery output
+    const availableColumns = inferStatementColumns({ stmt: select.from.query, cteColumns, tables })
+    if (hints.columns && availableColumns.length) {
+      const missingColumn = hints.columns.find(col => !availableColumns.includes(col))
+      if (missingColumn) {
+        throw new ColumnNotFoundError({
+          columnName: missingColumn,
+          availableColumns,
+          ...select.from,
+        })
+      }
     }
-    return planSelect({ select: select.from.query, ctePlans, tables })
+    return subPlan
   }
 }
 
@@ -179,24 +256,28 @@ function planFrom({ select, ctePlans, hints, tables }) {
  * @param {QueryPlan} options.left - the left side of the join (FROM or previous joins)
  * @param {JoinClause[]} options.joins - array of join clauses
  * @param {string} options.leftTable - name/alias of the left table
- * @param {Map<string, QueryPlan>} options.ctePlans
+ * @param {Map<string, QueryPlan>} [options.ctePlans]
+ * @param {Map<string, string[]>} [options.cteColumns]
  * @param {Map<string, string[] | undefined>} options.perTableColumns
  * @param {Record<string, AsyncDataSource>} [options.tables]
  * @returns {QueryPlan}
  */
-function planJoin({ left, joins, leftTable, ctePlans, perTableColumns, tables }) {
+function planJoin({ left, joins, leftTable, ctePlans, cteColumns, perTableColumns, tables }) {
   let plan = left
   let currentLeftTable = leftTable
 
   for (const join of joins) {
     const rightTable = join.alias ?? join.table
 
-    const ctePlan = ctePlans.get(join.table.toLowerCase())
+    const ctePlan = ctePlans?.get(join.table.toLowerCase())
     /** @type {ScanOptions} */
     const rightHints = {}
     if (!ctePlan) {
       rightHints.columns = perTableColumns.get(rightTable)
       validateScan({ ...join, hints: rightHints, tables })
+    } else {
+      // For CTE joins, use CTE column metadata for hints
+      rightHints.columns = perTableColumns.get(rightTable) ?? cteColumns?.get(join.table.toLowerCase())
     }
     /** @type {QueryPlan} */
     const rightScan = ctePlan ?? { type: 'Scan', table: join.table, hints: rightHints }
@@ -300,13 +381,9 @@ function resolveAliases(node, aliases) {
  * @returns {{ leftKey: ExprNode, rightKey: ExprNode } | undefined}
  */
 function extractSimpleJoinKeys({ condition, leftTable, rightTable }) {
-  if (condition.type !== 'binary' || condition.op !== '=') {
-    return undefined
-  }
+  if (condition.type !== 'binary' || condition.op !== '=') return
   const { left, right } = condition
-  if (left.type !== 'identifier' || right.type !== 'identifier') {
-    return undefined
-  }
+  if (left.type !== 'identifier' || right.type !== 'identifier') return
 
   // Check if keys are in swapped order (right table ref on left side)
   const leftRefsRight = left.name.startsWith(`${rightTable}.`)
@@ -333,11 +410,11 @@ function validateScan({ table, hints, tables, positionStart, positionEnd }) {
   if (!tables) return
   const resolved = tables[table]
   if (!resolved) {
-    throw tableNotFoundError({ table, tables, positionStart, positionEnd })
+    throw new TableNotFoundError({ table, tables, positionStart, positionEnd })
   }
   const missingColumn = hints.columns?.find(col => !resolved.columns.includes(col))
   if (missingColumn) {
-    throw columnNotFoundError({
+    throw new ColumnNotFoundError({
       columnName: missingColumn,
       availableColumns: resolved.columns,
       positionStart,
@@ -355,7 +432,7 @@ function validateScan({ table, hints, tables, positionStart, positionEnd }) {
 function isAllCountStar(columns) {
   if (columns.length === 0) return false
   return columns.every(col =>
-    col.kind === 'derived' &&
+    col.type === 'derived' &&
     col.expr.type === 'function' &&
     col.expr.funcName.toUpperCase() === 'COUNT' &&
     col.expr.args.length === 1 &&

package/src/plan/types.d.ts

@@ -1,4 +1,4 @@
-import { DerivedColumn, ExprNode, JoinType, OrderByItem, ScanOptions, SelectColumn } from '../types.js'
+import { DerivedColumn, ExprNode, JoinType, OrderByItem, ScanOptions, SelectColumn, SetOperator } from '../types.js'
 
 export type QueryPlan =
   | ScanNode
@@ -13,6 +13,7 @@ export type QueryPlan =
   | HashJoinNode
   | NestedLoopJoinNode
   | PositionalJoinNode
+  | SetOperationNode
 
 // Scan node
 export interface ScanNode {
@@ -104,3 +105,12 @@ export interface PositionalJoinNode {
   left: QueryPlan
   right: QueryPlan
 }
+
+// Set operation node (UNION, INTERSECT, EXCEPT)
+export interface SetOperationNode {
+  type: 'SetOperation'
+  operator: SetOperator
+  all: boolean
+  left: QueryPlan
+  right: QueryPlan
+}

package/src/spatial/bbox.js

@@ -1,11 +1,11 @@
 /**
- * @import { BBox, SimpleGeometry } from './geometry.js'
+ * @import { BoundingBox, SimpleGeometry } from './geometry.js'
  */
 
 export const EPSILON = 1e-10
 export const EPSILON_SQ = EPSILON * EPSILON
 
-/** @type {WeakMap<SimpleGeometry, BBox>} */
+/** @type {WeakMap<SimpleGeometry, BoundingBox>} */
 const bboxCache = new WeakMap()
 
 /**
@@ -26,7 +26,7 @@ export function bboxOverlap(a, b) {
  * Results are cached per geometry object.
  *
  * @param {SimpleGeometry} geom
- * @returns {BBox}
+ * @returns {BoundingBox}
  */
 export function bbox(geom) {
   let b = bboxCache.get(geom)

package/src/spatial/geometry.d.ts

@@ -15,7 +15,7 @@ export type Geometry =
  */
 export type SimpleGeometry = Point | LineString | Polygon
 
-export interface BBox {
+export interface BoundingBox {
   minX: number
   minY: number
   maxX: number

package/src/spatial/index.d.ts

@@ -0,0 +1,6 @@
+import type { BoundingBox, Geometry, SimpleGeometry } from './geometry.js'
+
+export function decompose(geom: Geometry): SimpleGeometry[]
+export function bbox(geom: SimpleGeometry): BoundingBox
+export function bboxOverlap(a: SimpleGeometry, b: SimpleGeometry): boolean
+export function parseWkt(wkt: string): Geometry | null

package/src/spatial/index.js

@@ -0,0 +1,3 @@
+export { decompose } from './spatial.js'
+export { bbox, bboxOverlap } from './bbox.js'
+export { parseWkt } from './wkt.js'

package/src/spatial/spatial.js

@@ -68,6 +68,25 @@ export function evaluateSpatialFunc({ funcName, args }) {
   }
 }
 
+/**
+ * Decompose Multi* and GeometryCollection into simple geometries.
+ *
+ * @param {Geometry} geom
+ * @returns {SimpleGeometry[]}
+ */
+export function decompose(geom) {
+  if (geom.type === 'MultiPoint') {
+    return geom.coordinates.map(c => ({ type: 'Point', coordinates: c }))
+  } else if (geom.type === 'MultiLineString') {
+    return geom.coordinates.map(c => ({ type: 'LineString', coordinates: c }))
+  } else if (geom.type === 'MultiPolygon') {
+    return geom.coordinates.map(c => ({ type: 'Polygon', coordinates: c }))
+  } else if (geom.type === 'GeometryCollection') {
+    return geom.geometries.flatMap(decompose)
+  }
+  return [geom]
+}
+
 /**
  * Normalize a geometry value. Accepts GeoJSON objects.
  * Returns null if the value is not a valid geometry.
@@ -90,10 +109,6 @@ function toGeometry(val) {
   return null
 }
 
-// ============================================================================
-// Minimum distance between geometries
-// ============================================================================
-
 /**
  * Get all line segments from a geometry.
  *
@@ -165,35 +180,6 @@ function stDWithin(a, b, distance) {
   return false
 }
 
-// ============================================================================
-// Spatial predicate dispatch - decompose to primitive type pairs
-// ============================================================================
-
-/**
- * Decompose Multi* and GeometryCollection into simple geometries.
- *
- * @param {Geometry} geom
- * @returns {SimpleGeometry[]}
- */
-function decompose(geom) {
-  switch (geom.type) {
-  case 'MultiPoint':
-    return geom.coordinates.map(c => ({ type: 'Point', coordinates: c }))
-  case 'MultiLineString':
-    return geom.coordinates.map(c => ({ type: 'LineString', coordinates: c }))
-  case 'MultiPolygon':
-    return geom.coordinates.map(c => ({ type: 'Polygon', coordinates: c }))
-  case 'GeometryCollection':
-    return geom.geometries.flatMap(decompose)
-  default:
-    return [geom]
-  }
-}
-
-// ============================================================================
-// ST_Contains
-// ============================================================================
-
 /**
  * @param {SimpleGeometry[]} a
  * @param {SimpleGeometry[]} b
@@ -204,10 +190,6 @@ function stContains(a, b) {
   return b.every(pb => a.some(pa => pairContainment(pa, pb) !== 'OUTSIDE'))
 }
 
-// ============================================================================
-// ST_ContainsProperly
-// ============================================================================
-
 /**
  * @param {SimpleGeometry[]} a
  * @param {SimpleGeometry[]} b
@@ -218,10 +200,6 @@ function stContainsProperly(a, b) {
   return b.every(pb => a.some(pa => pairContainment(pa, pb) === 'INSIDE'))
 }
 
-// ============================================================================
-// ST_Touches
-// ============================================================================
-
 /**
  * @param {SimpleGeometry[]} a
  * @param {SimpleGeometry[]} b
@@ -239,10 +217,6 @@ function stTouches(a, b) {
   return intersects
 }
 
-// ============================================================================
-// ST_Overlaps
-// ============================================================================
-
 /**
  * @param {SimpleGeometry[]} a
  * @param {SimpleGeometry[]} b
@@ -281,10 +255,6 @@ function geometryDimension(parts) {
   return max
 }
 
-// ============================================================================
-// ST_Equals
-// ============================================================================
-
 /**
  * @param {SimpleGeometry[]} a
  * @param {SimpleGeometry[]} b
@@ -310,10 +280,6 @@ function stEquals(a, b) {
   return true
 }
 
-// ============================================================================
-// ST_Crosses
-// ============================================================================
-
 /**
  * @param {SimpleGeometry[]} a
  * @param {SimpleGeometry[]} b

package/src/types.d.ts

@@ -1,4 +1,4 @@
-import type { ExprNode, SelectStatement, SqlPrimitive } from './ast.js'
+import type { ExprNode, SelectStatement, SqlPrimitive, Statement } from './ast.js'
 
 export * from './ast.js'
 export { ParserState, Token, TokenType } from './parse/types.js'
@@ -13,14 +13,14 @@ export interface ParseSqlOptions {
 // executeSql(options)
 export interface ExecuteSqlOptions {
   tables: Record<string, Row | AsyncDataSource>
-  query: string | SelectStatement
+  query: string | Statement
   functions?: Record<string, UserDefinedFunction>
   signal?: AbortSignal
 }
 
 // planSql(options)
 export interface PlanSqlOptions {
-  query: string | SelectStatement
+  query: string | Statement
   functions?: Record<string, UserDefinedFunction>
   tables?: Record<string, AsyncDataSource>
 }
@@ -49,6 +49,8 @@ export interface AsyncDataSource {
   numRows?: number
   columns: string[]
   scan(options: ScanOptions): ScanResults
+  // Optional method for fast column scans
+  scanColumn?(options: ScanColumnOptions): AsyncIterable<ArrayLike<SqlPrimitive>>
 }
 
 /**
@@ -77,6 +79,14 @@ export interface ScanOptions {
   signal?: AbortSignal
 }
 
+/**
+ * Options for scanning a single column.
+ */
+export interface ScanColumnOptions {
+  column: string
+  signal?: AbortSignal
+}
+
 export interface FunctionSignature {
   min: number
   max?: number
@@ -88,9 +98,9 @@ export interface UserDefinedFunction {
   arguments: FunctionSignature
 }
 
-export type AggregateFunc = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'JSON_ARRAYAGG' | 'STDDEV_SAMP' | 'STDDEV_POP'
+export type AggregateFunc = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'JSON_ARRAYAGG' | 'STDDEV_SAMP' | 'STDDEV_POP' | 'MEDIAN' | 'PERCENTILE_CONT' | 'APPROX_QUANTILE'
 
-export type RegExpFunction = 'REGEXP_SUBSTR' | 'REGEXP_REPLACE'
+export type RegExpFunction = 'REGEXP_SUBSTR' | 'REGEXP_EXTRACT' | 'REGEXP_REPLACE'
 
 export type MathFunc =
   | 'FLOOR'
@@ -131,6 +141,8 @@ export type StringFunc =
   | 'LEFT'
   | 'RIGHT'
   | 'INSTR'
+  | 'POSITION'
+  | 'STRPOS'
 
 export type SpatialFunc =
   | 'ST_INTERSECTS'

package/src/validation/executionErrors.js

@@ -1,3 +1,5 @@
+import { FUNCTION_SIGNATURES } from './functions.js'
+
 /**
  * Structured execution error with position range and optional row number.
  */
@@ -12,7 +14,7 @@ export class ExecutionError extends Error {
   constructor({ message, positionStart, positionEnd, rowIndex }) {
     const rowSuffix = rowIndex != null ? ` (row ${rowIndex})` : ''
     super(message + rowSuffix)
-    this.name = 'ExecutionError'
+    this.name = this.constructor.name
     this.positionStart = positionStart
     this.positionEnd = positionEnd
     this.rowIndex = rowIndex
@@ -20,16 +22,22 @@ export class ExecutionError extends Error {
 }
 
 /**
- * Error for invalid context (e.g., INTERVAL without date arithmetic).
- *
- * @param {Object} options
- * @param {string} options.item - What was used incorrectly
- * @param {string} options.validContext - Where it can be used
- * @param {number} options.positionStart
- * @param {number} options.positionEnd
- * @param {number} options.rowIndex - 1-based row number where error occurred
- * @returns {ExecutionError}
+ * Error for invalid argument type or value.
  */
-export function invalidContextError({ item, validContext, positionStart, positionEnd, rowIndex }) {
-  return new ExecutionError({ message: `${item} can only be used with ${validContext}`, positionStart, positionEnd, rowIndex })
+export class ArgValueError extends ExecutionError {
+  /**
+   * @param {Object} options
+   * @param {string} options.funcName - The function name
+   * @param {string} options.message - Specific error message
+   * @param {number} options.positionStart
+   * @param {number} options.positionEnd
+   * @param {string} [options.hint] - Recovery hint
+   * @param {number} [options.rowIndex] - 1-based row number where error occurred
+   */
+  constructor({ funcName, message, positionStart, positionEnd, hint, rowIndex }) {
+    const funcNameUpper = funcName.toUpperCase()
+    const signature = FUNCTION_SIGNATURES[funcNameUpper]?.signature ?? ''
+    const suffix = hint ? `. ${hint}` : ''
+    super({ message: `${funcName}(${signature}): ${message}${suffix}`, positionStart, positionEnd, rowIndex })
+  }
 }