relq 1.0.86 → 1.0.87

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 = {

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 = {

package/dist/index.d.ts

@@ -8502,45 +8502,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 left - Table proxy for the left (current) table
- * @param right - Table proxy for the right (joined) table
+ * @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
- * // 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()
+ *   .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>, left: TableProxy<TLeft>, right: TableProxy<TRight>) => JoinConditionBuilder<TLeft, TResult>;
+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 source - Table proxy for the source table
+ * @param joined - Table proxy for the joined (right/primary) table
+ *
+ * @example
+ * ```typescript
+ * db.table.users.select()
+ *   .rightJoin('orders', (on, users, orders) =>
+ *     on.equal(users.id, orders.userId)
+ *   )
+ * ```
+ */
+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 +8812,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 +8847,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 +8866,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 +8885,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 +8914,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 +8965,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 +8983,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 +9011,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.87",
   "description": "The Fully-Typed PostgreSQL ORM for TypeScript",
   "author": "Olajide Mathew O. <olajide.mathew@yuniq.solutions>",
   "license": "MIT",