@chidchanun/bcp 0.2.0 → 0.2.2

package/packages/config/src/environment-schema.ts

@@ -0,0 +1,677 @@
+export type BcpEnvironmentValueType =
+    | "string"
+    | "number"
+    | "boolean"
+    | "url";
+
+export interface BcpEnvironmentVariableRule {
+    type: BcpEnvironmentValueType;
+    required?: boolean;
+    secret?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    min?: number;
+    max?: number;
+    default?: string | number | boolean;
+    description?: string;
+}
+
+export type BcpEnvironmentSchema =
+    Record<
+        string,
+        BcpEnvironmentVariableRule
+    >;
+
+export interface BcpEnvironmentValidationIssue {
+    key: string;
+    severity: "error" | "warning";
+    code:
+        | "missing"
+        | "invalid_type"
+        | "too_short"
+        | "too_long"
+        | "too_small"
+        | "too_large"
+        | "public_secret"
+        | "invalid_default";
+    message: string;
+}
+
+export interface BcpEnvironmentValidationResult {
+    ok: boolean;
+    checked: number;
+    present: number;
+    defaults: number;
+    issues: BcpEnvironmentValidationIssue[];
+    values: Record<
+        string,
+        string | number | boolean
+    >;
+}
+
+export function defineEnvironment<
+    const TSchema extends BcpEnvironmentSchema
+>(
+    schema: TSchema
+): TSchema {
+    assertEnvironmentSchema(
+        schema
+    );
+
+    return schema;
+}
+
+export function applyEnvironmentDefaults(
+    schema: BcpEnvironmentSchema,
+    target:
+        NodeJS.ProcessEnv |
+        Record<string, string | undefined> =
+            process.env
+): number {
+    assertEnvironmentSchema(
+        schema
+    );
+
+    let applied = 0;
+
+    for (
+        const [
+            key,
+            rule,
+        ]
+        of Object.entries(
+            schema
+        )
+    ) {
+        if (
+            rule.default === undefined ||
+            (
+                target[key] !== undefined &&
+                target[key] !== ""
+            )
+        ) {
+            continue;
+        }
+
+        target[key] =
+            serializeEnvironmentValue(
+                rule.default
+            );
+        applied++;
+    }
+
+    return applied;
+}
+
+export function validateEnvironment(
+    schema: BcpEnvironmentSchema,
+    source:
+        NodeJS.ProcessEnv |
+        Record<string, string | undefined> =
+            process.env
+): BcpEnvironmentValidationResult {
+    assertEnvironmentSchema(
+        schema
+    );
+
+    const issues:
+        BcpEnvironmentValidationIssue[] = [];
+    const values:
+        Record<
+            string,
+            string | number | boolean
+        > = {};
+
+    let present = 0;
+    let defaults = 0;
+
+    for (
+        const [
+            key,
+            rule,
+        ]
+        of Object.entries(
+            schema
+        )
+    ) {
+        if (
+            rule.secret &&
+            key.startsWith(
+                "BCP_PUBLIC_"
+            )
+        ) {
+            issues.push({
+                key,
+                severity: "error",
+                code: "public_secret",
+                message:
+                    `${key} is marked secret but uses the BCP_PUBLIC_ prefix. Public variables are embedded in client bundles.`,
+            });
+        }
+
+        const raw =
+            source[key];
+        const hasSourceValue =
+            raw !== undefined &&
+            raw !== "";
+
+        if (hasSourceValue) {
+            present++;
+        }
+
+        const input:
+            string | number | boolean | undefined =
+            hasSourceValue
+                ? raw
+                : rule.default;
+
+        if (
+            input === undefined
+        ) {
+            if (
+                rule.required
+            ) {
+                issues.push({
+                    key,
+                    severity: "error",
+                    code: "missing",
+                    message:
+                        `${key} is required but was not provided.`,
+                });
+            }
+
+            continue;
+        }
+
+        if (
+            !hasSourceValue
+        ) {
+            defaults++;
+        }
+
+        const parsed =
+            parseEnvironmentRuleValue(
+                key,
+                input,
+                rule,
+                issues
+            );
+
+        if (
+            parsed !== undefined
+        ) {
+            values[key] =
+                parsed;
+        }
+    }
+
+    return {
+        ok:
+            !issues.some(
+                (issue) =>
+                    issue.severity ===
+                    "error"
+            ),
+        checked:
+            Object.keys(
+                schema
+            ).length,
+        present,
+        defaults,
+        issues,
+        values,
+    };
+}
+
+export function assertEnvironmentSchema(
+    schema: unknown
+): asserts schema is BcpEnvironmentSchema {
+    if (
+        !isPlainObject(
+            schema
+        )
+    ) {
+        throw new Error(
+            "BCP Framework: environment config must be an object."
+        );
+    }
+
+    for (
+        const [
+            key,
+            value,
+        ]
+        of Object.entries(
+            schema
+        )
+    ) {
+        if (
+            !/^[A-Za-z_][A-Za-z0-9_]*$/.test(
+                key
+            )
+        ) {
+            throw new Error(
+                `BCP Framework: invalid environment schema key "${key}".`
+            );
+        }
+
+        assertEnvironmentRule(
+            key,
+            value
+        );
+    }
+}
+
+function assertEnvironmentRule(
+    key: string,
+    value: unknown
+): asserts value is BcpEnvironmentVariableRule {
+    if (
+        !isPlainObject(
+            value
+        )
+    ) {
+        throw new Error(
+            `BCP Framework: environment.${key} must be an object.`
+        );
+    }
+
+    const allowed =
+        new Set([
+            "type",
+            "required",
+            "secret",
+            "minLength",
+            "maxLength",
+            "min",
+            "max",
+            "default",
+            "description",
+        ]);
+
+    for (
+        const property
+        of Object.keys(
+            value
+        )
+    ) {
+        if (
+            !allowed.has(
+                property
+            )
+        ) {
+            throw new Error(
+                `BCP Framework: unknown config option "environment.${key}.${property}".`
+            );
+        }
+    }
+
+    if (
+        value.type !== "string" &&
+        value.type !== "number" &&
+        value.type !== "boolean" &&
+        value.type !== "url"
+    ) {
+        throw new Error(
+            `BCP Framework: environment.${key}.type must be string, number, boolean, or url.`
+        );
+    }
+
+    assertOptionalBoolean(
+        value.required,
+        `environment.${key}.required`
+    );
+    assertOptionalBoolean(
+        value.secret,
+        `environment.${key}.secret`
+    );
+    assertOptionalNonNegativeInteger(
+        value.minLength,
+        `environment.${key}.minLength`
+    );
+    assertOptionalNonNegativeInteger(
+        value.maxLength,
+        `environment.${key}.maxLength`
+    );
+    assertOptionalFiniteNumber(
+        value.min,
+        `environment.${key}.min`
+    );
+    assertOptionalFiniteNumber(
+        value.max,
+        `environment.${key}.max`
+    );
+
+    if (
+        value.description !== undefined &&
+        (
+            typeof value.description !== "string" ||
+            value.description.trim() === ""
+        )
+    ) {
+        throw new Error(
+            `BCP Framework: environment.${key}.description must be a non-empty string.`
+        );
+    }
+
+    if (
+        value.minLength !== undefined &&
+        value.maxLength !== undefined &&
+        value.minLength > value.maxLength
+    ) {
+        throw new Error(
+            `BCP Framework: environment.${key}.minLength cannot be greater than maxLength.`
+        );
+    }
+
+    if (
+        value.min !== undefined &&
+        value.max !== undefined &&
+        value.min > value.max
+    ) {
+        throw new Error(
+            `BCP Framework: environment.${key}.min cannot be greater than max.`
+        );
+    }
+
+    if (
+        value.default !== undefined
+    ) {
+        const issues:
+            BcpEnvironmentValidationIssue[] = [];
+
+        const parsed =
+            parseEnvironmentRuleValue(
+                key,
+                value.default,
+                value as BcpEnvironmentVariableRule,
+                issues
+            );
+
+        if (
+            parsed === undefined ||
+            issues.some(
+                (issue) =>
+                    issue.severity ===
+                    "error"
+            )
+        ) {
+            throw new Error(
+                `BCP Framework: environment.${key}.default does not satisfy its declared rule.`
+            );
+        }
+    }
+}
+
+function parseEnvironmentRuleValue(
+    key: string,
+    input: string | number | boolean,
+    rule: BcpEnvironmentVariableRule,
+    issues: BcpEnvironmentValidationIssue[]
+): string | number | boolean | undefined {
+    if (
+        rule.type === "string" ||
+        rule.type === "url"
+    ) {
+        if (
+            typeof input !==
+            "string"
+        ) {
+            issues.push({
+                key,
+                severity: "error",
+                code: "invalid_type",
+                message:
+                    `${key} must be a ${rule.type}.`,
+            });
+            return undefined;
+        }
+
+        if (
+            rule.minLength !== undefined &&
+            input.length <
+            rule.minLength
+        ) {
+            issues.push({
+                key,
+                severity: "error",
+                code: "too_short",
+                message:
+                    `${key} must contain at least ${rule.minLength} character(s).`,
+            });
+        }
+
+        if (
+            rule.maxLength !== undefined &&
+            input.length >
+            rule.maxLength
+        ) {
+            issues.push({
+                key,
+                severity: "error",
+                code: "too_long",
+                message:
+                    `${key} must contain at most ${rule.maxLength} character(s).`,
+            });
+        }
+
+        if (
+            rule.type === "url"
+        ) {
+            try {
+                const url =
+                    new URL(
+                        input
+                    );
+
+                if (
+                    url.protocol !== "http:" &&
+                    url.protocol !== "https:"
+                ) {
+                    throw new Error(
+                        "unsupported protocol"
+                    );
+                }
+            } catch {
+                issues.push({
+                    key,
+                    severity: "error",
+                    code: "invalid_type",
+                    message:
+                        `${key} must be an absolute http(s) URL.`,
+                });
+                return undefined;
+            }
+        }
+
+        return input;
+    }
+
+    if (
+        rule.type === "number"
+    ) {
+        const parsed =
+            typeof input === "number"
+                ? input
+                : typeof input === "string" &&
+                    input.trim() !== ""
+                    ? Number(
+                        input
+                    )
+                    : Number.NaN;
+
+        if (
+            !Number.isFinite(
+                parsed
+            )
+        ) {
+            issues.push({
+                key,
+                severity: "error",
+                code: "invalid_type",
+                message:
+                    `${key} must be a finite number.`,
+            });
+            return undefined;
+        }
+
+        if (
+            rule.min !== undefined &&
+            parsed < rule.min
+        ) {
+            issues.push({
+                key,
+                severity: "error",
+                code: "too_small",
+                message:
+                    `${key} must be greater than or equal to ${rule.min}.`,
+            });
+        }
+
+        if (
+            rule.max !== undefined &&
+            parsed > rule.max
+        ) {
+            issues.push({
+                key,
+                severity: "error",
+                code: "too_large",
+                message:
+                    `${key} must be less than or equal to ${rule.max}.`,
+            });
+        }
+
+        return parsed;
+    }
+
+    if (
+        typeof input === "boolean"
+    ) {
+        return input;
+    }
+
+    if (
+        typeof input === "string"
+    ) {
+        const normalized =
+            input
+                .trim()
+                .toLowerCase();
+
+        if (
+            [
+                "1",
+                "true",
+                "yes",
+                "on",
+            ].includes(
+                normalized
+            )
+        ) {
+            return true;
+        }
+
+        if (
+            [
+                "0",
+                "false",
+                "no",
+                "off",
+            ].includes(
+                normalized
+            )
+        ) {
+            return false;
+        }
+    }
+
+    issues.push({
+        key,
+        severity: "error",
+        code: "invalid_type",
+        message:
+            `${key} must be a boolean value (true/false, 1/0, yes/no, on/off).`,
+    });
+
+    return undefined;
+}
+
+function serializeEnvironmentValue(
+    value: string | number | boolean
+): string {
+    if (
+        typeof value === "boolean"
+    ) {
+        return value
+            ? "true"
+            : "false";
+    }
+
+    return String(
+        value
+    );
+}
+
+function assertOptionalBoolean(
+    value: unknown,
+    label: string
+): void {
+    if (
+        value !== undefined &&
+        typeof value !== "boolean"
+    ) {
+        throw new Error(
+            `BCP Framework: ${label} must be boolean.`
+        );
+    }
+}
+
+function assertOptionalNonNegativeInteger(
+    value: unknown,
+    label: string
+): void {
+    if (
+        value !== undefined &&
+        (
+            !Number.isInteger(
+                value
+            ) ||
+            Number(value) < 0
+        )
+    ) {
+        throw new Error(
+            `BCP Framework: ${label} must be a non-negative integer.`
+        );
+    }
+}
+
+function assertOptionalFiniteNumber(
+    value: unknown,
+    label: string
+): void {
+    if (
+        value !== undefined &&
+        (
+            typeof value !== "number" ||
+            !Number.isFinite(
+                value
+            )
+        )
+    ) {
+        throw new Error(
+            `BCP Framework: ${label} must be a finite number.`
+        );
+    }
+}
+
+function isPlainObject(
+    value: unknown
+): value is Record<string, any> {
+    return (
+        typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(
+            value
+        )
+    );
+}