dotenv-gad 1.2.2 → 1.2.3

package/dist/cli/commands/sync.js

@@ -12,6 +12,9 @@ export default function (program) {
         const spinner = ora("Generating .env.example.......").start();
         try {
             const schema = await loadSchema(rootOpts.schema);
+            if (!schema || typeof schema !== "object") {
+                throw new Error(`The schema loaded from "${rootOpts.schema}" is not valid.`);
+            }
             let exampleContent = "# Auto-generated by dotenv-gad\n\n";
             Object.entries(schema).forEach(([key, rule]) => {
                 if (rule.sensitive)
@@ -49,7 +52,7 @@ export default function (program) {
         }
         catch (error) {
             spinner.fail(chalk.red(`Failed to generate .env.example`));
-            console.error(error);
+            console.error(chalk.yellow(error.message));
             process.exit(1);
         }
     });

package/dist/cli/commands/utils.js

@@ -15,7 +15,12 @@ export async function loadSchema(schemaPath) {
     const absPath = resolve(schemaPath);
     const importModule = async (filePath) => {
         const fileUrl = pathToFileURL(filePath).href;
-        return (await import(`${fileUrl}?t=${Date.now()}`)).default;
+        const imported = await import(`${fileUrl}?t=${Date.now()}`);
+        const schema = imported.default || imported.schema || imported;
+        if (!schema || typeof schema !== "object") {
+            throw new Error(`Schema not found. Ensure you 'export default' or export const schema' in your file.`);
+        }
+        return schema;
     };
     const loadTsModule = async (tsFilePath) => {
         const tempFile = join(__dirname, `../../temp-schema-${Date.now()}.mjs`);

package/dist/schema.js

@@ -1,9 +1,15 @@
 /**
- * Define a schema for a set of environment variables.
+ * A type-safe way to define your environment schema.
  *
- * @param schema A record where each key is the name of an environment variable
- * and the value is a `SchemaRule` object that defines the rules for that
- * variable.
+ * @example
+ * const schema = defineSchema({
+ *   APP_NAME: { type: "string", required: true },
+ *   APP_PORT: { type: "number", default: 3000 },
+ * });
+ *
+ * @template S
+ * @param {S} schema - Environment schema definition
+ * @returns {S} - The same schema definition, but with type safety
  */
 export function defineSchema(schema) {
     return schema;

package/dist/types/index.d.ts

@@ -5,8 +5,9 @@ import { loadEnv, createEnvProxy } from "./utils.js";
 import { composeSchema } from "./compose.js";
 import loadSchema from "./cli/commands/types.js";
 import { applyFix } from "./cli/commands/utils.js";
+import { ExtractEnv } from "./types.js";
 export { defineSchema, AggregateError, EnvValidationError, EnvValidator, loadEnv, createEnvProxy, composeSchema, loadSchema, applyFix, };
-export type { SchemaDefinition, SchemaRule };
+export type { SchemaDefinition, SchemaRule, ExtractEnv };
 export declare function validateEnv(schema: SchemaDefinition, options?: {
     strict?: boolean;
 }): Record<string, any>;

package/dist/types/schema.d.ts

@@ -26,11 +26,17 @@ export interface SchemaRule {
 }
 export type SchemaDefinition = Record<string, SchemaRule>;
 /**
- * Define a schema for a set of environment variables.
+ * A type-safe way to define your environment schema.
  *
- * @param schema A record where each key is the name of an environment variable
- * and the value is a `SchemaRule` object that defines the rules for that
- * variable.
+ * @example
+ * const schema = defineSchema({
+ *   APP_NAME: { type: "string", required: true },
+ *   APP_PORT: { type: "number", default: 3000 },
+ * });
+ *
+ * @template S
+ * @param {S} schema - Environment schema definition
+ * @returns {S} - The same schema definition, but with type safety
  */
-export declare function defineSchema(schema: SchemaDefinition): SchemaDefinition;
+export declare function defineSchema<const S extends SchemaDefinition>(schema: S): S;
 export {};

package/dist/types/types.d.ts

@@ -0,0 +1,28 @@
+import type { SchemaDefinition, SchemaRule } from "./schema.js";
+/**
+ * Type inference utilities for dotenv-gad.
+ * This provides autocomplete and type safety for environment variables.
+ */
+type TypeFromSchemaRule<T extends SchemaRule> = T['enum'] extends ReadonlyArray<infer E> ? E : T['type'] extends 'string' | 'email' | 'url' | 'ip' ? string : T['type'] extends 'number' | 'port' ? number : T['type'] extends 'boolean' ? boolean : T['type'] extends 'date' ? Date : T['type'] extends 'json' ? any : T['type'] extends 'array' ? T['items'] extends SchemaRule ? Array<TypeFromSchemaRule<T['items']>> : any[] : T['type'] extends 'object' ? T['properties'] extends Record<string, SchemaRule> ? {
+    [K in keyof T['properties']]: TypeFromSchemaRule<T['properties'][K]>;
+} : Record<string, any> : any;
+/**
+ * A property is  optional if rrquired is explicitly false or
+ * required is not set and no default is provided.
+ */
+type IsOptional<T extends SchemaRule> = T['required'] extends true ? false : T['default'] extends undefined ? true : false;
+/**
+ * Convert schema rule to Optional or Required type
+ */
+type PropertyToType<T extends SchemaRule> = IsOptional<T> extends true ? TypeFromSchemaRule<T> | undefined : TypeFromSchemaRule<T>;
+export type InferEnv<S extends SchemaDefinition> = {
+    [K in keyof S]: PropertyToType<S[K]>;
+};
+/**
+ * Utility type to extract the environment type from a schema
+ *
+ * Usage:
+ *      type MyEnv = ExtractEnv<typeof mySchema>
+ */
+export type ExtractEnv<S> = S extends SchemaDefinition ? InferEnv<S> : never;
+export {};

package/dist/types/utils.d.ts

@@ -1,18 +1,22 @@
 import { SchemaDefinition } from "./schema.js";
+import type { InferEnv } from "./types.js";
 /**
- * Load the environment variables from a .env file, validate them against the schema
- * and return an object with the validated values.
+ * Loads environment variables from .env file and validates them against
+ * the given schema.
  *
- * @param schema The schema definition for the environment variables.
- * @param options Options for the validation process.
- *
- * @returns A validated object with the environment variables.
+ * @template S The type of the schema definition.
+ * @param {S} schema The schema definition for the environment variables.
+ * @param {Object} [options] Optional options for the validation process.
+ * @param {boolean} [options.strict] When true, fail on environment variables not present in the schema.
+ * @param {boolean} [options.includeRaw] Include raw values in error reports (non-sensitive by default).
+ * @param {boolean} [options.includeSensitive] When used with `includeRaw`, will reveal values marked sensitive (use only for local debugging).
+ * @returns {InferEnv<S>} The validated environment variables.
  */
-export declare function loadEnv(schema: SchemaDefinition, options?: {
+export declare function loadEnv<S extends SchemaDefinition>(schema: S, options?: {
     strict?: boolean;
     includeRaw?: boolean;
     includeSensitive?: boolean;
-}): Record<string, any>;
+}): InferEnv<S>;
 /**
  * Create a proxy around the validated environment variables. The proxy will
  * throw an error if you try to access a variable that is not validated.

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.js

@@ -1,13 +1,16 @@
 import dotenv from "dotenv";
 import { EnvValidator } from "./validator.js";
 /**
- * Load the environment variables from a .env file, validate them against the schema
- * and return an object with the validated values.
+ * Loads environment variables from .env file and validates them against
+ * the given schema.
  *
- * @param schema The schema definition for the environment variables.
- * @param options Options for the validation process.
- *
- * @returns A validated object with the environment variables.
+ * @template S The type of the schema definition.
+ * @param {S} schema The schema definition for the environment variables.
+ * @param {Object} [options] Optional options for the validation process.
+ * @param {boolean} [options.strict] When true, fail on environment variables not present in the schema.
+ * @param {boolean} [options.includeRaw] Include raw values in error reports (non-sensitive by default).
+ * @param {boolean} [options.includeSensitive] When used with `includeRaw`, will reveal values marked sensitive (use only for local debugging).
+ * @returns {InferEnv<S>} The validated environment variables.
  */
 export function loadEnv(schema, options) {
     const env = dotenv.config().parsed || {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotenv-gad",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "main": "dist/index.js",
   "types": "dist/types/index.d.ts",
   "type": "module",
@@ -72,24 +72,24 @@
     "@types/jest": "^30.0.0",
     "@types/node": "^24.0.3",
     "@types/ora": "^3.1.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
     "cross-env": "^7.0.3",
     "cross-env-shell": "^7.0.3",
+    "dotenv": "^16.5.0",
     "esbuild": "^0.25.5",
     "eslint": "^9.17.0",
+    "figlet": "^1.8.0",
     "globals": "^15.14.0",
     "husky": "^9.1.7",
+    "inquirer": "^12.3.0",
     "jest": "^30.0.3",
     "jest-environment-jsdom": "^30.0.2",
+    "ora": "^8.1.1",
     "prettier": "^3.4.2",
     "ts-jest": "^29.4.0",
+    "tsup": "^8.5.1",
     "typescript-eslint": "^8.19.1"
   },
-  "dependencies": {
-    "chalk": "^5.3.0",
-    "commander": "^12.1.0",
-    "dotenv": "^16.5.0",
-    "figlet": "^1.8.0",
-    "inquirer": "^12.3.0",
-    "ora": "^8.1.1"
-  }
+  "dependencies": {}
 }