doc: add complete docs for all dotenv functionality

[cknight]

While looking at #3492 it was clear that the documentation for dotenv module was incomplete. This PR attempts to address this by including all options, capabilities and files associated with the dotenv module.

Note, for restrictEnvAccessTo, I was very unclear as to the purpose of this. No matter what I tried, this option did nothing. Either this is a bug or I'm using it incorrectly. I've copied the docs for this option verbatim but they are not clear and should be revisited.

[CLAassistant]

All committers have signed the CLA.

[kt3k]

Nice work! LGTM

[kt3k]

restrictEnvAccessTo restricts the env access range. Run the below 2 scripts with deno run --allow-read main.ts and there are differences in permission prompts.

import { load } from "https://deno.land/std@0.199.0/dotenv/mod.ts";
await load();

import { load } from "https://deno.land/std@0.199.0/dotenv/mod.ts";
await load({ restrictEnvAccessTo: ["FOO", "BAR"] });

[cknight]

Thanks @kt3k . I see the differences in the permission prompts, but not any functional differences in running it.

For example, running this code:

import { load } from "https://deno.land/std@0.199.0/dotenv/mod.ts";
const conf = await load({ restrictEnvAccessTo: ["FOO", "BAR"] });
console.log(conf);
console.log(Deno.env.get("FOO"));
console.log(Deno.env.get("BAR"));
console.log(Deno.env.get("HELLO"));

with this command:

HELLO=world FOO=this BAR=that deno run --allow-read main.ts

prompts me first for FOO and BAR then processes the first 3 console outputs, then prompts for HELLO then outputs the last console output. However, conf is empty, so other than prompting for individual env variables permissions vs all env variables, I can't see any reason why you'd use this? Nothing is actually restricted here, e.g. I can still access HELLO.

[kt3k]

Then compare the below 2 scripts:

import { load } from "https://deno.land/std@0.199.0/dotenv/mod.ts";
console.log(await load());

import { load } from "https://deno.land/std@0.199.0/dotenv/mod.ts";
const conf = await load({ restrictEnvAccessTo: ["FOO", "BAR"] });

With .env file:

A=$FOO
B=$BAR
C=$HELLO

With the command FOO=1 BAR=2 HELLO=3 deno run --allow-read main.ts.

The first one should print { A: "1", B: "2", C: "3" } and the 2nd prints { A: "1", B: "2", C: "undefined" } (the access to HELLO is restricted in the 2nd example)

[cknight]

@kt3k Ah! I see, it restricts access to expansion in the .env file from process supplied env variables. I understand now how it works, thanks for the follow up. Still puzzled however on the use case. If you want to use the conf rather than Deno.env.get() but restrict which process env variables are allowed to be included in the conf, then just don't reference them in your .env?

[kt3k]

The main point of restrictEnvAccessTo is permission consideration. If restrictEnvAccessTo is not given, the entire 'env' permission is required for using dotenv/load, which unnecessarily expose env vars that the user prefers to hide from the program.

The original issue: #2534

[kt3k]

I now feel the way we read env vars in parse (and load) API has a problem.

I created an issue #3572