os-user-dirs 2.6.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'
@@ -99,6 +106,27 @@ 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
@@ -165,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`)
@@ -216,11 +253,63 @@ Returns an object with app-scoped directories for the given application name. Th
 **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.
 
 **Returns:** `{ config, data, cache, state, log, temp, runtime }`
 
 On Windows, each directory uses a subdirectory structure (e.g. `%LOCALAPPDATA%/my-app/Config`, `%LOCALAPPDATA%/my-app/Data`).
 
+#### `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.
+
+**Parameters:**
+- `name` (string) — Application name
+
+**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;
 
@@ -81,6 +84,8 @@ export function getBasePath(name: BaseDirName): string | null;
 interface ProjectDirsOptions {
     /** Suffix appended to the app name (default: ""). */
     suffix?: string;
+    /** Vendor/organization name used as a parent directory (e.g. "My Org"). On Linux, normalized to lowercase with hyphens. */
+    vendor?: string;
 }
 
 interface ProjectDirsResult {
@@ -100,6 +105,32 @@ interface ProjectDirsResult {
  */
 export function projectDirs(name: string, options?: ProjectDirsOptions): ProjectDirsResult;
 
+interface ProjectUserDirsResult {
+    desktop: string;
+    downloads: string;
+    documents: string;
+    music: string;
+    pictures: string;
+    videos: string;
+    templates: string;
+    publicshare: string;
+}
+
+/**
+ * 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
+ */
+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`)
@@ -117,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;
@@ -143,9 +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",
@@ -241,31 +241,48 @@ const PROJECT_DIR_WIN32_SUB = {
     log:    "Log",
 };
 
+function normalizeVendor(vendor, platform) {
+    if (platform === "linux") {
+        return vendor.toLowerCase().replace(/\s+/g, "-");
+    }
+    return vendor;
+}
+
 function projectDirs(name, options) {
     if (!name || typeof name !== "string") {
         throw new Error("projectDirs requires a non-empty string name");
     }
 
     const suffix = (options && options.suffix != null) ? options.suffix : "";
+    const vendor = (options && options.vendor) ? options.vendor : "";
     const appName = name + suffix;
 
     const homedir = os.homedir();
     const platform = process.platform;
+    const vendorDir = vendor ? normalizeVendor(vendor, platform) : "";
+
+    function joinWithVendor() {
+        var segments = Array.prototype.slice.call(arguments);
+        if (vendorDir) {
+            segments.splice(1, 0, vendorDir);
+        }
+        return path.join.apply(path, segments);
+    }
 
     function resolveProject(kind) {
         if (kind === "temp") {
             if (platform === "win32") {
                 const localAppData = process.env.LOCALAPPDATA || path.join(homedir, "AppData", "Local");
-                return path.join(localAppData, "Temp", appName);
+                return joinWithVendor(localAppData, "Temp", appName);
             }
-            return path.join(os.tmpdir(), appName);
+            return joinWithVendor(os.tmpdir(), appName);
         }
 
         if (kind === "runtime") {
             if (platform === "linux") {
                 const envVal = process.env.XDG_RUNTIME_DIR;
                 if (envVal) {
-                    return path.join(path.resolve(envVal), appName);
+                    return joinWithVendor(path.resolve(envVal), appName);
                 }
             }
             return null;
@@ -276,10 +293,10 @@ function projectDirs(name, options) {
 
         const sub = PROJECT_DIR_WIN32_SUB[kind];
         if (platform === "win32" && sub) {
-            return path.join(base, appName, sub);
+            return joinWithVendor(base, appName, sub);
         }
 
-        return path.join(base, appName);
+        return joinWithVendor(base, appName);
     }
 
     return {
@@ -293,6 +310,43 @@ function projectDirs(name, options) {
     };
 }
 
+function projectUserDirs(name) {
+    if (!name || typeof name !== "string") {
+        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++) {
+        result[keys[i]] = path.join(resolve(keys[i]), 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;
@@ -316,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;
@@ -340,9 +415,9 @@ module.exports.configDirs = configDirs;
 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

@@ -23,5 +23,9 @@ export const configDirs = osUserDirs.configDirs;
 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.6.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"