add STATE directory support

* includes documentation and tests

index.d.ts

@@ -59,6 +59,21 @@ declare const xdg: {
 	*/
 	readonly runtime?: string;
 
+	/**
+	Directory for user-specific state files (non-essential and more volatile than configuration files).
+
+	@example
+	```js
+	import xdg = require('xdg-portable');
+
+	xdg.state;
+	//(mac)=> '/Users/rivy/Library/State'
+	//(nix)=> '/home/rivy/.local/state'
+	//(win)=> 'C:\\Users\\rivy\\AppData\\Local\\xdg.state'
+	```
+	*/
+	readonly state?: string;
+
 	/**
 	Preference-ordered array of base directories to search for data files in addition to `.data`.
 

index.js

@@ -34,6 +34,7 @@ const macos = () => {
 		config: _config,
 		data: _data,
 		runtime: env.XDG_RUNTIME_DIR ? env.XDG_RUNTIME_DIR : undefined,
+		state: env.XDG_STATE_HOME ? env.XDG_STATE_HOME : path.join(library, 'State'),
 		configDirs: _configDirs,
 		dataDirs: _dataDirs
 	};
@@ -44,7 +45,7 @@ const windows = () => {
 	const appData = env.APPDATA || path.join(homedir, 'AppData', 'Roaming');			// "AppData/Roaming" contains data which may follow user between machines
 	const localAppData = env.LOCALAPPDATA || path.join(homedir, 'AppData', 'Local');	// "AppData/Local" contains local-machine-only user data
 
-	// Locations for cache/config/data are invented (Windows doesn't have a popular convention)
+	// Locations for cache/config/data/state are invented (Windows doesn't have a popular convention)
 
 	const _config = env.XDG_CONFIG_HOME ? env.XDG_CONFIG_HOME : path.join(appData, 'xdg.config');
 	const _data = env.XDG_DATA_HOME ? env.XDG_DATA_HOME : path.join(appData, 'xdg.data');
@@ -64,6 +65,7 @@ const windows = () => {
 		config: _config,
 		data: _data,
 		runtime: env.XDG_RUNTIME_DIR ? env.XDG_RUNTIME_DIR : undefined,
+		state: env.XDG_STATE_HOME ? env.XDG_STATE_HOME : path.join(localAppData, 'xdg.state'),
 		configDirs: _configDirs,
 		dataDirs: _dataDirs
 	};
@@ -88,6 +90,7 @@ const linux = () => {
 		config: _config,
 		data: _data,
 		runtime: env.XDG_RUNTIME_DIR ? env.XDG_RUNTIME_DIR : undefined,
+		state: env.XDG_STATE_HOME || path.join(homedir, '.local', 'state'),
 		configDirs: _configDirs,
 		dataDirs: _dataDirs
 	};

index.test-d.ts

@@ -9,6 +9,8 @@ expectType<string | undefined>(xdg.cache);
 expectError<string>(xdg.cache);
 expectType<string | undefined>(xdg.runtime);
 expectError<string>(xdg.runtime);
+expectType<string | undefined>(xdg.state);
+expectError<string>(xdg.state);
 expectType<readonly string[]>(xdg.configDirs);
 expectError<string[]>(xdg.configDirs);
 expectType<readonly string[]>(xdg.dataDirs);

readme.md

@@ -33,7 +33,7 @@ xdg.dataDirs
 
 ## API
 
-The properties `.data`, `.config`, `.cache`, `.runtime` will return `null` in the uncommon case that both the XDG environment variable is not set and the users home directory can't be found. You need to handle this case. A common solution is to [fall back to a temp directory](https://github.com/yeoman/configstore/blob/b82690fc401318ad18dcd7d151a0003a4898a314/index.js#L15).
+The properties `.data`, `.config`, `.cache`, `.runtime`, `.state` will return `null` in the uncommon case that both the XDG environment variable is not set and the users home directory can't be found. You need to handle this case. A common solution is to [fall back to a temp directory](https://github.com/yeoman/configstore/blob/b82690fc401318ad18dcd7d151a0003a4898a314/index.js#L15).
 
 ### .data
 
@@ -51,6 +51,10 @@ Directory for user-specific non-essential data files.
 
 Directory for user-specific non-essential runtime files and other file objects (such as sockets, named pipes, etc).
 
+### .state
+
+Directory for user-specific state files (non-essential and more volatile than configuration files).
+
 ### .dataDirs
 
 Preference-ordered array of base directories to search for data files in addition to `.data`.

test.js

@@ -26,6 +26,12 @@ test('.runtime', t => {
 	t.is(xdg.runtime, 'runtime');
 });
 
+test('.state', t => {
+	process.env.XDG_STATE_HOME = 'state';
+	const xdg = importFresh('.');
+	t.is(xdg.state, 'state');
+});
+
 test('.dataDirs', t => {
 	process.env.XDG_DATA_DIRS = ['dirs', 'data_dirs'].join(path.delimiter);
 	const xdg = importFresh('.');