os-user-dirs 2.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm install
+      - run: npm test

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Hiroshi Murakami
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# 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.
+
+> **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.
+
+## Supported platforms
+
+- Windows
+- macOS
+- Linux (with XDG user-dirs.dirs support)
+
+## Install
+
+```console
+$ npm install os-user-dirs
+```
+
+## Usage
+
+```javascript
+const { downloads, desktop, documents, music, pictures, videos, getPath } = require("os-user-dirs");
+
+downloads();
+//=> '/home/user/Downloads'
+
+desktop();
+//=> '/home/user/Desktop'
+
+documents();
+//=> '/home/user/Documents'
+
+getPath("music");
+//=> '/home/user/Music'
+```
+
+### Default export (backward compatibility)
+
+```javascript
+const downloads = require("os-user-dirs");
+
+downloads();
+//=> '/home/user/Downloads'
+```
+
+## API
+
+### `downloads()`
+Returns the path to the Downloads directory.
+
+### `desktop()`
+Returns the path to the Desktop directory.
+
+### `documents()`
+Returns the path to the Documents directory.
+
+### `music()`
+Returns the path to the Music directory.
+
+### `pictures()`
+Returns the path to the Pictures directory.
+
+### `videos()`
+Returns the path to the Videos directory (Movies on macOS).
+
+### `getPath(name)`
+Returns the path to the specified directory. Valid names: `desktop`, `downloads`, `documents`, `music`, `pictures`, `videos`.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,92 @@
+const path = require("path");
+const os = require("os");
+const fs = require("fs");
+
+const XDG_KEYS = {
+    desktop: "XDG_DESKTOP_DIR",
+    downloads: "XDG_DOWNLOAD_DIR",
+    documents: "XDG_DOCUMENTS_DIR",
+    music: "XDG_MUSIC_DIR",
+    pictures: "XDG_PICTURES_DIR",
+    videos: "XDG_VIDEOS_DIR",
+};
+
+const MACOS_DEFAULTS = {
+    desktop: "Desktop",
+    downloads: "Downloads",
+    documents: "Documents",
+    music: "Music",
+    pictures: "Pictures",
+    videos: "Movies",
+};
+
+const DEFAULT_DIRS = {
+    desktop: "Desktop",
+    downloads: "Downloads",
+    documents: "Documents",
+    music: "Music",
+    pictures: "Pictures",
+    videos: "Videos",
+};
+
+function getXDGUserDir(key, configPath) {
+    configPath = configPath || path.join(os.homedir(), ".config", "user-dirs.dirs");
+    try {
+        const content = fs.readFileSync(configPath, "utf8");
+        const regex = new RegExp('^' + key + '="(.+)"$', "m");
+        const match = content.match(regex);
+        if (match) {
+            return path.normalize(match[1].replace("$HOME", os.homedir()));
+        }
+    } catch (e) {
+        // file not found or unreadable, fall through to default
+    }
+    return null;
+}
+
+function resolve(name) {
+    const xdgKey = XDG_KEYS[name];
+    if (!xdgKey) {
+        throw new Error("Unknown directory: " + name + ". Valid names: " + Object.keys(XDG_KEYS).join(", "));
+    }
+
+    if (process.platform === "linux") {
+        const xdgDir = getXDGUserDir(xdgKey);
+        if (xdgDir) {
+            return xdgDir;
+        }
+    }
+
+    const dirName = process.platform === "darwin"
+        ? MACOS_DEFAULTS[name]
+        : DEFAULT_DIRS[name];
+
+    return path.join(os.homedir(), dirName);
+}
+
+function getPath(name) {
+    return resolve(name);
+}
+
+function desktop() { return resolve("desktop"); }
+function downloads() { return resolve("downloads"); }
+function documents() { return resolve("documents"); }
+function music() { return resolve("music"); }
+function pictures() { return resolve("pictures"); }
+function videos() { return resolve("videos"); }
+
+// Backward compatibility: require("os-user-dirs")() returns Downloads path
+module.exports = downloads;
+module.exports.getPath = getPath;
+module.exports.desktop = desktop;
+module.exports.downloads = downloads;
+module.exports.documents = documents;
+module.exports.music = music;
+module.exports.pictures = pictures;
+module.exports.videos = videos;
+module.exports.getXDGUserDir = getXDGUserDir;
+
+// Deprecated: kept for backward compatibility
+module.exports.getXDGDownloadDir = function (configPath) {
+    return getXDGUserDir("XDG_DOWNLOAD_DIR", configPath);
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "os-user-dirs",
+  "version": "2.0.0",
+  "description": "Get OS-specific user directories (Downloads, Desktop, Documents, Music, Pictures, Videos) with zero dependencies.",
+  "main": "index.js",
+  "scripts": {
+    "test": "mocha test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velocitylabo/os-user-dirs.git"
+  },
+  "keywords": [
+    "os",
+    "directories",
+    "downloads",
+    "desktop",
+    "documents",
+    "music",
+    "pictures",
+    "videos",
+    "xdg",
+    "user-dirs",
+    "platform-folders"
+  ],
+  "author": "piroz",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/velocitylabo/os-user-dirs/issues"
+  },
+  "homepage": "https://github.com/velocitylabo/os-user-dirs#readme",
+  "devDependencies": {
+    "mocha": "^11.7.5"
+  }
+}

package/test.js

@@ -0,0 +1,168 @@
+const assert = require("assert");
+const path = require("path");
+const os = require("os");
+const fs = require("fs");
+const downloads = require("./");
+const {
+    getXDGDownloadDir,
+    getXDGUserDir,
+    getPath,
+    desktop,
+    documents,
+    music,
+    pictures,
+    videos,
+} = require("./");
+
+describe("os-user-dirs", () => {
+    describe("downloads (default export / backward compatibility)", () => {
+        it("returns a path ending with Downloads", () => {
+            assert.ok(path.basename(downloads()).match(/downloads/i));
+        });
+
+        it("returns an absolute path", () => {
+            assert.ok(path.isAbsolute(downloads()));
+        });
+
+        it("path starts with home directory", () => {
+            assert.ok(downloads().startsWith(os.homedir()));
+        });
+    });
+
+    describe("named directory functions", () => {
+        const cases = [
+            { fn: desktop, name: "desktop" },
+            { fn: downloads, name: "downloads" },
+            { fn: documents, name: "documents" },
+            { fn: music, name: "music" },
+            { fn: pictures, name: "pictures" },
+            { fn: videos, name: "videos" },
+        ];
+
+        cases.forEach(({ fn, name }) => {
+            it(`${name}() returns an absolute path`, () => {
+                assert.ok(path.isAbsolute(fn()));
+            });
+
+            it(`${name}() starts with home directory`, () => {
+                assert.ok(fn().startsWith(os.homedir()));
+            });
+        });
+    });
+
+    describe("getPath", () => {
+        it("returns the same result as named functions", () => {
+            assert.strictEqual(getPath("desktop"), desktop());
+            assert.strictEqual(getPath("downloads"), downloads());
+            assert.strictEqual(getPath("documents"), documents());
+            assert.strictEqual(getPath("music"), music());
+            assert.strictEqual(getPath("pictures"), pictures());
+            assert.strictEqual(getPath("videos"), videos());
+        });
+
+        it("throws for unknown directory names", () => {
+            assert.throws(() => getPath("unknown"), /Unknown directory/);
+        });
+    });
+
+    describe("getXDGUserDir", () => {
+        const tmpDir = path.join(os.tmpdir(), "os-user-dirs-test");
+
+        beforeEach(() => {
+            fs.mkdirSync(tmpDir, { recursive: true });
+        });
+
+        afterEach(() => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+
+        const xdgEntries = [
+            { key: "XDG_DESKTOP_DIR", value: "Desktop" },
+            { key: "XDG_DOWNLOAD_DIR", value: "Downloads" },
+            { key: "XDG_DOCUMENTS_DIR", value: "Documents" },
+            { key: "XDG_MUSIC_DIR", value: "Music" },
+            { key: "XDG_PICTURES_DIR", value: "Pictures" },
+            { key: "XDG_VIDEOS_DIR", value: "Videos" },
+        ];
+
+        xdgEntries.forEach(({ key, value }) => {
+            it(`parses ${key} with $HOME`, () => {
+                const configPath = path.join(tmpDir, "user-dirs.dirs");
+                fs.writeFileSync(configPath, `${key}="$HOME/${value}"\n`);
+                const result = getXDGUserDir(key, configPath);
+                assert.strictEqual(result, path.join(os.homedir(), value));
+            });
+        });
+
+        it("parses entry with absolute path", () => {
+            const configPath = path.join(tmpDir, "user-dirs.dirs");
+            fs.writeFileSync(configPath, 'XDG_DOWNLOAD_DIR="/custom/downloads"\n');
+            const result = getXDGUserDir("XDG_DOWNLOAD_DIR", configPath);
+            assert.strictEqual(result, path.normalize("/custom/downloads"));
+        });
+
+        it("parses correct entry among multiple entries", () => {
+            const configPath = path.join(tmpDir, "user-dirs.dirs");
+            const content = [
+                'XDG_DESKTOP_DIR="$HOME/Desktop"',
+                'XDG_DOWNLOAD_DIR="$HOME/MyDownloads"',
+                'XDG_DOCUMENTS_DIR="$HOME/Documents"',
+                'XDG_MUSIC_DIR="$HOME/Musik"',
+                'XDG_PICTURES_DIR="$HOME/Bilder"',
+                'XDG_VIDEOS_DIR="$HOME/Videos"',
+            ].join("\n");
+            fs.writeFileSync(configPath, content);
+
+            assert.strictEqual(
+                getXDGUserDir("XDG_DOWNLOAD_DIR", configPath),
+                path.join(os.homedir(), "MyDownloads")
+            );
+            assert.strictEqual(
+                getXDGUserDir("XDG_MUSIC_DIR", configPath),
+                path.join(os.homedir(), "Musik")
+            );
+            assert.strictEqual(
+                getXDGUserDir("XDG_PICTURES_DIR", configPath),
+                path.join(os.homedir(), "Bilder")
+            );
+        });
+
+        it("returns null when key is not present", () => {
+            const configPath = path.join(tmpDir, "user-dirs.dirs");
+            fs.writeFileSync(configPath, 'XDG_DESKTOP_DIR="$HOME/Desktop"\n');
+            const result = getXDGUserDir("XDG_DOWNLOAD_DIR", configPath);
+            assert.strictEqual(result, null);
+        });
+
+        it("returns null when config file does not exist", () => {
+            const configPath = path.join(tmpDir, "nonexistent");
+            const result = getXDGUserDir("XDG_DOWNLOAD_DIR", configPath);
+            assert.strictEqual(result, null);
+        });
+    });
+
+    describe("getXDGDownloadDir (backward compatibility)", () => {
+        const tmpDir = path.join(os.tmpdir(), "os-user-dirs-test");
+
+        beforeEach(() => {
+            fs.mkdirSync(tmpDir, { recursive: true });
+        });
+
+        afterEach(() => {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        });
+
+        it("parses XDG_DOWNLOAD_DIR with $HOME", () => {
+            const configPath = path.join(tmpDir, "user-dirs.dirs");
+            fs.writeFileSync(configPath, 'XDG_DOWNLOAD_DIR="$HOME/Downloads"\n');
+            const result = getXDGDownloadDir(configPath);
+            assert.strictEqual(result, path.join(os.homedir(), "Downloads"));
+        });
+
+        it("returns null when config file does not exist", () => {
+            const configPath = path.join(tmpDir, "nonexistent");
+            const result = getXDGDownloadDir(configPath);
+            assert.strictEqual(result, null);
+        });
+    });
+});