platformdirs 4.3.6 → 4.3.8-rc1

package/src/macos.js

@@ -0,0 +1,199 @@
+/**
+ * @module
+ * macOS.
+ */
+
+import * as os from "node:os";
+import * as path from "node:path";
+import process from "node:process";
+import { PlatformDirsABC } from "./api.js";
+
+/**
+ * Platform directories for the macOS operating system.
+ *
+ * Follows the guidance from [Apple documentation](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/FileSystemProgrammingGuide/MacOSXDirectories/MacOSXDirectories.html). Makes use of the {@link PlatformDirsABC.appname}, {@link PlatformDirsABC.version}, {@link PlatformDirsABC.ensureExists}.
+ */
+export class MacOS extends PlatformDirsABC {
+	/**
+	 * @return {string} data directory tied to the user, e.g. `~/Library/Application Support/$appname/$version`
+	 * @override
+	 */
+	get userDataDir() {
+		return this._appendAppNameAndVersion(
+			path.join(os.homedir(), "Library/Application Support"),
+		);
+	}
+
+	/**
+	 * @return {string} data directory shared by users, e.g. `/Library/Application
+	 * Support/$appname/$version`. If we're using a Node.js, Deno, or Bun binary
+	 * managed by [Homebrew](https://brew.sh), the directory will be under the
+	 * Homebrew prefix, e.g. `/opt/homebrew/share/$appname/$version`. If
+	 * {@link PlatformDirsABC.multipath} is enabled, and we're in Homebrew, the
+	 * response is a multi-path string separated by ":", e.g.
+	 * `/opt/homebrew/share/$appname/$version:/Library/Application
+	 * Support/$appname/$version`.
+	 * @override
+	 */
+	get siteDataDir() {
+		const isHomebrew = process.execPath.startsWith("/opt/homebrew");
+		const pathList = isHomebrew
+			? [this._appendAppNameAndVersion("/opt/homebrew/share")]
+			: [];
+		pathList.push(
+			this._appendAppNameAndVersion("/Library/Application Support"),
+		);
+		if (this.multipath) {
+			return pathList.join(path.delimiter);
+		}
+		return pathList[0];
+	}
+
+	/**
+	 * @return {string} data path shared by users. Only return the first item, even if
+	 * `multipath` is enabled is set to `true`.
+	 * @override
+	 */
+	get siteDataPath() {
+		return this._firstItemAsPathIfMultipath(this.siteDataDir);
+	}
+
+	/**
+	 * @return {string} config directory tied to the user, same as `userDataDir`
+	 * @override
+	 */
+	get userConfigDir() {
+		return this.userDataDir;
+	}
+
+	/**
+	 * @return {string} config directory shared by users, same as `siteDataDir`
+	 * @override
+	 */
+	get siteConfigDir() {
+		return this.siteDataDir;
+	}
+
+	/**
+	 * @return {string} cache directory tied to the user, e.g. `~/Library/Caches/$appname/$version`
+	 * @override
+	 */
+	get userCacheDir() {
+		return this._appendAppNameAndVersion(
+			path.join(os.homedir(), "Library/Caches"),
+		);
+	}
+
+	/**
+	 * @return {string} cache directory shared by users, e.g. `/Library/Caches/$appname/$version`.
+	 * If we're using a Node.js, Deno, or Bun binary managed by [Homebrew](https://brew.sh),
+	 * the directory will be under the Homebrew prefix, e.g. `/opt/homebrew/var/cache/$appname/$version`.
+	 * If {@link PlatformDirsABC.multipath} is enabled, and we're in Homebrew, the response is a multi-path string separated by ":", e.g.
+	 * `/opt/homebrew/var/cache/$appname/$version:/Library/Caches/$appname/$version`.
+	 * @override
+	 */
+	get siteCacheDir() {
+		const isHomebrew = process.execPath.startsWith("/opt/homebrew");
+		const pathList = isHomebrew
+			? [this._appendAppNameAndVersion("/opt/homebrew/var/cache")]
+			: [];
+		pathList.push(this._appendAppNameAndVersion("/Library/Caches"));
+		if (this.multipath) {
+			return pathList.join(path.delimiter);
+		}
+		return pathList[0];
+	}
+
+	/**
+	 * @return {string} cache path shared by users. Only return the first item, even if
+	 * `multipath` is enabled is set to `true`.
+	 * @override
+	 */
+	get siteCachePath() {
+		return this._firstItemAsPathIfMultipath(this.siteCacheDir);
+	}
+
+	/**
+	 * @return {string} state directory tied to the user, e.g. `~/Library/Application Support/$appname/$version`
+	 * @override
+	 */
+	get userStateDir() {
+		return this.userDataDir;
+	}
+
+	/**
+	 * @return {string} log directory tied to the user, e.g. `~/Library/Logs/$appname/$version`
+	 * @override
+	 */
+	get userLogDir() {
+		return this._appendAppNameAndVersion(
+			path.join(os.homedir(), "Library/Logs"),
+		);
+	}
+
+	/**
+	 * @return {string} documents directory tied to the user, e.g. `~/Documents`
+	 * @override
+	 */
+	get userDocumentsDir() {
+		return path.join(os.homedir(), "Documents");
+	}
+
+	/**
+	 * @return {string} downloads directory tied to the user, e.g. `~/Downloads`
+	 * @override
+	 */
+	get userDownloadsDir() {
+		return path.join(os.homedir(), "Downloads");
+	}
+
+	/**
+	 * @return {string} pictures directory tied to the user, e.g. `~/Pictures`
+	 * @override
+	 */
+	get userPicturesDir() {
+		return path.join(os.homedir(), "Pictures");
+	}
+
+	/**
+	 * @return {string} videos directory tied to the user, e.g. `~/Movies`
+	 * @override
+	 */
+	get userVideosDir() {
+		return path.join(os.homedir(), "Movies");
+	}
+
+	/**
+	 * @return {string} music directory tied to the user, e.g. `~/Music`
+	 * @override
+	 */
+	get userMusicDir() {
+		return path.join(os.homedir(), "Music");
+	}
+
+	/**
+	 * @return {string} desktop directory tied to the user, e.g. `~/Desktop`
+	 * @override
+	 */
+	get userDesktopDir() {
+		return path.join(os.homedir(), "Desktop");
+	}
+
+	/**
+	 * @return {string} runtime directory tied to the user, e.g. `~/Library/Caches/TemporaryItems`
+	 * @override
+	 */
+	get userRuntimeDir() {
+		return this._appendAppNameAndVersion(
+			path.join(os.homedir(), "Library/Caches/TemporaryItems"),
+		);
+	}
+
+	/**
+	 * @return {string} runtime directory shared by users, same as `userRuntimeDir`
+	 * @override
+	 */
+	get siteRuntimeDir() {
+		return this.userRuntimeDir;
+	}
+}

package/src/main.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { PlatformDirs, version } from "./index.js";
+
+/** @type {Record<string, keyof PlatformDirs>} */
+const props = {
+	user_data_dir: "userDataDir",
+	user_config_dir: "userConfigDir",
+	user_cache_dir: "userCacheDir",
+	user_state_dir: "userStateDir",
+	user_log_dir: "userLogDir",
+	user_documents_dir: "userDocumentsDir",
+	user_downloads_dir: "userDownloadsDir",
+	user_pictures_dir: "userPicturesDir",
+	user_videos_dir: "userVideosDir",
+	user_music_dir: "userMusicDir",
+	user_runtime_dir: "userRuntimeDir",
+	site_data_dir: "siteDataDir",
+	site_config_dir: "siteConfigDir",
+	site_cache_dir: "siteCacheDir",
+	site_runtime_dir: "siteRuntimeDir",
+};
+
+const appName = "MyApp";
+const appAuthor = "MyCompany";
+
+console.log(`-- platformdirs ${version} --`);
+
+console.log("-- app dirs (with optional 'version')");
+let dirs = new PlatformDirs(appName, appAuthor, "1.0");
+for (const [label, key] of Object.entries(props)) {
+	console.log(`${label}: ${dirs[key]}`);
+}
+
+console.log("\n-- app dirs (without optional 'version')");
+dirs = new PlatformDirs(appName, appAuthor);
+for (const [label, key] of Object.entries(props)) {
+	console.log(`${label}: ${dirs[key]}`);
+}
+
+console.log("\n-- app dirs (without optional 'appauthor')");
+dirs = new PlatformDirs(appName);
+for (const [label, key] of Object.entries(props)) {
+	console.log(`${label}: ${dirs[key]}`);
+}
+
+console.log("\n-- app dirs (with disabled 'appauthor')");
+dirs = new PlatformDirs(appName, false);
+for (const [label, key] of Object.entries(props)) {
+	console.log(`${label}: ${dirs[key]}`);
+}

package/src/unix.js

@@ -0,0 +1,350 @@
+/**
+ * @module
+ * Unix.
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import process from "node:process";
+import { PlatformDirsABC } from "./api.js";
+import { ConfigParser } from "./configparser.js";
+
+/** @return {number} */
+function getuid() {
+	if (!process.getuid) {
+		throw new Error("should only be used on Unix");
+	}
+	return process.getuid();
+}
+
+/**
+ * On Unix/Linux, we follow the [XDG Basedir
+ * Spec](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
+ *
+ * The spec allows overriding directories via environment variables. The
+ * examples shown are the default values, alongside the name of the environment
+ * variable that overrides them. Makes use of the
+ * {@link PlatformDirsABC.appname}, {@link PlatformDirsABC.version},
+ * {@link PlatformDirsABC.multipath}, {@link PlatformDirsABC.opinion},
+ * {@link PlatformDirsABC.ensureExists}.
+ */
+export class Unix extends PlatformDirsABC {
+	/**
+	 * @return {string} data directory tied to the user, e.g. `~/.local/share/$appname/$version` or `$XDG_DATA_HOME/$appname/$version`
+	 * @override
+	 */
+	get userDataDir() {
+		let path2 = process.env.XDG_DATA_HOME ?? "";
+		if (!path2.trim()) {
+			path2 = path.join(os.homedir(), ".local/share");
+		}
+		return this._appendAppNameAndVersion(path2);
+	}
+
+	/**
+	 * @return {string[]}
+	 * @protected @ignore @internal
+	 */
+	get _siteDataDirs() {
+		let path2 = process.env.XDG_DATA_DIRS ?? "";
+		if (!path2.trim()) {
+			path2 = `/usr/local/share${path.delimiter}/usr/share`;
+		}
+		return path2
+			.split(path.delimiter)
+			.map((p) => this._appendAppNameAndVersion(p));
+	}
+
+	/**
+	 * @return {string} data directories shared by users (if
+	 * {@link PlatformDirsABC.multipath} is enabled and `XDG_DATA_DIRS` is and a
+	 * multi path the response is also a multi path separated by the OS path
+	 * separator), e.g.
+	 * `/usr/local/share/$appname/$version:/usr/share/$appname/$version`
+	 * @override
+	 */
+	get siteDataDir() {
+		const dirs = this._siteDataDirs;
+		if (!this.multipath) {
+			return dirs[0];
+		}
+		return dirs.join(path.delimiter);
+	}
+
+	/**
+	 * @return {string} config directory tied to the user, e.g. `~/.config/$appname/$version` or `$XDG_CONFIG_HOME/$appname/$version`
+	 * @override
+	 */
+	get userConfigDir() {
+		let path2 = process.env.XDG_CONFIG_HOME ?? "";
+		if (!path2.trim()) {
+			path2 = path.join(os.homedir(), ".config");
+		}
+		return this._appendAppNameAndVersion(path2);
+	}
+
+	/**
+	 * @return {string[]}
+	 * @ignore @internal
+	 */
+	get _siteConfigDirs() {
+		let path2 = process.env.XDG_CONFIG_DIRS ?? "";
+		if (!path2.trim()) {
+			path2 = "/etc/xdg";
+		}
+		return path2
+			.split(path.delimiter)
+			.map((p) => this._appendAppNameAndVersion(p));
+	}
+
+	/**
+	 * @return {string} config directories shared by users (if
+	 * {@link PlatformDirsABC.multipath} is enabled and `XDG_CONFIG_DIRS` is and
+	 * a multi path the response is also a multi path separated by the OS path
+	 * separator), e.g. `/etc/xdg/$appname/$version`
+	 * @override
+	 */
+	get siteConfigDir() {
+		const dirs = this._siteConfigDirs;
+		if (!this.multipath) {
+			return dirs[0];
+		}
+		return dirs.join(path.delimiter);
+	}
+
+	/**
+	 * @return {string} cache directory tied to the user, e.g. `~/.cache/$appname/$version` or `$XDG_CACHE_HOME/$appname/$version`
+	 * @override
+	 */
+	get userCacheDir() {
+		let path2 = process.env.XDG_CACHE_HOME ?? "";
+		if (!path2.trim()) {
+			path2 = path.join(os.homedir(), ".cache");
+		}
+		return this._appendAppNameAndVersion(path2);
+	}
+
+	/**
+	 * @return {string} cache directory shared by users, e.g. `/var/cache/$appname/$version`
+	 * @override
+	 */
+	get siteCacheDir() {
+		return this._appendAppNameAndVersion("/var/cache");
+	}
+
+	/**
+	 * @return {string} state directory tied to the user, e.g. `~/.local/state/$appname/$version` or `$XDG_STATE_HOME/$appname/$version`
+	 * @override
+	 */
+	get userStateDir() {
+		let path2 = process.env.XDG_STATE_HOME ?? "";
+		if (!path2.trim()) {
+			path2 = path.join(os.homedir(), ".local/state");
+		}
+		return this._appendAppNameAndVersion(path2);
+	}
+
+	/**
+	 * @return {string} log directory tied to the user, same as `userCacheDir` if not opinionated else `log` in it.
+	 * @override
+	 */
+	get userLogDir() {
+		let path2 = this.userStateDir;
+		if (this.opinion) {
+			path2 = path.join(path2, "log");
+			this._optionallyCreateDirectory(path2);
+		}
+		return path2;
+	}
+
+	/**
+	 * @return {string} documents directory tied to the user, e.g. `~/Documents`
+	 * @override
+	 */
+	get userDocumentsDir() {
+		return getUserMediaDir("XDG_DOCUMENTS_DIR", "~/Documents");
+	}
+
+	/**
+	 * @return {string} downloads directory tied to the user, e.g. `~/Downloads`
+	 * @override
+	 */
+	get userDownloadsDir() {
+		return getUserMediaDir("XDG_DOWNLOAD_DIR", "~/Downloads");
+	}
+
+	/**
+	 * @return {string} pictures directory tied to the user, e.g. `~/Pictures`
+	 * @override
+	 */
+	get userPicturesDir() {
+		return getUserMediaDir("XDG_PICTURES_DIR", "~/Pictures");
+	}
+
+	/**
+	 * @return {string} videos directory tied to the user, e.g. `~/Videos`
+	 * @override
+	 */
+	get userVideosDir() {
+		return getUserMediaDir("XDG_VIDEOS_DIR", "~/Videos");
+	}
+
+	/**
+	 * @return {string} music directory tied to the user, e.g. `~/Music`
+	 * @override
+	 */
+	get userMusicDir() {
+		return getUserMediaDir("XDG_MUSIC_DIR", "~/Music");
+	}
+
+	/**
+	 * @return {string} desktop directory tied to the user, e.g. `~/Desktop`
+	 * @override
+	 */
+	get userDesktopDir() {
+		return getUserMediaDir("XDG_DESKTOP_DIR", "~/Desktop");
+	}
+
+	/**
+	 * @return {string} runtime directory tied to the user, e.g. `/run/user/$(id -u)/$appname/$version` or `$XDG_RUNTIME_DIR/$appname/$version`.
+	 *
+	 * For FreeBSD/OpenBSD/NetBSD, it would return `/var/run/user/$(id -u)/$appname/$version` if it exists, otherwise `/tmp/runtime-$(id -u)/$appname/$version`, if `XDG_RUNTIME_DIR` is not set.
+	 * @override
+	 */
+	get userRuntimeDir() {
+		let path2 = process.env.XDG_RUNTIME_DIR ?? "";
+		if (!path2.trim()) {
+			if (
+				process.platform === "freebsd" ||
+				process.platform === "netbsd" ||
+				process.platform === "openbsd"
+			) {
+				path2 = `/var/run/user/${getuid()}`;
+				if (!fs.existsSync(path2)) {
+					path2 = `/tmp/runtime-${getuid()}`;
+				}
+			} else {
+				path2 = `/run/user/${getuid()}`;
+			}
+		}
+		return this._appendAppNameAndVersion(path2);
+	}
+
+	/**
+	 * @return {string} runtime directory shared by users, e.g. `/run/$appname/$version` or `$XDG_RUNTIME_DIR/$appname/$version`.
+	 *
+	 * Note that this behaves almost exactly like `userRuntimeDir` if `XDG_RUNTIME_DIR` is set, but will fall back to paths associated to the root user isntead of a regular logged-in user if it's not set.
+	 *
+	 * If you wish to ensure that a logged-in user path is returned e.g. `/run/user/0`, use `userRuntimeDir` instead.
+	 *
+	 * For FreeBSD/OpenBSD/NetBSD, it would return `/var/run/$appname/$version` if `XDG_RUNTIME_DIR` is not set.
+	 * @override
+	 */
+	get siteRuntimeDir() {
+		let path2 = process.env.XDG_RUNTIME_DIR ?? "";
+		if (!path2.trim()) {
+			if (
+				process.platform === "freebsd" ||
+				process.platform === "netbsd" ||
+				process.platform === "openbsd"
+			) {
+				path2 = "/var/run";
+			} else {
+				path2 = "/run";
+			}
+		}
+		return this._appendAppNameAndVersion(path2);
+	}
+
+	/**
+	 * @return {string} data path shared by users. Only return the first item, even if `multipath` is set to `true`.
+	 * @override
+	 */
+	get siteDataPath() {
+		return this._firstItemAsPathIfMultipath(this.siteDataDir);
+	}
+
+	/**
+	 * @return {string} config path shared by users. Only return the first item, even if `multipath` is set to `true`.
+	 * @override
+	 */
+	get siteConfigPath() {
+		return this._firstItemAsPathIfMultipath(this.siteConfigDir);
+	}
+
+	/**
+	 * @return {string} cache path shared by users. Only return the first item, even if `multipath` is set to `true`.
+	 * @override
+	 */
+	get siteCachePath() {
+		return this._firstItemAsPathIfMultipath(this.siteCacheDir);
+	}
+
+	/**
+	 * @yields all user and site configuation directories
+	 * @return {Generator<string>}
+	 * @override
+	 */
+	*iterConfigDirs() {
+		yield this.userConfigDir;
+		yield* this._siteConfigDirs;
+	}
+
+	/**
+	 * @yields all user and site data directories
+	 * @return {Generator<string>}
+	 * @override
+	 */
+	*iterDataDirs() {
+		yield this.userDataDir;
+		yield* this._siteDataDirs;
+	}
+}
+
+/**
+ * @param {string} envVar
+ * @param {string} fallbackTildePath
+ * @returns {string}
+ */
+function getUserMediaDir(envVar, fallbackTildePath) {
+	let mediaDir = getUserDirsFolder(envVar);
+	if (mediaDir === undefined) {
+		mediaDir = (process.env[envVar] ?? "").trim();
+		if (!mediaDir) {
+			mediaDir = fallbackTildePath.replace(/^~/, os.homedir());
+		}
+	}
+	return mediaDir;
+}
+
+/**
+ * Return directory from user-dirs.dirs config file.
+ *
+ * See https://freedesktop.org/wiki/Software/xdg-user-dirs/.
+ * 
+ * ⚠️ This function uses **synchronous FS operations**.
+ *
+ * @param {string} key
+ * @returns {string | undefined}
+ */
+function getUserDirsFolder(key) {
+	const userDirsConfigPath = path.join(new Unix().userConfigDir, "user-dirs.dirs");
+	if (fs.existsSync(userDirsConfigPath)) {
+		// This works for now.
+	    const parser = new ConfigParser()
+
+	    const read = fs.readFileSync(userDirsConfigPath, "utf-8")
+	    parser.readString(`[top]\n${read}`)
+
+		const top = parser.get("top");
+	    if (!top || !(Object.hasOwn(top, key))) {
+	        return undefined
+	    }
+
+	    const path2 = top[key].replace(/(^"|"$)/g, "")
+	    return path2.replace("$HOME", os.homedir())
+	}
+
+	return undefined;
+}

package/src/version.js

@@ -0,0 +1,16 @@
+// https://github.com/nodejs/node/issues/51347
+import packageJSON from "../package.json" with { type: "json" };
+
+/**
+ * @param {unknown} error
+ * @return {never}
+ */
+function throwExpression(error) {
+	throw error;
+}
+
+export const version = packageJSON.version;
+const match =
+	packageJSON.version.match(/^(\d+)\.(\d+)\.(\d+)/) ??
+	throwExpression(new Error("unreachable"));
+export const versionTuple = [+match[1], +match[2], +match[3]];