Merge branch 'main' into release/0.x

Author: nandi95

.commitlintrc.js

@@ -18,6 +18,7 @@ module.exports = {
                 'collection',
                 'model',
                 'model-collection',
+                'ancestry-collection',
                 'paginator',
                 'factory',
                 'query-builder',

.github/semantic.yml

@@ -22,6 +22,7 @@ scopes:
   - 'collection'
   - 'model'
   - 'model-collection'
+  - 'ancestry-collection'
   - 'paginator'
   - 'factory'
   - 'query-builder'

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

@@ -38,4 +38,5 @@ jobs:
           git commit -m "Updates from ${{ github.ref }} - {{ github.sha }}" --no-verify
           git fetch
           git switch gh-pages
-          git push gh-pages
+          git merge origin/main
+          git push

docs/.vuepress/links.ts

@@ -28,7 +28,8 @@ const sidebar: SidebarConfig = [
             '/calliope/query-building',
             '/calliope/relationships',
             '/calliope/timestamps',
-            '/calliope/model-collection'
+            '/calliope/model-collection',
+            '/calliope/ancestry-collection'
         ]
     },
     {

docs/calliope/ancestry-collection.md

@@ -0,0 +1,78 @@
+# Ancestry Collection
+
+Sometimes you may encounter data structures that are meant to be sorted based on their relation to each other. For example messages and their replies, folders and their sub folders, tasks and their subtasks, etc... However, sometimes the data sources might not return the data in an easily digestible structured format but as a flat array.
+
+For these occasions you may use the AncestryCollection. The AncestryCollection is a subclass of the [ModelCollection](./model-collection.md), therefore all methods are inherited. Keep in mind that inherited methods will be operating on the top level items as one might expect.
+
+## Properties
+
+#### depthName
+<Badge text="static" type="warning"/>
+
+This string determines the name of the attribute that is set on the models when constructing the collection using the [treeOf](#treeof) method.
+
+## Methods
+
+[[toc]]
+
+#### treeOf
+<Badge text="static" type="warning"/>
+
+The `treeOf` static method creates the AncestryCollection from the given [ModelCollection](./model-collection.md). This arranges the models to as the child of their respective models. Optionally the method takes 2 more arguments:
+- `parentKey` (default: `'parentId'`) -  the name of the attribute that contains the parent's identifier.
+- `childrenRelation` (default: `'children'`): - the name of the relation the child models are nested under.
+
+This will also assign the [depth](#depthname) value to the model based on its position on the tree.
+```js
+import { AncestryCollection } from '@upfrontjs/framework';
+import Folder from '~/Models/Folder';
+
+const folders = await Folder.get();
+const folderTree = AncestryCollection.treeOf(folders);
+```
+
+#### flatten
+
+The `flatten` method deconstructs the tree to a flat [ModelCollection](./model-collection.md).
+
+```js
+import { AncestryCollection } from '@upfrontjs/framework';
+import Folder from '~/Models/Folder';
+
+const folders = await Folder.get();
+const folderTree = AncestryCollection.treeOf(folders);
+
+folderTree.flatten(); // ModelCollection
+```
+
+#### leaves
+
+The `leaves` method returns a [ModelCollection](./model-collection.md) containing all the models that does not have any children. With the analogy of a tree, it will not include roots, branches, only the models at the end of the bloodline.
+
+```js
+import { AncestryCollection } from '@upfrontjs/framework';
+import Folder from '~/Models/Folder';
+
+const folders = await Folder.get();
+const folderTree = AncestryCollection.treeOf(folders);
+
+folderTree.leaves(); // ModelCollection
+```
+
+#### isAncestryCollection
+<Badge text="static" type="warning"/>
+
+The `isAncestryCollection` static method same as the [isModelCollection](./model-collection.md#ismodelcollection) method on the ModelCollection, is used to evaluate that the given value is an AncestryCollection.
+```js
+import { AncestryCollection, ModelCollection, Collection } from '@upfrontjs/framework';
+import Folder from '~/Models/Folder';
+
+const modelCollection = await Folder.get();
+const folderTree = AncestryCollection.treeOf(modelCollection);
+
+AncestryCollection.isAncestryCollection(modelCollection); // false
+AncestryCollection.isAncestryCollection(folderTree); // true
+
+ModelCollection.isModelCollection(folderTree); // true
+Collection.isCollection(folderTree); // true
+```

docs/calliope/attributes.md

@@ -14,7 +14,9 @@ Casting transforms values when accessing or setting attributes on a model.
 To define the casters on your model you should define a getter for the `casts` property.
 
 <CodeGroup>
+
 <CodeGroupItem title="Javascript">
+
 ```js
 // User.js
 import { Model } from '@upfrontjs/framework';
@@ -27,9 +29,11 @@ export default class User extends Model {
     }
 }
 ```
+
 </CodeGroupItem>
 
 <CodeGroupItem title="Typescript">
+
 ```ts
 // User.ts
 import { Model } from '@upfrontjs/framework';
@@ -44,7 +48,9 @@ export default class User extends Model {
     }
 }
 ```
+
 </CodeGroupItem>
+
 </CodeGroup>
 
 **The following cast types are available:**
@@ -66,14 +72,17 @@ Casts the values to a [Collection](../helpers/collection.md) by calling the coll
 
 #### `'datetime'`
 
-Cast the values to the [given date time](../helpers/global-config.md#datetime) by calling the method or its constructor. If no date time defined in the config by default it will construct  a new [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object with the value.
+Cast the values to the [given date time](../helpers/global-config.md#datetime) by calling the method or its constructor.
+Default: If no date time defined in the config by default it will construct a new [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object with the value. This when receives a `null` value it will return `null` instead of a `Date` set to unix epoch.
 
 #### custom object
 
 This is an object which implements the `AttributeCaster` type. Meaning it has a `get` and a `set` method both of which accepts a value, and an `Attributes` object (the equivalent of [getRawAttributes](#getrawattributes)) argument.
 
 <CodeGroup>
+
 <CodeGroupItem title="Javascript">
+
 ```js
 // User.js
 import { Model } from '@upfrontjs/framework';
@@ -96,6 +105,7 @@ export default class User extends Model {
 </CodeGroupItem>
 
 <CodeGroupItem title="Typescript">
+
 ```ts
 // User.ts
 import { Model } from '@upfrontjs/framework';
@@ -116,7 +126,9 @@ export default class User extends Model {
     }
 }
 ```
+
 </CodeGroupItem>
+
 </CodeGroup>
 
 ### Further casting methods

docs/calliope/model-collection.md

@@ -4,6 +4,8 @@ ModelCollection is a subclass of the [Collection](../helpers/collection.md), the
 
 ## Methods
 
+[[toc]]
+
 #### modelKeys
 
 The `modelKeys` method returns the [primary key](./readme.md#getkey) of the models on a Collection.
@@ -29,6 +31,7 @@ modelCollection.findByKey(43, defaultModel); // Model
 ```
 
 #### isModelCollection
+<Badge text="static" type="warning"/>
 
 The `isModelCollection` static method same as the [isCollection](../helpers/collection.md#iscollection) method on the collection, is used to evaluate that the given value is a ModelCollection.
 ```js

docs/cookbook.md

@@ -13,6 +13,7 @@ In the documentation simple and concise examples are favoured to avoid too much
 - [Sending requests without models](#sending-requests-without-models)
 - [Alias methods](#alias-methods)
 - [Extend query builder functionality](#extend-query-builder-functionality)
+- [Using it with automated query builder packages](#using-it-with-automated-query-builder-packages)
 - [Send paginated requests](#send-paginated-requests)
 
 #### Extend the collections to fit your needs.
@@ -46,7 +47,7 @@ const users = await User.latest()
     .get()
     .then(users => new UserCollection(users.toArray()));
 
-if (users.areAwake().length === modelCollection.length) {
+if (users.areAwake().length === users.length) {
     await users.markAsReady();
 } else {
     console.log('Oh no, somebody\'s not ready yet!');
@@ -184,19 +185,21 @@ Extending/overwriting the model should not be a daunting task. If we wanted we c
 import type { FormatsQueryParameters, QueryParams, StaticToThis } from '@upfrontjs/framework';
 import { Model as BaseModel } from '@upfrontjs/framework';
 
+type Appendage = string;
+
 export default class Model extends BaseModel implements FormatsQueryParameters {
     protected appends: string[] = [];
 
-    public append(name: string): this {
+    public append(name: Appendage): this {
         this.appends.push(name);
         return this;
     }
 
-    public static append<T extends StaticToThis<Model>>(this: T, name: string): T['prototype'] {
+    public static append<T extends StaticToThis<Model>>(this: T, name: Appendage): T['prototype'] {
         this.newQuery().append(name);
     }
 
-    public withoutAppend(name: string): this {
+    public withoutAppend(name: Appendage): this {
         this.appends = this.appends.filter(appended => appended !== name);
         return this;
     }
@@ -218,6 +221,85 @@ export default class Model extends BaseModel implements FormatsQueryParameters {
 
 Now if our other models extend our own model they will have the option to set the `appends` field on the outgoing requests.
 
+#### Using it with automated query builder packages
+
+For even more convenience the package can be adjusted to be used with some sort of automated query parsing code on the backend.
+Closely similar to [query builder extending](#extend-query-builder-functionality) you may create a more generalised approach to allow setting such query params.
+
+```ts
+import type { AttributeKeys, FormatsQueryParameters, StaticToThis, QueryParams } from '@upfrontjs/framework';
+import { Model as BaseModel } from '@upfrontjs/framework';
+
+// example query parameters the back-end might be looking for.
+interface RequestParameters extends Record<string, unknown> {
+    /**
+     * Append these values if set.
+     */
+    append?: string[];
+    /**
+     * Return with these relations if set.
+     */
+    include?: (string | `${string}Count`)[];
+    /**
+     * Return only these fields if set.
+     */
+    fields?: string[];
+    /**
+     * Only return records where these filters return true when this is set.
+     */
+    filter?: Record<string, string>;
+    /**
+     * Sort by this property if set.
+     */
+    sort?: string;
+}
+
+export default class Model extends BaseModel implements FormatsQueryParameters {
+    /**
+     * The parameters that should be sent along in the next request.
+     *
+     * @protected
+     */
+    protected requestParameters: RequestParameters = {};
+
+    /**
+     * Set url parameters for the next request.
+     */
+    public withParameter(params: RequestParameters): this {
+        this.requestParameters = Object.assign(this.requestParameters, params);
+
+        return this;
+    }
+
+    /**
+     * Static version of the withParameter method.
+     *
+     * @param {RequestParameters} params
+     */
+    public static withParameters<T extends StaticToThis<Model>>(this: T, params: RequestParameters): T['prototype'] {
+        return new this().withParameter(params);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public resetQueryParameters(): this {
+        this.requestParameters = {};
+
+        return super.resetQueryParameters();
+    }
+
+    /**
+     * @inheritDoc
+     *
+     * @protected
+     */
+    public formatQueryParameters(parameters: QueryParams & Record<string, any>): Record<string, any> {
+        return Object.assign(parameters, this.requestParameters);
+    }
+}
+```
+
 #### Send paginated requests
 
 While it's nice to be able to [paginate locally](./helpers/pagination.md) it might not be desired to get too much data upfront. In this case a pagination can be implemented that will only get the pages in question on an explicit request. Of course, you might change the typings and the implementation to fit your needs.

docs/getting-started/installation.md

@@ -1,17 +1,23 @@
 # Installation
 
 <CodeGroup>
+
 <CodeGroupItem title="npm">
+
 ```shell
 npm install @upfrontjs/framework
 ```
+
 </CodeGroupItem>
 
 <CodeGroupItem title="yarn">
+
 ```shell
 yarn install @upfrontjs/framework
 ```
+
 </CodeGroupItem>
+
 </CodeGroup>
 
 The library is transpiled to ES6 (currently the lowest supported version), but if you're using [Typescript](https://www.typescriptlang.org/), you could choose to use the source `.ts` files. To do so, import files from `/src` folder as opposed to the library root.

docs/getting-started/readme.md

@@ -14,12 +14,11 @@ const excellentStudentNames = students
 ```
 
 ## What does it solve?
-There are number of solutions out there for fetching data and working with the response. However not all of these might be as scalable as one would hope. With state management, you might have a getter for users, but those users include all users, meaning for a custom collection you would need a new getter method. An on-demand ajax request written specifically to solve a single issue, while it is simple to do, it quickly gets repetitive and hard to maintain. [Upfront](./installation.md) solves the above by creating abstraction over the data in a unified api. Just like the above examples it can be used to fetch data on demand or be complimentary to state management libraries.
+There are number of solutions out there for fetching data and working with the response. However not all of these might be as maintainable as one would hope. With state management, you might have a getter for users, but those users include all users, meaning for a custom collection you would need a new getter method. An on-demand ajax request written specifically to solve a single issue, while it is simple to do, it quickly gets repetitive and laborious to maintain. [Upfront](./installation.md) solves the above by creating abstraction over the data in a unified api. Just like the above examples it can be used to fetch data on demand or be complimentary to state management libraries.
 
 ## Caveats
 While using this package increases ease of access and cuts down development time, it can also have unintended consequences. By pushing more logic to the client side you may expose backend logic such as data relations. Furthermore, if you're incorrectly implementing the [backend requirements](./installation.md#backend-requirements) you may introduce vulnerabilities such as sql injection.
 
 ---
 
 As always you're encouraged to explore the [source](https://github.com/upfrontjs/framework) yourself or look at the [api reference](https://upfrontjs.github.io/framework/) to gain insight on how the package works, and the [tests](https://github.com/upfrontjs/framework/tree/main/tests) to see how it's used.
-