lint, add unit tests, generate readme

Author: jonschlinkert

.eslintrc.js

@@ -1,3 +1,5 @@
+'use strict';
+
 module.exports = {
   root: true,
   extends: 'eslint:recommended',

README.md

@@ -1,6 +1,6 @@
 # @folder/xdg [![NPM version](https://img.shields.io/npm/v/@folder/xdg.svg?style=flat)](https://www.npmjs.com/package/@folder/xdg) [![NPM monthly downloads](https://img.shields.io/npm/dm/@folder/xdg.svg?style=flat)](https://npmjs.org/package/@folder/xdg) [![NPM total downloads](https://img.shields.io/npm/dt/@folder/xdg.svg?style=flat)](https://npmjs.org/package/@folder/xdg)
 
-> Get cross-platform XDG Base Directories or their equivalents. Works with Linux, Windows, or MacOS.
+> Get cross-platform XDG Base Directories or their equivalents. Works with Linux, Windows (win32), or MacOS (darwin).
 
 Please consider following this project's author, [Jon Schlinkert](https://github.com/jonschlinkert), and consider starring the project to show your :heart: and support.
 
@@ -251,7 +251,7 @@ The main export, and each method, returns an object with the following propertie
 
 ## Main Export
 
-### [xdg](index.js#L18)
+### [xdg](index.js#L17)
 
 Get the XDG Base Directory paths for Linux, or equivalent paths for Windows or MaxOS.
 
@@ -260,7 +260,7 @@ Get the XDG Base Directory paths for Linux, or equivalent paths for Windows or M
 * `options` **{Object}**
 * `returns` **{Object}**: Returns an object of paths for the current platform.
 
-### [.darwin](index.js#L44)
+### [.darwin](index.js#L42)
 
 Get XDG equivalent paths for MacOS. Used by the main export when `process.platform` is `darwin`. Aliased as `xdg.macos()`.
 
@@ -277,7 +277,7 @@ const dirs = xdg.darwin();
 const dirs = xdg.macos();
 ```
 
-### [.linux](index.js#L89)
+### [.linux](index.js#L93)
 
 Get XDG equivalent paths for Linux. Used by the main export when `process.platform` is `linux`.
 
@@ -290,7 +290,7 @@ Get XDG equivalent paths for Linux. Used by the main export when `process.platfo
 const dirs = xdg.linux();
 ```
 
-### [.win32](index.js#L136)
+### [.win32](index.js#L145)
 
 Get XDG equivalent paths for MacOS. Used by the main export when `process.platform` is `win32`. Aliased as `xdg.windows()`.
 
@@ -307,164 +307,6 @@ const dirs = xdg.win32();
 const dirs = xdg.windows();
 ```
 
-### [.userdirs()](lib/userdirs.js#L17)
-
-Get the XDG User Directories for Linux, or equivalents for Windows or MaxOS.
-
-**Params**
-
-* `options` **{Object}**
-* `returns` **{Object}**: Returns an object of directory paths.
-
-### [.userdirs.expand()](lib/userdirs.js#L39)
-
-Returns an object to with paths to `user-dirs.*` files, as well as functions to
-load each file.
-
-**Params**
-
-* `options` **{Object}**
-* `paths` **{Object}**: Optionally pass the paths from the `userdirs()` function to avoid creating them again.
-* `returns` **{Object}**: Returns an object with a `paths` object, and `config`, `defaults`, `dirs`, and `create` functions for actually loading the user-dir files.
-
-### [.userdirs.conf()](lib/userdirs.js#L76)
-
-Loads and parses the contents of `user-dirs.conf`, if one exists in user home.
-
-**Params**
-
-* `options` **{Object}**
-* `returns` **{Object}**: Returns configur
-
-**Example**
-
-```js
-const config = userdirs.conf();
-console.log(config);
-//=> { enabled: true, filename_encoding: 'UTF-8' }
-```
-
-### [.userdirs.defaults()](lib/userdirs.js#L105)
-
-Loads and parses the contents of `user-dirs.defaults`, if one exists in user home.
-
-// Example results:
-// {
-//   XDG_DESKTOP_DIR: '/Users/jonschlinkert/Desktop',
-//   XDG_DOWNLOAD_DIR: '/Users/jonschlinkert/Downloads',
-//   XDG_TEMPLATES_DIR: '/Users/jonschlinkert/Templates',
-//   XDG_PUBLICSHARE_DIR: '/Users/jonschlinkert/Public',
-//   XDG_DOCUMENTS_DIR: '/Users/jonschlinkert/Documents',
-//   XDG_MUSIC_DIR: '/Users/jonschlinkert/Music',
-//   XDG_PICTURES_DIR: '/Users/jonschlinkert/Pictures',
-//   XDG_VIDEOS_DIR: '/Users/jonschlinkert/Videos'
-// }
-
-**Params**
-
-* `options` **{Object}**
-* `returns` **{Object}**: Returns an object of paths.
-
-**Example**
-
-```js
-const defaults = userdirs.defaults();
-console.log(defaults);
-```
-
-### [.userdirs.dirs()](lib/userdirs.js#L132)
-
-Loads and parses the contents of `user-dirs.dirs`, if one exists in user home.
-
-**Params**
-
-* `options` **{Object}**
-* `returns` **{Object}**: Returns an object of paths.
-
-**Example**
-
-```js
-const dirs = userdirs.dirs();
-console.log(dirs);
-// Example results:
-// {
-//   XDG_MUSIC_DIR: '/Users/jonschlinkert/Documents/Music',
-//   XDG_PICTURES_DIR: '/Users/jonschlinkert/Documents/Pictures',
-//   XDG_TEMPLATES_DIR: '/Users/jonschlinkert/Documents/Templates',
-//   XDG_VIDEOS_DIR: '/Users/jonschlinkert/Documents/Videos'
-// }
-```
-
-### [.userdirs.create()](lib/userdirs.js#L165)
-
-Get the actual XDG User Directories to use for MacOS. Gets the `user-dirs.conf`, `user-dirs.defaults`, and the `user-dirs.dirs` files and, if not disabled in `user-dirs.conf`, merges the values in defaults and dirs to create the paths to use.
-
-**Params**
-
-* `options` **{Object}**
-* `returns` **{Object}**: Returns an object of paths.
-
-**Example**
-
-```js
-const dirs = userdirs.create();
-console.log(dirs);
-// Example results:
-// {
-//   XDG_DESKTOP_DIR: '/Users/jonschlinkert/Desktop',
-//   XDG_DOWNLOAD_DIR: '/Users/jonschlinkert/Downloads',
-//   XDG_TEMPLATES_DIR: '/Users/jonschlinkert/Documents/Templates',
-//   XDG_PUBLICSHARE_DIR: '/Users/jonschlinkert/Public',
-//   XDG_DOCUMENTS_DIR: '/Users/jonschlinkert/Documents',
-//   XDG_MUSIC_DIR: '/Users/jonschlinkert/Documents/Music',
-//   XDG_PICTURES_DIR: '/Users/jonschlinkert/Documents/Pictures',
-//   XDG_VIDEOS_DIR: '/Users/jonschlinkert/Documents/Videos'
-// }
-```
-
-### [.userdirs.darwin()](lib/userdirs.js#L181)
-
-Get the XDG User Directories for MacOS. This method is used by the main function when `process.platform` is `darwin`. Exposed as a method so you can call it directly if necessary. Also aliased as `userdirs.macos()`.
-
-**Params**
-
-* `options` **{Object}**
-* `returns` **{Object}**: Returns an object of paths.
-
-**Example**
-
-```js
-const { dirs, conf, defaults } = userdirs.darwin(); // or userdirs.macos();
-```
-
-### [.userdirs.linux()](lib/userdirs.js#L209)
-
-Gets the XDG User Directories for Linux. Used by the main export when `process.platform` is `linux`.
-
-* `returns` **{Object}**: Returns an object of paths.
-* `returns` **{Object}**: Returns an object of paths.
-
-**Example**
-
-```js
-const { dirs, conf, defaults } = userdirs.linux();
-```
-
-### [.userdirs.win32()](lib/userdirs.js#L235)
-
-Gets the XDG User Directories for MacOS. Used by the `userdirs()` function when `process.platform` is `win32`. Also aliased as `userdirs.windows()`.
-
-**Params**
-
-* `options` **{Object}**
-* `returns` **{Object}**: Returns an object of paths.
-
-**Example**
-
-```js
-const { dirs, conf, defaults } = userdirs.win32(); // or userdirs.windows();
-```
-
 ## XDG Base Directories
 
 This documentation is from the Arch Linux [XDG Base Directory](https://wiki.archlinux.org/index.php/XDG_Base_Directory) docs.
@@ -563,4 +405,4 @@ Released under the MIT License.
 
 ***
 
-_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on July 22, 2023._
+_This file was generated by [verb-generate-readme](https://github.com/verbose/verb-generate-readme), v0.8.0, on July 24, 2023._

index.js

@@ -200,7 +200,7 @@ xdg.macos = xdg.darwin;
  * Expose "user dirs"
  */
 
-xdg.userdirs = require('./lib/userdirs');
+xdg.userdirs = require('./lib/user-dirs');
 
 /**
  * Expose "xdg"

lib/expand.js

@@ -9,12 +9,15 @@ const pico = require('picomatch');
 const ini = require('ini');
 const toml = require('toml');
 const yaml = require('yaml');
-const userdirs = require('./userdirs');
+const userdirs = require('./user-dirs');
 const { dir, homedir, isObject, read, resolve } = require('./utils');
 
 const readfile = config => (pathname, find = false) => {
   try {
-    const fullpath = config.find && find ? config.find(pathname) : path.resolve(config.home, pathname);
+    const fullpath = config.find && find
+      ? config.find(pathname)
+      : path.resolve(config.home, pathname);
+
     return read(fullpath);
   } catch (err) {
     if (err.code !== 'ENOENT') {
@@ -113,15 +116,9 @@ const writefile = dir => (pathname, ...args) => {
 };
 
 const find = config => pathname => {
-  // const cwd = config.parent?.cwd;
-
   for (const dir of config.dirs) {
     const filepath = path.resolve(dir, pathname);
 
-    // if (dir === cwd) {
-    //   console.log({ dir, pathname, filepath });
-    // }
-
     if (fs.existsSync(filepath)) {
       return filepath;
     }

lib/userdirs.js lib/user-dirs.jslib/userdirs.js renamed to lib/user-dirs.js

@@ -24,6 +24,14 @@ const userdirs = (options = {}) => {
   return fn(options);
 };
 
+/**
+ * Convenience methods
+ */
+
+userdirs.home = (options = {}) => {
+  return options.homedir || homedir(options.platform || process.platform);
+};
+
 /**
  * Returns an object to with paths to `user-dirs.*` files, as well as functions to
  * load each file.
@@ -180,10 +188,20 @@ userdirs.create = (...args) => userdirs.expand(...args).create();
 userdirs.darwin = (options = {}) => {
   const env = options.env || process.env;
 
-  const etc = '/etc/xdg';
+  // It seems that there is still considerable debate about whether to use
+  // `Application Support` or `Preferences` for the home folder on MacOS.
+  // This spec is for linux, so we'll continue to have these debates until
+  // it's formalized for other OSes. For now, we'll use `Application Support`,
+  // since that seems to be the most commonly agreed upon. If you disagree,
+  // You can pass `homeFolder: 'Preferences'` on the options.
+  const homeFolder = options.homeFolder || 'Application Support';
+
+  // Non-standard, but this gives us an escape hatch
+  const etc = env.XDG_ETC || options.etc || '/etc/xdg';
+
   const home = options.homedir || homedir('darwin');
   const lib = path.join(home, 'Library');
-  const app = env.XDG_CONFIG_HOME || path.join(lib, 'Application Support');
+  const app = env.XDG_CONFIG_HOME || path.join(lib, homeFolder);
 
   return {
     conf: env.XDG_USER_DIRS_CONF || path.join(etc, 'user-dirs.conf'),
@@ -207,9 +225,11 @@ userdirs.darwin = (options = {}) => {
 
 userdirs.linux = (options = {}) => {
   const env = options.env || process.env;
+
+  // Non-standard, but this gives us an escape hatch
+  const etc = env.XDG_ETC || options.etc || '/etc/xdg';
   const home = options.homedir || homedir('linux');
   const config = env.XDG_CONFIG_HOME || path.join(home, '.config');
-  const etc = '/etc/xdg';
 
   return {
     conf: env.XDG_USER_DIRS_CONF || path.join(etc, 'user-dirs.conf'),
@@ -245,15 +265,6 @@ userdirs.win32 = (options = {}) => {
   };
 };
 
-/**
- * Convenience methods
- */
-
-userdirs.home = (options = {}) => {
-  const platform = options.platform || process.platform;
-  return options.homedir || homedir(platform);
-};
-
 /**
  * Expose "userdirs" API
  */