@antelopejs/interface-core 0.0.13 → 0.1.0

package/dist/config.d.ts

@@ -32,6 +32,33 @@ export interface ModuleSourceLocalFolder extends ModuleSource {
     installCommand?: ModuleInstallCommand;
     reloadCommand?: ModuleInstallCommand;
 }
+/**
+ * A value a module may publish as a config variable.
+ *
+ * Only primitives travel between modules: the value is substituted into
+ * another module's configuration before that module constructs.
+ */
+export type ConfigVarValue = string | number | boolean;
+/**
+ * The config variables a module publishes from its `provide` callback.
+ *
+ * The keys must match the names the module declares in its `package.json`
+ * under `antelopeJs.configVars`. Consumers reference them from their own
+ * configuration with `${@<moduleName>.<VAR_NAME>}`, and the core substitutes
+ * the values before any module constructs.
+ */
+export type ConfigVars = Record<string, ConfigVarValue>;
+/**
+ * The `provide` lifecycle callback a provider module exports.
+ *
+ * It runs before every `construct`, which is what makes the published values
+ * available to consumers whatever the order of the interface graph. A provider
+ * must therefore compute its values on its own: no other module has
+ * constructed yet, so awaiting another module's interface from `provide`
+ * deadlocks the startup. The core interfaces registered before the module
+ * lifecycle starts, `GetRuntimeInfo()` among them, remain available.
+ */
+export type ConfigVarProvider = (config: unknown) => Promise<ConfigVars | void> | ConfigVars | void;
 export interface AntelopeTestConfig {
     folder?: string;
     setup?: () => undefined | Partial<AntelopeConfig> | Promise<undefined | Partial<AntelopeConfig>>;

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";AAAA,sBAAsB;;AAuGtB,oCAEC;AAFD,SAAgB,YAAY,CAAC,KAAkB;IAC7C,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";AAAA,sBAAsB;;AAyItB,oCAEC;AAFD,SAAgB,YAAY,CAAC,KAAkB;IAC7C,OAAO,KAAK,CAAC;AACf,CAAC"}

package/docs/7.configuration.md

@@ -174,6 +174,53 @@ Logging configuration within the project config.
 | `formatter`      | `Record<string, string>`           | Custom formatters per channel                     |
 | `dateFormat`     | `string`                           | Date format string for log timestamps             |
 
+## Config variables
+
+A module can publish named values other modules reference from their own configuration. The provider declares the names it publishes in its `package.json`, returns them from its `provide` callback, and the core substitutes them into every consumer before any module constructs.
+
+```json
+{
+  "name": "api",
+  "antelopeJs": {
+    "configVars": ["API_PORT"]
+  }
+}
+```
+
+```ts
+import type { ConfigVars } from "@antelopejs/interface-core/config";
+
+export async function provide(config: unknown): Promise<ConfigVars> {
+  const port = await reservePort(config);
+  return { API_PORT: port };
+}
+```
+
+`provide` is optional and only providers implement it. It runs before every `construct`, so a provider cannot await another module's interface from it: nothing has constructed yet. The core interfaces registered before the module lifecycle starts — `GetRuntimeInfo()` among them — stay available, which is enough to compute a port, a base URL or a generated secret.
+
+A consumer references the value with `${@<moduleName>.<VAR_NAME>}`, where `<moduleName>` is the module key used in the project configuration:
+
+```ts
+export default defineConfig({
+  name: "my-project",
+  modules: {
+    api: { version: "1.0.0" },
+    dms: {
+      version: "1.0.0",
+      config: { apiBaseUrl: "http://127.0.0.1:${@api.API_PORT}" },
+    },
+  },
+});
+```
+
+| Type                | Definition                                                               | Description                             |
+| ------------------- | ------------------------------------------------------------------------ | --------------------------------------- |
+| `ConfigVarValue`    | `string \| number \| boolean`                                            | A single published value                |
+| `ConfigVars`        | `Record<string, ConfigVarValue>`                                         | The record `provide` returns            |
+| `ConfigVarProvider` | `(config: unknown) => Promise<ConfigVars \| void> \| ConfigVars \| void` | The signature of the `provide` callback |
+
+Values are resolved once, before construction, and never re-resolved afterwards. `construct` cannot publish config variables: its return value is ignored. See the core documentation for the resolution order and the failure modes.
+
 ## `AntelopeTestConfig`
 
 Test configuration for the project.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-core",
-  "version": "0.0.13",
+  "version": "0.1.0",
   "description": "AntelopeJS core interface primitives - proxies, decorators, interface functions, and logging",
   "keywords": [
     "antelopejs",