convex-env 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shawn Rodgers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+<p align="center">
+  <img src="https://b9sa6juqtj.ufs.sh/f/WmevHvqCEmRaetBLb0NWmSZIsPhkweq8TtVxHraXLjAdgyEC" alt="Convex Env Logo" style="max-width: 500px; width: 100%;">
+</p>
+
+<h2 align="center">Convex Env</h2>
+<p align="center">Typesafe access to environment variables in Convex</p>
+
+### Overview
+
+If you've ever used [t3-env](https://github.com/t3-oss/t3-env), its basically that, but native to [Convex](https://www.convex.dev).
+
+Validators currently supported:
+
+- v.string()
+- v.number()
+- v.boolean()
+
+you can use `v.optional()` on _any supported validator_, see [example](#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.
+
+### Installation
+
+```
+ni convex-env
+```
+
+```
+pnpm i convex-env
+```
+
+```
+bun i convex-env
+```
+
+```
+npm i convex-env
+```
+
+```
+yarn add convex-env
+```
+
+### Usage
+
+```typescript
+// convex.env.ts
+
+import { createEnv } from "convex-env";
+import { v } from "convex/values";
+
+export const env = createEnv({
+  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()),
+});
+```
+
+Then access them anywhere in Convex.
+
+```typescript
+// auth.ts
+
+import { env } from "./convex.env";
+
+export const createAuth = (ctx: GenericCtx<DataModel>) => {
+  return betterAuth({
+    baseURL: env.CONVEX_SITE_URL,
+    socialProviders: {
+      google: {
+        clientId: env.GOOGLE_CLIENT_ID,
+        clientSecret: env.GOOGLE_CLIENT_SECRET,
+      },
+    },
+  });
+};
+```
+
+You can also pass values manually
+
+```typescript
+// convex.env.ts
+
+import { createEnv } from "convex-env";
+import { v } from "convex/values";
+
+export const env = createEnv(
+  {
+    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()),
+  },
+  {
+    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,
+  }
+);
+```

package/dist/index.d.mts

@@ -0,0 +1,41 @@
+import { Infer, VBoolean, VFloat64, VOptional, VString } from "convex/values";
+
+//#region src/types.d.ts
+type AllowedPrimitiveValidators = VString | VFloat64 | VBoolean;
+type AllowedOptionalValidators = VOptional<AllowedPrimitiveValidators>;
+type AllowedValidators = AllowedPrimitiveValidators | AllowedOptionalValidators;
+type InferredOuput<V extends AllowedValidators> = Infer<V>;
+//#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
+ *
+ * @public
+ *
+ * @example
+ * const env = createEnv({
+ *   FOO: v.string(),
+ *   BAR: v.number(),
+ *   BAZ: v.boolean(),
+ * });
+ *
+ * @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,
+ * });
+ *
+ */
+declare const createEnv: <T extends Record<string, AllowedValidators>>(entries: T, inputEnv?: Partial<Record<keyof T, string | undefined>>) => { [K in keyof T]: InferredOuput<T[K]> };
+//#endregion
+export { createEnv };

package/dist/index.mjs

@@ -0,0 +1,76 @@
+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);
+	throw new Error("Validator is not supported");
+};
+const validateAndTransformNumber = (value) => {
+	if (Number.isNaN(Number(value))) throw new Error("Value is not a number");
+	if (Number.isFinite(Number(value)) === false) throw new Error("Value is not a finite number");
+	return Number(value);
+};
+const validateAndTransformBoolean = (value) => {
+	if (value.trim().toLowerCase() === "true") return true;
+	if (value.trim().toLowerCase() === "false") return false;
+	throw new Error("Value is not a valid boolean");
+};
+
+//#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
+*
+* @public
+*
+* @example
+* const env = createEnv({
+*   FOO: v.string(),
+*   BAR: v.number(),
+*   BAZ: v.boolean(),
+* });
+*
+* @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,
+* });
+*
+*/
+const createEnv = (entries, inputEnv) => {
+	const env = inputEnv ?? process.env;
+	return Object.keys(entries).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 transformedValue = transformed(envValue, validator);
+			if (validate(validator, transformedValue) === false) throw new Error(`Variable failed validation`);
+			return [key, transformedValue];
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			throw new Error(`Error creating environment variable ${key}: ${errorMessage}`);
+		}
+	}).reduce((acc, [key, value]) => {
+		acc[key] = value;
+		return acc;
+	}, {});
+};
+
+//#endregion
+export { createEnv };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "convex-env",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "Typesafe access to environment variables in Convex",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint": "oxlint --type-aware --type-check",
+    "lint:fix": "oxlint --type-aware --type-check --fix && oxfmt",
+    "fmt": "oxfmt",
+    "test": "vitest",
+    "release": "changeset publish"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.8",
+    "@types/node": "^25.0.3",
+    "oxfmt": "^0.20.0",
+    "oxlint": "^1.35.0",
+    "oxlint-tsgolint": "^0.10.0",
+    "tsdown": "^0.18.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "convex-helpers": "^0.1.108"
+  },
+  "peerDependencies": {
+    "convex": ">=1.20.0"
+  }
+}