squirreling 0.7.1 → 0.7.2

package/README.md

@@ -10,7 +10,7 @@
 ![coverage](https://img.shields.io/badge/Coverage-95-darkred)
 [![dependencies](https://img.shields.io/badge/Dependencies-0-blueviolet)](https://www.npmjs.com/package/squirreling?activeTab=dependencies)
 
-Squirreling is a streaming async SQL engine for JavaScript. It is designed to provide efficient streaming of results from pluggable backends for highly efficient retrieval of data for browser applications.
+Squirreling is a streaming async SQL engine built for the web. It is designed to query over various data sources and provide efficient streaming of results. 100% JavaScript with zero dependencies.
 
 ## Features
 
@@ -79,7 +79,7 @@ console.log(`Collected rows:`, rows)
 
 - `SELECT` statements with `WHERE`, `ORDER BY`, `LIMIT`, `OFFSET`
 - Subqueries in `SELECT`, `FROM`, and `WHERE` clauses
-- `JOIN` operations: `INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN`, `FULL JOIN`
+- `JOIN` operations: `INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN`, `FULL JOIN`, `POSITIONAL JOIN`
 - `GROUP BY` and `HAVING` clauses
 
 ### Functions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squirreling",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Squirreling SQL Engine",
   "author": "Hyperparam",
   "homepage": "https://hyperparam.app",
@@ -37,7 +37,7 @@
     "test": "vitest run"
   },
   "devDependencies": {
-    "@types/node": "24.10.4",
+    "@types/node": "25.0.3",
     "@vitest/coverage-v8": "4.0.16",
     "eslint": "9.39.2",
     "eslint-plugin-jsdoc": "61.5.0",

package/src/execute/join.js

@@ -43,16 +43,26 @@ export async function executeJoins({ leftSource, joins, leftTable, tables, funct
     return {
       async *scan(options) {
         const { signal } = options
-        yield* hashJoin({
-          leftRows: leftSource.scan(options), // Stream directly, not buffered
-          rightRows,
-          join,
-          leftTable: currentLeftTable,
-          rightTable,
-          tables,
-          functions,
-          signal,
-        })
+        if (join.joinType === 'POSITIONAL') {
+          yield* positionalJoin({
+            leftRows: leftSource.scan(options),
+            rightRows,
+            leftTable: currentLeftTable,
+            rightTable,
+            signal,
+          })
+        } else {
+          yield* hashJoin({
+            leftRows: leftSource.scan(options), // Stream directly, not buffered
+            rightRows,
+            join,
+            leftTable: currentLeftTable,
+            rightTable,
+            tables,
+            functions,
+            signal,
+          })
+        }
       },
     }
   }
@@ -84,15 +94,22 @@ export async function executeJoins({ leftSource, joins, leftTable, tables, funct
     // Collect intermediate results into array for next join
     /** @type {AsyncRow[]} */
     const newLeftRows = []
-    const joined = hashJoin({
-      leftRows,
-      rightRows,
-      join,
-      leftTable: currentLeftTable,
-      rightTable,
-      tables,
-      functions,
-    })
+    const joined = join.joinType === 'POSITIONAL'
+      ? positionalJoin({
+        leftRows,
+        rightRows,
+        leftTable: currentLeftTable,
+        rightTable,
+      })
+      : hashJoin({
+        leftRows,
+        rightRows,
+        join,
+        leftTable: currentLeftTable,
+        rightTable,
+        tables,
+        functions,
+      })
     for await (const row of joined) {
       newLeftRows.push(row)
     }
@@ -121,16 +138,26 @@ export async function executeJoins({ leftSource, joins, leftTable, tables, funct
   return {
     async *scan(options) {
       const { signal } = options
-      yield* hashJoin({
-        leftRows,
-        rightRows,
-        join,
-        leftTable: currentLeftTable,
-        rightTable,
-        tables,
-        functions,
-        signal,
-      })
+      if (join.joinType === 'POSITIONAL') {
+        yield* positionalJoin({
+          leftRows,
+          rightRows,
+          leftTable: currentLeftTable,
+          rightTable,
+          signal,
+        })
+      } else {
+        yield* hashJoin({
+          leftRows,
+          rightRows,
+          join,
+          leftTable: currentLeftTable,
+          rightTable,
+          tables,
+          functions,
+          signal,
+        })
+      }
     },
   }
 }
@@ -230,6 +257,48 @@ function mergeRows(leftRow, rightRow, leftTable, rightTable) {
   return { columns, cells }
 }
 
+/**
+ * Performs a positional join between left and right row sets.
+ * Matches rows by their index position (row 0 with row 0, row 1 with row 1, etc.).
+ * When tables have different lengths, the shorter table is padded with NULLs.
+ *
+ * @param {Object} params
+ * @param {AsyncIterable<AsyncRow>|AsyncRow[]} params.leftRows - rows from left table
+ * @param {AsyncRow[]} params.rightRows - rows from right table (must be buffered)
+ * @param {string} params.leftTable - name of left table (for column prefixing)
+ * @param {string} params.rightTable - name of right table (for column prefixing, may be alias)
+ * @param {AbortSignal} [params.signal] - abort signal for cancellation
+ * @yields {AsyncRow} joined rows
+ */
+async function* positionalJoin({ leftRows, rightRows, leftTable, rightTable, signal }) {
+  // Buffer left rows if streaming
+  /** @type {AsyncRow[]} */
+  const leftArr = []
+  for await (const row of leftRows) {
+    if (signal?.aborted) return
+    leftArr.push(row)
+  }
+
+  const maxLen = Math.max(leftArr.length, rightRows.length)
+
+  // Get column info for NULL row creation
+  const leftCols = leftArr[0]?.columns ?? []
+  const rightCols = rightRows[0]?.columns ?? []
+  const leftPrefixedCols = leftCols.flatMap(col =>
+    col.includes('.') ? [col] : [`${leftTable}.${col}`, col]
+  )
+  const rightPrefixedCols = rightCols.flatMap(col =>
+    col.includes('.') ? [col] : [`${rightTable}.${col}`, col]
+  )
+
+  for (let i = 0; i < maxLen; i++) {
+    if (signal?.aborted) return
+    const leftRow = leftArr[i] ?? createNullRow(leftPrefixedCols)
+    const rightRow = rightRows[i] ?? createNullRow(rightPrefixedCols)
+    yield mergeRows(leftRow, rightRow, leftTable, rightTable)
+  }
+}
+
 /**
  * Performs a hash join between left and right row sets (streaming).
  * Yields rows as they are found instead of buffering all results.

package/src/index.d.ts

@@ -1,5 +1,5 @@
-import type { AsyncDataSource, AsyncRow, ExecuteSqlOptions, ParseSqlOptions, SelectStatement, SqlPrimitive } from './types.js'
-export type { AsyncDataSource, AsyncRow, ParseSqlOptions, SqlPrimitive } from './types.js'
+import type { AsyncDataSource, AsyncRow, ExecuteSqlOptions, ParseSqlOptions, SelectStatement, SqlPrimitive, Token } from './types.js'
+export type { AsyncCells, AsyncDataSource, AsyncRow, ExprNode, ParseSqlOptions, SelectStatement, SqlPrimitive, Token, UserDefinedFunction } from './types.js'
 
 /**
  * Executes a SQL SELECT query against an array of data rows
@@ -23,6 +23,14 @@ export function executeSql(options: ExecuteSqlOptions): AsyncGenerator<AsyncRow>
  */
 export function parseSql(options: ParseSqlOptions): SelectStatement
 
+/**
+ * Tokenizes a SQL query string into an array of tokens
+ *
+ * @param sql - SQL query string to tokenize
+ * @returns array of tokens
+ */
+export function tokenizeSql(sql: string): Token[]
+
 /**
  * Collects all results from an async generator into an array
  *

package/src/index.js

@@ -1,5 +1,6 @@
 export { executeSql } from './execute/execute.js'
 export { parseSql } from './parse/parse.js'
+export { tokenizeSql } from './parse/tokenize.js'
 export { collect } from './execute/utils.js'
 export { cachedDataSource } from './backend/dataSource.js'
 export { ParseError } from './parseErrors.js'

package/src/parse/joins.js

@@ -40,6 +40,9 @@ export function parseJoins(state) {
           // FULL OUTER JOIN
         }
         joinType = 'FULL'
+      } else if (tok.value === 'POSITIONAL') {
+        consume(state)
+        joinType = 'POSITIONAL'
       } else if (tok.value === 'JOIN') {
         // Just JOIN (defaults to INNER)
         consume(state)
@@ -61,9 +64,13 @@ export function parseJoins(state) {
     const tableName = expectIdentifier(state).value
     const tableAlias = parseTableAlias(state)
 
-    // Parse ON condition
-    expect(state, 'keyword', 'ON')
-    const condition = parseExpression(state)
+    // Parse ON condition (not for POSITIONAL joins)
+    /** @type {import('../types.js').ExprNode | undefined} */
+    let condition
+    if (joinType !== 'POSITIONAL') {
+      expect(state, 'keyword', 'ON')
+      condition = parseExpression(state)
+    }
 
     joins.push({
       joinType,

package/src/parse/parse.js

@@ -1,4 +1,4 @@
-import { tokenize } from './tokenize.js'
+import { tokenizeSql } from './tokenize.js'
 import { parseExpression } from './expression.js'
 import { RESERVED_AFTER_COLUMN, RESERVED_AFTER_TABLE, isKnownFunction } from '../validation.js'
 import { consume, current, expect, expectIdentifier, match, parseError, peekToken } from './state.js'
@@ -13,7 +13,7 @@ import { parseJoins } from './joins.js'
  * @returns {SelectStatement}
  */
 export function parseSql({ query, functions }) {
-  const tokens = tokenize(query)
+  const tokens = tokenizeSql(query)
   /** @type {ParserState} */
   const state = { tokens, pos: 0, functions }
   const select = parseSelectInternal(state)

package/src/parse/tokenize.js

@@ -46,6 +46,7 @@ const KEYWORDS = new Set([
   'RIGHT',
   'FULL',
   'OUTER',
+  'POSITIONAL',
   'ON',
   'INTERVAL',
   'DAY',
@@ -60,7 +61,7 @@ const KEYWORDS = new Set([
  * @param {string} sql
  * @returns {Token[]}
  */
-export function tokenize(sql) {
+export function tokenizeSql(sql) {
   /** @type {Token[]} */
   const tokens = []
   const { length } = sql

package/src/types.d.ts

@@ -255,7 +255,7 @@ export interface OrderByItem {
   nulls?: 'FIRST' | 'LAST'
 }
 
-export type JoinType = 'INNER' | 'LEFT' | 'RIGHT' | 'FULL' | 'CROSS'
+export type JoinType = 'INNER' | 'LEFT' | 'RIGHT' | 'FULL' | 'CROSS' | 'POSITIONAL'
 
 export interface JoinClause {
   joinType: JoinType

package/src/validation.js

@@ -211,5 +211,5 @@ export const RESERVED_AFTER_COLUMN = new Set([
 // Keywords that cannot be used as table aliases
 export const RESERVED_AFTER_TABLE = new Set([
   'WHERE', 'GROUP', 'HAVING', 'ORDER', 'LIMIT', 'OFFSET', 'JOIN', 'INNER',
-  'LEFT', 'RIGHT', 'FULL', 'CROSS', 'ON',
+  'LEFT', 'RIGHT', 'FULL', 'CROSS', 'ON', 'POSITIONAL',
 ])