env-safe-check 1.0.0

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,38 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+  workflow_dispatch: {}
+
+jobs:
+  build:
+    # Only run automatically for the `main` branch or when a release is created.
+    if: github.ref == 'refs/heads/main' || github.event_name == 'release' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm test
+
+  publish-npm:
+    needs: build
+    # Only publish when the run is for `main` or a release (keeps publishes scoped to main).
+    if: github.ref == 'refs/heads/main' || github.event_name == 'release' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

package/README.md

@@ -0,0 +1,93 @@
+# env-safe-check
+
+Reliable, minimal utility to validate required environment variables at runtime.
+
+This tiny library helps Node and TypeScript projects fail fast with a clear
+error message when required environment variables are missing or empty.
+
+**Highlights**
+
+- Zero runtime dependencies
+- Tiny API: a single `validateEnv()` function
+- Works in TypeScript and JavaScript projects (ESM)
+- Safe defaults for CI and production (exits with non-zero code on missing vars)
+
+## Installation
+
+Install from npm (devs using this repo can also build locally):
+
+```bash
+npm install env-safe-check
+```
+
+For local development (this repository):
+
+```bash
+npm install
+npm run build
+```
+
+## Quick usage
+
+TypeScript (recommended):
+
+```ts
+import { validateEnv } from 'env-safe-check';
+
+// throw and exit if any required env var is missing or empty
+validateEnv(['DATABASE_URL', 'API_KEY']);
+```
+
+JavaScript (ESM):
+
+```js
+import { validateEnv } from 'env-safe-check';
+
+validateEnv(['DATABASE_URL', 'API_KEY']);
+```
+
+When any required variable is missing the library prints a friendly list
+and exits the process with code `1`.
+
+## API
+
+- `validateEnv(required: string[]): void`
+  - `required` — array of environment variable names to verify.
+  - Throws/terminates the process (with a console error) when any are
+    missing or empty.
+
+## Project specifics (for contributors / package authors)
+
+- Source files are TypeScript in `src/`.
+- Build emits ESM JavaScript into `dist/`.
+- Source imports are written without `.js` extensions for ergonomics in
+  TypeScript; the build process rewrites emitted imports to include `.js`
+  so the output is runnable under Node ESM (`node >= 12` with ESM support).
+
+Commands:
+
+```bash
+# Build and patch emitted imports
+npm run build
+
+# Run TypeScript type-check only
+npx tsc --noEmit
+```
+
+## Publishing
+
+1. Bump the package version in `package.json`.
+2. Run `npm run build` to produce `dist/`.
+3. Verify the `main`/`exports` fields point to built files (if applicable).
+4. `npm publish --access public`
+
+## Contributing
+
+Contributions are welcome. Open issues for bugs or small feature requests.
+
+Please run the tests (if added) and ensure linting/type-checks pass before
+submitting a PR.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "env-safe-check",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"hello world\"",
+    "build": "tsc && node ./scripts/patch-extensions.cjs"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^20.6.5"
+  }
+}

package/scripts/patch-extensions.cjs

@@ -0,0 +1,32 @@
+const fs = require('fs');
+const path = require('path');
+
+function walk(dir) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full);
+    else if (entry.isFile() && full.endsWith('.js')) patchFile(full);
+  }
+}
+
+function patchFile(file) {
+  let src = fs.readFileSync(file, 'utf8');
+  src = src.replace(/(from\s+|import\()(["'])(\.\/[^"'\)]+?)\2/g, (m, p1, q, p2) => {
+    if (/\.[a-zA-Z0-9]+$/.test(p2)) return m;
+    return `${p1}${q}${p2}.js${q}`;
+  });
+  src = src.replace(/(export\s+[^;]*?from\s+)(["'])(\.\/[^"']+?)\2/g, (m, p1, q, p2) => {
+    if (/\.[a-zA-Z0-9]+$/.test(p2)) return m;
+    return `${p1}${q}${p2}.js${q}`;
+  });
+  fs.writeFileSync(file, src, 'utf8');
+}
+
+const dist = path.join(__dirname, '..', 'dist');
+if (!fs.existsSync(dist)) {
+  console.error('dist directory not found; run tsc first');
+  process.exit(1);
+}
+walk(dist);
+console.log('Patched imports to include .js extensions in', dist);

package/scripts/patch-extensions.js

@@ -0,0 +1,38 @@
+const fs = require('fs');
+const path = require('path');
+
+function walk(dir) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full);
+    else if (entry.isFile() && full.endsWith('.js')) patchFile(full);
+  }
+}
+
+function patchFile(file) {
+  let src = fs.readFileSync(file, 'utf8');
+  // Replace import/export specifiers that are relative and have no extension
+  // Examples: import {x} from "./foo"  -> ./foo.js
+  //          export * from './bar'    -> ./bar.js
+  src = src.replace(/(from\s+|import\()(["'])(\.\/[^"'\)]+?)\2/g, (m, p1, q, p2) => {
+    // p2 is like ./module or ../module/sub
+    // If it already ends with an extension, leave it
+    if (/\.[a-zA-Z0-9]+$/.test(p2)) return m;
+    return `${p1}${q}${p2}.js${q}`;
+  });
+  // also handle export ... from '...'
+  src = src.replace(/(export\s+[^;]*?from\s+)(["'])(\.\/[^"']+?)\2/g, (m, p1, q, p2) => {
+    if (/\.[a-zA-Z0-9]+$/.test(p2)) return m;
+    return `${p1}${q}${p2}.js${q}`;
+  });
+  fs.writeFileSync(file, src, 'utf8');
+}
+
+const dist = path.join(__dirname, '..', 'dist');
+if (!fs.existsSync(dist)) {
+  console.error('dist directory not found; run tsc first');
+  process.exit(1);
+}
+walk(dist);
+console.log('Patched imports to include .js extensions in', dist);

package/src/index.ts

@@ -0,0 +1 @@
+export { validateEnv } from "./validate";

package/src/validate.ts

@@ -0,0 +1,20 @@
+export function validateEnv(required: string[]): void {
+  const missing = required.filter((key) => {
+    const value = process.env[key];
+    return value === undefined || value.trim() === "";
+  });
+
+  if (missing.length > 0) {
+    console.error("❌ Missing required environment variables:\n");
+
+    missing.forEach((key) => {
+      console.error(`- ${key}`);
+    });
+
+    console.error(
+      "\nPlease define them in your .env file or environment config."
+    );
+
+    process.exit(1);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,46 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    // "rootDir": "./src",
+    // "outDir": "./dist",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "esnext",
+    "moduleResolution": "node",
+    "target": "esnext",
+    "outDir": "./dist",
+    "types": ["node"],
+    // For nodejs:
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    // "noImplicitReturns": true,
+    // "noImplicitOverride": true,
+    // "noUnusedLocals": true,
+    // "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "jsx": "react-jsx",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+  }
+}