platformdirs 4.3.7 → 4.3.8-rc1

package/README.md

@@ -4,8 +4,6 @@
 
 <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)
@@ -22,7 +20,7 @@ console.log(userLogDir("my-app", "gopher", "7.8"))
 </table>
 
 <p align=center>
-    <a href="https://jsdocs.io/package/platformdirs">Documentation</a>
+    <a href="https://tsdocs.dev/docs/platformdirs">Documentation</a>
     | <a href="https://pypi.org/project/platformdirs/">Original <code>platformdirs</code> project</a>
 </p>
 
@@ -33,6 +31,9 @@ console.log(userLogDir("my-app", "gopher", "7.8"))
 ## Installation
 
 ![npm](https://img.shields.io/static/v1?style=for-the-badge&message=npm&color=CB3837&logo=npm&logoColor=FFFFFF&label=)
+![pnpm](https://img.shields.io/static/v1?style=for-the-badge&message=pnpm&color=222222&logo=pnpm&logoColor=F69220&label=)
+![Bun](https://img.shields.io/static/v1?style=for-the-badge&message=Bun&color=000000&logo=Bun&logoColor=FFFFFF&label=)
+![Deno](https://img.shields.io/static/v1?style=for-the-badge&message=Deno&color=222222&logo=Deno&logoColor=70FFAF&label=)
 
 You can install this package from [the npm registry](https://www.npmjs.com/) using npm, Yarn, pnpm, Bun, Deno, etc.
 
@@ -40,6 +41,8 @@ You can install this package from [the npm registry](https://www.npmjs.com/) usi
 npm install platformdirs
 ```
 
+This package works with Node.js, Deno, and Bun. It is not intended to be used in the browser.
+
 ## Usage
 
 ![Node.js](https://img.shields.io/static/v1?style=for-the-badge&message=Node.js&color=5FA04E&logo=Node.js&logoColor=FFFFFF&label=)
@@ -64,7 +67,7 @@ if (!fs.existsSync(bigCSVPath)) {
 }
 ```
 
-📚 For more information check out [the documentation](https://jsdocs.io/package/platformdirs)
+📚 For more information check out [the documentation](https://tsdocs.dev/docs/platformdirs)
 
 You can quickly dump all the directories for the current environment by running the included `platformdirs` CLI command. This is helpful for quickly determining what `dirs.userConfigDir` and friends return.
 
@@ -75,7 +78,74 @@ npx platformdirs
 <details><summary>Output on Windows</summary>
 
 ```
-TODO
+-- platformdirs 4.3.7 --
+-- app dirs (with optional 'version')
+user_data_dir: C:\Users\me\AppData\Local\MyCompany\MyApp\1.0
+user_config_dir: C:\Users\me\AppData\Local\MyCompany\MyApp\1.0
+user_cache_dir: C:\Users\me\AppData\Local\MyCompany\MyApp\Cache\1.0
+user_state_dir: C:\Users\me\AppData\Local\MyCompany\MyApp\1.0
+user_log_dir: C:\Users\me\AppData\Local\MyCompany\MyApp\1.0\Logs
+user_documents_dir: C:\Users\me\Documents
+user_downloads_dir: C:\Users\me\Downloads
+user_pictures_dir: C:\Users\me\Pictures
+user_videos_dir: C:\Users\me\Videos
+user_music_dir: C:\Users\me\Music
+user_runtime_dir: C:\Users\me\AppData\Local\Temp\MyCompany\MyApp\1.0
+site_data_dir: C:\ProgramData\MyCompany\MyApp\1.0
+site_config_dir: C:\ProgramData\MyCompany\MyApp\1.0
+site_cache_dir: C:\ProgramData\MyCompany\MyApp\Cache\1.0
+site_runtime_dir: C:\Users\me\AppData\Local\Temp\MyCompany\MyApp\1.0
+
+-- app dirs (without optional 'version')
+user_data_dir: C:\Users\me\AppData\Local\MyCompany\MyApp
+user_config_dir: C:\Users\me\AppData\Local\MyCompany\MyApp
+user_cache_dir: C:\Users\me\AppData\Local\MyCompany\MyApp\Cache
+user_state_dir: C:\Users\me\AppData\Local\MyCompany\MyApp
+user_log_dir: C:\Users\me\AppData\Local\MyCompany\MyApp\Logs
+user_documents_dir: C:\Users\me\Documents
+user_downloads_dir: C:\Users\me\Downloads
+user_pictures_dir: C:\Users\me\Pictures
+user_videos_dir: C:\Users\me\Videos
+user_music_dir: C:\Users\me\Music
+user_runtime_dir: C:\Users\me\AppData\Local\Temp\MyCompany\MyApp
+site_data_dir: C:\ProgramData\MyCompany\MyApp
+site_config_dir: C:\ProgramData\MyCompany\MyApp
+site_cache_dir: C:\ProgramData\MyCompany\MyApp\Cache
+site_runtime_dir: C:\Users\me\AppData\Local\Temp\MyCompany\MyApp
+
+-- app dirs (without optional 'appauthor')
+user_data_dir: C:\Users\me\AppData\Local\MyApp\MyApp
+user_config_dir: C:\Users\me\AppData\Local\MyApp\MyApp
+user_cache_dir: C:\Users\me\AppData\Local\MyApp\MyApp\Cache
+user_state_dir: C:\Users\me\AppData\Local\MyApp\MyApp
+user_log_dir: C:\Users\me\AppData\Local\MyApp\MyApp\Logs
+user_documents_dir: C:\Users\me\Documents
+user_downloads_dir: C:\Users\me\Downloads
+user_pictures_dir: C:\Users\me\Pictures
+user_videos_dir: C:\Users\me\Videos
+user_music_dir: C:\Users\me\Music
+user_runtime_dir: C:\Users\me\AppData\Local\Temp\MyApp\MyApp
+site_data_dir: C:\ProgramData\MyApp\MyApp
+site_config_dir: C:\ProgramData\MyApp\MyApp
+site_cache_dir: C:\ProgramData\MyApp\MyApp\Cache
+site_runtime_dir: C:\Users\me\AppData\Local\Temp\MyApp\MyApp
+
+-- app dirs (with disabled 'appauthor')
+user_data_dir: C:\Users\me\AppData\Local\MyApp
+user_config_dir: C:\Users\me\AppData\Local\MyApp
+user_cache_dir: C:\Users\me\AppData\Local\MyApp\Cache
+user_state_dir: C:\Users\me\AppData\Local\MyApp
+user_log_dir: C:\Users\me\AppData\Local\MyApp\Logs
+user_documents_dir: C:\Users\me\Documents
+user_downloads_dir: C:\Users\me\Downloads
+user_pictures_dir: C:\Users\me\Pictures
+user_videos_dir: C:\Users\me\Videos
+user_music_dir: C:\Users\me\Music
+user_runtime_dir: C:\Users\me\AppData\Local\Temp\MyApp
+site_data_dir: C:\ProgramData\MyApp
+site_config_dir: C:\ProgramData\MyApp
+site_cache_dir: C:\ProgramData\MyApp\Cache
+site_runtime_dir: C:\Users\me\AppData\Local\Temp\MyApp
 ```
 
 </details>
@@ -169,4 +239,8 @@ site_runtime_dir: /run/MyApp
 ![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.
+This project uses Node.js, npm, TypeScript, and [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.
+
+For package releases make sure to always release a `-rc1` version first. If it's 100% OK then proceed to release it as normal. The goal is to keep the npm `platformdirs@X.Y.Z` package in sync with PyPI `platformdirs==X.Y.Z`.
+
+So far I have failed at this and now I'm two patch versions _ahead_ of the Python package. Oopsies.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "platformdirs",
-	"version": "4.3.7",
+	"version": "4.3.8-rc1",
 	"description": "📂 Unified interface to get platform-specific directories",
 	"keywords": [
 		"nodejs",
@@ -13,7 +13,7 @@
 		"known-folders",
 		"platformdirs"
 	],
-	"homepage": "https://jsdocs.io/package/platformdirs",
+	"homepage": "https://tsdocs.dev/docs/platformdirs",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/jcbhmr/platformdirs.js.git"
@@ -22,33 +22,30 @@
 	"author": "Jacob Hummer <jcbhmr@outlook.com> (https://jcbhmr.me)",
 	"type": "module",
 	"exports": {
-		".": "./dist/index.js",
-		"./android": "./dist/android.js",
-		"./api": "./dist/api.js",
-		"./macos": "./dist/macos.js",
-		"./unix": "./dist/unix.js",
-		"./version": "./dist/version.js"
+		".": "./src/index.js",
+		"./android": "./src/android.js",
+		"./api": "./src/api.js",
+		"./macos": "./src/macos.js",
+		"./unix": "./src/unix.js",
+		"./version": "./src/version.js"
 	},
 	"bin": {
-		"platformdirs": "dist/main.js"
+		"platformdirs": "src/main.js"
 	},
-	"files": [
-		"dist"
-	],
+	"files": ["src"],
 	"scripts": {
-		"build": "tsc --noCheck",
 		"format": "biome format --write .",
 		"lint": "biome check --write . && tsc --noEmit",
-		"run": "tsx src/main.ts",
-		"test": "tsx --test",
-		"prepack": "npm run build"
+		"run": "node src/main.js",
+		"test": "node --test"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "1.9.4",
 		"@types/node": "^22.9.0",
+		"@types/which": "^3.0.4",
 		"execa": "^9.5.1",
-		"tsx": "^4.19.2",
-		"typescript": "^5.6.3"
+		"typescript": "^5.6.3",
+		"which": "^5.0.0"
 	},
 	"engines": {
 		"node": ">=18"

package/src/android.js

@@ -0,0 +1,203 @@
+/**
+ * @module
+ * Android.
+ *
+ * TODO: Implement this module.
+ */
+
+import * as path from "node:path";
+import { PlatformDirsABC } from "./api.js";
+
+/**
+ * @param {unknown} error
+ * @return {never}
+ */
+function throwExpression(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 {
+	/**
+	 * @override
+	 * @return {string} data directory tied to the user, e.g. `/data/user/<userid>/<packagename>/files/<AppName>`
+	 */
+	get userDataDir() {
+		return this._appendAppNameAndVersion(
+			_androidFolder() ?? throwExpression(new Error("unreachable")),
+			"files",
+		);
+	}
+
+	/**
+	 * @override
+	 * @return {string} data directory shared by users, same as `userDataDir`
+	 */
+	get siteDataDir() {
+		return this.userDataDir;
+	}
+
+	/**
+	 * @override
+	 * @return {string} config directory tied to the user, e.g. `/data/user/<userid>/<packagename>/shared_prefs/<AppName>`
+	 */
+	get userConfigDir() {
+		return this._appendAppNameAndVersion(
+			_androidFolder() ?? throwExpression(new Error("unreachable")),
+			"shared_prefs",
+		);
+	}
+
+	/**
+	 * @override
+	 * @return {string} config directory shared by users, same as `userConfigDir`
+	 */
+	get siteConfigDir() {
+		return this.userConfigDir;
+	}
+
+	/**
+	 * @override
+	 * @return {string} cache directory tied to the user, e.g. `/data/user/<userid>/<packagename>/cache/<AppName>`
+	 */
+	get userCacheDir() {
+		return this._appendAppNameAndVersion(
+			_androidFolder() ?? throwExpression(new Error("unreachable")),
+			"cache",
+		);
+	}
+
+	/**
+	 * @override
+	 * @return {string} cache directory shared by users, same as `userCacheDir`
+	 */
+	get siteCacheDir() {
+		return this.userCacheDir;
+	}
+
+	/**
+	 * @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, 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;
+	}
+
+	/**
+	 * @override
+	 * @return {string} documents directory tied to the user, e.g. `/storage/emulated/0/Documents`
+	 */
+	get userDocumentsDir() {
+		return androidDocumentsFolder();
+	}
+
+	/**
+	 * @override
+	 * @return {string} downloads directory tied to the user, e.g. `/storage/emulated/0/Downloads`
+	 */
+	get userDownloadsDir() {
+		return androidDownloadsFolder();
+	}
+
+	/**
+	 * @override
+	 * @return {string} pictures directory tied to the user, e.g. `/storage/emulated/0/Pictures`
+	 */
+	get userPicturesDir() {
+		return androidPicturesFolder();
+	}
+
+	/**
+	 * @override
+	 * @return {string} videos directory tied to the user, e.g. `/storage/emulated/0/Movies`
+	 */
+	get userVideosDir() {
+		return androidVideosFolder();
+	}
+
+	/**
+	 * @override
+	 * @return {string} music directory tied to the user, e.g. `/storage/emulated/0/Music`
+	 */
+	get userMusicDir() {
+		return androidMusicFolder();
+	}
+
+	/**
+	 * @override
+	 * @return {string} desktop directory tied to the user, e.g. `/storage/emulated/0/Desktop`
+	 */
+	get userDesktopDir() {
+		return "/storage/emulated/0/Desktop";
+	}
+
+	/**
+	 * @override
+	 * @return {string} 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;
+	}
+
+	/**
+	 * @override
+	 * @return {string} runtime directory shared by users, same as `userRuntimeDir`
+	 */
+	get siteRuntimeDir() {
+		return this.userRuntimeDir;
+	}
+}
+
+/**
+ * @return {string | undefined}
+ * @ignore @internal
+ */
+export function _androidFolder() {
+	throw new Error("Not implemented");
+}
+
+/** @return {string} */
+function androidDocumentsFolder() {
+	throw new Error("Not implemented");
+}
+
+/** @return {string} */
+function androidDownloadsFolder() {
+	throw new Error("Not implemented");
+}
+
+/** @return {string} */
+function androidPicturesFolder() {
+	throw new Error("Not implemented");
+}
+
+/** @return {string} */
+function androidVideosFolder() {
+	throw new Error("Not implemented");
+}
+
+/** @return {string} */
+function androidMusicFolder() {
+	throw new Error("Not implemented");
+}