From d04b57cb669e5dcf2d747d567c6c1cf2012744bb Mon Sep 17 00:00:00 2001
From: Max Metral <max.metral@sesamecare.com>
Date: Thu, 19 Oct 2023 22:12:59 -0400
Subject: [PATCH] fix(formatters): document and clean up a couple formatters

---
 README.md                     | 17 ++++++++++++++++-
 src/shortstop/envHandler.ts   |  6 +++---
 src/shortstop/fileHandlers.ts |  2 +-
 3 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 875426d..24d8894 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,18 @@
 # confit
 
-@sesamecare-oss/confit is a modern rewrite of [confit](https://github.com/krakenjs/confit) in Typescript using Promises and bundling the standard shortstop handlers. The general approach of stackable environment-aware configurations is retained, but we add proper typing for key lookups and just generally modernize the build pipeline.
+@sesamecare-oss/confit is a modern rewrite of [confit](https://github.com/krakenjs/confit) in Typescript using Promises and bundling the standard shortstop handlers. The general approach of stackable environment-aware configurations is retained, but we add proper typing for key lookups and just generally modernize the build pipeline. We also bundle the shortstop infrastructure and the common shortstop handlers.
+
+## env
+
+The env shortstop handler accepts the following format specificiations:
+
+* `env:SOMEVAR|u` - Return the variable if it exists and is non-empty, else undefined
+* `env:SOMEVAR|ud` - Return the variable as a number if it exists, or undefined
+* `env:SOMEVAR|d` - Return the value as a decimal, or NaN if not there
+* `env:SOMEVAR|b` - Return the value as a boolean - empty, false, 0 and undefined will be false
+* `env:SOMEVAR|!b` - Return the value as a boolean but inverted so that empty/undefined/0/false are true
+
+## file
+
+The file handler uses the pipe character to allow specifying the encoding with which to read the file. The valid encodings are
+`base64|binary|hex|utf8|ucs2|utf16le|ascii`. If you somehow have a pipe with one of these values at the end your filename (wow), use `|binary` at the end to make it clearer and behave as normal.
diff --git a/src/shortstop/envHandler.ts b/src/shortstop/envHandler.ts
index 6a470af..098d146 100644
--- a/src/shortstop/envHandler.ts
+++ b/src/shortstop/envHandler.ts
@@ -10,15 +10,15 @@ export function envHandler() {
     '|ud': (value?: string) => {
       return value === '' || value === undefined ? undefined : parseInt(value, 10);
     },
-    // Return it as a decimal
+    // Return the value as a decimal
     '|d': (value?: string) => {
       return parseInt(value || '', 10);
     },
-    // Return it as a boolean - empty, false, 0 and undefined will be false
+    // Return the value as a boolean - empty, false, 0 and undefined will be false
     '|b': (value?: string) => {
       return value !== '' && value !== 'false' && value !== '0' && value !== undefined;
     },
-    // Return it as a boolean but inverted so that empty/undefined/0/false are true
+    // Return the value as a boolean but inverted so that empty/undefined/0/false are true
     '|!b': (value?: string) => {
       return value === '' || value === 'false' || value === '0' || value === undefined;
     },
diff --git a/src/shortstop/fileHandlers.ts b/src/shortstop/fileHandlers.ts
index d1d5596..978437c 100644
--- a/src/shortstop/fileHandlers.ts
+++ b/src/shortstop/fileHandlers.ts
@@ -71,7 +71,7 @@ export function fileHandler(basedir?: string | ReadOptions, options?: ReadOption
     const finalOptions = { ...baseOptions };
     let filename = value;
     // Find the options value with a pipe character and a spec at the end
-    const match = filename.match(/(.*)\|(base64|hex|utf8|ucs2|utf16le|ascii)$/);
+    const match = filename.match(/(.*)\|(base64|binary|hex|utf8|ucs2|utf16le|ascii)$/);
     if (match) {
       filename = match[1];
       finalOptions.encoding = match[2] as BufferEncoding;