env-dictionary 1.0.0

package/README.md

@@ -0,0 +1,315 @@
+# Dictionary
+
+A TypeScript library for type-safe environment variable handling with runtime validation.
+
+## Features
+
+- **Type Safety**: Full TypeScript support with inferred types
+- **Runtime Validation**: Validate environment variables against defined schemas
+- **Multiple Type Support**: Built-in validators for string, number, boolean, object, array, and any types
+- **Flexible API**: Choose between schema-based or descriptor-based approaches
+- **Zero Dependencies**: Lightweight with no external runtime dependencies
+- **Bun Optimized**: Built with Bun in mind, works with any TypeScript project
+
+## Installation
+
+Install the package:
+
+```bash
+bun install
+```
+
+## Quick Start
+
+### Using Dictionary (Schema-based)
+
+```typescript
+import { Dictionary } from './lib/dictionary';
+import { t } from './lib/t';
+
+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([
+  { API_KEY: 'secret', type: t.string() },
+  { PORT: 3000, type: t.number() },
+  { DEBUG: true, type: t.boolean() },
+]);
+
+console.log(env.env.API_KEY); // 'secret'
+console.log(env.env.PORT); // 3000
+console.log(env.env.DEBUG); // true
+```
+
+## API Reference
+
+### t
+
+The `t` object provides type validators for schema definitions.
+
+#### Available Types
+
+| Type | Validator | Example |
+|------|-----------|---------|
+| `string` | `t.string()` | `'hello'` |
+| `number` | `t.number()` | `42` |
+| `boolean` | `t.boolean()` | `true` |
+| `object` | `t.object()` | `{ key: 'value' }` |
+| `array` | `t.array()` | `[1, 2, 3]` |
+| `any` | `t.any()` | Any value |
+
+### Dictionary
+
+A class that validates environment variables against a schema.
+
+#### Constructor
+
+```typescript
+new Dictionary<T>(options: DictionaryOptions)
+```
+
+**Parameters:**
+
+- `options.env: Record<string, unknown>` - The environment variables to validate
+- `options.schema?: Record<string, SchemaType>` - Optional schema for validation
+
+**Properties:**
+
+- `values: T` - The validated and typed environment variables
+
+#### 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(),
+  },
+});
+```
+
+#### 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
+
+### DictionaryEnv
+
+A class that creates a typed environment object from an array of descriptors.
+
+#### Constructor
+
+```typescript
+new DictionaryEnv<TSchema>(schema: TSchema)
+```
+
+**Parameters:**
+
+- `schema: TSchema[]` - Array of descriptors defining environment variables
+
+**Properties:**
+
+- `env: TEnv` - The typed environment object
+
+#### Example
+
+```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() },
+]);
+```
+
+#### Descriptor Format
+
+Each descriptor must have:
+- A variable name (key)
+- A value
+- A `type` property with the validator
+
+#### 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
+
+## Usage Patterns
+
+### Environment Variables
+
+Commonly used for validating `.env` files:
+
+```typescript
+import { Dictionary } from './lib/dictionary';
+import { t } from './lib/t';
+
+const env = new Dictionary({
+  env: process.env,
+  schema: {
+    DATABASE_URL: t.string(),
+    PORT: t.number(),
+    NODE_ENV: t.string(),
+  },
+});
+```
+
+### Configuration Object
+
+Can be used with any configuration object:
+
+```typescript
+const config = {
+  server: {
+    host: 'localhost',
+    port: 8080,
+  },
+  features: {
+    auth: true,
+    logging: false,
+  },
+};
+
+const typedConfig = new Dictionary({
+  env: config,
+  schema: {
+    server: t.object(),
+    features: t.object(),
+  },
+});
+```
+
+### Nested Configuration
+
+For complex nested objects, use the `object` type:
+
+```typescript
+const dbConfig = new Dictionary({
+  env: {
+    database: {
+      host: 'localhost',
+      port: 5432,
+      ssl: true,
+    },
+  },
+  schema: {
+    database: t.object(),
+  },
+});
+```
+
+## Error Handling
+
+Both `Dictionary` and `DictionaryEnv` throw errors when validation fails:
+
+```typescript
+import { Dictionary } from './lib/dictionary';
+import { t } from './lib/t';
+
+try {
+  const dict = new Dictionary({
+    env: {
+      PORT: '3000', // Should be a number
+    },
+    schema: {
+      PORT: t.number(),
+    },
+  });
+} catch (error) {
+  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
+
+Both classes provide full TypeScript type inference:
+
+```typescript
+const env = new DictionaryEnv([
+  { API_KEY: 'secret', type: t.string() },
+  { PORT: 3000, type: t.number() },
+  { DEBUG: true, type: t.boolean() },
+]);
+
+// TypeScript knows these types:
+env.env.API_KEY; // string
+env.env.PORT; // number
+env.env.DEBUG; // boolean
+env.env.UNKNOWN; // TypeScript error
+```
+
+## Development
+
+### Install Dependencies
+
+```bash
+bun install
+```
+
+### Build
+
+```bash
+bun run build
+```
+
+### Run Tests
+
+```bash
+bun test
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please ensure all tests pass before submitting a pull request.

package/bun.lock

@@ -0,0 +1,25 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "dictionary",
+      "devDependencies": {
+        "@types/bun": "latest",
+      },
+      "peerDependencies": {
+        "typescript": "^5",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.5", "", { "dependencies": { "bun-types": "1.3.5" } }, "sha512-RnygCqNrd3srIPEWBd5LFeUYG7plCoH2Yw9WaZGyNmdTEei+gWaHqydbaIRkIkcbXwhBT94q78QljxN0Sk838w=="],
+
+    "@types/node": ["@types/node@25.0.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA=="],
+
+    "bun-types": ["bun-types@1.3.5", "", { "dependencies": { "@types/node": "*" } }, "sha512-inmAYe2PFLs0SUbFOWSVD24sg1jFlMPxOjOSSCYqUgn4Hsc3rDc7dFvfVYjFPNHtov6kgUeulV4SxbuIV/stPw=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

package/index.ts

@@ -0,0 +1 @@
+export { t } from "./lib/t";

package/lib/dictionary.ts

@@ -0,0 +1,59 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: . */
+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<
+	TSchema extends DictionaryEnvDescriptor<string, any>[],
+> {
+	public readonly env: {
+		[K in TSchema[number] as K extends { type: SchemaType }
+			? keyof K & string
+			: never]: K extends { type: infer S }
+			? S extends { validate: (input: unknown) => input is infer U }
+				? U
+				: never
+			: never;
+	};
+
+	constructor(schema: TSchema) {
+		const result: any = {};
+		for (const desc of schema) {
+			const key = Object.keys(desc).find((k) => k !== "type");
+			if (!key) throw new Error("Descriptor must have a variable name");
+			const val = (desc as any)[key];
+			const type = (desc as any).type;
+			if (!type || typeof type.validate !== "function")
+				throw new Error("Descriptor must have a type");
+			if (!type.validate(val)) {
+				throw new Error(
+					`ENV value "${key}" is not valid for the provided type`,
+				);
+			}
+			result[key] = val;
+		}
+		this.env = result;
+	}
+}

package/lib/t.ts

@@ -0,0 +1,47 @@
+/** biome-ignore-all lint/suspicious/noExplicitAny: . */
+type SchemaType = "string" | "number" | "boolean" | "object" | "array" | "any";
+
+interface Schema<T, S extends SchemaType> {
+	type: S;
+	validate: (input: unknown) => input is T;
+}
+
+const stringSchema: Schema<string, "string"> = {
+	type: "string",
+	validate: (input): input is string => typeof input === "string",
+};
+
+const numberSchema: Schema<number, "number"> = {
+	type: "number",
+	validate: (input): input is number => typeof input === "number",
+};
+
+const booleanSchema: Schema<boolean, "boolean"> = {
+	type: "boolean",
+	validate: (input): input is boolean => typeof input === "boolean",
+};
+
+const objectSchema: Schema<object, "object"> = {
+	type: "object",
+	validate: (input): input is object =>
+		typeof input === "object" && input !== null && !Array.isArray(input),
+};
+
+const arraySchema: Schema<any[], "array"> = {
+	type: "array",
+	validate: (input): input is any[] => Array.isArray(input),
+};
+
+const anySchema: Schema<any, "any"> = {
+	type: "any",
+	validate: (_input): _input is any => true,
+};
+
+export const t = {
+	string: () => stringSchema,
+	number: () => numberSchema,
+	boolean: () => booleanSchema,
+	object: () => objectSchema,
+	array: () => arraySchema,
+	any: () => anySchema,
+};

package/lib/types.ts

@@ -0,0 +1,21 @@
+import type { t } from "./t";
+
+type SchemaType = ReturnType<
+	| typeof t.string
+	| typeof t.number
+	| typeof t.boolean
+	| typeof t.object
+	| typeof t.array
+	| typeof t.any
+>;
+
+type DictionaryOptions = {
+	env: Record<string, unknown>;
+	schema?: Record<string, SchemaType>;
+};
+
+type DictionaryEnvDescriptor<T extends string, V> = { [K in T]: V } & {
+	type: SchemaType;
+};
+
+export type { SchemaType, DictionaryOptions, DictionaryEnvDescriptor }

package/package.json

@@ -0,0 +1,12 @@
+{
+	"name": "env-dictionary",
+	"version": "1.0.0",
+	"module": "dist/index.js",
+	"type": "module",
+	"devDependencies": {
+		"@types/bun": "latest"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	}
+}

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+	"compilerOptions": {
+		"lib": ["ESNext"],
+		"target": "ESNext",
+		"module": "Preserve",
+		"moduleDetection": "force",
+		"jsx": "react-jsx",
+		"allowJs": true,
+
+		"moduleResolution": "bundler",
+		"allowImportingTsExtensions": true,
+		"verbatimModuleSyntax": true,
+		"noEmit": true,
+
+		"strict": true,
+		"skipLibCheck": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": true,
+		"noImplicitOverride": true,
+
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noPropertyAccessFromIndexSignature": false
+	}
+}