squirreling 0.16.8 → 0.16.9

package/README.md

@@ -12,7 +12,7 @@
 
 Squirreling is a streaming async SQL engine in pure JavaScript. Built for the browser from the ground up: streaming input and output, pluggable data sources, and lazy async cell evaluation. This makes Squirreling ideal for querying data from network sources, APIs, or LLMs where latency and cost matter.
 
-> Part of **[HypStack](https://hypstack.ai/)**, an open-source stack for AI observability.
+> Powers **[HypAware](https://hypaware.ai/?utm_source=github-readme)**, the improvement loop for all your agents.
 
 - **Standard SQL**: Full SQL support for querying data (read-only)
 - **Async UDFs**: User-defined functions can call APIs or models
@@ -146,6 +146,7 @@ Squirreling mostly follows the SQL standard. The following features are supporte
 - `JOIN` operations: `INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN`, `FULL JOIN`, `CROSS JOIN`, `POSITIONAL JOIN`, `LATERAL VIEW [OUTER] EXPLODE(...)`, with `ON` or `USING (col, ...)` conditions
 - `GROUP BY` and `HAVING` clauses, including `GROUP BY ALL`
 - Set operations: `UNION`, `UNION ALL`, `INTERSECT`, `INTERSECT ALL`, `EXCEPT`, `EXCEPT ALL`
+- `SHOW TABLES` to list the available tables
 - Expressions: `CASE`, `CAST`, `TRY_CAST`, `BETWEEN`, `IN`, `LIKE`, `IS NULL`, `IS NOT NULL`, string concatenation `||`
 - Subscript access: zero-based array indexing `col[0]`, struct field access `col['field']`, and chains like `col[0].field`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.16.8",
+  "version": "0.16.9",
   "description": "Squirreling Async SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -40,12 +40,12 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
-    "@types/node": "26.6.3",
-    "@vitest/coverage-v8": "5.0.2",
-    "eslint": "10.11.0",
-    "eslint-plugin-jsdoc": "65.0.0",
-    "globals": "17.12.0",
+    "@types/node": "26.6.5",
+    "@vitest/coverage-v8": "5.0.4",
+    "eslint": "10.12.0",
+    "eslint-plugin-jsdoc": "65.3.4",
+    "globals": "17.13.0",
     "typescript": "7.0.2",
-    "vitest": "5.0.2"
+    "vitest": "5.0.4"
   }
 }

package/src/ast.d.ts

@@ -41,7 +41,12 @@ export interface WithStatement extends AstBase {
   query: Statement
 }
 
-export type Statement = SelectStatement | SetOperationStatement | WithStatement
+// SHOW TABLES statement: lists the names of the available tables
+export interface ShowTablesStatement extends AstBase {
+  type: 'show tables'
+}
+
+export type Statement = SelectStatement | SetOperationStatement | WithStatement | ShowTablesStatement
 
 export interface CTEDefinition extends AstBase {
   name: string

package/src/execute/execute.js

@@ -37,6 +37,9 @@ const YIELD_INTERVAL = 4000
 export function executeSql({ tables, query, functions, signal }) {
   const parsed = typeof query === 'string' ? parseSql({ query, functions }) : query
 
+  // Listing names does not require table contents or inferred schemas.
+  if (parsed.type === 'show tables') return executeShowTables({ tables, signal })
+
   // Normalize tables: convert arrays to AsyncDataSource
   /** @type {Record<string, AsyncDataSource>} */
   const normalizedTables = {}
@@ -97,6 +100,8 @@ export function executePlan({ plan, context }) {
     return executeScan(plan, context)
   } else if (plan.type === 'SingleRow') {
     return executeSingleRow()
+  } else if (plan.type === 'ShowTables') {
+    return executeShowTables(context)
   } else if (plan.type === 'Count') {
     return executeCount(plan, context)
   } else if (plan.type === 'Filter') {
@@ -148,6 +153,31 @@ function executeSingleRow() {
   }
 }
 
+/**
+ * Executes SHOW TABLES: yields one row per available table name, sorted.
+ *
+ * @param {Pick<ExecuteSqlOptions, 'tables' | 'signal'>} context
+ * @returns {QueryResults}
+ */
+function executeShowTables(context) {
+  const columns = ['name']
+  const names = Object.keys(context.tables).sort()
+  return {
+    columns,
+    numRows: names.length,
+    maxRows: names.length,
+    async *rows() {
+      for (const name of names) {
+        context.signal?.throwIfAborted()
+        yield {
+          columns,
+          cells: { name: () => Promise.resolve(name) },
+        }
+      }
+    },
+  }
+}
+
 /**
  * Executes a table-valued function (e.g. UNNEST, JSON_EACH).
  * Evaluates the argument once against the outer row (for lateral joins) or an

package/src/index.d.ts

@@ -35,6 +35,7 @@ export type {
   ScanResults,
   SelectStatement,
   SetOperationStatement,
+  ShowTablesStatement,
   SqlType,
   SqlPrimitive,
   Statement,

package/src/parse/extractTables.js

@@ -46,6 +46,10 @@ function walkStatement(stmt, cteScope, refs) {
     for (const o of stmt.orderBy) walkExpr(o.expr, cteScope, refs)
     return
   }
+  if (stmt.type === 'show tables') {
+    // SHOW TABLES references no source tables
+    return
+  }
   // select
   if (!stmt.from) {
     // FROM-less SELECT (e.g. `SELECT 1`), no source tables

package/src/parse/parse.js

@@ -47,6 +47,17 @@ export function parseSql({ query, functions }) {
  */
 export function parseStatement(state) {
   const positionStart = state.lastPos
+  const showTok = current(state)
+  if (showTok.type === 'identifier' && showTok.value.toUpperCase() === 'SHOW') {
+    consume(state)
+    const tok = current(state)
+    if (tok.type !== 'identifier' || tok.value.toUpperCase() !== 'TABLES') {
+      throw parseError(state, 'TABLES')
+    }
+    consume(state)
+    match(state, 'semicolon')
+    return { type: 'show tables', positionStart: showTok.positionStart, positionEnd: state.lastPos }
+  }
   if (match(state, 'keyword', 'WITH')) {
     const recursiveTok = current(state)
     if (recursiveTok.type === 'identifier' && recursiveTok.value.toUpperCase() === 'RECURSIVE') {

package/src/plan/columns.js

@@ -40,7 +40,7 @@ export function fromAlias(from) {
  */
 export function statementScope(stmt) {
   if (stmt.type === 'with') return statementScope(stmt.query)
-  if (stmt.type === 'compound') return undefined
+  if (stmt.type === 'compound' || stmt.type === 'show tables') return undefined
   const alias = fromAlias(stmt.from)
   const joins = stmt.joins.map(j => j.alias ?? j.table)
   return alias === undefined ? joins : [alias, ...joins]
@@ -329,6 +329,7 @@ export function collectColumnsFromExpr(expr, columns, aliases, context) {
  * @param {ColumnCollectionContext} [context]
  */
 function collectCorrelatedColumnsFromStatement(stmt, columns, context) {
+  if (stmt.type === 'show tables') return
   if (stmt.type === 'compound') {
     collectCorrelatedColumnsFromStatement(stmt.left, columns, context)
     collectCorrelatedColumnsFromStatement(stmt.right, columns, context)
@@ -386,6 +387,7 @@ function collectCorrelatedColumnsFromStatement(stmt, columns, context) {
  * @param {ColumnCollectionContext} [context]
  */
 function collectFromFunctionArgs(stmt, columns, context) {
+  if (stmt.type === 'show tables') return
   if (stmt.type === 'compound') {
     collectFromFunctionArgs(stmt.left, columns, context)
     collectFromFunctionArgs(stmt.right, columns, context)
@@ -414,6 +416,9 @@ function collectFromFunctionArgs(stmt, columns, context) {
  * @returns {string[]}
  */
 export function inferStatementColumns({ stmt, cteColumns, tables }) {
+  if (stmt.type === 'show tables') {
+    return ['name']
+  }
   if (stmt.type === 'with') {
     return inferStatementColumns({ stmt: stmt.query, cteColumns, tables })
   }

package/src/plan/plan.js

@@ -38,6 +38,9 @@ export function planSql({ query, functions, tables, ctePlans, cteColumns }) {
  * @returns {QueryPlan}
  */
 export function planStatement({ stmt, ctePlans, cteColumns, tables, parentColumns, outerScope }) {
+  if (stmt.type === 'show tables') {
+    return { type: 'ShowTables' }
+  }
   if (stmt.type === 'with') {
     // Build CTE plans in order (each CTE can reference preceding CTEs)
     ctePlans ??= new Map()

package/src/plan/types.d.ts

@@ -15,6 +15,7 @@ export type QueryPlan =
   | NestedLoopJoinNode
   | PositionalJoinNode
   | SetOperationNode
+  | ShowTablesNode
   | SubqueryNode
   | TableFunctionNode
   | WindowNode
@@ -35,6 +36,11 @@ export interface SingleRowNode {
   type: 'SingleRow'
 }
 
+// SHOW TABLES: yields one row per available table name
+export interface ShowTablesNode {
+  type: 'ShowTables'
+}
+
 // Count node for COUNT(*) optimization
 export interface CountNode {
   type: 'Count'