@kurdel/common 0.1.0-beta.2 → 0.1.0-beta.4

package/README.md

@@ -1,5 +1,28 @@
 # @kurdel/common
 
+## Environment configuration
+
+Define typed environment variables and validate all of them before application
+startup:
+
+```ts
+import { env, loadEnv } from '@kurdel/common';
+
+const environment = loadEnv({
+  NODE_ENV: env.enum(['development', 'test', 'production'], {
+    default: 'development',
+  }),
+  PORT: env.number({ default: 3000, integer: true, min: 1, max: 65_535 }),
+  DATABASE_URL: env.string({ minLength: 1 }),
+  ENABLE_AUDIT: env.boolean({ default: true }),
+  SENTRY_DSN: env.optional(env.string()),
+});
+```
+
+The returned object is inferred from the schema. Invalid configuration throws
+one `EnvironmentValidationError` containing every affected variable and safe
+reason, without including rejected values.
+
 Shared TypeScript types, interfaces, and utilities used by Kurdel packages.
 Application code normally receives this package transitively through the
 framework packages that depend on it.

package/lib/auth-user.d.ts

@@ -9,6 +9,7 @@
  * Properties:
  * - `id` — public stable identity of the user (string or number).
  * - `roles` — zero or more logical roles (e.g., `"admin"`, `"user"`, `"system"`).
+ * - `permissions` — optional capabilities resolved for the current identity.
  * - Additional fields may be attached by strategies (JWT payload, profile data, etc.).
  *
  * @remarks
@@ -18,6 +19,7 @@
 export interface AuthUser {
     id: string | number;
     roles: string[];
+    permissions?: string[];
     [key: string]: unknown;
 }
 /** Metadata about the credential used for the current authentication. */

package/lib/environment.d.ts

@@ -0,0 +1,39 @@
+export type EnvironmentSource = Readonly<Record<string, string | undefined>>;
+export type EnvironmentIssue = {
+    key: string;
+    message: string;
+};
+export declare class EnvironmentValidationError extends Error {
+    readonly issues: readonly EnvironmentIssue[];
+    constructor(issues: readonly EnvironmentIssue[]);
+}
+export interface EnvironmentVariable<T> {
+    parse(value: string | undefined): T;
+}
+type BaseOptions<T> = {
+    default?: T;
+};
+type StringOptions = BaseOptions<string> & {
+    trim?: boolean;
+    minLength?: number;
+    maxLength?: number;
+};
+type NumberOptions = BaseOptions<number> & {
+    integer?: boolean;
+    min?: number;
+    max?: number;
+};
+export declare const env: {
+    optional<T>(definition: EnvironmentVariable<T>): EnvironmentVariable<T | undefined>;
+    string(options?: StringOptions): EnvironmentVariable<string>;
+    number(options?: NumberOptions): EnvironmentVariable<number>;
+    boolean(options?: BaseOptions<boolean>): EnvironmentVariable<boolean>;
+    enum<const T extends readonly [string, ...string[]]>(values: T, options?: BaseOptions<T[number]>): EnvironmentVariable<T[number]>;
+};
+type EnvironmentSchema = Record<string, EnvironmentVariable<unknown>>;
+export type InferEnvironment<T extends EnvironmentSchema> = {
+    [K in keyof T]: T[K] extends EnvironmentVariable<infer V> ? V : never;
+};
+/** Parses all configured variables and reports every validation issue at once. */
+export declare function loadEnv<const T extends EnvironmentSchema>(schema: T, source?: EnvironmentSource): InferEnvironment<T>;
+export {};

package/lib/environment.js

@@ -0,0 +1,101 @@
+export class EnvironmentValidationError extends Error {
+    constructor(issues) {
+        super([
+            'Invalid environment configuration:',
+            ...issues.map(issue => `- ${issue.key}: ${issue.message}`),
+        ].join('\n'));
+        this.issues = issues;
+        this.name = 'EnvironmentValidationError';
+    }
+}
+function requiredValue(value, options) {
+    if (value !== undefined && value.trim() !== '')
+        return value;
+    if (Object.prototype.hasOwnProperty.call(options, 'default'))
+        return options.default;
+    throw new Error('is required');
+}
+function variable(parse) {
+    return { parse };
+}
+export const env = {
+    optional(definition) {
+        return variable(value => value === undefined || value.trim() === ''
+            ? undefined
+            : definition.parse(value));
+    },
+    string(options = {}) {
+        return variable(value => {
+            const resolved = requiredValue(value, options);
+            if (typeof resolved !== 'string')
+                return resolved;
+            const parsed = options.trim === false ? resolved : resolved.trim();
+            if (options.minLength !== undefined && parsed.length < options.minLength) {
+                throw new Error(`must contain at least ${options.minLength} characters`);
+            }
+            if (options.maxLength !== undefined && parsed.length > options.maxLength) {
+                throw new Error(`must contain at most ${options.maxLength} characters`);
+            }
+            return parsed;
+        });
+    },
+    number(options = {}) {
+        return variable(value => {
+            const resolved = requiredValue(value, options);
+            const parsed = typeof resolved === 'number' ? resolved : Number(resolved);
+            if (!Number.isFinite(parsed))
+                throw new Error('must be a finite number');
+            if (options.integer && !Number.isInteger(parsed))
+                throw new Error('must be an integer');
+            if (options.min !== undefined && parsed < options.min) {
+                throw new Error(`must be greater than or equal to ${options.min}`);
+            }
+            if (options.max !== undefined && parsed > options.max) {
+                throw new Error(`must be less than or equal to ${options.max}`);
+            }
+            return parsed;
+        });
+    },
+    boolean(options = {}) {
+        return variable(value => {
+            const resolved = requiredValue(value, options);
+            if (typeof resolved === 'boolean')
+                return resolved;
+            const normalized = resolved.trim().toLowerCase();
+            if (['true', '1', 'yes', 'on'].includes(normalized))
+                return true;
+            if (['false', '0', 'no', 'off'].includes(normalized))
+                return false;
+            throw new Error('must be a boolean');
+        });
+    },
+    enum(values, options = {}) {
+        return variable(value => {
+            const resolved = requiredValue(value, options);
+            const normalized = typeof resolved === 'string' ? resolved.trim() : resolved;
+            if (values.includes(normalized))
+                return normalized;
+            throw new Error(`must be one of: ${values.join(', ')}`);
+        });
+    },
+};
+/** Parses all configured variables and reports every validation issue at once. */
+export function loadEnv(schema, source = process.env) {
+    const output = {};
+    const issues = [];
+    for (const [key, definition] of Object.entries(schema)) {
+        try {
+            output[key] = definition.parse(source[key]);
+        }
+        catch (error) {
+            issues.push({
+                key,
+                message: error instanceof Error ? error.message : 'is invalid',
+            });
+        }
+    }
+    if (issues.length > 0)
+        throw new EnvironmentValidationError(issues);
+    return output;
+}
+//# sourceMappingURL=environment.js.map

package/lib/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../src/environment.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -4,3 +4,4 @@ export * from './auth-user.js';
 export * from './http-response-extended.js';
 export * from './json-loader.js';
 export * from './url.js';
+export * from './environment.js';

package/lib/index.js

@@ -4,4 +4,5 @@ export * from './auth-user.js';
 export * from './http-response-extended.js';
 export * from './json-loader.js';
 export * from './url.js';
+export * from './environment.js';
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kurdel/common",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.4",
   "description": "Shared types and utilities for Kurdel packages",
   "type": "module",
   "exports": {
@@ -13,7 +13,7 @@
   ],
   "scripts": {
     "prepack": "npm run build",
-    "test": "echo \"No tests yet\"",
+    "test": "vitest run",
     "clean": "rimraf lib ../../.cache/tsconfig.common.build.tsbuildinfo",
     "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
     "build:force": "npm run clean && tsc -p tsconfig.build.json --force && tsc-alias -p tsconfig.build.json"