WebDAV Client for Node.js

Common errors

• connect ECONNREFUSED <IP>:<PORT>

  cause The WebDAV server is not running, is inaccessible, or the specified URL/port is incorrect.
  fix Verify that the WebDAV server is operational and reachable from the client's host. Ensure the `url` provided in the `Connection` constructor is correct.

• Error: Not Found (404)

  cause The requested file or directory does not exist on the WebDAV server at the specified path.
  fix Double-check the path provided to WebDAV methods (e.g., `get`, `readdir`, `put`) for accuracy against the server's directory structure.

• Error: Unauthorized (401)

  cause The client failed to authenticate with the WebDAV server due to incorrect or missing credentials.
  fix Provide valid `username` and `password` in the `ConnectionOptions` or ensure a custom `authenticator` is correctly configured.

Warnings

• gotcha The `webdav-client` library is explicitly designed for Node.js environments and is not intended for use in browsers.
  Fix: For frontend applications, use a WebDAV client library specifically built and tested for browser compatibility.
• gotcha The API exclusively uses a callback-based asynchronous pattern, which might require adaptation if your project primarily uses Promises or async/await.
  Fix: Wrap callback-based methods in Promises using `util.promisify` from Node.js's built-in `util` module to enable `async/await` syntax, or choose an alternative client that natively supports Promises.
• gotcha The library does not include built-in retry mechanisms for transient network failures or server unavailability.
  Fix: Implement custom retry logic around API calls (e.g., using libraries like `p-retry` for Promises or a custom loop for callbacks) to improve resilience against intermittent connection issues.

Install

• npm install webdav-client npm
• yarn add webdav-client yarn
• pnpm add webdav-client pnpm

Imports

• * as webdavClient
  wrong:

  import webdavClient from 'webdav-client'

  correct:

  import * as webdavClient from 'webdav-client'

  Standard namespace import for accessing all exports, where `Connection` is a property of `webdavClient`.
• Connection
  wrong:

  import Connection from 'webdav-client'

  correct:

  import { Connection } from 'webdav-client'

  Named import for direct access to the primary `Connection` class.
• Connection (CommonJS)
  wrong:

  const { Connection } = require('webdav-client');

  correct:

  const webdavClient = require('webdav-client');
  const connection = new webdavClient.Connection(...);

  CommonJS import pattern. The `Connection` class is a property of the module object exported by `webdav-client`. Direct destructuring like `const { Connection } = require('webdav-client')` might not always yield the expected class if the module's export structure changes.

Quickstart

Demonstrates how to initialize the WebDAV client with optional authentication and fetch the content of a specified file using its callback-based API.

import { Connection } from 'webdav-client';
import * as path from 'path';

const webdavUrl = process.env.WEBDAV_URL ?? 'http://localhost:1900';
const webdavUser = process.env.WEBDAV_USER;
const webdavPass = process.env.WEBDAV_PASS;

const options = { url: webdavUrl };
if (webdavUser && webdavPass) {
    options.username = webdavUser;
    options.password = webdavPass;
}

const connection = new Connection(options);
const filePath = '/path/of/my/file.txt';

console.log(`Attempting to fetch file '${filePath}' from ${webdavUrl}`);

connection.get(filePath, (e, content) => {
    if (e) {
        console.error(`Error fetching file: ${e.message}`);
        // Additional error handling based on status codes (e.g., 404, 401)
        if (e.statusCode === 404) {
            console.error('File not found.');
        } else if (e.statusCode === 401) {
            console.error('Unauthorized access. Check credentials.');
        }
        return;
    }
    
    console.log(`Content of '${filePath}':\n${content.toString()}`);
});