platformdirs 4.3.7 → 4.3.8-rc1

package/src/windows.js

@@ -0,0 +1,279 @@
+/**
+ * @module
+ * Windows.
+ */
+
+import * as path from "node:path";
+import process from "node:process";
+import { PlatformDirsABC } from "./api.js";
+
+/**
+ * [MSDN on where to store app data
+ * files](https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid)
+ *
+ * Makes use of the {@link PlatformDirsABC.appname},
+ * {@link PlatformDirsABC.appauthor}, {@link PlatformDirsABC.version},
+ * {@link PlatformDirsABC.roaming}, {@link PlatformDirsABC.opinion},
+ * {@link PlatformDirsABC.ensureExists}.
+ */
+export class Windows extends PlatformDirsABC {
+	/**
+	 * @return {string} data directory tied to the user, e.g. `%USERPROFILE%\AppData\Local\$appauthor\$appname` (not roaming) or `%USERPROFILE%\AppData\Roaming\$appauthor\$appname` (roaming)
+	 * @override
+	 */
+	get userDataDir() {
+		const const2 = this.roaming ? "CSIDL_APPDATA" : "CSIDL_LOCAL_APPDATA";
+		const path2 = path.normalize(getWinFolder(const2));
+		return this._appendParts(path2);
+	}
+
+	/**
+	 * @protected
+	 * @param {string} path2
+	 * @param {{ opinionValue?: string | undefined }} [param1]
+	 * @return {string}
+	 */
+	_appendParts(path2, { opinionValue } = {}) {
+		const params = [];
+		if (this.appname) {
+			if (this.appauthor !== false) {
+				const author = this.appauthor || this.appname;
+				params.push(author);
+			}
+			params.push(this.appname);
+			if (opinionValue !== undefined && this.opinion) {
+				params.push(opinionValue);
+			}
+			if (this.version) {
+				params.push(this.version);
+			}
+		}
+		const path3 = path.join(path2, ...params);
+		this._optionallyCreateDirectory(path3);
+		return path3;
+	}
+
+	/**
+	 * @return {string} data directory shared by users, e.g. `C:\ProgramData\$appauthor\$appname`
+	 * @override
+	 */
+	get siteDataDir() {
+		const path2 = path.normalize(getWinFolder("CSIDL_COMMON_APPDATA"));
+		return this._appendParts(path2);
+	}
+
+	/**
+	 * @override
+	 * @return {string} config directory tied to the user, same as `userDataDir`
+	 */
+	get userConfigDir() {
+		return this.userDataDir;
+	}
+
+	/**
+	 * @return {string} config directory shared by users, same as `siteDataDir`
+	 * @override
+	 */
+	get siteConfigDir() {
+		return this.siteDataDir;
+	}
+
+	/**
+	 * @override
+	 * @return {string} cache directory tied to the user (if opinionated with `Cache` folder within `$appname`) e.g. `%USERPROFILE%\AppData\Local\$appauthor\$appname\Cache\$version`
+	 */
+	get userCacheDir() {
+		const path2 = path.normalize(getWinFolder("CSIDL_LOCAL_APPDATA"));
+		return this._appendParts(path2, { opinionValue: "Cache" });
+	}
+
+	/**
+	 * @override
+	 * @return {string} cache directory shared by users, e.g. `C:\ProgramData\$appauthor\$appname\Cache\$version`
+	 */
+	get siteCacheDir() {
+		const path2 = path.normalize(getWinFolder("CSIDL_COMMON_APPDATA"));
+		return this._appendParts(path2, { opinionValue: "Cache" });
+	}
+
+	/**
+	 * @override
+	 * @return {string} state directory tied to the user, same as `userDataDir`
+	 */
+	get userStateDir() {
+		return this.userDataDir;
+	}
+
+	/**
+	 * @override
+	 * @return {string} log directory tied to the user, same as `userCacheDir` if not opinionated else `log` in it
+	 */
+	get userLogDir() {
+		let path2 = this.userDataDir;
+		if (this.opinion) {
+			path2 = path.join(path2, "Logs");
+			this._optionallyCreateDirectory(path2);
+		}
+		return path2;
+	}
+
+	/**
+	 * @return {string} documents directory tied to the user, e.g. `%USERPROFILE%\Documents`
+	 * @override
+	 */
+	get userDocumentsDir() {
+		return path.normalize(getWinFolder("CSIDL_PERSONAL"));
+	}
+
+	/**
+	 * @override
+	 * @return {string} downloads directory tied to the user, e.g. `%USERPROFILE%\Downloads`
+	 */
+	get userDownloadsDir() {
+		return path.normalize(getWinFolder("CSIDL_DOWNLOADS"));
+	}
+
+	/**
+	 * @override
+	 * @return {string} pictures directory tied to the user, e.g. `%USERPROFILE%\Pictures`
+	 */
+	get userPicturesDir() {
+		return path.normalize(getWinFolder("CSIDL_MYPICTURES"));
+	}
+
+	/**
+	 * @override
+	 * @return {string} videos directory tied to the user, e.g. `%USERPROFILE%\Videos`
+	 */
+	get userVideosDir() {
+		return path.normalize(getWinFolder("CSIDL_MYVIDEO"));
+	}
+
+	/**
+	 * @override
+	 * @return {string} music directory tied to the user, e.g. `%USERPROFILE%\Music`
+	 */
+	get userMusicDir() {
+		return path.normalize(getWinFolder("CSIDL_MYMUSIC"));
+	}
+
+	/**
+	 * @override
+	 * @return {string} desktop directory tied to the user, e.g. `%USERPROFILE%\Desktop`
+	 */
+	get userDesktopDir() {
+		return path.normalize(getWinFolder("CSIDL_DESKTOPDIRECTORY"));
+	}
+
+	/**
+	 * @override
+	 * @return {string} runtime directory tied to the user, e.g. `%USERPROFILE%\AppData\Local\Temp\$appauthor\$appname`
+	 */
+	get userRuntimeDir() {
+		const path2 = path.normalize(
+			path.join(getWinFolder("CSIDL_LOCAL_APPDATA"), "Temp"),
+		);
+		return this._appendParts(path2);
+	}
+
+	/**
+	 * @override
+	 * @return {string} runtime directory shared by users, same as `userRuntimeDir`
+	 */
+	get siteRuntimeDir() {
+		return this.userRuntimeDir;
+	}
+}
+
+/**
+ * Get folder from environment variable
+ * @param {string} csidlName
+ * @return {string}
+ */
+function getWinFolderFromEnvVars(csidlName) {
+	let result = getWinFolderIfCSIDLNameNotEnvVar(csidlName);
+	if (result !== undefined) {
+		return result;
+	}
+
+	if (csidlName === "CSIDL_APPDATA") {
+		result = process.env.APPDATA;
+		if (result === undefined) {
+			throw new Error("Unset environment variable: APPDATA");
+		}
+	} else if (csidlName === "CSIDL_COMMON_APPDATA") {
+		result = process.env.ALLUSERSPROFILE;
+		if (result === undefined) {
+			throw new Error("Unset environment variable: ALLUSERSPROFILE");
+		}
+	} else if (csidlName === "CSIDL_LOCAL_APPDATA") {
+		result = process.env.LOCALAPPDATA;
+		if (result === undefined) {
+			throw new Error("Unset environment variable: LOCALAPPDATA");
+		}
+	} else {
+		throw new Error(`Unknown CSIDL name: ${csidlName}`);
+	}
+	return result;
+}
+
+/**
+ * Get a folder for a CSIDL name that does not exist as an environment variable.
+ * @param {string} csidlName
+ * @return {string | undefined}
+ */
+function getWinFolderIfCSIDLNameNotEnvVar(csidlName) {
+	if (csidlName === "CSIDL_PERSONAL") {
+		const p = process.env.USERPROFILE;
+		if (p === undefined) {
+			throw new Error("Unset environment variable: USERPROFILE");
+		}
+		return path.join(path.normalize(p), "Documents");
+	}
+	if (csidlName === "CSIDL_DOWNLOADS") {
+		const p = process.env.USERPROFILE;
+		if (p === undefined) {
+			throw new Error("Unset environment variable: USERPROFILE");
+		}
+		return path.join(path.normalize(p), "Downloads");
+	}
+	if (csidlName === "CSIDL_MYPICTURES") {
+		const p = process.env.USERPROFILE;
+		if (p === undefined) {
+			throw new Error("Unset environment variable: USERPROFILE");
+		}
+		return path.join(path.normalize(p), "Pictures");
+	}
+	if (csidlName === "CSIDL_MYVIDEO") {
+		const p = process.env.USERPROFILE;
+		if (p === undefined) {
+			throw new Error("Unset environment variable: USERPROFILE");
+		}
+		return path.join(path.normalize(p), "Videos");
+	}
+	if (csidlName === "CSIDL_MYMUSIC") {
+		const p = process.env.USERPROFILE;
+		if (p === undefined) {
+			throw new Error("Unset environment variable: USERPROFILE");
+		}
+		return path.join(path.normalize(p), "Music");
+	}
+	return undefined;
+}
+
+// function getWinFolderFromRegistry(csidlName: string): string {
+//   throw new Error("Not implemented");
+// }
+
+// function getWinFolderViaCTypes(csidlName: string): string {
+//   throw new Error("Not implemented");
+// }
+
+/**
+ * @returns {(csidlName: string) => string}
+ */
+function pickGetWinFolder() {
+	return getWinFolderFromEnvVars;
+}
+
+const getWinFolder = pickGetWinFolder();

package/dist/android.d.ts

@@ -1,81 +0,0 @@
-/**
- * @module
- * Android.
- *
- * TODO: Implement this module.
- */
-import { PlatformDirsABC } from "./api.js";
-/**
- * Follows the guidance [from here](https://android.stackexchange.com/a/216132).
- *
- * Makes use of the {@link PlatformDirsABC.appname},
- * {@link PlatformDirsABC.version}, {@link PlatformDirsABC.ensureExists}.
- */
-export declare class Android extends PlatformDirsABC {
-    /**
-     * @return data directory tied to the user, e.g. `/data/user/<userid>/<packagename>/files/<AppName>`
-     */
-    get userDataDir(): string;
-    /**
-     * @return data directory shared by users, same as `userDataDir`
-     */
-    get siteDataDir(): string;
-    /**
-     * @return config directory tied to the user, e.g. `/data/user/<userid>/<packagename>/shared_prefs/<AppName>`
-     */
-    get userConfigDir(): string;
-    /**
-     * @return config directory shared by users, same as `userConfigDir`
-     */
-    get siteConfigDir(): string;
-    /**
-     * @return cache directory tied to the user, e.g. `/data/user/<userid>/<packagename>/cache/<AppName>`
-     */
-    get userCacheDir(): string;
-    /**
-     * @return cache directory shared by users, same as `userCacheDir`
-     */
-    get siteCacheDir(): string;
-    /**
-     * @return state directory tied to the user, same as `userDataDir`
-     */
-    get userStateDir(): string;
-    /**
-     * @return log directory tied to the user, same as `userCacheDir` if not opinionated else `log` in it, e.g. `/data/user/<userid>/<packagename>/cache/<AppName>/log`
-     */
-    get userLogDir(): string;
-    /**
-     * @return documents directory tied to the user, e.g. `/storage/emulated/0/Documents`
-     */
-    get userDocumentsDir(): string;
-    /**
-     * @return downloads directory tied to the user, e.g. `/storage/emulated/0/Downloads`
-     */
-    get userDownloadsDir(): string;
-    /**
-     * @return pictures directory tied to the user, e.g. `/storage/emulated/0/Pictures`
-     */
-    get userPicturesDir(): string;
-    /**
-     * @return videos directory tied to the user, e.g. `/storage/emulated/0/Movies`
-     */
-    get userVideosDir(): string;
-    /**
-     * @return music directory tied to the user, e.g. `/storage/emulated/0/Music`
-     */
-    get userMusicDir(): string;
-    /**
-     * @return desktop directory tied to the user, e.g. `/storage/emulated/0/Desktop`
-     */
-    get userDesktopDir(): string;
-    /**
-     * @return runtime directory tied to the user, same as `userCacheDir` if not opinionated else `tmp` in it, e.g. `/data/user/<userid>/<packagename>/cache/<AppName>/tmp`
-     */
-    get userRuntimeDir(): string;
-    /**
-     * @return runtime directory shared by users, same as `userRuntimeDir`
-     */
-    get siteRuntimeDir(): string;
-}
-/** @ignore @internal */
-export declare function _androidFolder(): string | undefined;

package/dist/android.js

@@ -1,142 +0,0 @@
-/**
- * @module
- * Android.
- *
- * TODO: Implement this module.
- */
-import * as path from "node:path";
-import { PlatformDirsABC } from "./api.js";
-function throw2(error) {
-    throw error;
-}
-/**
- * Follows the guidance [from here](https://android.stackexchange.com/a/216132).
- *
- * Makes use of the {@link PlatformDirsABC.appname},
- * {@link PlatformDirsABC.version}, {@link PlatformDirsABC.ensureExists}.
- */
-export class Android extends PlatformDirsABC {
-    /**
-     * @return data directory tied to the user, e.g. `/data/user/<userid>/<packagename>/files/<AppName>`
-     */
-    get userDataDir() {
-        return this._appendAppNameAndVersion(_androidFolder() ?? throw2(new Error("unreachable")), "files");
-    }
-    /**
-     * @return data directory shared by users, same as `userDataDir`
-     */
-    get siteDataDir() {
-        return this.userDataDir;
-    }
-    /**
-     * @return config directory tied to the user, e.g. `/data/user/<userid>/<packagename>/shared_prefs/<AppName>`
-     */
-    get userConfigDir() {
-        return this._appendAppNameAndVersion(_androidFolder() ?? throw2(new Error("unreachable")), "shared_prefs");
-    }
-    /**
-     * @return config directory shared by users, same as `userConfigDir`
-     */
-    get siteConfigDir() {
-        return this.userConfigDir;
-    }
-    /**
-     * @return cache directory tied to the user, e.g. `/data/user/<userid>/<packagename>/cache/<AppName>`
-     */
-    get userCacheDir() {
-        return this._appendAppNameAndVersion(_androidFolder() ?? throw2(new Error("unreachable")), "cache");
-    }
-    /**
-     * @return cache directory shared by users, same as `userCacheDir`
-     */
-    get siteCacheDir() {
-        return this.userCacheDir;
-    }
-    /**
-     * @return state directory tied to the user, same as `userDataDir`
-     */
-    get userStateDir() {
-        return this.userDataDir;
-    }
-    /**
-     * @return log directory tied to the user, same as `userCacheDir` if not opinionated else `log` in it, e.g. `/data/user/<userid>/<packagename>/cache/<AppName>/log`
-     */
-    get userLogDir() {
-        let path2 = this.userCacheDir;
-        if (this.opinion) {
-            path2 = path.join(path2, "log");
-        }
-        return path2;
-    }
-    /**
-     * @return documents directory tied to the user, e.g. `/storage/emulated/0/Documents`
-     */
-    get userDocumentsDir() {
-        return androidDocumentsFolder();
-    }
-    /**
-     * @return downloads directory tied to the user, e.g. `/storage/emulated/0/Downloads`
-     */
-    get userDownloadsDir() {
-        return androidDownloadsFolder();
-    }
-    /**
-     * @return pictures directory tied to the user, e.g. `/storage/emulated/0/Pictures`
-     */
-    get userPicturesDir() {
-        return androidPicturesFolder();
-    }
-    /**
-     * @return videos directory tied to the user, e.g. `/storage/emulated/0/Movies`
-     */
-    get userVideosDir() {
-        return androidVideosFolder();
-    }
-    /**
-     * @return music directory tied to the user, e.g. `/storage/emulated/0/Music`
-     */
-    get userMusicDir() {
-        return androidMusicFolder();
-    }
-    /**
-     * @return desktop directory tied to the user, e.g. `/storage/emulated/0/Desktop`
-     */
-    get userDesktopDir() {
-        return "/storage/emulated/0/Desktop";
-    }
-    /**
-     * @return runtime directory tied to the user, same as `userCacheDir` if not opinionated else `tmp` in it, e.g. `/data/user/<userid>/<packagename>/cache/<AppName>/tmp`
-     */
-    get userRuntimeDir() {
-        let path2 = this.userCacheDir;
-        if (this.opinion) {
-            path2 = path.join(path2, "tmp");
-        }
-        return path2;
-    }
-    /**
-     * @return runtime directory shared by users, same as `userRuntimeDir`
-     */
-    get siteRuntimeDir() {
-        return this.userRuntimeDir;
-    }
-}
-/** @ignore @internal */
-export function _androidFolder() {
-    throw new Error("Not implemented");
-}
-function androidDocumentsFolder() {
-    throw new Error("Not implemented");
-}
-function androidDownloadsFolder() {
-    throw new Error("Not implemented");
-}
-function androidPicturesFolder() {
-    throw new Error("Not implemented");
-}
-function androidVideosFolder() {
-    throw new Error("Not implemented");
-}
-function androidMusicFolder() {
-    throw new Error("Not implemented");
-}