platformdirs 4.3.6-rc1

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();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,238 @@
+/**
+ * @module
+ *
+ * platformdirs is a library to determine platform-specific system directories. This includes directories where to place cache files, user data, configuration, etc.
+ *
+ * The source code and issue tracker are both hosted on [GitHub](https://github.com/jcbhmr/platformdirs.js).
+ *
+ * Utilities for determining application-specific dirs.
+ *
+ * See https://github.com/platformdirs/platformdirs for details and usage.
+ */
+import type { Android } from "./android.js";
+import type { MacOS } from "./macos.js";
+import type { Unix } from "./unix.js";
+import type { Windows } from "./windows.js";
+export type PlatformDirs = Windows | MacOS | Unix | Android;
+export declare const PlatformDirs: typeof Windows | typeof MacOS | typeof Unix | typeof Android;
+export declare const AppDirs: typeof Windows | typeof MacOS | typeof Unix | typeof Android;
+/**
+ *
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param roaming See {@link PlatformDirs.roaming}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns data directory tied to the user
+ */
+export declare function userDataDir(appname?: string, appauthor?: string | false, version?: string, roaming?: boolean, ensureExists?: boolean): string;
+/**
+ *
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param multipath See {@link PlatformDirs.multipath}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns data directory shared by users
+ */
+export declare function siteDataDir(appname?: string, appauthor?: string | false, version?: string, multipath?: boolean, ensureExists?: boolean): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param roaming See {@link PlatformDirs.roaming}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns config directory tied to the user
+ */
+export declare function userConfigDir(appname?: string, appauthor?: string | false, version?: string, roaming?: boolean, ensureExists?: boolean): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param multipath See {@link PlatformDirs.multipath}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns config directory shared by users
+ */
+export declare function siteConfigDir(appname?: string, appauthor?: string | false, version?: string, multipath?: boolean, ensureExists?: boolean): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param opinion See {@link PlatformDirs.opinion}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns cache directory tied to the user
+ */
+export declare function userCacheDir(appname?: string, appauthor?: string | false, version?: string, opinion?: boolean, ensureExists?: boolean): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param opinion See {@link PlatformDirs.opinion}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns cache directory tied to the user
+ */
+export declare function siteCacheDir(appname?: string, appauthor?: string | false, version?: string, opinion?: boolean, ensureExists?: boolean): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param roaming See {@link PlatformDirs.roaming}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns state directory tied to the user
+ */
+export declare function userStateDir(appname?: string, appauthor?: string | false, version?: string, roaming?: boolean, ensureExists?: boolean): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param opinion See {@link PlatformDirs.opinion}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns log directory tied to the user
+ */
+export declare function userLogDir(appname?: string, appauthor?: string | false, version?: string, opinion?: boolean, ensureExists?: boolean): string;
+/**
+ * @returns documents directory tied to the user
+ */
+export declare function userDocumentsDir(): string;
+/**
+ * @returns downloads directory tied to the user
+ */
+export declare function userDownloadsDir(): string;
+/**
+ * @returns pictures directory tied to the user
+ */
+export declare function userPicturesDir(): string;
+/**
+ * @returns videos directory tied to the user
+ */
+export declare function userVideosDir(): string;
+/**
+ * @returns music directory tied to the user
+ */
+export declare function userMusicDir(): string;
+/**
+ * @returns desktop directory tied to the user
+ */
+export declare function userDesktopDir(): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param opinion See {@link PlatformDirs.opinion}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns runtime directory tied to the user
+ */
+export declare function userRuntimeDir(appname?: string, appauthor?: string | false, version?: string, opinion?: boolean, ensureExists?: boolean): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param opinion See {@link PlatformDirs.opinion}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns runtime directory shared by users
+ */
+export declare function siteRuntimeDir(appname?: string, appauthor?: string | false, version?: string, opinion?: boolean, ensureExists?: boolean): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param roaming See {@link PlatformDirs.roaming}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns data path tied to the user
+ */
+export declare function userDataPath(appname?: string, appauthor?: string | false, version?: string, roaming?: boolean, ensureExists?: boolean): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param multipath See {@link PlatformDirs.multipath}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns data path shared by users
+ */
+export declare function siteDataPath(appname?: string, appauthor?: string | false, version?: string, multipath?: boolean, ensureExists?: boolean): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param roaming See {@link PlatformDirs.roaming}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns config path tied to the user
+ */
+export declare function userConfigPath(appname?: string, appauthor?: string | false, version?: string, roaming?: boolean, ensureExists?: boolean): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param multipath See {@link PlatformDirs.multipath}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns config path shared by the users
+ */
+export declare function siteConfigPath(appname?: string, appauthor?: string | false, version?: string, multipath?: boolean, ensureExists?: boolean): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param opinion See {@link PlatformDirs.opinion}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns cache path shared by users
+ */
+export declare function siteCachePath(appname?: string, appauthor?: string | false, version?: string, opinion?: boolean, ensureExists?: boolean): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param opinion See {@link PlatformDirs.opinion}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns cache path tied to the user
+ */
+export declare function userCachePath(appname?: string, appauthor?: string | false, version?: string, opinion?: boolean, ensureExists?: boolean): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param roaming See {@link PlatformDirs.roaming}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns state path tied to the user
+ */
+export declare function userStatePath(appname?: string, appauthor?: string | false, version?: string, roaming?: boolean, ensureExists?: boolean): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param opinion See {@link PlatformDirs.opinion}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns log path tied to the user
+ */
+export declare function userLogPath(appname?: string, appauthor?: string | false, version?: string, opinion?: boolean, ensureExists?: boolean): string;
+/** @returns documents path tied to the user */
+export declare function userDocumentsPath(): string;
+/** @returns downloads path tied to the user */
+export declare function userDownloadsPath(): string;
+/** @returns pictures path tied to the user */
+export declare function userPicturesPath(): string;
+/** @returns videos path tied to the user */
+export declare function userVideosPath(): string;
+/** @returns music path tied to the user */
+export declare function userMusicPath(): string;
+/** @returns desktop path tied to the user */
+export declare function userDesktopPath(): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param opinion See {@link PlatformDirs.opinion}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns runtime path tied to the user
+ */
+export declare function userRuntimePath(appname?: string, appauthor?: string | false, version?: string, opinion?: boolean, ensureExists?: boolean): string;
+/**
+ * @param appname See {@link PlatformDirs.appname}
+ * @param appauthor See {@link PlatformDirs.appauthor}
+ * @param version See {@link PlatformDirs.version}
+ * @param opinion See {@link PlatformDirs.opinion}
+ * @param ensureExists See {@link PlatformDirs.ensureExists}
+ * @returns runtime path shared by users
+ */
+export declare function siteRuntimePath(appname?: string, appauthor?: string | false, version?: string, opinion?: boolean, ensureExists?: boolean): string;
+export { PlatformDirsABC } from "./api.js";
+export { version, versionTuple as versionInfo } from "./version.js";