feat: upstream release/0.x into main (#182)

## Docs 
* docs: updated pagination recipe 
* docs: corrected pagination example 
  * The exists method has taken the `_lastSyncedAt` property into account and here it was not set before 
* docs: adjust wording in doc blocks 
* docs(services): noted `handleError` is now async 
* docs(query-builder): added documentation for `resetQueryParameters` 
* docs: fixed grammar mistakes 
* docs(factory): updated examples to be in-line with mocks 
* docs(api-calls): updated methods to preferred uppercase 
* docs: updated recipe to use the new typing 
* docs(timestamps): updated attribute name getter method names 
    * Linked: 114176e 
* docs: fixed typo in test name 
* docs: updated pagination recipe to handle model constructors 
* docs(api-calls): updated to uppercase method names 
  * Updated all method argument to `call` to uppercase for consistency 
* docs: fixed examples 
* docs(api-calls): updated method name to uppercase 
  * change missed from 03486f1 
 
## Perf 
* perf(query-builder): simplified withs deduplication 
 
## Feature 
* feat(services): made handleError async on ApiResponseHandler 
* feat(api-calls): added default type argument 
  * While this is invalid, from the outside TS still figures the current `this` correctly 
* feat(query-builder): changed `resetQueryParameters` access to public 
* feat(api-calls): export `Method` type 
* feat(services): widened request type on ApiResponse 
* feat(services): added HEAD request handling 
* feat(services): improve typings of services call and handle method 
* feat(attributes): improved `Attributes` type inference 
    * Resolves #154 
* feat(attributes): improved `only` method's typing 
* feat(attributes): improved `except` typing 
* feat(attributes): improved typings on attribute management methods 
    * Following have been updated: 
      `getOriginal` 
      `getRawOriginal` 
      `getChanges` 
      `getDeletedAttributes` 
      `getNewAttributes` 
* feat: updated static methods returning models to infer type from `this` 
* feat: updated some static inference to not use error ignoring 
    * Updates related to: 63ed0be 
* feat(model): added `create` method 
    * This allows to constructing a model more fluently 
 
## Fix 
* fix(model): updated missed distinctBy in the clone method 
* fix(attributes): fixed casting methods typing to accept mixed values 
* fix(api-calls): pass the response attributes to the constructor 
  * This also cleans up the code a little 
* fix(services): normalised fetch methods 
  * `patch` could failed with lowercase method name 
* fix(api-calls): updated typing to be inclusive of each other on `get` 
* fix(relations): fixed `addRelation` typing to accept subclass of a model 
* fix: fixed outstanding eslint and typing errors 
* fix(model-collection): fixed wrong typing of `toJSON` 
    * Issue introduced in b4d6db4 
* fix(**BREAKING CHANGE**): renamed timestamp name methods 
  * Renamed the following: 
    `getDeletedAtColumn` -> `getDeletedAtName` 
    `getCreatedAtColumn` -> `getCreatedAtName` 
    `getUpdatedAtColumn` -> `getUpdatedAtName` 
 
## Test 
* test(timestamps): tested `restore` accepting server deletedAt value 
* test: added initial baseEndpoint in testing 
* test(services): added missing test updates 
    * Updates missed from a07b22a 
* test(attributes): fixed failing guarding tests 
* test(services): added missing test updates 
    * Updates missed from a07b22a 
* test(relations): updated testing to use the new typings 
* test(model): updated to use new typings 
* test(api-calls): added missing data unwrap test 
* test(api-calls): added missing endpoint getter test 
 
## Refactor 
* refactor(services): simplified `handleError` in response handler 
* refactor(attributes): simplified `getAttribute` override typing 
* refactor(factory): update return types of mock factories 
* refactor(model-collection): updated `toJSON` typing 
  * updated `toJSON` typing to track the model's `toJSON` 
 
## Chore 
* chore: incremented package version 
* chore: added new eslint rule 
* chore: moved todos into github 
* chore(deps): updated non-breaking dependencies 
  * @commitlint/prompt-cli 
  * @types/uuid 
  * @typescript-eslint/eslint-plugin 
  * @typescript-eslint/parser 
  * commitlint 
  * eslint 
  * eslint-plugin-jest 
  * lint-staged 
  * qs 
  * rollup 
  * typedoc 
  * typescript 
* chore(deps-dev): updated breaking change dependencies 
  * semantic-release 
 
## Style 
* style: fixed eslint issues 
 
## Continuous Integration 
* ci: added matrix values explanation

Author: nandi95

.eslintrc.js

@@ -40,6 +40,7 @@ module.exports = {
         "max-len": ["warn", 120],
         "eqeqeq": "error",
         "no-restricted-imports": "off",
+        "lines-between-class-members": "off",
 
         // https://github.com/typescript-eslint/typescript-eslint/tree/master/packages/eslint-plugin#supported-rules
         '@typescript-eslint/object-curly-spacing': ['warn', 'always'],
@@ -87,6 +88,7 @@ module.exports = {
         "@typescript-eslint/no-confusing-void-expression": "off",
         "@typescript-eslint/array-type": "warn",
         "@typescript-eslint/prefer-for-of": "off",
-        "@typescript-eslint/no-restricted-imports": "off"
+        "@typescript-eslint/no-restricted-imports": "off",
+        "@typescript-eslint/lines-between-class-members": ["error"],
     }
 }

.github/workflows/test.yml

@@ -20,6 +20,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
+        # current and active LTS
         node: [ 16, 17 ]
     steps:
       - uses: actions/checkout@v2

TODO

@@ -91,14 +91,14 @@ user.delete({ attribute: 1 });
 <Badge text="async" type="warning"/>
 <Badge text="advanced" type="warning"/>
 
-The `call` method is what powers the rest of the api calls on the model. It takes one argument and two optional arguments. The first argument is the method name which is one of `'delete' | 'get' | 'patch' | 'post' | 'put'`. The second is the data to send along with the request. and the third is any custom headers in an object format to be sent along. After the request the [resetEndpoint](#resetendpoint) will be called and all [query parameters](./query-building.md) will be reset.
+The `call` method is what powers the rest of the api calls on the model. It takes one argument and two optional arguments. The first argument is the method name which is one of `'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT' | 'HEAD'`. The second is the data to send along with the request. and the third is any custom headers in an object format to be sent along. After the request the [resetEndpoint](#resetendpoint) will be called and all [query parameters](./query-building.md) will be reset.
 
 ```ts
 import User from '@Models/User';
 
 const user = new User();
 
-await user.call('get', { query: 'value' }); // GET your-api.com/users?query=value
+await user.call('GET', { query: 'value' }); // GET your-api.com/users?query=value
 ```
 
 ### Endpoint manipulation

docs/calliope/api-calls.md

@@ -50,7 +50,7 @@ export default class User extends Model {
 **The following cast types are available:**
 
 ::: warning
-If the values cannot be casted, an error will be thrown.
+If the values cannot be cast, an error will be thrown.
 :::
 #### `'boolean'`
 Casts the values to boolean. It does not evaluate values as truthy or falsy, it expects the numeric `0, 1`, booleans or `'true', 'false'` in any casing. This is useful to parse the data from the back-end.
@@ -409,7 +409,7 @@ user.name; // 'Jane Doe'
 
 When setting an attribute following priority will apply to value:
  - If exists use the [mutator](#mutatorsaccessors) to set the attribute.
- - If [cast](#casting) defined, use the casted value to set the attribute.
+ - If [cast](#casting) defined, use the cast value to set the attribute.
  - If the `key` argument is a defined relation and the `value` argument is a valid relation value, set the relation value.
  - Otherwise, just set the attribute on the model.
 
@@ -428,7 +428,7 @@ Optionally the method takes a second argument which is returned if the key canno
 This method is internally used when accessing attributes on the model like in the above example. The model will resolve the value in the following order:
 
  - If the attribute exists and has an [accessor](#mutatorsaccessors), return the accessor's value.
- - If the attribute exists, and a cast has been defined, return the casted value.
+ - If the attribute exists, and a cast has been defined, return the cast value.
  - If the given key is a relation's name, and the relation [has been loaded](./relationships.md#relationloaded), return the relation.
  - If the key is a property of the model, and it's a function, return the default value.
  - If the key is a property of the model, return its value.

docs/calliope/attributes.md

@@ -348,7 +348,7 @@ User.orderByDesc('column');
 
 #### latest
 
-The `latest` method is an alias of the [orderBy](#orderby) method using a descending order. You may optionally specify which column to order by with the default being the result of the [getCreatedAtColumn](./timestamps.md#getcreatedatcolumn) method.
+The `latest` method is an alias of the [orderBy](#orderby) method using a descending order. You may optionally specify which column to order by with the default being the result of the [getCreatedAtName](./timestamps.md#getcreatedatname) method.
 
 ```js
 import User from '@Models/User';
@@ -359,7 +359,7 @@ User.latest('signed_up_at');
 
 #### oldest
 
-The `oldest` method is an alias of the [orderBy](#orderby) method using an ascending order. You may optionally specify which column to order by with the default being the result of the [getCreatedAtColumn](./timestamps.md#getcreatedatcolumn) method.
+The `oldest` method is an alias of the [orderBy](#orderby) method using an ascending order. You may optionally specify which column to order by with the default being the result of the [getCreatedAtName](./timestamps.md#getcreatedatname) method.
 
 ```js
 import User from '@Models/User';
@@ -399,6 +399,18 @@ import User from '@Models/User';
 User.newQuery(); // The query builder
 ```
 
+#### resetQueryParameters
+
+The `resetQueryParameters` is a method that clears all previously set query parameters.
+
+```js
+import User from '@Models/User';
+
+const user = new User();
+void user.where('columns', 'value').get(); // would send the where query
+void user.where('columns', 'value').resetQueryParameters().get(); // would NOT send any query
+```
+
 ## Properties
 
 #### withRelations

docs/calliope/query-building.md

@@ -71,7 +71,7 @@ This will typehint keys on the model when accessing the above keys like `user.ag
 
 #### primaryKey
 
-The `primaryKey` is a getter of the column name which is used to identify your model. The default value is `'id'`.
+The `primaryKey` is a getter of the attribute name which is used to identify your model. The default value is `'id'`.
 
 ```js
 // User.js
@@ -147,12 +147,12 @@ import User from '@Models/User';
 const user = User.factory().create();
 user.getKey(); // 1
 user.name; // 'the name'
-user.getAttribute(user.getCreatedAtColumn()); // Date instance
+user.getAttribute(user.getCreatedAtName()); // Date instance
 
 const userCopy = user.replicate();
 userCopy.getKey(); // undefined
 userCopy.name; // 'the name'
-userCopy.getAttribute(userCopy.getCreatedAtColumn()); // undefined
+userCopy.getAttribute(userCopy.getCreatedAtName()); // undefined
 ```
 
 #### clone

docs/calliope/readme.md

@@ -114,7 +114,7 @@ const userComments = await user.$comments().get();
 ```
 
 ::: tip
-[hasMany](#hasmany) and [hasOne](#hasone) methods also allows us to create related resources while automatically setting the related column value.
+[hasMany](#hasmany) and [hasOne](#hasone) methods also allows us to create related resources while automatically setting the related attribute value.
 
 ```ts
 // User.ts

docs/calliope/relationships.md

@@ -9,26 +9,26 @@ Timestamps are a feature of the model used for tracking changes on your entities
 #### createdAt
 
 The `createdAt` is a static property on the model. The default value is `'createdAt'`. You may over ride this if the expected timestamp attribute is named differently.
-The letter casing is no concern here as [getCreatedAtColumn](#getcreatedatcolumn) will update it to the correct casing.
+The letter casing is no concern here as [getCreatedAtName](#getcreatedatname) will update it to the correct casing.
 
 #### updatedAt
 
 The `updatedAt` is a static property on the model. The default value is `'updatedAt'`. You may over ride this if the expected timestamp attribute is named differently.
-The letter casing is no concern here as [getUpdatedAtColumn](#getupdatedatcolumn) will update it to the correct casing.
+The letter casing is no concern here as [getUpdatedAtName](#getupdatedatname) will update it to the correct casing.
 
 #### timestamps
 
 The `timestamps` is a read only attribute that signifies whether the model uses timestamps or not. The default value is `true`;
 
 ### Methods
 
-#### getCreatedAtColumn
+#### getCreatedAtName
 
-The `getCreatedAtColumn` method returns the value of the static [createdAt](#createdat) value with the letter casing set to the given [attributeCasing](./attributes.md#attributecasing).
+The `getCreatedAtName` method returns the value of the static [createdAt](#createdat) value with the letter casing set to the given [attributeCasing](./attributes.md#attributecasing).
 
-#### getUpdatedAtColumn
+#### getUpdatedAtName
 
-The `getUpdatedAtColumn` method returns the value of the static [updatedAt](#updatedat) value with the letter casing set to the given [attributeCasing](./attributes.md#attributecasing).
+The `getUpdatedAtName` method returns the value of the static [updatedAt](#updatedat) value with the letter casing set to the given [attributeCasing](./attributes.md#attributecasing).
 
 #### usesTimestamps
 
@@ -37,7 +37,7 @@ The `usesTimestamps` method returns the value of the [timestamps](#timestamps-3)
 #### touch
 <Badge text="async" type="warning"/>
 
-The `touch` method sends a `PATCH` request with the new [updatedAt](#getupdatedatcolumn) attribute value. It updates the attribute from the response data.
+The `touch` method sends a `PATCH` request with the new [updatedAt](#getupdatedatname) attribute value. It updates the attribute from the response data.
 
 ::: tip
 Your backend should probably not trust this input, but generate its own timestamp.
@@ -46,7 +46,7 @@ Your backend should probably not trust this input, but generate its own timestam
 #### freshTimestamps
 <Badge text="async" type="warning"/>
 
-The `freshTimestamps` method sends `GET` request [selecting](./query-building.md#select) only the [createdAt](#getcreatedatcolumn) and [updatedAt](#getupdatedatcolumn) attributes, which are updated from the response on success.
+The `freshTimestamps` method sends `GET` request [selecting](./query-building.md#select) only the [createdAt](#getcreatedatname) and [updatedAt](#getupdatedatname) attributes, which are updated from the response on success.
 
 ## Soft Deletes
 
@@ -55,21 +55,21 @@ The `freshTimestamps` method sends `GET` request [selecting](./query-building.md
 #### deletedAt
 
 The `deletedAt` is a static property on the model. The default value is `'deletedAt'`. You may over ride this if the expected timestamp attribute is named differently.
-The letter casing is no concern here as [getDeletedAtColumn](#getdeletedatcolumn) will update it to the correct casing.
+The letter casing is no concern here as [getDeletedAtName](#getdeletedatname) will update it to the correct casing.
 
 #### softDeletes
 
 The `softDeletes` is a read only attribute that signifies whether the model uses soft deleting or not. The default value is `true`;
 
 #### trashed
 
-The `trashed` is a getter property that returns a boolean depending on whether the model has the [deletedAt](#getdeletedatcolumn) set to a truthy value.
+The `trashed` is a getter property that returns a boolean depending on whether the model has the [deletedAt](#getdeletedatname) set to a truthy value.
 
 ### Methods
 
-#### getDeletedAtColumn
+#### getDeletedAtName
 
-The `getDeletedAtColumn` method returns the value of the static [deletedAt](#deletedat) value with the letter casing set to the given [attributeCasing](./attributes.md#attributecasing).
+The `getDeletedAtName` method returns the value of the static [deletedAt](#deletedat) value with the letter casing set to the given [attributeCasing](./attributes.md#attributecasing).
 
 #### usesSoftDeletes
 
@@ -80,7 +80,7 @@ The `usesSoftDeletes` method returns the value of the [softDeletes](#softdeletes
 
  The `delete` method is an extension of the api calling method [delete](./api-calls.md#delete). If the model is not [using softDeletes](#usessoftdeletes) the logic will fall back to the original [delete](./api-calls.md#delete) method's logic therefore, method accepts an optional object argument which will be sent along on the request in the body.
 
-This method sends a `DELETE` request with the new [deletedAt](#getdeletedatcolumn) attribute value. It updates the attribute from the response data.
+This method sends a `DELETE` request with the new [deletedAt](#getdeletedatname) attribute value. It updates the attribute from the response data.
 
 ::: tip
 Your backend should probably not trust this input, but generate its own timestamp.
@@ -89,6 +89,6 @@ Your backend should probably not trust this input, but generate its own timestam
 #### restore
 <Badge text="async" type="warning"/>
 
-The `restore` methods sends a `PATCH` request with the nullified [deletedAt](#getdeletedatcolumn) attribute value. It updates the attribute to `null` on successful request.
+The `restore` methods sends a `PATCH` request with the nullified [deletedAt](#getdeletedatname) attribute value. It updates the attribute to `null` on successful request.
 
 

docs/calliope/timestamps.md

@@ -129,7 +129,7 @@ const form = new FormData;
 const response = await handler.handle(
     api.call(
         config.get('baseEndPoint').finish('/') + 'form',
-        'post',
+        'POST',
         form,
         { 'X-Requested-With': 'Upfront' },
         { query: { parameters: 'to encode' } }
@@ -175,7 +175,7 @@ const myFirstUser = await User.where('name', 'like', '%me%').first()
 Extending/overwriting the model should not be a daunting task. If we wanted we could add an extra method to send data to the server. In this example we add a new field on the sent data which is called `appends` and we're expecting the server to append additional information on the model response data.
 
 ```ts
-import type { FormatsQueryParameters, QueryParams } from '@upfrontjs/framework';
+import type { FormatsQueryParameters, QueryParams, StaticToThis } from '@upfrontjs/framework';
 import { Model as BaseModel } from '@upfrontjs/framework';
 
 export default class Model extends BaseModel implements FormatsQueryParameters {
@@ -185,9 +185,9 @@ export default class Model extends BaseModel implements FormatsQueryParameters {
         this.appends.push(name);
         return this;
     }
-    
-    public static append<T extends Model>(name: string): T {
-        this.newQuery<T>().append(name);
+
+    public static append<T extends StaticToThis<Model>>(this: T, name: string): T['prototype'] {
+        this.newQuery().append(name);
     }
 
     public withoutAppend(name: string): this {
@@ -217,50 +217,98 @@ Now if our other models extend our own model they will have the option to set th
 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.
 
 ```ts
-// utils.ts
-import type { Model, ModelCollection } from '@upfrontjs/framework';
-import User from '@models/User';
+// paginator.ts
+import type { Attributes, Model } from '@upfrontjs/framework';
+import { ModelCollection } from '@upfrontjs/framework';
 
-interface MyJsonApiResponse {
-    data: Attributes[];
+interface PaginatedApiResponse<T = Attributes> {
+    data: T[];
     links: {
         first: string;
         last: string;
-        next: string;
+        prev: string | null;
+        next: string | null;
     };
     meta: {
         current_page: number;
+        /**
+         * From all the existing records this is where the current items start from.
+         */
         from: number;
+        /**
+         * From all the existing records this is where the current items go to.
+         */
         to: number;
         last_page: number;
+        /**
+         * String representation of a number.
+         */
+        per_page: string;
+        links: {
+            url: string | null;
+            label: string;
+            active: boolean;
+        }[];
+        /**
+         * Total number of records.
+         */
         total: number;
         path: string;
     };
 }
 
-interface PaginatedModels<T extends Model> {
+export interface PaginatedModels<T extends Model> {
     data: ModelCollection<T>;
-    next: () => Promise<PaginatedModels<T>>;
-    previous: () => Promise<PaginatedModels<T>>;
-    page: (page: number) => Promise<PaginatedModels<T>>;
-    meta: MyJsonApiResponse['meta'];
+    next: () => Promise<PaginatedModels<T> | undefined>;
+    previous: () => Promise<PaginatedModels<T> | undefined>;
+    page: (page: number) => Promise<PaginatedModels<T> | undefined>;
+    hasNext: boolean;
+    hasPrevious: boolean;
+    from: PaginatedApiResponse['meta']['from'];
+    to: PaginatedApiResponse['meta']['to'];
+    total: PaginatedApiResponse['meta']['total'];
 }
 
-export async function paginateModels<T extends Model>(builder: T, page = 1, limit = 25): Promise<PaginatedModels<T>> {
-    const response = await builder.clone().limit(limit).page(page).call<MyJsonApiResponse>('get');
-    const modelCollection = new ModelCollection<T>(response!.data.map(attributes => builder.new(attributes)));
-    // or some other custom logic where the response `meta` and `links` or other keys (if any) are taken into account
+async function paginatedModels<T extends Model>(
+    builder: T | (new() => T),
+    page = 1,
+    limit = 25
+): Promise<PaginatedModels<T>> {
+    const instance = !(builder instanceof Model) ? new builder() : builder.clone();
+    
+    const response = (await instance.limit(limit).page(page).call<PaginatedApiResponse<Attributes<T>>>('GET'))!;
+    const modelCollection = new ModelCollection<T>(response.data.map(attributes => {
+        return instance
+            .new(attributes)
+            // @ts-expect-error - Protected internal method required for correct .exists detection
+            .setLastSyncedAt();
+    }));
 
     return {
         data: modelCollection,
-        next: async () => paginateModels(builder, page + 1, limit),
-        previous: async () => paginateModels(builder, page - 1, limit),
-        page: async (pageNumber: number) => paginateModels(builder, pageNumber, limit),
-        meta: response!.meta
-        // any other keys here like that you want to have access to
+        next: async () => {
+            if (!response.links.next) return;
+            return paginatedModels(instance, page + 1, limit);
+        },
+        previous: async () => {
+            if (!response.links.prev) return;
+            return paginatedModels(instance, page - 1, limit);
+        },
+        page: async (pageNumber: number) => {
+            if (pageNumber > response.meta.last_page || pageNumber < 0) return;
+            return paginatedModels(instance, pageNumber, limit);
+        },
+        from: response.meta.from,
+        to: response.meta.to,
+        total: response.meta.total,
+        hasNext: !!response.links.next,
+        hasPrevious: !!response.links.prev
     };
 }
 
+export default paginator;
+
+// script.ts
 // paginate users where column has the value of 1
 const firstPage = await paginateModels(User.where('column', 1));
 const secondPage = await firstPage.next();

docs/cookbook.md

@@ -12,7 +12,7 @@ The `handleSuccess` method attempts to parse the [`ApiResponse`](./readme.md#api
 
 #### handleError
 
-The `handleError` method throws the captured error from [handleSuccess](#handlesuccess).
+The `handleError` is an async method that throws the captured error from [handleSuccess](#handlesuccess).
 
 #### handleFinally