platformdirs 4.3.6 → 4.3.7

package/dist/android.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @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

@@ -0,0 +1,142 @@
+/**
+ * @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");
+}

package/dist/api.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Base API.
+ * @module
+ */
+/**
+ * Abstract base class for platform directories.
+ */
+export declare abstract class PlatformDirsABC {
+    /**
+     * The name of the application.
+     */
+    appname: string | undefined;
+    /**
+     * The name of the app author or distributing body for this application.
+     *
+     * Typically it is the owning company name. Defaults to `appname`. You may pass `false` to disable it.
+     */
+    appauthor: string | false | undefined;
+    /**
+     * An optional version path element to append to the path.
+     *
+     * You might want to use this if you want multiple versions of your app to be able to run independently. If used, this would typically be `<major>.<minor>`.
+     */
+    version: string | undefined;
+    /**
+     * Whether to use the roaming appdata directory on Windows.
+     *
+     * That means that for users on a Windows network setup for roaming profiles, this user data will be synced on login (see [here](https://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx)).
+     */
+    roaming: boolean;
+    /**
+     * An optional parameter which indicates that the entire list of data dirs should be returned.
+     *
+     * By default, the first item would only be returned.
+     */
+    multipath: boolean;
+    /**
+     * A flag to indicating to use opinionated values.
+     */
+    opinion: boolean;
+    /**
+     * Optionally create the directory (and any missing parents) upon access if
+     * it does not exist.
+     *
+     * By default, no directories are created.
+     *
+     * ⚠️ Since the getters (`dirs.userDataDir`, etc.) are synchronous, the
+     * directory creation will use `fs.mkdirSync()` which **is a blocking
+     * synchronous operation** to ensure that the returned path does indeed
+     * exist before returning the path to the caller. This is for convenience.
+     * If you require non-blocking async operation you should set this to
+     * `false` and use `fs.mkdir()` or `fsPromises.mkdir()` yourself.
+     */
+    ensureExists: boolean;
+    /**
+     * Create a new platform directory.
+     * @param appname See `appname`
+     * @param appauthor See `appauthor`
+     * @param version See `version`
+     * @param roaming See `roaming`
+     * @param multipath See `multipath`
+     * @param opinion See `opinion`
+     * @param ensureExists See `ensureExists`
+     */
+    constructor(appname?: string, appauthor?: string | false, version?: string, roaming?: boolean, multipath?: boolean, opinion?: boolean, ensureExists?: boolean);
+    /** @ignore @internal */
+    protected _appendAppNameAndVersion(...base: string[]): string;
+    /** @ignore @internal */
+    protected _optionallyCreateDirectory(dir: string): void;
+    /** @ignore @internal */
+    protected _firstItemAsPathIfMultipath(directory: string): string;
+    /**
+     * @return data directory tied to the user
+     */
+    abstract get userDataDir(): string;
+    /**
+     * @return data directory shared by users
+     */
+    abstract get siteDataDir(): string;
+    /**
+     * @return config directory tied to the user
+     */
+    abstract get userConfigDir(): string;
+    /**
+     * @return config directory shared by users
+     */
+    abstract get siteConfigDir(): string;
+    /**
+     * @return cache directory tied to the user
+     */
+    abstract get userCacheDir(): string;
+    /**
+     * @return cache directory shared by users
+     */
+    abstract get siteCacheDir(): string;
+    /**
+     * @return state directory tied to the user
+     */
+    abstract get userStateDir(): string;
+    /**
+     * @return log directory tied to the user
+     */
+    abstract get userLogDir(): string;
+    /**
+     * @return documents directory tied to the user
+     */
+    abstract get userDocumentsDir(): string;
+    /**
+     * @return downloads directory tied to the user
+     */
+    abstract get userDownloadsDir(): string;
+    /**
+     * @return pictures directory tied to the user
+     */
+    abstract get userPicturesDir(): string;
+    /**
+     * @return videos directory tied to the user
+     */
+    abstract get userVideosDir(): string;
+    /**
+     * @return music directory tied to the user
+     */
+    abstract get userMusicDir(): string;
+    /**
+     * @return desktop directory tied to the user
+     */
+    abstract get userDesktopDir(): string;
+    /**
+     * @return runtime directory tied to the user
+     */
+    abstract get userRuntimeDir(): string;
+    /**
+     * @return runtime directory shared by users
+     */
+    abstract get siteRuntimeDir(): string;
+    /**
+     * @return data path tied to the user
+     */
+    get userDataPath(): string;
+    /**
+     * @return data path shared by users
+     */
+    get siteDataPath(): string;
+    /**
+     * @return config path tied to the user
+     */
+    get userConfigPath(): string;
+    /**
+     * @return config path shared by users
+     */
+    get siteConfigPath(): string;
+    /**
+     * @return cache path tied to the user
+     */
+    get userCachePath(): string;
+    /**
+     * @return cache path shared by users
+     */
+    get siteCachePath(): string;
+    /**
+     * @return state path tied to the user
+     */
+    get userStatePath(): string;
+    /**
+     * @return log path tied to the user
+     */
+    get userLogPath(): string;
+    /**
+     * @return documents path tied to the user
+     */
+    get userDocumentsPath(): string;
+    /**
+     * @return downloads path tied to the user
+     */
+    get userDownloadsPath(): string;
+    /**
+     * @return pictures path tied to the user
+     */
+    get userPicturesPath(): string;
+    /**
+     * @return videos path tied to the user
+     */
+    get userVideosPath(): string;
+    /**
+     * @return music path tied to the user
+     */
+    get userMusicPath(): string;
+    /**
+     * @return desktop path tied to the user
+     */
+    get userDesktopPath(): string;
+    /**
+     * @return runtime path tied to the user
+     */
+    get userRuntimePath(): string;
+    /**
+     * @return runtime path shared by users
+     */
+    get siteRuntimePath(): string;
+    /**
+     * @yields all user and site configuration directories
+     */
+    iterConfigDirs(): Generator<string>;
+    /**
+     * @yields all user and site data directories
+     */
+    iterDataDirs(): Generator<string>;
+    /**
+     * @yields all user and site cache directories
+     */
+    iterCacheDirs(): Generator<string>;
+    /**
+     * @yields all user and site runtime directories
+     */
+    iterRuntimeDirs(): Generator<string>;
+    /**
+     * @yields all user and site state directories
+     */
+    iterConfigPaths(): Generator<string>;
+    /**
+     * @yields all user and site data directories
+     */
+    iterDataPaths(): Generator<string>;
+    /**
+     * @yields all user and site cache directories
+     */
+    iterCachePaths(): Generator<string>;
+    /**
+     * @yields all user and site runtime directories
+     */
+    iterRuntimePaths(): Generator<string>;
+}

package/dist/api.js

@@ -0,0 +1,250 @@
+/**
+ * Base API.
+ * @module
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * Abstract base class for platform directories.
+ */
+export class PlatformDirsABC {
+    /**
+     * The name of the application.
+     */
+    appname;
+    /**
+     * The name of the app author or distributing body for this application.
+     *
+     * Typically it is the owning company name. Defaults to `appname`. You may pass `false` to disable it.
+     */
+    appauthor;
+    /**
+     * An optional version path element to append to the path.
+     *
+     * You might want to use this if you want multiple versions of your app to be able to run independently. If used, this would typically be `<major>.<minor>`.
+     */
+    version;
+    /**
+     * Whether to use the roaming appdata directory on Windows.
+     *
+     * That means that for users on a Windows network setup for roaming profiles, this user data will be synced on login (see [here](https://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx)).
+     */
+    roaming;
+    /**
+     * An optional parameter which indicates that the entire list of data dirs should be returned.
+     *
+     * By default, the first item would only be returned.
+     */
+    multipath;
+    /**
+     * A flag to indicating to use opinionated values.
+     */
+    opinion;
+    /**
+     * Optionally create the directory (and any missing parents) upon access if
+     * it does not exist.
+     *
+     * By default, no directories are created.
+     *
+     * ⚠️ Since the getters (`dirs.userDataDir`, etc.) are synchronous, the
+     * directory creation will use `fs.mkdirSync()` which **is a blocking
+     * synchronous operation** to ensure that the returned path does indeed
+     * exist before returning the path to the caller. This is for convenience.
+     * If you require non-blocking async operation you should set this to
+     * `false` and use `fs.mkdir()` or `fsPromises.mkdir()` yourself.
+     */
+    ensureExists;
+    /**
+     * Create a new platform directory.
+     * @param appname See `appname`
+     * @param appauthor See `appauthor`
+     * @param version See `version`
+     * @param roaming See `roaming`
+     * @param multipath See `multipath`
+     * @param opinion See `opinion`
+     * @param ensureExists See `ensureExists`
+     */
+    constructor(appname, appauthor, version, roaming = false, multipath = false, opinion = true, ensureExists = false) {
+        this.appname = appname;
+        this.appauthor = appauthor;
+        this.version = version;
+        this.roaming = roaming;
+        this.multipath = multipath;
+        this.opinion = opinion;
+        this.ensureExists = ensureExists;
+    }
+    /** @ignore @internal */
+    _appendAppNameAndVersion(...base) {
+        const params = base.slice(1);
+        if (this.appname) {
+            params.push(this.appname);
+            if (this.version) {
+                params.push(this.version);
+            }
+        }
+        const path2 = path.join(base[0], ...params);
+        this._optionallyCreateDirectory(path2);
+        return path2;
+    }
+    /** @ignore @internal */
+    _optionallyCreateDirectory(dir) {
+        if (this.ensureExists) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+    }
+    /** @ignore @internal */
+    _firstItemAsPathIfMultipath(directory) {
+        if (this.multipath) {
+            return directory.split(path.delimiter)[0];
+        }
+        return directory;
+    }
+    /**
+     * @return data path tied to the user
+     */
+    get userDataPath() {
+        return this.userDataDir;
+    }
+    /**
+     * @return data path shared by users
+     */
+    get siteDataPath() {
+        return this.siteDataDir;
+    }
+    /**
+     * @return config path tied to the user
+     */
+    get userConfigPath() {
+        return this.userConfigDir;
+    }
+    /**
+     * @return config path shared by users
+     */
+    get siteConfigPath() {
+        return this.siteConfigDir;
+    }
+    /**
+     * @return cache path tied to the user
+     */
+    get userCachePath() {
+        return this.userCacheDir;
+    }
+    /**
+     * @return cache path shared by users
+     */
+    get siteCachePath() {
+        return this.siteCacheDir;
+    }
+    /**
+     * @return state path tied to the user
+     */
+    get userStatePath() {
+        return this.userStateDir;
+    }
+    /**
+     * @return log path tied to the user
+     */
+    get userLogPath() {
+        return this.userLogDir;
+    }
+    /**
+     * @return documents path tied to the user
+     */
+    get userDocumentsPath() {
+        return this.userDocumentsDir;
+    }
+    /**
+     * @return downloads path tied to the user
+     */
+    get userDownloadsPath() {
+        return this.userDownloadsDir;
+    }
+    /**
+     * @return pictures path tied to the user
+     */
+    get userPicturesPath() {
+        return this.userPicturesDir;
+    }
+    /**
+     * @return videos path tied to the user
+     */
+    get userVideosPath() {
+        return this.userVideosDir;
+    }
+    /**
+     * @return music path tied to the user
+     */
+    get userMusicPath() {
+        return this.userMusicDir;
+    }
+    /**
+     * @return desktop path tied to the user
+     */
+    get userDesktopPath() {
+        return this.userDesktopDir;
+    }
+    /**
+     * @return runtime path tied to the user
+     */
+    get userRuntimePath() {
+        return this.userRuntimeDir;
+    }
+    /**
+     * @return runtime path shared by users
+     */
+    get siteRuntimePath() {
+        return this.siteRuntimeDir;
+    }
+    /**
+     * @yields all user and site configuration directories
+     */
+    *iterConfigDirs() {
+        yield this.userConfigDir;
+        yield this.siteConfigDir;
+    }
+    /**
+     * @yields all user and site data directories
+     */
+    *iterDataDirs() {
+        yield this.userDataDir;
+        yield this.siteDataDir;
+    }
+    /**
+     * @yields all user and site cache directories
+     */
+    *iterCacheDirs() {
+        yield this.userCacheDir;
+        yield this.siteCacheDir;
+    }
+    /**
+     * @yields all user and site runtime directories
+     */
+    *iterRuntimeDirs() {
+        yield this.userRuntimeDir;
+        yield this.siteRuntimeDir;
+    }
+    /**
+     * @yields all user and site state directories
+     */
+    *iterConfigPaths() {
+        yield* this.iterConfigDirs();
+    }
+    /**
+     * @yields all user and site data directories
+     */
+    *iterDataPaths() {
+        yield* this.iterDataDirs();
+    }
+    /**
+     * @yields all user and site cache directories
+     */
+    *iterCachePaths() {
+        yield* this.iterCacheDirs();
+    }
+    /**
+     * @yields all user and site runtime directories
+     */
+    *iterRuntimePaths() {
+        yield* this.iterRuntimeDirs();
+    }
+}