platformdirs 4.3.6-rc1

package/dist/unix.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @module
+ * Unix.
+ */
+import { PlatformDirsABC } from "./api.js";
+/**
+ * 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 declare class Unix extends PlatformDirsABC {
+    /**
+     * @return data directory tied to the user, e.g. `~/.local/share/$appname/$version` or `$XDG_DATA_HOME/$appname/$version`
+     */
+    get userDataDir(): string;
+    /** @ignore @internal */
+    protected get _siteDataDirs(): string[];
+    /**
+     * @return 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`
+     */
+    get siteDataDir(): string;
+    /**
+     * @return config directory tied to the user, e.g. `~/.config/$appname/$version` or `$XDG_CONFIG_HOME/$appname/$version`
+     */
+    get userConfigDir(): string;
+    /** @ignore @internal */
+    get _siteConfigDirs(): string[];
+    /**
+     * @return 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`
+     */
+    get siteConfigDir(): string;
+    /**
+     * @return cache directory tied to the user, e.g. `~/.cache/$appname/$version` or `$XDG_CACHE_HOME/$appname/$version`
+     */
+    get userCacheDir(): string;
+    /**
+     * @return cache directory shared by users, e.g. `/var/cache/$appname/$version`
+     */
+    get siteCacheDir(): string;
+    /**
+     * @return state directory tied to the user, e.g. `~/.local/state/$appname/$version` or `$XDG_STATE_HOME/$appname/$version`
+     */
+    get userStateDir(): string;
+    /**
+     * @return log directory tied to the user, same as `userCacheDir` if not opinionated else `log` in it.
+     */
+    get userLogDir(): string;
+    /**
+     * @return documents directory tied to the user, e.g. `~/Documents`
+     */
+    get userDocumentsDir(): string;
+    /**
+     * @return downloads directory tied to the user, e.g. `~/Downloads`
+     */
+    get userDownloadsDir(): string;
+    /**
+     * @return pictures directory tied to the user, e.g. `~/Pictures`
+     */
+    get userPicturesDir(): string;
+    /**
+     * @return videos directory tied to the user, e.g. `~/Videos`
+     */
+    get userVideosDir(): string;
+    /**
+     * @return music directory tied to the user, e.g. `~/Music`
+     */
+    get userMusicDir(): string;
+    /**
+     * @return desktop directory tied to the user, e.g. `~/Desktop`
+     */
+    get userDesktopDir(): string;
+    /**
+     * @return 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.
+     */
+    get userRuntimeDir(): string;
+    /**
+     * @return 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.
+     */
+    get siteRuntimeDir(): string;
+    /**
+     * @return data path shared by users. Only return the first item, even if `multipath` is set to `true`.
+     */
+    get siteDataPath(): string;
+    /**
+     * @return config path shared by users. Only return the first item, even if `multipath` is set to `true`.
+     */
+    get siteConfigPath(): string;
+    /**
+     * @return cache path shared by users. Only return the first item, even if `multipath` is set to `true`.
+     */
+    get siteCachePath(): string;
+    /**
+     * @yields all user and site configuation directories
+     */
+    iterConfigDirs(): Generator<string>;
+    /**
+     * @yields all user and site data directories
+     */
+    iterDataDirs(): Generator<string>;
+}

package/dist/unix.js

@@ -0,0 +1,277 @@
+/**
+ * @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";
+function expanduser(path2) {
+    return path2.replace(/^~/, os.homedir());
+}
+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 data directory tied to the user, e.g. `~/.local/share/$appname/$version` or `$XDG_DATA_HOME/$appname/$version`
+     */
+    get userDataDir() {
+        let path2 = process.env.XDG_DATA_HOME ?? "";
+        if (!path2.trim()) {
+            path2 = expanduser("~/.local/share");
+        }
+        return this._appendAppNameAndVersion(path2);
+    }
+    /** @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 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`
+     */
+    get siteDataDir() {
+        const dirs = this._siteDataDirs;
+        if (!this.multipath) {
+            return dirs[0];
+        }
+        return dirs.join(path.delimiter);
+    }
+    /**
+     * @return config directory tied to the user, e.g. `~/.config/$appname/$version` or `$XDG_CONFIG_HOME/$appname/$version`
+     */
+    get userConfigDir() {
+        let path2 = process.env.XDG_CONFIG_HOME ?? "";
+        if (!path2.trim()) {
+            path2 = expanduser("~/.config");
+        }
+        return this._appendAppNameAndVersion(path2);
+    }
+    /** @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 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`
+     */
+    get siteConfigDir() {
+        const dirs = this._siteConfigDirs;
+        if (!this.multipath) {
+            return dirs[0];
+        }
+        return dirs.join(path.delimiter);
+    }
+    /**
+     * @return cache directory tied to the user, e.g. `~/.cache/$appname/$version` or `$XDG_CACHE_HOME/$appname/$version`
+     */
+    get userCacheDir() {
+        let path2 = process.env.XDG_CACHE_HOME ?? "";
+        if (!path2.trim()) {
+            path2 = expanduser("~/.cache");
+        }
+        return this._appendAppNameAndVersion(path2);
+    }
+    /**
+     * @return cache directory shared by users, e.g. `/var/cache/$appname/$version`
+     */
+    get siteCacheDir() {
+        return this._appendAppNameAndVersion("/var/cache");
+    }
+    /**
+     * @return state directory tied to the user, e.g. `~/.local/state/$appname/$version` or `$XDG_STATE_HOME/$appname/$version`
+     */
+    get userStateDir() {
+        let path2 = process.env.XDG_STATE_HOME ?? "";
+        if (!path2.trim()) {
+            path2 = expanduser("~/.local/state");
+        }
+        return this._appendAppNameAndVersion(path2);
+    }
+    /**
+     * @return log directory tied to the user, same as `userCacheDir` if not opinionated else `log` in it.
+     */
+    get userLogDir() {
+        let path2 = this.userStateDir;
+        if (this.opinion) {
+            path2 = path.join(path2, "log");
+            this._optionallyCreateDirectory(path2);
+        }
+        return path2;
+    }
+    /**
+     * @return documents directory tied to the user, e.g. `~/Documents`
+     */
+    get userDocumentsDir() {
+        return getUserMediaDir("XDG_DOCUMENTS_DIR", "~/Documents");
+    }
+    /**
+     * @return downloads directory tied to the user, e.g. `~/Downloads`
+     */
+    get userDownloadsDir() {
+        return getUserMediaDir("XDG_DOWNLOAD_DIR", "~/Downloads");
+    }
+    /**
+     * @return pictures directory tied to the user, e.g. `~/Pictures`
+     */
+    get userPicturesDir() {
+        return getUserMediaDir("XDG_PICTURES_DIR", "~/Pictures");
+    }
+    /**
+     * @return videos directory tied to the user, e.g. `~/Videos`
+     */
+    get userVideosDir() {
+        return getUserMediaDir("XDG_VIDEOS_DIR", "~/Videos");
+    }
+    /**
+     * @return music directory tied to the user, e.g. `~/Music`
+     */
+    get userMusicDir() {
+        return getUserMediaDir("XDG_MUSIC_DIR", "~/Music");
+    }
+    /**
+     * @return desktop directory tied to the user, e.g. `~/Desktop`
+     */
+    get userDesktopDir() {
+        return getUserMediaDir("XDG_DESKTOP_DIR", "~/Desktop");
+    }
+    /**
+     * @return 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.
+     */
+    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 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.
+     */
+    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 data path shared by users. Only return the first item, even if `multipath` is set to `true`.
+     */
+    get siteDataPath() {
+        return this._firstItemAsPathIfMultipath(this.siteDataDir);
+    }
+    /**
+     * @return config path shared by users. Only return the first item, even if `multipath` is set to `true`.
+     */
+    get siteConfigPath() {
+        return this._firstItemAsPathIfMultipath(this.siteConfigDir);
+    }
+    /**
+     * @return cache path shared by users. Only return the first item, even if `multipath` is set to `true`.
+     */
+    get siteCachePath() {
+        return this._firstItemAsPathIfMultipath(this.siteCacheDir);
+    }
+    /**
+     * @yields all user and site configuation directories
+     */
+    *iterConfigDirs() {
+        yield this.userConfigDir;
+        yield* this._siteConfigDirs;
+    }
+    /**
+     * @yields all user and site data directories
+     */
+    *iterDataDirs() {
+        yield this.userDataDir;
+        yield* this._siteDataDirs;
+    }
+}
+function getUserMediaDir(envVar, fallbackTildePath) {
+    let mediaDir = getUserDirsFolder(envVar);
+    if (mediaDir === undefined) {
+        mediaDir = (process.env[envVar] ?? "").trim();
+        if (!mediaDir) {
+            mediaDir = expanduser(fallbackTildePath);
+        }
+    }
+    return mediaDir;
+}
+/**
+ * Return directory from user-dirs.dirs config file.
+ *
+ * See https://freedesktop.org/wiki/Software/xdg-user-dirs/.
+ */
+function getUserDirsFolder(key) {
+    // const userDirsConfigPath = path.join(new Unix().userConfigDir, "user-dirs.dirs");
+    // if (fs.existsSync(userDirsConfigPath)) {
+    //     const parser = new ConfigParser()
+    //     const read = fs.readFileSync(userDirsConfigPath, "utf-8")
+    //     parser.readString(`[top]\n${read}`)
+    //     if (parser.get("top", key) === undefined) {
+    //         return undefined
+    //     }
+    //     const path2 = parser.get("top", key).trim()
+    //     return path2.replace("$HOME", expanduser("~"))
+    // }
+    return undefined;
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const version: string;
+export declare const versionTuple: (string | number)[];

package/dist/version.js

@@ -0,0 +1,24 @@
+import packageJSON from "../package.json" with { type: "json" };
+/**
+ * And one with numbered capture groups instead (so cg1 = major, cg2 = minor,
+ * cg3 = patch, cg4 = prerelease and cg5 = buildmetadata) that is compatible
+ * with ECMA Script (JavaScript), PCRE (Perl Compatible Regular Expressions,
+ * i.e. Perl, PHP and R), Python and Go.
+ *
+ * See: https://regex101.com/r/vkijKf/1/
+ *
+ * @license CC-BY-3.0
+ * @see https://semver.org/
+ */
+const semverRegex = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+export const version = packageJSON.version;
+const match = packageJSON.version.match(semverRegex);
+if (!match) {
+    throw new Error("unreachable");
+}
+export const versionTuple = [
+    +match[0],
+    +match[1],
+    +match[2],
+    ...match.slice(3),
+];

package/dist/windows.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @module
+ * Windows.
+ */
+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 declare class Windows extends PlatformDirsABC {
+    /**
+     * @return data directory tied to the user, e.g. `%USERPROFILE%\AppData\Local\$appauthor\$appname` (not roaming) or `%USERPROFILE%\AppData\Roaming\$appauthor\$appname` (roaming)
+     */
+    get userDataDir(): string;
+    protected _appendParts(path2: string, { opinionValue }?: {
+        opinionValue?: string | undefined;
+    }): string;
+    /**
+     * @return data directory shared by users, e.g. `C:\ProgramData\$appauthor\$appname`
+     */
+    get siteDataDir(): string;
+    /**
+     * @return config directory tied to the user, same as `userDataDir`
+     */
+    get userConfigDir(): string;
+    /**
+     * @return config directory shared by users, same as `siteDataDir`
+     */
+    get siteConfigDir(): string;
+    /**
+     * @return cache directory tied to the user (if opinionated with `Cache` folder within `$appname`) e.g. `%USERPROFILE%\AppData\Local\$appauthor\$appname\Cache\$version`
+     */
+    get userCacheDir(): string;
+    /**
+     * @return cache directory shared by users, e.g. `C:\ProgramData\$appauthor\$appname\Cache\$version`
+     */
+    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
+     */
+    get userLogDir(): string;
+    /**
+     * @return documents directory tied to the user, e.g. `%USERPROFILE%\Documents`
+     */
+    get userDocumentsDir(): string;
+    /**
+     * @return downloads directory tied to the user, e.g. `%USERPROFILE%\Downloads`
+     */
+    get userDownloadsDir(): string;
+    /**
+     * @return pictures directory tied to the user, e.g. `%USERPROFILE%\Pictures`
+     */
+    get userPicturesDir(): string;
+    /**
+     * @return videos directory tied to the user, e.g. `%USERPROFILE%\Videos`
+     */
+    get userVideosDir(): string;
+    /**
+     * @return music directory tied to the user, e.g. `%USERPROFILE%\Music`
+     */
+    get userMusicDir(): string;
+    /**
+     * @return desktop directory tied to the user, e.g. `%USERPROFILE%\Desktop`
+     */
+    get userDesktopDir(): string;
+    /**
+     * @return runtime directory tied to the user, e.g. `%USERPROFILE%\AppData\Local\Temp\$appauthor\$appname`
+     */
+    get userRuntimeDir(): string;
+    /**
+     * @return runtime directory shared by users, same as `userRuntimeDir`
+     */
+    get siteRuntimeDir(): string;
+}