os-user-dirs 2.1.0 → 2.3.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, Music, Pictures, Videos) with zero dependencies.
+Get OS-specific user directories (Downloads, Desktop, Documents, etc.) and XDG base directories (config, data, cache, runtime) with zero dependencies.
 
 > **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.
 
@@ -21,7 +21,7 @@ $ npm install os-user-dirs
 ### ESM (recommended)
 
 ```javascript
-import { downloads, desktop, documents, music, pictures, videos, getPath } from "os-user-dirs";
+import { downloads, desktop, documents, music, pictures, videos, templates, publicshare, getPath } from "os-user-dirs";
 
 downloads();
 //=> '/home/user/Downloads'
@@ -29,17 +29,41 @@ downloads();
 desktop();
 //=> '/home/user/Desktop'
 
-documents();
-//=> '/home/user/Documents'
+templates();
+//=> '/home/user/Templates'
+
+publicshare();
+//=> '/home/user/Public'
 
 getPath("music");
 //=> '/home/user/Music'
 ```
 
+#### Base directories
+
+```javascript
+import { configDir, dataDir, cacheDir, runtimeDir, getBasePath } from "os-user-dirs";
+
+configDir();
+//=> '/home/user/.config'
+
+dataDir();
+//=> '/home/user/.local/share'
+
+cacheDir();
+//=> '/home/user/.cache'
+
+runtimeDir();
+//=> '/run/user/1000' (or null)
+
+getBasePath("config");
+//=> '/home/user/.config'
+```
+
 ### CommonJS
 
 ```javascript
-const { downloads, desktop, documents, music, pictures, videos, getPath } = require("os-user-dirs");
+const { downloads, desktop, documents, music, pictures, videos, templates, publicshare, getPath } = require("os-user-dirs");
 
 downloads();
 //=> '/home/user/Downloads'
@@ -65,9 +89,10 @@ Full type definitions are included. `getPath()` accepts a union type for auto-co
 ```typescript
 import { getPath } from "os-user-dirs";
 
-getPath("downloads"); // OK
-getPath("desktop");   // OK
-getPath("unknown");   // Type error
+getPath("downloads");  // OK
+getPath("desktop");    // OK
+getPath("templates");  // OK
+getPath("unknown");    // Type error
 ```
 
 ## API
@@ -90,8 +115,31 @@ Returns the path to the Pictures directory.
 ### `videos()`
 Returns the path to the Videos directory (Movies on macOS).
 
+### `templates()`
+Returns the path to the Templates directory.
+
+### `publicshare()`
+Returns the path to the Public Share directory.
+
 ### `getPath(name)`
-Returns the path to the specified directory. Valid names: `desktop`, `downloads`, `documents`, `music`, `pictures`, `videos`.
+Returns the path to the specified user directory. Valid names: `desktop`, `downloads`, `documents`, `music`, `pictures`, `videos`, `templates`, `publicshare`.
+
+### Base Directories
+
+#### `configDir()`
+Returns the path to the config directory (`~/.config` on Linux, `~/Library/Application Support` on macOS, `%APPDATA%` on Windows).
+
+#### `dataDir()`
+Returns the path to the data directory (`~/.local/share` on Linux, `~/Library/Application Support` on macOS, `%LOCALAPPDATA%` on Windows).
+
+#### `cacheDir()`
+Returns the path to the cache directory (`~/.cache` on Linux, `~/Library/Caches` 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`.
 
 ## License
 

package/index.d.ts

@@ -1,4 +1,4 @@
-type DirName = "desktop" | "downloads" | "documents" | "music" | "pictures" | "videos";
+type DirName = "desktop" | "downloads" | "documents" | "music" | "pictures" | "videos" | "templates" | "publicshare";
 
 /** Returns the path to the Desktop directory. */
 export function desktop(): string;
@@ -18,9 +18,36 @@ export function pictures(): string;
 /** Returns the path to the Videos directory (Movies on macOS). */
 export function videos(): string;
 
+/** Returns the path to the Templates directory. */
+export function templates(): string;
+
+/** Returns the path to the Public Share directory. */
+export function publicshare(): string;
+
 /** Returns the path to the specified user directory. */
 export function getPath(name: DirName): string;
 
+type BaseDirName = "config" | "data" | "cache" | "runtime";
+
+/** Returns the path to the XDG config directory. */
+export function configDir(): string;
+
+/** Returns the path to the XDG data directory. */
+export function dataDir(): string;
+
+/** Returns the path to the XDG cache directory. */
+export function cacheDir(): string;
+
+/** Returns the path to the XDG runtime directory, or null if unavailable. */
+export function runtimeDir(): string | null;
+
+/** 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: "runtime"): string | null;
+export function getBasePath(name: BaseDirName): string | null;
+
 /**
  * Reads an XDG user-dirs.dirs config and returns the directory for the given key.
  * @param key - XDG key (e.g. "XDG_DOWNLOAD_DIR")
@@ -41,7 +68,14 @@ declare const osUserDirs: typeof downloads & {
     music: typeof music;
     pictures: typeof pictures;
     videos: typeof videos;
+    templates: typeof templates;
+    publicshare: typeof publicshare;
     getPath: typeof getPath;
+    configDir: typeof configDir;
+    dataDir: typeof dataDir;
+    cacheDir: typeof cacheDir;
+    runtimeDir: typeof runtimeDir;
+    getBasePath: typeof getBasePath;
     getXDGUserDir: typeof getXDGUserDir;
     getXDGDownloadDir: typeof getXDGDownloadDir;
 };

package/index.js

@@ -9,6 +9,8 @@ const XDG_KEYS = {
     music: "XDG_MUSIC_DIR",
     pictures: "XDG_PICTURES_DIR",
     videos: "XDG_VIDEOS_DIR",
+    templates: "XDG_TEMPLATES_DIR",
+    publicshare: "XDG_PUBLICSHARE_DIR",
 };
 
 const MACOS_DEFAULTS = {
@@ -18,6 +20,8 @@ const MACOS_DEFAULTS = {
     music: "Music",
     pictures: "Pictures",
     videos: "Movies",
+    templates: "Templates",
+    publicshare: "Public",
 };
 
 const DEFAULT_DIRS = {
@@ -27,6 +31,8 @@ const DEFAULT_DIRS = {
     music: "Music",
     pictures: "Pictures",
     videos: "Videos",
+    templates: "Templates",
+    publicshare: "Public",
 };
 
 function getXDGUserDir(key, configPath) {
@@ -74,6 +80,69 @@ function documents() { return resolve("documents"); }
 function music() { return resolve("music"); }
 function pictures() { return resolve("pictures"); }
 function videos() { return resolve("videos"); }
+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 },
+};
+
+function resolveBase(name) {
+    const cfg = BASE_DIR_CONFIG[name];
+    if (!cfg) {
+        throw new Error("Unknown base directory: " + name + ". Valid names: " + Object.keys(BASE_DIR_CONFIG).join(", "));
+    }
+
+    const homedir = os.homedir();
+    const platform = process.platform;
+
+    // On Linux, check the XDG environment variable first
+    if (platform === "linux") {
+        const envVal = process.env[cfg.env];
+        if (envVal) {
+            return path.resolve(envVal);
+        }
+        // Fall back to default suffix, or null for runtime
+        return cfg.linux ? path.join(homedir, cfg.linux) : null;
+    }
+
+    if (platform === "darwin") {
+        return cfg.darwin ? path.join(homedir, cfg.darwin) : null;
+    }
+
+    // Windows: read from environment variable, with hardcoded fallback
+    if (platform === "win32") {
+        if (cfg.win32) {
+            const winVal = process.env[cfg.win32];
+            if (winVal) {
+                return path.resolve(winVal);
+            }
+            // Fallback when env var is missing
+            if (cfg.win32 === "APPDATA") {
+                return path.join(homedir, "AppData", "Roaming");
+            }
+            if (cfg.win32 === "LOCALAPPDATA") {
+                return path.join(homedir, "AppData", "Local");
+            }
+        }
+        return null;
+    }
+
+    // Unknown platform: use XDG-style defaults (same as Linux without env var)
+    return cfg.linux ? path.join(homedir, cfg.linux) : null;
+}
+
+function configDir() { return resolveBase("config"); }
+function dataDir() { return resolveBase("data"); }
+function cacheDir() { return resolveBase("cache"); }
+function runtimeDir() { return resolveBase("runtime"); }
+
+function getBasePath(name) {
+    return resolveBase(name);
+}
 
 // Backward compatibility: require("os-user-dirs")() returns Downloads path
 module.exports = downloads;
@@ -84,6 +153,13 @@ module.exports.documents = documents;
 module.exports.music = music;
 module.exports.pictures = pictures;
 module.exports.videos = videos;
+module.exports.templates = templates;
+module.exports.publicshare = publicshare;
+module.exports.configDir = configDir;
+module.exports.dataDir = dataDir;
+module.exports.cacheDir = cacheDir;
+module.exports.runtimeDir = runtimeDir;
+module.exports.getBasePath = getBasePath;
 module.exports.getXDGUserDir = getXDGUserDir;
 
 // Deprecated: kept for backward compatibility

package/index.mjs

@@ -7,6 +7,13 @@ export const documents = osUserDirs.documents;
 export const music = osUserDirs.music;
 export const pictures = osUserDirs.pictures;
 export const videos = osUserDirs.videos;
+export const templates = osUserDirs.templates;
+export const publicshare = osUserDirs.publicshare;
 export const getPath = osUserDirs.getPath;
+export const configDir = osUserDirs.configDir;
+export const dataDir = osUserDirs.dataDir;
+export const cacheDir = osUserDirs.cacheDir;
+export const runtimeDir = osUserDirs.runtimeDir;
+export const getBasePath = osUserDirs.getBasePath;
 export const getXDGUserDir = osUserDirs.getXDGUserDir;
 export const getXDGDownloadDir = osUserDirs.getXDGDownloadDir;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "os-user-dirs",
-  "version": "2.1.0",
-  "description": "Get OS-specific user directories (Downloads, Desktop, Documents, Music, Pictures, Videos) with zero dependencies.",
+  "version": "2.3.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",
   "exports": {
@@ -32,6 +32,11 @@
     "music",
     "pictures",
     "videos",
+    "templates",
+    "public",
+    "config",
+    "data",
+    "cache",
     "xdg",
     "user-dirs",
     "platform-folders"