@adonisjs/env 7.0.0-next.0 → 7.0.0-next.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -15,14 +15,29 @@ var debug_default = debuglog("adonisjs:env");
15
15
 
16
16
  // src/loader.ts
17
17
  var EnvLoader = class {
18
+ /**
19
+ * The application root directory path
20
+ */
18
21
  #appRoot;
22
+ /**
23
+ * Whether to load the .env.example file
24
+ */
19
25
  #loadExampleFile;
26
+ /**
27
+ * Creates a new EnvLoader instance
28
+ *
29
+ * @param appRoot - The application root directory as string or URL
30
+ * @param loadExampleFile - Whether to load .env.example file
31
+ */
20
32
  constructor(appRoot, loadExampleFile = false) {
21
33
  this.#appRoot = typeof appRoot === "string" ? appRoot : fileURLToPath(appRoot);
22
34
  this.#loadExampleFile = loadExampleFile;
23
35
  }
24
36
  /**
25
37
  * Optionally read a file from the disk
38
+ *
39
+ * @param filePath - Path to the file to read
40
+ * @returns Promise resolving to file existence status and contents
26
41
  */
27
42
  async #loadFile(filePath) {
28
43
  try {
@@ -38,6 +53,8 @@ var EnvLoader = class {
38
53
  /**
39
54
  * Load contents of the main dot-env file and the current
40
55
  * environment dot-env file
56
+ *
57
+ * @returns Promise resolving to array of loaded environment files
41
58
  */
42
59
  async load() {
43
60
  const ENV_PATH = process.env.ENV_PATH;
package/build/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- export { Env } from './src/env.js';
2
- export { EnvParser } from './src/parser.js';
3
- export { EnvLoader } from './src/loader.js';
4
- export * as errors from './src/errors.js';
5
- export { EnvProcessor } from './src/processor.js';
1
+ export { Env } from './src/env.ts';
2
+ export { EnvParser } from './src/parser.ts';
3
+ export { EnvLoader } from './src/loader.ts';
4
+ export * as errors from './src/errors.ts';
5
+ export { EnvProcessor } from './src/processor.ts';
package/build/index.js CHANGED
@@ -2,7 +2,7 @@ import {
2
2
  EnvLoader,
3
3
  __export,
4
4
  debug_default
5
- } from "./chunk-EIJZNYI6.js";
5
+ } from "./chunk-KE5AFOK2.js";
6
6
 
7
7
  // src/env.ts
8
8
  import { schema as envSchema } from "@poppinss/validator-lite";
@@ -29,15 +29,56 @@ var E_IDENTIFIER_ALREADY_DEFINED = createError(
29
29
  );
30
30
 
31
31
  // src/parser.ts
32
+ import { readFile } from "fs/promises";
33
+ import { RuntimeException } from "@poppinss/utils/exception";
32
34
  var EnvParser = class _EnvParser {
35
+ /**
36
+ * Raw environment file contents
37
+ */
33
38
  #envContents;
39
+ /**
40
+ * Application root directory URL
41
+ */
42
+ #appRoot;
43
+ /**
44
+ * Whether to prefer process.env values over parsed values
45
+ */
34
46
  #preferProcessEnv = true;
35
- static #identifiers = {};
36
- constructor(envContents, options) {
47
+ /**
48
+ * Static collection of registered identifiers with their callbacks
49
+ */
50
+ static #identifiers = {
51
+ async file(value, key, appRoot) {
52
+ const filePath = new URL(value, appRoot);
53
+ try {
54
+ const contents = await readFile(filePath, "utf-8");
55
+ return contents;
56
+ } catch (error) {
57
+ if (error.code === "ENOENT") {
58
+ throw new RuntimeException(
59
+ `Cannot process "${key}" env variable. Unable to locate file "${filePath}"`,
60
+ {
61
+ cause: error
62
+ }
63
+ );
64
+ }
65
+ throw error;
66
+ }
67
+ }
68
+ };
69
+ /**
70
+ * Creates a new EnvParser instance
71
+ *
72
+ * @param envContents - Raw environment file contents
73
+ * @param appRoot - Application root directory URL
74
+ * @param options - Parser options
75
+ */
76
+ constructor(envContents, appRoot, options) {
37
77
  if (options?.ignoreProcessEnv) {
38
78
  this.#preferProcessEnv = false;
39
79
  }
40
80
  this.#envContents = envContents;
81
+ this.#appRoot = appRoot;
41
82
  }
42
83
  /**
43
84
  * Define an identifier for any environment value. The callback is invoked
@@ -45,12 +86,23 @@ var EnvParser = class _EnvParser {
45
86
  *
46
87
  * @deprecated use `EnvParser.defineIdentifier` instead
47
88
  */
89
+ /**
90
+ * Define an identifier for any environment value. The callback is invoked
91
+ * when the value match the identifier to modify its interpolation.
92
+ *
93
+ * @deprecated use `EnvParser.defineIdentifier` instead
94
+ * @param name - The identifier name
95
+ * @param callback - Callback function to process the identifier value
96
+ */
48
97
  static identifier(name, callback) {
49
98
  _EnvParser.defineIdentifier(name, callback);
50
99
  }
51
100
  /**
52
101
  * Define an identifier for any environment value. The callback is invoked
53
102
  * when the value match the identifier to modify its interpolation.
103
+ *
104
+ * @param name - The identifier name
105
+ * @param callback - Callback function to process the identifier value
54
106
  */
55
107
  static defineIdentifier(name, callback) {
56
108
  if (this.#identifiers[name]) {
@@ -62,6 +114,9 @@ var EnvParser = class _EnvParser {
62
114
  * Define an identifier for any environment value, if it's not already defined.
63
115
  * The callback is invoked when the value match the identifier to modify its
64
116
  * interpolation.
117
+ *
118
+ * @param name - The identifier name
119
+ * @param callback - Callback function to process the identifier value
65
120
  */
66
121
  static defineIdentifierIfMissing(name, callback) {
67
122
  if (typeof this.#identifiers[name] === "undefined") {
@@ -70,12 +125,18 @@ var EnvParser = class _EnvParser {
70
125
  }
71
126
  /**
72
127
  * Remove an identifier
128
+ *
129
+ * @param name - The identifier name to remove
73
130
  */
74
131
  static removeIdentifier(name) {
75
132
  delete this.#identifiers[name];
76
133
  }
77
134
  /**
78
135
  * Returns the value from the parsed object
136
+ *
137
+ * @param key - The environment variable key
138
+ * @param parsed - Parsed environment variables object
139
+ * @returns The resolved environment variable value
79
140
  */
80
141
  #getValue(key, parsed) {
81
142
  if (this.#preferProcessEnv && process.env[key]) {
@@ -88,6 +149,10 @@ var EnvParser = class _EnvParser {
88
149
  }
89
150
  /**
90
151
  * Interpolating the token wrapped inside the mustache braces.
152
+ *
153
+ * @param token - The token to interpolate
154
+ * @param parsed - Parsed environment variables object
155
+ * @returns Interpolated value
91
156
  */
92
157
  #interpolateMustache(token, parsed) {
93
158
  const closingBrace = token.indexOf("}");
@@ -102,6 +167,10 @@ var EnvParser = class _EnvParser {
102
167
  * `$`. We only capture numbers,letter and underscore.
103
168
  * For other characters, one can use the mustache
104
169
  * braces.
170
+ *
171
+ * @param token - The token to interpolate
172
+ * @param parsed - Parsed environment variables object
173
+ * @returns Interpolated value
105
174
  */
106
175
  #interpolateVariable(token, parsed) {
107
176
  return token.replace(/[a-zA-Z0-9_]+/, (key) => {
@@ -110,6 +179,10 @@ var EnvParser = class _EnvParser {
110
179
  }
111
180
  /**
112
181
  * Interpolates the referenced values
182
+ *
183
+ * @param value - The value to interpolate
184
+ * @param parsed - Parsed environment variables object
185
+ * @returns Interpolated value
113
186
  */
114
187
  #interpolate(value, parsed) {
115
188
  const tokens = value.split("$");
@@ -139,6 +212,8 @@ var EnvParser = class _EnvParser {
139
212
  }
140
213
  /**
141
214
  * Parse the env string to an object of environment variables.
215
+ *
216
+ * @returns Promise resolving to parsed environment variables
142
217
  */
143
218
  async parse() {
144
219
  const envCollection = dotenv.parse(this.#envContents.trim());
@@ -150,7 +225,9 @@ var EnvParser = class _EnvParser {
150
225
  for (const identifier of identifiers) {
151
226
  if (value.startsWith(`${identifier}:`)) {
152
227
  result[key] = await _EnvParser.#identifiers[identifier](
153
- value.substring(identifier.length + 1)
228
+ value.substring(identifier.length + 1),
229
+ key,
230
+ this.#appRoot
154
231
  );
155
232
  continue $keyLoop;
156
233
  }
@@ -170,8 +247,19 @@ var EnvParser = class _EnvParser {
170
247
 
171
248
  // src/validator.ts
172
249
  var EnvValidator = class {
250
+ /**
251
+ * The validation schema for environment variables
252
+ */
173
253
  #schema;
254
+ /**
255
+ * The error instance for validation failures
256
+ */
174
257
  #error;
258
+ /**
259
+ * Creates a new EnvValidator instance
260
+ *
261
+ * @param schema - The validation schema object
262
+ */
175
263
  constructor(schema) {
176
264
  this.#schema = schema;
177
265
  this.#error = new E_INVALID_ENV_VARIABLES();
@@ -182,6 +270,9 @@ var EnvValidator = class {
182
270
  *
183
271
  * The return value is a merged copy of the original object and the
184
272
  * values mutated by the schema validator.
273
+ *
274
+ * @param values - Object of environment variable values to validate
275
+ * @returns Validated and transformed environment variables
185
276
  */
186
277
  validate(values) {
187
278
  const help = [];
@@ -211,17 +302,26 @@ var EnvProcessor = class {
211
302
  * App root is needed to load files
212
303
  */
213
304
  #appRoot;
305
+ /**
306
+ * Creates a new EnvProcessor instance
307
+ *
308
+ * @param appRoot - The application root directory URL
309
+ */
214
310
  constructor(appRoot) {
215
311
  this.#appRoot = appRoot;
216
312
  }
217
313
  /**
218
314
  * Parse env variables from raw contents
315
+ *
316
+ * @param envContents - Raw environment file contents
317
+ * @param store - Store object to collect parsed variables
318
+ * @returns Updated store with parsed variables
219
319
  */
220
320
  async #processContents(envContents, store) {
221
321
  if (!envContents.trim()) {
222
322
  return store;
223
323
  }
224
- const parser = new EnvParser(envContents);
324
+ const parser = new EnvParser(envContents, this.#appRoot);
225
325
  const values = await parser.parse();
226
326
  Object.keys(values).forEach((key) => {
227
327
  let value = process.env[key];
@@ -237,6 +337,8 @@ var EnvProcessor = class {
237
337
  }
238
338
  /**
239
339
  * Parse env variables by loading dot files.
340
+ *
341
+ * @returns Promise resolving to collected environment variables
240
342
  */
241
343
  async #loadAndProcessDotFiles() {
242
344
  const loader = new EnvLoader(this.#appRoot);
@@ -253,6 +355,8 @@ var EnvProcessor = class {
253
355
  }
254
356
  /**
255
357
  * Process env variables
358
+ *
359
+ * @returns Promise resolving to processed environment variables
256
360
  */
257
361
  async process() {
258
362
  return this.#loadAndProcessDotFiles();
@@ -265,6 +369,11 @@ var Env = class _Env {
265
369
  * A cache of env values
266
370
  */
267
371
  #values;
372
+ /**
373
+ * Creates a new Env instance
374
+ *
375
+ * @param values - Validated environment values
376
+ */
268
377
  constructor(values) {
269
378
  this.#values = values;
270
379
  }
@@ -272,6 +381,10 @@ var Env = class _Env {
272
381
  * Create an instance of the env class by validating the
273
382
  * environment variables. Also, the `.env` files are
274
383
  * loaded from the appRoot
384
+ *
385
+ * @param appRoot - The application root directory URL
386
+ * @param schema - Validation schema for environment variables
387
+ * @returns Promise resolving to an Env instance with validated values
275
388
  */
276
389
  static async create(appRoot, schema) {
277
390
  const values = await new EnvProcessor(appRoot).process();
@@ -283,6 +396,8 @@ var Env = class _Env {
283
396
  * when the value match the identifier to modify its interpolation.
284
397
  *
285
398
  * @deprecated use `Env.defineIdentifier` instead
399
+ * @param name - The identifier name
400
+ * @param callback - Callback function to process the identifier value
286
401
  */
287
402
  static identifier(name, callback) {
288
403
  return EnvParser.defineIdentifier(name, callback);
@@ -290,6 +405,9 @@ var Env = class _Env {
290
405
  /**
291
406
  * Define an identifier for any environment value. The callback is invoked
292
407
  * when the value match the identifier to modify its interpolation.
408
+ *
409
+ * @param name - The identifier name
410
+ * @param callback - Callback function to process the identifier value
293
411
  */
294
412
  static defineIdentifier(name, callback) {
295
413
  EnvParser.defineIdentifier(name, callback);
@@ -298,12 +416,17 @@ var Env = class _Env {
298
416
  * Define an identifier for any environment value, if it's not already defined.
299
417
  * The callback is invoked when the value match the identifier to modify its
300
418
  * interpolation.
419
+ *
420
+ * @param name - The identifier name
421
+ * @param callback - Callback function to process the identifier value
301
422
  */
302
423
  static defineIdentifierIfMissing(name, callback) {
303
424
  EnvParser.defineIdentifierIfMissing(name, callback);
304
425
  }
305
426
  /**
306
427
  * Remove an identifier
428
+ *
429
+ * @param name - The identifier name to remove
307
430
  */
308
431
  static removeIdentifier(name) {
309
432
  EnvParser.removeIdentifier(name);
@@ -316,6 +439,9 @@ var Env = class _Env {
316
439
  * Define the validation rules for validating environment
317
440
  * variables. The return value is an instance of the
318
441
  * env validator
442
+ *
443
+ * @param schema - Validation schema object
444
+ * @returns EnvValidator instance
319
445
  */
320
446
  static rules(schema) {
321
447
  const validator = new EnvValidator(schema);
@@ -1,28 +1,53 @@
1
+ /**
2
+ * Environment editor for managing and modifying .env files.
3
+ * Provides functionality to load, edit, and save environment configuration files.
4
+ */
1
5
  export declare class EnvEditor {
2
6
  #private;
3
7
  /**
4
8
  * Creates an instance of env editor and loads .env files
5
9
  * contents.
10
+ *
11
+ * @param appRoot - The application root directory URL
12
+ * @returns Promise resolving to an EnvEditor instance
6
13
  */
7
14
  static create(appRoot: URL): Promise<EnvEditor>;
15
+ /**
16
+ * Constructs a new EnvEditor instance
17
+ *
18
+ * @param appRoot - The application root directory URL
19
+ */
8
20
  constructor(appRoot: URL);
9
21
  /**
10
22
  * Loads .env files for editing. Only ".env" and ".env.example"
11
23
  * files are picked for editing.
24
+ *
25
+ * @returns Promise that resolves when files are loaded
12
26
  */
13
27
  load(): Promise<void>;
14
28
  /**
15
29
  * Add key-value pair to the dot-env files.
16
30
  * If `withEmptyExampleValue` is true then the key will be added with an empty value
17
31
  * to the `.env.example` file.
32
+ *
33
+ * @param key - The environment variable key
34
+ * @param value - The environment variable value
35
+ * @param withEmptyExampleValue - Whether to add empty value to .env.example file
18
36
  */
19
37
  add(key: string, value: string | number | boolean, withEmptyExampleValue?: boolean): void;
38
+ /**
39
+ * Returns the loaded files as JSON
40
+ *
41
+ * @returns Array of file objects with contents and paths
42
+ */
20
43
  toJSON(): {
21
44
  contents: string[];
22
45
  path: string;
23
46
  }[];
24
47
  /**
25
48
  * Save changes to the disk
49
+ *
50
+ * @returns Promise that resolves when files are saved
26
51
  */
27
52
  save(): Promise<void>;
28
53
  }
@@ -1,24 +1,41 @@
1
1
  import {
2
2
  EnvLoader
3
- } from "../chunk-EIJZNYI6.js";
3
+ } from "../chunk-KE5AFOK2.js";
4
4
 
5
5
  // src/editor.ts
6
6
  import splitLines from "split-lines";
7
7
  import lodash from "@poppinss/utils/lodash";
8
8
  import { writeFile } from "fs/promises";
9
9
  var EnvEditor = class _EnvEditor {
10
+ /**
11
+ * The application root directory URL
12
+ */
10
13
  #appRoot;
14
+ /**
15
+ * Environment file loader instance
16
+ */
11
17
  #loader;
18
+ /**
19
+ * Array of loaded environment files with their contents and paths
20
+ */
12
21
  #files = [];
13
22
  /**
14
23
  * Creates an instance of env editor and loads .env files
15
24
  * contents.
25
+ *
26
+ * @param appRoot - The application root directory URL
27
+ * @returns Promise resolving to an EnvEditor instance
16
28
  */
17
29
  static async create(appRoot) {
18
30
  const editor = new _EnvEditor(appRoot);
19
31
  await editor.load();
20
32
  return editor;
21
33
  }
34
+ /**
35
+ * Constructs a new EnvEditor instance
36
+ *
37
+ * @param appRoot - The application root directory URL
38
+ */
22
39
  constructor(appRoot) {
23
40
  this.#appRoot = appRoot;
24
41
  this.#loader = new EnvLoader(this.#appRoot, true);
@@ -26,6 +43,8 @@ var EnvEditor = class _EnvEditor {
26
43
  /**
27
44
  * Loads .env files for editing. Only ".env" and ".env.example"
28
45
  * files are picked for editing.
46
+ *
47
+ * @returns Promise that resolves when files are loaded
29
48
  */
30
49
  async load() {
31
50
  const envFiles = await this.#loader.load();
@@ -42,6 +61,10 @@ var EnvEditor = class _EnvEditor {
42
61
  * Add key-value pair to the dot-env files.
43
62
  * If `withEmptyExampleValue` is true then the key will be added with an empty value
44
63
  * to the `.env.example` file.
64
+ *
65
+ * @param key - The environment variable key
66
+ * @param value - The environment variable value
67
+ * @param withEmptyExampleValue - Whether to add empty value to .env.example file
45
68
  */
46
69
  add(key, value, withEmptyExampleValue = false) {
47
70
  this.#files.forEach((file) => {
@@ -54,11 +77,18 @@ var EnvEditor = class _EnvEditor {
54
77
  }
55
78
  });
56
79
  }
80
+ /**
81
+ * Returns the loaded files as JSON
82
+ *
83
+ * @returns Array of file objects with contents and paths
84
+ */
57
85
  toJSON() {
58
86
  return this.#files;
59
87
  }
60
88
  /**
61
89
  * Save changes to the disk
90
+ *
91
+ * @returns Promise that resolves when files are saved
62
92
  */
63
93
  async save() {
64
94
  await Promise.all(
@@ -1,6 +1,6 @@
1
1
  import { schema as envSchema } from '@poppinss/validator-lite';
2
2
  import type { ValidateFn } from '@poppinss/validator-lite/types';
3
- import { EnvValidator } from './validator.js';
3
+ import { EnvValidator } from './validator.ts';
4
4
  /**
5
5
  * A wrapper over "process.env" with types information.
6
6
  *
@@ -17,11 +17,20 @@ import { EnvValidator } from './validator.js';
17
17
  */
18
18
  export declare class Env<EnvValues extends Record<string, any>> {
19
19
  #private;
20
+ /**
21
+ * Creates a new Env instance
22
+ *
23
+ * @param values - Validated environment values
24
+ */
20
25
  constructor(values: EnvValues);
21
26
  /**
22
27
  * Create an instance of the env class by validating the
23
28
  * environment variables. Also, the `.env` files are
24
29
  * loaded from the appRoot
30
+ *
31
+ * @param appRoot - The application root directory URL
32
+ * @param schema - Validation schema for environment variables
33
+ * @returns Promise resolving to an Env instance with validated values
25
34
  */
26
35
  static create<Schema extends {
27
36
  [key: string]: ValidateFn<unknown>;
@@ -33,21 +42,31 @@ export declare class Env<EnvValues extends Record<string, any>> {
33
42
  * when the value match the identifier to modify its interpolation.
34
43
  *
35
44
  * @deprecated use `Env.defineIdentifier` instead
45
+ * @param name - The identifier name
46
+ * @param callback - Callback function to process the identifier value
36
47
  */
37
48
  static identifier(name: string, callback: (value: string) => Promise<string> | string): void;
38
49
  /**
39
50
  * Define an identifier for any environment value. The callback is invoked
40
51
  * when the value match the identifier to modify its interpolation.
52
+ *
53
+ * @param name - The identifier name
54
+ * @param callback - Callback function to process the identifier value
41
55
  */
42
56
  static defineIdentifier(name: string, callback: (value: string) => Promise<string> | string): void;
43
57
  /**
44
58
  * Define an identifier for any environment value, if it's not already defined.
45
59
  * The callback is invoked when the value match the identifier to modify its
46
60
  * interpolation.
61
+ *
62
+ * @param name - The identifier name
63
+ * @param callback - Callback function to process the identifier value
47
64
  */
48
65
  static defineIdentifierIfMissing(name: string, callback: (value: string) => Promise<string> | string): void;
49
66
  /**
50
67
  * Remove an identifier
68
+ *
69
+ * @param name - The identifier name to remove
51
70
  */
52
71
  static removeIdentifier(name: string): void;
53
72
  /**
@@ -58,6 +77,9 @@ export declare class Env<EnvValues extends Record<string, any>> {
58
77
  * Define the validation rules for validating environment
59
78
  * variables. The return value is an instance of the
60
79
  * env validator
80
+ *
81
+ * @param schema - Validation schema object
82
+ * @returns EnvValidator instance
61
83
  */
62
84
  static rules<T extends {
63
85
  [key: string]: ValidateFn<unknown>;
@@ -76,6 +98,10 @@ export declare class Env<EnvValues extends Record<string, any>> {
76
98
  * // With default value
77
99
  * Env.get('PORT', 3000)
78
100
  * ```
101
+ *
102
+ * @param key - The environment variable key
103
+ * @param defaultValue - Default value if key is not found
104
+ * @returns The environment variable value or default
79
105
  */
80
106
  get<K extends keyof EnvValues>(key: K): EnvValues[K];
81
107
  get<K extends keyof EnvValues>(key: K, defaultValue: Exclude<EnvValues[K], undefined>): Exclude<EnvValues[K], undefined>;
@@ -93,6 +119,9 @@ export declare class Env<EnvValues extends Record<string, any>> {
93
119
  * Env.get('PORT') === 3000 // true
94
120
  * process.env.PORT === '3000' // true
95
121
  * ```
122
+ *
123
+ * @param key - The environment variable key
124
+ * @param value - The value to set
96
125
  */
97
126
  set<K extends keyof EnvValues>(key: K, value: EnvValues[K]): void;
98
127
  set(key: string, value: string): void;
@@ -1,7 +1,6 @@
1
1
  import { Exception } from '@poppinss/utils/exception';
2
2
  /**
3
- * Exception raised when one or more env variables
4
- * are invalid
3
+ * Exception raised when one or more env variables are invalid
5
4
  */
6
5
  export declare const E_INVALID_ENV_VARIABLES: {
7
6
  new (message?: string, options?: ErrorOptions & {
@@ -27,4 +26,7 @@ export declare const E_INVALID_ENV_VARIABLES: {
27
26
  prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
28
27
  stackTraceLimit: number;
29
28
  };
29
+ /**
30
+ * Exception raised when the identifier is already defined
31
+ */
30
32
  export declare const E_IDENTIFIER_ALREADY_DEFINED: new (args: [string], options?: ErrorOptions) => Exception;
@@ -22,10 +22,18 @@
22
22
  */
23
23
  export declare class EnvLoader {
24
24
  #private;
25
+ /**
26
+ * Creates a new EnvLoader instance
27
+ *
28
+ * @param appRoot - The application root directory as string or URL
29
+ * @param loadExampleFile - Whether to load .env.example file
30
+ */
25
31
  constructor(appRoot: string | URL, loadExampleFile?: boolean);
26
32
  /**
27
33
  * Load contents of the main dot-env file and the current
28
34
  * environment dot-env file
35
+ *
36
+ * @returns Promise resolving to array of loaded environment files
29
37
  */
30
38
  load(): Promise<{
31
39
  contents: string;
@@ -41,7 +41,14 @@ import { type DotenvParseOutput } from 'dotenv';
41
41
  */
42
42
  export declare class EnvParser {
43
43
  #private;
44
- constructor(envContents: string, options?: {
44
+ /**
45
+ * Creates a new EnvParser instance
46
+ *
47
+ * @param envContents - Raw environment file contents
48
+ * @param appRoot - Application root directory URL
49
+ * @param options - Parser options
50
+ */
51
+ constructor(envContents: string, appRoot: URL, options?: {
45
52
  ignoreProcessEnv: boolean;
46
53
  });
47
54
  /**
@@ -50,24 +57,42 @@ export declare class EnvParser {
50
57
  *
51
58
  * @deprecated use `EnvParser.defineIdentifier` instead
52
59
  */
60
+ /**
61
+ * Define an identifier for any environment value. The callback is invoked
62
+ * when the value match the identifier to modify its interpolation.
63
+ *
64
+ * @deprecated use `EnvParser.defineIdentifier` instead
65
+ * @param name - The identifier name
66
+ * @param callback - Callback function to process the identifier value
67
+ */
53
68
  static identifier(name: string, callback: (value: string) => Promise<string> | string): void;
54
69
  /**
55
70
  * Define an identifier for any environment value. The callback is invoked
56
71
  * when the value match the identifier to modify its interpolation.
72
+ *
73
+ * @param name - The identifier name
74
+ * @param callback - Callback function to process the identifier value
57
75
  */
58
76
  static defineIdentifier(name: string, callback: (value: string) => Promise<string> | string): void;
59
77
  /**
60
78
  * Define an identifier for any environment value, if it's not already defined.
61
79
  * The callback is invoked when the value match the identifier to modify its
62
80
  * interpolation.
81
+ *
82
+ * @param name - The identifier name
83
+ * @param callback - Callback function to process the identifier value
63
84
  */
64
85
  static defineIdentifierIfMissing(name: string, callback: (value: string) => Promise<string> | string): void;
65
86
  /**
66
87
  * Remove an identifier
88
+ *
89
+ * @param name - The identifier name to remove
67
90
  */
68
91
  static removeIdentifier(name: string): void;
69
92
  /**
70
93
  * Parse the env string to an object of environment variables.
94
+ *
95
+ * @returns Promise resolving to parsed environment variables
71
96
  */
72
97
  parse(): Promise<DotenvParseOutput>;
73
98
  }
@@ -3,9 +3,16 @@
3
3
  */
4
4
  export declare class EnvProcessor {
5
5
  #private;
6
+ /**
7
+ * Creates a new EnvProcessor instance
8
+ *
9
+ * @param appRoot - The application root directory URL
10
+ */
6
11
  constructor(appRoot: URL);
7
12
  /**
8
13
  * Process env variables
14
+ *
15
+ * @returns Promise resolving to processed environment variables
9
16
  */
10
17
  process(): Promise<Record<string, any>>;
11
18
  }
@@ -0,0 +1 @@
1
+ export type EnvIdentifierCallback = (value: string, key: string, appRoot: URL) => Promise<string> | string;
File without changes
@@ -9,6 +9,11 @@ export declare class EnvValidator<Schema extends {
9
9
  [key: string]: ValidateFn<unknown>;
10
10
  }> {
11
11
  #private;
12
+ /**
13
+ * Creates a new EnvValidator instance
14
+ *
15
+ * @param schema - The validation schema object
16
+ */
12
17
  constructor(schema: Schema);
13
18
  /**
14
19
  * Accepts an object of values to validate against the pre-defined
@@ -16,6 +21,9 @@ export declare class EnvValidator<Schema extends {
16
21
  *
17
22
  * The return value is a merged copy of the original object and the
18
23
  * values mutated by the schema validator.
24
+ *
25
+ * @param values - Object of environment variable values to validate
26
+ * @returns Validated and transformed environment variables
19
27
  */
20
28
  validate(values: {
21
29
  [K: string]: string | undefined;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adonisjs/env",
3
- "version": "7.0.0-next.0",
3
+ "version": "7.0.0-next.1",
4
4
  "description": "Environment variable manager for Node.js",
5
5
  "main": "build/index.js",
6
6
  "type": "module",
@@ -12,6 +12,7 @@
12
12
  ],
13
13
  "exports": {
14
14
  ".": "./build/index.js",
15
+ "./types": "./build/src/types.js",
15
16
  "./editor": "./build/src/editor.js"
16
17
  },
17
18
  "engines": {
@@ -33,24 +34,24 @@
33
34
  "quick:test": "node --import=@poppinss/ts-exec --enable-source-maps bin/test.ts"
34
35
  },
35
36
  "devDependencies": {
36
- "@adonisjs/eslint-config": "^3.0.0-next.0",
37
+ "@adonisjs/eslint-config": "^3.0.0-next.1",
37
38
  "@adonisjs/prettier-config": "^1.4.5",
38
39
  "@adonisjs/tsconfig": "^2.0.0-next.0",
39
40
  "@japa/assert": "^4.1.1",
40
41
  "@japa/expect-type": "^2.0.3",
41
42
  "@japa/file-system": "^2.3.2",
42
- "@japa/runner": "^4.3.0",
43
- "@poppinss/ts-exec": "^1.4.0",
43
+ "@japa/runner": "^4.4.0",
44
+ "@poppinss/ts-exec": "^1.4.1",
44
45
  "@release-it/conventional-changelog": "^10.0.1",
45
- "@types/node": "^24.1.0",
46
+ "@types/node": "^24.3.0",
46
47
  "c8": "^10.1.3",
47
48
  "cross-env": "^10.0.0",
48
49
  "del-cli": "^6.0.0",
49
- "eslint": "^9.32.0",
50
+ "eslint": "^9.34.0",
50
51
  "prettier": "^3.6.2",
51
52
  "release-it": "^19.0.4",
52
53
  "tsup": "^8.5.0",
53
- "typescript": "^5.8.3"
54
+ "typescript": "^5.9.2"
54
55
  },
55
56
  "dependencies": {
56
57
  "@poppinss/utils": "^7.0.0-next.3",
@@ -83,6 +84,7 @@
83
84
  "tsup": {
84
85
  "entry": [
85
86
  "./index.ts",
87
+ "./src/types.ts",
86
88
  "./src/editor.ts"
87
89
  ],
88
90
  "outDir": "./build",