platformdirs 4.3.6-rc1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jacob Hummer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# `platformdirs` for JavaScript
+
+📂 Unified interface to get platform-specific directories
+
+<table align=center><td>
+
+<div><sub><i>Running on Linux</i></sub></div>
+
+```js
+const dirs = new PlatformDirs("awesome-app", "octocat", "1.2")
+console.log(dirs.userDataDir)
+//=> /home/jcbhmr/.local/share/awesome-app/1.2
+console.log(dirs.userConfigDir)
+//=> /home/jcbhmr/.config/awesome-app/1.2
+
+console.log(userRuntimeDir("other-app", "ferris", "4.5"))
+//=> /run/user/33333/other-app/4.5
+console.log(userLogDir("my-app", "gopher", "7.8"))
+//=> /home/jcbhmr/.local/state/my-app/7.8/log
+```
+
+</table>
+
+<p align=center>
+    <a href="https://jsdocs.io/package/platformdirs">Documentation</a>
+    | <a href="https://pypi.org/project/platformdirs/">Original <code>platformdirs</code> project</a>
+</p>
+
+🚀 Works on Windows, macOS, Linux, ~~and Android~~<sup>not yet</sup> \
+✅ Uses platform-specific best practices \
+🐍 A re-implementation of Python's [`platformdirs`](https://pypi.org/project/platformdirs/) package
+
+## Installation
+
+![npm](https://img.shields.io/static/v1?style=for-the-badge&message=npm&color=CB3837&logo=npm&logoColor=FFFFFF&label=)
+
+You can install this package from [the npm registry](https://www.npmjs.com/) using npm, Yarn, pnpm, Bun, Deno, etc.
+
+```sh
+npm install platformdirs
+```
+
+## Usage
+
+![Node.js](https://img.shields.io/static/v1?style=for-the-badge&message=Node.js&color=5FA04E&logo=Node.js&logoColor=FFFFFF&label=)
+![Deno](https://img.shields.io/static/v1?style=for-the-badge&message=Deno&color=222222&logo=Deno&logoColor=70FFAF&label=)
+![Bun](https://img.shields.io/static/v1?style=for-the-badge&message=Bun&color=000000&logo=Bun&logoColor=FFFFFF&label=)
+![Windows](https://img.shields.io/static/v1?style=for-the-badge&message=Windows&color=0078D4&logo=Windows&logoColor=FFFFFF&label=)
+![Linux](https://img.shields.io/static/v1?style=for-the-badge&message=Linux&color=222222&logo=Linux&logoColor=FCC624&label=)
+![macOS](https://img.shields.io/static/v1?style=for-the-badge&message=macOS&color=000000&logo=macOS&logoColor=FFFFFF&label=)
+
+
+```js
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as stream from "node:stream";
+import * as platformdirs from "platformdirs";
+
+const cacheDir = platformdirs.userCacheDir("awesome-app", "octocat", "1.2")
+const bigCSVPath = path.join(cacheDir, "big.csv");
+if (!fs.existsSync(bigCSVPath)) {
+    const response = await fetch("https://example.com/big.csv");
+    await response.body.pipeTo(stream.Writable.toWeb(fs.createWriteStream(bigCSVPath)));
+}
+```
+
+📚 For more information check out [the documentation](https://jsdocs.io/package/platformdirs)
+
+```sh
+npx platformdirs
+```
+
+<details><summary>Output on Windows</summary>
+
+```
+
+```
+
+</details>
+
+<details><summary>Output on macOS</summary>
+
+```
+
+```
+
+</details>
+
+<details><summary>Output on Linux</summary>
+
+```
+-- platformdirs 4.3.6 --
+-- app dirs (with optional 'version')
+user_data_dir: /home/me/.local/share/MyApp/1.0
+user_config_dir: /home/me/.config/MyApp/1.0
+user_cache_dir: /home/me/.cache/MyApp/1.0
+user_state_dir: /home/me/.local/state/MyApp/1.0
+user_log_dir: /home/me/.local/state/MyApp/1.0/log
+user_documents_dir: /home/me/Documents
+user_downloads_dir: /home/me/Downloads
+user_pictures_dir: /home/me/Pictures
+user_videos_dir: /home/me/Videos
+user_music_dir: /home/me/Music
+user_runtime_dir: /run/user/1000/MyApp/1.0
+site_data_dir: /usr/local/share/MyApp/1.0
+site_config_dir: /etc/xdg/MyApp/1.0
+site_cache_dir: /var/cache/MyApp/1.0
+site_runtime_dir: /run/MyApp/1.0
+
+-- app dirs (without optional 'version')
+user_data_dir: /home/me/.local/share/MyApp
+user_config_dir: /home/me/.config/MyApp
+user_cache_dir: /home/me/.cache/MyApp
+user_state_dir: /home/me/.local/state/MyApp
+user_log_dir: /home/me/.local/state/MyApp/log
+user_documents_dir: /home/me/Documents
+user_downloads_dir: /home/me/Downloads
+user_pictures_dir: /home/me/Pictures
+user_videos_dir: /home/me/Videos
+user_music_dir: /home/me/Music
+user_runtime_dir: /run/user/1000/MyApp
+site_data_dir: /usr/local/share/MyApp
+site_config_dir: /etc/xdg/MyApp
+site_cache_dir: /var/cache/MyApp
+site_runtime_dir: /run/MyApp
+
+-- app dirs (without optional 'appauthor')
+user_data_dir: /home/me/.local/share/MyApp
+user_config_dir: /home/me/.config/MyApp
+user_cache_dir: /home/me/.cache/MyApp
+user_state_dir: /home/me/.local/state/MyApp
+user_log_dir: /home/me/.local/state/MyApp/log
+user_documents_dir: /home/me/Documents
+user_downloads_dir: /home/me/Downloads
+user_pictures_dir: /home/me/Pictures
+user_videos_dir: /home/me/Videos
+user_music_dir: /home/me/Music
+user_runtime_dir: /run/user/1000/MyApp
+site_data_dir: /usr/local/share/MyApp
+site_config_dir: /etc/xdg/MyApp
+site_cache_dir: /var/cache/MyApp
+site_runtime_dir: /run/MyApp
+
+-- app dirs (with disabled 'appauthor')
+user_data_dir: /home/me/.local/share/MyApp
+user_config_dir: /home/me/.config/MyApp
+user_cache_dir: /home/me/.cache/MyApp
+user_state_dir: /home/me/.local/state/MyApp
+user_log_dir: /home/me/.local/state/MyApp/log
+user_documents_dir: /home/me/Documents
+user_downloads_dir: /home/me/Downloads
+user_pictures_dir: /home/me/Pictures
+user_videos_dir: /home/me/Videos
+user_music_dir: /home/me/Music
+user_runtime_dir: /run/user/1000/MyApp
+site_data_dir: /usr/local/share/MyApp
+site_config_dir: /etc/xdg/MyApp
+site_cache_dir: /var/cache/MyApp
+site_runtime_dir: /run/MyApp
+```
+
+</details>
+
+## Development
+
+![Node.js](https://img.shields.io/static/v1?style=for-the-badge&message=Node.js&color=5FA04E&logo=Node.js&logoColor=FFFFFF&label=)
+![TypeScript](https://img.shields.io/static/v1?style=for-the-badge&message=TypeScript&color=3178C6&logo=TypeScript&logoColor=FFFFFF&label=)
+![Biome](https://img.shields.io/static/v1?style=for-the-badge&message=Biome&color=60A5FA&logo=Biome&logoColor=FFFFFF&label=)
+
+This project uses Node.js, TypeScript, and npm. Why Node.js instead of [Deno](https://deno.com/) & [JSR](https://jsr.io/)? Because it's not as popular (yet). I'd love to use Deno & JSR but nobody knows what they are. This project does use [Biome](https://biomejs.dev/) instead of the usual [Prettier](https://prettier.io/) & [ESLint](https://eslint.org/) combo. Why? Because ESLint bungled their v9 release and Biome offers a more cohesive linter & formatter solution.

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