feat: 0.10.0 (#202)

## Feature 
* feat(collection): added `chunkBy` method 
 
## Fix 
* fix(services)(**BREAKING CHANGE**): updated default `arrayFormat` 
  * previous configuration caused query string structure issues by not specifying array indexes 
* fix(model): removed unnecessary `resetQueryParameters` in `findMany` 
 
## Documentation 
* docs(collection): documented `chunkBy` method 
 
## Chore 
* chore: incremented version 
* chore(deps-dev): locked ts eslint version 
  * Locked while the following resolves: 
  * typescript-eslint/typescript-eslint#4569 
 
## Performance 
* perf(collection): removed redundant construct calls 
 
## Continuous Integration 
* ci: added remote before pushing 
* ci: run build test on PRs going into main too

Author: nandi95

.github/workflows/build.yml

@@ -9,6 +9,7 @@ on:
       - 'src/**/*.ts'
       - 'package-lock.json'
     branches:
+      - main
       - 'release/*'
 
 jobs:

.github/workflows/deploy-api-docs.yml

@@ -30,5 +30,5 @@ jobs:
           git add -f .nojekyll
           git add -f index.html
           git add -f modules.html
-          git commit -m "Updates from ${{ github.ref }}" --no-verify
-          git push -u origin gh-pages
+          git commit -m "Updates from ${{ github.ref }} - {{ github.sha }}" --no-verify
+          git push origin -u gh-pages

docs/helpers/collection.md

@@ -216,6 +216,39 @@ collection.chunk(2); // Collection[Collection[1, 2], Collection[3, 4], Collectio
 collection.chunk(5); // Collection[Collection[1, 2, 3, 4, 5]]
 ```
 
+#### chunkBy
+
+The `chunkBy` method returns an object where the keys are the resolved key values. The method also accepts a callback function which can be used to chunk by deeply nested key values.
+```js
+import { Collection } from '@upfrontjs/framework';
+
+const collection = new Collection([
+    { id: 0, parentId: 5 },
+    { id: 1, parentId: 5 },
+    { id: 2, parentId: 3 },
+    { id: 3, parentId: 3 },
+    { id: 4, parentId: 3 }
+]);
+
+/**
+ * Will result in:
+ * {
+ *     '5': Collection[{ id: 0, parentId: 5 },{ id: 1, parentId: 5 }],
+ *     '3': Collection[{ id: 2, parentId: 3 },{ id: 3, parentId: 3 },{ id: 4, parentId: 3 }],
+ * }
+ */
+collection.chunkBy('parentId');
+
+/**
+ * Will result in:
+ * {
+ *     '5': Collection[{ id: 0, parentId: 5 },{ id: 1, parentId: 5 }],
+ *     '3': Collection[{ id: 2, parentId: 3 },{ id: 3, parentId: 3 },{ id: 4, parentId: 3 }],
+ * }
+ */
+collection.chunkBy(item => item.parentKey);
+```
+
 #### when
 
 The `when` method executes the given method if the first argument evaluates to true. The method has to return the collection.

package-lock.json

@@ -1,6 +1,6 @@
 {
     "name": "@upfrontjs/framework",
-    "version": "0.9.1",
+    "version": "0.10.0",
     "description": "Data handling framework complementary to backend model systems.",
     "main": "index.min.js",
     "module": "index.es.min.js",
@@ -89,8 +89,8 @@
         "@types/qs": "^6.9.5",
         "@types/semantic-release": "^17.2.1",
         "@types/uuid": "^8.3.0",
-        "@typescript-eslint/eslint-plugin": "^5.4.0",
-        "@typescript-eslint/parser": "^5.4.0",
+        "@typescript-eslint/eslint-plugin": "5.11.0",
+        "@typescript-eslint/parser": "5.11.0",
         "commitlint": "^16.0.0",
         "conventional-changelog-conventionalcommits": "4.6.0",
         "eslint": "^8.3.0",

package.json

@@ -316,10 +316,7 @@ export default class Model extends SoftDeletes implements HasFactory {
      * @param {string[]|number[]} ids
      */
     public async findMany<T extends this>(ids: (number | string)[]): Promise<ModelCollection<T>> {
-        let response = await this
-            .resetQueryParameters()
-            .whereKey(ids)
-            .get<T>();
+        let response = await this.whereKey(ids).get<T>();
 
         if (response instanceof Model) {
             response = new ModelCollection([response]);

src/Calliope/Model.ts

@@ -26,7 +26,7 @@ export default class API implements ApiCaller {
      * @see https://www.npmjs.com/package/qs
      */
     protected readonly getParamEncodingOptions: qs.IStringifyOptions = {
-        arrayFormat: 'brackets', // comma does not work currently https://github.com/ljharb/qs/issues/410
+        arrayFormat: 'indices',
         strictNullHandling: true,
         indices: true,
         encodeValuesOnly: true,

src/Services/API.ts

@@ -4,6 +4,7 @@ import type Jsonable from '../Contracts/Jsonable';
 import LogicException from '../Exceptions/LogicException';
 import { isObjectLiteral } from './function';
 import type { MaybeArray } from './type';
+import InvalidOffsetException from '../Exceptions/InvalidOffsetException';
 
 export default class Collection<T> implements Jsonable, Arrayable<T>, Iterable<T>, ArrayLike<T> {
     /**
@@ -296,7 +297,7 @@ export default class Collection<T> implements Jsonable, Arrayable<T>, Iterable<T
     }
 
     /**
-     * Remove all items the are deep equal to the argument.
+     * Remove all items that are deep equal to the argument.
      *
      * @param {any} item
      *
@@ -314,7 +315,7 @@ export default class Collection<T> implements Jsonable, Arrayable<T>, Iterable<T
      * @return {this}
      */
     public nth(every: number): this {
-        return this._newInstance(this.toArray().filter((_item, index) => (index + 1) % every === 0));
+        return this.filter((_item, index) => (index + 1) % every === 0);
     }
 
     /**
@@ -323,7 +324,7 @@ export default class Collection<T> implements Jsonable, Arrayable<T>, Iterable<T
      * @return {this}
      */
     public withoutEmpty(): this {
-        return this._newInstance(this.toArray().filter(item => item !== undefined && item !== null));
+        return this.filter(item => item !== undefined && item !== null);
     }
 
     /**
@@ -415,7 +416,7 @@ export default class Collection<T> implements Jsonable, Arrayable<T>, Iterable<T
             ? values
             : new Collection(Array.isArray(values) ? values : [values]);
 
-        return this._newInstance(this.toArray().filter(item => argCollection.includes(item)));
+        return this.filter(item => argCollection.includes(item));
     }
 
     /**
@@ -435,12 +436,47 @@ export default class Collection<T> implements Jsonable, Arrayable<T>, Iterable<T
                 continue;
             }
 
-            result.push(this._newInstance(this.slice(start, start + size).toArray()));
+            result.push(this.slice(start, start + size));
         }
 
         return new Collection(result);
     }
 
+    /**
+     * Chunk the collection by the specified key.
+     */
+    public chunkBy<K extends keyof T>(key: K | ((item: T) => PropertyKey)): Record<PropertyKey, Collection<T>> {
+        if (!this._allAreObjects()) {
+            throw new TypeError('Every item needs to be an object to be able to access its properties.');
+        }
+
+        const result: Record<PropertyKey, Collection<T>> = {};
+
+        if (typeof key === 'string' || typeof key === 'number' || typeof key === 'symbol') {
+            if (!this.every(obj => key in obj)) {
+                throw new InvalidOffsetException(
+                    '\'' + String(key) + '\' is not present in every item of the collection.'
+                );
+            }
+
+            this.pluck(String(key)).unique().forEach(value => {
+                result[value as PropertyKey] = this.filter(item => item[key] === value);
+            });
+        } else {
+            this.forEach(item => {
+                const propertyKey = key(item);
+
+                if (!result.hasOwnProperty(propertyKey)) {
+                    result[propertyKey] = new Collection();
+                }
+
+                result[propertyKey]!.push(item);
+            });
+        }
+
+        return result;
+    }
+
     /**
      * Call a callback on the collection
      * when the first argument is Boolean(true) or
@@ -535,18 +571,13 @@ export default class Collection<T> implements Jsonable, Arrayable<T>, Iterable<T
             return this;
         }
 
-        const array = this.toArray();
-
         if (count < 0) {
-            return this._newInstance(
-                array
-                    .reverse()
-                    .filter((_item, index) => index + 1 <= Math.abs(count))
-                    .reverse()
-            );
+            return this.reverse()
+                .filter((_item, index) => index + 1 <= Math.abs(count))
+                .reverse();
         }
 
-        return this._newInstance(array.filter((_item, index) => index + 1 <= count));
+        return this.filter((_item, index) => index + 1 <= count);
     }
 
     /**
@@ -600,18 +631,13 @@ export default class Collection<T> implements Jsonable, Arrayable<T>, Iterable<T
             return this._newInstance(this.toArray());
         }
 
-        const array = this.toArray();
-
         if (count < 0) {
-            return this._newInstance(
-                array
-                    .reverse()
-                    .filter((_item, index) => index >= Math.abs(count))
-                    .reverse()
-            );
+            return this.reverse()
+                .filter((_item, index) => index >= Math.abs(count))
+                .reverse();
         }
 
-        return this._newInstance(array.filter((_item, index) => index >= count));
+        return this.filter((_item, index) => index >= count);
     }
 
     /**
@@ -663,23 +689,20 @@ export default class Collection<T> implements Jsonable, Arrayable<T>, Iterable<T
     public pluck<Keys extends Readonly<string[]> | string[]>(properties: Keys): Collection<Record<Keys[number], any>>;
     public pluck(properties: MaybeArray<string>): Collection<any> {
         if (!this._allAreObjects()) {
-            throw new TypeError('Every item needs to be an object to be able to access its properties');
+            throw new TypeError('Every item needs to be an object to be able to access its properties.');
         }
 
         if (Array.isArray(properties)) {
-            return new Collection(
-                this.map((item: Record<string, unknown>) => {
-                    const obj: Record<string, unknown> = {};
+            return this.map((item: Record<string, unknown>) => {
+                const obj: Record<string, unknown> = {};
 
-                    properties.forEach(property => obj[property] = item[property]);
+                properties.forEach(property => obj[property] = item[property]);
 
-                    return obj;
-                })
-                    .toArray()
-            );
+                return obj;
+            });
         }
 
-        return new Collection(this.map((item: Record<string, unknown>) => item[properties]).toArray());
+        return this.map((item: Record<string, unknown>) => item[properties]);
     }
 
     /**
@@ -752,7 +775,7 @@ export default class Collection<T> implements Jsonable, Arrayable<T>, Iterable<T
     }
 
     /**
-     * Get the summative of the collection values.
+     * Get summative of the collection values.
      *
      * @param {string|function} key
      */

src/Support/Collection.ts

@@ -316,8 +316,8 @@ describe('CallsApi', () => {
                     newKey: 'new value'
                 });
                 expect(getLastRequest()!.url).toBe(
-                    finish(config.get('baseEndPoint')!, '/') + caller.getEndpoint()
-                    + '?wheres[][column]=id&wheres[][operator]=%3D&wheres[][value]=1&wheres[][boolean]=and&key=value'
+                    finish(config.get('baseEndPoint')!, '/') + caller.getEndpoint() +
+                    '?wheres[0][column]=id&wheres[0][operator]=%3D&wheres[0][value]=1&wheres[0][boolean]=and&key=value'
                 );
 
                 config.unset('requestMiddleware');
@@ -560,7 +560,7 @@ describe('CallsApi', () => {
 
             expect(getLastRequest()?.url)
                 .toBe(`${config.get('baseEndPoint')!}/${caller.getEndpoint()}`
-                    + '?wheres[][column]=id&wheres[][operator]=%3D&wheres[][value]=2&wheres[][boolean]=and');
+                    + '?wheres[0][column]=id&wheres[0][operator]=%3D&wheres[0][value]=2&wheres[0][boolean]=and');
         });
 
         it('should send query parameters in the request', async () => {
@@ -570,7 +570,7 @@ describe('CallsApi', () => {
             expect(getLastRequest()?.url).toBe(
                 String(config.get('baseEndPoint')) + '/'
                 + caller.getEndpoint()
-                + '?wheres[][column]=id&wheres[][operator]=%3D&wheres[][value]=43&wheres[][boolean]=and'
+                + '?wheres[0][column]=id&wheres[0][operator]=%3D&wheres[0][value]=43&wheres[0][boolean]=and'
             );
         });
 
@@ -642,7 +642,7 @@ describe('CallsApi', () => {
             expect(getLastRequest()?.body).toStrictEqual({ key: 'value' });
             expect(getLastRequest()?.url).toBe(
                 `${config.get('baseEndPoint')!}/${caller.getEndpoint()}`
-                + '?wheres[][column]=id&wheres[][operator]=%3D&wheres[][value]=43&wheres[][boolean]=and'
+                + '?wheres[0][column]=id&wheres[0][operator]=%3D&wheres[0][value]=43&wheres[0][boolean]=and'
             );
         });
     });
@@ -683,7 +683,7 @@ describe('CallsApi', () => {
             expect(getLastRequest()?.body).toStrictEqual({ key: 'value' });
             expect(getLastRequest()?.url).toBe(
                 `${config.get('baseEndPoint')!}/${caller.getEndpoint()}`
-                + '?wheres[][column]=id&wheres[][operator]=%3D&wheres[][value]=43&wheres[][boolean]=and'
+                + '?wheres[0][column]=id&wheres[0][operator]=%3D&wheres[0][value]=43&wheres[0][boolean]=and'
             );
         });
     });
@@ -724,7 +724,7 @@ describe('CallsApi', () => {
             expect(getLastRequest()?.body).toStrictEqual({ key: 'value' });
             expect(getLastRequest()?.url).toBe(
                 `${config.get('baseEndPoint')!}/${caller.getEndpoint()}`
-                + '?wheres[][column]=id&wheres[][operator]=%3D&wheres[][value]=43&wheres[][boolean]=and'
+                + '?wheres[0][column]=id&wheres[0][operator]=%3D&wheres[0][value]=43&wheres[0][boolean]=and'
             );
         });
     });
@@ -773,7 +773,7 @@ describe('CallsApi', () => {
 
             expect(getLastRequest()?.url).toBe(
                 `${config.get('baseEndPoint')!}/${caller.getEndpoint()}`
-                + '?wheres[][column]=id&wheres[][operator]=%3D&wheres[][value]=43&wheres[][boolean]=and'
+                + '?wheres[0][column]=id&wheres[0][operator]=%3D&wheres[0][value]=43&wheres[0][boolean]=and'
             );
         });
     });

tests/Calliope/Concerns/CallsApi.test.ts

@@ -332,7 +332,7 @@ describe('HasRelations', () => {
                     String(config.get('baseEndPoint'))
                     + '/' + String(hasRelations.getEndpoint())
                     + '/' + String(hasRelations.getKey())
-                    + '?' + 'with[]=file&with[]=files'
+                    + '?' + 'with[0]=file&with[1]=files'
                 );
             }
         );

tests/Calliope/Concerns/HasRelations.test.ts

@@ -129,8 +129,8 @@ describe('HasTimestamps', () => {
             expect(getLastRequest()?.url).toBe(
                 String(config.get('baseEndPoint'))
                 + finish(start(hasTimestamps.getEndpoint(), '/'), '/' + String(hasTimestamps.getKey()))
-                + '?wheres[][column]=id&wheres[][operator]=%3D&wheres[][value]=1&wheres[][boolean]=and'
-                + '&columns[]=createdAt&columns[]=updatedAt'
+                + '?wheres[0][column]=id&wheres[0][operator]=%3D&wheres[0][value]=1&wheres[0][boolean]=and'
+                + '&columns[0]=createdAt&columns[1]=updatedAt'
             );
         });