@antelopejs/interface-core 0.0.14 → 0.1.0

package/dist/config.d.ts

@@ -40,14 +40,25 @@ export interface ModuleSourceLocalFolder extends ModuleSource {
  */
 export type ConfigVarValue = string | number | boolean;
 /**
- * The config variables a module publishes from its `construct` callback.
+ * 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 constructing the consumer.
+ * 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;;AA2HtB,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

@@ -176,7 +176,7 @@ Logging configuration within the project config.
 
 ## 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 `construct`, and the core substitutes them into every consumer before that consumer constructs.
+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
 {
@@ -190,12 +190,14 @@ A module can publish named values other modules reference from their own configu
 ```ts
 import type { ConfigVars } from "@antelopejs/interface-core/config";
 
-export async function construct(config: unknown): Promise<ConfigVars> {
-  const port = await bindPort(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
@@ -211,12 +213,13 @@ export default defineConfig({
 });
 ```
 
-| Type             | Definition                       | Description                                         |
-| ---------------- | -------------------------------- | --------------------------------------------------- |
-| `ConfigVarValue` | `string \| number \| boolean`    | A single published value                            |
-| `ConfigVars`     | `Record<string, ConfigVarValue>` | The record `construct` returns to publish variables |
+| 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, at construct time, and never re-resolved afterwards. See the core documentation for the resolution order and the failure modes.
+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`
 

package/package.json

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