fixing #153; moving breaking changes and a list of new features to md files; removing unused code; adding more unit tests; adding v1 github action to test the package

Author: AleksandrRogov

.github/BREAKING_CHANGES_V2.md

@@ -0,0 +1,118 @@
+# Breaking Changes in v2 (v1 -> v2)
+
+ ### 1. DynamicsWebApi Callbacks is fully removed
+All modern browsers support Promises (including await/async). The main reason why the Callbacks version was added in the first place was Internet Explorer which has been replaced with Edge and is neither maintained or supported by Microsoft anymore.
+
+ ### 2. Configuration object changes
+`webApiUrl` and `webApiVersion` have been removed and replaced with `serverUrl`, `dataApi` and `searchApi`. [#139](https://github.com/AleksandrRogov/DynamicsWebApi/issues/139) 
+
+**Node.JS**
+**Before**
+```js
+new DynamicsWebApi({
+    webApiUrl: "https://<YOUR ORG HERE>.api.crm.dynamics.com/api/data/v9.1/"
+});
+```
+**Now**
+```js
+new DynamicsWebApi({
+    serverUrl: "https://<YOUR ORG HERE>.api.crm.dynamics.com",
+    dataApi: {
+        version: "9.1"
+    }
+});
+```
+**Web Resource**
+**Before**
+```js
+new DynamicsWebApi({
+    webApiVersion: "9.1"
+});
+```
+**Now**
+```js
+new DynamicsWebApi({
+    dataApi: {
+        version: "9.1"
+    }
+});
+```
+
+ ### 3. All request functions with multiple parameters are removed.
+No more "simple" functions with multiple parameters. This has been done to streamline the request parameters and not introduce breaking changes when new parameters have been added. Furthermore, now all functions have access to impersonation, cache and data tracking functionality.
+
+### 4. Changes to the names of some request functions and properties
+
+| Old Name | New Name |
+|--------|--------|
+| createRequest | create |
+| updateRequest | update |
+| upsertRequest | upsert |
+| deleteRequest | deleteRecord |
+| retrieveRequest | retrieve |
+| retrieveMultipleRequest | retrieveMultiple | 
+| retrieveAllRequest | retrieveAll |
+| executeFetchXml | fetch |
+| executeFetchXmlAll | fetchAll |
+| executeBoundFunction | callFunction |
+| executeUnboundFunction | callFunction |
+| executeBoundAction | callAction |
+| executeUnboundAction | callAction |
+| utility | Utility |
+
+ ### 5. In some requests `entity` property is replaced with `data`
+Affected requests: `createRequest`, `updateRequest` and `upsertRequest` and their corresponding new names: `create`, `update` and `upsert`.
+
+Example:
+```js
+const lead = {
+    subject: "Test WebAPI",
+    firstname: "Test",
+    lastname: "WebAPI",
+    jobtitle: "Title"
+};
+
+const result = await dynamicsWebApi.create({
+    collection: "leads",
+    data: lead,
+    returnRepresentation: true
+});
+```
+
+### 6. `config.onTokenRefresh` is now a promise-based function
+Usage example:
+```ts
+const cca = new MSAL.ConfidentialClientApplication(msalConfig);
+const serverUrl = 'https://<YOUR ORG HERE>.api.crm.dynamics.com';
+
+//function calls an external functionality that acquires a token and passes it to DynamicsWebApi
+const acquireToken = async () => {
+    try {
+        return await cca.acquireTokenByClientCredential({
+            scopes: [`${serverUrl}/.default`],
+        });
+    }
+    catch (error) {
+        //error logging here
+        //or a fallback authentication
+
+        //to abort a request just return null
+        //or re-throw an error
+        return null;
+    }
+}
+
+const dynamicsWebApi = new DynamicsWebApi({
+    serverUrl: serverUrl,
+    onTokenRefresh: acquireToken
+});
+```
+
+### 7. Removed `id`  property from the request object.
+`id` has been deprecated for quite some time and got removed in v2. Use `key` instead.
+
+### 8. Default version of Dataverse API is set to `9.2`
+In case you still need version `8.0`, please set `dataApi.version` to `8.0`.
+
+### 9. Supported minimum version of Node.js raised to v.15.0.0.
+It was time to finally bump up the JavaScript specification from ES5 to ES2020 for the project. It is widely supported in all modern browsers and all currently maintained versions of Node. Even though the minimum Node.js version that supports ES2020 is 14.5.0, I would recommend running DynamicsWebApi on at least v.15.0.0 for all features to work correctly. In all versions prior to 15 the `AbortSignal` functionality won't work because it did not exist there yet.

.github/NEW_IN_V2.md

@@ -0,0 +1,42 @@
+# What's New in Version 2
+
+DynamicsWebApi v2 has been fully rewritten in TypeScript. The process of rewriting the code made it possible to refactor and improve many modules of the library and organize them in a more logical way as well as to remove redundant features that were no longer needed. As a result, DynamicsWebApi now has many new features such as:
+
+### Microsoft Dataverse Search API
+v2 brings the power of Search, Suggest and Autocomplete capabilities of Microsoft Dataverse Search API.
+
+### `AbortController` and `AbortSignal` support (for Node.js 15+ and Browser)
+Each request can now be aborted when it's no longer need to be completed via the `AbortController`.
+
+### All requests support Impersonation, NoCache and other common properties
+v1 did not have full support of mentioned properties in some requests. v2 fixes that by making all request parameters implement a single `BaseRequest` interface.
+
+### On demand Changesets in Batch Operations
+Control what requests should be included or excluded from the changesets by setting `inChangeSet` parameter to `false` (it's `true` when no set). By default, all requests (except for GET) are included in a changeset. Thus, it does not break the core logic introduced in v1.
+
+### CSDL $metadata document
+Retrieve the org's CSDL $metadata document with a single call of `retrieveCsdlMetadata` function. The library returns the raw text and does not parse or process it in any way.
+
+### NPM Package contents
+NPM package now includes a pre-bundled code of DynamicsWebApi to simplify a compilation process of the projects that depend on it. There are 4 separate bundles: 
+- `dist/dynamics-web-api.js` - a Browser ready version (to use as a Dynamics 365 web resource) [IIFE] + it's minified version `.min.js`.
+- `dist/cjs/dynamics-web-api.js` - a Node.js module [CommonJS].
+- `dist/esm/dynamics-web-api.mjs` - a Node.js module [ESM].
+- `dist/browser/esm/dynamics-web-api.js` - an ESM module for a Browser (to use as a Dynamics 365 web resource).
+
+Type definition for the library also moved into the `dist` folder.
+
+Please let me know (create an issue) if we need to add a `cjs` bundle for the Browser as well. I did not have any case where I had to use cjs specifically for the browser but it's just me :blush: and you may have a different case.
+
+### Other changes
+Not all changes are visible outside, some changes and fixes I've done were in the core of the library itself. Here are some of them:
+- All request objects passed as function parameters are fully cloned and remain untouched. Which means, whatever has been passed into the functions is not getting modified in any way. This was not always true in v1 (and I admit that it was my mistake). It is a positive change because _input parameters should never be changed inside the functions_ (there are exceptions but not in this case).
+- All deprecated JavaScript functions used by the library have been replaced with their modern alternatives.
+- The core has been _promisified_, except for `xhr` and `http` modules. This makes the overall code cleaner and easier to follow.
+- Rewriting to TypeScript gave me a chance to go through the code line by line and identify suboptimal functions/features which were successfully tweaked or removed.
+
+...and other.
+
+### Migration
+
+If you are currently using v1 and planning on migrating to v2 please consult with a list of [breaking changes](/.github/BREAKING_CHANGES_V2.md).

.github/README.md

@@ -12,14 +12,14 @@ As well as Microsoft Dynamics 365 CE (online), Microsoft Dynamics 365 CE (on-pre
 
 ### **This documentation is for version 2.x. If you are working with version 1.x, please check [this instead](https://github.com/AleksandrRogov/DynamicsWebApi/tree/v1).**
 
-Please check [DynamicsWebApi Wiki](../../wiki/) where you will find documentation to DynamicsWebApi API and more.
+Please check [DynamicsWebApi Wiki](../../../wiki/) where you will find documentation to DynamicsWebApi API and more.
 
 Browser-compiled script and type definitions can be found in a [dist](/dist/) folder.
 
 ## Main Features
 
-- **Microsoft Dataverse Search API**. Access full power of its Search, Suggestion and Autocomplete capabilities.
-- **Batch Requests**. Convert all requests into a Batch operation with a single line of code.
+- **Microsoft Dataverse Search API**. Access the full power of its Search, Suggestion and Autocomplete capabilities.
+- **Batch Requests**. Convert all requests into a Batch operation with two lines of code.
 - **Simplicity and Automation**. Such as automated paging, big file downloading/uploading in chunks of data, automated conversion of requests with long URLs into a Batch Request in the background and more!
 - **CRUD operations**. Including Fetch XML, Actions and Functions in Microsoft Dataverse Web API.
 - **Table Definitions (Entity Metadata)**. Query and modify Table, Column, Choice (Option Set) and Relationship definitions.
@@ -46,6 +46,8 @@ Also, please check [suggestions and contributions](#contributions) section to le
 
 ## Table of Contents
 
+* v2 breaking changes are [here](/.github/BREAKING_CHANGES_V2.md)
+* List of new features in v2 is [here](/.github/NEW_IN_V2.md)
 * [Getting Started](#getting-started)
   * [Dynamics 365 Web Resource](#dynamics-365-web-resource)
   * [Node.js](#nodejs)
@@ -121,7 +123,7 @@ Also, please check [suggestions and contributions](#contributions) section to le
 ### Dynamics 365 Web Resource
 To use DynamicsWebApi inside Dynamics 365 you need to download a browser version of the library, it can be found in [dist](/dist/) folder.
 
-Upload a script as a JavaScript Web Resource, add it to a table form or reference it in your HTML Web Resource and then initialize the main object:
+Upload a script as a JavaScript Web Resource, add it to a table form or reference it in the HTML Web Resource and then initialize the main object:
 
 ```ts
 //By default DynamicsWebApi makes calls to 
@@ -192,16 +194,15 @@ const acquireToken = async () => {
     }
 }
 
-//create DynamicsWebApi
+//create DynamicsWebApi;
+//By default DynamicsWebApi makes calls to 
+//Web API v9.2 and Search API v1.0
 const dynamicsWebApi = new DynamicsWebApi({
     serverUrl: serverUrl,
-    dataApi: {
-        version: "9.2"
-    },
     onTokenRefresh: acquireToken
 });
 
-try{
+try {
     //call any function
     const response = await dynamicsWebApi.callFunction("WhoAmI");
     console.log(`Hello from Dynamics 365! My id is: ${response.UserId}`);
@@ -269,7 +270,7 @@ If you are using `DynamicsWebApi` **outside Microsoft Dynamics 365** and set `us
 | path | `string` | A path to API, for example: "data" or "search". Optional. |
 | version | `string` | API Version, for example: "1.0" or "9.2". Optional. |
 
-Both `dataApi` and `seatchApi` can be omitted from a configuration. Their default values are:
+Both `dataApi` and `searchApi` can be omitted from a configuration. Their default values are:
 
 ```js
 //dataApi
@@ -293,7 +294,7 @@ Both `dataApi` and `seatchApi` can be omitted from a configuration. Their defaul
 
 ## Request Examples
 
-Please use [DynamicsWebApi Wiki](../../wiki/) for an object reference. It is automatically generated and I could not find a better doc generator, pardon me for that. If you know a good ".d.ts -> .md" doc generator - let me know!
+Please use [DynamicsWebApi Wiki](./../../wiki/) for an object reference. It is automatically generated and I could not find a better doc generator, pardon me for that. If you know a good ".d.ts -> .md" doc generator - let me know!
 
 The following table describes all __possible__ properties that can be set in `request` object.
 
@@ -2373,7 +2374,8 @@ If you are developing CRM Web Resources with TypeScript (and are not using NPM),
 The declaration file is an ESM module, so if you are not using any bundler, you will have to add another d.ts file (let's call it `dynamics-web-api.browser.d.ts` and put it in the `types` folder) that will make DynamicsWebApi available globally. Here is an example (the same folder structure as mentioned above):
 
 ```ts
-//import a class from dynamics-web-api.d.ts file
+//dynamics-web-api.browser.d.ts
+//import a DynamicsWebApi class from dynamics-web-api.d.ts file
 import { DynamicsWebApi } from "./dynamicsWebApi"
 //make the DynamicsWebApi class available globally
 export = DynamicsWebApi;
@@ -2408,7 +2410,7 @@ the config option "formatted" will enable developers to retrieve all information
 - [X] Full proxy support. `Added in v.1.7.2`.
 - [X] Refactoring and conversion to TypeScript - coming with `v.2.0`! Stay tuned!
 - [X] Implement [Dataverse Search API](https://docs.microsoft.com/en-us/power-apps/developer/data-platform/webapi/relevance-search). 
-- [ ] Allow custom headers to be passed to the request. #151
+- [ ] Allow custom headers to be passed to the request. [#151](https://github.com/AleksandrRogov/DynamicsWebApi/issues/151)
 
 Many more features to come!
 

.github/workflows/build-test-coverage-v1.yml

@@ -0,0 +1,35 @@
+# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
+
+name: DynamicsWebApi V1 CI
+
+on:
+  push:
+    branches: [ "v1" ]
+  pull_request:
+    branches: [ "v1" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [14.x, 16.x, 18.x]
+    steps:
+    - uses: actions/checkout@v3
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v3
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+    - run: npm ci
+    - run: npm run build --if-present
+    - run: npm test
+    # todo: add coveralls for v1
+    # - name: Prepare coverage
+    #   run: npm run test-coverage
+    # - name: Publish to Coveralls
+    #   if: ${{ matrix.node-version == 16.x }}
+    #   uses: coverallsapp/github-action@master
+    #   with:
+    #     github-token: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -26,9 +26,9 @@ Browser-compiled script and type definitions can be found in a [dist](/dist/) fo
 
 **Please note!** "Dynamics 365" in this readme refers to Microsoft Dataverse (formerly known as Microsoft Common Data Service) / Microsoft Dynamics 365 Customer Engagement / Micorosft Dynamics CRM. **NOT** Microsoft Dynamics 365 Finance and Operations.
 
-### For a full documentation please check [DynamicsWebApi on GitHub](https://github.com/AleksandrRogov/DynamicsWebApi).
+## Usage examples
 
-## Usage samples
+### For a full documentation please check [DynamicsWebApi on GitHub](https://github.com/AleksandrRogov/DynamicsWebApi).
 
 ### Dynamics 365 Web Resource
 To use DynamicsWebApi inside Dynamics 365 you need to download a browser version of the library, it can be found in [dist](/dist/) folder.
@@ -87,6 +87,8 @@ const contactId = responses[0];
 const salesorderId = responses[1];
 ```
 
+### For a full documentation please check [DynamicsWebApi on GitHub](https://github.com/AleksandrRogov/DynamicsWebApi).
+
 ## Contributions
 
 First of all, I would like to thank you for using `DynamicsWebApi` library in your Dynamics 365 CE / Common Data Service project, the fact that my project helps someone to achieve their development goals already makes me happy.