os-user-dirs 2.7.0 → 3.0.1

package/README.md

@@ -1,14 +1,33 @@
-# 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)
+[![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.
+
+- Node.js 20 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
 
@@ -16,132 +35,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 } from "os-user-dirs";
+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
@@ -159,6 +81,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.
 
@@ -186,9 +110,18 @@ Returns the path to the Public Share directory.
 ### `getPath(name)`
 Returns the path to the specified user directory. Valid names: `desktop`, `downloads`, `documents`, `music`, `pictures`, `videos`, `templates`, `publicshare`.
 
+### `homeDir()`
+Returns the path to the user's home directory. Uses `os.homedir()` internally.
+
 ### `binDir()`
 Returns the path to the user local bin directory (`~/.local/bin` on Linux/macOS), or `null` on Windows.
 
+### `trashDir()`
+Returns the path to the user trash directory, or `null` on Windows.
+- Linux: `$XDG_DATA_HOME/Trash` (default `~/.local/share/Trash`) — FreeDesktop Trash spec
+- macOS: `~/.Trash`
+- Windows: `null` (Recycle Bin requires Shell API)
+
 ### `applicationsDir()`
 Returns the path to the user applications directory.
 - Linux: `$XDG_DATA_HOME/applications` (default `~/.local/share/applications`)
@@ -220,36 +153,138 @@ 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`.
+## 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";
+
+// Basic usage
+const dirs = projectDirs("my-app");
+// => { 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)
+
+// With suffix
+const dirs3 = projectDirs("my-app", { suffix: "-nodejs" });
+dirs3.config //=> '~/.config/my-app-nodejs'
+```
+
+### Project User Directories
+
+```javascript
+import { projectUserDirs } from "os-user-dirs";
+
+const dirs = projectUserDirs("my-app");
+// => { desktop, downloads, documents, music, pictures, videos, templates, publicshare }
+dirs.downloads //=> '/home/user/Downloads/my-app'
+```
+
+### Utilities
+
+| 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 |
+
+## TypeScript
+
+Full type definitions are included. `getPath()` and `getBasePath()` accept union types for auto-completion:
+
+```typescript
+import { getPath, getBasePath } from "os-user-dirs";
+
+getPath("downloads");   // OK — type: string
+getPath("unknown");     // Type error
+
+getBasePath("config");  // OK — type: string
+getBasePath("unknown"); // Type error
+```
 
-**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.
+## Integration guides
 
-**Returns:** `{ config, data, cache, state, log, temp, runtime }`
+- **[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
 
-On Windows, each directory uses a subdirectory structure (e.g. `%LOCALAPPDATA%/my-app/Config`, `%LOCALAPPDATA%/my-app/Data`).
+## Migration from xdg-basedir
+## Migration Guides
 
-#### `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.
+Switching from another library? We have you covered:
 
-**Parameters:**
-- `name` (string) — Application name
+- **[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
 
-**Returns:** `{ desktop, downloads, documents, music, pictures, videos, templates, publicshare }`
+## Documentation
+
+- [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
+
+### `getXDGDownloadDir()` removed
+
+`getXDGDownloadDir()` was deprecated in v2.3.0 and has been removed in v3.0.0.
+
+**Before (v2.x):**
+```javascript
+const { getXDGDownloadDir } = require("os-user-dirs");
+getXDGDownloadDir(); // reads XDG user-dirs.dirs for download path
+```
+
+**After (v3.x):**
+```javascript
+const { downloads, getXDGUserDir } = require("os-user-dirs");
+downloads();                              // recommended: cross-platform Downloads path
+getXDGUserDir("XDG_DOWNLOAD_DIR");        // direct replacement if you need XDG config parsing
+```
 
 ## License
 

package/index.d.ts

@@ -1,56 +1,236 @@
 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
+ * ```js
+ * const { desktop } = require('os-user-dirs');
+ * console.log(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
+ * ```js
+ * const { downloads } = require('os-user-dirs');
+ * console.log(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
+ * ```js
+ * const { documents } = require('os-user-dirs');
+ * console.log(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
+ * ```js
+ * const { music } = require('os-user-dirs');
+ * console.log(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
+ * ```js
+ * const { pictures } = require('os-user-dirs');
+ * console.log(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
+ * ```js
+ * const { videos } = require('os-user-dirs');
+ * console.log(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
+ * ```js
+ * const { templates } = require('os-user-dirs');
+ * console.log(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
+ * ```js
+ * const { publicshare } = require('os-user-dirs');
+ * console.log(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.
+ * @example
+ * ```js
+ * const { getPath } = require('os-user-dirs');
+ * console.log(getPath('downloads')); // '/home/user/Downloads'
+ * console.log(getPath('desktop'));    // '/home/user/Desktop'
+ * ```
+ */
 export function getPath(name: DirName): string;
 
-/** Returns the path to the user local bin directory (~/.local/bin), or null on Windows. */
+/**
+ * Returns the path to the user's home directory.
+ * @example
+ * ```js
+ * const { homeDir } = require('os-user-dirs');
+ * console.log(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.
+ * @example
+ * ```js
+ * const { binDir } = require('os-user-dirs');
+ * console.log(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
+ * ```js
+ * const { configDir } = require('os-user-dirs');
+ * console.log(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
+ * ```js
+ * const { dataDir } = require('os-user-dirs');
+ * console.log(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
+ * ```js
+ * const { cacheDir } = require('os-user-dirs');
+ * console.log(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
+ * ```js
+ * const { stateDir } = require('os-user-dirs');
+ * console.log(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
+ * ```js
+ * const { logDir } = require('os-user-dirs');
+ * console.log(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
+ * ```js
+ * const { runtimeDir } = require('os-user-dirs');
+ * console.log(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
+ * ```js
+ * const { fontsDir } = require('os-user-dirs');
+ * console.log(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;
 
 /**
@@ -58,6 +238,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
+ * ```js
+ * const { configDirs } = require('os-user-dirs');
+ * console.log(configDirs());
+ * // Linux:   ['/etc/xdg']
+ * // macOS:   ['/Library/Application Support', '/Library/Preferences']
+ * // Windows: ['C:\ProgramData']
+ * ```
  */
 export function configDirs(): string[];
 
@@ -66,10 +254,27 @@ 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
+ * ```js
+ * const { dataDirs } = require('os-user-dirs');
+ * console.log(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.
+ * @example
+ * ```js
+ * const { getBasePath } = require('os-user-dirs');
+ * console.log(getBasePath('config'));  // '/home/user/.config'
+ * console.log(getBasePath('data'));    // '/home/user/.local/share'
+ * console.log(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;
@@ -99,6 +304,23 @@ 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)
+ * @example
+ * ```js
+ * const { projectDirs } = require('os-user-dirs');
+ * const dirs = projectDirs('my-app');
+ * console.log(dirs.config); // Linux: '/home/user/.config/my-app'
+ * console.log(dirs.data);   // Linux: '/home/user/.local/share/my-app'
+ * console.log(dirs.cache);  // Linux: '/home/user/.cache/my-app'
+ * ```
+ * @example
+ * ```js
+ * // With vendor option
+ * const dirs = projectDirs('my-app', { vendor: 'My Org' });
+ * console.log(dirs.config);
+ * // Linux:   '/home/user/.config/my-org/my-app'
+ * // macOS:   '/Users/user/Library/Application Support/My Org/my-app'
+ * // Windows: 'C:\Users\user\AppData\Local\My Org\my-app\Config'
+ * ```
  */
 export function projectDirs(name: string, options?: ProjectDirsOptions): ProjectDirsResult;
 
@@ -117,14 +339,46 @@ 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
+ * ```js
+ * const { projectUserDirs } = require('os-user-dirs');
+ * const dirs = projectUserDirs('my-app');
+ * console.log(dirs.downloads); // '/home/user/Downloads/my-app'
+ * console.log(dirs.documents); // '/home/user/Documents/my-app'
+ * console.log(dirs.desktop);   // '/home/user/Desktop/my-app'
+ * ```
  */
 export function projectUserDirs(name: string): ProjectUserDirsResult;
 
+/**
+ * Returns the path to the user trash directory, or null on Windows.
+ * Linux: `$XDG_DATA_HOME/Trash` (default `~/.local/share/Trash`)
+ * macOS: `~/.Trash`
+ * Windows: `null` (Recycle Bin requires Shell API)
+ * @example
+ * ```js
+ * const { trashDir } = require('os-user-dirs');
+ * console.log(trashDir());
+ * // Linux:   '/home/user/.local/share/Trash'
+ * // macOS:   '/Users/user/.Trash'
+ * // Windows: null
+ * ```
+ */
+export function trashDir(): string | null;
+
 /**
  * Returns the path to the user applications directory.
  * Linux: `$XDG_DATA_HOME/applications` (default `~/.local/share/applications`)
  * macOS: `~/Applications`
  * Windows: `%APPDATA%/Microsoft/Windows/Start Menu/Programs`
+ * @example
+ * ```js
+ * const { applicationsDir } = require('os-user-dirs');
+ * console.log(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;
 
@@ -133,13 +387,40 @@ 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
+ * ```js
+ * const { getXDGUserDir } = require('os-user-dirs');
+ * console.log(getXDGUserDir('XDG_DOWNLOAD_DIR')); // '/home/user/Downloads'
+ * console.log(getXDGUserDir('XDG_DESKTOP_DIR'));   // '/home/user/Desktop'
+ * ```
  */
 export function getXDGUserDir(key: string, configPath?: string): string | null;
 
 /**
- * @deprecated Use `getXDGUserDir("XDG_DOWNLOAD_DIR", configPath)` instead.
+ * Ensures the specified directory exists, creating it recursively if necessary.
+ * @param dirPath - The directory path to ensure exists
+ * @returns The directory path
+ * @example
+ * ```js
+ * const { ensureDirSync } = require('os-user-dirs');
+ * const dir = ensureDirSync('/tmp/my-app/data');
+ * console.log(dir); // '/tmp/my-app/data'
+ * ```
+ */
+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
+ * ```js
+ * const { ensureDir } = require('os-user-dirs');
+ * const dir = await ensureDir('/tmp/my-app/data');
+ * console.log(dir); // '/tmp/my-app/data'
+ * ```
  */
-export function getXDGDownloadDir(configPath?: string): string | null;
+export function ensureDir(dirPath: string): Promise<string>;
 
 declare const osUserDirs: typeof downloads & {
     downloads: typeof downloads;
@@ -163,10 +444,13 @@ declare const osUserDirs: typeof downloads & {
     configDirs: typeof configDirs;
     dataDirs: typeof dataDirs;
     projectDirs: typeof projectDirs;
+    trashDir: typeof trashDir;
     applicationsDir: typeof applicationsDir;
     projectUserDirs: typeof projectUserDirs;
+    homeDir: typeof homeDir;
     getXDGUserDir: typeof getXDGUserDir;
-    getXDGDownloadDir: typeof getXDGDownloadDir;
+    ensureDirSync: typeof ensureDirSync;
+    ensureDir: typeof ensureDir;
 };
 
 export default osUserDirs;

package/index.js

@@ -1,6 +1,6 @@
-const path = require("path");
-const os = require("os");
-const fs = require("fs");
+const path = require("node:path");
+const os = require("node:os");
+const fs = require("node:fs");
 
 const XDG_KEYS = {
     desktop: "XDG_DESKTOP_DIR",
@@ -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,45 @@ 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() {
+    const platform = process.platform;
+    const homedir = os.homedir();
+
+    if (platform === "linux") {
+        const envVal = process.env.XDG_DATA_HOME;
+        const base = envVal ? path.resolve(envVal) : path.join(homedir, ".local", "share");
+        return path.join(base, "Trash");
+    }
+
+    if (platform === "darwin") {
+        return path.join(homedir, ".Trash");
+    }
+
+    if (platform === "win32") {
+        return null;
+    }
+
+    // Unknown platform: use XDG-style default
+    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");
     }
 
@@ -338,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");
     }
 
@@ -346,6 +370,27 @@ function applicationsDir() {
     return path.join(homedir, ".local", "share", "applications");
 }
 
+function homeDir() {
+    return os.homedir();
+}
+
+function ensureDirSync(dirPath) {
+    if (!dirPath || typeof dirPath !== "string") {
+        throw new Error("ensureDirSync requires a non-empty string path");
+    }
+    fs.mkdirSync(dirPath, { recursive: true });
+    return dirPath;
+}
+
+function ensureDir(dirPath) {
+    if (!dirPath || typeof dirPath !== "string") {
+        return Promise.reject(new Error("ensureDir requires a non-empty string path"));
+    }
+    return fs.promises.mkdir(dirPath, { recursive: true }).then(function () {
+        return dirPath;
+    });
+}
+
 // Backward compatibility: require("os-user-dirs")() returns Downloads path
 module.exports = downloads;
 module.exports.getPath = getPath;
@@ -371,9 +416,8 @@ module.exports.dataDirs = dataDirs;
 module.exports.projectDirs = projectDirs;
 module.exports.applicationsDir = applicationsDir;
 module.exports.projectUserDirs = projectUserDirs;
+module.exports.homeDir = homeDir;
 module.exports.getXDGUserDir = getXDGUserDir;
-
-// Deprecated: kept for backward compatibility
-module.exports.getXDGDownloadDir = function (configPath) {
-    return getXDGUserDir("XDG_DOWNLOAD_DIR", configPath);
-};
+module.exports.ensureDirSync = ensureDirSync;
+module.exports.trashDir = trashDir;
+module.exports.ensureDir = ensureDir;

package/index.mjs

@@ -24,5 +24,8 @@ export const dataDirs = osUserDirs.dataDirs;
 export const projectDirs = osUserDirs.projectDirs;
 export const applicationsDir = osUserDirs.applicationsDir;
 export const projectUserDirs = osUserDirs.projectUserDirs;
+export const homeDir = osUserDirs.homeDir;
 export const getXDGUserDir = osUserDirs.getXDGUserDir;
-export const getXDGDownloadDir = osUserDirs.getXDGDownloadDir;
+export const trashDir = osUserDirs.trashDir;
+export const ensureDirSync = osUserDirs.ensureDirSync;
+export const ensureDir = osUserDirs.ensureDir;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "os-user-dirs",
-  "version": "2.7.0",
+  "version": "3.0.1",
   "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",
@@ -39,15 +40,57 @@
     "cache",
     "xdg",
     "user-dirs",
-    "platform-folders"
+    "platform-folders",
+    "env-paths",
+    "xdg-basedir",
+    "appdata-path",
+    "xdg-base-directory",
+    "user-directories",
+    "app-paths",
+    "config-dir",
+    "data-dir",
+    "cache-dir",
+    "downloads-dir",
+    "desktop-dir",
+    "cross-platform",
+    "linux",
+    "macos",
+    "windows",
+    "zero-dependencies",
+    "cjs",
+    "esm",
+    "dual-module",
+    "typescript"
   ],
   "author": "piroz",
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/velocitylabo/os-user-dirs/issues"
   },
+  "engines": {
+    "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"
   }
 }