docs: add example of implementing optional-value

examples/optional-value.mjs

@@ -0,0 +1,49 @@
+// This is an example of adding support for an option with an optional value,
+// which can be used like a boolean-type or a string-type.
+
+import { parseArgs } from 'node:util';
+import process from 'node:process';
+
+const options = {
+  'host': { type: 'string', preset: 'localhost', short: 'h', default: 'default.com' },
+  'debug': { type: 'boolean', short:'d' },
+};
+
+let args = process.argv.slice(2);
+
+do {
+  const { tokens } = parseArgs({ args, options, strict:false, tokens: true });
+  // Insert preset if:
+  // - missing value, like: --host
+  // - value came from following argument we want to process as option, like: --host --debug
+  // An empty string is a valid value for a string-type option.
+  const needsPreset = tokens.find((token) =>
+    token.kind === 'option'
+    && options[token.name]
+    && options[token.name].type === 'string'
+    && options[token.name].preset !== undefined
+    && (token.value === undefined || (token.value.startsWith('-') && !token.inlineValue)));
+
+  if (!needsPreset) break;
+
+  // Add preset value as an inline value to the original argument.
+  const joiner = args[needsPreset.index].startsWith('--') ? '=' : '';
+  args[needsPreset.index] = `${args[needsPreset.index]}${joiner}${options[needsPreset.name].preset}`;
+
+} while (true);
+
+
+const { values } = parseArgs({args, options, allowPositionals: true });
+console.log(values);
+
+// Try the following:
+//   node optional-value.mjs
+//   node optional-value.mjs -h
+//   node optional-value.mjs --host
+//   node optional-value.mjs -hHOSTNAME
+//   node optional-value.mjs --host=HOSTNAME
+//   node optional-value.mjs --host=
+//   node optional-value.mjs -h -d
+//   node optional-value.mjs -dh
+//   node optional-value.mjs --host --debug
+//   node optional-value.mjs --host -- POSITIONAL