Enhanced Data Retrieval: Implement Join Conditions

.github/workflows/main.yml

@@ -29,7 +29,7 @@ jobs:
 
       # Runs a single command using the runners shell
       - name: build docker db
-        run: docker-compose up -d
+        run: docker compose up -d
 
       - name: install
         run: yarn install
@@ -38,7 +38,7 @@ jobs:
         run: yarn build
 
       - name: check docker
-        run: docker-compose up -d
+        run: docker compose up -d
 
       # Runs a set of commands using the runners shell
       - name: tests

docs/requests.md

@@ -218,6 +218,23 @@ _Examples:_
 
 **_Notice:_** primary field/column always persists in relational objects. To use nested relations, the parent level **MUST** be set before the child level like example above.
 
+### New Feature: Join Condition (on clause)
+
+The join parameter now supports specifying a WHERE condition within the ON clause of the join using the on property. This allows for more granular control over the joined data.
+
+> ?join=**relation**||**field1**,**field2**,...||on[0]=**field**||**\$condition**||**value**,on[1]=**field**||**\$condition**...&join=...
+
+_Examples:_
+
+Suppose you want to retrieve `Posts` along with their associated `Author` data, but you only want to include `Authors` where the `isActive` field is `true` and the `profilePicture` field is `null` (meaning the author doesn't have a profile picture set). You can achieve this with the following query string:
+
+> ?join=**author**||**fullName**,**email**||on[0]=**author.isActive**||**\$eq**||**true**&on[1]=**author.profilePicture**||**\$isnull**
+
+This query will join the `Post` entity with its related `Author` entity, but it will only include `Author` objects where:
+
+- The `isActive` field is set to `true`.
+- The `profilePicture` field is `null`.
+
 ### limit
 
 Receive `N` amount of entities.
@@ -330,10 +347,18 @@ qb.setFilter({ field: "foo", operator: CondOperator.NOT_NULL })
     value: "test"
   });
 
-qb.select(["foo", "bar"])
-  .setJoin({ field: "company" })
-  .setJoin({ field: "profile", select: ["name", "email"] })
-  .sortBy({ field: "bar", order: "DECS" })
+qb.select(['foo', 'bar'])
+  .setJoin({ field: 'company' })
+  .setJoin({ field: 'profile', select: ['name', 'email'] })
+  .setJoin({
+    field: 'boo',
+    select: ['status', 'date'],
+    on: [
+      { field: 'bar', operator: 'eq', value: 100 },
+      { field: 'baz', operator: 'isnull' },
+    ],
+  })
+  .sortBy({ field: 'bar', order: 'DECS' })
   .setLimit(20)
   .setPage(3)
   .resetCache()

packages/crud-request/src/request-query.builder.ts

@@ -6,7 +6,7 @@ import {
   isString,
   isUndefined,
 } from '@dataui/crud-util';
-import { stringify } from 'qs';
+import { IStringifyOptions, stringify } from 'qs';
 
 import {
   CreateQueryParams,
@@ -58,6 +58,11 @@ export class RequestQueryBuilder {
   private paramNames: {
     [key in keyof RequestQueryBuilderOptions['paramNamesMap']]: string;
   } = {};
+  private joinConditionString: IStringifyOptions = {
+    encode: false,
+    delimiter: this.options.delimStr,
+    arrayFormat: 'indices',
+  };
   public queryObject: { [key: string]: any } = {};
   public queryString: string;
 
@@ -203,13 +208,28 @@ export class RequestQueryBuilder {
     );
   }
 
-  private addJoin(j: QueryJoin | QueryJoinArr): string {
-    const join = Array.isArray(j) ? { field: j[0], select: j[1] } : j;
-    validateJoin(join);
-    const d = this.options.delim;
-    const ds = this.options.delimStr;
+  private addJoin(join: QueryJoin | QueryJoinArr): string {
+    const { delim, delimStr } = this.options;
+
+    const normalizedJoin = Array.isArray(join)
+      ? { field: join[0], select: join[1], on: join[2] }
+      : join;
+
+    validateJoin(normalizedJoin);
+
+    const conditions = isArrayFull(normalizedJoin.on)
+      ? { on: normalizedJoin.on.map((condition) => this.cond(condition, 'filter')) }
+      : '';
+
+    const fieldPart = normalizedJoin.field;
+    const selectPart = isArrayFull(normalizedJoin.select)
+      ? delim + normalizedJoin.select.join(delimStr)
+      : '';
+    const conditionsPart = conditions
+      ? delim + stringify(conditions, this.joinConditionString)
+      : '';
 
-    return join.field + (isArrayFull(join.select) ? d + join.select.join(ds) : '');
+    return fieldPart + selectPart + conditionsPart;
   }
 
   private addSortBy(s: QuerySort | QuerySortArr): string {

packages/crud-request/src/request-query.parser.ts

@@ -40,6 +40,7 @@ import {
   SConditionAND,
   SFields,
 } from './types';
+import { IParseOptions, parse } from 'qs';
 
 // tslint:disable:variable-name ban-types
 export class RequestQueryParser implements ParsedRequestParams {
@@ -66,6 +67,10 @@ export class RequestQueryParser implements ParsedRequestParams {
   private _paramNames: string[];
   private _paramsOptions: ParamsOptions;
 
+  private _joinConditionParseOptions: IParseOptions = {
+    delimiter: this._options.delimStr,
+  };
+
   private get _options(): RequestQueryBuilderOptions {
     return RequestQueryBuilder.getOptions();
   }
@@ -350,12 +355,25 @@ export class RequestQueryParser implements ParsedRequestParams {
     return condition;
   }
 
+  private parseJoinConditions(conditionsString: string): QueryFilter[] {
+    const conditions: string[] = parse(conditionsString, this._joinConditionParseOptions)[
+      'on'
+    ];
+    return conditions.map((cond: string) => this.conditionParser('filter', {}, cond));
+  }
+
   private joinParser(data: string): QueryJoin {
     const param = data.split(this._options.delim);
+    const field = param[0];
+    const selectString = param[1];
+    const conditions = param.slice(2).join(this._options.delim);
+
     const join: QueryJoin = {
-      field: param[0],
-      select: isStringFull(param[1]) ? param[1].split(this._options.delimStr) : undefined,
+      field,
+      select: selectString ? selectString.split(this._options.delimStr) : undefined,
+      on: isStringFull(conditions) ? this.parseJoinConditions(conditions) : undefined,
     };
+
     validateJoin(join);
 
     return join;

packages/crud-request/src/request-query.validator.ts

@@ -1,4 +1,5 @@
 import {
+  isArrayFull,
   isArrayStrings,
   isEqual,
   isNil,
@@ -89,6 +90,9 @@ export function validateJoin(join: QueryJoin): void {
   if (!isUndefined(join.select) && !isArrayStrings(join.select)) {
     throw new RequestQueryException('Invalid join select. Array of strings expected');
   }
+  if (!isUndefined(join.on) && !isArrayFull(join.on)) {
+    join.on.map((condition) => validateCondition(condition, 'filter', {}));
+  }
 }
 
 export function validateSort(sort: QuerySort): void {

packages/crud-request/src/types/request-query.types.ts

@@ -11,9 +11,10 @@ export type QueryFilterArr = [string, ComparisonOperator, any?];
 export interface QueryJoin {
   field: string;
   select?: QueryFields;
+  on?: QueryFilter[];
 }
 
-export type QueryJoinArr = [string, QueryFields?];
+export type QueryJoinArr = [string, QueryFields?, QueryFilter[]?];
 
 export interface QuerySort {
   field: string;

packages/crud-request/test/request-query.builder.spec.ts

@@ -93,7 +93,10 @@ describe('#request-query', () => {
         expect(qb.queryObject.filter).toIncludeSameMembers(expected);
       });
       it('should set filter, 4', () => {
-        qb.setFilter([['foo', 'eq', 'bar'], ['baz', 'ne', 'zoo']]);
+        qb.setFilter([
+          ['foo', 'eq', 'bar'],
+          ['baz', 'ne', 'zoo'],
+        ]);
         const expected = ['foo||eq||bar', 'baz||ne||zoo'];
         expect(qb.queryObject.filter).toIncludeSameMembers(expected);
       });
@@ -155,6 +158,15 @@ describe('#request-query', () => {
       it('should throw an error, 3', () => {
         expect((qb.setJoin as any).bind(qb, [{}])).toThrowError(RequestQueryException);
       });
+      it('should throw an error, 4', () => {
+        expect(
+          (qb.setJoin as any).bind(qb, {
+            field: 'bar',
+            select: ['a', 'b', 'c'],
+            on: [{}],
+          }),
+        ).toThrowError(RequestQueryException);
+      });
       it('should set join, 1', () => {
         qb.setJoin({ field: 'foo' });
         const expected = ['foo'];
@@ -180,6 +192,40 @@ describe('#request-query', () => {
         const expected = ['baz', 'foo||a,b,c'];
         expect(qb.queryObject.join).toIncludeSameMembers(expected);
       });
+      it('should set join, 6', () => {
+        qb.setJoin([
+          ['baz'],
+          ['foo', ['a', 'b', 'c']],
+          ['boo', ['a', 'b', 'c'], [{ field: 'bar', operator: 'eq', value: 100 }]],
+        ]);
+        const expected = ['baz', 'foo||a,b,c', 'boo||a,b,c||on[0]=bar||eq||100'];
+        expect(qb.queryObject.join).toIncludeSameMembers(expected);
+      });
+      it('should set join, 7', () => {
+        qb.setJoin([
+          {
+            field: 'baz',
+            select: ['a', 'b', 'c'],
+            on: [{ field: 'bar', operator: 'eq', value: 100 }],
+          },
+        ]);
+        const expected = ['baz||a,b,c||on[0]=bar||eq||100'];
+        expect(qb.queryObject.join).toIncludeSameMembers(expected);
+      });
+      it('should set join, 8', () => {
+        qb.setJoin([
+          {
+            field: 'baz',
+            select: ['a', 'b', 'c'],
+            on: [
+              { field: 'bar', operator: 'eq', value: 100 },
+              { field: 'foo', operator: 'isnull' },
+            ],
+          },
+        ]);
+        const expected = ['baz||a,b,c||on[0]=bar||eq||100,on[1]=foo||isnull'];
+        expect(qb.queryObject.join).toIncludeSameMembers(expected);
+      });
     });
 
     describe('#sortBy', () => {
@@ -206,7 +252,10 @@ describe('#request-query', () => {
         expect(qb.queryObject.sort).toIncludeSameMembers(expected);
       });
       it('should set sort, 2', () => {
-        qb.sortBy([{ field: 'foo', order: 'ASC' }, { field: 'bar', order: 'DESC' }]);
+        qb.sortBy([
+          { field: 'foo', order: 'ASC' },
+          { field: 'bar', order: 'DESC' },
+        ]);
         const expected = ['foo,ASC', 'bar,DESC'];
         expect(qb.queryObject.sort).toIncludeSameMembers(expected);
       });
@@ -329,7 +378,14 @@ describe('#request-query', () => {
           .select(['foo', 'bar'])
           .setFilter(['is', 'notnull'])
           .setOr({ field: 'ok', operator: 'ne', value: false })
-          .setJoin({ field: 'voo', select: ['h', 'data'] })
+          .setJoin({
+            field: 'voo',
+            select: ['h', 'data'],
+            on: [
+              { field: 'foo', operator: 'eq', value: 'baz' },
+              { field: 'bar', operator: 'isnull' },
+            ],
+          })
           .setLimit(1)
           .setOffset(2)
           .setPage(3)
@@ -338,7 +394,7 @@ describe('#request-query', () => {
           .setIncludeDeleted(1)
           .query(false);
         const expected =
-          'fields=foo,bar&filter[0]=is||notnull&or[0]=ok||ne||false&join[0]=voo||h,data&limit=1&offset=2&page=3&sort[0]=foo,DESC&cache=0&include_deleted=1';
+          'fields=foo,bar&filter[0]=is||notnull&or[0]=ok||ne||false&join[0]=voo||h,data||on[0]=foo||eq||baz,on[1]=bar||isnull&limit=1&offset=2&page=3&sort[0]=foo,DESC&cache=0&include_deleted=1';
         expect(test).toBe(expected);
       });
     });
@@ -375,15 +431,22 @@ describe('#request-query', () => {
           fields: ['foo', 'bar'],
           filter: ['is', 'notnull'],
           or: { field: 'ok', operator: 'ne', value: false },
-          join: { field: 'voo', select: ['h', 'data'] },
+          join: {
+            field: 'voo',
+            select: ['h', 'data'],
+            on: [
+              { field: 'foo', operator: 'eq', value: 'baz' },
+              { field: 'bar', operator: 'isnull' },
+            ],
+          },
           limit: 1,
           offset: 2,
           page: 3,
           sort: [['foo', 'DESC']],
           resetCache: true,
         }).query(false);
         const expected =
-          'fields=foo,bar&filter[0]=is||notnull&or[0]=ok||ne||false&join[0]=voo||h,data&limit=1&offset=2&page=3&sort[0]=foo,DESC&cache=0';
+          'fields=foo,bar&filter[0]=is||notnull&or[0]=ok||ne||false&join[0]=voo||h,data||on[0]=foo||eq||baz,on[1]=bar||isnull&limit=1&offset=2&page=3&sort[0]=foo,DESC&cache=0';
         expect(test).toBe(expected);
       });
       it('should return a valid query string, 2', () => {

packages/crud-request/test/request-query.parser.spec.ts

@@ -259,6 +259,32 @@ describe('#request-query', () => {
           expect(test.join[0]).toMatchObject(expected[0]);
           expect(test.join[1]).toMatchObject(expected[1]);
         });
+        it('should set array, 3', () => {
+          const query = {
+            join: [
+              'foo',
+              'bar||baz,boo',
+              'bar||baz,boo||on[0]=name||eq||jhon,on[1]=foo||isnull',
+            ],
+          };
+          const expected: QueryJoin[] = [
+            { field: 'foo' },
+            { field: 'bar', select: ['baz', 'boo'] },
+            {
+              field: 'bar',
+              select: ['baz', 'boo'],
+              on: [
+                { field: 'name', operator: 'eq', value: 'jhon' },
+                { field: 'foo', operator: 'isnull', value: '' },
+              ],
+            },
+          ];
+          const test = qp.parseQuery(query);
+
+          expect(test.join[0]).toMatchObject(expected[0]);
+          expect(test.join[1]).toMatchObject(expected[1]);
+          expect(test.join[2]).toMatchObject(expected[2]);
+        });
       });
 
       describe('#parse sort', () => {