tsdav

tsdav is a TypeScript client library for the WebDAV, CalDAV, and CardDAV protocols, giving JavaScript and TypeScript applications a single JSON-based API for talking to any compliant server — Google Calendar, iCloud, Nextcloud, Fastmail, Zoho, and self-hosted Baikal/Radicale instances included. Instead of hand-rolling raw XML PROPFIND and REPORT requests, developers call typed functions like fetchCalendars, fetchVCards, and syncCollection and get back parsed JavaScript objects.

The library ships both a functional API (createDAVClient) and a class-based API (DAVClient), supports Basic, Bearer, Digest, OAuth2, and fully custom auth flows, and runs unmodified in Node.js 18+, browsers, Bun, Cloudflare Workers, and Deno thanks to a pluggable fetch implementation. Built-in sync-collection and smart-sync helpers handle CalDAV/CardDAV delta sync so consumers don’t need to reimplement ctag/sync-token bookkeeping themselves.

What You Get

• A createDAVClient/DAVClient pair covering account discovery, calendar and address book queries, object CRUD, and collection sync in one client instance.
• Built-in auth helpers for Basic, Bearer, Digest, OAuth2 (with token refresh), and fully custom auth functions.
• CalDAV and CardDAV sync primitives (syncCollection, smartCollectionSync, smartCollectionSyncDetailed) that manage ctag/sync-token comparisons for incremental updates.
• Cross-runtime support for Node.js 18+, browsers, Bun, Deno, and Cloudflare Workers via a pluggable fetch override.
• Automatic XML-to-JSON conversion for DAV requests and responses so callers work with plain JS objects instead of raw XML.

Common Use Cases

• Building a calendar app that reads and writes events against Google, iCloud, Fastmail, or Nextcloud CalDAV servers.
• Syncing contacts from a CardDAV-compliant address book (Apple, Nextcloud, Baikal) into an app’s own data store.
• Adding two-way calendar and contacts sync to a SaaS product without maintaining a separate integration per provider.
• Implementing incremental sync in a mobile or desktop client via syncCollection/smartCollectionSync instead of full refetches.

Under The Hood

Architecture tsdav is organized as one file per protocol concern: request.ts is the single choke point where XML<->JSON conversion (via xml-js) and header merging happen for every DAV call; collection.ts builds generic WebDAV collection query/sync primitives on top of it; calendar.ts and addressBook.ts add CalDAV/CardDAV-specific façades (fetchCalendars, fetchVCards, syncCalendarsDetailed, etc.); account.ts handles service discovery and account bootstrapping; and client.ts exposes two ergonomic entrypoints — a functional createDAVClient and a class-based DAVClient — both implemented as thin wrappers that partially apply shared params (auth headers, fetchOptions, fetch override) onto the same underlying functions via a defaultParam higher-order helper. Because every higher-level module depends on request.ts’s DAVRequest/DAVResponse shapes, that module is the load-bearing abstraction in the codebase.

Tech Stack The library is pure TypeScript with a deliberately minimal runtime dependency footprint — just debug for namespaced logging and xml-js for XML<->JS conversion. The build pipeline emits type declarations via tsc and bundles cjs/esm/browser outputs with rolldown (a Rust-based bundler), finalized by a custom scripts/finalize-dist.cjs step; biome handles linting and formatting instead of ESLint/Prettier; vitest with @vitest/coverage-v8 runs the test suite; and the package.json exports map ships conditional entrypoints for browser, deno, bun, worker, import, and require consumers, targeting Node.js >=18.

Code Quality The repo has an extensive unit test suite covering type helpers, camelCase conversion, fetch wrapping, request building, and each protocol module, plus a full set of integration tests that run against real Apple/iCloud, Nextcloud, Baikal, Fastmail, Google, and Zoho accounts (gated behind environment credentials and a MOCK_FETCH toggle for CI). GitHub Actions runs typecheck, lint, and test across a Node 18/20/22/24 matrix. TypeScript strict mode is enabled, biome enforces consistent style, and errors are thrown with explicit, descriptive messages rather than silently swallowed.

What Makes It Unique The standout technical choices are the smartCollectionSync/smartCollectionSyncDetailed helpers, which abstract WebDAV’s sync-collection REPORT semantics (ctag and sync-token comparison) into a single call instead of leaving delta-sync bookkeeping to the caller, and the multi-runtime packaging that lets one client run unmodified across Node.js, browsers, Bun, Deno, and Cloudflare Workers via a pluggable fetch and conditional package exports. The underlying DAV protocols themselves are standard, but comprehensive real-provider integration coverage and the sync abstraction are genuinely differentiated relative to other DAV clients.