js.documents 7.8.21 → 7.9.0

package/README.md

@@ -606,7 +606,7 @@ import { readFirebirdBackup } from "documents.js";
 const { summary, tables } = readFirebirdBackup(firebirdBackupBytes);
 ```
 
-**SQL `SELECT` engine** — `parseSelect`/`evaluateSelect` run a bounded `SELECT` over `readOdbTables`' output. Closed allowlist grammar: column list or `*` or aggregates (`COUNT`/`SUM`/`AVG`/`MIN`/`MAX`), `FROM` one table plus zero or more `[INNER] JOIN table ON predicate` clauses (a plain nested-loop inner join; a column past the first table must be qualified by its own table name, since there is no alias grammar), optional `WHERE`/`GROUP BY`/`ORDER BY`. OUTER/LEFT/RIGHT/FULL/CROSS/NATURAL joins, subqueries, and everything else outside the grammar throws `HsqldbSqlUnsupportedError`:
+**SQL `SELECT` engine** — `parseSelect`/`evaluateSelect` run a bounded `SELECT` over `readOdbTables`' output. Closed allowlist grammar: column list or `*` or aggregates (`COUNT`/`SUM`/`AVG`/`MIN`/`MAX`), `FROM` one table plus zero or more joins (`[INNER]`, `LEFT [OUTER]`, `RIGHT [OUTER]`, `FULL [OUTER]`, `CROSS`, or `NATURAL`, each a plain nested-loop join with `ON`, `USING (col, ...)`, or NATURAL's own implicit equi-join over shared columns; a `USING`/`NATURAL` join's shared columns merge into one output column, `COALESCE(left, right)`), optional table aliases (`FROM t [AS] alias`, which is what makes a genuine self-join possible), optional `WHERE`/`GROUP BY`/`ORDER BY`. Subqueries, column aliases, and everything else outside the grammar throws `HsqldbSqlUnsupportedError`:
 
 ```ts
 import { decodePackage, readOdbInventory } from "odf.js";
@@ -892,7 +892,7 @@ To run a single test file: `pnpm vitest run src/path/to/file.test.ts`.
 - **The rpt formula engine's group scoping cascades enclosing breaks inward.** A group at level L starts a new instance when its own expression breaks OR when any enclosing group breaks — otherwise a "Q2" subtotal would span two regions. `HASCHANGED` itself knows nothing about groups; the cascade lives in the report structure. Aggregates are computed over complete ranges (not running totals); group expressions may not transitively depend on aggregates (circular).
 - **The rpt function set is a closed allowlist; separator is semicolon.** `rpt:HASCHANGED`/`rpt:LEFT`/`rpt:SUM`/`COUNT`/`AVG`/`MIN`/`MAX`/`field:[COLUMN]` — everything else throws. `[NAME]` and `"NAME"` are one concept. Three refusals where guessing would produce wrong values: non-boolean group expressions, `rpt:LEFT` over non-text, per-row formulas in report header/footer.
 - **The rpt engine emits no page headers/footers** — the renderer places them under a single-logical-page model, at report scope.
-- **The SQL engine is a closed allowlist** — JOINs, subqueries, `UNION`, `DISTINCT`, `HAVING`, `LIMIT`, aliases, `CASE`, arithmetic, etc. all throw `HsqldbSqlUnsupportedError` naming the construct. Silently dropping a clause would return plausible wrong rows.
+- **The SQL engine is a closed allowlist** — subqueries, `UNION`, `DISTINCT`, `HAVING`, `LIMIT`, column aliases, `CASE`, arithmetic, etc. all throw `HsqldbSqlUnsupportedError` naming the construct. Silently dropping a clause would return plausible wrong rows. JOINs (every kind, `USING`, `NATURAL`) and table aliases are real grammar.
 - **Four SQL semantics decisions:** (1) NULL is `{ kind: 'empty' }`, three-valued logic; (2) values compare within classes (numeric/boolean/text), cross-class throws; (3) `GROUP BY` puts NULLs in one group, first-appearance order; `COUNT(*)` counts rows, `COUNT(column)` counts non-NULL; (4) `ORDER BY` sorts NULLs last under ASC, stable.
 - **Unquoted SQL identifiers fold to upper case; double-quoted match exactly.**
 - **All four `.odb` decoder tiers are implemented.** Tier 4 (BINARY/COMPRESSED) is a sibling of Tier 2, not a new value decoder — it recovers DDL as TEXT-format script text and decodes rows through the same per-column encoder. An external-only connection is a permanent scope boundary.

package/dist/{evaluate-DjUkdPfO.d.cts → evaluate-3T-0yAut.d.cts}

@@ -1,5 +1,5 @@
 import { r as HsqldbTable } from "./script-DsGGIzGU.cjs";
-import { f as SqlSelectStatement } from "./parser-D9fiOUfR.cjs";
+import { m as SqlSelectStatement } from "./parser-h1n0BflA.cjs";
 import { ContentCellValue } from "document-schema.js";
 //#region src/odb/sql/evaluate.d.ts
 interface SqlResultSet {

package/dist/{evaluate-BKLK67uP.d.ts → evaluate-Ddsxehrf.d.ts}

@@ -1,5 +1,5 @@
 import { r as HsqldbTable } from "./script-DsGGIzGU.js";
-import { f as SqlSelectStatement } from "./parser-fyVOtBAo.js";
+import { m as SqlSelectStatement } from "./parser-D-9P_0Qd.js";
 import { ContentCellValue } from "document-schema.js";
 //#region src/odb/sql/evaluate.d.ts
 interface SqlResultSet {

package/dist/index.d.cts

@@ -114,8 +114,8 @@ import { odbTablesToSpreadsheetDocument } from "./odb/spreadsheet.cjs";
 import { readOdbForms, readOdbReports } from "./odb/components.cjs";
 import { OdbTableNotFoundError, OdbTableNotSpecifiedError } from "./odb/csv.cjs";
 import { i as tokenizeSql, n as SqlPunctuation, r as SqlToken, t as SqlComparisonOperator } from "./lexer-DgsW7jMA.cjs";
-import { a as SqlJoinClause, c as SqlOperand, d as SqlSelectItem, f as SqlSelectStatement, i as SqlFromClause, l as SqlOrderByTerm, m as parseSelect, n as SqlAggregateFunction, o as SqlLiteral, p as SqlSortDirection, r as SqlColumnRef, s as SqlNameRef, t as SqlAggregateArgument, u as SqlPredicate } from "./parser-D9fiOUfR.cjs";
-import { n as evaluateSelect, t as SqlResultSet } from "./evaluate-DjUkdPfO.cjs";
+import { a as SqlJoinClause, c as SqlLiteral, d as SqlOrderByTerm, f as SqlPredicate, g as parseSelect, h as SqlSortDirection, i as SqlFromClause, l as SqlNameRef, m as SqlSelectStatement, n as SqlAggregateFunction, p as SqlSelectItem, r as SqlColumnRef, t as SqlAggregateArgument, u as SqlOperand } from "./parser-h1n0BflA.cjs";
+import { n as evaluateSelect, t as SqlResultSet } from "./evaluate-3T-0yAut.cjs";
 import { HsqldbSqlEvaluationError, HsqldbSqlParseError, HsqldbSqlUnsupportedError } from "./odb/sql/errors.cjs";
 import { RptBandDefinition, RptBandInstance, RptBandKind, RptGroupDefinition, RptNamedFunctionDefinition, RptReportDefinition, RptReportRun, RptScope, evaluateRptBandOutsideData, runRptReport } from "./odb/formula/evaluate.cjs";
 import { RptAggregateFunction, RptFormula, RptReference, parseRptFormula } from "./odb/formula/parser.cjs";

package/dist/index.d.ts

@@ -114,8 +114,8 @@ import { odbTablesToSpreadsheetDocument } from "./odb/spreadsheet.js";
 import { readOdbForms, readOdbReports } from "./odb/components.js";
 import { OdbTableNotFoundError, OdbTableNotSpecifiedError } from "./odb/csv.js";
 import { i as tokenizeSql, n as SqlPunctuation, r as SqlToken, t as SqlComparisonOperator } from "./lexer-DgsW7jMA.js";
-import { a as SqlJoinClause, c as SqlOperand, d as SqlSelectItem, f as SqlSelectStatement, i as SqlFromClause, l as SqlOrderByTerm, m as parseSelect, n as SqlAggregateFunction, o as SqlLiteral, p as SqlSortDirection, r as SqlColumnRef, s as SqlNameRef, t as SqlAggregateArgument, u as SqlPredicate } from "./parser-fyVOtBAo.js";
-import { n as evaluateSelect, t as SqlResultSet } from "./evaluate-BKLK67uP.js";
+import { a as SqlJoinClause, c as SqlLiteral, d as SqlOrderByTerm, f as SqlPredicate, g as parseSelect, h as SqlSortDirection, i as SqlFromClause, l as SqlNameRef, m as SqlSelectStatement, n as SqlAggregateFunction, p as SqlSelectItem, r as SqlColumnRef, t as SqlAggregateArgument, u as SqlOperand } from "./parser-D-9P_0Qd.js";
+import { n as evaluateSelect, t as SqlResultSet } from "./evaluate-Ddsxehrf.js";
 import { HsqldbSqlEvaluationError, HsqldbSqlParseError, HsqldbSqlUnsupportedError } from "./odb/sql/errors.js";
 import { RptBandDefinition, RptBandInstance, RptBandKind, RptGroupDefinition, RptNamedFunctionDefinition, RptReportDefinition, RptReportRun, RptScope, evaluateRptBandOutsideData, runRptReport } from "./odb/formula/evaluate.js";
 import { RptAggregateFunction, RptFormula, RptReference, parseRptFormula } from "./odb/formula/parser.js";

package/dist/odb/formula/evaluate.d.cts

@@ -1,4 +1,4 @@
-import { t as SqlResultSet } from "../../evaluate-DjUkdPfO.cjs";
+import { t as SqlResultSet } from "../../evaluate-3T-0yAut.cjs";
 import { ContentCellValue } from "document-schema.js";
 //#region src/odb/formula/evaluate.d.ts
 type RptBandKind = "report-header" | "group-header" | "detail" | "group-footer" | "report-footer";

package/dist/odb/formula/evaluate.d.ts

@@ -1,4 +1,4 @@
-import { t as SqlResultSet } from "../../evaluate-BKLK67uP.js";
+import { t as SqlResultSet } from "../../evaluate-Ddsxehrf.js";
 import { ContentCellValue } from "document-schema.js";
 //#region src/odb/formula/evaluate.d.ts
 type RptBandKind = "report-header" | "group-header" | "detail" | "group-footer" | "report-footer";

package/dist/odb/report/render.d.cts

@@ -1,4 +1,4 @@
-import { t as SqlResultSet } from "../../evaluate-DjUkdPfO.cjs";
+import { t as SqlResultSet } from "../../evaluate-3T-0yAut.cjs";
 import { ContentDocument } from "document-schema.js";
 import { OdbReport } from "odf.js";
 //#region src/odb/report/render.d.ts

package/dist/odb/report/render.d.ts

@@ -1,4 +1,4 @@
-import { t as SqlResultSet } from "../../evaluate-BKLK67uP.js";
+import { t as SqlResultSet } from "../../evaluate-Ddsxehrf.js";
 import { ContentDocument } from "document-schema.js";
 import { OdbReport } from "odf.js";
 //#region src/odb/report/render.d.ts

package/dist/odb/report/source.d.cts

@@ -1,5 +1,5 @@
 import { n as HsqldbDecodeOptions } from "../../rowformat-Cl2exlEh.cjs";
-import { t as SqlResultSet } from "../../evaluate-DjUkdPfO.cjs";
+import { t as SqlResultSet } from "../../evaluate-3T-0yAut.cjs";
 import { OdbQueryInfo, OdbReport, Package } from "odf.js";
 //#region src/odb/report/source.d.ts
 declare class OdbReportDataSourceError extends Error {

package/dist/odb/report/source.d.ts

@@ -1,5 +1,5 @@
 import { n as HsqldbDecodeOptions } from "../../rowformat-Cl2exlEh.js";
-import { t as SqlResultSet } from "../../evaluate-BKLK67uP.js";
+import { t as SqlResultSet } from "../../evaluate-Ddsxehrf.js";
 import { OdbQueryInfo, OdbReport, Package } from "odf.js";
 //#region src/odb/report/source.d.ts
 declare class OdbReportDataSourceError extends Error {

package/dist/odb/sql/evaluate.cjs

@@ -71,6 +71,16 @@ function resolveTable(tables, ref, sql) {
 	if (table === void 0) throw new require_odb_sql_errors.HsqldbSqlEvaluationError(`table "${resolvedName}" not found`, sql);
 	return table;
 }
+function columnAt(columns, index, sql) {
+	const column = columns[index];
+	if (column === void 0) throw new require_odb_sql_errors.HsqldbSqlEvaluationError(`column index ${String(index)} is outside the joined column list`, sql);
+	return column;
+}
+function valueAtIndex(row, index, sql) {
+	const value = row[index];
+	if (value === void 0) throw new require_odb_sql_errors.HsqldbSqlEvaluationError(`malformed joined row: it carries ${String(row.length)} values but index ${String(index)} was expected`, sql);
+	return value;
+}
 function resolveColumnIndex(columns, candidateIndices, ref, sql) {
 	let firstExact;
 	let exactCount = 0;
@@ -98,39 +108,32 @@ var ColumnResolver = class {
 	sql;
 	cache = /* @__PURE__ */ new Map();
 	columns;
-	tableNames;
-	constructor(tables, sql) {
+	qualifierNames;
+	constructor(columns, sql) {
 		this.sql = sql;
-		this.tableNames = tables.map((table) => table.tableName);
-		this.columns = tables.flatMap((table) => table.columns.map((column) => ({
-			tableName: table.tableName,
-			columnName: column.name
-		})));
+		this.columns = columns;
+		this.qualifierNames = [...new Set(columns.flatMap((column) => column.qualifiers))];
 	}
 	get columnCount() {
 		return this.columns.length;
 	}
 	nameAt(index) {
-		const column = this.columns[index];
-		if (column === void 0) throw new require_odb_sql_errors.HsqldbSqlEvaluationError(`column index ${String(index)} is outside the joined column list`, this.sql);
-		return column.columnName;
+		return columnAt(this.columns, index, this.sql).columnName;
 	}
 	indexOf(ref) {
 		const cached = this.cache.get(ref);
 		if (cached !== void 0) return cached;
 		let candidateIndices;
 		if (ref.qualifier !== void 0) {
-			const qualifierName = resolveName(this.tableNames, ref.qualifier, "table qualifier", this.sql);
-			candidateIndices = this.columns.map((column, index) => column.tableName === qualifierName ? index : -1).filter((index) => index >= 0);
+			const qualifierName = resolveName(this.qualifierNames, ref.qualifier, "table qualifier", this.sql);
+			candidateIndices = this.columns.map((column, index) => column.qualifiers.includes(qualifierName) ? index : -1).filter((index) => index >= 0);
 		} else candidateIndices = this.columns.map((_column, index) => index);
 		const index = resolveColumnIndex(this.columns, candidateIndices, ref.column, this.sql);
 		this.cache.set(ref, index);
 		return index;
 	}
 	valueAt(index, row) {
-		const value = row[index];
-		if (value === void 0) throw new require_odb_sql_errors.HsqldbSqlEvaluationError(`malformed joined row: it carries ${String(row.length)} values but the joined column list declares ${String(this.columns.length)}`, this.sql);
-		return value;
+		return valueAtIndex(row, index, this.sql);
 	}
 	valueOf(ref, row) {
 		return this.valueAt(this.indexOf(ref), row);
@@ -326,29 +329,129 @@ function evaluateGrouped(statement, plan, matching, resolver) {
 		rows: sortRows(sortable, statement.orderBy.map((term) => term.direction), statement.sql)
 	};
 }
-function joinTables(from, tables, sql) {
-	const baseTable = resolveTable(tables, from.table, sql);
-	const resolvedTables = [baseTable];
-	let rows = baseTable.rows;
-	for (const join of from.joins) {
-		const joinTable = resolveTable(tables, join.table, sql);
-		const resolver = new ColumnResolver([...resolvedTables, joinTable], sql);
-		const nextRows = [];
-		for (const leftRow of rows) for (const rightRow of joinTable.rows) {
-			const combined = [...leftRow, ...rightRow];
-			if (evaluatePredicate(join.on, combined, resolver, sql) === "true") nextRows.push(combined);
-		}
-		rows = nextRows;
-		resolvedTables.push(joinTable);
+function tableColumns(qualifier, table) {
+	return table.columns.map((column) => ({
+		qualifiers: [qualifier],
+		columnName: column.name
+	}));
+}
+function nullRow(count) {
+	return new Array(count).fill(require_odb_values.CELL_NULL);
+}
+function computeNaturalSharedPairs(leftColumns, rightColumns, sql) {
+	const rightIndexByName = /* @__PURE__ */ new Map();
+	const ambiguousRightNames = /* @__PURE__ */ new Set();
+	rightColumns.forEach((column, index) => {
+		if (rightIndexByName.has(column.columnName)) ambiguousRightNames.add(column.columnName);
+		else rightIndexByName.set(column.columnName, index);
+	});
+	const pairs = [];
+	const seenNames = /* @__PURE__ */ new Set();
+	leftColumns.forEach((leftColumn, leftIndex) => {
+		const rightIndex = rightIndexByName.get(leftColumn.columnName);
+		if (rightIndex === void 0) return;
+		if (ambiguousRightNames.has(leftColumn.columnName) || seenNames.has(leftColumn.columnName)) throw new require_odb_sql_errors.HsqldbSqlEvaluationError(`NATURAL JOIN cannot determine a unique match for column "${leftColumn.columnName}" -- more than one column shares that name on one side of the join`, sql);
+		seenNames.add(leftColumn.columnName);
+		pairs.push({
+			leftIndex,
+			rightIndex,
+			columnName: leftColumn.columnName
+		});
+	});
+	return pairs;
+}
+function evaluateSharedColumnMatch(combined, pairs, leftColumnCount, sql) {
+	return pairs.every((pair) => {
+		const left = valueAtIndex(combined, pair.leftIndex, sql);
+		const right = valueAtIndex(combined, leftColumnCount + pair.rightIndex, sql);
+		return left.kind !== "empty" && right.kind !== "empty" && compareValues(left, right, sql) === 0;
+	});
+}
+function mergeSharedColumns(rawColumns, rows, sharedPairs, leftColumnCount, sql) {
+	const sharedLeftIndices = new Set(sharedPairs.map((pair) => pair.leftIndex));
+	const sharedRightIndices = new Set(sharedPairs.map((pair) => leftColumnCount + pair.rightIndex));
+	const remainingIndices = rawColumns.map((_column, index) => index).filter((index) => !sharedLeftIndices.has(index) && !sharedRightIndices.has(index));
+	return {
+		columns: [...sharedPairs.map((pair) => {
+			const leftColumn = columnAt(rawColumns, pair.leftIndex, sql);
+			const rightColumn = columnAt(rawColumns, leftColumnCount + pair.rightIndex, sql);
+			return {
+				qualifiers: [.../* @__PURE__ */ new Set([...leftColumn.qualifiers, ...rightColumn.qualifiers])],
+				columnName: leftColumn.columnName
+			};
+		}), ...remainingIndices.map((index) => columnAt(rawColumns, index, sql))],
+		rows: rows.map((row) => {
+			const mergedValues = sharedPairs.map((pair) => {
+				const leftValue = valueAtIndex(row, pair.leftIndex, sql);
+				const rightValue = valueAtIndex(row, leftColumnCount + pair.rightIndex, sql);
+				return leftValue.kind !== "empty" ? leftValue : rightValue;
+			});
+			const remainingValues = remainingIndices.map((index) => valueAtIndex(row, index, sql));
+			return [...mergedValues, ...remainingValues];
+		})
+	};
+}
+function applyJoinClause(left, join, tables, sql) {
+	const rightTable = resolveTable(tables, join.table, sql);
+	const rightColumns = tableColumns(join.alias !== void 0 ? join.alias.name : rightTable.tableName, rightTable);
+	const leftColumnCount = left.columns.length;
+	const rawColumns = [...left.columns, ...rightColumns];
+	let onPredicate;
+	let sharedPairs = [];
+	if (join.condition.kind === "on") onPredicate = join.condition.predicate;
+	else if (join.condition.kind === "using") {
+		const allLeftIndices = left.columns.map((_column, index) => index);
+		const allRightIndices = rightColumns.map((_column, index) => index);
+		sharedPairs = join.condition.columns.map((ref) => {
+			const leftIndex = resolveColumnIndex(left.columns, allLeftIndices, ref, sql);
+			return {
+				leftIndex,
+				rightIndex: resolveColumnIndex(rightColumns, allRightIndices, ref, sql),
+				columnName: columnAt(left.columns, leftIndex, sql).columnName
+			};
+		});
+	} else if (join.condition.kind === "natural") {
+		sharedPairs = computeNaturalSharedPairs(left.columns, rightColumns, sql);
+		if (sharedPairs.length === 0) throw new require_odb_sql_errors.HsqldbSqlEvaluationError("NATURAL JOIN found no columns shared between the joined tables", sql);
 	}
+	const rawResolver = new ColumnResolver(rawColumns, sql);
+	const matchedLeft = /* @__PURE__ */ new Set();
+	const matchedRight = /* @__PURE__ */ new Set();
+	const paired = [];
+	left.rows.forEach((leftRow, leftIndex) => {
+		rightTable.rows.forEach((rightRow, rightIndex) => {
+			const combined = [...leftRow, ...rightRow];
+			if (onPredicate !== void 0 ? evaluatePredicate(onPredicate, combined, rawResolver, sql) === "true" : sharedPairs.length > 0 ? evaluateSharedColumnMatch(combined, sharedPairs, leftColumnCount, sql) : true) {
+				paired.push(combined);
+				matchedLeft.add(leftIndex);
+				matchedRight.add(rightIndex);
+			}
+		});
+	});
+	if (join.joinKind === "left" || join.joinKind === "full") left.rows.forEach((leftRow, leftIndex) => {
+		if (!matchedLeft.has(leftIndex)) paired.push([...leftRow, ...nullRow(rightColumns.length)]);
+	});
+	if (join.joinKind === "right" || join.joinKind === "full") rightTable.rows.forEach((rightRow, rightIndex) => {
+		if (!matchedRight.has(rightIndex)) paired.push([...nullRow(leftColumnCount), ...rightRow]);
+	});
+	if (join.condition.kind === "using" || join.condition.kind === "natural") return mergeSharedColumns(rawColumns, paired, sharedPairs, leftColumnCount, sql);
 	return {
-		resolvedTables,
-		rows
+		columns: rawColumns,
+		rows: paired
+	};
+}
+function joinTables(from, tables, sql) {
+	const baseTable = resolveTable(tables, from.table, sql);
+	let result = {
+		columns: tableColumns(from.alias !== void 0 ? from.alias.name : baseTable.tableName, baseTable),
+		rows: baseTable.rows
 	};
+	for (const join of from.joins) result = applyJoinClause(result, join, tables, sql);
+	return result;
 }
 function evaluateSelect(statement, tables) {
-	const { resolvedTables, rows } = joinTables(statement.from, tables, statement.sql);
-	const resolver = new ColumnResolver(resolvedTables, statement.sql);
+	const { columns, rows } = joinTables(statement.from, tables, statement.sql);
+	const resolver = new ColumnResolver(columns, statement.sql);
 	const plan = planSelectList(statement, resolver);
 	const where = statement.where;
 	const matching = where === void 0 ? rows : rows.filter((row) => evaluatePredicate(where, row, resolver, statement.sql) === "true");

package/dist/odb/sql/evaluate.d.cts

@@ -1,2 +1,2 @@
-import { n as evaluateSelect, t as SqlResultSet } from "../../evaluate-DjUkdPfO.cjs";
+import { n as evaluateSelect, t as SqlResultSet } from "../../evaluate-3T-0yAut.cjs";
 export { SqlResultSet, evaluateSelect };

package/dist/odb/sql/evaluate.d.ts

@@ -1,2 +1,2 @@
-import { n as evaluateSelect, t as SqlResultSet } from "../../evaluate-BKLK67uP.js";
+import { n as evaluateSelect, t as SqlResultSet } from "../../evaluate-Ddsxehrf.js";
 export { SqlResultSet, evaluateSelect };

package/dist/odb/sql/evaluate.js

@@ -70,6 +70,16 @@ function resolveTable(tables, ref, sql) {
 	if (table === void 0) throw new HsqldbSqlEvaluationError(`table "${resolvedName}" not found`, sql);
 	return table;
 }
+function columnAt(columns, index, sql) {
+	const column = columns[index];
+	if (column === void 0) throw new HsqldbSqlEvaluationError(`column index ${String(index)} is outside the joined column list`, sql);
+	return column;
+}
+function valueAtIndex(row, index, sql) {
+	const value = row[index];
+	if (value === void 0) throw new HsqldbSqlEvaluationError(`malformed joined row: it carries ${String(row.length)} values but index ${String(index)} was expected`, sql);
+	return value;
+}
 function resolveColumnIndex(columns, candidateIndices, ref, sql) {
 	let firstExact;
 	let exactCount = 0;
@@ -97,39 +107,32 @@ var ColumnResolver = class {
 	sql;
 	cache = /* @__PURE__ */ new Map();
 	columns;
-	tableNames;
-	constructor(tables, sql) {
+	qualifierNames;
+	constructor(columns, sql) {
 		this.sql = sql;
-		this.tableNames = tables.map((table) => table.tableName);
-		this.columns = tables.flatMap((table) => table.columns.map((column) => ({
-			tableName: table.tableName,
-			columnName: column.name
-		})));
+		this.columns = columns;
+		this.qualifierNames = [...new Set(columns.flatMap((column) => column.qualifiers))];
 	}
 	get columnCount() {
 		return this.columns.length;
 	}
 	nameAt(index) {
-		const column = this.columns[index];
-		if (column === void 0) throw new HsqldbSqlEvaluationError(`column index ${String(index)} is outside the joined column list`, this.sql);
-		return column.columnName;
+		return columnAt(this.columns, index, this.sql).columnName;
 	}
 	indexOf(ref) {
 		const cached = this.cache.get(ref);
 		if (cached !== void 0) return cached;
 		let candidateIndices;
 		if (ref.qualifier !== void 0) {
-			const qualifierName = resolveName(this.tableNames, ref.qualifier, "table qualifier", this.sql);
-			candidateIndices = this.columns.map((column, index) => column.tableName === qualifierName ? index : -1).filter((index) => index >= 0);
+			const qualifierName = resolveName(this.qualifierNames, ref.qualifier, "table qualifier", this.sql);
+			candidateIndices = this.columns.map((column, index) => column.qualifiers.includes(qualifierName) ? index : -1).filter((index) => index >= 0);
 		} else candidateIndices = this.columns.map((_column, index) => index);
 		const index = resolveColumnIndex(this.columns, candidateIndices, ref.column, this.sql);
 		this.cache.set(ref, index);
 		return index;
 	}
 	valueAt(index, row) {
-		const value = row[index];
-		if (value === void 0) throw new HsqldbSqlEvaluationError(`malformed joined row: it carries ${String(row.length)} values but the joined column list declares ${String(this.columns.length)}`, this.sql);
-		return value;
+		return valueAtIndex(row, index, this.sql);
 	}
 	valueOf(ref, row) {
 		return this.valueAt(this.indexOf(ref), row);
@@ -325,29 +328,129 @@ function evaluateGrouped(statement, plan, matching, resolver) {
 		rows: sortRows(sortable, statement.orderBy.map((term) => term.direction), statement.sql)
 	};
 }
-function joinTables(from, tables, sql) {
-	const baseTable = resolveTable(tables, from.table, sql);
-	const resolvedTables = [baseTable];
-	let rows = baseTable.rows;
-	for (const join of from.joins) {
-		const joinTable = resolveTable(tables, join.table, sql);
-		const resolver = new ColumnResolver([...resolvedTables, joinTable], sql);
-		const nextRows = [];
-		for (const leftRow of rows) for (const rightRow of joinTable.rows) {
-			const combined = [...leftRow, ...rightRow];
-			if (evaluatePredicate(join.on, combined, resolver, sql) === "true") nextRows.push(combined);
-		}
-		rows = nextRows;
-		resolvedTables.push(joinTable);
+function tableColumns(qualifier, table) {
+	return table.columns.map((column) => ({
+		qualifiers: [qualifier],
+		columnName: column.name
+	}));
+}
+function nullRow(count) {
+	return new Array(count).fill(CELL_NULL);
+}
+function computeNaturalSharedPairs(leftColumns, rightColumns, sql) {
+	const rightIndexByName = /* @__PURE__ */ new Map();
+	const ambiguousRightNames = /* @__PURE__ */ new Set();
+	rightColumns.forEach((column, index) => {
+		if (rightIndexByName.has(column.columnName)) ambiguousRightNames.add(column.columnName);
+		else rightIndexByName.set(column.columnName, index);
+	});
+	const pairs = [];
+	const seenNames = /* @__PURE__ */ new Set();
+	leftColumns.forEach((leftColumn, leftIndex) => {
+		const rightIndex = rightIndexByName.get(leftColumn.columnName);
+		if (rightIndex === void 0) return;
+		if (ambiguousRightNames.has(leftColumn.columnName) || seenNames.has(leftColumn.columnName)) throw new HsqldbSqlEvaluationError(`NATURAL JOIN cannot determine a unique match for column "${leftColumn.columnName}" -- more than one column shares that name on one side of the join`, sql);
+		seenNames.add(leftColumn.columnName);
+		pairs.push({
+			leftIndex,
+			rightIndex,
+			columnName: leftColumn.columnName
+		});
+	});
+	return pairs;
+}
+function evaluateSharedColumnMatch(combined, pairs, leftColumnCount, sql) {
+	return pairs.every((pair) => {
+		const left = valueAtIndex(combined, pair.leftIndex, sql);
+		const right = valueAtIndex(combined, leftColumnCount + pair.rightIndex, sql);
+		return left.kind !== "empty" && right.kind !== "empty" && compareValues(left, right, sql) === 0;
+	});
+}
+function mergeSharedColumns(rawColumns, rows, sharedPairs, leftColumnCount, sql) {
+	const sharedLeftIndices = new Set(sharedPairs.map((pair) => pair.leftIndex));
+	const sharedRightIndices = new Set(sharedPairs.map((pair) => leftColumnCount + pair.rightIndex));
+	const remainingIndices = rawColumns.map((_column, index) => index).filter((index) => !sharedLeftIndices.has(index) && !sharedRightIndices.has(index));
+	return {
+		columns: [...sharedPairs.map((pair) => {
+			const leftColumn = columnAt(rawColumns, pair.leftIndex, sql);
+			const rightColumn = columnAt(rawColumns, leftColumnCount + pair.rightIndex, sql);
+			return {
+				qualifiers: [.../* @__PURE__ */ new Set([...leftColumn.qualifiers, ...rightColumn.qualifiers])],
+				columnName: leftColumn.columnName
+			};
+		}), ...remainingIndices.map((index) => columnAt(rawColumns, index, sql))],
+		rows: rows.map((row) => {
+			const mergedValues = sharedPairs.map((pair) => {
+				const leftValue = valueAtIndex(row, pair.leftIndex, sql);
+				const rightValue = valueAtIndex(row, leftColumnCount + pair.rightIndex, sql);
+				return leftValue.kind !== "empty" ? leftValue : rightValue;
+			});
+			const remainingValues = remainingIndices.map((index) => valueAtIndex(row, index, sql));
+			return [...mergedValues, ...remainingValues];
+		})
+	};
+}
+function applyJoinClause(left, join, tables, sql) {
+	const rightTable = resolveTable(tables, join.table, sql);
+	const rightColumns = tableColumns(join.alias !== void 0 ? join.alias.name : rightTable.tableName, rightTable);
+	const leftColumnCount = left.columns.length;
+	const rawColumns = [...left.columns, ...rightColumns];
+	let onPredicate;
+	let sharedPairs = [];
+	if (join.condition.kind === "on") onPredicate = join.condition.predicate;
+	else if (join.condition.kind === "using") {
+		const allLeftIndices = left.columns.map((_column, index) => index);
+		const allRightIndices = rightColumns.map((_column, index) => index);
+		sharedPairs = join.condition.columns.map((ref) => {
+			const leftIndex = resolveColumnIndex(left.columns, allLeftIndices, ref, sql);
+			return {
+				leftIndex,
+				rightIndex: resolveColumnIndex(rightColumns, allRightIndices, ref, sql),
+				columnName: columnAt(left.columns, leftIndex, sql).columnName
+			};
+		});
+	} else if (join.condition.kind === "natural") {
+		sharedPairs = computeNaturalSharedPairs(left.columns, rightColumns, sql);
+		if (sharedPairs.length === 0) throw new HsqldbSqlEvaluationError("NATURAL JOIN found no columns shared between the joined tables", sql);
 	}
+	const rawResolver = new ColumnResolver(rawColumns, sql);
+	const matchedLeft = /* @__PURE__ */ new Set();
+	const matchedRight = /* @__PURE__ */ new Set();
+	const paired = [];
+	left.rows.forEach((leftRow, leftIndex) => {
+		rightTable.rows.forEach((rightRow, rightIndex) => {
+			const combined = [...leftRow, ...rightRow];
+			if (onPredicate !== void 0 ? evaluatePredicate(onPredicate, combined, rawResolver, sql) === "true" : sharedPairs.length > 0 ? evaluateSharedColumnMatch(combined, sharedPairs, leftColumnCount, sql) : true) {
+				paired.push(combined);
+				matchedLeft.add(leftIndex);
+				matchedRight.add(rightIndex);
+			}
+		});
+	});
+	if (join.joinKind === "left" || join.joinKind === "full") left.rows.forEach((leftRow, leftIndex) => {
+		if (!matchedLeft.has(leftIndex)) paired.push([...leftRow, ...nullRow(rightColumns.length)]);
+	});
+	if (join.joinKind === "right" || join.joinKind === "full") rightTable.rows.forEach((rightRow, rightIndex) => {
+		if (!matchedRight.has(rightIndex)) paired.push([...nullRow(leftColumnCount), ...rightRow]);
+	});
+	if (join.condition.kind === "using" || join.condition.kind === "natural") return mergeSharedColumns(rawColumns, paired, sharedPairs, leftColumnCount, sql);
 	return {
-		resolvedTables,
-		rows
+		columns: rawColumns,
+		rows: paired
+	};
+}
+function joinTables(from, tables, sql) {
+	const baseTable = resolveTable(tables, from.table, sql);
+	let result = {
+		columns: tableColumns(from.alias !== void 0 ? from.alias.name : baseTable.tableName, baseTable),
+		rows: baseTable.rows
 	};
+	for (const join of from.joins) result = applyJoinClause(result, join, tables, sql);
+	return result;
 }
 function evaluateSelect(statement, tables) {
-	const { resolvedTables, rows } = joinTables(statement.from, tables, statement.sql);
-	const resolver = new ColumnResolver(resolvedTables, statement.sql);
+	const { columns, rows } = joinTables(statement.from, tables, statement.sql);
+	const resolver = new ColumnResolver(columns, statement.sql);
 	const plan = planSelectList(statement, resolver);
 	const where = statement.where;
 	const matching = where === void 0 ? rows : rows.filter((row) => evaluatePredicate(where, row, resolver, statement.sql) === "true");

package/dist/odb/sql/parser.cjs

@@ -13,13 +13,6 @@ function isAggregateFunction(keyword) {
 	return AGGREGATE_FUNCTIONS.has(keyword);
 }
 const OUT_OF_SCOPE_KEYWORDS = /* @__PURE__ */ new Map([
-	["OUTER", "a JOIN"],
-	["LEFT", "a JOIN"],
-	["RIGHT", "a JOIN"],
-	["FULL", "a JOIN"],
-	["CROSS", "a JOIN"],
-	["NATURAL", "a JOIN"],
-	["USING", "a JOIN"],
 	["UNION", "UNION"],
 	["INTERSECT", "INTERSECT"],
 	["EXCEPT", "EXCEPT"],
@@ -31,7 +24,6 @@ const OUT_OF_SCOPE_KEYWORDS = /* @__PURE__ */ new Map([
 	["OFFSET", "a row-limit clause (OFFSET)"],
 	["FETCH", "a row-limit clause (FETCH)"],
 	["TOP", "a row-limit clause (TOP)"],
-	["AS", "a column or table alias (AS)"],
 	["CASE", "a CASE expression"],
 	["WHEN", "a CASE expression"],
 	["THEN", "a CASE expression"],
@@ -175,11 +167,12 @@ var SqlParser = class {
 	}
 	parseSelectItem() {
 		const token = this.peek();
-		if (token.kind === "keyword" && isAggregateFunction(token.keyword)) return this.parseAggregate(token.keyword);
-		return {
+		const item = token.kind === "keyword" && isAggregateFunction(token.keyword) ? this.parseAggregate(token.keyword) : {
 			kind: "column",
 			column: this.parseColumnRef()
 		};
+		if (this.atKeyword("AS")) throw new require_odb_sql_errors.HsqldbSqlUnsupportedError("a column alias (AS)", this.sql);
+		return item;
 	}
 	parseSelectList() {
 		if (this.atPunctuation("*")) {
@@ -439,27 +432,93 @@ var SqlParser = class {
 			direction: "asc"
 		};
 	}
-	parseTableRef() {
+	parseTableRefWithAlias() {
 		if (this.atPunctuation("(")) throw new require_odb_sql_errors.HsqldbSqlUnsupportedError("a derived table in FROM", this.sql);
-		const name = this.takeName("a table name");
+		const table = this.takeName("a table name");
 		if (this.atPunctuation(".")) throw new require_odb_sql_errors.HsqldbSqlUnsupportedError("a schema-qualified table name", this.sql);
-		if (this.peek().kind === "identifier") throw new require_odb_sql_errors.HsqldbSqlUnsupportedError("a table alias", this.sql);
-		return name;
+		return {
+			table,
+			alias: this.parseOptionalTableAlias()
+		};
+	}
+	parseOptionalTableAlias() {
+		if (this.atKeyword("AS")) {
+			this.advance();
+			return this.takeName("a table alias after AS");
+		}
+		if (this.peek().kind === "identifier") return this.takeName("a table alias");
+	}
+	parseJoinKind() {
+		if (this.atKeyword("INNER")) {
+			this.advance();
+			return "inner";
+		}
+		if (this.atKeyword("LEFT")) {
+			this.advance();
+			this.consumeOptionalOuter();
+			return "left";
+		}
+		if (this.atKeyword("RIGHT")) {
+			this.advance();
+			this.consumeOptionalOuter();
+			return "right";
+		}
+		if (this.atKeyword("FULL")) {
+			this.advance();
+			this.consumeOptionalOuter();
+			return "full";
+		}
+		if (this.atKeyword("CROSS")) {
+			this.advance();
+			return "cross";
+		}
+		if (this.atKeyword("JOIN")) return "inner";
+	}
+	consumeOptionalOuter() {
+		if (this.atKeyword("OUTER")) this.advance();
+	}
+	parseJoinCondition(joinKind, natural) {
+		if (natural) return { kind: "natural" };
+		if (joinKind === "cross") return { kind: "none" };
+		if (this.atKeyword("USING")) {
+			this.advance();
+			this.takePunctuation("(");
+			const columns = [this.takeName("a column name in USING")];
+			while (this.atPunctuation(",")) {
+				this.advance();
+				columns.push(this.takeName("a column name in USING"));
+			}
+			this.takePunctuation(")");
+			return {
+				kind: "using",
+				columns
+			};
+		}
+		this.takeKeyword("ON");
+		return {
+			kind: "on",
+			predicate: this.parsePredicate()
+		};
 	}
 	parseJoins() {
 		const joins = [];
 		for (;;) {
-			if (this.atKeyword("INNER")) {
-				this.advance();
-				this.takeKeyword("JOIN");
-			} else if (this.atKeyword("JOIN")) this.advance();
-			else break;
-			const table = this.parseTableRef();
-			this.takeKeyword("ON");
-			const on = this.parsePredicate();
+			const natural = this.atKeyword("NATURAL");
+			if (natural) this.advance();
+			const joinKind = this.parseJoinKind();
+			if (joinKind === void 0) {
+				if (natural) this.fail("keyword JOIN, INNER, LEFT, RIGHT or FULL after NATURAL");
+				break;
+			}
+			if (natural && joinKind === "cross") this.fail("keyword JOIN, INNER, LEFT, RIGHT or FULL after NATURAL (NATURAL CROSS JOIN is not valid SQL)");
+			this.takeKeyword("JOIN");
+			const { table, alias } = this.parseTableRefWithAlias();
+			const condition = this.parseJoinCondition(joinKind, natural);
 			joins.push({
+				joinKind,
 				table,
-				on
+				alias,
+				condition
 			});
 		}
 		return joins;
@@ -470,8 +529,10 @@ var SqlParser = class {
 		this.advance();
 		const items = this.parseSelectList();
 		this.takeKeyword("FROM");
+		const { table, alias } = this.parseTableRefWithAlias();
 		const from = {
-			table: this.parseTableRef(),
+			table,
+			alias,
 			joins: this.parseJoins()
 		};
 		if (this.atPunctuation(",")) throw new require_odb_sql_errors.HsqldbSqlUnsupportedError("a comma-separated FROM list (write an explicit JOIN instead)", this.sql);

package/dist/odb/sql/parser.d.cts

@@ -1,2 +1,2 @@
-import { a as SqlJoinClause, c as SqlOperand, d as SqlSelectItem, f as SqlSelectStatement, i as SqlFromClause, l as SqlOrderByTerm, m as parseSelect, n as SqlAggregateFunction, o as SqlLiteral, p as SqlSortDirection, r as SqlColumnRef, s as SqlNameRef, t as SqlAggregateArgument, u as SqlPredicate } from "../../parser-D9fiOUfR.cjs";
-export { SqlAggregateArgument, SqlAggregateFunction, SqlColumnRef, SqlFromClause, SqlJoinClause, SqlLiteral, SqlNameRef, SqlOperand, SqlOrderByTerm, SqlPredicate, SqlSelectItem, SqlSelectStatement, SqlSortDirection, parseSelect };
+import { a as SqlJoinClause, c as SqlLiteral, d as SqlOrderByTerm, f as SqlPredicate, g as parseSelect, h as SqlSortDirection, i as SqlFromClause, l as SqlNameRef, m as SqlSelectStatement, n as SqlAggregateFunction, o as SqlJoinCondition, p as SqlSelectItem, r as SqlColumnRef, s as SqlJoinKind, t as SqlAggregateArgument, u as SqlOperand } from "../../parser-h1n0BflA.cjs";
+export { SqlAggregateArgument, SqlAggregateFunction, SqlColumnRef, SqlFromClause, SqlJoinClause, SqlJoinCondition, SqlJoinKind, SqlLiteral, SqlNameRef, SqlOperand, SqlOrderByTerm, SqlPredicate, SqlSelectItem, SqlSelectStatement, SqlSortDirection, parseSelect };

package/dist/odb/sql/parser.d.ts

@@ -1,2 +1,2 @@
-import { a as SqlJoinClause, c as SqlOperand, d as SqlSelectItem, f as SqlSelectStatement, i as SqlFromClause, l as SqlOrderByTerm, m as parseSelect, n as SqlAggregateFunction, o as SqlLiteral, p as SqlSortDirection, r as SqlColumnRef, s as SqlNameRef, t as SqlAggregateArgument, u as SqlPredicate } from "../../parser-fyVOtBAo.js";
-export { SqlAggregateArgument, SqlAggregateFunction, SqlColumnRef, SqlFromClause, SqlJoinClause, SqlLiteral, SqlNameRef, SqlOperand, SqlOrderByTerm, SqlPredicate, SqlSelectItem, SqlSelectStatement, SqlSortDirection, parseSelect };
+import { a as SqlJoinClause, c as SqlLiteral, d as SqlOrderByTerm, f as SqlPredicate, g as parseSelect, h as SqlSortDirection, i as SqlFromClause, l as SqlNameRef, m as SqlSelectStatement, n as SqlAggregateFunction, o as SqlJoinCondition, p as SqlSelectItem, r as SqlColumnRef, s as SqlJoinKind, t as SqlAggregateArgument, u as SqlOperand } from "../../parser-D-9P_0Qd.js";
+export { SqlAggregateArgument, SqlAggregateFunction, SqlColumnRef, SqlFromClause, SqlJoinClause, SqlJoinCondition, SqlJoinKind, SqlLiteral, SqlNameRef, SqlOperand, SqlOrderByTerm, SqlPredicate, SqlSelectItem, SqlSelectStatement, SqlSortDirection, parseSelect };

package/dist/odb/sql/parser.js

@@ -12,13 +12,6 @@ function isAggregateFunction(keyword) {
 	return AGGREGATE_FUNCTIONS.has(keyword);
 }
 const OUT_OF_SCOPE_KEYWORDS = /* @__PURE__ */ new Map([
-	["OUTER", "a JOIN"],
-	["LEFT", "a JOIN"],
-	["RIGHT", "a JOIN"],
-	["FULL", "a JOIN"],
-	["CROSS", "a JOIN"],
-	["NATURAL", "a JOIN"],
-	["USING", "a JOIN"],
 	["UNION", "UNION"],
 	["INTERSECT", "INTERSECT"],
 	["EXCEPT", "EXCEPT"],
@@ -30,7 +23,6 @@ const OUT_OF_SCOPE_KEYWORDS = /* @__PURE__ */ new Map([
 	["OFFSET", "a row-limit clause (OFFSET)"],
 	["FETCH", "a row-limit clause (FETCH)"],
 	["TOP", "a row-limit clause (TOP)"],
-	["AS", "a column or table alias (AS)"],
 	["CASE", "a CASE expression"],
 	["WHEN", "a CASE expression"],
 	["THEN", "a CASE expression"],
@@ -174,11 +166,12 @@ var SqlParser = class {
 	}
 	parseSelectItem() {
 		const token = this.peek();
-		if (token.kind === "keyword" && isAggregateFunction(token.keyword)) return this.parseAggregate(token.keyword);
-		return {
+		const item = token.kind === "keyword" && isAggregateFunction(token.keyword) ? this.parseAggregate(token.keyword) : {
 			kind: "column",
 			column: this.parseColumnRef()
 		};
+		if (this.atKeyword("AS")) throw new HsqldbSqlUnsupportedError("a column alias (AS)", this.sql);
+		return item;
 	}
 	parseSelectList() {
 		if (this.atPunctuation("*")) {
@@ -438,27 +431,93 @@ var SqlParser = class {
 			direction: "asc"
 		};
 	}
-	parseTableRef() {
+	parseTableRefWithAlias() {
 		if (this.atPunctuation("(")) throw new HsqldbSqlUnsupportedError("a derived table in FROM", this.sql);
-		const name = this.takeName("a table name");
+		const table = this.takeName("a table name");
 		if (this.atPunctuation(".")) throw new HsqldbSqlUnsupportedError("a schema-qualified table name", this.sql);
-		if (this.peek().kind === "identifier") throw new HsqldbSqlUnsupportedError("a table alias", this.sql);
-		return name;
+		return {
+			table,
+			alias: this.parseOptionalTableAlias()
+		};
+	}
+	parseOptionalTableAlias() {
+		if (this.atKeyword("AS")) {
+			this.advance();
+			return this.takeName("a table alias after AS");
+		}
+		if (this.peek().kind === "identifier") return this.takeName("a table alias");
+	}
+	parseJoinKind() {
+		if (this.atKeyword("INNER")) {
+			this.advance();
+			return "inner";
+		}
+		if (this.atKeyword("LEFT")) {
+			this.advance();
+			this.consumeOptionalOuter();
+			return "left";
+		}
+		if (this.atKeyword("RIGHT")) {
+			this.advance();
+			this.consumeOptionalOuter();
+			return "right";
+		}
+		if (this.atKeyword("FULL")) {
+			this.advance();
+			this.consumeOptionalOuter();
+			return "full";
+		}
+		if (this.atKeyword("CROSS")) {
+			this.advance();
+			return "cross";
+		}
+		if (this.atKeyword("JOIN")) return "inner";
+	}
+	consumeOptionalOuter() {
+		if (this.atKeyword("OUTER")) this.advance();
+	}
+	parseJoinCondition(joinKind, natural) {
+		if (natural) return { kind: "natural" };
+		if (joinKind === "cross") return { kind: "none" };
+		if (this.atKeyword("USING")) {
+			this.advance();
+			this.takePunctuation("(");
+			const columns = [this.takeName("a column name in USING")];
+			while (this.atPunctuation(",")) {
+				this.advance();
+				columns.push(this.takeName("a column name in USING"));
+			}
+			this.takePunctuation(")");
+			return {
+				kind: "using",
+				columns
+			};
+		}
+		this.takeKeyword("ON");
+		return {
+			kind: "on",
+			predicate: this.parsePredicate()
+		};
 	}
 	parseJoins() {
 		const joins = [];
 		for (;;) {
-			if (this.atKeyword("INNER")) {
-				this.advance();
-				this.takeKeyword("JOIN");
-			} else if (this.atKeyword("JOIN")) this.advance();
-			else break;
-			const table = this.parseTableRef();
-			this.takeKeyword("ON");
-			const on = this.parsePredicate();
+			const natural = this.atKeyword("NATURAL");
+			if (natural) this.advance();
+			const joinKind = this.parseJoinKind();
+			if (joinKind === void 0) {
+				if (natural) this.fail("keyword JOIN, INNER, LEFT, RIGHT or FULL after NATURAL");
+				break;
+			}
+			if (natural && joinKind === "cross") this.fail("keyword JOIN, INNER, LEFT, RIGHT or FULL after NATURAL (NATURAL CROSS JOIN is not valid SQL)");
+			this.takeKeyword("JOIN");
+			const { table, alias } = this.parseTableRefWithAlias();
+			const condition = this.parseJoinCondition(joinKind, natural);
 			joins.push({
+				joinKind,
 				table,
-				on
+				alias,
+				condition
 			});
 		}
 		return joins;
@@ -469,8 +528,10 @@ var SqlParser = class {
 		this.advance();
 		const items = this.parseSelectList();
 		this.takeKeyword("FROM");
+		const { table, alias } = this.parseTableRefWithAlias();
 		const from = {
-			table: this.parseTableRef(),
+			table,
+			alias,
 			joins: this.parseJoins()
 		};
 		if (this.atPunctuation(",")) throw new HsqldbSqlUnsupportedError("a comma-separated FROM list (write an explicit JOIN instead)", this.sql);

package/dist/{parser-fyVOtBAo.d.ts → parser-D-9P_0Qd.d.ts}

@@ -88,12 +88,27 @@ interface SqlOrderByTerm {
   readonly column: SqlColumnRef;
   readonly direction: SqlSortDirection;
 }
+type SqlJoinKind = "inner" | "left" | "right" | "full" | "cross";
+type SqlJoinCondition = {
+  readonly kind: "on";
+  readonly predicate: SqlPredicate;
+} | {
+  readonly kind: "using";
+  readonly columns: readonly SqlNameRef[];
+} | {
+  readonly kind: "natural";
+} | {
+  readonly kind: "none";
+};
 interface SqlJoinClause {
+  readonly joinKind: SqlJoinKind;
   readonly table: SqlNameRef;
-  readonly on: SqlPredicate;
+  readonly alias: SqlNameRef | undefined;
+  readonly condition: SqlJoinCondition;
 }
 interface SqlFromClause {
   readonly table: SqlNameRef;
+  readonly alias: SqlNameRef | undefined;
   readonly joins: readonly SqlJoinClause[];
 }
 interface SqlSelectStatement {
@@ -106,4 +121,4 @@ interface SqlSelectStatement {
 }
 declare function parseSelect(sql: string): SqlSelectStatement;
 //#endregion
-export { SqlJoinClause as a, SqlOperand as c, SqlSelectItem as d, SqlSelectStatement as f, SqlFromClause as i, SqlOrderByTerm as l, parseSelect as m, SqlAggregateFunction as n, SqlLiteral as o, SqlSortDirection as p, SqlColumnRef as r, SqlNameRef as s, SqlAggregateArgument as t, SqlPredicate as u };
+export { SqlJoinClause as a, SqlLiteral as c, SqlOrderByTerm as d, SqlPredicate as f, parseSelect as g, SqlSortDirection as h, SqlFromClause as i, SqlNameRef as l, SqlSelectStatement as m, SqlAggregateFunction as n, SqlJoinCondition as o, SqlSelectItem as p, SqlColumnRef as r, SqlJoinKind as s, SqlAggregateArgument as t, SqlOperand as u };

package/dist/{parser-D9fiOUfR.d.cts → parser-h1n0BflA.d.cts}

@@ -88,12 +88,27 @@ interface SqlOrderByTerm {
   readonly column: SqlColumnRef;
   readonly direction: SqlSortDirection;
 }
+type SqlJoinKind = "inner" | "left" | "right" | "full" | "cross";
+type SqlJoinCondition = {
+  readonly kind: "on";
+  readonly predicate: SqlPredicate;
+} | {
+  readonly kind: "using";
+  readonly columns: readonly SqlNameRef[];
+} | {
+  readonly kind: "natural";
+} | {
+  readonly kind: "none";
+};
 interface SqlJoinClause {
+  readonly joinKind: SqlJoinKind;
   readonly table: SqlNameRef;
-  readonly on: SqlPredicate;
+  readonly alias: SqlNameRef | undefined;
+  readonly condition: SqlJoinCondition;
 }
 interface SqlFromClause {
   readonly table: SqlNameRef;
+  readonly alias: SqlNameRef | undefined;
   readonly joins: readonly SqlJoinClause[];
 }
 interface SqlSelectStatement {
@@ -106,4 +121,4 @@ interface SqlSelectStatement {
 }
 declare function parseSelect(sql: string): SqlSelectStatement;
 //#endregion
-export { SqlJoinClause as a, SqlOperand as c, SqlSelectItem as d, SqlSelectStatement as f, SqlFromClause as i, SqlOrderByTerm as l, parseSelect as m, SqlAggregateFunction as n, SqlLiteral as o, SqlSortDirection as p, SqlColumnRef as r, SqlNameRef as s, SqlAggregateArgument as t, SqlPredicate as u };
+export { SqlJoinClause as a, SqlLiteral as c, SqlOrderByTerm as d, SqlPredicate as f, parseSelect as g, SqlSortDirection as h, SqlFromClause as i, SqlNameRef as l, SqlSelectStatement as m, SqlAggregateFunction as n, SqlJoinCondition as o, SqlSelectItem as p, SqlColumnRef as r, SqlJoinKind as s, SqlAggregateArgument as t, SqlOperand as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "js.documents",
-  "version": "7.8.21",
+  "version": "7.9.0",
   "description": "Bidirectional docx/pptx <-> PDF conversion and a read+write editable OOXML document model, built on ooxml.js and Zod 4 codecs.",
   "type": "module",
   "repository": {
@@ -91,7 +91,7 @@
     "rtf-codec": "4.1.3",
     "temml": "0.13.4",
     "wpd-codec": "3.2.1",
-    "xls-codec": "4.10.0",
+    "xls-codec": "4.11.0",
     "zod": "4.4.3"
   },
   "devDependencies": {