# 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:

```ts
// 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.

```ts
// 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>();
```

```ts
// 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](./2.proxies.md) - Deep dive into `AsyncProxy`, `EventProxy`, and `RegisteringProxy`
- [Decorators](./3.decorators.md) - Build type-safe decorator factories
- [Modules](./5.modules.md) - Understand module lifecycle events
- [Logging](./6.logging.md) - Use the structured logging system