@weapnl/js-junction 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+## Unreleased
+
+## v3.3.5
+- Lodash is now globally available.
+
+## v3.3.4
+- Changed how empty array/object is sent to API through form-data. Previously a key with a `null` value would be sent, now a key with an empty string value will be sent.
+
+## v3.3.3
+- Changed how empty array/object is sent to API through form-data. Previously no key or value would be sent, now a key with a `null` value will be sent.
+
+## v3.3.2
+- Added new option to `attribute, relation or accessor` called `jsonKey` which specifies the key to use when parsing from/to json. 
+
+## v3.3.1
+- Now using *signal* instead of the deprecated *cancel token* to cancel requests.
+- Updated `axios` to `1.3`.
+- Fixed dependency vulnerabilities (`npm audit fix`).
+
+## v3.3.0
+- Added ability to set global headers.
+
+## v3.2.0
+- Added ability to set response interceptors.
+
+## v3.1.0
+- Fixed bug where `null` values were omitted when using a FormData request.
+
+## v3.0.5
+- Fixed the bug where the given data was merged into the files object in the `storeFiles` method.
+
+## v3.0.4
+- Added build service in docker-compose.
+- Booleans are now cast to `'0'` or `'1'` in form data.
+
+## v3.0.3
+- Fixed bug where `model.show()` would allow an empty parameter, effectively causing an `index` request to be executed.
+- When type of `attribute, relation or accessor` is Object, and the json value is an Array, convert it to an Object.
+
+## v3.0.2
+- Improvement to some JSDoc's for better autocomplete.
+- Made data of FormData recursive when using the `storeFiles` method on the `Request` model.
+
+## v3.0.1
+- Fixed bug where `false` values would be parsed as `null`.
+
+## v3.0.0
+- Added docker-compose file.
+- Now using `/src/index.js` as main file instead of `/dist/index.js`.
+- Added a pluck method.
+
+## v2.7.5
+- Added `toJson` and `fromJson` options for accessors.
+
+## v2.7.4
+- Fixed a bug where the default value for Accessor's was not used properly.
+
+## v2.7.3
+- Fixed a bug where query params would contain empty or null values.
+
+## v2.7.2
+- Fixed a bug in `Caster.js` where Array type would be cast to an array inside an array (for example `[["test@email.com"]]`).
+
+## v2.7.1
+- Fixed a bug in `Caster.js` where an error was thrown if an accessor value of type `Model` was null/undefined.
+- Added `storeFiles()` to the `batch` class.
+
+## v2.7.0
+- Added `counts` to count relations (#3).
+- Added ability to perform an action using the `action()` method in the Request class. 
+- **BREAKING:** `save()` method on Model class doesn't accept `identifier` parameter anymore.
+
+## v2.6.0
+- Added ability to store files through the `storeFiles()` method in the request class.
+- Added method (`customParameters`) to add custom parameters to a request.
+- Now handling any status code between 200-300 as a successful request.
+- Fixed a bug where the `Caster` class tried to cast an `undefined` value and crashed. Added extra check which returns `null` when the value to be cast is `undefined`
+
+## v2.5.1
+- Fixed bug where the `whereIn` filter set the wrong variable for the column.
+
+## v2.5.0
+- Added `save()` method to Model and Batch classes.
+- Now setting properties on model instead of using getters/setters.
+- Fixed bug where default attribute/relation values weren't set when creating a new model.
+- Added ability to set type for `accessors` so they can be cast.
+
+## v2.4.0
+- Fixed bug where having 2 models with relations to each other would result in an infinite loop.
+- Added `extraData` parameter to the `store()` and `update()` methods on a `Model`.
+- Added function (`batch`) to run multiple requests at the same time (#2).
+- Added ability to set default values in constructor of models.
+- Response events are now async safe.
+- Changed how casting is done and the caster doesn't try to cast `null` values anymore.
+- Now formatting error messages so nested errors are returned as objects.
+
+## v2.3.1
+- Fixed bug where converting to snake case would break when using dot notation.
+
+## v2.3.0
+- **BREAKING:** Removed the `defaults()` and `casts()` methods in favor of a new `attributes()` method for better expandability of the package.
+- Added `relations()` and `accessors()` methods to the Model class.
+- **BREAKING:** Removed the `getAttribute()` and `setAttribute()` methods of the Model class.
+- **BREAKING:** `toJson()` now returns the attributes, accessors and relations instead of just the attributes.
+
+## v2.2.0
+- Now converting columns to snake case in `order`, `search`, `whereIn` and `wheres`.
+- Moved `pagination` from modifiers to separate class (in accordance with https://repo.weap.nl/packages/laravel/restapi/-/merge_requests/8).
+- Added optional `findPageById` parameter to `pagination` to find the page the given id is on.
+
+## v2.1.0
+- Added `casts()` method to the `Model` class so specific casts can be done on incoming json. 
+- Fixed a bug where in some filters the wrong separator was used to generate the url.
+
+## v2.0.0
+- Added `Model` class with included query builder for an easier syntax than the existing requests.
+- Changed entry file from `api.js` to a new file `index.js`.
+- Moved some code from `Request`  to new class `Connection` to support the new `Model` class.
+- Moved `filter` and `modifier` methods to mixins.  
+- **BREAKING:** Changed how the `api` is initialized and configured. Read `README.md` for more info.
+
+## v1.1.0
+- Added custom callbacks `onSuccess`, `onError`, `onValidationError`, `onUnauthorized`, `onForbidden`.
+
+## v1.0.0
+- Initial version

package/README.md

@@ -0,0 +1,348 @@
+# JS-Junction
+
+This project allows you to easily consume API's built with [Laravel-Junction](https://github.com/weapnl/Laravel-Junction).
+
+This package has support for Typescript (TS).
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+    - [Creating Models](#creating-models)
+    - [Performing Requests](#performing-requests)
+    - [Applying Filters and Scopes](#applying-filters-and-scopes)
+
+## Installation
+```bash
+npm install @weapnl/js-junction
+```
+
+## Quick Start
+```javascript
+import api, { Model } from '@weapnl/js-junction';
+
+api.host('YOUR API HOST URI HERE') // Optionally: add '.suffix('API SUFFIX HERE');'
+
+// Define a model
+class User extends Model {
+    static attributes () {
+        return {
+            id: {
+                type: Number,
+            },
+            name: {
+                type: String,
+            },
+        };
+    }
+
+    static get endpoint () {
+        return 'users';
+    }
+}
+
+// Create a new user.
+const user = new User();
+user.name = 'John';
+user.store();
+
+// Retrieve a user.
+const user = User.show(1);
+
+// Update the user.
+user.name = 'Jane';
+user.update();
+
+// Delete the user.
+user.destroy();
+
+// List all users.
+const users = User.index();
+```
+
+## Usage
+
+### Creating Models
+```javascript
+// User.js
+import { Model } from '@weapnl/js-junction';
+
+export default class User extends Model {
+    // All the model properties which are fully readable and fillable on the API
+    static attributes () {
+        return {
+            // Note: id is ALWAYS required
+            id: {
+                // Default value to be assigned when creating the empty property.
+                default: 0,
+
+                // Will be used to cast from/to json. Has higher priority than the seperate 'fromJson' and 'toJson' methods.
+                type: Number, // Type will be used to cast from and to json
+
+                // Casts that will be performed when creating the model from json.
+                // Allows:
+                // - Functions
+                // - Array of functions, executed from left to right and each following function gets the return value of the previous.
+                // - Javascript types
+                // - Models that inherit from the Model class.
+                fromJson: _.toNumber,
+                toJson: [_.toString, _.trim],
+
+                // The key which is used when parsing the attribute from/to json. By default the snake_case version of the attribute name will be used.
+                jsonKey: 'id',
+            }, 
+
+            // All options are optional and if no options are given an empty object should be passed.
+            name: {},
+            email: {},
+            phone: {},
+        };
+    }
+
+    // Relations of the model which are defined in the API
+    static relations () {
+        return {
+            addresses: {
+                // Value(s) of the relation will be cast to the type. Same casts are allowed as the attributes. 
+                // If a list of items is returned, the cast will be preformed on each item seperately.
+                type: Address,
+
+                // The key which is used when parsing the attribute from/to json. By default the snake_case version of the attribute name will be used.
+                jsonKey: 'id',
+            },
+        };
+    }
+
+    // Accessors of the model which are defined in the API.
+    static accessors () {
+        return {
+            fullName: {
+                // Default value to be assigned when creating the empty property.
+                default: '',
+
+                // Will be used to cast from/to json. Has higher priority than the seperate 'fromJson' and 'toJson' methods.
+                type: String,
+
+                // Casts that will be performed when creating the model from json.
+                // Allows:
+                // - Functions
+                // - Array of functions, executed from left to right and each following function gets the return value of the previous.
+                // - Javascript types
+                // - Models that inherit from the Model class.
+                fromJson: _.toNumber,
+                toJson: [_.toString, _.trim],
+
+                // The key which is used when parsing the attribute from/to json. By default the snake_case version of the attribute name will be used.
+                jsonKey: 'id',
+            },
+        }
+    }
+
+    // Counts of relations of the model which are defined in the API.
+    static counts () {
+        return {
+            posts: {
+                default: 0,
+            },
+        }
+    }
+
+    // Used to know what URL to send the request to.
+    static get endpoint () {
+        return 'users';
+    }
+}
+```
+
+### Performing Requests
+
+#### Model Requests
+```javascript
+// Create a new user.
+const user = new User();
+user.name = 'John';
+user.store();
+
+// Retrieve a user.
+const user = new User().show(1);
+
+// Update the user.
+user.name = 'Jane';
+user.save(); // This will call store() or update() depending on the id of the model.
+
+// Delete the user.
+user.destroy();
+
+// List all users.
+const users = new User().index();
+```
+
+#### Applying filters and scopes
+```javascript
+// Get all users that match the filters
+const request = await new User()
+    .limit(10) // Limit max 10 items
+    .order('id', 'asc') // Order by id ascending
+    .order([['id', 'asc'], ['name', 'desc']]) // Order by id ascending and name descending
+    .with('orders') // Load relation
+    .with(['orders']) // Load relations
+    .count('orders') // Add relation counts (will add a key `ordersCount` to the result)
+    .scope('hasOrders', 'extra params') // Apply scope
+    .search('john doe') // Search for 'john doe', on the searchable columns of the model (defined in the API)
+    .search('john doe', ['name', 'email']) // Search for 'john doe' in columns 'name' and 'email'
+    .whereIn('city', ['Gemert', 'Eindhoven', 'Amsterdam']) // Set where in clause
+    .where('name', '=', 'John') // Add where clause
+    .where('name', 'John') // If no operator is given, '=' is used
+    .appends('age') // Add accessor
+    .appends(['age']) // Add accessors
+    .hiddenFields('id') // Hide field
+    .hiddenFields(['id', 'comments']) // Hide fields
+    .pluck('name') // Only retrieve the given fields
+    .pluck(['name', 'company.name']) // Only retrieve the given fields 
+    .pagination(1, 25) // Paginate 25 per page, page 1
+    .pagination(1, 25, 50) // The 3th parameter is a pageForId parameter. This is used to find the correct page for the given id. If the id can not be found, the given page will be used. It will now look for the user with id 50, and returns that page.
+    .get();
+```
+
+#### Examples
+
+**The `.save()` method.**
+
+To create a new record or update an existing one, you can use the `.save()` method. This method is a convenient shortcut for `.store()` and `.update()`. It determines whether to create or update by checking if the model's `id` is set. If an `id` is present, `.update()` is called; otherwise, `.store()` is used to create a new record.
+
+**Cloning a model's instance.**
+```javascript
+// Return a clone of the model
+const clonedUser = user.clone();
+```
+
+**Batch requests**
+```javascript
+const firstUser = new User().show(1);
+firstUser.name = 'John';
+
+const secondUser = new User().show(2);
+secondUser.name = 'Jane';
+
+const batch = await api.batch([
+    firstUser,
+    secondUser,
+]);
+
+await batch.update();
+
+if (batch.successful) {
+    // All requests executed successfully.
+}
+```
+
+**Regular requests**
+```javascript
+// Get all users from a custom endpoint
+const users = api.request('users').get();
+
+// Custom POST request
+await api.request('users')
+    .onSuccess((response) => {
+        // Handle success
+    })
+    .post({
+        name: 'John',
+        email: 'john@example.com'
+    });
+```
+The request has support for GET, POST, PUT and DELETE requests.
+
+**Custom actions**
+
+This package also supports custom actions. These actions can be defined in the API and can be called on a model or a custom request.
+```javascript
+const request = await api
+    .request('CUSTOM ENDPOINT')
+    .action('actionName', 1) // You can pass the id of the model here, or the id of the request. In this case it is 1.
+    .put({
+        // Extra data
+    });
+
+const user = new User().show(1);
+
+const request = await user
+    .action('actionName') // It will take the id of the user now, since it is a model. The id is 1 in this case.
+    .put({
+        // Extra data
+    });
+```
+**Store files**
+
+```javascript
+// First parameter is a file or array of files.
+// Second parameter is an object with possible extra data to send to the backend. PLEASE NOTE: Be aware that it will be sent as FormData.
+
+let request = await api.request('users/files')
+    .storeFiles(this.files, {
+        filePrefix: 'test_', 
+        extraDataId: 123,
+    });
+```
+
+**Custom callbacks**
+
+```javascript
+let request = await api.request('users')
+    .onSuccess((data) => {
+        // Request successful
+    })
+    .onUnauthorized((response) => {
+        // Missing or invalid token
+    })
+    .onForbidden((response) => {
+        // Access not allowed
+    })
+    .onValidationError((validation) => {
+        // validation.message
+        // validation.errors
+    })
+    .onError((response) => {
+        // Any other status code not caught by other callbacks
+    })
+    .get();
+```
+
+**Cancel requests**
+
+If you want to cancel a pending request, you can do the following:
+```javascript
+const request = api.request('users').get();
+request.cancel();
+
+api.cancelRequests(); // Cancel all currently pending requests.
+```
+
+**Set a bearer token**
+
+```javascript
+api.setBearer('YOUR TOKEN HERE');
+
+api.resetBearer(); // Resets the bearer token.
+```
+
+**Set a CSRF token**
+
+```javascript
+api.setCsrf('YOUR TOKEN HERE');
+
+api.resetCsrf(); // Resets the CSRF token.
+```
+
+**Set a custom header**
+
+```javascript
+api.setHeader('HEADER NAME HERE', 'YOUR VALUE HERE');
+
+api.removeHeader('HEADER NAME HERE'); // Removes the header.
+```
+
+**Sample response**
+
+After executing a request, the property `response` contains a `Response` object, which has properties `statusCode`, `data` and `validation`.

package/babel.config.json

@@ -0,0 +1,5 @@
+{
+    "presets": [
+        "@babel/preset-env"
+    ]
+}