os-user-dirs 2.7.0 → 3.0.0

package/README.md

@@ -4,6 +4,10 @@ Get OS-specific user directories (Downloads, Desktop, Documents, etc.) and XDG b
 
 > **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.
 
+## Requirements
+
+- Node.js 18 or later
+
 ## Supported platforms
 
 - Windows
@@ -21,7 +25,10 @@ $ npm install os-user-dirs
 ### ESM (recommended)
 
 ```javascript
-import { downloads, desktop, documents, music, pictures, videos, templates, publicshare, getPath } from "os-user-dirs";
+import { downloads, desktop, documents, music, pictures, videos, templates, publicshare, getPath, homeDir } from "os-user-dirs";
+
+homeDir();
+//=> '/home/user'
 
 downloads();
 //=> '/home/user/Downloads'
@@ -186,9 +193,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`)
@@ -251,6 +267,49 @@ Returns an object with project-scoped user directories. Each value is the corres
 
 **Returns:** `{ desktop, downloads, documents, music, pictures, videos, templates, publicshare }`
 
+### Utilities
+
+#### `ensureDirSync(dirPath)`
+Ensures the specified directory exists, creating it recursively if necessary. Returns the directory path.
+
+#### `ensureDir(dirPath)`
+Async version of `ensureDirSync`. Returns a promise that resolves with the directory path.
+
+```javascript
+import { projectDirs, ensureDirSync, ensureDir } from "os-user-dirs";
+
+const dirs = projectDirs("my-app");
+
+// Sync
+ensureDirSync(dirs.config);
+
+// Async
+await ensureDir(dirs.data);
+```
+
+## Migration from env-paths
+
+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.
+
+## 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
 
 MIT

package/index.d.ts

@@ -27,6 +27,9 @@ export function publicshare(): string;
 /** Returns the path to the specified user directory. */
 export function getPath(name: DirName): string;
 
+/** Returns the path to the user's home directory. */
+export function homeDir(): string;
+
 /** Returns the path to the user local bin directory (~/.local/bin), or null on Windows. */
 export function binDir(): string | null;
 
@@ -120,6 +123,14 @@ interface ProjectUserDirsResult {
  */
 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)
+ */
+export function trashDir(): string | null;
+
 /**
  * Returns the path to the user applications directory.
  * Linux: `$XDG_DATA_HOME/applications` (default `~/.local/share/applications`)
@@ -137,9 +148,18 @@ export function applicationsDir(): string;
 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
+ */
+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
  */
-export function getXDGDownloadDir(configPath?: string): string | null;
+export function ensureDir(dirPath: string): Promise<string>;
 
 declare const osUserDirs: typeof downloads & {
     downloads: typeof downloads;
@@ -163,10 +183,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",
@@ -323,6 +323,30 @@ function projectUserDirs(name) {
     return result;
 }
 
+function trashDir() {
+    var platform = process.platform;
+    var homedir = os.homedir();
+
+    if (platform === "linux") {
+        var envVal = process.env.XDG_DATA_HOME;
+        var 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
+    var envVal = process.env.XDG_DATA_HOME;
+    var 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;
@@ -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.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",
@@ -46,6 +46,9 @@
   "bugs": {
     "url": "https://github.com/velocitylabo/os-user-dirs/issues"
   },
+  "engines": {
+    "node": ">=18"
+  },
   "homepage": "https://github.com/velocitylabo/os-user-dirs#readme",
   "devDependencies": {
     "mocha": "^11.7.5"