@pitininja/envious 6.0.0-beta6 → 6.0.0

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.
package/README.md ADDED
@@ -0,0 +1,159 @@
1
+ # Envious
2
+
3
+ [![npm version](https://badge.fury.io/js/@pitininja%2Fenvious.svg)](https://badge.fury.io/js/@pitininja%2Fenvious)
4
+
5
+ > Parse and validate environment variables
6
+
7
+ - [Install](#install)
8
+ - [Resolvers](#resolvers)
9
+ - [Usage](#usage)
10
+ - [Options](#options)
11
+ - [Errors](#errors)
12
+ - [Migration](#migration)
13
+ - [Legacy versions](#legacy-versions)
14
+
15
+ ## Install
16
+
17
+ Envious works by installing and using two packages : the core package and a resolver.
18
+
19
+ ### Core package
20
+
21
+ ```shell
22
+ npm i @pitininja/envious
23
+ ```
24
+
25
+ ### Resolvers
26
+
27
+ #### Typebox
28
+
29
+ ```shell
30
+ npm i @pitininja/envious-typebox
31
+ ```
32
+
33
+ - [Typebox resolver documentation](https://codeberg.org/pitininja/envious/src/branch/master/packages/resolvers/typebox/README.md)
34
+ - [Official Typebox documentation](https://sinclairzx81.github.io/typebox/)
35
+
36
+ #### Zod
37
+
38
+ ```shell
39
+ npm i @pitininja/envious-zod
40
+ ```
41
+
42
+ - [Zod resolver documentation](https://codeberg.org/pitininja/envious/src/branch/master/packages/resolvers/zod/README.md)
43
+ - [Official Zod documentation](https://zod.dev/)
44
+
45
+ ## Usage
46
+
47
+ Here is an example using the Typebox resolver :
48
+
49
+ ```typescript
50
+ import { envious } from '@pitininja/envious';
51
+ import { typeboxResolver } from '@pitininja/envious-typebox';
52
+ import { Type } from '@sinclair/typebox';
53
+
54
+ const env = envious({
55
+ resolver: typeboxResolver({
56
+ schema: Type.Object({
57
+ STRING_VAR: Type.String(),
58
+ NUMBER_VAR: Type.Integer(),
59
+ BOOLEAN_VAR_WITH_DEFAULT: Type.Boolean({ default: false }),
60
+ OPTIONAL_VAR: Type.Optional(Type.String())
61
+ })
62
+ })
63
+ });
64
+ ```
65
+
66
+ Then run the script with loaded environment variables, and these variables will be parsed and validated.
67
+
68
+ ```shell
69
+ # Example loading environment variables with Node.js
70
+ node --env-file=.env index.js
71
+ # Example loading environment variables with TSX
72
+ tsx --env-file=.env index.ts
73
+ # Example loading environment variables with DotEnv
74
+ dotenv -e .env -- node index.js
75
+ ```
76
+
77
+ ## Options
78
+
79
+ ### Logging
80
+
81
+ In addition to throwing an `EnviousError`, errors can be logged in the console. To do so, use the `logErrors` option :
82
+
83
+ ```typescript
84
+ import { envious } from '@pitininja/envious';
85
+ import { typeboxResolver } from '@pitininja/envious-typebox';
86
+ import { Type } from '@sinclair/typebox';
87
+
88
+ const env = envious({
89
+ resolver: typeboxResolver({
90
+ schema: Type.Object({
91
+ STRING_VAR: Type.String()
92
+ })
93
+ }),
94
+ logErrors: true
95
+ });
96
+ ```
97
+
98
+ You can also provide your own logging function :
99
+
100
+ ```typescript
101
+ import { envious } from '@pitininja/envious';
102
+ import { typeboxResolver } from '@pitininja/envious-typebox';
103
+ import { Type } from '@sinclair/typebox';
104
+
105
+ const env = envious({
106
+ resolver: typeboxResolver({
107
+ schema: Type.Object({
108
+ STRING_VAR: Type.String()
109
+ })
110
+ }),
111
+ logErrors: true,
112
+ logger: (message) => {
113
+ myCustomLogger(message)
114
+ }
115
+ });
116
+ ```
117
+
118
+ ## Errors
119
+
120
+ If something goes wrong, Envious will throw an error of class `EnviousError`.
121
+
122
+ An `EnviousError` error contains a message and a list of `EnviousErrorVariable`.
123
+
124
+ Here is a simple example of how to handle Envious errors :
125
+
126
+ ```typescript
127
+ import { envious, EnviousError } from '@pitininja/envious';
128
+ import { typeboxResolver } from '@pitininja/envious-typebox';
129
+ import { Type } from '@sinclair/typebox';
130
+
131
+ try {
132
+ const env = envious({
133
+ resolver: typeboxResolver({
134
+ schema: Type.Object({
135
+ STRING_VAR: Type.String()
136
+ })
137
+ })
138
+ });
139
+ } catch (err: unknown) {
140
+ if (err instanceof EnviousError) {
141
+ // General error message
142
+ console.log('Message:', err.message);
143
+ // Array of EnviousErrorVariable
144
+ console.log('Errors:', err.errors);
145
+ for (const { name, messages } of err.errors) {
146
+ // Variable name and error messages related to that variable
147
+ console.log(`${name} : ${messages.join(', ')}`);
148
+ }
149
+ }
150
+ }
151
+ ```
152
+
153
+ ## Migration
154
+
155
+ [Migration guide to v6](https://codeberg.org/pitininja/envious/src/branch/master/doc/migration-v6.md)
156
+
157
+ ## Legacy versions
158
+
159
+ [Legacy documentation for v5 or lower](https://codeberg.org/pitininja/envious/src/branch/master/doc/legacy.md)
@@ -0,0 +1,28 @@
1
+ export type EnviousErrorVariable = {
2
+ name: string;
3
+ messages: string[];
4
+ };
5
+ type EnviousErrorOptions<T> = {
6
+ message?: string;
7
+ } & ({
8
+ variables?: never;
9
+ transform?: never;
10
+ resolverErrors?: never;
11
+ } | {
12
+ variables: EnviousErrorVariable[];
13
+ transform?: never;
14
+ resolverErrors?: never;
15
+ } | {
16
+ variables?: never;
17
+ transform: (resolverError: T) => {
18
+ name: string;
19
+ message: string;
20
+ };
21
+ resolverErrors: T[];
22
+ });
23
+ export declare class EnviousError<T> extends Error {
24
+ variables: EnviousErrorVariable[];
25
+ constructor({ message, variables, transform, resolverErrors }: EnviousErrorOptions<T>);
26
+ private resolverErrorsToErrorVariables;
27
+ }
28
+ export {};
package/dist/error.js ADDED
@@ -0,0 +1,36 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.EnviousError = void 0;
4
+ class EnviousError extends Error {
5
+ variables;
6
+ constructor({ message = 'Invalid environment variables', variables, transform, resolverErrors }) {
7
+ super(message);
8
+ if (variables) {
9
+ this.variables = variables;
10
+ }
11
+ else if (transform && resolverErrors) {
12
+ this.variables = this.resolverErrorsToErrorVariables({
13
+ transform,
14
+ resolverErrors
15
+ });
16
+ }
17
+ else {
18
+ this.variables = [];
19
+ }
20
+ }
21
+ resolverErrorsToErrorVariables({ transform, resolverErrors }) {
22
+ const variables = [];
23
+ const validationErrorsMap = new Map();
24
+ for (const resolverError of resolverErrors) {
25
+ const { name, message } = transform(resolverError);
26
+ const errorMessages = validationErrorsMap.get(name);
27
+ validationErrorsMap.set(name, [...(errorMessages ?? []), message]);
28
+ }
29
+ for (const [name, messages] of validationErrorsMap.entries()) {
30
+ variables.push({ name, messages });
31
+ }
32
+ return variables;
33
+ }
34
+ }
35
+ exports.EnviousError = EnviousError;
36
+ //# sourceMappingURL=error.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":";;;AAoCA,kBAA6B,SAAQ,KAAK;IACtC,SAAS,CAAyB;IAElC,YAAY,EACR,OAAO,GAAG,+BAA+B,EACzC,SAAS,EACT,SAAS,EACT,cAAc,EACO,EAAE;QACvB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,SAAS,EAAE,CAAC;YACZ,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC/B,CAAC;aAAM,IAAI,SAAS,IAAI,cAAc,EAAE,CAAC;YACrC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,8BAA8B,CAAC;gBACjD,SAAS;gBACT,cAAc;aACjB,CAAC,CAAC;QACP,CAAC;aAAM,CAAC;YACJ,IAAI,CAAC,SAAS,GAAG,EAAE,CAAC;QACxB,CAAC;IAAA,CACJ;IAEO,8BAA8B,CAAI,EACtC,SAAS,EACT,cAAc,EACyB,EAAE;QACzC,MAAM,SAAS,GAA2B,EAAE,CAAC;QAC7C,MAAM,mBAAmB,GAAG,IAAI,GAAG,EAAoB,CAAC;QACxD,KAAK,MAAM,aAAa,IAAI,cAAc,EAAE,CAAC;YACzC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,SAAS,CAAC,aAAa,CAAC,CAAC;YACnD,MAAM,aAAa,GAAG,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACpD,mBAAmB,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QACvE,CAAC;QACD,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,mBAAmB,CAAC,OAAO,EAAE,EAAE,CAAC;YAC3D,SAAS,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,SAAS,CAAC;IAAA,CACpB;CACJ"}
@@ -1,5 +1,5 @@
1
- import { EnviousError, type EnviousErrorVariable } from '../../common/error';
2
- export { EnviousError, type EnviousErrorVariable };
1
+ import { EnviousError } from './error';
2
+ export { EnviousError };
3
3
  type EnviousResolver<T> = (env: NodeJS.ProcessEnv) => T;
4
4
  export type EnviousOptions<T> = {
5
5
  resolver: EnviousResolver<T>;
@@ -1,7 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.envious = exports.EnviousError = void 0;
4
- const error_1 = require("../../common/error");
4
+ const error_1 = require("./error");
5
5
  Object.defineProperty(exports, "EnviousError", { enumerable: true, get: function () { return error_1.EnviousError; } });
6
6
  const logErrorVariables = (variables, logger) => {
7
7
  // biome-ignore lint/suspicious/noConsole: console default is the default logger here
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAAkE;6FAAzD,oBAAY;AAYrB,MAAM,iBAAiB,GAAG,CACtB,SAAiC,EACjC,MAAkC,EACpC,EAAE,CAAC;IACD,qFAAqF;IACrF,MAAM,GAAG,GAAG,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC;IACpC,GAAG,CAAC,2CAA2C,CAAC,CAAC;IACjD,KAAK,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,SAAS,EAAE,CAAC;QACzC,GAAG,CAAC,OAAO,IAAI,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChD,CAAC;AAAA,CACJ,CAAC;AAEK,MAAM,OAAO,GAAG,CAAI,EACvB,QAAQ,EACR,SAAS,EACT,MAAM,EACU,EAAE,EAAE,CAAC;IACrB,IAAI,CAAC;QACD,OAAO,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,IAAI,GAAG,YAAY,oBAAY,EAAE,CAAC;YAC9B,IAAI,SAAS,EAAE,CAAC;gBACZ,iBAAiB,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YAC7C,CAAC;YACD,MAAM,GAAG,CAAC;QACd,CAAC;QACD,MAAM,IAAI,oBAAY,CAAC;YACnB,OAAO,EAAE,uDAAuD,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE;SACpH,CAAC,CAAC;IACP,CAAC;AAAA,CACJ,CAAC;AAlBW,QAAA,OAAO,GAAP,OAAO,CAkBlB"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pitininja/envious",
3
- "version": "6.0.0-beta6",
3
+ "version": "6.0.0",
4
4
  "license": "AGPL-3.0-or-later",
5
5
  "homepage": "https://codeberg.org/pitininja/envious",
6
6
  "repository": {
@@ -12,11 +12,12 @@
12
12
  },
13
13
  "files": [
14
14
  "./dist",
15
- "./package.json"
15
+ "./package.json",
16
+ "./README.md"
16
17
  ],
17
- "main": "./dist/core/src/index.js",
18
- "types": "./dist/core/src/index.d.ts",
18
+ "main": "./dist/index.js",
19
+ "types": "./dist/index.d.ts",
19
20
  "scripts": {
20
- "build": "npx tsgo --build --clean tsconfig.json && npx tsgo -b ./tsconfig.json"
21
+ "build": "npx tsgo --build --clean ./tsconfig.build.json && npx tsgo -b ./tsconfig.build.json"
21
22
  }
22
23
  }
@@ -1,21 +0,0 @@
1
- export type EnviousErrorVariable = {
2
- name: string;
3
- messages: string[];
4
- };
5
- type EnviousErrorOptions = {
6
- message?: string;
7
- variables?: EnviousErrorVariable[];
8
- };
9
- export declare class EnviousError extends Error {
10
- variables: EnviousErrorVariable[];
11
- constructor({ message, variables }: EnviousErrorOptions);
12
- }
13
- type ResolverErrorsToEnviousErrorsOptions<T> = {
14
- transform: (resolverError: T) => {
15
- name: string;
16
- message: string;
17
- };
18
- resolverErrors: T[];
19
- };
20
- export declare const resolverErrorsToEnviousErrors: <T>({ transform, resolverErrors }: ResolverErrorsToEnviousErrorsOptions<T>) => EnviousErrorVariable[];
21
- export {};
@@ -1,26 +0,0 @@
1
- "use strict";
2
- Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.resolverErrorsToEnviousErrors = exports.EnviousError = void 0;
4
- class EnviousError extends Error {
5
- variables;
6
- constructor({ message = 'Invalid environment variables', variables = [] }) {
7
- super(message);
8
- this.variables = variables;
9
- }
10
- }
11
- exports.EnviousError = EnviousError;
12
- const resolverErrorsToEnviousErrors = ({ transform, resolverErrors }) => {
13
- const enviousErrors = [];
14
- const validationErrorsMap = new Map();
15
- for (const resolverError of resolverErrors) {
16
- const { name, message } = transform(resolverError);
17
- const errorMessages = validationErrorsMap.get(name);
18
- validationErrorsMap.set(name, [...(errorMessages ?? []), message]);
19
- }
20
- for (const [name, messages] of validationErrorsMap.entries()) {
21
- enviousErrors.push({ name, messages });
22
- }
23
- return enviousErrors;
24
- };
25
- exports.resolverErrorsToEnviousErrors = resolverErrorsToEnviousErrors;
26
- //# sourceMappingURL=error.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"error.js","sourceRoot":"","sources":["../../../common/error.ts"],"names":[],"mappings":";;;AAUA,kBAA0B,SAAQ,KAAK;IACnC,SAAS,CAAyB;IAClC,YAAY,EACR,OAAO,GAAG,+BAA+B,EACzC,SAAS,GAAG,EAAE,EACI,EAAE;QACpB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAAA,CAC9B;CACJ;;AAUM,MAAM,6BAA6B,GAAG,CAAI,EAC7C,SAAS,EACT,cAAc,EACwB,EAAE,EAAE,CAAC;IAC3C,MAAM,aAAa,GAA2B,EAAE,CAAC;IACjD,MAAM,mBAAmB,GAAG,IAAI,GAAG,EAAoB,CAAC;IACxD,KAAK,MAAM,aAAa,IAAI,cAAc,EAAE,CAAC;QACzC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,SAAS,CAAC,aAAa,CAAC,CAAC;QACnD,MAAM,aAAa,GAAG,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpD,mBAAmB,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IACvE,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,mBAAmB,CAAC,OAAO,EAAE,EAAE,CAAC;QAC3D,aAAa,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,aAAa,CAAC;AAAA,CACxB,CAAC;AAfW,QAAA,6BAA6B,GAA7B,6BAA6B,CAexC"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":";;;AAAA,8CAA6E;6FAApE,oBAAY;AAYrB,MAAM,iBAAiB,GAAG,CACtB,SAAiC,EACjC,MAAkC,EACpC,EAAE,CAAC;IACD,qFAAqF;IACrF,MAAM,GAAG,GAAG,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC;IACpC,GAAG,CAAC,2CAA2C,CAAC,CAAC;IACjD,KAAK,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,SAAS,EAAE,CAAC;QACzC,GAAG,CAAC,OAAO,IAAI,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChD,CAAC;AAAA,CACJ,CAAC;AAEK,MAAM,OAAO,GAAG,CAAI,EACvB,QAAQ,EACR,SAAS,EACT,MAAM,EACU,EAAE,EAAE,CAAC;IACrB,IAAI,CAAC;QACD,OAAO,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,IAAI,GAAG,YAAY,oBAAY,EAAE,CAAC;YAC9B,IAAI,SAAS,EAAE,CAAC;gBACZ,iBAAiB,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;YAC7C,CAAC;YACD,MAAM,GAAG,CAAC;QACd,CAAC;QACD,MAAM,IAAI,oBAAY,CAAC;YACnB,OAAO,EAAE,uDAAuD,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE;SACpH,CAAC,CAAC;IACP,CAAC;AAAA,CACJ,CAAC;AAlBW,QAAA,OAAO,GAAP,OAAO,CAkBlB"}