os-user-dirs 2.3.0 → 2.5.0

package/README.md

@@ -1,6 +1,6 @@
 # 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)
 
-Get OS-specific user directories (Downloads, Desktop, Documents, etc.) and XDG base directories (config, data, cache, runtime) with zero dependencies.
+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`).
 
 > **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.
 
@@ -42,7 +42,7 @@ getPath("music");
 #### Base directories
 
 ```javascript
-import { configDir, dataDir, cacheDir, runtimeDir, getBasePath } from "os-user-dirs";
+import { configDir, dataDir, cacheDir, stateDir, logDir, runtimeDir, getBasePath } from "os-user-dirs";
 
 configDir();
 //=> '/home/user/.config'
@@ -53,6 +53,12 @@ dataDir();
 cacheDir();
 //=> '/home/user/.cache'
 
+stateDir();
+//=> '/home/user/.local/state'
+
+logDir();
+//=> '/home/user/.local/state' (Linux), '~/Library/Logs' (macOS)
+
 runtimeDir();
 //=> '/run/user/1000' (or null)
 
@@ -60,6 +66,41 @@ 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";
+
+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'
+```
+
 ### CommonJS
 
 ```javascript
@@ -135,11 +176,38 @@ Returns the path to the data directory (`~/.local/share` on Linux, `~/Library/Ap
 #### `cacheDir()`
 Returns the path to the cache directory (`~/.cache` on Linux, `~/Library/Caches` on macOS, `%LOCALAPPDATA%` on Windows).
 
+#### `stateDir()`
+Returns the path to the state directory (`~/.local/state` on Linux, `~/Library/Application Support` on macOS, `%LOCALAPPDATA%` on Windows).
+
+#### `logDir()`
+Returns the path to the log directory (`~/.local/state` on Linux, `~/Library/Logs` on macOS, `%LOCALAPPDATA%` on Windows).
+
 #### `runtimeDir()`
 Returns the path to the runtime directory (`$XDG_RUNTIME_DIR` on Linux), or `null` if unavailable.
 
 #### `getBasePath(name)`
-Returns the path to the specified base directory. Valid names: `config`, `data`, `cache`, `runtime`.
+Returns the path to the specified base directory. Valid names: `config`, `data`, `cache`, `state`, `log`, `runtime`.
+
+### 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%]`.
+
+#### `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%]`.
+
+### 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).
+
+**Parameters:**
+- `name` (string) — Application name
+- `options.suffix` (string, optional) — Suffix appended to the app name (e.g. `"-nodejs"`)
+
+**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`).
 
 ## License
 

package/index.d.ts

@@ -27,7 +27,7 @@ export function publicshare(): string;
 /** Returns the path to the specified user directory. */
 export function getPath(name: DirName): string;
 
-type BaseDirName = "config" | "data" | "cache" | "runtime";
+type BaseDirName = "config" | "data" | "cache" | "state" | "log" | "runtime";
 
 /** Returns the path to the XDG config directory. */
 export function configDir(): string;
@@ -38,16 +38,62 @@ export function dataDir(): string;
 /** Returns the path to the XDG cache directory. */
 export function cacheDir(): string;
 
+/** Returns the path to the XDG state directory. */
+export function stateDir(): string;
+
+/** Returns the path to the log directory. */
+export function logDir(): string;
+
 /** Returns the path to the XDG runtime directory, or null if unavailable. */
 export function runtimeDir(): string | null;
 
+/**
+ * Returns the system config directory search path list.
+ * On Linux, reads `$XDG_CONFIG_DIRS` (default: `["/etc/xdg"]`).
+ * On macOS: `["/Library/Application Support", "/Library/Preferences"]`.
+ * On Windows: `[%PROGRAMDATA%]`.
+ */
+export function configDirs(): string[];
+
+/**
+ * Returns the system data directory search path list.
+ * On Linux, reads `$XDG_DATA_DIRS` (default: `["/usr/local/share", "/usr/share"]`).
+ * On macOS: `["/Library/Application Support"]`.
+ * On Windows: `[%PROGRAMDATA%]`.
+ */
+export function dataDirs(): string[];
+
 /** Returns the path to the specified base directory. */
 export function getBasePath(name: "config"): string;
 export function getBasePath(name: "data"): string;
 export function getBasePath(name: "cache"): string;
+export function getBasePath(name: "state"): string;
+export function getBasePath(name: "log"): string;
 export function getBasePath(name: "runtime"): string | null;
 export function getBasePath(name: BaseDirName): string | null;
 
+interface ProjectDirsOptions {
+    /** Suffix appended to the app name (default: ""). */
+    suffix?: string;
+}
+
+interface ProjectDirsResult {
+    config: string;
+    data: string;
+    cache: string;
+    state: string;
+    log: string;
+    temp: string;
+    runtime: string | null;
+}
+
+/**
+ * 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)
+ */
+export function projectDirs(name: string, options?: ProjectDirsOptions): ProjectDirsResult;
+
 /**
  * Reads an XDG user-dirs.dirs config and returns the directory for the given key.
  * @param key - XDG key (e.g. "XDG_DOWNLOAD_DIR")
@@ -74,8 +120,13 @@ declare const osUserDirs: typeof downloads & {
     configDir: typeof configDir;
     dataDir: typeof dataDir;
     cacheDir: typeof cacheDir;
+    stateDir: typeof stateDir;
+    logDir: typeof logDir;
     runtimeDir: typeof runtimeDir;
     getBasePath: typeof getBasePath;
+    configDirs: typeof configDirs;
+    dataDirs: typeof dataDirs;
+    projectDirs: typeof projectDirs;
     getXDGUserDir: typeof getXDGUserDir;
     getXDGDownloadDir: typeof getXDGDownloadDir;
 };

package/index.js

@@ -84,10 +84,12 @@ function templates() { return resolve("templates"); }
 function publicshare() { return resolve("publicshare"); }
 
 const BASE_DIR_CONFIG = {
-    config:  { env: "XDG_CONFIG_HOME",  linux: ".config",      darwin: "Library/Application Support", win32: "APPDATA" },
-    data:    { env: "XDG_DATA_HOME",    linux: ".local/share",  darwin: "Library/Application Support", win32: "LOCALAPPDATA" },
-    cache:   { env: "XDG_CACHE_HOME",   linux: ".cache",        darwin: "Library/Caches",              win32: "LOCALAPPDATA" },
-    runtime: { env: "XDG_RUNTIME_DIR",  linux: null,            darwin: null,                          win32: null },
+    config:  { env: "XDG_CONFIG_HOME",  linux: ".config",        darwin: "Library/Application Support", win32: "APPDATA" },
+    data:    { env: "XDG_DATA_HOME",    linux: ".local/share",   darwin: "Library/Application Support", win32: "LOCALAPPDATA" },
+    cache:   { env: "XDG_CACHE_HOME",   linux: ".cache",         darwin: "Library/Caches",              win32: "LOCALAPPDATA" },
+    state:   { env: "XDG_STATE_HOME",   linux: ".local/state",   darwin: "Library/Application Support", win32: "LOCALAPPDATA" },
+    log:     { env: "XDG_STATE_HOME",   linux: ".local/state",   darwin: "Library/Logs",                win32: "LOCALAPPDATA" },
+    runtime: { env: "XDG_RUNTIME_DIR",  linux: null,             darwin: null,                          win32: null },
 };
 
 function resolveBase(name) {
@@ -138,12 +140,127 @@ function resolveBase(name) {
 function configDir() { return resolveBase("config"); }
 function dataDir() { return resolveBase("data"); }
 function cacheDir() { return resolveBase("cache"); }
+function stateDir() { return resolveBase("state"); }
+function logDir() { return resolveBase("log"); }
 function runtimeDir() { return resolveBase("runtime"); }
 
+const SEARCH_DIRS_CONFIG = {
+    config: {
+        env: "XDG_CONFIG_DIRS",
+        linux: ["/etc/xdg"],
+        darwin: ["/Library/Application Support", "/Library/Preferences"],
+        win32: "PROGRAMDATA",
+    },
+    data: {
+        env: "XDG_DATA_DIRS",
+        linux: ["/usr/local/share", "/usr/share"],
+        darwin: ["/Library/Application Support"],
+        win32: "PROGRAMDATA",
+    },
+};
+
+function resolveSearchDirs(name) {
+    const cfg = SEARCH_DIRS_CONFIG[name];
+    if (!cfg) {
+        throw new Error("Unknown search directory: " + name + ". Valid names: " + Object.keys(SEARCH_DIRS_CONFIG).join(", "));
+    }
+
+    const platform = process.platform;
+
+    if (platform === "linux") {
+        const envVal = process.env[cfg.env];
+        if (envVal) {
+            const dirs = envVal.split(":").filter(Boolean);
+            if (dirs.length > 0) {
+                return dirs.map(function (d) { return path.resolve(d); });
+            }
+        }
+        return cfg.linux.slice();
+    }
+
+    if (platform === "darwin") {
+        return cfg.darwin.slice();
+    }
+
+    if (platform === "win32") {
+        const winVal = process.env[cfg.win32];
+        if (winVal) {
+            return [path.resolve(winVal)];
+        }
+        return [path.join(process.env.SYSTEMDRIVE || "C:", "ProgramData")];
+    }
+
+    // Unknown platform: use Linux defaults
+    return cfg.linux.slice();
+}
+
+function configDirs() { return resolveSearchDirs("config"); }
+function dataDirs() { return resolveSearchDirs("data"); }
+
 function getBasePath(name) {
     return resolveBase(name);
 }
 
+const PROJECT_DIR_WIN32_SUB = {
+    config: "Config",
+    data:   "Data",
+    cache:  "Cache",
+    state:  "State",
+    log:    "Log",
+};
+
+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 appName = name + suffix;
+
+    const homedir = os.homedir();
+    const platform = process.platform;
+
+    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 path.join(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 null;
+        }
+
+        const base = resolveBase(kind);
+        if (!base) { return null; }
+
+        const sub = PROJECT_DIR_WIN32_SUB[kind];
+        if (platform === "win32" && sub) {
+            return path.join(base, appName, sub);
+        }
+
+        return path.join(base, appName);
+    }
+
+    return {
+        config:  resolveProject("config"),
+        data:    resolveProject("data"),
+        cache:   resolveProject("cache"),
+        state:   resolveProject("state"),
+        log:     resolveProject("log"),
+        temp:    resolveProject("temp"),
+        runtime: resolveProject("runtime"),
+    };
+}
+
 // Backward compatibility: require("os-user-dirs")() returns Downloads path
 module.exports = downloads;
 module.exports.getPath = getPath;
@@ -158,8 +275,13 @@ module.exports.publicshare = publicshare;
 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.getBasePath = getBasePath;
+module.exports.configDirs = configDirs;
+module.exports.dataDirs = dataDirs;
+module.exports.projectDirs = projectDirs;
 module.exports.getXDGUserDir = getXDGUserDir;
 
 // Deprecated: kept for backward compatibility

package/index.mjs

@@ -13,7 +13,12 @@ export const getPath = osUserDirs.getPath;
 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 getBasePath = osUserDirs.getBasePath;
+export const configDirs = osUserDirs.configDirs;
+export const dataDirs = osUserDirs.dataDirs;
+export const projectDirs = osUserDirs.projectDirs;
 export const getXDGUserDir = osUserDirs.getXDGUserDir;
 export const getXDGDownloadDir = osUserDirs.getXDGDownloadDir;

package/package.json

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