convex-env 1.0.2 → 2.1.0

package/README.md

@@ -3,21 +3,22 @@
 </p>
 
 <h2 align="center">Convex Env</h2>
-<p align="center">Typesafe access to environment variables in Convex</p>
+<p align="center">Type-safe access to environment variables in Convex</p>
 
 ### Overview
 
-If you've ever used [t3-env](https://github.com/t3-oss/t3-env), it's basically that, but native to [Convex](https://www.convex.dev).
+Similar to [t3-env](https://github.com/t3-oss/t3-env), but native to [Convex](https://www.convex.dev).
 
 Validators currently supported:
 
 - v.string()
 - v.number()
 - v.boolean()
+- v.union() + v.literal() (strings only)
 
-you can use `v.optional()` on _any_ supported validator, see [example](#usage) below
+You can use `v.optional()` on _any_ supported validator, see [examples](#usage) below
 
-<span style="color: red;"><strong>IMPORTANT</strong></span>: The <code>env</code> object from <code>createEnv</code> should only be used in the Convex runtime, the values on it will not be accessible client side.
+<span style="color: red;"><strong>IMPORTANT</strong></span>: The <code>env</code> object from <code>createEnv</code> should only be used in the Convex runtime, the values on it will not be accessible client-side.
 
 ### Installation
 
@@ -50,6 +51,7 @@ import { createEnv } from "convex-env";
 import { v } from "convex/values";
 
 export const env = createEnv({
+  ENVIRONMENT: v.union(v.literal("development"), v.literal("production")),
   CONVEX_SITE_URL: v.string(),
   BETTER_AUTH_SECRET: v.string(),
   GOOGLE_CLIENT_ID: v.string(),
@@ -79,7 +81,7 @@ export const createAuth = (ctx: GenericCtx<DataModel>) => {
 };
 ```
 
-You can also pass values manually
+You can optionally pass values manually
 
 ```typescript
 // convex/convex.env.ts
@@ -87,24 +89,50 @@ You can also pass values manually
 import { createEnv } from "convex-env";
 import { v } from "convex/values";
 
-export const env = createEnv(
-  {
+export const env = createEnv({
+  schema: {
     CONVEX_SITE_URL: v.string(),
-    BETTER_AUTH_SECRET: v.string(),
-    GOOGLE_CLIENT_ID: v.string(),
-    GOOGLE_CLIENT_SECRET: v.string(),
     MAX_REQUESTS_PER_USER: v.number(),
     DEBUG_MODE: v.optional(v.boolean()),
   },
-  {
+  // optional, defaults to process.env
+  values: {
     CONVEX_SITE_URL: process.env.CONVEX_SITE_URL,
-    BETTER_AUTH_SECRET: process.env.BETTER_AUTH_SECRET,
-    GOOGLE_CLIENT_ID: process.env.GOOGLE_CLIENT_ID,
-    GOOGLE_CLIENT_SECRET: process.env.GOOGLE_CLIENT_SECRET,
     MAX_REQUESTS_PER_USER: process.env.MAX_REQUESTS_PER_USER,
     DEBUG_MODE: process.env.DEBUG_MODE,
-  }
-);
+  },
+});
+```
+
+If you're running into an issue where it says an environment variable isn't found when you **know for a fact** that it is there, then you may need to use `verifyEnv` to verify the existence and type separately from the creation of the env object.
+
+```typescript
+// convex/convex.env.ts
+
+import { createEnv } from "convex-env";
+import { v } from "convex/values";
+
+export const schema = {
+  CONVEX_SITE_URL: v.string(),
+  MAX_REQUESTS_PER_USER: v.number(),
+  DEBUG_MODE: v.optional(v.boolean()),
+};
+
+export const env = createEnv({
+  schema,
+  options: {
+    skipValidation: true,
+  },
+});
+```
+
+```typescript
+// convex/convex.config.ts
+
+import { schema } from "./convex.env";
+import { verifyEnv } from "convex-env";
+
+verifyEnv(schema);
 ```
 
 ### Why use it?

package/dist/index.d.mts

@@ -1,19 +1,25 @@
-import { Infer, VBoolean, VFloat64, VOptional, VString } from "convex/values";
+import { Infer, VBoolean, VFloat64, VLiteral, VOptional, VString, VUnion } from "convex/values";
 
 //#region src/types.d.ts
-type AllowedPrimitiveValidators = VString | VFloat64 | VBoolean;
+type AllowedBaseValidators = VString | VFloat64 | VBoolean;
+type AllowedLiteralValidators = VLiteral<string>;
+type AllowedUnionValidators = VUnion<any, [AllowedLiteralValidators, AllowedLiteralValidators, ...AllowedLiteralValidators[]]>;
+type AllowedPrimitiveValidators = AllowedBaseValidators | AllowedLiteralValidators | AllowedUnionValidators;
 type AllowedOptionalValidators = VOptional<AllowedPrimitiveValidators>;
 type AllowedValidators = AllowedPrimitiveValidators | AllowedOptionalValidators;
 type InferredOuput<V extends AllowedValidators> = Infer<V>;
+type Values<Schema> = Partial<Record<keyof Schema, string | undefined>>;
+type CreateEnvOptions = {
+  skipValidation?: boolean;
+};
 //#endregion
 //#region src/index.d.ts
 /**
- * WARNING: The object returned by `createEnv` should only be accessed within the Convex runtime.
- * The values on the returned object will NOT be accessible  client side.
  *
- * @param entries - The names of the environment variables and their validators
- * @param inputEnv (Optional) pass in a record of the values to use, defaults to process.env if not provided
- * @returns An object with the same keys as the entries, but with the validated typesafe values
+ * WARNING: The object returned by `createEnv` should only be accessed within the Convex runtime. The values on the returned object will NOT be accessible client-side.
+ *
+ * @param args - You can either pass in the schema object directly, or an object with the schema, values, and options. See examples below.
+ * @returns An object with the same keys as the schema, but with validated type-safe values.
  *
  * @public
  *
@@ -26,16 +32,55 @@ type InferredOuput<V extends AllowedValidators> = Infer<V>;
  *
  * @example
  * const env = createEnv({
+ *   schema: {
+ *     FOO: v.string(),
+ *     BAR: v.number(),
+ *     BAZ: v.optional(v.boolean()),
+ *   },
+ *   values: {
+ *     FOO: process.env.FOO,
+ *     BAR: "42",
+ *     BAZ: "true",
+ *   },
+ *   options: {
+ *     skipValidation: true,
+ *   },
+ * });
+ *
+ */
+declare const createEnv: <Schema extends Record<string, AllowedValidators>>(args: Schema | {
+  schema: Schema;
+  values?: Values<Schema>;
+  options?: CreateEnvOptions;
+}) => { [K in keyof Schema]: InferredOuput<Schema[K]> };
+/**
+ *
+ * @description You may want to verify the existence and type of the environment variables separately from the creation of the env object. If so, use this function in convex.config.ts, and use the skipValidation option when calling createEnv.
+ *
+ * @param args - You can either pass in the schema object directly, or an object with the schema and values. See examples below.
+ * @returns void
+ *
+ * @public
+ *
+ * @example
+ * const schema = {
  *   FOO: v.string(),
  *   BAR: v.number(),
  *   BAZ: v.boolean(),
- * }, {
- *   FOO: process.env.FOO,
- *   BAR: process.env.BAR,
- *   BAZ: process.env.BAZ,
- * });
+ * };
+ * verifyEnv(schema);
  *
+ * @example
+ * const schema = {
+ *   FOO: v.string(),
+ *   BAR: v.number(),
+ *   BAZ: v.boolean(),
+ * };
+ * verifyEnv({ schema, values: { FOO: process.env.FOO, BAR: "42", BAZ: "true" } });
  */
-declare const createEnv: <T extends Record<string, AllowedValidators>>(entries: T, inputEnv?: Partial<Record<keyof T, string | undefined>>) => { [K in keyof T]: InferredOuput<T[K]> };
+declare const verifyEnv: <Schema extends Record<string, AllowedValidators>>(args: Schema | {
+  schema: Schema;
+  values?: Values<Schema>;
+}) => void;
 //#endregion
-export { createEnv };
+export { createEnv, verifyEnv };

package/dist/index.mjs

@@ -1,13 +1,14 @@
 import { validate } from "convex-helpers/validators";
-import { v } from "convex/values";
 
 //#region src/transform.ts
 const transformed = (value, validator) => {
 	if (value === void 0) return void 0;
 	if (value.trim() === "") throw new Error("Value is empty");
-	if (validator.kind === v.string().kind) return value;
-	if (validator.kind === v.number().kind) return validateAndTransformNumber(value);
-	if (validator.kind === v.boolean().kind) return validateAndTransformBoolean(value);
+	if (validator.kind === "union") return value;
+	if (validator.kind === "literal") return value;
+	if (validator.kind === "string") return value;
+	if (validator.kind === "float64") return validateAndTransformNumber(value);
+	if (validator.kind === "boolean") return validateAndTransformBoolean(value);
 	throw new Error("Validator is not supported");
 };
 const validateAndTransformNumber = (value) => {
@@ -24,12 +25,11 @@ const validateAndTransformBoolean = (value) => {
 //#endregion
 //#region src/index.ts
 /**
-* WARNING: The object returned by `createEnv` should only be accessed within the Convex runtime.
-* The values on the returned object will NOT be accessible  client side.
 *
-* @param entries - The names of the environment variables and their validators
-* @param inputEnv (Optional) pass in a record of the values to use, defaults to process.env if not provided
-* @returns An object with the same keys as the entries, but with the validated typesafe values
+* WARNING: The object returned by `createEnv` should only be accessed within the Convex runtime. The values on the returned object will NOT be accessible client-side.
+*
+* @param args - You can either pass in the schema object directly, or an object with the schema, values, and options. See examples below.
+* @returns An object with the same keys as the schema, but with validated type-safe values.
 *
 * @public
 *
@@ -42,25 +42,42 @@ const validateAndTransformBoolean = (value) => {
 *
 * @example
 * const env = createEnv({
-*   FOO: v.string(),
-*   BAR: v.number(),
-*   BAZ: v.boolean(),
-* }, {
-*   FOO: process.env.FOO,
-*   BAR: process.env.BAR,
-*   BAZ: process.env.BAZ,
+*   schema: {
+*     FOO: v.string(),
+*     BAR: v.number(),
+*     BAZ: v.optional(v.boolean()),
+*   },
+*   values: {
+*     FOO: process.env.FOO,
+*     BAR: "42",
+*     BAZ: "true",
+*   },
+*   options: {
+*     skipValidation: true,
+*   },
 * });
 *
 */
-const createEnv = (entries, inputEnv) => {
-	const env = inputEnv ?? process.env;
-	return Object.keys(entries).map((key) => {
+const createEnv = (args) => {
+	let schema;
+	let inputValues;
+	let options;
+	const isSchemaObject = (arg) => {
+		return "schema" in arg;
+	};
+	if (isSchemaObject(args)) {
+		schema = args.schema;
+		inputValues = args.values;
+		options = args.options;
+	} else schema = args;
+	const values = inputValues ?? process.env;
+	return Object.keys(schema).map((key) => {
 		try {
-			const validator = entries[key];
-			const envValue = env[key];
-			if (validator.isOptional === "required" && envValue === void 0) throw new Error("Variable is required but not found in env");
+			const validator = schema[key];
+			const envValue = values[key];
+			if (validator.isOptional === "required" && envValue === void 0 && options?.skipValidation !== true) throw new Error("Variable is required but not found in env");
 			const transformedValue = transformed(envValue, validator);
-			if (validate(validator, transformedValue) === false) throw new Error(`Variable failed validation`);
+			if (validate(validator, transformedValue) === false && options?.skipValidation !== true) throw new Error(`Variable failed validation`);
 			return [key, transformedValue];
 		} catch (error) {
 			const errorMessage = error instanceof Error ? error.message : String(error);
@@ -71,6 +88,54 @@ const createEnv = (entries, inputEnv) => {
 		return acc;
 	}, {});
 };
+/**
+*
+* @description You may want to verify the existence and type of the environment variables separately from the creation of the env object. If so, use this function in convex.config.ts, and use the skipValidation option when calling createEnv.
+*
+* @param args - You can either pass in the schema object directly, or an object with the schema and values. See examples below.
+* @returns void
+*
+* @public
+*
+* @example
+* const schema = {
+*   FOO: v.string(),
+*   BAR: v.number(),
+*   BAZ: v.boolean(),
+* };
+* verifyEnv(schema);
+*
+* @example
+* const schema = {
+*   FOO: v.string(),
+*   BAR: v.number(),
+*   BAZ: v.boolean(),
+* };
+* verifyEnv({ schema, values: { FOO: process.env.FOO, BAR: "42", BAZ: "true" } });
+*/
+const verifyEnv = (args) => {
+	let schema;
+	let inputValues;
+	const isSchemaObject = (arg) => {
+		return "schema" in arg;
+	};
+	if (isSchemaObject(args)) {
+		schema = args.schema;
+		inputValues = args.values;
+	} else schema = args;
+	const values = inputValues ?? process.env;
+	Object.keys(schema).map((key) => {
+		try {
+			const validator = schema[key];
+			const envValue = values[key];
+			if (validator.isOptional === "required" && envValue === void 0) throw new Error("Variable is required but not found in env");
+			if (validate(validator, transformed(envValue, validator)) === false) throw new Error(`Variable failed validation`);
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			throw new Error(`Error verifying environment variable ${key}: ${errorMessage}`);
+		}
+	});
+};
 
 //#endregion
-export { createEnv };
+export { createEnv, verifyEnv };

package/package.json

@@ -1,12 +1,22 @@
 {
   "name": "convex-env",
   "type": "module",
-  "version": "1.0.2",
-  "description": "Typesafe access to environment variables in Convex",
+  "version": "2.1.0",
+  "license": "MIT",
+  "description": "Type-safe access to environment variables in Convex",
   "exports": {
     ".": "./dist/index.mjs",
     "./package.json": "./package.json"
   },
+  "keywords": [
+    "convex",
+    "env",
+    "environment variables"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bentsignal/convex-env.git"
+  },
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",