Interface Core Documentation

Overview

@antelopejs/interface-core provides the foundational building blocks for the AntelopeJS interface system. It defines the core primitives that enable type-safe, module-aware communication between decoupled components.

The package exports several key categories of functionality:

• Proxies - AsyncProxy, EventProxy, and RegisteringProxy manage cross-module function calls, events, and registrations with automatic cleanup when modules are unloaded.
• Interface functions - InterfaceFunction and ImplementInterface wire up interface declarations to their concrete implementations.
• Decorator factories - Utilities for building type-safe TypeScript decorators that target classes, properties, methods, and parameters.
• Metadata - GetMetadata provides reflection-based metadata retrieval with inheritance support.
• Module lifecycle - Events and functions for managing module construction, startup, shutdown, and destruction.
• Logging - A structured, channel-based logging system with multiple severity levels.
• Configuration - TypeScript types and helpers for defining AntelopeJS project configurations.

Import paths

The package exposes several entry points:

// Main entry - proxies, InterfaceFunction, GetMetadata, ImplementInterface, GetInterfaceInstances
import { AsyncProxy, InterfaceFunction, GetMetadata } from "@antelopejs/interface-core";

// Decorator factories
import { MakeClassDecorator, MakeMethodDecorator } from "@antelopejs/interface-core/decorators";

// Module lifecycle events and management
import { Events, ListModules, LoadModule } from "@antelopejs/interface-core/modules";

// Logging system
import { Logging } from "@antelopejs/interface-core/logging";

// Configuration types and helpers
import { defineConfig } from "@antelopejs/interface-core/config";

How interfaces work

AntelopeJS interfaces act as contracts between modules. One module declares an interface using proxy objects and InterfaceFunction, while another module provides the implementation using ImplementInterface. The proxy layer handles queuing, lifecycle management, and automatic cleanup.

// Declaration side: define what the interface looks like
import { InterfaceFunction, EventProxy } from "@antelopejs/interface-core";

export const GetUser = InterfaceFunction<(id: string) => { name: string }>();
export const OnUserCreated = new EventProxy<(userId: string) => void>();

// Implementation side: provide the concrete behavior
import { ImplementInterface } from "@antelopejs/interface-core";
import * as UserInterface from "./declaration";

ImplementInterface(UserInterface, {
  GetUser(id: string) {
    return { name: "Alice" };
  },
});

The proxy system ensures that calls to GetUser before the implementation is attached are automatically queued and resolved once the implementation becomes available. When the implementing module is unloaded, the proxy detaches and resumes queuing.

Next steps

• Proxies - Deep dive into AsyncProxy, EventProxy, and RegisteringProxy
• Decorators - Build type-safe decorator factories
• Modules - Understand module lifecycle events
• Logging - Use the structured logging system