add AppFacade#env(key: string) (#251)

Author: terrablue

packages/core/package.json

@@ -29,6 +29,7 @@
     "@rcompat/cli": "^0.18.1",
     "@rcompat/crypto": "^0.16.1",
     "@rcompat/dict": "^0.5.1",
+    "@rcompat/env": "^0.17.2",
     "@rcompat/error": "^0.3.1",
     "@rcompat/fn": "^0.5.1",
     "@rcompat/fs": "^0.28.1",
@@ -54,6 +55,11 @@
     }
   },
   "exports": {
+    "./AppFacade": {
+      "@primate/source": "./src/public/AppFacade.ts",
+      "browser": "./lib/private/app/Facade.browser.js",
+      "default": "./lib/public/AppFacade.js"
+    },
     "./*": {
       "@primate/source": "./src/public/*.ts",
       "default": "./lib/public/*.js"

packages/core/src/private/app/EnvSchema.ts

@@ -0,0 +1,6 @@
+import type { Dict } from "@rcompat/type";
+import type { Parsed } from "pema";
+
+type EnvSchema = Dict<Parsed<unknown>>;
+
+export type { EnvSchema as default };

packages/core/src/private/app/Facade.browser.ts

@@ -0,0 +1,23 @@
+/**
+ * Browser stub for AppFacade.
+ * env must never be called in frontend code, ecrets must not leak to clients
+ */
+export default class AppFacade {
+  config(_path: string): never {
+    throw new Error("AppFacade.config() is not available in the browser");
+  }
+
+  env(_key: string): never {
+    throw new Error(
+      "AppFacade.env() is server-only. Do not call env() in frontend/browser code.",
+    );
+  }
+
+  view(_name: string): never {
+    throw new Error("AppFacade.view() is not available in the browser");
+  }
+
+  get root(): never {
+    throw new Error("AppFacade.root is not available in the browser");
+  }
+}

packages/core/src/private/app/Facade.ts

@@ -1,23 +1,41 @@
-import type Config from "#config/Config";
+import type EnvSchema from "#app/EnvSchema";
 import type ServerView from "#client/ServerView";
+import type Config from "#config/Config";
+import E from "#errors";
 import type ServeApp from "#serve/App";
 import dict from "@rcompat/dict";
+import env from "@rcompat/env";
+import type { ObjectType } from "pema";
+import ParseError from "pema/ParseError";
 
 const s_attach = Symbol("attach");
 const s_config = Symbol("config");
 
 export { s_attach, s_config };
 
-export default class AppFacade {
+type Env<P extends EnvSchema> = { [K in keyof P]: P[K]["infer"] };
+
+export default class AppFacade<T extends EnvSchema = EnvSchema> {
   #config: Config;
   #app?: ServeApp;
+  #env?: Env<T>;
 
   constructor(config: Config) {
     this.#config = config;
   }
 
   [s_attach](app: ServeApp) {
     this.#app = app;
+
+    const schema = this.#config.env.schema as ObjectType<T> | undefined;
+    if (schema !== undefined) {
+      try {
+        this.#env = schema.coerce(env.toJSON()) as Env<T>;
+      } catch (error) {
+        if (ParseError.is(error)) throw E.env_invalid_schema(error);
+        throw error;
+      }
+    }
   }
 
   get [s_config]() {
@@ -28,6 +46,15 @@ export default class AppFacade {
     return dict.get(this.#config, path);
   }
 
+  env<K extends keyof T>(key: K): T[K]["infer"];
+  env(key: string): unknown {
+    if (this.#env !== undefined) {
+      if (!(key in this.#env)) throw E.env_missing_key(key);
+      return this.#env[key as keyof T];
+    }
+    return env.get(key);
+  }
+
   get #with() {
     if (!this.#app) throw new Error("ServeApp not bound yet (used too early)");
     return this.#app;

packages/core/src/private/config/index.ts

@@ -1,6 +1,12 @@
+import type EnvSchema from "#app/EnvSchema";
 import AppFacade from "#app/Facade";
 import schema from "#config/schema";
+import type { ObjectType } from "pema";
 
-export default (input: typeof schema.input = {}) =>
-  new AppFacade(schema.parse(input));
-;
+export default function config<P extends EnvSchema = EnvSchema>(
+  input: typeof schema.input & {
+    env?: { schema?: ObjectType<P> };
+  } = {},
+): AppFacade<P> {
+  return new AppFacade<P>(schema.parse(input as typeof schema.input));
+}

packages/core/src/private/config/schema.ts

@@ -1,6 +1,8 @@
 import type DB from "#db/DB";
 import type Module from "#Module";
 import fs from "@rcompat/fs";
+import type { Dict } from "@rcompat/type";
+import type { ObjectType, Parsed } from "pema";
 import p from "pema";
 
 export default p({
@@ -29,6 +31,9 @@ export default p({
       blocking: p.boolean.default(true),
     }).optional(),
   },
+  env: {
+    schema: p.pure<ObjectType<Dict<Parsed<unknown>>>>().optional(),
+  },
   modules: p.array(p.object({
     name: p.string,
     setup: p.function,

packages/core/src/private/errors.ts

@@ -1,5 +1,6 @@
 import error from "@rcompat/error";
 import type { FileRef } from "@rcompat/fs";
+import type ParseError from "pema/ParseError";
 
 const t = error.template;
 
@@ -203,6 +204,21 @@ const VIEW = error.coded({
   view_error,
 });
 
+function env_invalid_schema(cause: ParseError) {
+  const issues = cause.issues
+    .map(i => `  ${i.path.replace(/^\//, "")}: ${i.message}`)
+    .join("\n");
+  return t`environment variables failed validation:\n${issues}`;
+}
+function env_missing_key(key: string) {
+  return t`environment variable ${key} is not defined`;
+}
+
+const ENV = error.coded({
+  env_invalid_schema,
+  env_missing_key,
+});
+
 const errors = {
   ...APP,
   ...BUILD,
@@ -215,6 +231,7 @@ const errors = {
   ...SESSION,
   ...TARGET,
   ...VIEW,
+  ...ENV,
 };
 
 export type Code = keyof typeof errors;