os-user-dirs 2.0.0 → 2.2.0

package/README.md

@@ -18,8 +18,10 @@ $ npm install os-user-dirs
 
 ## Usage
 
+### ESM (recommended)
+
 ```javascript
-const { downloads, desktop, documents, music, pictures, videos, getPath } = require("os-user-dirs");
+import { downloads, desktop, documents, music, pictures, videos, getPath } from "os-user-dirs";
 
 downloads();
 //=> '/home/user/Downloads'
@@ -34,15 +36,40 @@ getPath("music");
 //=> '/home/user/Music'
 ```
 
+### CommonJS
+
+```javascript
+const { downloads, desktop, documents, music, pictures, videos, getPath } = require("os-user-dirs");
+
+downloads();
+//=> '/home/user/Downloads'
+```
+
 ### Default export (backward compatibility)
 
 ```javascript
+// ESM
+import downloads from "os-user-dirs";
+
+// CommonJS
 const downloads = require("os-user-dirs");
 
 downloads();
 //=> '/home/user/Downloads'
 ```
 
+### TypeScript
+
+Full type definitions are included. `getPath()` accepts a union type for auto-completion:
+
+```typescript
+import { getPath } from "os-user-dirs";
+
+getPath("downloads"); // OK
+getPath("desktop");   // OK
+getPath("unknown");   // Type error
+```
+
 ## API
 
 ### `downloads()`

package/index.d.ts

@@ -0,0 +1,49 @@
+type DirName = "desktop" | "downloads" | "documents" | "music" | "pictures" | "videos";
+
+/** Returns the path to the Desktop directory. */
+export function desktop(): string;
+
+/** Returns the path to the Downloads directory. */
+export function downloads(): string;
+
+/** Returns the path to the Documents directory. */
+export function documents(): string;
+
+/** Returns the path to the Music directory. */
+export function music(): string;
+
+/** Returns the path to the Pictures directory. */
+export function pictures(): string;
+
+/** Returns the path to the Videos directory (Movies on macOS). */
+export function videos(): string;
+
+/** Returns the path to the specified user directory. */
+export function getPath(name: DirName): 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")
+ * @param configPath - Optional path to user-dirs.dirs config file
+ * @returns The resolved directory path, or null if not found
+ */
+export function getXDGUserDir(key: string, configPath?: string): string | null;
+
+/**
+ * @deprecated Use `getXDGUserDir("XDG_DOWNLOAD_DIR", configPath)` instead.
+ */
+export function getXDGDownloadDir(configPath?: string): string | null;
+
+declare const osUserDirs: typeof downloads & {
+    downloads: typeof downloads;
+    desktop: typeof desktop;
+    documents: typeof documents;
+    music: typeof music;
+    pictures: typeof pictures;
+    videos: typeof videos;
+    getPath: typeof getPath;
+    getXDGUserDir: typeof getXDGUserDir;
+    getXDGDownloadDir: typeof getXDGDownloadDir;
+};
+
+export default osUserDirs;

package/index.mjs

@@ -0,0 +1,12 @@
+import osUserDirs from './index.js';
+
+export default osUserDirs;
+export const downloads = osUserDirs.downloads;
+export const desktop = osUserDirs.desktop;
+export const documents = osUserDirs.documents;
+export const music = osUserDirs.music;
+export const pictures = osUserDirs.pictures;
+export const videos = osUserDirs.videos;
+export const getPath = osUserDirs.getPath;
+export const getXDGUserDir = osUserDirs.getXDGUserDir;
+export const getXDGDownloadDir = osUserDirs.getXDGDownloadDir;

package/package.json

@@ -1,8 +1,21 @@
 {
   "name": "os-user-dirs",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Get OS-specific user directories (Downloads, Desktop, Documents, Music, Pictures, Videos) with zero dependencies.",
   "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.mjs",
+    "index.d.ts"
+  ],
   "scripts": {
     "test": "mocha test.js"
   },

package/.github/workflows/ci.yml

@@ -1,23 +0,0 @@
-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/test.js

@@ -1,168 +0,0 @@
-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);
-        });
-    });
-});