relq 1.0.86 → 1.0.88

package/dist/cjs/core/helpers/select-joins.cjs

@@ -25,7 +25,12 @@ function executeTypeSafeJoin(ctx, joinType, tableOrAlias, callback) {
     const rightProxy = (0, table_proxy_1.createTableProxy)(rightTableName, rightAlias, rightTableDef);
     const conditionBuilder = new join_condition_builder_1.JoinConditionBuilder();
     if (callback) {
-        callback(conditionBuilder, leftProxy, rightProxy);
+        if (joinType === 'RIGHT JOIN') {
+            callback(conditionBuilder, leftProxy, rightProxy);
+        }
+        else {
+            callback(conditionBuilder, rightProxy, leftProxy);
+        }
     }
     const conditionInternals = conditionBuilder[join_internals_1.JOIN_INTERNAL];
     if (!conditionInternals.hasConditions() && schema && relations) {
@@ -37,7 +42,7 @@ function executeTypeSafeJoin(ctx, joinType, tableOrAlias, callback) {
         }
         else {
             throw new relq_errors_1.RelqQueryError(`Cannot auto-resolve FK relationship between "${ctx.schemaKey || ctx.tableName}" and "${rightTableKey}". ` +
-                `Either provide a callback with explicit join conditions, or define the relationship in your relations config.`, { hint: `Use .join('${rightTableKey}', (on, left, right) => on.equal(left.columnName, right.id))` });
+                `Either provide a callback with explicit join conditions, or define the relationship in your relations config.`, { hint: `Use .join('${rightTableKey}', (on, ${rightTableKey}, source) => on.equal(${rightTableKey}.id, source.columnName))` });
         }
     }
     const selectedProps = conditionInternals.getSelectedColumns();
@@ -93,7 +98,7 @@ function executeTypeSafeJoinMany(ctx, joinType, tableOrAlias, callback) {
         };
     };
     conditionBuilder[join_internals_1.JOIN_SETUP](proxyCreator, rightProxy);
-    callback(conditionBuilder, leftProxy, rightProxy);
+    callback(conditionBuilder, rightProxy, leftProxy);
     const lateralSQL = buildLateralSubquery(rightTableName, rightAlias, conditionBuilder, rightTableDef);
     const lateralJoinType = joinType === 'LEFT JOIN' ? 'LEFT JOIN LATERAL' : 'JOIN LATERAL';
     const joinClause = {
@@ -113,12 +118,21 @@ function buildLateralSubquery(tableName, alias, builder, tableDef) {
     const internals = builder[join_internals_1.JOIN_INTERNAL];
     parts.push('SELECT');
     const selectedProps = internals.getSelectedColumns();
+    const innerJoins = internals.getInnerJoins();
+    const hasInnerJoins = innerJoins.length > 0;
+    const toSnake = (s) => s.replace(/[A-Z]/g, l => `_${l.toLowerCase()}`);
     if (selectedProps && selectedProps.length > 0) {
         const tableColumns = tableDef?.$columns || tableDef;
         const selectCols = selectedProps.map(prop => {
             const columnDef = tableColumns?.[prop];
-            const sqlName = columnDef?.$columnName || prop;
-            return `"${alias}"."${sqlName}" AS "${prop}"`;
+            if (columnDef || !hasInnerJoins) {
+                const sqlName = columnDef?.$columnName || toSnake(prop);
+                return `"${alias}"."${sqlName}" AS "${prop}"`;
+            }
+            else {
+                const sqlName = toSnake(prop);
+                return `"${sqlName}" AS "${prop}"`;
+            }
         }).join(', ');
         parts.push(selectCols);
     }
@@ -126,7 +140,6 @@ function buildLateralSubquery(tableName, alias, builder, tableDef) {
         parts.push(`"${alias}".*`);
     }
     parts.push(`FROM "${tableName}" AS "${alias}"`);
-    const innerJoins = internals.getInnerJoins();
     for (const join of innerJoins) {
         parts.push(`${join.type} "${join.table}" AS "${join.alias}" ON ${join.onClause}`);
     }

package/dist/cjs/select/join-condition-builder.cjs

@@ -98,12 +98,12 @@ class JoinConditionBuilder {
         this.whereConditions.push(...collector.getConditions());
         return this;
     }
-    select(columns) {
-        if (columns === '*') {
-            this.selectedColumns = undefined;
+    select(...args) {
+        if (args.length === 1 && Array.isArray(args[0])) {
+            this.selectedColumns = args[0];
         }
         else {
-            this.selectedColumns = columns;
+            this.selectedColumns = args;
         }
         return this;
     }

package/dist/cjs/select/join-many-condition-builder.cjs

@@ -34,28 +34,34 @@ class JoinManyConditionBuilder extends join_condition_builder_1.JoinConditionBui
             this.rightProxy = rightProxy;
         };
     }
-    innerJoin(table, callback) {
+    innerJoin(tableOrAlias, callback) {
         if (!this.proxyCreator) {
             throw new Error('innerJoin requires proxy creator - use raw innerJoinRaw() instead');
         }
-        const { proxy: innerProxy, tableName } = this.proxyCreator(table, table);
+        const [tableKey, alias] = Array.isArray(tableOrAlias)
+            ? tableOrAlias
+            : [tableOrAlias, tableOrAlias];
+        const { proxy: innerProxy, tableName } = this.proxyCreator(tableKey, alias);
         const conditionBuilder = new join_condition_builder_1.JoinConditionBuilder();
         callback(conditionBuilder, innerProxy);
         const internals = conditionBuilder[join_internals_1.JOIN_INTERNAL];
         const onClause = internals.toSQL();
-        this.innerJoins.push({ type: 'JOIN', table: tableName, alias: table, onClause });
+        this.innerJoins.push({ type: 'JOIN', table: tableName, alias, onClause });
         return this;
     }
-    leftInnerJoin(table, callback) {
+    leftInnerJoin(tableOrAlias, callback) {
         if (!this.proxyCreator) {
             throw new Error('leftInnerJoin requires proxy creator - use raw leftInnerJoinRaw() instead');
         }
-        const { proxy: innerProxy, tableName } = this.proxyCreator(table, table);
+        const [tableKey, alias] = Array.isArray(tableOrAlias)
+            ? tableOrAlias
+            : [tableOrAlias, tableOrAlias];
+        const { proxy: innerProxy, tableName } = this.proxyCreator(tableKey, alias);
         const conditionBuilder = new join_condition_builder_1.JoinConditionBuilder();
         callback(conditionBuilder, innerProxy);
         const internals = conditionBuilder[join_internals_1.JOIN_INTERNAL];
         const onClause = internals.toSQL();
-        this.innerJoins.push({ type: 'LEFT JOIN', table: tableName, alias: table, onClause });
+        this.innerJoins.push({ type: 'LEFT JOIN', table: tableName, alias, onClause });
         return this;
     }
     innerJoinRaw(table, alias, onClause) {
@@ -66,12 +72,12 @@ class JoinManyConditionBuilder extends join_condition_builder_1.JoinConditionBui
         this.innerJoins.push({ type: 'LEFT JOIN', table, alias, onClause });
         return this;
     }
-    select(columns) {
-        if (columns === '*') {
-            this.selectedColumns = undefined;
+    select(...args) {
+        if (args.length === 1 && Array.isArray(args[0])) {
+            this.selectedColumns = args[0];
         }
         else {
-            this.selectedColumns = columns;
+            this.selectedColumns = args;
         }
         return this;
     }

package/dist/esm/core/helpers/select-joins.js

@@ -21,7 +21,12 @@ export function executeTypeSafeJoin(ctx, joinType, tableOrAlias, callback) {
     const rightProxy = createTableProxy(rightTableName, rightAlias, rightTableDef);
     const conditionBuilder = new JoinConditionBuilder();
     if (callback) {
-        callback(conditionBuilder, leftProxy, rightProxy);
+        if (joinType === 'RIGHT JOIN') {
+            callback(conditionBuilder, leftProxy, rightProxy);
+        }
+        else {
+            callback(conditionBuilder, rightProxy, leftProxy);
+        }
     }
     const conditionInternals = conditionBuilder[JOIN_INTERNAL];
     if (!conditionInternals.hasConditions() && schema && relations) {
@@ -33,7 +38,7 @@ export function executeTypeSafeJoin(ctx, joinType, tableOrAlias, callback) {
         }
         else {
             throw new RelqQueryError(`Cannot auto-resolve FK relationship between "${ctx.schemaKey || ctx.tableName}" and "${rightTableKey}". ` +
-                `Either provide a callback with explicit join conditions, or define the relationship in your relations config.`, { hint: `Use .join('${rightTableKey}', (on, left, right) => on.equal(left.columnName, right.id))` });
+                `Either provide a callback with explicit join conditions, or define the relationship in your relations config.`, { hint: `Use .join('${rightTableKey}', (on, ${rightTableKey}, source) => on.equal(${rightTableKey}.id, source.columnName))` });
         }
     }
     const selectedProps = conditionInternals.getSelectedColumns();
@@ -89,7 +94,7 @@ export function executeTypeSafeJoinMany(ctx, joinType, tableOrAlias, callback) {
         };
     };
     conditionBuilder[JOIN_SETUP](proxyCreator, rightProxy);
-    callback(conditionBuilder, leftProxy, rightProxy);
+    callback(conditionBuilder, rightProxy, leftProxy);
     const lateralSQL = buildLateralSubquery(rightTableName, rightAlias, conditionBuilder, rightTableDef);
     const lateralJoinType = joinType === 'LEFT JOIN' ? 'LEFT JOIN LATERAL' : 'JOIN LATERAL';
     const joinClause = {
@@ -109,12 +114,21 @@ function buildLateralSubquery(tableName, alias, builder, tableDef) {
     const internals = builder[JOIN_INTERNAL];
     parts.push('SELECT');
     const selectedProps = internals.getSelectedColumns();
+    const innerJoins = internals.getInnerJoins();
+    const hasInnerJoins = innerJoins.length > 0;
+    const toSnake = (s) => s.replace(/[A-Z]/g, l => `_${l.toLowerCase()}`);
     if (selectedProps && selectedProps.length > 0) {
         const tableColumns = tableDef?.$columns || tableDef;
         const selectCols = selectedProps.map(prop => {
             const columnDef = tableColumns?.[prop];
-            const sqlName = columnDef?.$columnName || prop;
-            return `"${alias}"."${sqlName}" AS "${prop}"`;
+            if (columnDef || !hasInnerJoins) {
+                const sqlName = columnDef?.$columnName || toSnake(prop);
+                return `"${alias}"."${sqlName}" AS "${prop}"`;
+            }
+            else {
+                const sqlName = toSnake(prop);
+                return `"${sqlName}" AS "${prop}"`;
+            }
         }).join(', ');
         parts.push(selectCols);
     }
@@ -122,7 +136,6 @@ function buildLateralSubquery(tableName, alias, builder, tableDef) {
         parts.push(`"${alias}".*`);
     }
     parts.push(`FROM "${tableName}" AS "${alias}"`);
-    const innerJoins = internals.getInnerJoins();
     for (const join of innerJoins) {
         parts.push(`${join.type} "${join.table}" AS "${join.alias}" ON ${join.onClause}`);
     }

package/dist/esm/select/join-condition-builder.js

@@ -91,12 +91,12 @@ export class JoinConditionBuilder {
         this.whereConditions.push(...collector.getConditions());
         return this;
     }
-    select(columns) {
-        if (columns === '*') {
-            this.selectedColumns = undefined;
+    select(...args) {
+        if (args.length === 1 && Array.isArray(args[0])) {
+            this.selectedColumns = args[0];
         }
         else {
-            this.selectedColumns = columns;
+            this.selectedColumns = args;
         }
         return this;
     }

package/dist/esm/select/join-many-condition-builder.js

@@ -27,28 +27,34 @@ export class JoinManyConditionBuilder extends JoinConditionBuilder {
             this.rightProxy = rightProxy;
         };
     }
-    innerJoin(table, callback) {
+    innerJoin(tableOrAlias, callback) {
         if (!this.proxyCreator) {
             throw new Error('innerJoin requires proxy creator - use raw innerJoinRaw() instead');
         }
-        const { proxy: innerProxy, tableName } = this.proxyCreator(table, table);
+        const [tableKey, alias] = Array.isArray(tableOrAlias)
+            ? tableOrAlias
+            : [tableOrAlias, tableOrAlias];
+        const { proxy: innerProxy, tableName } = this.proxyCreator(tableKey, alias);
         const conditionBuilder = new JoinConditionBuilder();
         callback(conditionBuilder, innerProxy);
         const internals = conditionBuilder[JOIN_INTERNAL];
         const onClause = internals.toSQL();
-        this.innerJoins.push({ type: 'JOIN', table: tableName, alias: table, onClause });
+        this.innerJoins.push({ type: 'JOIN', table: tableName, alias, onClause });
         return this;
     }
-    leftInnerJoin(table, callback) {
+    leftInnerJoin(tableOrAlias, callback) {
         if (!this.proxyCreator) {
             throw new Error('leftInnerJoin requires proxy creator - use raw leftInnerJoinRaw() instead');
         }
-        const { proxy: innerProxy, tableName } = this.proxyCreator(table, table);
+        const [tableKey, alias] = Array.isArray(tableOrAlias)
+            ? tableOrAlias
+            : [tableOrAlias, tableOrAlias];
+        const { proxy: innerProxy, tableName } = this.proxyCreator(tableKey, alias);
         const conditionBuilder = new JoinConditionBuilder();
         callback(conditionBuilder, innerProxy);
         const internals = conditionBuilder[JOIN_INTERNAL];
         const onClause = internals.toSQL();
-        this.innerJoins.push({ type: 'LEFT JOIN', table: tableName, alias: table, onClause });
+        this.innerJoins.push({ type: 'LEFT JOIN', table: tableName, alias, onClause });
         return this;
     }
     innerJoinRaw(table, alias, onClause) {
@@ -59,12 +65,12 @@ export class JoinManyConditionBuilder extends JoinConditionBuilder {
         this.innerJoins.push({ type: 'LEFT JOIN', table, alias, onClause });
         return this;
     }
-    select(columns) {
-        if (columns === '*') {
-            this.selectedColumns = undefined;
+    select(...args) {
+        if (args.length === 1 && Array.isArray(args[0])) {
+            this.selectedColumns = args[0];
         }
         else {
-            this.selectedColumns = columns;
+            this.selectedColumns = args;
         }
         return this;
     }

package/dist/index.d.ts

@@ -7644,17 +7644,17 @@ declare class JoinConditionBuilder<TLeft = any, TRight = any> {
 	where(callback: (q: TypedConditionBuilder<TRight>) => TypedConditionBuilder<TRight>): this;
 	/**
 	 * Select specific columns from the joined table.
-	 * If not called or called with '*', all columns are selected.
+	 * If not called, all columns are selected.
 	 * The return type narrows TRight to only the selected columns.
 	 *
-	 * @param columns - Array of column names to select, or '*' for all columns
-	 *
 	 * @example
 	 * on.equal(orders.userId, users.id)
-	 *   .select(['id', 'name', 'email'])
-	 * on.select('*')  // Select all (default)
+	 *   .select(['id', 'name', 'email'])   // array syntax
+	 * on.equal(orders.userId, users.id)
+	 *   .select('id', 'name', 'email')     // spread syntax
 	 */
-	select<K extends ColumnKeys<TRight>>(columns: K[] | "*"): JoinConditionBuilder<TLeft, PickColumns<TRight, K>>;
+	select<K extends ColumnKeys<TRight>>(columns: K[]): JoinConditionBuilder<TLeft, PickColumns<TRight, K>>;
+	select<K extends ColumnKeys<TRight>>(...columns: K[]): JoinConditionBuilder<TLeft, PickColumns<TRight, K>>;
 	/** @internal */
 	get [JOIN_INTERNAL](): JoinConditionInternals;
 	/**
@@ -7786,7 +7786,10 @@ declare class JoinManyConditionBuilder<TSchema = any, TLeft = any, TRight = any,
 	 * // JOIN LATERAL (SELECT ... FROM purchases JOIN products ON ... WHERE ...) ...
 	 * ```
 	 */
-	innerJoin<TInnerKey extends Exclude<keyof TSchema & string, TRightKey>>(table: TInnerKey, callback: InnerJoinCallback<TRight, TSchema[TInnerKey]>): this;
+	innerJoin<TInnerKey extends Exclude<keyof TSchema & string, TRightKey>>(tableOrAlias: TInnerKey | [
+		TInnerKey,
+		string
+	], callback: InnerJoinCallback<TRight, TSchema[TInnerKey]>): this;
 	/**
 	 * Add a LEFT JOIN within the LATERAL subquery.
 	 * Autocomplete excludes parent tables already in scope.
@@ -7794,7 +7797,10 @@ declare class JoinManyConditionBuilder<TSchema = any, TLeft = any, TRight = any,
 	 * @param table - Table name (schema key) to join
 	 * @param callback - Join callback receiving (on, innerTable)
 	 */
-	leftInnerJoin<TInnerKey extends Exclude<keyof TSchema & string, TRightKey>>(table: TInnerKey, callback: InnerJoinCallback<TRight, TSchema[TInnerKey]>): this;
+	leftInnerJoin<TInnerKey extends Exclude<keyof TSchema & string, TRightKey>>(tableOrAlias: TInnerKey | [
+		TInnerKey,
+		string
+	], callback: InnerJoinCallback<TRight, TSchema[TInnerKey]>): this;
 	/**
 	 * Add a raw inner JOIN with SQL string (no type safety).
 	 * Use when you don't have schema access.
@@ -7812,9 +7818,12 @@ declare class JoinManyConditionBuilder<TSchema = any, TLeft = any, TRight = any,
 	 * Select specific columns from the joined table.
 	 * The return type narrows TRight to only the selected columns.
 	 *
-	 * @param columns - Array of column names to select, or '*' for all columns
+	 * @example
+	 * on.select(['id', 'name'])   // array syntax
+	 * on.select('id', 'name')     // spread syntax
 	 */
-	select<K extends ColumnKeys<TRight>>(columns: K[] | "*"): JoinManyConditionBuilder<TSchema, TLeft, PickColumns<TRight, K>, TRightKey>;
+	select<K extends ColumnKeys<TRight>>(columns: K[]): JoinManyConditionBuilder<TSchema, TLeft, PickColumns<TRight, K>, TRightKey>;
+	select<K extends ColumnKeys<TRight>>(...columns: K[]): JoinManyConditionBuilder<TSchema, TLeft, PickColumns<TRight, K>, TRightKey>;
 	/** @internal */
 	get [JOIN_INTERNAL](): JoinManyInternals;
 	/**
@@ -8502,45 +8511,63 @@ export type InferResultType<TSchema, TTable, TColumns> = TColumns extends [
 } ? TColumns extends readonly string[] ? Simplify$1<Pick<TSelect, Extract<TColumns[number], keyof TSelect>>> : TSelect : SelectResult<TTable, TColumns extends readonly any[] ? TColumns : [
 ]>;
 /**
- * Join callback function type with positional parameters for better type inference.
- * TResult allows the callback to return a narrowed type (e.g., after .select())
+ * Join callback function type for join/innerJoin/leftJoin.
+ * The joined table proxy comes FIRST for natural DX:
+ * when you write `.join('orders', ...)`, `orders` is what you think about first.
+ *
+ * @param on - The condition builder for ON clause
+ * @param joined - Table proxy for the joined table (the one in .join('tableName'))
+ * @param source - Table proxy for the source table (the one .join() is called on)
+ *
+ * @example
+ * ```typescript
+ * db.table.users.select()
+ *   .join('orders', (on, orders, users) =>
+ *     on.equal(orders.userId, users.id)
+ *       .select(['id', 'total'])
+ *   )
+ * ```
+ */
+export type JoinCallback<TLeft, TRight, TResult = TRight> = (on: JoinConditionBuilder<TLeft, TRight>, joined: TableProxy<TRight>, source: TableProxy<TLeft>) => JoinConditionBuilder<TLeft, TResult>;
+/**
+ * Right join callback — reversed parameter order from JoinCallback.
+ * For rightJoin, the source table comes first since the right (joined) table
+ * is the primary table in a RIGHT JOIN.
  *
  * @param on - The condition builder for ON clause
- * @param left - Table proxy for the left (current) table
- * @param right - Table proxy for the right (joined) table
+ * @param source - Table proxy for the source table
+ * @param joined - Table proxy for the joined (right/primary) table
  *
  * @example
  * ```typescript
- * // Positional params provide better autocomplete and type inference
- * .join('users', (on, orders, users) =>
- *   on.equal(orders.userId, users.id)
- *     .select(['id', 'name'])  // Narrows result to only these columns
- * )
+ * db.table.users.select()
+ *   .rightJoin('orders', (on, users, orders) =>
+ *     on.equal(users.id, orders.userId)
+ *   )
  * ```
  */
-export type JoinCallback<TLeft, TRight, TResult = TRight> = (on: JoinConditionBuilder<TLeft, TRight>, left: TableProxy<TLeft>, right: TableProxy<TRight>) => JoinConditionBuilder<TLeft, TResult>;
+export type RightJoinCallback<TLeft, TRight, TResult = TRight> = (on: JoinConditionBuilder<TLeft, TRight>, source: TableProxy<TLeft>, joined: TableProxy<TRight>) => JoinConditionBuilder<TLeft, TResult>;
 /**
  * JoinMany callback function type for LATERAL subqueries.
- * Provides additional orderBy, limit, offset capabilities.
- * Includes schema for type-safe inner joins with autocomplete.
- * TResult allows the callback to return a narrowed type (e.g., after .select())
+ * Same parameter order as JoinCallback: joined table first, source second.
  *
  * @param on - The condition builder for LATERAL subquery
- * @param left - Table proxy for the left (current/outer) table
- * @param right - Table proxy for the right (joined/inner) table
+ * @param joined - Table proxy for the joined table
+ * @param source - Table proxy for the source (outer) table
  *
  * @example
  * ```typescript
  * // Get top 5 orders per user
- * .joinMany('orders', (on, users, orders) =>
- *   on.equal(users.id, orders.userId)
- *     .where(q => q.equal('status', 'completed'))
- *     .orderBy(orders.createdAt, 'DESC')
- *     .limit(5)
- * )
+ * db.table.users.select()
+ *   .joinMany('orders', (on, orders, users) =>
+ *     on.equal(orders.userId, users.id)
+ *       .where(q => q.equal('status', 'completed'))
+ *       .orderBy(orders.createdAt, 'DESC')
+ *       .limit(5)
+ *   )
  * ```
  */
-export type JoinManyCallback<TSchema, TLeft, TRight, TRightKey extends string, TResult = TRight> = (on: JoinManyConditionBuilder<TSchema, TLeft, TRight, TRightKey>, left: TableProxy<TLeft>, right: TableProxy<TRight>) => JoinManyConditionBuilder<TSchema, TLeft, TResult, TRightKey>;
+export type JoinManyCallback<TSchema, TLeft, TRight, TRightKey extends string, TResult = TRight> = (on: JoinManyConditionBuilder<TSchema, TLeft, TRight, TRightKey>, joined: TableProxy<TRight>, source: TableProxy<TLeft>) => JoinManyConditionBuilder<TSchema, TLeft, TResult, TRightKey>;
 /**
  * Internal interface for query builders
  * This interface exposes execution methods that are hidden from the public API
@@ -8794,16 +8821,16 @@ declare class ConnectedSelectBuilder<TSchema = any, TTable = any, TColumns exten
 	 *   .join('users')  // Auto-detects orders.userId → users.id
 	 * // Result: { ...order, users: { id, name, ... } }
 	 *
-	 * // With explicit callback
+	 * // With explicit callback — joined table first, source second
 	 * db.table.orders.select()
-	 *   .join('users', (on, orders, users) =>
-	 *     on.equal(orders.userId, users.id)
+	 *   .join('users', (on, users, orders) =>
+	 *     on.equal(users.id, orders.userId)
 	 *   )
 	 *
 	 * // With alias
 	 * db.table.orders.select()
-	 *   .join(['users', 'user'], (on, orders, user) =>
-	 *     on.equal(orders.userId, user.id)
+	 *   .join(['users', 'user'], (on, user, orders) =>
+	 *     on.equal(user.id, orders.userId)
 	 *   )
 	 * // Result: { ...order, user: { id, name, ... } }
 	 * ```
@@ -8829,10 +8856,10 @@ declare class ConnectedSelectBuilder<TSchema = any, TTable = any, TColumns exten
 	 *   .leftJoin('users')
 	 * // Result: { ...order, users: { ... } | null }
 	 *
-	 * // With callback
+	 * // With callback — joined table first, source second
 	 * db.table.orders.select()
-	 *   .leftJoin(['users', 'user'], (on, orders, user) =>
-	 *     on.equal(orders.userId, user.id)
+	 *   .leftJoin(['users', 'user'], (on, user, orders) =>
+	 *     on.equal(user.id, orders.userId)
 	 *   )
 	 * ```
 	 */
@@ -8848,12 +8875,15 @@ declare class ConnectedSelectBuilder<TSchema = any, TTable = any, TColumns exten
 	leftJoin<TRightKey extends keyof TSchema & string, TResult>(table: TRightKey, callback: JoinCallback<TTable, TSchema[TRightKey], TResult>): ConnectedSelectBuilder<TSchema, TTable, TColumns, TJoined & NestedLeftJoin<TRightKey, TResult>>;
 	/**
 	 * Type-safe RIGHT JOIN.
+	 * Callback order is (on, source, joined) — reversed from join/leftJoin
+	 * because in a RIGHT JOIN the joined table is the primary table.
 	 *
 	 * @example
 	 * ```typescript
 	 * db.table.orders.select()
-	 *   .rightJoin('users')
-	 * // Result: { ...order, users: { ... } }
+	 *   .rightJoin('users', (on, orders, users) =>
+	 *     on.equal(orders.userId, users.id)
+	 *   )
 	 * ```
 	 */
 	rightJoin<TRightKey extends keyof TSchema & string, TAlias extends string>(tableAndAlias: [
@@ -8864,8 +8894,8 @@ declare class ConnectedSelectBuilder<TSchema = any, TTable = any, TColumns exten
 	rightJoin<TRightKey extends keyof TSchema & string, TAlias extends string>(tableAndAlias: [
 		TRightKey,
 		TAlias
-	], callback: JoinCallback<TTable, TSchema[TRightKey]>): ConnectedSelectBuilder<TSchema, TTable, TColumns, TJoined & NestedJoin<TAlias, TSchema[TRightKey]>>;
-	rightJoin<TRightKey extends keyof TSchema & string>(table: TRightKey, callback: JoinCallback<TTable, TSchema[TRightKey]>): ConnectedSelectBuilder<TSchema, TTable, TColumns, TJoined & NestedJoin<TRightKey, TSchema[TRightKey]>>;
+	], callback: RightJoinCallback<TTable, TSchema[TRightKey]>): ConnectedSelectBuilder<TSchema, TTable, TColumns, TJoined & NestedJoin<TAlias, TSchema[TRightKey]>>;
+	rightJoin<TRightKey extends keyof TSchema & string>(table: TRightKey, callback: RightJoinCallback<TTable, TSchema[TRightKey]>): ConnectedSelectBuilder<TSchema, TTable, TColumns, TJoined & NestedJoin<TRightKey, TSchema[TRightKey]>>;
 	/**
 	 * Type-safe INNER JOIN (alias for join()).
 	 */
@@ -8893,8 +8923,8 @@ declare class ConnectedSelectBuilder<TSchema = any, TTable = any, TColumns exten
 	 * db.table.users.select()
 	 *   .joinSubquery(
 	 *     'recent_orders',
-	 *     db.table.orders.select().join('payments', (on, o, p) =>
-	 *       on.equal(o.id, p.orderId)
+	 *     db.table.orders.select().join('payments', (on, p, o) =>
+	 *       on.equal(p.orderId, o.id)
 	 *     ),
 	 *     `"recent_orders"."user_id" = "users"."id"`
 	 *   )
@@ -8944,15 +8974,15 @@ declare class ConnectedSelectBuilder<TSchema = any, TTable = any, TColumns exten
 	 * | SQLite      | ❌        | Use separate queries |
 	 *
 	 * @param tableOrAlias - Table name or [tableName, alias] tuple
-	 * @param callback - Join condition callback: `(on, left, right) => on.equal(...)`
+	 * @param callback - Join condition callback: `(on, joined, source) => on.equal(...)`
 	 * @throws {RelqConfigError} If dialect doesn't support LATERAL joins
 	 *
 	 * @example
 	 * ```typescript
-	 * // Get top 5 orders per user
+	 * // Get top 5 orders per user — joined table first, source second
 	 * db.table.users.select()
-	 *   .joinMany('orders', (on, users, orders) =>
-	 *     on.equal(users.id, orders.userId)
+	 *   .joinMany('orders', (on, orders, users) =>
+	 *     on.equal(orders.userId, users.id)
 	 *       .where(q => q.equal('status', 'completed'))
 	 *       .orderBy('createdAt', 'DESC')
 	 *       .limit(5)
@@ -8962,8 +8992,8 @@ declare class ConnectedSelectBuilder<TSchema = any, TTable = any, TColumns exten
 	 *
 	 * // With alias
 	 * db.table.users.select()
-	 *   .joinMany(['orders', 'recentOrders'], (on, users, orders) =>
-	 *     on.equal(users.id, orders.userId)
+	 *   .joinMany(['orders', 'recentOrders'], (on, orders, users) =>
+	 *     on.equal(orders.userId, users.id)
 	 *       .orderBy('createdAt', 'DESC')
 	 *       .limit(3)
 	 *   )
@@ -8990,15 +9020,15 @@ declare class ConnectedSelectBuilder<TSchema = any, TTable = any, TColumns exten
 	 * | SQLite      | ❌        | Use separate queries |
 	 *
 	 * @param tableOrAlias - Table name or [tableName, alias] tuple
-	 * @param callback - Join condition callback: `(on, left, right) => on.equal(...)`
+	 * @param callback - Join condition callback: `(on, joined, source) => on.equal(...)`
 	 * @throws {RelqConfigError} If dialect doesn't support LATERAL joins
 	 *
 	 * @example
 	 * ```typescript
 	 * // Get all users with their orders (empty array if no orders)
 	 * db.table.users.select()
-	 *   .leftJoinMany('orders', (on, users, orders) =>
-	 *     on.equal(users.id, orders.userId)
+	 *   .leftJoinMany('orders', (on, orders, users) =>
+	 *     on.equal(orders.userId, users.id)
 	 *       .where(q => q.equal('status', 'completed'))
 	 *   )
 	 *   .all()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "relq",
-  "version": "1.0.86",
+  "version": "1.0.88",
   "description": "The Fully-Typed PostgreSQL ORM for TypeScript",
   "author": "Olajide Mathew O. <olajide.mathew@yuniq.solutions>",
   "license": "MIT",