@antelopejs/interface-core 0.0.12 → 0.0.14

package/docs/7.configuration.md

@@ -34,7 +34,11 @@ export default defineConfig({
     database: "@antelopejs/database",
     auth: {
       version: "1.0.0",
-      source: { type: "package", package: "@antelopejs/auth", version: "1.0.0" },
+      source: {
+        type: "package",
+        package: "@antelopejs/auth",
+        version: "1.0.0",
+      },
       config: { secret: "my-secret" },
     },
   },
@@ -48,7 +52,11 @@ export default defineConfig((ctx) => {
     name: "my-project",
     modules: {
       database: {
-        source: { type: "package", package: "@antelopejs/database", version: "1.0.0" },
+        source: {
+          type: "package",
+          package: "@antelopejs/database",
+          version: "1.0.0",
+        },
         config: {
           host: ctx.env === "production" ? "db.prod.internal" : "localhost",
         },
@@ -62,15 +70,15 @@ export default defineConfig((ctx) => {
 
 The root configuration object for an AntelopeJS project.
 
-| Property         | Type                                            | Description                                 |
-| ---------------- | ----------------------------------------------- | ------------------------------------------- |
-| `name`           | `string`                                        | Project name                                |
-| `cacheFolder`    | `string`                                        | Optional custom cache directory              |
-| `modules`        | `Record<string, string \| AntelopeModuleConfig>` | Module definitions (shorthand or full)       |
-| `logging`        | `AntelopeLogging`                               | Optional logging configuration              |
-| `envOverrides`   | `Record<string, string \| string[]>`            | Optional environment variable overrides      |
-| `environments`   | `Record<string, Partial<AntelopeConfig>>`        | Optional per-environment config overrides    |
-| `test`           | `AntelopeTestConfig`                            | Optional test configuration                 |
+| Property       | Type                                             | Description                               |
+| -------------- | ------------------------------------------------ | ----------------------------------------- |
+| `name`         | `string`                                         | Project name                              |
+| `cacheFolder`  | `string`                                         | Optional custom cache directory           |
+| `modules`      | `Record<string, string \| AntelopeModuleConfig>` | Module definitions (shorthand or full)    |
+| `logging`      | `AntelopeLogging`                                | Optional logging configuration            |
+| `envOverrides` | `Record<string, string \| string[]>`             | Optional environment variable overrides   |
+| `environments` | `Record<string, Partial<AntelopeConfig>>`        | Optional per-environment config overrides |
+| `test`         | `AntelopeTestConfig`                             | Optional test configuration               |
 
 ## Module sources
 
@@ -146,35 +154,79 @@ Like the local source, `local-folder` also accepts an optional `reloadCommand` t
 
 Full module configuration within the project config.
 
-| Property          | Type                                              | Description                              |
-| ----------------- | ------------------------------------------------- | ---------------------------------------- |
-| `version`         | `string`                                          | Optional version constraint              |
-| `source`          | `ModuleSource*`                                   | Source definition (local, git, package, local-folder) |
-| `config`          | `unknown`                                         | Optional runtime configuration           |
-| `importOverrides` | `ImportOverride[] \| Record<string, string>`       | Optional import path redirections        |
-| `disabledExports` | `string[]`                                        | Optional list of exports to disable      |
+| Property          | Type                                         | Description                                           |
+| ----------------- | -------------------------------------------- | ----------------------------------------------------- |
+| `version`         | `string`                                     | Optional version constraint                           |
+| `source`          | `ModuleSource*`                              | Source definition (local, git, package, local-folder) |
+| `config`          | `unknown`                                    | Optional runtime configuration                        |
+| `importOverrides` | `ImportOverride[] \| Record<string, string>` | Optional import path redirections                     |
+| `disabledExports` | `string[]`                                   | Optional list of exports to disable                   |
 
 ## `AntelopeLogging`
 
 Logging configuration within the project config.
 
-| Property          | Type                              | Description                                |
-| ----------------- | --------------------------------- | ------------------------------------------ |
-| `enabled`         | `boolean`                         | Enable or disable logging                  |
-| `moduleTracking`  | `object`                          | Track module-level logging with includes/excludes |
-| `channelFilter`   | `Record<string, number \| string>` | Filter log output by channel and level     |
-| `formatter`       | `Record<string, string>`          | Custom formatters per channel              |
-| `dateFormat`      | `string`                          | Date format string for log timestamps      |
+| Property         | Type                               | Description                                       |
+| ---------------- | ---------------------------------- | ------------------------------------------------- |
+| `enabled`        | `boolean`                          | Enable or disable logging                         |
+| `moduleTracking` | `object`                           | Track module-level logging with includes/excludes |
+| `channelFilter`  | `Record<string, number \| string>` | Filter log output by channel and level            |
+| `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 `construct`, and the core substitutes them into every consumer before that consumer constructs.
+
+```json
+{
+  "name": "api",
+  "antelopeJs": {
+    "configVars": ["API_PORT"]
+  }
+}
+```
+
+```ts
+import type { ConfigVars } from "@antelopejs/interface-core/config";
+
+export async function construct(config: unknown): Promise<ConfigVars> {
+  const port = await bindPort(config);
+  return { API_PORT: port };
+}
+```
+
+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 `construct` returns to publish variables |
+
+Values are resolved once, at construct time, and never re-resolved afterwards. See the core documentation for the resolution order and the failure modes.
 
 ## `AntelopeTestConfig`
 
 Test configuration for the project.
 
-| Property  | Type         | Description                                         |
-| --------- | ------------ | --------------------------------------------------- |
-| `folder`  | `string`     | Optional test folder path                           |
-| `setup`   | `Function`   | Optional async setup function returning partial config |
-| `cleanup` | `Function`   | Optional async cleanup function                     |
+| Property  | Type       | Description                                            |
+| --------- | ---------- | ------------------------------------------------------ |
+| `folder`  | `string`   | Optional test folder path                              |
+| `setup`   | `Function` | Optional async setup function returning partial config |
+| `cleanup` | `Function` | Optional async cleanup function                        |
 
 ## Next steps
 

package/docs/8.runtime.md

@@ -23,11 +23,11 @@ const info = await GetRuntimeInfo();
 // { dev: true, projectPath: "/path/to/project", env: "default" }
 ```
 
-| Field         | Description                                                       |
-| ------------- | ----------------------------------------------------------------- |
-| `dev`         | `true` when running under `ajs project dev`, `false` otherwise    |
-| `projectPath` | Absolute path to the root of the running project                  |
-| `env`         | Name of the active configuration environment                      |
+| Field         | Description                                                    |
+| ------------- | -------------------------------------------------------------- |
+| `dev`         | `true` when running under `ajs project dev`, `false` otherwise |
+| `projectPath` | Absolute path to the root of the running project               |
+| `env`         | Name of the active configuration environment                   |
 
 ## `RegisterDevServer`
 

package/package.json

@@ -1,48 +1,24 @@
 {
   "name": "@antelopejs/interface-core",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "AntelopeJS core interface primitives - proxies, decorators, interface functions, and logging",
   "keywords": [
     "antelopejs",
-    "interface",
-    "core"
+    "core",
+    "interface"
   ],
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AntelopeJS/interface-core.git"
   },
-  "license": "Apache-2.0",
-  "packageManager": "pnpm@10.6.5",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
   "files": [
     "dist",
     "docs",
     "skills"
   ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./*": {
-      "types": "./dist/*.d.ts",
-      "default": "./dist/*.js"
-    },
-    "./config": {
-      "types": "./dist/config.d.ts",
-      "default": "./dist/config.js"
-    },
-    "./logging": {
-      "types": "./dist/logging/index.d.ts",
-      "default": "./dist/logging/index.js"
-    },
-    "./logging/*": {
-      "types": "./dist/logging/*.d.ts",
-      "default": "./dist/logging/*.js"
-    },
-    "./package.json": "./package.json"
-  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "typesVersions": {
     "*": {
       "decorators": [
@@ -71,37 +47,70 @@
       ]
     }
   },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    },
+    "./logging": {
+      "types": "./dist/logging/index.d.ts",
+      "default": "./dist/logging/index.js"
+    },
+    "./logging/*": {
+      "types": "./dist/logging/*.d.ts",
+      "default": "./dist/logging/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "scripts": {
     "build": "rimraf dist && tsc",
-    "format": "biome format --write .",
-    "lint:fix": "biome check --write .",
-    "lint": "biome check .",
+    "format": "oxfmt .",
+    "lint:fix": "oxlint --fix",
+    "lint": "oxlint",
     "prepack": "pnpm run build",
-    "release": "pnpm run lint && pnpm run prepack && release-it",
-    "test": "pnpm run build && ajs module test .",
-    "test:package": "node test/package-consumer.mjs"
-  },
-  "antelopeJs": {
-    "test": "src/antelope.test.ts",
-    "skills": [
-      "./skills"
-    ]
+    "release": "pnpm run lint && pnpm run test && pnpm run test:package && pnpm run prepack && release-it",
+    "test": "pnpm run build && mocha 'dist/tests/**/*.test.js'",
+    "test:package": "node test/package-consumer.mjs",
+    "format:check": "oxfmt --check .",
+    "knip": "knip"
   },
   "dependencies": {
     "reflect-metadata": "^0.2.2"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.3.2",
+    "@antelopejs/tooling-configs": "^0.0.4",
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.19.15",
     "chai": "^4.5.0",
+    "eslint-plugin-perfectionist": "^5.11.0",
+    "knip": "^6.34.0",
+    "mocha": "^11.7.5",
+    "oxfmt": "^0.66.0",
+    "oxlint": "1.81.0",
+    "oxlint-tsgolint": "^7.0.2001",
     "release-it": "^19.2.4",
     "release-it-changelogen": "^0.1.0",
     "rimraf": "^6.1.3",
     "typescript": "^5.9.3"
   },
-  "publishConfig": {
-    "access": "public"
+  "packageManager": "pnpm@10.6.5",
+  "antelopeJs": {
+    "test": "src/antelope.test.ts",
+    "skills": [
+      "./skills"
+    ]
   }
 }

package/skills/core-interface/SKILL.md

@@ -16,12 +16,48 @@ factories, `GetMetadata`, and config types are ordinary consumer-side helpers (n
 ## Import paths
 
 ```ts
-import { InterfaceFunction, ImplementInterface, GetMetadata, GetInterfaceInstances, GetInterfaceInstance, AsyncProxy, EventProxy, RegisteringProxy, GetResponsibleModule } from "@antelopejs/interface-core";
-import { MakeClassDecorator, MakeMethodDecorator, MakePropertyDecorator, MakeParameterDecorator } from "@antelopejs/interface-core/decorators"; // + many combined variants
-import { Events, ListModules, GetModuleInfo, LoadModule, StartModule, StopModule, DestroyModule, ReloadModule } from "@antelopejs/interface-core/modules";
-import { AsyncProxy, EventProxy, RegisteringProxy } from "@antelopejs/interface-core/proxies"; // same classes the root entry re-exports; pick one import site
-import { GetRuntimeInfo, RegisterDevServer, DEV_REGISTRY_PATH } from "@antelopejs/interface-core/runtime";
-import { defineConfig, type AntelopeConfig, type AntelopeModuleConfig } from "@antelopejs/interface-core/config";
+import {
+  InterfaceFunction,
+  ImplementInterface,
+  GetMetadata,
+  GetInterfaceInstances,
+  GetInterfaceInstance,
+  AsyncProxy,
+  EventProxy,
+  RegisteringProxy,
+  GetResponsibleModule,
+} from "@antelopejs/interface-core";
+import {
+  MakeClassDecorator,
+  MakeMethodDecorator,
+  MakePropertyDecorator,
+  MakeParameterDecorator,
+} from "@antelopejs/interface-core/decorators"; // + many combined variants
+import {
+  Events,
+  ListModules,
+  GetModuleInfo,
+  LoadModule,
+  StartModule,
+  StopModule,
+  DestroyModule,
+  ReloadModule,
+} from "@antelopejs/interface-core/modules";
+import {
+  AsyncProxy,
+  EventProxy,
+  RegisteringProxy,
+} from "@antelopejs/interface-core/proxies"; // same classes the root entry re-exports; pick one import site
+import {
+  GetRuntimeInfo,
+  RegisterDevServer,
+  DEV_REGISTRY_PATH,
+} from "@antelopejs/interface-core/runtime";
+import {
+  defineConfig,
+  type AntelopeConfig,
+  type AntelopeModuleConfig,
+} from "@antelopejs/interface-core/config";
 import { Logging } from "@antelopejs/interface-core/logging";
 ```
 
@@ -65,8 +101,8 @@ implemented; providers `emit` on them, consumers `register`/`unregister` handler
 ```ts
 import { Logging } from "@antelopejs/interface-core/logging";
 
-Logging.Info("hello");                       // main channel; also Error/Warn/Debug/Trace
-const ch = new Logging.Channel("database");  // named channel
+Logging.Info("hello"); // main channel; also Error/Warn/Debug/Trace
+const ch = new Logging.Channel("database"); // named channel
 ch.Debug("query", { ms: 12 });
 ```