os-user-dirs 3.0.1 → 3.2.0

package/README.md

@@ -3,12 +3,14 @@
 [![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)
 
 > All-in-one OS directory paths — user directories, XDG base directories, and app-scoped project directories — with zero dependencies.
 
-- Node.js 20 or later
+- Node.js 20+, Deno 2+, Bun 1+
 
 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.
 
@@ -27,6 +29,7 @@ Replaces [`env-paths`](https://github.com/sindresorhus/env-paths), [`xdg-basedir
 | XDG search paths | **Yes** | - | **Yes** | - |
 | Project directories | **Yes** | **Yes** | - | - |
 | CJS + ESM | **Both** | ESM only (v3) | ESM only (v5) | CJS |
+| Deno / Bun | **Yes** | - | - | - |
 | TypeScript | **Included** | Included | Included | - |
 
 ## Install
@@ -35,7 +38,7 @@ Replaces [`env-paths`](https://github.com/sindresorhus/env-paths), [`xdg-basedir
 $ npm install os-user-dirs
 ```
 
-Requires Node.js 20 or later. Works on Windows, macOS, and Linux.
+Requires Node.js 20 or later. Works on Windows, macOS, and Linux. Also compatible with [Deno](https://deno.land/) and [Bun](https://bun.sh/).
 
 ## Quick Start
 
@@ -66,6 +69,25 @@ CommonJS is also supported:
 const { downloads, configDir, projectDirs } = require("os-user-dirs");
 ```
 
+### Deno
+
+```typescript
+import { downloads, configDir } from "npm:os-user-dirs";
+
+downloads();  //=> '/home/user/Downloads'
+configDir();  //=> '/home/user/.config'
+```
+
+### Bun
+
+```javascript
+import { downloads, configDir } from "os-user-dirs";
+// or: const { downloads, configDir } = require("os-user-dirs");
+
+downloads();  //=> '/home/user/Downloads'
+configDir();  //=> '/home/user/.config'
+```
+
 ### TypeScript
 
 Full type definitions are included. `getPath()` accepts a union type for auto-completion:
@@ -153,6 +175,25 @@ 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")` |
+| Dump all directory paths | `getAllDirs()` |
+| 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
@@ -226,10 +267,44 @@ const dirs = projectUserDirs("my-app");
 dirs.downloads //=> '/home/user/Downloads/my-app'
 ```
 
+### Namespace Exports
+
+For better organization, functions are also available via namespace objects:
+
+```javascript
+import { user, base, project } from "os-user-dirs";
+
+// User directories
+user.downloads()   //=> '/home/user/Downloads'
+user.desktop()     //=> '/home/user/Desktop'
+user.homeDir()     //=> '/home/user'
+
+// XDG base directories
+base.configDir()   //=> '/home/user/.config'
+base.dataDir()     //=> '/home/user/.local/share'
+base.configDirs()  //=> ['/etc/xdg']
+
+// Project directories
+const dirs = project.dirs("my-app");
+dirs.config  //=> '/home/user/.config/my-app'
+
+const userDirs = project.userDirs("my-app");
+userDirs.downloads  //=> '/home/user/Downloads/my-app'
+```
+
+| Namespace | Functions |
+|---|---|
+| `user` | `desktop`, `downloads`, `documents`, `music`, `pictures`, `videos`, `templates`, `publicshare`, `homeDir`, `binDir`, `fontsDir`, `trashDir`, `applicationsDir` |
+| `base` | `configDir`, `dataDir`, `cacheDir`, `stateDir`, `logDir`, `runtimeDir`, `configDirs`, `dataDirs` |
+| `project` | `dirs` (= `projectDirs`), `userDirs` (= `projectUserDirs`) |
+
+All flat exports remain available for backward compatibility.
+
 ### Utilities
 
 | Function | Description |
 |---|---|
+| `getAllDirs()` | Returns all directory paths as a single object |
 | `ensureDirSync(dirPath)` | Creates directory recursively if needed (sync) |
 | `ensureDir(dirPath)` | Creates directory recursively if needed (async) |
 | `getXDGUserDir(key)` | Parse XDG user-dirs.dirs config |
@@ -251,9 +326,10 @@ getBasePath("unknown"); // Type error
 ## 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
+- **[Tauri Guide](docs/guide-tauri.md)** — Using os-user-dirs in Tauri apps: path API mapping, sidecar patterns, shared config with CLI companions
+- **[VS Code Extension Guide](docs/guide-vscode-extension.md)** — Using os-user-dirs in VS Code extensions: `globalStorageUri` comparison, file export patterns, shared config with CLI tools
 - **[CLI Tools Guide](docs/guide-cli-tools.md)** — Using `projectDirs()` with commander, yargs, and oclif for config, cache, and log management
 
-## Migration from xdg-basedir
 ## Migration Guides
 
 Switching from another library? We have you covered:
@@ -286,6 +362,14 @@ downloads();                              // recommended: cross-platform Downloa
 getXDGUserDir("XDG_DOWNLOAD_DIR");        // direct replacement if you need XDG config parsing
 ```
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding conventions, and pull request guidelines.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for the security policy and vulnerability reporting instructions.
+
 ## License
 
 MIT

package/index.d.ts

@@ -3,12 +3,12 @@ type DirName = "desktop" | "downloads" | "documents" | "music" | "pictures" | "v
 /**
  * Returns the path to the Desktop directory.
  * @example
- * ```js
- * const { desktop } = require('os-user-dirs');
- * console.log(desktop());
+ * ```ts
+ * import { desktop } from 'os-user-dirs';
+ * const dir = desktop();
  * // Linux:   '/home/user/Desktop'
  * // macOS:   '/Users/user/Desktop'
- * // Windows: 'C:\Users\user\Desktop'
+ * // Windows: 'C:\\Users\\user\\Desktop'
  * ```
  */
 export function desktop(): string;
@@ -16,12 +16,12 @@ export function desktop(): string;
 /**
  * Returns the path to the Downloads directory.
  * @example
- * ```js
- * const { downloads } = require('os-user-dirs');
- * console.log(downloads());
+ * ```ts
+ * import { downloads } from 'os-user-dirs';
+ * const dir = downloads();
  * // Linux:   '/home/user/Downloads'
  * // macOS:   '/Users/user/Downloads'
- * // Windows: 'C:\Users\user\Downloads'
+ * // Windows: 'C:\\Users\\user\\Downloads'
  * ```
  */
 export function downloads(): string;
@@ -29,12 +29,12 @@ export function downloads(): string;
 /**
  * Returns the path to the Documents directory.
  * @example
- * ```js
- * const { documents } = require('os-user-dirs');
- * console.log(documents());
+ * ```ts
+ * import { documents } from 'os-user-dirs';
+ * const dir = documents();
  * // Linux:   '/home/user/Documents'
  * // macOS:   '/Users/user/Documents'
- * // Windows: 'C:\Users\user\Documents'
+ * // Windows: 'C:\\Users\\user\\Documents'
  * ```
  */
 export function documents(): string;
@@ -42,12 +42,12 @@ export function documents(): string;
 /**
  * Returns the path to the Music directory.
  * @example
- * ```js
- * const { music } = require('os-user-dirs');
- * console.log(music());
+ * ```ts
+ * import { music } from 'os-user-dirs';
+ * const dir = music();
  * // Linux:   '/home/user/Music'
  * // macOS:   '/Users/user/Music'
- * // Windows: 'C:\Users\user\Music'
+ * // Windows: 'C:\\Users\\user\\Music'
  * ```
  */
 export function music(): string;
@@ -55,12 +55,12 @@ export function music(): string;
 /**
  * Returns the path to the Pictures directory.
  * @example
- * ```js
- * const { pictures } = require('os-user-dirs');
- * console.log(pictures());
+ * ```ts
+ * import { pictures } from 'os-user-dirs';
+ * const dir = pictures();
  * // Linux:   '/home/user/Pictures'
  * // macOS:   '/Users/user/Pictures'
- * // Windows: 'C:\Users\user\Pictures'
+ * // Windows: 'C:\\Users\\user\\Pictures'
  * ```
  */
 export function pictures(): string;
@@ -68,12 +68,12 @@ export function pictures(): string;
 /**
  * Returns the path to the Videos directory (Movies on macOS).
  * @example
- * ```js
- * const { videos } = require('os-user-dirs');
- * console.log(videos());
+ * ```ts
+ * import { videos } from 'os-user-dirs';
+ * const dir = videos();
  * // Linux:   '/home/user/Videos'
  * // macOS:   '/Users/user/Movies'
- * // Windows: 'C:\Users\user\Videos'
+ * // Windows: 'C:\\Users\\user\\Videos'
  * ```
  */
 export function videos(): string;
@@ -81,12 +81,12 @@ export function videos(): string;
 /**
  * Returns the path to the Templates directory.
  * @example
- * ```js
- * const { templates } = require('os-user-dirs');
- * console.log(templates());
+ * ```ts
+ * import { templates } from 'os-user-dirs';
+ * const dir = templates();
  * // Linux:   '/home/user/Templates'
  * // macOS:   '/Users/user/Templates'
- * // Windows: 'C:\Users\user\Templates'
+ * // Windows: 'C:\\Users\\user\\Templates'
  * ```
  */
 export function templates(): string;
@@ -94,23 +94,24 @@ export function templates(): string;
 /**
  * Returns the path to the Public Share directory.
  * @example
- * ```js
- * const { publicshare } = require('os-user-dirs');
- * console.log(publicshare());
+ * ```ts
+ * import { publicshare } from 'os-user-dirs';
+ * const dir = publicshare();
  * // Linux:   '/home/user/Public'
  * // macOS:   '/Users/user/Public'
- * // Windows: 'C:\Users\user\Public'
+ * // Windows: 'C:\\Users\\user\\Public'
  * ```
  */
 export function publicshare(): string;
 
 /**
  * Returns the path to the specified user directory.
+ * @param name - Directory name to resolve
  * @example
- * ```js
- * const { getPath } = require('os-user-dirs');
- * console.log(getPath('downloads')); // '/home/user/Downloads'
- * console.log(getPath('desktop'));    // '/home/user/Desktop'
+ * ```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;
@@ -118,12 +119,12 @@ export function getPath(name: DirName): string;
 /**
  * Returns the path to the user's home directory.
  * @example
- * ```js
- * const { homeDir } = require('os-user-dirs');
- * console.log(homeDir());
+ * ```ts
+ * import { homeDir } from 'os-user-dirs';
+ * const dir = homeDir();
  * // Linux:   '/home/user'
  * // macOS:   '/Users/user'
- * // Windows: 'C:\Users\user'
+ * // Windows: 'C:\\Users\\user'
  * ```
  */
 export function homeDir(): string;
@@ -131,9 +132,9 @@ 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());
+ * ```ts
+ * import { binDir } from 'os-user-dirs';
+ * const dir = binDir();
  * // Linux/macOS: '/home/user/.local/bin'
  * // Windows:     null
  * ```
@@ -145,12 +146,12 @@ type BaseDirName = "config" | "data" | "cache" | "state" | "log" | "runtime";
 /**
  * Returns the path to the XDG config directory.
  * @example
- * ```js
- * const { configDir } = require('os-user-dirs');
- * console.log(configDir());
+ * ```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'
+ * // Windows: 'C:\\Users\\user\\AppData\\Roaming'
  * ```
  */
 export function configDir(): string;
@@ -158,12 +159,12 @@ export function configDir(): string;
 /**
  * Returns the path to the XDG data directory.
  * @example
- * ```js
- * const { dataDir } = require('os-user-dirs');
- * console.log(dataDir());
+ * ```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'
+ * // Windows: 'C:\\Users\\user\\AppData\\Local'
  * ```
  */
 export function dataDir(): string;
@@ -171,12 +172,12 @@ export function dataDir(): string;
 /**
  * Returns the path to the XDG cache directory.
  * @example
- * ```js
- * const { cacheDir } = require('os-user-dirs');
- * console.log(cacheDir());
+ * ```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'
+ * // Windows: 'C:\\Users\\user\\AppData\\Local'
  * ```
  */
 export function cacheDir(): string;
@@ -184,12 +185,12 @@ export function cacheDir(): string;
 /**
  * Returns the path to the XDG state directory.
  * @example
- * ```js
- * const { stateDir } = require('os-user-dirs');
- * console.log(stateDir());
+ * ```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'
+ * // Windows: 'C:\\Users\\user\\AppData\\Local'
  * ```
  */
 export function stateDir(): string;
@@ -197,12 +198,12 @@ export function stateDir(): string;
 /**
  * Returns the path to the log directory.
  * @example
- * ```js
- * const { logDir } = require('os-user-dirs');
- * console.log(logDir());
+ * ```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'
+ * // Windows: 'C:\\Users\\user\\AppData\\Local'
  * ```
  */
 export function logDir(): string;
@@ -210,9 +211,9 @@ export function logDir(): string;
 /**
  * Returns the path to the XDG runtime directory, or null if unavailable.
  * @example
- * ```js
- * const { runtimeDir } = require('os-user-dirs');
- * console.log(runtimeDir());
+ * ```ts
+ * import { runtimeDir } from 'os-user-dirs';
+ * const dir = runtimeDir();
  * // Linux:   '/run/user/1000' (if $XDG_RUNTIME_DIR is set)
  * // macOS:   null
  * // Windows: null
@@ -223,12 +224,12 @@ export function runtimeDir(): string | null;
 /**
  * Returns the path to the user fonts directory.
  * @example
- * ```js
- * const { fontsDir } = require('os-user-dirs');
- * console.log(fontsDir());
+ * ```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'
+ * // Windows: 'C:\\Users\\user\\AppData\\Local\\Microsoft\\Windows\\Fonts'
  * ```
  */
 export function fontsDir(): string;
@@ -239,12 +240,12 @@ export function fontsDir(): string;
  * On macOS: `["/Library/Application Support", "/Library/Preferences"]`.
  * On Windows: `[%PROGRAMDATA%]`.
  * @example
- * ```js
- * const { configDirs } = require('os-user-dirs');
- * console.log(configDirs());
+ * ```ts
+ * import { configDirs } from 'os-user-dirs';
+ * const dirs = configDirs();
  * // Linux:   ['/etc/xdg']
  * // macOS:   ['/Library/Application Support', '/Library/Preferences']
- * // Windows: ['C:\ProgramData']
+ * // Windows: ['C:\\ProgramData']
  * ```
  */
 export function configDirs(): string[];
@@ -255,24 +256,25 @@ export function configDirs(): string[];
  * On macOS: `["/Library/Application Support"]`.
  * On Windows: `[%PROGRAMDATA%]`.
  * @example
- * ```js
- * const { dataDirs } = require('os-user-dirs');
- * console.log(dataDirs());
+ * ```ts
+ * import { dataDirs } from 'os-user-dirs';
+ * const dirs = dataDirs();
  * // Linux:   ['/usr/local/share', '/usr/share']
  * // macOS:   ['/Library/Application Support']
- * // Windows: ['C:\ProgramData']
+ * // Windows: ['C:\\ProgramData']
  * ```
  */
 export function dataDirs(): string[];
 
 /**
  * Returns the path to the specified base directory.
+ * @param name - Base directory name to resolve
  * @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
+ * ```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;
@@ -303,23 +305,28 @@ 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
- * ```js
- * const { projectDirs } = require('os-user-dirs');
+ * ```ts
+ * import { projectDirs } from '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'
+ * // 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
- * ```js
+ * ```ts
  * // 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'
+ * // 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;
@@ -340,12 +347,12 @@ interface ProjectUserDirsResult {
  * 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');
+ * ```ts
+ * import { projectUserDirs } from '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'
+ * // 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;
@@ -356,9 +363,9 @@ export function projectUserDirs(name: string): ProjectUserDirsResult;
  * macOS: `~/.Trash`
  * Windows: `null` (Recycle Bin requires Shell API)
  * @example
- * ```js
- * const { trashDir } = require('os-user-dirs');
- * console.log(trashDir());
+ * ```ts
+ * import { trashDir } from 'os-user-dirs';
+ * const dir = trashDir();
  * // Linux:   '/home/user/.local/share/Trash'
  * // macOS:   '/Users/user/.Trash'
  * // Windows: null
@@ -372,12 +379,12 @@ export function trashDir(): string | null;
  * macOS: `~/Applications`
  * Windows: `%APPDATA%/Microsoft/Windows/Start Menu/Programs`
  * @example
- * ```js
- * const { applicationsDir } = require('os-user-dirs');
- * console.log(applicationsDir());
+ * ```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'
+ * // Windows: 'C:\\Users\\user\\AppData\\Roaming\\Microsoft\\Windows\\Start Menu\\Programs'
  * ```
  */
 export function applicationsDir(): string;
@@ -388,10 +395,10 @@ export function applicationsDir(): string;
  * @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'
+ * ```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;
@@ -401,10 +408,10 @@ export function getXDGUserDir(key: string, configPath?: string): string | null;
  * @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'
+ * ```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;
@@ -414,14 +421,118 @@ export function ensureDirSync(dirPath: string): string;
  * @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'
+ * ```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>;
 
+interface GetAllDirsResult {
+    downloads: string;
+    desktop: string;
+    documents: string;
+    music: string;
+    pictures: string;
+    videos: string;
+    templates: string;
+    publicshare: string;
+    configDir: string;
+    dataDir: string;
+    cacheDir: string;
+    stateDir: string;
+    logDir: string;
+    runtimeDir: string | null;
+    fontsDir: string;
+    binDir: string | null;
+    applicationsDir: string;
+    trashDir: string | null;
+    homeDir: string;
+}
+
+/**
+ * Returns all directory paths as a single object.
+ * Useful for debugging, configuration dumps, or diagnostics.
+ * Does not include array-returning functions (`configDirs`, `dataDirs`)
+ * or functions requiring arguments (`projectDirs`, `projectUserDirs`).
+ * @example
+ * ```ts
+ * import { getAllDirs } from 'os-user-dirs';
+ * const dirs = getAllDirs();
+ * console.log(dirs.downloads);  // '/home/user/Downloads'
+ * console.log(dirs.configDir);  // '/home/user/.config'
+ * console.log(dirs.homeDir);    // '/home/user'
+ * ```
+ */
+export function getAllDirs(): GetAllDirsResult;
+
+/**
+ * Namespace grouping user directory functions.
+ * Provides organized access to user-specific directory functions.
+ * @example
+ * ```ts
+ * import { user } from 'os-user-dirs';
+ * user.downloads();   // '/home/user/Downloads'
+ * user.desktop();     // '/home/user/Desktop'
+ * user.homeDir();     // '/home/user'
+ * ```
+ */
+export const user: {
+    desktop: typeof desktop;
+    downloads: typeof downloads;
+    documents: typeof documents;
+    music: typeof music;
+    pictures: typeof pictures;
+    videos: typeof videos;
+    templates: typeof templates;
+    publicshare: typeof publicshare;
+    homeDir: typeof homeDir;
+    binDir: typeof binDir;
+    fontsDir: typeof fontsDir;
+    trashDir: typeof trashDir;
+    applicationsDir: typeof applicationsDir;
+};
+
+/**
+ * Namespace grouping XDG base directory functions.
+ * Provides organized access to base directory and search path functions.
+ * @example
+ * ```ts
+ * import { base } from 'os-user-dirs';
+ * base.configDir();   // '/home/user/.config'
+ * base.dataDir();     // '/home/user/.local/share'
+ * base.configDirs();  // ['/etc/xdg']
+ * ```
+ */
+export const base: {
+    configDir: typeof configDir;
+    dataDir: typeof dataDir;
+    cacheDir: typeof cacheDir;
+    stateDir: typeof stateDir;
+    logDir: typeof logDir;
+    runtimeDir: typeof runtimeDir;
+    configDirs: typeof configDirs;
+    dataDirs: typeof dataDirs;
+};
+
+/**
+ * Namespace grouping project-scoped directory functions.
+ * Provides organized access to application-scoped directory functions.
+ * @example
+ * ```ts
+ * import { project } from 'os-user-dirs';
+ * const dirs = project.dirs('my-app');
+ * dirs.config;  // '/home/user/.config/my-app'
+ * const userDirs = project.userDirs('my-app');
+ * userDirs.downloads;  // '/home/user/Downloads/my-app'
+ * ```
+ */
+export const project: {
+    dirs: typeof projectDirs;
+    userDirs: typeof projectUserDirs;
+};
+
 declare const osUserDirs: typeof downloads & {
     downloads: typeof downloads;
     desktop: typeof desktop;
@@ -451,6 +562,10 @@ declare const osUserDirs: typeof downloads & {
     getXDGUserDir: typeof getXDGUserDir;
     ensureDirSync: typeof ensureDirSync;
     ensureDir: typeof ensureDir;
+    getAllDirs: typeof getAllDirs;
+    user: typeof user;
+    base: typeof base;
+    project: typeof project;
 };
 
 export default osUserDirs;

package/index.js

@@ -374,6 +374,30 @@ function homeDir() {
     return os.homedir();
 }
 
+function getAllDirs() {
+    return {
+        downloads: downloads(),
+        desktop: desktop(),
+        documents: documents(),
+        music: music(),
+        pictures: pictures(),
+        videos: videos(),
+        templates: templates(),
+        publicshare: publicshare(),
+        configDir: configDir(),
+        dataDir: dataDir(),
+        cacheDir: cacheDir(),
+        stateDir: stateDir(),
+        logDir: logDir(),
+        runtimeDir: runtimeDir(),
+        fontsDir: fontsDir(),
+        binDir: binDir(),
+        applicationsDir: applicationsDir(),
+        trashDir: trashDir(),
+        homeDir: homeDir(),
+    };
+}
+
 function ensureDirSync(dirPath) {
     if (!dirPath || typeof dirPath !== "string") {
         throw new Error("ensureDirSync requires a non-empty string path");
@@ -391,6 +415,39 @@ function ensureDir(dirPath) {
     });
 }
 
+// Namespace exports
+const user = {
+    desktop: desktop,
+    downloads: downloads,
+    documents: documents,
+    music: music,
+    pictures: pictures,
+    videos: videos,
+    templates: templates,
+    publicshare: publicshare,
+    homeDir: homeDir,
+    binDir: binDir,
+    fontsDir: fontsDir,
+    trashDir: trashDir,
+    applicationsDir: applicationsDir,
+};
+
+const base = {
+    configDir: configDir,
+    dataDir: dataDir,
+    cacheDir: cacheDir,
+    stateDir: stateDir,
+    logDir: logDir,
+    runtimeDir: runtimeDir,
+    configDirs: configDirs,
+    dataDirs: dataDirs,
+};
+
+const project = {
+    dirs: projectDirs,
+    userDirs: projectUserDirs,
+};
+
 // Backward compatibility: require("os-user-dirs")() returns Downloads path
 module.exports = downloads;
 module.exports.getPath = getPath;
@@ -421,3 +478,7 @@ module.exports.getXDGUserDir = getXDGUserDir;
 module.exports.ensureDirSync = ensureDirSync;
 module.exports.trashDir = trashDir;
 module.exports.ensureDir = ensureDir;
+module.exports.getAllDirs = getAllDirs;
+module.exports.user = user;
+module.exports.base = base;
+module.exports.project = project;

package/index.mjs

@@ -29,3 +29,7 @@ export const getXDGUserDir = osUserDirs.getXDGUserDir;
 export const trashDir = osUserDirs.trashDir;
 export const ensureDirSync = osUserDirs.ensureDirSync;
 export const ensureDir = osUserDirs.ensureDir;
+export const getAllDirs = osUserDirs.getAllDirs;
+export const user = osUserDirs.user;
+export const base = osUserDirs.base;
+export const project = osUserDirs.project;

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "os-user-dirs",
-  "version": "3.0.1",
+  "version": "3.2.0",
   "description": "Get OS-specific user directories and XDG base directories (config, data, cache, runtime) with zero dependencies.",
   "main": "index.js",
+  "type": "commonjs",
   "types": "index.d.ts",
   "exports": {
     ".": {
@@ -27,6 +28,8 @@
   "keywords": [
     "os",
     "directories",
+    "user-dirs",
+    "user-directories",
     "downloads",
     "desktop",
     "documents",
@@ -35,23 +38,31 @@
     "videos",
     "templates",
     "public",
+    "home-dir",
     "config",
     "data",
     "cache",
+    "state",
+    "runtime",
     "xdg",
-    "user-dirs",
-    "platform-folders",
-    "env-paths",
     "xdg-basedir",
-    "appdata-path",
     "xdg-base-directory",
-    "user-directories",
-    "app-paths",
+    "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",