env-dictionary 1.0.0 → 1.0.1

package/README.md

@@ -1,4 +1,4 @@
-# Dictionary
+# env-dictionary
 
 A TypeScript library for type-safe environment variable handling with runtime validation.
 
@@ -21,37 +21,13 @@ bun install
 
 ## Quick Start
 
-### Using Dictionary (Schema-based)
+### Using Dictionary (Create a typed env)
 
 ```typescript
-import { Dictionary } from './lib/dictionary';
-import { t } from './lib/t';
+import { Dictionary } from 'env-dictionary';
+import { t } from 'env-dictionary';
 
-const config = new Dictionary({
-  env: {
-    API_KEY: 'secret',
-    PORT: 3000,
-    DEBUG: true,
-  },
-  schema: {
-    API_KEY: t.string(),
-    PORT: t.number(),
-    DEBUG: t.boolean(),
-  },
-});
-
-console.log(config.values.API_KEY); // 'secret'
-console.log(config.values.PORT); // 3000
-console.log(config.values.DEBUG); // true
-```
-
-### Using DictionaryEnv (Descriptor-based)
-
-```typescript
-import { DictionaryEnv } from './lib/dictionary';
-import { t } from './lib/t';
-
-const env = new DictionaryEnv([
+const env = new Dictionary([
   { API_KEY: 'secret', type: t.string() },
   { PORT: 3000, type: t.number() },
   { DEBUG: true, type: t.boolean() },
@@ -62,6 +38,35 @@ console.log(env.env.PORT); // 3000
 console.log(env.env.DEBUG); // true
 ```
 
+### Using DictionaryEnv (Type pre-existing envs)
+
+```typescript
+import { DictionaryEnv } from 'env-dictionary';
+
+const typedEnv = new DictionaryEnv({ env: process.env })
+
+console.log(typedEnv.env.PORT) // 8080
+console.log(typedEnv.type.PORT) // Number
+```
+
+You can also provide a descriptor-based schema:
+
+```typescript
+import { DictionaryEnv } from 'env-dictionary';
+import { t } from 'env-dictionary';
+
+const typedEnv = new DictionaryEnv(
+  { env: process.env },
+  { schema: [
+    { var: 'PORT', type: t.number() },
+    { var: 'API_KEY', type: t.string() },
+  ]}
+)
+
+console.log(typedEnv.env.PORT) // 8080
+console.log(typedEnv.type.PORT) // Number
+```
+
 ## API Reference
 
 ### t
@@ -81,106 +86,135 @@ The `t` object provides type validators for schema definitions.
 
 ### Dictionary
 
-A class that validates environment variables against a schema.
+A class that creates a typed environment object from an array of descriptors.
 
 #### Constructor
 
 ```typescript
-new Dictionary<T>(options: DictionaryOptions)
+new Dictionary<TSchema>(schema: TSchema)
 ```
 
 **Parameters:**
 
-- `options.env: Record<string, unknown>` - The environment variables to validate
-- `options.schema?: Record<string, SchemaType>` - Optional schema for validation
+- `schema: TSchema[]` - Array of descriptors defining environment variables
 
 **Properties:**
 
-- `values: T` - The validated and typed environment variables
+- `env: TEnv` - The typed environment object
 
 #### Example
 
 ```typescript
-const dict = new Dictionary({
-  env: {
-    API_KEY: 'secret',
-    PORT: 3000,
-    DEBUG: true,
-    CONFIG: { url: 'https://api.example.com' },
-    ITEMS: [1, 2, 3],
-  },
-  schema: {
-    API_KEY: t.string(),
-    PORT: t.number(),
-    DEBUG: t.boolean(),
-    CONFIG: t.object(),
-    ITEMS: t.array(),
-  },
-});
+const env = new Dictionary([
+  { API_KEY: 'secret', type: t.string() },
+  { PORT: 3000, type: t.number() },
+  { DEBUG: true, type: t.boolean() },
+  { CONFIG: { url: 'https://api.example.com' }, type: t.object() },
+  { ITEMS: [1, 2, 3], type: t.array() },
+]);
 ```
 
+#### Descriptor Format
+
+Each descriptor must have:
+- A variable name (key)
+- A value
+- A `type` property with the validator
+
 #### Behavior
 
-- If no schema is provided, all environment variables are included as-is
-- If a schema is provided, only keys defined in the schema are included
-- Throws an error if a variable fails validation
-- Values are automatically typed based on the schema
+- Throws an error if a descriptor is missing a variable name
+- Throws an error if a descriptor is missing a type
+- Throws an error if a value fails validation for its type
+- Types are automatically inferred from the descriptors
 
 ### DictionaryEnv
 
-A class that creates a typed environment object from an array of descriptors.
+A class that validates environment variables against a schema.
 
 #### Constructor
 
 ```typescript
-new DictionaryEnv<TSchema>(schema: TSchema)
+new DictionaryEnv<T>(options: DictionaryOptions, descriptorOptions?: { schema: Array<{ var: string; type: SchemaType }> })
 ```
 
 **Parameters:**
 
-- `schema: TSchema[]` - Array of descriptors defining environment variables
+- `options.env: Record<string, unknown>` - The environment variables to validate
+- `options.schema?: Record<string, SchemaType>` - Optional schema for validation (key-based)
+- `descriptorOptions?: { schema: Array<{ var: string; type: SchemaType }> }` - Optional descriptor-based schema
 
 **Properties:**
 
-- `env: TEnv` - The typed environment object
+- `env: T` - The validated and typed environment variables
+- `type: { [K in keyof T]: TypeConstructor }` - Type constructors for each variable
 
-#### Example
+#### Examples
+
+**Key-based schema:**
 
 ```typescript
-const env = new DictionaryEnv([
-  { API_KEY: 'secret', type: t.string() },
-  { PORT: 3000, type: t.number() },
-  { DEBUG: true, type: t.boolean() },
-  { CONFIG: { url: 'https://api.example.com' }, type: t.object() },
-  { ITEMS: [1, 2, 3], type: t.array() },
-]);
+const typedEnv = new DictionaryEnv({
+  env: {
+    API_KEY: 'secret',
+    PORT: 3000,
+    DEBUG: true,
+    CONFIG: { url: 'https://api.example.com' },
+    ITEMS: [1, 2, 3],
+  },
+  schema: {
+    API_KEY: t.string(),
+    PORT: t.number(),
+    DEBUG: t.boolean(),
+    CONFIG: t.object(),
+    ITEMS: t.array(),
+  },
+});
 ```
 
-#### Descriptor Format
+**Descriptor-based schema:**
 
-Each descriptor must have:
-- A variable name (key)
-- A value
-- A `type` property with the validator
+```typescript
+const typedEnv = new DictionaryEnv(
+  { env: process.env },
+  { schema: [
+    { var: 'PORT', type: t.number() },
+    { var: 'API_KEY', type: t.string() },
+  ]}
+);
+```
 
 #### Behavior
 
-- Throws an error if a descriptor is missing a variable name
-- Throws an error if a descriptor is missing a type
-- Throws an error if a value fails validation for its type
-- Types are automatically inferred from the descriptors
+- If no schema is provided, all environment variables are included as-is with inferred types
+- If a schema is provided (key-based or descriptor-based), only keys defined in the schema are included
+- Throws an error if a variable fails validation
+- Values are automatically typed based on the schema
 
 ## Usage Patterns
 
 ### Environment Variables
 
-Commonly used for validating `.env` files:
+Use `Dictionary` to create a new typed environment:
 
 ```typescript
-import { Dictionary } from './lib/dictionary';
-import { t } from './lib/t';
+import { Dictionary } from 'env-dictionary';
+import { t } from 'env-dictionary';
+
+const env = new Dictionary([
+  { DATABASE_URL: 'postgresql://localhost', type: t.string() },
+  { PORT: 5432, type: t.number() },
+  { NODE_ENV: 'development', type: t.string() },
+]);
+```
+
+Use `DictionaryEnv` to type a pre-existing environment (key-based schema):
 
-const env = new Dictionary({
+```typescript
+import { DictionaryEnv } from 'env-dictionary';
+import { t } from 'env-dictionary';
+
+const typedEnv = new DictionaryEnv({
   env: process.env,
   schema: {
     DATABASE_URL: t.string(),
@@ -190,6 +224,22 @@ const env = new Dictionary({
 });
 ```
 
+Use `DictionaryEnv` with descriptor-based schema:
+
+```typescript
+import { DictionaryEnv } from 'env-dictionary';
+import { t } from 'env-dictionary';
+
+const typedEnv = new DictionaryEnv(
+  { env: process.env },
+  { schema: [
+    { var: 'DATABASE_URL', type: t.string() },
+    { var: 'PORT', type: t.number() },
+    { var: 'NODE_ENV', type: t.string() },
+  ]}
+);
+```
+
 ### Configuration Object
 
 Can be used with any configuration object:
@@ -206,7 +256,7 @@ const config = {
   },
 };
 
-const typedConfig = new Dictionary({
+const typedConfig = new DictionaryEnv({
   env: config,
   schema: {
     server: t.object(),
@@ -220,7 +270,7 @@ const typedConfig = new Dictionary({
 For complex nested objects, use the `object` type:
 
 ```typescript
-const dbConfig = new Dictionary({
+const dbConfig = new DictionaryEnv({
   env: {
     database: {
       host: 'localhost',
@@ -239,11 +289,23 @@ const dbConfig = new Dictionary({
 Both `Dictionary` and `DictionaryEnv` throw errors when validation fails:
 
 ```typescript
-import { Dictionary } from './lib/dictionary';
-import { t } from './lib/t';
+import { Dictionary } from 'env-dictionary';
+import { t } from 'env-dictionary';
+
+try {
+  const env = new Dictionary([
+    { PORT: '3000', type: t.number() }, // Should be a number
+  ]);
+} catch (error) {
+  console.error(error.message);
+  // 'ENV value "PORT" is not valid for the provided type'
+}
+
+import { DictionaryEnv } from 'env-dictionary';
+import { t } from 'env-dictionary';
 
 try {
-  const dict = new Dictionary({
+  const typedEnv = new DictionaryEnv({
     env: {
       PORT: '3000', // Should be a number
     },
@@ -255,17 +317,6 @@ try {
   console.error(error.message);
   // 'Invalid environment variable "PORT".'
 }
-
-import { DictionaryEnv } from './lib/dictionary';
-
-try {
-  const env = new DictionaryEnv([
-    { PORT: '3000', type: t.number() }, // Should be a number
-  ]);
-} catch (error) {
-  console.error(error.message);
-  // 'ENV value "PORT" is not valid for the provided type'
-}
 ```
 
 ## Type Safety
@@ -273,7 +324,10 @@ try {
 Both classes provide full TypeScript type inference:
 
 ```typescript
-const env = new DictionaryEnv([
+import { Dictionary } from 'env-dictionary';
+import { t } from 'env-dictionary';
+
+const env = new Dictionary([
   { API_KEY: 'secret', type: t.string() },
   { PORT: 3000, type: t.number() },
   { DEBUG: true, type: t.boolean() },

package/index.ts

@@ -1 +1,2 @@
+export { Dictionary, DictionaryEnv } from "./lib/dictionary";
 export { t } from "./lib/t";

package/lib/dictionary.ts

@@ -1,31 +1,11 @@
 /** biome-ignore-all lint/suspicious/noExplicitAny: . */
-import type { DictionaryEnvDescriptor, DictionaryOptions, SchemaType } from "./types";
+import type {
+	DictionaryEnvDescriptor,
+	DictionaryOptions,
+	SchemaType,
+} from "./types";
 
-export class Dictionary<T extends Record<string, any> = Record<string, any>> {
-	public readonly values: T;
-	constructor(options: DictionaryOptions) {
-		const { env, schema } = options;
-
-		let typedEnv: any = {};
-		if (schema) {
-			for (const key in schema) {
-				const s = schema[key];
-				const value = env[key];
-				if (s?.validate(value)) {
-					typedEnv[key] = value;
-				} else if (s) {
-					throw new Error(`Invalid environment variable "${key}".`);
-				}
-			}
-		} else {
-			typedEnv = env;
-		}
-
-		this.values = typedEnv;
-	}
-}
-
-export class DictionaryEnv<
+export class Dictionary<
 	TSchema extends DictionaryEnvDescriptor<string, any>[],
 > {
 	public readonly env: {
@@ -57,3 +37,89 @@ export class DictionaryEnv<
 		this.env = result;
 	}
 }
+
+export class DictionaryEnv<
+	T extends Record<string, any> = Record<string, any>,
+> {
+	public readonly env: T;
+	public readonly type: {
+		[K in keyof T]: T[K] extends string
+			? typeof String
+			: T[K] extends number
+				? typeof Number
+				: T[K] extends boolean
+					? typeof Boolean
+					: T[K] extends object
+						? typeof Object
+						: typeof Array;
+	};
+	constructor(
+		options: DictionaryOptions,
+		descriptorOptions?: { schema: Array<{ var: string; type: SchemaType }> },
+	) {
+		const { env, schema } = options;
+
+		const typeMap: any = {
+			string: String,
+			number: Number,
+			boolean: Boolean,
+			object: Object,
+			array: Array,
+			any: Object,
+		};
+
+		let typedEnv: any = {};
+		let resultTypeMap: any = {};
+
+		if (descriptorOptions?.schema) {
+			const { schema: descriptors } = descriptorOptions;
+			for (const desc of descriptors) {
+				const key = desc.var;
+				const s = desc.type;
+				const value = env[key];
+				if (s?.validate(value)) {
+					// Convert string numbers to actual numbers
+					if (s.type === "number" && typeof value === "string") {
+						typedEnv[key] = Number(value);
+					} else {
+						typedEnv[key] = value;
+					}
+					resultTypeMap[key] = typeMap[s.type];
+				} else if (s) {
+					throw new Error(`Invalid environment variable "${key}".`);
+				}
+			}
+		} else if (schema) {
+			for (const key in schema) {
+				const s = schema[key];
+				const value = env[key];
+				if (s?.validate(value)) {
+					// Convert string numbers to actual numbers
+					if (s.type === "number" && typeof value === "string") {
+						typedEnv[key] = Number(value);
+					} else {
+						typedEnv[key] = value;
+					}
+					resultTypeMap[key] = typeMap[s.type];
+				} else if (s) {
+					throw new Error(`Invalid environment variable "${key}".`);
+				}
+			}
+		} else {
+			typedEnv = env;
+			for (const key in env) {
+				const value = env[key];
+				if (typeof value === "string") resultTypeMap[key] = String;
+				else if (typeof value === "number") resultTypeMap[key] = Number;
+				else if (typeof value === "boolean") resultTypeMap[key] = Boolean;
+				else if (Array.isArray(value)) resultTypeMap[key] = Array;
+				else if (typeof value === "object" && value !== null)
+					resultTypeMap[key] = Object;
+				else resultTypeMap[key] = typeof value;
+			}
+		}
+
+		this.env = typedEnv;
+		this.type = resultTypeMap;
+	}
+}

package/lib/t.ts

@@ -13,7 +13,14 @@ const stringSchema: Schema<string, "string"> = {
 
 const numberSchema: Schema<number, "number"> = {
 	type: "number",
-	validate: (input): input is number => typeof input === "number",
+	validate: (input): input is number => {
+		if (typeof input === "number") return true;
+		if (typeof input === "string") {
+			const parsed = Number(input);
+			return !isNaN(parsed) && isFinite(parsed) && input.trim() !== "";
+		}
+		return false;
+	},
 };
 
 const booleanSchema: Schema<boolean, "boolean"> = {

package/lib/types.ts

@@ -18,4 +18,4 @@ type DictionaryEnvDescriptor<T extends string, V> = { [K in T]: V } & {
 	type: SchemaType;
 };
 
-export type { SchemaType, DictionaryOptions, DictionaryEnvDescriptor }
+export type { SchemaType, DictionaryOptions, DictionaryEnvDescriptor };

package/package.json

@@ -1,8 +1,12 @@
 {
 	"name": "env-dictionary",
-	"version": "1.0.0",
+	"version": "1.0.1",
 	"module": "dist/index.js",
 	"type": "module",
+	"scripts": {
+		"build": "bun build index.ts --outdir dist --target node",
+		"typecheck": "tsc --noEmit"
+	},
 	"devDependencies": {
 		"@types/bun": "latest"
 	},