os-user-dirs 2.5.0 → 2.7.0

package/README.md

@@ -99,6 +99,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,6 +186,15 @@ 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`.
 
+### `binDir()`
+Returns the path to the user local bin directory (`~/.local/bin` on Linux/macOS), or `null` on Windows.
+
+### `applicationsDir()`
+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`
+
 ### Base Directories
 
 #### `configDir()`
@@ -185,6 +215,9 @@ Returns the path to the log directory (`~/.local/state` on Linux, `~/Library/Log
 #### `runtimeDir()`
 Returns the path to the runtime directory (`$XDG_RUNTIME_DIR` on Linux), or `null` if unavailable.
 
+#### `fontsDir()`
+Returns the path to the user fonts directory (`~/.local/share/fonts` on Linux, `~/Library/Fonts` on macOS, `%LOCALAPPDATA%/Microsoft/Windows/Fonts` on Windows). On Linux, respects `$XDG_DATA_HOME`.
+
 #### `getBasePath(name)`
 Returns the path to the specified base directory. Valid names: `config`, `data`, `cache`, `state`, `log`, `runtime`.
 
@@ -204,11 +237,20 @@ 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 }`
+
 ## 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 local bin directory (~/.local/bin), or null on Windows. */
+export function binDir(): string | null;
+
 type BaseDirName = "config" | "data" | "cache" | "state" | "log" | "runtime";
 
 /** Returns the path to the XDG config directory. */
@@ -47,6 +50,9 @@ export function logDir(): string;
 /** Returns the path to the XDG runtime directory, or null if unavailable. */
 export function runtimeDir(): string | null;
 
+/** Returns the path to the user fonts directory. */
+export function fontsDir(): string;
+
 /**
  * Returns the system config directory search path list.
  * On Linux, reads `$XDG_CONFIG_DIRS` (default: `["/etc/xdg"]`).
@@ -75,6 +81,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 {
@@ -94,6 +102,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 applications directory.
+ * Linux: `$XDG_DATA_HOME/applications` (default `~/.local/share/applications`)
+ * macOS: `~/Applications`
+ * Windows: `%APPDATA%/Microsoft/Windows/Start Menu/Programs`
+ */
+export function applicationsDir(): string;
+
 /**
  * Reads an XDG user-dirs.dirs config and returns the directory for the given key.
  * @param key - XDG key (e.g. "XDG_DOWNLOAD_DIR")
@@ -117,16 +151,20 @@ declare const osUserDirs: typeof downloads & {
     templates: typeof templates;
     publicshare: typeof publicshare;
     getPath: typeof getPath;
+    binDir: typeof binDir;
     configDir: typeof configDir;
     dataDir: typeof dataDir;
     cacheDir: typeof cacheDir;
     stateDir: typeof stateDir;
     logDir: typeof logDir;
     runtimeDir: typeof runtimeDir;
+    fontsDir: typeof fontsDir;
     getBasePath: typeof getBasePath;
     configDirs: typeof configDirs;
     dataDirs: typeof dataDirs;
     projectDirs: typeof projectDirs;
+    applicationsDir: typeof applicationsDir;
+    projectUserDirs: typeof projectUserDirs;
     getXDGUserDir: typeof getXDGUserDir;
     getXDGDownloadDir: typeof getXDGDownloadDir;
 };

package/index.js

@@ -137,6 +137,13 @@ function resolveBase(name) {
     return cfg.linux ? path.join(homedir, cfg.linux) : null;
 }
 
+function binDir() {
+    if (process.platform === "win32") {
+        return null;
+    }
+    return path.join(os.homedir(), ".local", "bin");
+}
+
 function configDir() { return resolveBase("config"); }
 function dataDir() { return resolveBase("data"); }
 function cacheDir() { return resolveBase("cache"); }
@@ -144,6 +151,31 @@ function stateDir() { return resolveBase("state"); }
 function logDir() { return resolveBase("log"); }
 function runtimeDir() { return resolveBase("runtime"); }
 
+function fontsDir() {
+    var platform = process.platform;
+    var homedir = os.homedir();
+
+    if (platform === "linux") {
+        var envVal = process.env.XDG_DATA_HOME;
+        if (envVal) {
+            return path.join(path.resolve(envVal), "fonts");
+        }
+        return path.join(homedir, ".local", "share", "fonts");
+    }
+
+    if (platform === "darwin") {
+        return path.join(homedir, "Library", "Fonts");
+    }
+
+    if (platform === "win32") {
+        var localAppData = process.env.LOCALAPPDATA || path.join(homedir, "AppData", "Local");
+        return path.join(localAppData, "Microsoft", "Windows", "Fonts");
+    }
+
+    // Unknown platform: use XDG-style default
+    return path.join(homedir, ".local", "share", "fonts");
+}
+
 const SEARCH_DIRS_CONFIG = {
     config: {
         env: "XDG_CONFIG_DIRS",
@@ -209,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;
@@ -244,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 {
@@ -261,6 +310,42 @@ 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 applicationsDir() {
+    var homedir = os.homedir();
+    var platform = process.platform;
+
+    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, "applications");
+    }
+
+    if (platform === "darwin") {
+        return path.join(homedir, "Applications");
+    }
+
+    if (platform === "win32") {
+        var appdata = process.env.APPDATA || path.join(homedir, "AppData", "Roaming");
+        return path.join(appdata, "Microsoft", "Windows", "Start Menu", "Programs");
+    }
+
+    // Unknown platform: use XDG-style default
+    return path.join(homedir, ".local", "share", "applications");
+}
+
 // Backward compatibility: require("os-user-dirs")() returns Downloads path
 module.exports = downloads;
 module.exports.getPath = getPath;
@@ -272,16 +357,20 @@ module.exports.pictures = pictures;
 module.exports.videos = videos;
 module.exports.templates = templates;
 module.exports.publicshare = publicshare;
+module.exports.binDir = binDir;
 module.exports.configDir = configDir;
 module.exports.dataDir = dataDir;
 module.exports.cacheDir = cacheDir;
 module.exports.stateDir = stateDir;
 module.exports.logDir = logDir;
 module.exports.runtimeDir = runtimeDir;
+module.exports.fontsDir = fontsDir;
 module.exports.getBasePath = getBasePath;
 module.exports.configDirs = configDirs;
 module.exports.dataDirs = dataDirs;
 module.exports.projectDirs = projectDirs;
+module.exports.applicationsDir = applicationsDir;
+module.exports.projectUserDirs = projectUserDirs;
 module.exports.getXDGUserDir = getXDGUserDir;
 
 // Deprecated: kept for backward compatibility

package/index.mjs

@@ -10,15 +10,19 @@ export const videos = osUserDirs.videos;
 export const templates = osUserDirs.templates;
 export const publicshare = osUserDirs.publicshare;
 export const getPath = osUserDirs.getPath;
+export const binDir = osUserDirs.binDir;
 export const configDir = osUserDirs.configDir;
 export const dataDir = osUserDirs.dataDir;
 export const cacheDir = osUserDirs.cacheDir;
 export const stateDir = osUserDirs.stateDir;
 export const logDir = osUserDirs.logDir;
 export const runtimeDir = osUserDirs.runtimeDir;
+export const fontsDir = osUserDirs.fontsDir;
 export const getBasePath = osUserDirs.getBasePath;
 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 getXDGUserDir = osUserDirs.getXDGUserDir;
 export const getXDGDownloadDir = osUserDirs.getXDGDownloadDir;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "os-user-dirs",
-  "version": "2.5.0",
+  "version": "2.7.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",