Implement src/env.ts with unit tests (MONGODB_URI resolution) #136

New issue

Closed

opened 2026-08-31 22:03:35 +00:00 by david · 1 comment

david commented

2026-08-31 22:03:35 +00:00

Owner

Summary

Implement extensions/mongodb/src/env.ts — the environment-resolution module that finds the MongoDB connection string in <cwd>/.env — with unit tests. It provides loadEnvFile(), findMongoUri(), and extractMongoUri() used by the extension factory and (indirectly) every tool.

Background

Depends on: #133

This is the single place the MONGODB_URI is resolved; the extension factory (a later step) uses extractMongoUri() to decide whether to register tools at all. It mirrors extensions/postgres/env.ts exactly, substituting the URI key. Case-insensitive matching plus a nested-key fallback exist so config injected by container/tooling environments (which often uppercase or nest keys) is found. No live MongoDB is involved — this is pure, unit-testable logic.

Documentation Required

A separate process downloads these into the listed folder before this issue is implemented. Check the folder for the actual reference material before starting.

docs/reference/dotenv/ — for the dotenv dependency used to parse .env:

https://github.com/motdotla/dotenv — official README: config() (options: path, debug, override, processEnv, quiet) and parse() (accepts a String/Buffer, returns a key/value object); the .env parsing rules (comments, quotes, empty values).
https://www.npmjs.com/package/dotenv — npm package page (mirror of the README; version info).

Also use extensions/postgres/env.ts in this repo as the structural reference implementation.

Implementation Details

Mirror extensions/postgres/env.ts. Suggested signatures (match the postgres sibling's naming where it differs):

loadEnvFile(): Record<string, string> — parse <cwd>/.env via dotenv (e.g. dotenv.parse on the file contents, or dotenv.config({ path, processEnv: {} })); return an empty record {} when the file is missing or unreadable. Never throws.
findMongoUri(envVars: Record<string, string>): string | undefined — locate the URI key:
- Top-level: case-insensitive match on mongodb_uri — MONGODB_URI, mongodb_uri, Database_Uri all match. Compare normalized (lowercased) keys for equality.
- Nested fallback: any key whose lowercased form ends with __mongodb_uri (double underscore prefix), any prefix — config__MONGODB_URI, app__Database_Uri match. The prefix may be anything, including config, app, etc.
- Priority: top-level match wins over nested.
- No false positives: MY_MONGODB_URI must NOT match — it is not equal to mongodb_uri case-insensitively, and it does not end with __mongodb_uri (only a single underscore separates MY from MONGODB_URI).
extractMongoUri(envVars: Record<string, string>): string | null — return the URI string found by findMongoUri, or null when missing or when the value is an empty string.

Write co-located tests in src/env.test.ts (bun test). For the missing-.env case, point the loader at a directory without a .env (make the path injectable for tests, or use dotenv.parse on a controlled input — follow the postgres sibling's testing approach).

Acceptance Criteria

loadEnvFile() returns {} for a missing/unreadable .env and never throws.
A parsed .env returns its key/value record.
findMongoUri resolves MONGODB_URI, mongodb_uri, and Database_Uri (case-insensitive top-level).
findMongoUri resolves nested config__MONGODB_URI and app__Database_Uri.
Top-level key wins over a nested key when both are present.
MY_MONGODB_URI does not match.
extractMongoUri returns null for absent key and for an empty-string value; returns the URI string otherwise.
bun test in extensions/mongodb/ is green for src/env.ts (all of the above cases).

Test Plan

cd extensions/mongodb
bun test   # env tests green

## Summary Implement `extensions/mongodb/src/env.ts` — the environment-resolution module that finds the MongoDB connection string in `<cwd>/.env` — with unit tests. It provides `loadEnvFile()`, `findMongoUri()`, and `extractMongoUri()` used by the extension factory and (indirectly) every tool. ## Background **Depends on:** #133 This is the single place the `MONGODB_URI` is resolved; the extension factory (a later step) uses `extractMongoUri()` to decide whether to register tools at all. It mirrors `extensions/postgres/env.ts` exactly, substituting the URI key. Case-insensitive matching plus a nested-key fallback exist so config injected by container/tooling environments (which often uppercase or nest keys) is found. No live MongoDB is involved — this is pure, unit-testable logic. ## Documentation Required A separate process downloads these into the listed folder before this issue is implemented. Check the folder for the actual reference material before starting. **`docs/reference/dotenv/`** — for the `dotenv` dependency used to parse `.env`: - https://github.com/motdotla/dotenv — official README: `config()` (options: `path`, `debug`, `override`, `processEnv`, `quiet`) and `parse()` (accepts a String/Buffer, returns a key/value object); the .env parsing rules (comments, quotes, empty values). - https://www.npmjs.com/package/dotenv — npm package page (mirror of the README; version info). Also use `extensions/postgres/env.ts` in this repo as the structural reference implementation. ## Implementation Details Mirror `extensions/postgres/env.ts`. Suggested signatures (match the postgres sibling's naming where it differs): - `loadEnvFile(): Record<string, string>` — parse `<cwd>/.env` via `dotenv` (e.g. `dotenv.parse` on the file contents, or `dotenv.config({ path, processEnv: {} })`); return an empty record `{}` when the file is missing or unreadable. Never throws. - `findMongoUri(envVars: Record<string, string>): string | undefined` — locate the URI key: - Top-level: case-insensitive match on `mongodb_uri` — `MONGODB_URI`, `mongodb_uri`, `Database_Uri` all match. Compare normalized (lowercased) keys for equality. - Nested fallback: any key whose lowercased form **ends with** `__mongodb_uri` (double underscore prefix), any prefix — `config__MONGODB_URI`, `app__Database_Uri` match. The prefix may be anything, including `config`, `app`, etc. - Priority: top-level match wins over nested. - No false positives: `MY_MONGODB_URI` must NOT match — it is not equal to `mongodb_uri` case-insensitively, and it does not end with `__mongodb_uri` (only a single underscore separates `MY` from `MONGODB_URI`). - `extractMongoUri(envVars: Record<string, string>): string | null` — return the URI string found by `findMongoUri`, or `null` when missing or when the value is an empty string. Write co-located tests in `src/env.test.ts` (bun test). For the missing-`.env` case, point the loader at a directory without a `.env` (make the path injectable for tests, or use `dotenv.parse` on a controlled input — follow the postgres sibling's testing approach). ## Acceptance Criteria - [ ] `loadEnvFile()` returns `{}` for a missing/unreadable `.env` and never throws. - [ ] A parsed `.env` returns its key/value record. - [ ] `findMongoUri` resolves `MONGODB_URI`, `mongodb_uri`, and `Database_Uri` (case-insensitive top-level). - [ ] `findMongoUri` resolves nested `config__MONGODB_URI` and `app__Database_Uri`. - [ ] Top-level key wins over a nested key when both are present. - [ ] `MY_MONGODB_URI` does not match. - [ ] `extractMongoUri` returns `null` for absent key and for an empty-string value; returns the URI string otherwise. - [ ] `bun test` in `extensions/mongodb/` is green for `src/env.ts` (all of the above cases). ## Test Plan ```bash cd extensions/mongodb bun test # env tests green ```

david added this to the MongoDB: M2 - Env Module milestone

2026-08-31 22:03:35 +00:00

david added the

feature

label

2026-08-31 22:03:35 +00:00

david referenced this issue

2026-08-31 22:06:34 +00:00

Implement index.ts async factory + lifecycle with tests #143

david added the

ready

label