@iskra-bun/config-kit 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @iskra-bun/config-kit
+
+## 0.1.0
+
+### Minor Changes
+
+- f9654df: Initial public release. Typed, Zod-validated environment/config loading: `loadConfig` returns a deep-frozen config, env coercers (`envBool`, `envNumber`, `envPort`, `envEnum`), and validation errors that never echo secret values.
+
+### Patch Changes
+
+- Updated dependencies [f9654df]
+- Updated dependencies
+- Updated dependencies [f9654df]
+    - @iskra-bun/core@0.1.1

package/README.md

@@ -0,0 +1,38 @@
+# @iskra-bun/config-kit
+
+Carga y validacion de configuracion de entorno con Zod para Iskra.
+
+## Instalacion
+
+```bash
+bun add @iskra-bun/config-kit @iskra-bun/core
+```
+
+## Uso rapido
+
+```typescript
+import { loadConfig, envBool, envPort, envEnum, z } from '@iskra-bun/config-kit';
+
+const config = loadConfig({
+    schema: z.object({
+        DATABASE_URL: z.string().url(),
+        PORT: envPort,
+        DEBUG: envBool,
+        NODE_ENV: envEnum(['development', 'production', 'test'] as const),
+    }),
+});
+
+// config es tipado, validado, y completamente inmutable (deep-frozen)
+console.log(config.PORT); // number
+console.log(config.DEBUG); // boolean
+```
+
+Bun carga `.env` automaticamente en `process.env`, por lo que `loadConfig` lo recoge sin configuracion adicional.
+
+## Documentacion
+
+Guia completa: [docs/config-kit.md](../../docs/config-kit.md)
+
+## Licencia
+
+AGPL-3.0-or-later

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+export { z } from 'zod';
+
+interface LoadConfigOptions<TSchema extends z.ZodTypeAny> {
+    /** The Zod schema to validate the source against. */
+    schema: TSchema;
+    /**
+     * The environment source to validate.
+     * Defaults to `process.env`.
+     */
+    source?: Record<string, string | undefined>;
+}
+/**
+ * Validates `source` (defaults to `process.env`) against the provided Zod schema
+ * and returns a deep-frozen, typed config object.
+ *
+ * On failure, throws a `ConfigError` listing each invalid or missing field by name
+ * and reason — never echoing secret values.
+ */
+declare function loadConfig<TSchema extends z.ZodTypeAny>(options: LoadConfigOptions<TSchema>): z.output<TSchema>;
+
+/**
+ * Coerce a string env var to boolean.
+ * Accepts "true"/"1"/"yes" as true, "false"/"0"/"no" as false.
+ * Rejects any other value.
+ */
+declare const envBool: z.ZodPipeline<z.ZodEffects<z.ZodString, boolean, string>, z.ZodBoolean>;
+/**
+ * Coerce a string env var to a finite number.
+ */
+declare const envNumber: z.ZodPipeline<z.ZodEffects<z.ZodString, number, string>, z.ZodNumber>;
+/**
+ * Coerce a string env var to a valid TCP port (1–65535).
+ */
+declare const envPort: z.ZodPipeline<z.ZodEffects<z.ZodString, number, string>, z.ZodNumber>;
+/**
+ * Coerce a string env var to one of the provided literal values.
+ * Usage: envEnum(['development', 'production', 'test'])
+ */
+declare function envEnum<T extends string>(values: readonly [T, ...T[]]): z.ZodPipeline<z.ZodEffects<z.ZodString, T, string>, z.ZodEnum<[T, ...T[]]>>;
+
+export { type LoadConfigOptions, envBool, envEnum, envNumber, envPort, loadConfig };

package/dist/index.js

@@ -0,0 +1,96 @@
+// src/loader.ts
+import { ConfigError } from "@iskra-bun/core";
+function loadConfig(options) {
+  const { schema, source = process.env } = options;
+  const result = schema.safeParse(source);
+  if (!result.success) {
+    const issues = result.error.issues.map((issue) => {
+      const path = issue.path.length > 0 ? issue.path.join(".") : "<root>";
+      return `  \u2022 ${path}: ${issue.message}`;
+    });
+    throw new ConfigError(
+      `Config validation failed:
+${issues.join("\n")}`,
+      {
+        context: {
+          // Only report field names and messages — never values.
+          fields: result.error.issues.map((i) => ({
+            path: i.path.join(".") || "<root>",
+            message: i.message
+          }))
+        }
+      }
+    );
+  }
+  return deepFreeze(result.data);
+}
+function deepFreeze(obj) {
+  if (obj === null || typeof obj !== "object") return obj;
+  for (const key of Object.keys(obj)) {
+    const value = obj[key];
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+      deepFreeze(value);
+    }
+  }
+  return Object.freeze(obj);
+}
+
+// src/coercers.ts
+import { z } from "zod";
+var envBool = z.string().transform((val, ctx) => {
+  const lower = val.toLowerCase().trim();
+  if (lower === "true" || lower === "1" || lower === "yes") return true;
+  if (lower === "false" || lower === "0" || lower === "no") return false;
+  ctx.addIssue({
+    code: z.ZodIssueCode.custom,
+    message: `Expected boolean-like string ("true"/"1"/"yes"/"false"/"0"/"no"), received "${val}"`
+  });
+  return z.NEVER;
+}).pipe(z.boolean());
+var envNumber = z.string().transform((val, ctx) => {
+  const trimmed = val.trim();
+  const n = Number(trimmed);
+  if (trimmed === "" || !Number.isFinite(n)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `Expected a finite number, received "${val}"`
+    });
+    return z.NEVER;
+  }
+  return n;
+}).pipe(z.number());
+var envPort = z.string().transform((val, ctx) => {
+  const n = Number(val);
+  if (!Number.isInteger(n) || n < 1 || n > 65535) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: `Expected a port number (1\u201365535), received "${val}"`
+    });
+    return z.NEVER;
+  }
+  return n;
+}).pipe(z.number().int().min(1).max(65535));
+function envEnum(values) {
+  return z.string().transform((val, ctx) => {
+    if (!values.includes(val)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Expected one of [${values.map((v) => `"${v}"`).join(", ")}], received "${val}"`
+      });
+      return z.NEVER;
+    }
+    return val;
+  }).pipe(z.enum(values));
+}
+
+// src/index.ts
+import { z as z2 } from "zod";
+export {
+  envBool,
+  envEnum,
+  envNumber,
+  envPort,
+  loadConfig,
+  z2 as z
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/loader.ts","../src/coercers.ts","../src/index.ts"],"sourcesContent":["import { z } from 'zod';\nimport { ConfigError } from '@iskra-bun/core';\n\nexport interface LoadConfigOptions<TSchema extends z.ZodTypeAny> {\n    /** The Zod schema to validate the source against. */\n    schema: TSchema;\n    /**\n     * The environment source to validate.\n     * Defaults to `process.env`.\n     */\n    source?: Record<string, string | undefined>;\n}\n\n/**\n * Validates `source` (defaults to `process.env`) against the provided Zod schema\n * and returns a deep-frozen, typed config object.\n *\n * On failure, throws a `ConfigError` listing each invalid or missing field by name\n * and reason — never echoing secret values.\n */\nexport function loadConfig<TSchema extends z.ZodTypeAny>(\n    options: LoadConfigOptions<TSchema>,\n): z.output<TSchema> {\n    const { schema, source = process.env } = options;\n\n    const result = schema.safeParse(source);\n\n    if (!result.success) {\n        const issues = result.error.issues.map(issue => {\n            const path = issue.path.length > 0 ? issue.path.join('.') : '<root>';\n            return `  • ${path}: ${issue.message}`;\n        });\n\n        throw new ConfigError(\n            `Config validation failed:\\n${issues.join('\\n')}`,\n            {\n                context: {\n                    // Only report field names and messages — never values.\n                    fields: result.error.issues.map(i => ({\n                        path: i.path.join('.') || '<root>',\n                        message: i.message,\n                    })),\n                },\n            },\n        );\n    }\n\n    return deepFreeze(result.data) as z.output<TSchema>;\n}\n\n/**\n * Recursively freezes an object so the returned config is truly immutable.\n */\nfunction deepFreeze<T>(obj: T): T {\n    if (obj === null || typeof obj !== 'object') return obj;\n\n    for (const key of Object.keys(obj as object)) {\n        const value = (obj as Record<string, unknown>)[key];\n        if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {\n            deepFreeze(value);\n        }\n    }\n\n    return Object.freeze(obj);\n}\n","import { z } from 'zod';\n\n/**\n * Coerce a string env var to boolean.\n * Accepts \"true\"/\"1\"/\"yes\" as true, \"false\"/\"0\"/\"no\" as false.\n * Rejects any other value.\n */\nexport const envBool = z\n    .string()\n    .transform((val, ctx) => {\n        const lower = val.toLowerCase().trim();\n        if (lower === 'true' || lower === '1' || lower === 'yes') return true;\n        if (lower === 'false' || lower === '0' || lower === 'no') return false;\n        ctx.addIssue({\n            code: z.ZodIssueCode.custom,\n            message: `Expected boolean-like string (\"true\"/\"1\"/\"yes\"/\"false\"/\"0\"/\"no\"), received \"${val}\"`,\n        });\n        return z.NEVER;\n    })\n    .pipe(z.boolean());\n\n/**\n * Coerce a string env var to a finite number.\n */\nexport const envNumber = z\n    .string()\n    .transform((val, ctx) => {\n        const trimmed = val.trim();\n        const n = Number(trimmed);\n        if (trimmed === '' || !Number.isFinite(n)) {\n            ctx.addIssue({\n                code: z.ZodIssueCode.custom,\n                message: `Expected a finite number, received \"${val}\"`,\n            });\n            return z.NEVER;\n        }\n        return n;\n    })\n    .pipe(z.number());\n\n/**\n * Coerce a string env var to a valid TCP port (1–65535).\n */\nexport const envPort = z\n    .string()\n    .transform((val, ctx) => {\n        const n = Number(val);\n        if (!Number.isInteger(n) || n < 1 || n > 65535) {\n            ctx.addIssue({\n                code: z.ZodIssueCode.custom,\n                message: `Expected a port number (1–65535), received \"${val}\"`,\n            });\n            return z.NEVER;\n        }\n        return n;\n    })\n    .pipe(z.number().int().min(1).max(65535));\n\n/**\n * Coerce a string env var to one of the provided literal values.\n * Usage: envEnum(['development', 'production', 'test'])\n */\nexport function envEnum<T extends string>(values: readonly [T, ...T[]]) {\n    return z\n        .string()\n        .transform((val, ctx) => {\n            if (!(values as readonly string[]).includes(val)) {\n                ctx.addIssue({\n                    code: z.ZodIssueCode.custom,\n                    message: `Expected one of [${values.map(v => `\"${v}\"`).join(', ')}], received \"${val}\"`,\n                });\n                return z.NEVER;\n            }\n            return val as T;\n        })\n        .pipe(z.enum(values));\n}\n","export { loadConfig } from './loader';\nexport type { LoadConfigOptions } from './loader';\nexport { envBool, envNumber, envPort, envEnum } from './coercers';\nexport { z } from 'zod';\n"],"mappings":"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","names":["z"]}

package/package.json

@@ -0,0 +1,57 @@
+{
+    "name": "@iskra-bun/config-kit",
+    "version": "0.1.0",
+    "description": "Carga y validacion de configuracion de entorno con Zod para Iskra.",
+    "keywords": [
+        "iskra",
+        "bun",
+        "typescript",
+        "config",
+        "env",
+        "zod",
+        "validation"
+    ],
+    "author": "Joan Lascano",
+    "license": "AGPL-3.0-or-later",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/fearful/iskra.git",
+        "directory": "packages/config-kit"
+    },
+    "homepage": "https://github.com/fearful/iskra/tree/main/packages/config-kit#readme",
+    "bugs": "https://github.com/fearful/iskra/issues",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "source": "./src/index.ts",
+            "bun": "./src/index.ts",
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "README.md",
+        "CHANGELOG.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "test": "bun test",
+        "build": "tsup --config ../../tsup.config.ts"
+    },
+    "dependencies": {
+        "@iskra-bun/core": "0.1.1",
+        "zod": "^3.24.1"
+    },
+    "devDependencies": {
+        "@types/bun": "^1.3.5",
+        "@types/node": "^22.10.2"
+    }
+}

package/src/coercers.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+
+/**
+ * Coerce a string env var to boolean.
+ * Accepts "true"/"1"/"yes" as true, "false"/"0"/"no" as false.
+ * Rejects any other value.
+ */
+export const envBool = z
+    .string()
+    .transform((val, ctx) => {
+        const lower = val.toLowerCase().trim();
+        if (lower === 'true' || lower === '1' || lower === 'yes') return true;
+        if (lower === 'false' || lower === '0' || lower === 'no') return false;
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `Expected boolean-like string ("true"/"1"/"yes"/"false"/"0"/"no"), received "${val}"`,
+        });
+        return z.NEVER;
+    })
+    .pipe(z.boolean());
+
+/**
+ * Coerce a string env var to a finite number.
+ */
+export const envNumber = z
+    .string()
+    .transform((val, ctx) => {
+        const trimmed = val.trim();
+        const n = Number(trimmed);
+        if (trimmed === '' || !Number.isFinite(n)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Expected a finite number, received "${val}"`,
+            });
+            return z.NEVER;
+        }
+        return n;
+    })
+    .pipe(z.number());
+
+/**
+ * Coerce a string env var to a valid TCP port (1–65535).
+ */
+export const envPort = z
+    .string()
+    .transform((val, ctx) => {
+        const n = Number(val);
+        if (!Number.isInteger(n) || n < 1 || n > 65535) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Expected a port number (1–65535), received "${val}"`,
+            });
+            return z.NEVER;
+        }
+        return n;
+    })
+    .pipe(z.number().int().min(1).max(65535));
+
+/**
+ * Coerce a string env var to one of the provided literal values.
+ * Usage: envEnum(['development', 'production', 'test'])
+ */
+export function envEnum<T extends string>(values: readonly [T, ...T[]]) {
+    return z
+        .string()
+        .transform((val, ctx) => {
+            if (!(values as readonly string[]).includes(val)) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `Expected one of [${values.map(v => `"${v}"`).join(', ')}], received "${val}"`,
+                });
+                return z.NEVER;
+            }
+            return val as T;
+        })
+        .pipe(z.enum(values));
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { loadConfig } from './loader';
+export type { LoadConfigOptions } from './loader';
+export { envBool, envNumber, envPort, envEnum } from './coercers';
+export { z } from 'zod';

package/src/loader.ts

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { ConfigError } from '@iskra-bun/core';
+
+export interface LoadConfigOptions<TSchema extends z.ZodTypeAny> {
+    /** The Zod schema to validate the source against. */
+    schema: TSchema;
+    /**
+     * The environment source to validate.
+     * Defaults to `process.env`.
+     */
+    source?: Record<string, string | undefined>;
+}
+
+/**
+ * Validates `source` (defaults to `process.env`) against the provided Zod schema
+ * and returns a deep-frozen, typed config object.
+ *
+ * On failure, throws a `ConfigError` listing each invalid or missing field by name
+ * and reason — never echoing secret values.
+ */
+export function loadConfig<TSchema extends z.ZodTypeAny>(
+    options: LoadConfigOptions<TSchema>,
+): z.output<TSchema> {
+    const { schema, source = process.env } = options;
+
+    const result = schema.safeParse(source);
+
+    if (!result.success) {
+        const issues = result.error.issues.map(issue => {
+            const path = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+            return `  • ${path}: ${issue.message}`;
+        });
+
+        throw new ConfigError(
+            `Config validation failed:\n${issues.join('\n')}`,
+            {
+                context: {
+                    // Only report field names and messages — never values.
+                    fields: result.error.issues.map(i => ({
+                        path: i.path.join('.') || '<root>',
+                        message: i.message,
+                    })),
+                },
+            },
+        );
+    }
+
+    return deepFreeze(result.data) as z.output<TSchema>;
+}
+
+/**
+ * Recursively freezes an object so the returned config is truly immutable.
+ */
+function deepFreeze<T>(obj: T): T {
+    if (obj === null || typeof obj !== 'object') return obj;
+
+    for (const key of Object.keys(obj as object)) {
+        const value = (obj as Record<string, unknown>)[key];
+        if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+            deepFreeze(value);
+        }
+    }
+
+    return Object.freeze(obj);
+}