From 1023d638b3c55b4be4ce1cde8259b4324f907776 Mon Sep 17 00:00:00 2001
From: Roy Ivy III <rivy.dev@gmail.com>
Date: Sat, 29 Jun 2019 19:17:09 -0500
Subject: [PATCH] add STATE directory support

* includes documentation and tests
---
 index.d.ts      | 15 +++++++++++++++
 index.js        |  5 ++++-
 index.test-d.ts |  2 ++
 readme.md       |  6 +++++-
 test.js         |  6 ++++++
 5 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/index.d.ts b/index.d.ts
index a222290..07073cc 100644
--- a/index.d.ts
+++ b/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`.
 
diff --git a/index.js b/index.js
index 8dfdad9..c1b3ff2 100644
--- a/index.js
+++ b/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
 	};
diff --git a/index.test-d.ts b/index.test-d.ts
index 7e72e1d..946454b 100644
--- a/index.test-d.ts
+++ b/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);
diff --git a/readme.md b/readme.md
index e26bee6..d42dfa3 100644
--- a/readme.md
+++ b/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`.
diff --git a/test.js b/test.js
index db3e392..237a8e9 100644
--- a/test.js
+++ b/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('.');