os-user-dirs 3.0.0 → 3.1.0

package/README.md

@@ -1,18 +1,35 @@
-# os-user-dirs [![CI](https://github.com/velocitylabo/os-user-dirs/actions/workflows/ci.yml/badge.svg)](https://github.com/velocitylabo/os-user-dirs/actions/workflows/ci.yml)
+# os-user-dirs
 
-Get OS-specific user directories (Downloads, Desktop, Documents, etc.) and XDG base directories (config, data, cache, state, log, runtime) with zero dependencies. Also provides `projectDirs()` for app-scoped directories (similar to `env-paths`).
+[![npm version](https://img.shields.io/npm/v/os-user-dirs.svg)](https://www.npmjs.com/package/os-user-dirs)
+[![npm downloads](https://img.shields.io/npm/dw/os-user-dirs.svg)](https://www.npmjs.com/package/os-user-dirs)
+[![CI](https://github.com/velocitylabo/os-user-dirs/actions/workflows/ci.yml/badge.svg)](https://github.com/velocitylabo/os-user-dirs/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/velocitylabo/os-user-dirs/graph/badge.svg)](https://codecov.io/gh/velocitylabo/os-user-dirs)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/os-user-dirs)](https://bundlephobia.com/package/os-user-dirs)
+[![Node.js](https://img.shields.io/node/v/os-user-dirs.svg)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/os-user-dirs.svg)](https://github.com/velocitylabo/os-user-dirs/blob/master/LICENSE)
 
-> **Note:** This package was previously published as [`os-downloads`](https://www.npmjs.com/package/os-downloads). The old package is deprecated — please use `os-user-dirs` instead.
+> All-in-one OS directory paths — user directories, XDG base directories, and app-scoped project directories — with zero dependencies.
 
-## Requirements
+- Node.js 20 or later
 
-- Node.js 18 or later
+Replaces [`env-paths`](https://github.com/sindresorhus/env-paths), [`xdg-basedir`](https://github.com/sindresorhus/xdg-basedir), and [`platform-folders`](https://github.com/nicbarker/platform-folders) in a single package. CJS + ESM dual support, TypeScript included.
 
-## Supported platforms
+> **Note:** This package was previously published as [`os-downloads`](https://www.npmjs.com/package/os-downloads). The old package is deprecated — please use `os-user-dirs` instead.
 
-- Windows
-- macOS
-- Linux (with XDG user-dirs.dirs support)
+## Why os-user-dirs?
+
+| Feature | os-user-dirs | env-paths | xdg-basedir | platform-folders |
+|---|:---:|:---:|:---:|:---:|
+| Weekly downloads | Growing | ~30M | ~7M | ~642 |
+| Last updated | **Active** | 4 years ago | 4 years ago | Low activity |
+| Dependencies | **0** | 0 | 0 | C++ native |
+| Platforms | **All** | All | Linux only | All |
+| User directories (8) | **Yes** | - | - | Partial |
+| XDG base directories (6) | **Yes** | Partial | **Yes** | Partial |
+| XDG search paths | **Yes** | - | **Yes** | - |
+| Project directories | **Yes** | **Yes** | - | - |
+| CJS + ESM | **Both** | ESM only (v3) | ESM only (v5) | CJS |
+| TypeScript | **Included** | Included | Included | - |
 
 ## Install
 
@@ -20,135 +37,35 @@ Get OS-specific user directories (Downloads, Desktop, Documents, etc.) and XDG b
 $ npm install os-user-dirs
 ```
 
-## Usage
+Requires Node.js 20 or later. Works on Windows, macOS, and Linux.
 
-### ESM (recommended)
+## Quick Start
 
 ```javascript
-import { downloads, desktop, documents, music, pictures, videos, templates, publicshare, getPath, homeDir } from "os-user-dirs";
-
-homeDir();
-//=> '/home/user'
+import { downloads, configDir, projectDirs, ensureDir } from "os-user-dirs";
 
+// User directories
 downloads();
 //=> '/home/user/Downloads'
 
-desktop();
-//=> '/home/user/Desktop'
-
-templates();
-//=> '/home/user/Templates'
-
-publicshare();
-//=> '/home/user/Public'
-
-getPath("music");
-//=> '/home/user/Music'
-```
-
-#### Base directories
-
-```javascript
-import { configDir, dataDir, cacheDir, stateDir, logDir, runtimeDir, getBasePath } from "os-user-dirs";
-
+// XDG base directories
 configDir();
 //=> '/home/user/.config'
 
-dataDir();
-//=> '/home/user/.local/share'
-
-cacheDir();
-//=> '/home/user/.cache'
-
-stateDir();
-//=> '/home/user/.local/state'
-
-logDir();
-//=> '/home/user/.local/state' (Linux), '~/Library/Logs' (macOS)
-
-runtimeDir();
-//=> '/run/user/1000' (or null)
-
-getBasePath("config");
-//=> '/home/user/.config'
-```
-
-#### System search directories
-
-```javascript
-import { configDirs, dataDirs } from "os-user-dirs";
-
-configDirs();
-//=> ['/etc/xdg'] (Linux)
-//=> ['/Library/Application Support', '/Library/Preferences'] (macOS)
-//=> ['C:\\ProgramData'] (Windows)
-
-dataDirs();
-//=> ['/usr/local/share', '/usr/share'] (Linux)
-//=> ['/Library/Application Support'] (macOS)
-//=> ['C:\\ProgramData'] (Windows)
-```
-
-#### Project directories
-
-```javascript
-import { projectDirs } from "os-user-dirs";
-
+// App-scoped project directories (env-paths alternative)
 const dirs = projectDirs("my-app");
 dirs.config  //=> '/home/user/.config/my-app'
 dirs.data    //=> '/home/user/.local/share/my-app'
 dirs.cache   //=> '/home/user/.cache/my-app'
-dirs.state   //=> '/home/user/.local/state/my-app'
-dirs.log     //=> '/home/user/.local/state/my-app'
-dirs.temp    //=> '/tmp/my-app'
-dirs.runtime //=> '/run/user/1000/my-app' (or null)
-
-// With suffix option
-const dirs2 = projectDirs("my-app", { suffix: "-nodejs" });
-dirs2.config //=> '/home/user/.config/my-app-nodejs'
-
-// With vendor option
-const dirs3 = projectDirs("my-app", { vendor: "My Org" });
-dirs3.config //=> '/home/user/.config/my-org/my-app' (Linux)
-dirs3.config //=> '~/Library/Application Support/My Org/my-app' (macOS)
-```
-
-#### Project user directories
 
-```javascript
-import { projectUserDirs } from "os-user-dirs";
-
-const dirs = projectUserDirs("my-app");
-dirs.desktop     //=> '/home/user/Desktop/my-app'
-dirs.downloads   //=> '/home/user/Downloads/my-app'
-dirs.documents   //=> '/home/user/Documents/my-app'
-dirs.music       //=> '/home/user/Music/my-app'
-dirs.pictures    //=> '/home/user/Pictures/my-app'
-dirs.videos      //=> '/home/user/Videos/my-app'
-dirs.templates   //=> '/home/user/Templates/my-app'
-dirs.publicshare //=> '/home/user/Public/my-app'
-```
-
-### CommonJS
-
-```javascript
-const { downloads, desktop, documents, music, pictures, videos, templates, publicshare, getPath } = require("os-user-dirs");
-
-downloads();
-//=> '/home/user/Downloads'
+// Ensure directory exists before use
+await ensureDir(dirs.config);
 ```
 
-### Default export (backward compatibility)
+CommonJS is also supported:
 
 ```javascript
-// ESM
-import downloads from "os-user-dirs";
-
-// CommonJS
-const downloads = require("os-user-dirs");
-
-downloads();
-//=> '/home/user/Downloads'
+const { downloads, configDir, projectDirs } = require("os-user-dirs");
 ```
 
 ### TypeScript
@@ -166,6 +83,8 @@ getPath("unknown");    // Type error
 
 ## API
 
+> For detailed API documentation with platform-specific behavior, environment variables, and edge cases, see the **[API Reference](docs/api.md)**.
+
 ### `downloads()`
 Returns the path to the Downloads directory.
 
@@ -237,59 +156,135 @@ Returns the path to the user fonts directory (`~/.local/share/fonts` on Linux, `
 #### `getBasePath(name)`
 Returns the path to the specified base directory. Valid names: `config`, `data`, `cache`, `state`, `log`, `runtime`.
 
+## Which function should I use?
+
+| Use case | Function |
+|---|---|
+| Store app config files | `configDir()` or `projectDirs("my-app").config` |
+| Store app data / databases | `dataDir()` or `projectDirs("my-app").data` |
+| Store app cache | `cacheDir()` or `projectDirs("my-app").cache` |
+| Store app logs | `logDir()` or `projectDirs("my-app").log` |
+| Get user's Downloads folder | `downloads()` |
+| Get user's Documents folder | `documents()` |
+| Get all app-scoped dirs at once | `projectDirs("my-app")` |
+| Find system-wide config locations | `configDirs()` |
+| Ensure a directory exists | `ensureDir(path)` / `ensureDirSync(path)` |
+| Get user's home directory | `homeDir()` |
+
+> For the full API with platform-specific details, see the **[API Reference](docs/api.md)**.
+
+## API Overview
+
+### User Directories
+
+| Function | Description |
+|---|---|
+| `downloads()` | Downloads directory |
+| `desktop()` | Desktop directory |
+| `documents()` | Documents directory |
+| `music()` | Music directory |
+| `pictures()` | Pictures directory |
+| `videos()` | Videos directory (Movies on macOS) |
+| `templates()` | Templates directory |
+| `publicshare()` | Public Share directory |
+| `homeDir()` | Home directory |
+| `getPath(name)` | Get user directory by name |
+
+### Base Directories (XDG)
+
+| Function | Linux | macOS | Windows |
+|---|---|---|---|
+| `configDir()` | `~/.config` | `~/Library/Application Support` | `%APPDATA%` |
+| `dataDir()` | `~/.local/share` | `~/Library/Application Support` | `%LOCALAPPDATA%` |
+| `cacheDir()` | `~/.cache` | `~/Library/Caches` | `%LOCALAPPDATA%` |
+| `stateDir()` | `~/.local/state` | `~/Library/Application Support` | `%LOCALAPPDATA%` |
+| `logDir()` | `~/.local/state` | `~/Library/Logs` | `%LOCALAPPDATA%` |
+| `runtimeDir()` | `$XDG_RUNTIME_DIR` | `null` | `null` |
+| `getBasePath(name)` | Get base directory by name | | |
+
 ### System Search Directories
 
-#### `configDirs()`
-Returns the system config directory search path list (`string[]`). On Linux, reads `$XDG_CONFIG_DIRS` (default: `["/etc/xdg"]`). On macOS: `["/Library/Application Support", "/Library/Preferences"]`. On Windows: `[%PROGRAMDATA%]`.
+| Function | Linux | macOS | Windows |
+|---|---|---|---|
+| `configDirs()` | `$XDG_CONFIG_DIRS` | `["/Library/Application Support", "/Library/Preferences"]` | `[%PROGRAMDATA%]` |
+| `dataDirs()` | `$XDG_DATA_DIRS` | `["/Library/Application Support"]` | `[%PROGRAMDATA%]` |
+
+### Additional Directories
 
-#### `dataDirs()`
-Returns the system data directory search path list (`string[]`). On Linux, reads `$XDG_DATA_DIRS` (default: `["/usr/local/share", "/usr/share"]`). On macOS: `["/Library/Application Support"]`. On Windows: `[%PROGRAMDATA%]`.
+| Function | Linux | macOS | Windows |
+|---|---|---|---|
+| `fontsDir()` | `~/.local/share/fonts` | `~/Library/Fonts` | `%LOCALAPPDATA%/Microsoft/Windows/Fonts` |
+| `binDir()` | `~/.local/bin` | `~/.local/bin` | `null` |
+| `applicationsDir()` | `~/.local/share/applications` | `~/Applications` | Start Menu |
+| `trashDir()` | `~/.local/share/Trash` | `~/.Trash` | `null` |
 
 ### Project Directories
 
-#### `projectDirs(name, options?)`
-Returns an object with app-scoped directories for the given application name. This is a zero-dependency alternative to [`env-paths`](https://github.com/sindresorhus/env-paths).
+```javascript
+import { projectDirs } from "os-user-dirs";
 
-**Parameters:**
-- `name` (string) — Application name
-- `options.suffix` (string, optional) — Suffix appended to the app name (e.g. `"-nodejs"`)
-- `options.vendor` (string, optional) — Vendor/organization name used as a parent directory. On Linux, the vendor name is normalized to lowercase with spaces replaced by hyphens (e.g. `"My Org"` → `"my-org"`). On macOS and Windows, it is used as-is.
+// Basic usage
+const dirs = projectDirs("my-app");
+// => { config, data, cache, state, log, temp, runtime }
 
-**Returns:** `{ config, data, cache, state, log, temp, runtime }`
+// With vendor (organization) prefix
+const dirs2 = projectDirs("my-app", { vendor: "My Org" });
+dirs2.config //=> '~/.config/my-org/my-app' (Linux)
 
-On Windows, each directory uses a subdirectory structure (e.g. `%LOCALAPPDATA%/my-app/Config`, `%LOCALAPPDATA%/my-app/Data`).
+// With suffix
+const dirs3 = projectDirs("my-app", { suffix: "-nodejs" });
+dirs3.config //=> '~/.config/my-app-nodejs'
+```
 
-#### `projectUserDirs(name)`
-Returns an object with project-scoped user directories. Each value is the corresponding user directory with the app name appended as a subdirectory.
+### Project User Directories
 
-**Parameters:**
-- `name` (string) — Application name
+```javascript
+import { projectUserDirs } from "os-user-dirs";
 
-**Returns:** `{ desktop, downloads, documents, music, pictures, videos, templates, publicshare }`
+const dirs = projectUserDirs("my-app");
+// => { desktop, downloads, documents, music, pictures, videos, templates, publicshare }
+dirs.downloads //=> '/home/user/Downloads/my-app'
+```
 
 ### Utilities
 
-#### `ensureDirSync(dirPath)`
-Ensures the specified directory exists, creating it recursively if necessary. Returns the directory path.
+| Function | Description |
+|---|---|
+| `ensureDirSync(dirPath)` | Creates directory recursively if needed (sync) |
+| `ensureDir(dirPath)` | Creates directory recursively if needed (async) |
+| `getXDGUserDir(key)` | Parse XDG user-dirs.dirs config |
 
-#### `ensureDir(dirPath)`
-Async version of `ensureDirSync`. Returns a promise that resolves with the directory path.
+## TypeScript
 
-```javascript
-import { projectDirs, ensureDirSync, ensureDir } from "os-user-dirs";
+Full type definitions are included. `getPath()` and `getBasePath()` accept union types for auto-completion:
 
-const dirs = projectDirs("my-app");
+```typescript
+import { getPath, getBasePath } from "os-user-dirs";
 
-// Sync
-ensureDirSync(dirs.config);
+getPath("downloads");   // OK — type: string
+getPath("unknown");     // Type error
 
-// Async
-await ensureDir(dirs.data);
+getBasePath("config");  // OK — type: string
+getBasePath("unknown"); // Type error
 ```
 
-## Migration from env-paths
+## Integration guides
+
+- **[Electron Guide](docs/guide-electron.md)** — Using os-user-dirs in Electron apps: `app.getPath()` mapping, main/renderer process patterns, vendor-scoped directories
+- **[CLI Tools Guide](docs/guide-cli-tools.md)** — Using `projectDirs()` with commander, yargs, and oclif for config, cache, and log management
+
+## Migration Guides
+
+Switching from another library? We have you covered:
+
+- **[From xdg-basedir](docs/migration-from-xdg-basedir.md)** — API mapping, code examples (v4 CJS and v5 ESM), cross-platform benefits
+- **[From env-paths](docs/migration-from-env-paths.md)** — API mapping, code examples, additional features summary
+
+## Documentation
 
-Switching from [env-paths](https://github.com/sindresorhus/env-paths)? See the **[Migration Guide](docs/migration-from-env-paths.md)** for API mapping, code examples, and a summary of additional features.
+- [API Reference](docs/api.md) — Detailed documentation for all functions
+- [Migration from xdg-basedir](docs/migration-from-xdg-basedir.md)
+- [Migration from env-paths](docs/migration-from-env-paths.md)
 
 ## Migration from v2.x
 

package/index.d.ts

@@ -1,59 +1,237 @@
 type DirName = "desktop" | "downloads" | "documents" | "music" | "pictures" | "videos" | "templates" | "publicshare";
 
-/** Returns the path to the Desktop directory. */
+/**
+ * Returns the path to the Desktop directory.
+ * @example
+ * ```ts
+ * import { desktop } from 'os-user-dirs';
+ * const dir = desktop();
+ * // Linux:   '/home/user/Desktop'
+ * // macOS:   '/Users/user/Desktop'
+ * // Windows: 'C:\\Users\\user\\Desktop'
+ * ```
+ */
 export function desktop(): string;
 
-/** Returns the path to the Downloads directory. */
+/**
+ * Returns the path to the Downloads directory.
+ * @example
+ * ```ts
+ * import { downloads } from 'os-user-dirs';
+ * const dir = downloads();
+ * // Linux:   '/home/user/Downloads'
+ * // macOS:   '/Users/user/Downloads'
+ * // Windows: 'C:\\Users\\user\\Downloads'
+ * ```
+ */
 export function downloads(): string;
 
-/** Returns the path to the Documents directory. */
+/**
+ * Returns the path to the Documents directory.
+ * @example
+ * ```ts
+ * import { documents } from 'os-user-dirs';
+ * const dir = documents();
+ * // Linux:   '/home/user/Documents'
+ * // macOS:   '/Users/user/Documents'
+ * // Windows: 'C:\\Users\\user\\Documents'
+ * ```
+ */
 export function documents(): string;
 
-/** Returns the path to the Music directory. */
+/**
+ * Returns the path to the Music directory.
+ * @example
+ * ```ts
+ * import { music } from 'os-user-dirs';
+ * const dir = music();
+ * // Linux:   '/home/user/Music'
+ * // macOS:   '/Users/user/Music'
+ * // Windows: 'C:\\Users\\user\\Music'
+ * ```
+ */
 export function music(): string;
 
-/** Returns the path to the Pictures directory. */
+/**
+ * Returns the path to the Pictures directory.
+ * @example
+ * ```ts
+ * import { pictures } from 'os-user-dirs';
+ * const dir = pictures();
+ * // Linux:   '/home/user/Pictures'
+ * // macOS:   '/Users/user/Pictures'
+ * // Windows: 'C:\\Users\\user\\Pictures'
+ * ```
+ */
 export function pictures(): string;
 
-/** Returns the path to the Videos directory (Movies on macOS). */
+/**
+ * Returns the path to the Videos directory (Movies on macOS).
+ * @example
+ * ```ts
+ * import { videos } from 'os-user-dirs';
+ * const dir = videos();
+ * // Linux:   '/home/user/Videos'
+ * // macOS:   '/Users/user/Movies'
+ * // Windows: 'C:\\Users\\user\\Videos'
+ * ```
+ */
 export function videos(): string;
 
-/** Returns the path to the Templates directory. */
+/**
+ * Returns the path to the Templates directory.
+ * @example
+ * ```ts
+ * import { templates } from 'os-user-dirs';
+ * const dir = templates();
+ * // Linux:   '/home/user/Templates'
+ * // macOS:   '/Users/user/Templates'
+ * // Windows: 'C:\\Users\\user\\Templates'
+ * ```
+ */
 export function templates(): string;
 
-/** Returns the path to the Public Share directory. */
+/**
+ * Returns the path to the Public Share directory.
+ * @example
+ * ```ts
+ * import { publicshare } from 'os-user-dirs';
+ * const dir = publicshare();
+ * // Linux:   '/home/user/Public'
+ * // macOS:   '/Users/user/Public'
+ * // Windows: 'C:\\Users\\user\\Public'
+ * ```
+ */
 export function publicshare(): string;
 
-/** Returns the path to the specified user directory. */
+/**
+ * Returns the path to the specified user directory.
+ * @param name - Directory name to resolve
+ * @example
+ * ```ts
+ * import { getPath } from 'os-user-dirs';
+ * const dir = getPath('downloads'); // '/home/user/Downloads'
+ * const dir2 = getPath('desktop');  // '/home/user/Desktop'
+ * ```
+ */
 export function getPath(name: DirName): string;
 
-/** Returns the path to the user's home directory. */
+/**
+ * Returns the path to the user's home directory.
+ * @example
+ * ```ts
+ * import { homeDir } from 'os-user-dirs';
+ * const dir = homeDir();
+ * // Linux:   '/home/user'
+ * // macOS:   '/Users/user'
+ * // Windows: 'C:\\Users\\user'
+ * ```
+ */
 export function homeDir(): string;
 
-/** Returns the path to the user local bin directory (~/.local/bin), or null on Windows. */
+/**
+ * Returns the path to the user local bin directory (~/.local/bin), or null on Windows.
+ * @example
+ * ```ts
+ * import { binDir } from 'os-user-dirs';
+ * const dir = binDir();
+ * // Linux/macOS: '/home/user/.local/bin'
+ * // Windows:     null
+ * ```
+ */
 export function binDir(): string | null;
 
 type BaseDirName = "config" | "data" | "cache" | "state" | "log" | "runtime";
 
-/** Returns the path to the XDG config directory. */
+/**
+ * Returns the path to the XDG config directory.
+ * @example
+ * ```ts
+ * import { configDir } from 'os-user-dirs';
+ * const dir = configDir();
+ * // Linux:   '/home/user/.config'
+ * // macOS:   '/Users/user/Library/Application Support'
+ * // Windows: 'C:\\Users\\user\\AppData\\Roaming'
+ * ```
+ */
 export function configDir(): string;
 
-/** Returns the path to the XDG data directory. */
+/**
+ * Returns the path to the XDG data directory.
+ * @example
+ * ```ts
+ * import { dataDir } from 'os-user-dirs';
+ * const dir = dataDir();
+ * // Linux:   '/home/user/.local/share'
+ * // macOS:   '/Users/user/Library/Application Support'
+ * // Windows: 'C:\\Users\\user\\AppData\\Local'
+ * ```
+ */
 export function dataDir(): string;
 
-/** Returns the path to the XDG cache directory. */
+/**
+ * Returns the path to the XDG cache directory.
+ * @example
+ * ```ts
+ * import { cacheDir } from 'os-user-dirs';
+ * const dir = cacheDir();
+ * // Linux:   '/home/user/.cache'
+ * // macOS:   '/Users/user/Library/Caches'
+ * // Windows: 'C:\\Users\\user\\AppData\\Local'
+ * ```
+ */
 export function cacheDir(): string;
 
-/** Returns the path to the XDG state directory. */
+/**
+ * Returns the path to the XDG state directory.
+ * @example
+ * ```ts
+ * import { stateDir } from 'os-user-dirs';
+ * const dir = stateDir();
+ * // Linux:   '/home/user/.local/state'
+ * // macOS:   '/Users/user/Library/Application Support'
+ * // Windows: 'C:\\Users\\user\\AppData\\Local'
+ * ```
+ */
 export function stateDir(): string;
 
-/** Returns the path to the log directory. */
+/**
+ * Returns the path to the log directory.
+ * @example
+ * ```ts
+ * import { logDir } from 'os-user-dirs';
+ * const dir = logDir();
+ * // Linux:   '/home/user/.local/state'
+ * // macOS:   '/Users/user/Library/Logs'
+ * // Windows: 'C:\\Users\\user\\AppData\\Local'
+ * ```
+ */
 export function logDir(): string;
 
-/** Returns the path to the XDG runtime directory, or null if unavailable. */
+/**
+ * Returns the path to the XDG runtime directory, or null if unavailable.
+ * @example
+ * ```ts
+ * import { runtimeDir } from 'os-user-dirs';
+ * const dir = runtimeDir();
+ * // Linux:   '/run/user/1000' (if $XDG_RUNTIME_DIR is set)
+ * // macOS:   null
+ * // Windows: null
+ * ```
+ */
 export function runtimeDir(): string | null;
 
-/** Returns the path to the user fonts directory. */
+/**
+ * Returns the path to the user fonts directory.
+ * @example
+ * ```ts
+ * import { fontsDir } from 'os-user-dirs';
+ * const dir = fontsDir();
+ * // Linux:   '/home/user/.local/share/fonts'
+ * // macOS:   '/Users/user/Library/Fonts'
+ * // Windows: 'C:\\Users\\user\\AppData\\Local\\Microsoft\\Windows\\Fonts'
+ * ```
+ */
 export function fontsDir(): string;
 
 /**
@@ -61,6 +239,14 @@ export function fontsDir(): string;
  * On Linux, reads `$XDG_CONFIG_DIRS` (default: `["/etc/xdg"]`).
  * On macOS: `["/Library/Application Support", "/Library/Preferences"]`.
  * On Windows: `[%PROGRAMDATA%]`.
+ * @example
+ * ```ts
+ * import { configDirs } from 'os-user-dirs';
+ * const dirs = configDirs();
+ * // Linux:   ['/etc/xdg']
+ * // macOS:   ['/Library/Application Support', '/Library/Preferences']
+ * // Windows: ['C:\\ProgramData']
+ * ```
  */
 export function configDirs(): string[];
 
@@ -69,10 +255,28 @@ export function configDirs(): string[];
  * On Linux, reads `$XDG_DATA_DIRS` (default: `["/usr/local/share", "/usr/share"]`).
  * On macOS: `["/Library/Application Support"]`.
  * On Windows: `[%PROGRAMDATA%]`.
+ * @example
+ * ```ts
+ * import { dataDirs } from 'os-user-dirs';
+ * const dirs = dataDirs();
+ * // Linux:   ['/usr/local/share', '/usr/share']
+ * // macOS:   ['/Library/Application Support']
+ * // Windows: ['C:\\ProgramData']
+ * ```
  */
 export function dataDirs(): string[];
 
-/** Returns the path to the specified base directory. */
+/**
+ * Returns the path to the specified base directory.
+ * @param name - Base directory name to resolve
+ * @example
+ * ```ts
+ * import { getBasePath } from 'os-user-dirs';
+ * const config = getBasePath('config');  // '/home/user/.config'
+ * const data = getBasePath('data');      // '/home/user/.local/share'
+ * const runtime = getBasePath('runtime'); // '/run/user/1000' or null
+ * ```
+ */
 export function getBasePath(name: "config"): string;
 export function getBasePath(name: "data"): string;
 export function getBasePath(name: "cache"): string;
@@ -101,7 +305,29 @@ interface ProjectDirsResult {
 /**
  * Returns application-scoped directories for the given app name.
  * @param name - Application name used to derive directory paths
- * @param options - Optional settings (e.g. suffix)
+ * @param options - Optional settings (e.g. vendor, suffix)
+ * @example
+ * ```ts
+ * import { projectDirs } from 'os-user-dirs';
+ * const dirs = projectDirs('my-app');
+ * // Linux:   dirs.config => '/home/user/.config/my-app'
+ * // macOS:   dirs.config => '/Users/user/Library/Application Support/my-app'
+ * // Windows: dirs.config => 'C:\\Users\\user\\AppData\\Local\\my-app\\Config'
+ * ```
+ * @example
+ * ```ts
+ * // With vendor option
+ * const dirs = projectDirs('my-app', { vendor: 'My Org' });
+ * // Linux:   dirs.config => '/home/user/.config/my-org/my-app'
+ * // macOS:   dirs.config => '/Users/user/Library/Application Support/My Org/my-app'
+ * // Windows: dirs.config => 'C:\\Users\\user\\AppData\\Local\\My Org\\my-app\\Config'
+ * ```
+ * @example
+ * ```ts
+ * // With suffix option
+ * const dirs = projectDirs('my-app', { suffix: '-beta' });
+ * // Linux:   dirs.config => '/home/user/.config/my-app-beta'
+ * ```
  */
 export function projectDirs(name: string, options?: ProjectDirsOptions): ProjectDirsResult;
 
@@ -120,6 +346,14 @@ interface ProjectUserDirsResult {
  * Returns project-scoped user directories for the given app name.
  * Each value is the user directory path with the app name appended as a subdirectory.
  * @param name - Application name used to derive directory paths
+ * @example
+ * ```ts
+ * import { projectUserDirs } from 'os-user-dirs';
+ * const dirs = projectUserDirs('my-app');
+ * // dirs.downloads => '/home/user/Downloads/my-app'
+ * // dirs.documents => '/home/user/Documents/my-app'
+ * // dirs.desktop   => '/home/user/Desktop/my-app'
+ * ```
  */
 export function projectUserDirs(name: string): ProjectUserDirsResult;
 
@@ -128,6 +362,14 @@ export function projectUserDirs(name: string): ProjectUserDirsResult;
  * Linux: `$XDG_DATA_HOME/Trash` (default `~/.local/share/Trash`)
  * macOS: `~/.Trash`
  * Windows: `null` (Recycle Bin requires Shell API)
+ * @example
+ * ```ts
+ * import { trashDir } from 'os-user-dirs';
+ * const dir = trashDir();
+ * // Linux:   '/home/user/.local/share/Trash'
+ * // macOS:   '/Users/user/.Trash'
+ * // Windows: null
+ * ```
  */
 export function trashDir(): string | null;
 
@@ -136,6 +378,14 @@ export function trashDir(): string | null;
  * Linux: `$XDG_DATA_HOME/applications` (default `~/.local/share/applications`)
  * macOS: `~/Applications`
  * Windows: `%APPDATA%/Microsoft/Windows/Start Menu/Programs`
+ * @example
+ * ```ts
+ * import { applicationsDir } from 'os-user-dirs';
+ * const dir = applicationsDir();
+ * // Linux:   '/home/user/.local/share/applications'
+ * // macOS:   '/Users/user/Applications'
+ * // Windows: 'C:\\Users\\user\\AppData\\Roaming\\Microsoft\\Windows\\Start Menu\\Programs'
+ * ```
  */
 export function applicationsDir(): string;
 
@@ -144,6 +394,12 @@ export function applicationsDir(): string;
  * @param key - XDG key (e.g. "XDG_DOWNLOAD_DIR")
  * @param configPath - Optional path to user-dirs.dirs config file
  * @returns The resolved directory path, or null if not found
+ * @example
+ * ```ts
+ * import { getXDGUserDir } from 'os-user-dirs';
+ * const dir = getXDGUserDir('XDG_DOWNLOAD_DIR'); // '/home/user/Downloads'
+ * const dir2 = getXDGUserDir('XDG_DESKTOP_DIR'); // '/home/user/Desktop'
+ * ```
  */
 export function getXDGUserDir(key: string, configPath?: string): string | null;
 
@@ -151,6 +407,12 @@ export function getXDGUserDir(key: string, configPath?: string): string | null;
  * Ensures the specified directory exists, creating it recursively if necessary.
  * @param dirPath - The directory path to ensure exists
  * @returns The directory path
+ * @example
+ * ```ts
+ * import { ensureDirSync, configDir } from 'os-user-dirs';
+ * const dir = ensureDirSync(configDir() + '/my-app');
+ * // Creates the directory if it doesn't exist and returns the path
+ * ```
  */
 export function ensureDirSync(dirPath: string): string;
 
@@ -158,6 +420,12 @@ export function ensureDirSync(dirPath: string): string;
  * Ensures the specified directory exists, creating it recursively if necessary (async version).
  * @param dirPath - The directory path to ensure exists
  * @returns A promise that resolves with the directory path
+ * @example
+ * ```ts
+ * import { ensureDir, cacheDir } from 'os-user-dirs';
+ * const dir = await ensureDir(cacheDir() + '/my-app');
+ * // Creates the directory if it doesn't exist and returns the path
+ * ```
  */
 export function ensureDir(dirPath: string): Promise<string>;
 

package/index.js

@@ -152,11 +152,11 @@ function logDir() { return resolveBase("log"); }
 function runtimeDir() { return resolveBase("runtime"); }
 
 function fontsDir() {
-    var platform = process.platform;
-    var homedir = os.homedir();
+    const platform = process.platform;
+    const homedir = os.homedir();
 
     if (platform === "linux") {
-        var envVal = process.env.XDG_DATA_HOME;
+        const envVal = process.env.XDG_DATA_HOME;
         if (envVal) {
             return path.join(path.resolve(envVal), "fonts");
         }
@@ -168,7 +168,7 @@ function fontsDir() {
     }
 
     if (platform === "win32") {
-        var localAppData = process.env.LOCALAPPDATA || path.join(homedir, "AppData", "Local");
+        const localAppData = process.env.LOCALAPPDATA || path.join(homedir, "AppData", "Local");
         return path.join(localAppData, "Microsoft", "Windows", "Fonts");
     }
 
@@ -262,7 +262,7 @@ function projectDirs(name, options) {
     const vendorDir = vendor ? normalizeVendor(vendor, platform) : "";
 
     function joinWithVendor() {
-        var segments = Array.prototype.slice.call(arguments);
+        const segments = Array.prototype.slice.call(arguments);
         if (vendorDir) {
             segments.splice(1, 0, vendorDir);
         }
@@ -315,21 +315,21 @@ function projectUserDirs(name) {
         throw new Error("projectUserDirs requires a non-empty string name");
     }
 
-    var result = {};
-    var keys = Object.keys(XDG_KEYS);
-    for (var i = 0; i < keys.length; i++) {
+    const result = {};
+    const keys = Object.keys(XDG_KEYS);
+    for (let i = 0; i < keys.length; i++) {
         result[keys[i]] = path.join(resolve(keys[i]), name);
     }
     return result;
 }
 
 function trashDir() {
-    var platform = process.platform;
-    var homedir = os.homedir();
+    const platform = process.platform;
+    const homedir = os.homedir();
 
     if (platform === "linux") {
-        var envVal = process.env.XDG_DATA_HOME;
-        var base = envVal ? path.resolve(envVal) : path.join(homedir, ".local", "share");
+        const envVal = process.env.XDG_DATA_HOME;
+        const base = envVal ? path.resolve(envVal) : path.join(homedir, ".local", "share");
         return path.join(base, "Trash");
     }
 
@@ -342,18 +342,18 @@ function trashDir() {
     }
 
     // Unknown platform: use XDG-style default
-    var envVal = process.env.XDG_DATA_HOME;
-    var base = envVal ? path.resolve(envVal) : path.join(homedir, ".local", "share");
+    const envVal = process.env.XDG_DATA_HOME;
+    const base = envVal ? path.resolve(envVal) : path.join(homedir, ".local", "share");
     return path.join(base, "Trash");
 }
 
 function applicationsDir() {
-    var homedir = os.homedir();
-    var platform = process.platform;
+    const homedir = os.homedir();
+    const platform = process.platform;
 
     if (platform === "linux") {
-        var envVal = process.env.XDG_DATA_HOME;
-        var base = envVal ? path.resolve(envVal) : path.join(homedir, ".local", "share");
+        const envVal = process.env.XDG_DATA_HOME;
+        const base = envVal ? path.resolve(envVal) : path.join(homedir, ".local", "share");
         return path.join(base, "applications");
     }
 
@@ -362,7 +362,7 @@ function applicationsDir() {
     }
 
     if (platform === "win32") {
-        var appdata = process.env.APPDATA || path.join(homedir, "AppData", "Roaming");
+        const appdata = process.env.APPDATA || path.join(homedir, "AppData", "Roaming");
         return path.join(appdata, "Microsoft", "Windows", "Start Menu", "Programs");
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "os-user-dirs",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Get OS-specific user directories and XDG base directories (config, data, cache, runtime) with zero dependencies.",
   "main": "index.js",
   "types": "index.d.ts",
@@ -17,7 +17,8 @@
     "index.d.ts"
   ],
   "scripts": {
-    "test": "mocha test.js"
+    "test": "mocha test.js",
+    "coverage": "c8 --all mocha test.js"
   },
   "repository": {
     "type": "git",
@@ -26,6 +27,8 @@
   "keywords": [
     "os",
     "directories",
+    "user-dirs",
+    "user-directories",
     "downloads",
     "desktop",
     "documents",
@@ -34,12 +37,40 @@
     "videos",
     "templates",
     "public",
+    "home-dir",
     "config",
     "data",
     "cache",
+    "state",
+    "runtime",
     "xdg",
-    "user-dirs",
-    "platform-folders"
+    "xdg-basedir",
+    "xdg-base-directory",
+    "freedesktop",
+    "config-dir",
+    "data-dir",
+    "cache-dir",
+    "state-dir",
+    "runtime-dir",
+    "log-dir",
+    "downloads-dir",
+    "desktop-dir",
+    "fonts-dir",
+    "trash-dir",
+    "project-dirs",
+    "app-paths",
+    "env-paths",
+    "platform-folders",
+    "appdata-path",
+    "cross-platform",
+    "linux",
+    "macos",
+    "windows",
+    "zero-dependencies",
+    "cjs",
+    "esm",
+    "dual-module",
+    "typescript"
   ],
   "author": "piroz",
   "license": "MIT",
@@ -47,10 +78,29 @@
     "url": "https://github.com/velocitylabo/os-user-dirs/issues"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "homepage": "https://github.com/velocitylabo/os-user-dirs#readme",
+  "c8": {
+    "all": true,
+    "src": [
+      "."
+    ],
+    "include": [
+      "index.js"
+    ],
+    "reporter": [
+      "text",
+      "lcov"
+    ],
+    "check-coverage": true,
+    "branches": 80,
+    "lines": 75,
+    "functions": 100,
+    "statements": 75
+  },
   "devDependencies": {
+    "c8": "^11.0.0",
     "mocha": "^11.7.5"
   }
 }