Merge pull request #327 from perry-mitchell/esm

ESM + fetch

.github/workflows/test.yml

@@ -7,11 +7,11 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [10.x, 12.x, 14.x, 16.x]
+        node-version: [14.x, 16.x, 18.x, latest]
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Node.js specs ${{ matrix.node-version }}
-        uses: actions/setup-node@v1
+        uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node-version }}
       - run: npm ci
@@ -20,11 +20,11 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [14.x]
+        node-version: [18.x]
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Node.js web specs ${{ matrix.node-version }}
-        uses: actions/setup-node@v1
+        uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node-version }}
         env:

.mocharc.json

@@ -0,0 +1,3 @@
+{
+    "loader": "ts-node/esm"
+}

README.md

@@ -6,34 +6,63 @@
 
 ## About
 
-WebDAV is a well-known, stable and highly flexible protocol for interacting with remote filesystems via an API. Being that it is so widespread, many file hosting services such as **Box**, **Nextcloud**/**ownCloud** and **Yandex** use it as a fallback to their primary interfaces.
+WebDAV is a well-known, stable and highly flexible protocol for interacting with remote filesystems via an API. Being that it is so widespread, many file hosting services such as **Nextcloud**/**ownCloud**, **Box** and **Yandex** use it as a fallback to their primary interfaces.
 
 This library provides a **WebDAV client** interface that makes interacting with WebDAV enabled services easy. The API returns promises and resolve with the results. It parses and prepares directory-contents requests for easy consumption, as well as providing methods for fetching things like file stats and quotas.
 
 This library's motivation is **not** to follow an RFC or to strictly adhere to standard WebDAV interfaces, but to provide an easy-to-consume client API for working with most WebDAV services from Node or the browser.
 
-### Node support
+### Supported Versions / Environments
 
-This library is compatible with **NodeJS version 10** and above (For version 6/8 support, use versions in the range of `2.*`. For version 4 support, use versions in the range of `1.*`). Versions 2.x and 1.x are no longer supported, so use them at your own risk. Version 3.x is deprecated and may receive the odd bugfix.
+Version 5 is under active development. Version 4 is in support mode, and will receive security and stability related bugfixes. Earlier versions are deprecated and will not receive updates.
 
-### Browser support
+Version 5 upgrades the library to use ESM (ECMAScript Modules), and so your environment must fit one of the following formats to be able to use this library:
 
-This WebDAV client is supported in the browser is of version 3. The compilation settings specify a minimum supported browser version of Internet Explorer 11, however testing in this browser is not performed regularly.
+ * NodeJS project with `"type": "module"` in `package.json` (ESM mode)
+ * Web project bundled with a tool like Webpack that can handle ESM
+
+If you're not ready to upgrade, you may consider using version 4 of this library.
+
+#### Requests
+
+This library uses [`cross-fetch`](https://github.com/lquixada/cross-fetch) to make requests in a cross-platform manner. It uses the browser's native `fetch` if present, or a polyfill if not. In Node and other environments it uses [`node-fetch`](https://github.com/node-fetch/node-fetch).
+
+Versions before v5 used Axios for requests.
+
+#### Node support
+
+Support table:
+
+| Library Major Version | Node JS Range     |
+|-----------------------|-------------------|
+| v5                    | 14+               |
+| v4                    | 10-18             |
+| v3                    | 10-16             |
+| v2                    | 6-14              |
+| v1                    | 4-12              |
+
+#### Browser support
+
+Browser environments are supported from version 3 onwards of this library.
+
+As mentioned above, v5 introduced ESM and this may require additional configuration when bundling for the browser.
 
 _Although you may choose to transpile this library's default entry point (NodeJS) yourself, it is not advised - use the dedicated web version instead._
 
-You can use the web version via a different entry point:
+In version 4 you had to use a different entry-point for the web version, and while this is still possible to use in version 5, you no longer need to:
 
 ```typescript
 import { createClient } from "webdav/web";
-```
 
-The browser version uses a UMD-style module definition, meaning you can simply load the library within your browser using a `<script>` tag. When using this method the library is made available on the window object as such: `window.WebDAV`. For example:
+// or
 
-```javascript
-const client = window.WebDAV.createClient(/* ... */);
+import { createClient } from "webdav";
+
+// will both work fine in supported bundlers
 ```
 
+Versions 3/4 supported a UMD-style module in the browser, but this is no longer supported in version 5. Version 5 provides only an ESM-enabled bundle that can be imported into other ESM-supporting projects.
+
 **NB:** Streams are not available within the browser, so `createReadStream` and `createWriteStream` are just stubbed. Calling them will throw an exception.
 
 ### Types
@@ -143,15 +172,14 @@ The available configuration options are as follows:
 | Option        | Default       | Description                                       |
 |---------------|---------------|---------------------------------------------------|
 | `authType`    | `null`        | The authentication type to use. If not provided, defaults to trying to detect based upon whether `username` and `password` were provided. |
+| `contactHref` | _[This URL](https://github.com/perry-mitchell/webdav-client/blob/master/LOCK_CONTACT.md)_ | Contact URL used for LOCKs. |
 | `headers`     | `{}`          | Additional headers provided to all requests. Headers provided here are overridden by method-specific headers, including `Authorization`. |
 | `httpAgent`   | _None_        | HTTP agent instance. Available only in Node. See [http.Agent](https://nodejs.org/api/http.html#http_class_http_agent). |
 | `httpsAgent`  | _None_        | HTTPS agent instance. Available only in Node. See [https.Agent](https://nodejs.org/api/https.html#https_class_https_agent). |
-| `maxBodyLength` | _None_      | Maximum body length allowed for sending, in bytes. |
-| `maxContentLength` | _None_   | Maximum content length allowed for receiving, in bytes. |
 | `password`    | _None_        | Password for authentication.                      |
 | `token`       | _None_        | Token object for authentication.                  |
 | `username`    | _None_        | Username for authentication.                      |
-| `withCredentials` | _None_    | Credentials inclusion setting for Axios.          |
+| `withCredentials` | _None_    | Credentials inclusion setting for the request,    |
 
 ### Client methods
 
@@ -377,8 +405,6 @@ Text files can also be fetched:
 const str: string = await client.getFileContents("/config.json", { format: "text" });
 ```
 
-Specify the `maxContentLength` option to alter the maximum number of bytes the client can receive in the request (**NodeJS only**).
-
 ```typescript
 (filename: string, options?: GetFileContentsOptions) => Promise<BufferLike | string | ResponseDataDetailed<BufferLike | string>>
 ```
@@ -392,23 +418,6 @@ Specify the `maxContentLength` option to alter the maximum number of bytes the c
 
 _`options` extends [method options](#method-options)._
 
-##### Download progress
-
-You can calculate the progress of the download by using `onDownloadProgress`:
-
-```typescript
-import { ProgressEvent } from "webdav";
-
-await client.getFileContents("/package.zip", {
-    onDownloadProgress: (progressEvent: ProgressEvent) => {
-        // {
-        //     total: 12345600,
-        //     loaded: 54023
-        // }
-    }
-});
-```
-
 #### getFileDownloadLink
 
 Generate a public link where a file can be downloaded. This method is synchronous. **Exposes authentication details in the URL**.
@@ -520,18 +529,6 @@ await client.putFileContents("/my/file.jpg", imageBuffer, { overwrite: false });
 await client.putFileContents("/my/file.txt", str);
 ```
 
-Specify the `maxBodyLength` option to alter the maximum number of bytes the client can send in the request (**NodeJS only**). When using `{ overwrite: false }`, responses with status `412` are caught and no error is thrown.
-
-Handling Upload Progress (browsers only):
-*This uses the axios onUploadProgress callback which uses the native XMLHttpRequest [progress event](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequestEventTarget/onprogress).*
-
-```typescript
-// Upload a file and log the progress to the console:
-await client.putFileContents("/my/file.jpg", imageFile, { onUploadProgress: progress => {
-    console.log(`Uploaded ${progress.loaded} bytes of ${progress.total}`);
-} });
-```
-
 ```typescript
 (filename: string, data: string | BufferLike | Stream.Readable, options?: PutFileContentsOptions) => Promise<boolean>
 ```
@@ -663,4 +660,9 @@ It is a known issue that ownCloud and Nextcloud servers by default don't return
 
 ## Projects using this WebDAV client
 
-[Buttercup Password Manager](https://github.com/buttercup), [Nextcloud Server](https://github.com/nextcloud/server), [Nextcloud Photos](https://github.com/nextcloud/photos), [ownCloud SDK](https://github.com/owncloud/owncloud-sdk), [React OxIDE](https://github.com/bootrino/reactoxide), [BackItUp](https://github.com/simatec/ioBroker.backitup)
+ * [Buttercup Password Manager](https://github.com/buttercup)
+ * [Nextcloud Server](https://github.com/nextcloud/server)
+ * [Nextcloud Photos](https://github.com/nextcloud/photos)
+ * [ownCloud SDK](https://github.com/owncloud/owncloud-sdk)
+ * [React OxIDE](https://github.com/bootrino/reactoxide)
+ * [BackItUp](https://github.com/simatec/ioBroker.backitup)