@pitininja/envious 3.3.5 → 4.0.0

package/README.md

@@ -10,23 +10,69 @@ npm i @pitininja/envious
 
 ## Usage
 
-* Environment variables are automatically loaded using [Dotenv](https://github.com/motdotla/dotenv)
-* Refer to the [official Typebox documentation](https://github.com/sinclairzx81/typebox) for how to write a Typebox schema
+Environment variables are automatically loaded using [Dotenv](https://github.com/motdotla/dotenv).
+
+Refer to the [official Typebox documentation](https://github.com/sinclairzx81/typebox) for how to write a Typebox schema.
 
 ```typescript
+import { envious } from '@pitininja/envious';
 import { Type } from '@sinclair/typebox';
+
+const env = envious(
+    Type.Object({
+        STRING_VAR: Type.String(),
+        NUMBER_VAR: Type.Integer(),
+        BOOLEAN_VAR_WITH_DEFAULT: Type.Boolean({ default: false }),
+        OPTIONAL_VAR: Type.Optional(Type.String())
+    })
+);
+```
+
+## Formats
+
+String formats can be loaded in the `formats` property of the options parameter, as an object with the format name as key and a regex or a validation function as value.
+
+```typescript
 import { envious } from '@pitininja/envious';
+import { Type } from '@sinclair/typebox';
+import dayjs from 'dayjs';
+
+const env = envious(
+    Type.Object({
+        EXAMPLE_URI: Type.String({ format: 'uri' }),
+        EXAMPLE_DATE: Type.String({ format: 'date' })
+    }),
+    {
+        formats: {
+            uri: /^(?:[a-z][a-z0-9+\-.]*:)(?:\/?\/)?[^\s]*$/i,
+            date: (val) => dayjs(val).isValid()
+        }
+    }
+);
+```
+
+## Errors
+
+If something goes wrong, Envious will throw an error of class `EnviousError`.
+
+An `EnviousError` error contains a message and a list of `ValueError` (an error class taken from Typebox).
+
+Here is a simple example of how to handle Envious errors :
+
+```typescript
+import { envious, EnviousError } from '@pitininja/envious';
+import { Type } from '@sinclair/typebox';
 
-export const schema = Type.Object({
-    STRING_VAR: Type.String(),
-    NUMBER_VAR: Type.Integer(),
-    BOOLEAN_VAR_WITH_DEFAULT: Type.Boolean({ default: false }),
-    OPTIONAL_VAR: Type.Optional(Type.String())
-});
-
-/**
-Parse your environment variables.
-If the environment variables don't match the schema, an error will be thrown.
-*/
-const env = envious(schema);
+try {
+    const env = envious(
+        Type.Object({
+            STRING_VAR: Type.String()
+        })
+    );
+} catch (err: unknown) {
+    if (err instanceof EnviousError) {
+        console.log('Message:', err.message); // Error message
+        console.log('Errors:', err.errors); // Typebox's ValueError array
+    }
+}
 ```

package/dist/index.d.ts

@@ -1,3 +1,14 @@
 import 'dotenv/config';
-import type { Static, TObject } from '@sinclair/typebox';
-export declare const envious: <T extends TObject>(schema: T) => Static<T>;
+import { type Static, type TObject } from '@sinclair/typebox';
+import { type ValueError } from '@sinclair/typebox/value';
+export type EnviousFormats = {
+    [name: string]: RegExp | ((val: unknown) => boolean);
+};
+export type EnviousOptions = {
+    formats: EnviousFormats;
+};
+export declare class EnviousError extends Error {
+    errors: ValueError[];
+    constructor(message: string, errors?: ValueError[]);
+}
+export declare const envious: <T extends TObject>(schema: T, options?: EnviousOptions) => Static<T>;

package/dist/index.js

@@ -1,34 +1,48 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.envious = void 0;
+exports.envious = exports.EnviousError = void 0;
 require("dotenv/config");
-const node_os_1 = __importDefault(require("node:os"));
+const typebox_1 = require("@sinclair/typebox");
 const value_1 = require("@sinclair/typebox/value");
-const envious = (schema) => {
-    const parsed = value_1.Value.Parse(schema, process.env);
-    const errors = [...value_1.Value.Errors(schema, parsed)];
-    if (errors.length) {
-        const computedErrorMessages = {};
-        for (const { path, message } of errors) {
-            const envVarName = path.replace(/^\//, '');
-            if (!computedErrorMessages[envVarName]) {
-                computedErrorMessages[envVarName] = [];
-            }
-            computedErrorMessages[envVarName].push(message);
+class EnviousError extends Error {
+    errors;
+    constructor(message, errors) {
+        super(message);
+        this.errors = errors ?? [];
+    }
+}
+exports.EnviousError = EnviousError;
+const setFormats = (formats) => {
+    for (const name of Object.keys(formats)) {
+        const format = formats[name];
+        typebox_1.FormatRegistry.Set(name, format instanceof RegExp ? (val) => format.test(val) : format);
+    }
+};
+const envious = (schema, options) => {
+    const invalidEnvVarMessage = 'Invalid environment variables';
+    try {
+        if (options?.formats) {
+            setFormats(options.formats);
+        }
+        const parsed = value_1.Value.Parse(schema, process.env);
+        const errors = [...value_1.Value.Errors(schema, parsed)];
+        if (errors.length) {
+            throw new EnviousError(invalidEnvVarMessage, errors);
+        }
+        return value_1.Value.Cast({
+            ...schema,
+            additionalProperties: false
+        }, parsed);
+    }
+    catch (err) {
+        if (err instanceof EnviousError) {
+            throw err;
+        }
+        if (err instanceof value_1.AssertError) {
+            throw new EnviousError(invalidEnvVarMessage, err.error ? [err.error] : []);
         }
-        const errorTextParts = [
-            'Invalid environment variables',
-            ...Object.entries(computedErrorMessages).map(([varName, messages]) => `  ${varName} : ${messages.join(', ')}`)
-        ];
-        throw new Error(errorTextParts.join(node_os_1.default.EOL));
+        throw new EnviousError(`Unexpected error while parsing environment variables${err instanceof Error ? ` (${err.message})` : ''}`);
     }
-    return value_1.Value.Cast({
-        ...schema,
-        additionalProperties: false
-    }, parsed);
 };
 exports.envious = envious;
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AAAA,yBAAuB;AACvB,sDAAyB;AAEzB,mDAAgD;AAEzC,MAAM,OAAO,GAAG,CAAoB,MAAS,EAAa,EAAE;IAC/D,MAAM,MAAM,GAAG,aAAK,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,CAAC,GAAG,aAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAChB,MAAM,qBAAqB,GAA6B,EAAE,CAAC;QAC3D,KAAK,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,MAAM,EAAE,CAAC;YACrC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAC3C,IAAI,CAAC,qBAAqB,CAAC,UAAU,CAAC,EAAE,CAAC;gBACrC,qBAAqB,CAAC,UAAU,CAAC,GAAG,EAAE,CAAC;YAC3C,CAAC;YACD,qBAAqB,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpD,CAAC;QACD,MAAM,cAAc,GAAa;YAC7B,+BAA+B;YAC/B,GAAG,MAAM,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC,GAAG,CACxC,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,KAAK,OAAO,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACnE;SACJ,CAAC;QACF,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,iBAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,aAAK,CAAC,IAAI,CACb;QACI,GAAG,MAAM;QACT,oBAAoB,EAAE,KAAK;KAC9B,EACD,MAAM,CACT,CAAC;AACN,CAAC,CAAC;AA3BW,QAAA,OAAO,WA2BlB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,yBAAuB;AACvB,+CAA8E;AAC9E,mDAA8E;AAU9E,MAAa,YAAa,SAAQ,KAAK;IACnC,MAAM,CAAe;IACrB,YAAY,OAAe,EAAE,MAAqB;QAC9C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,EAAE,CAAC;IAC/B,CAAC;CACJ;AAND,oCAMC;AAED,MAAM,UAAU,GAAG,CAAC,OAAuB,EAAE,EAAE;IAC3C,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7B,wBAAc,CAAC,GAAG,CACd,IAAI,EACJ,MAAM,YAAY,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAChE,CAAC;IACN,CAAC;AACL,CAAC,CAAC;AAEK,MAAM,OAAO,GAAG,CACnB,MAAS,EACT,OAAwB,EACf,EAAE;IACX,MAAM,oBAAoB,GAAG,+BAA+B,CAAC;IAC7D,IAAI,CAAC;QACD,IAAI,OAAO,EAAE,OAAO,EAAE,CAAC;YACnB,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;QACD,MAAM,MAAM,GAAG,aAAK,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QAChD,MAAM,MAAM,GAAG,CAAC,GAAG,aAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QACjD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAChB,MAAM,IAAI,YAAY,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC;QACzD,CAAC;QACD,OAAO,aAAK,CAAC,IAAI,CACb;YACI,GAAG,MAAM;YACT,oBAAoB,EAAE,KAAK;SAC9B,EACD,MAAM,CACT,CAAC;IACN,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACpB,IAAI,GAAG,YAAY,YAAY,EAAE,CAAC;YAC9B,MAAM,GAAG,CAAC;QACd,CAAC;QACD,IAAI,GAAG,YAAY,mBAAW,EAAE,CAAC;YAC7B,MAAM,IAAI,YAAY,CAClB,oBAAoB,EACpB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAC/B,CAAC;QACN,CAAC;QACD,MAAM,IAAI,YAAY,CAClB,uDAAuD,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAC3G,CAAC;IACN,CAAC;AACL,CAAC,CAAC;AAnCW,QAAA,OAAO,WAmClB"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@pitininja/envious",
-    "version": "3.3.5",
+    "version": "4.0.0",
     "license": "AGPL-3.0-or-later",
     "homepage": "https://github.com/pitininja/envious",
     "repository": {
@@ -24,7 +24,7 @@
     "devDependencies": {
         "@biomejs/biome": "^1.9.4",
         "@tsconfig/recommended": "^1.0.8",
-        "@types/node": "^22.8.4",
+        "@types/node": "^22.8.7",
         "@vitest/coverage-istanbul": "^2.1.4",
         "husky": "^9.1.6",
         "typescript": "^5.6.3",