@antelopejs/interface-core 0.0.6 → 0.0.8

package/docs/3.decorators.md

@@ -0,0 +1,169 @@
+# Decorators
+
+## Overview
+
+The `@antelopejs/interface-core/decorators` module provides factory functions for creating type-safe TypeScript decorators. These factories handle the boilerplate of splitting decorator arguments from factory arguments, producing reusable, parameterized decorators for classes, properties, methods, and parameters.
+
+## Import
+
+```ts
+import {
+  MakeClassDecorator,
+  MakePropertyDecorator,
+  MakeMethodDecorator,
+  MakeParameterDecorator,
+} from "@antelopejs/interface-core/decorators";
+```
+
+## Types
+
+The module exports several utility types used throughout the decorator system:
+
+| Type                 | Description                                                  |
+| -------------------- | ------------------------------------------------------------ |
+| `Func<A, R>`         | Generic function type with arguments `A` and return type `R` |
+| `Class<T, A>`        | Class constructor that creates instances of type `T`         |
+| `ClassDecorator<C>`  | Decorator applied to class constructors                      |
+| `PropertyDecorator`  | Decorator applied to class properties                        |
+| `MethodDecorator`    | Decorator applied to class methods and accessors             |
+| `ParameterDecorator` | Decorator applied to method parameters                       |
+
+## Single-target decorator factories
+
+### `MakeClassDecorator`
+
+Creates a decorator factory that targets classes. The handler receives the decorated class as its first argument, followed by any factory parameters.
+
+```ts
+import { MakeClassDecorator } from "@antelopejs/interface-core/decorators";
+
+const Entity = MakeClassDecorator((target: Function, tableName: string) => {
+  Reflect.defineMetadata("table", tableName, target);
+});
+
+@Entity("users")
+class User {
+  name!: string;
+}
+```
+
+### `MakePropertyDecorator`
+
+Creates a decorator factory that targets properties. The handler receives the target object and property key, followed by factory parameters.
+
+```ts
+import { MakePropertyDecorator } from "@antelopejs/interface-core/decorators";
+
+const Column = MakePropertyDecorator((target: any, key: PropertyKey, columnName: string) => {
+  const columns = Reflect.getOwnMetadata("columns", target) || [];
+  columns.push({ key, columnName });
+  Reflect.defineMetadata("columns", columns, target);
+});
+
+class User {
+  @Column("user_name")
+  name!: string;
+}
+```
+
+### `MakeMethodDecorator`
+
+Creates a decorator factory that targets methods and accessors. The handler receives the target object, method key, and property descriptor, followed by factory parameters.
+
+```ts
+import { MakeMethodDecorator } from "@antelopejs/interface-core/decorators";
+
+const Log = MakeMethodDecorator(
+  (target: any, key: PropertyKey, descriptor: PropertyDescriptor, level: string) => {
+    const original = descriptor.value;
+    descriptor.value = function (...args: any[]) {
+      console.log(`[${level}] Calling ${String(key)}`);
+      return original.apply(this, args);
+    };
+  },
+);
+
+class Service {
+  @Log("info")
+  process() {
+    // ...
+  }
+}
+```
+
+### `MakeParameterDecorator`
+
+Creates a decorator factory that targets method parameters. The handler receives the target object, method key, and parameter index, followed by factory parameters.
+
+```ts
+import { MakeParameterDecorator } from "@antelopejs/interface-core/decorators";
+
+const Inject = MakeParameterDecorator(
+  (target: any, key: PropertyKey, index: number, token: string) => {
+    const injections = Reflect.getOwnMetadata("injections", target, key) || [];
+    injections[index] = token;
+    Reflect.defineMetadata("injections", injections, target, key);
+  },
+);
+
+class Controller {
+  handle(@Inject("db") db: any) {
+    // ...
+  }
+}
+```
+
+## Multi-target decorator factories
+
+For decorators that apply to multiple targets, the module provides combined factory functions. These detect the decorator context automatically based on the number and types of arguments received.
+
+| Factory                                            | Targets                                   |
+| -------------------------------------------------- | ----------------------------------------- |
+| `MakePropertyAndClassDecorator`                    | Properties and classes                    |
+| `MakeMethodAndClassDecorator`                      | Methods and classes                       |
+| `MakeMethodAndPropertyDecorator`                   | Methods and properties                    |
+| `MakeMethodAndPropertyAndClassDecorator`            | Methods, properties, and classes          |
+| `MakeParameterAndClassDecorator`                   | Parameters and classes                    |
+| `MakeParameterAndPropertyDecorator`                | Parameters and properties                 |
+| `MakeParameterAndPropertyAndClassDecorator`         | Parameters, properties, and classes       |
+| `MakeParameterAndMethodDecorator`                  | Parameters and methods                    |
+| `MakeParameterAndMethodAndClassDecorator`           | Parameters, methods, and classes          |
+| `MakeParameterAndMethodAndPropertyDecorator`        | Parameters, methods, and properties       |
+| `MakeParameterAndMethodAndPropertyAndClassDecorator`| Parameters, methods, properties, classes  |
+
+### Example: method and class decorator
+
+```ts
+import { MakeMethodAndClassDecorator } from "@antelopejs/interface-core/decorators";
+
+const Track = MakeMethodAndClassDecorator(
+  (target: any, key: PropertyKey | undefined, descriptor: PropertyDescriptor | undefined, category: string) => {
+    if (descriptor) {
+      // Applied to a method
+      const original = descriptor.value;
+      descriptor.value = function (...args: any[]) {
+        console.log(`[${category}] ${String(key)} called`);
+        return original.apply(this, args);
+      };
+    } else {
+      // Applied to a class
+      Reflect.defineMetadata("trackCategory", category, target);
+    }
+  },
+);
+
+@Track("api")
+class ApiController {
+  @Track("endpoint")
+  getUsers() {
+    // ...
+  }
+}
+```
+
+When applied to a class, the `key` and `descriptor` arguments are `undefined`. When applied to a method, all three arguments are provided.
+
+## Next steps
+
+- [Metadata](./4.metadata.md) - Reflection-based metadata with `GetMetadata`
+- [Proxies](./2.proxies.md) - Module-aware proxy classes

package/docs/4.metadata.md

@@ -0,0 +1,107 @@
+# Metadata
+
+## Overview
+
+The `GetMetadata` function provides a reflection-based metadata system built on top of the `reflect-metadata` library. It retrieves or creates metadata instances associated with target objects, supporting inheritance through the prototype chain.
+
+## Import
+
+```ts
+import { GetMetadata } from "@antelopejs/interface-core";
+```
+
+## `GetMetadata`
+
+```ts
+function GetMetadata<T, U>(target: U, meta: Class<T, [U]> & { key: symbol }, inherit?: boolean): T
+```
+
+### Parameters
+
+| Parameter | Type                             | Default | Description                                          |
+| --------- | -------------------------------- | ------- | ---------------------------------------------------- |
+| `target`  | `U`                              | -       | The object to retrieve or create metadata for        |
+| `meta`    | `Class<T, [U]> & { key: symbol }` | -       | A metadata class with a static `key` symbol          |
+| `inherit` | `boolean`                        | `true`  | Whether to inherit metadata from the prototype chain |
+
+### Return value
+
+Returns the metadata instance of type `T` associated with the target.
+
+## Define a metadata class
+
+A metadata class must have a static `key` property (a `Symbol`) and accept the target object as a constructor argument.
+
+```ts
+class RouteMetadata {
+  static key = Symbol("RouteMetadata");
+
+  public routes: Map<string, string> = new Map();
+
+  constructor(_target: any) {
+    // Initialize metadata for the target
+  }
+}
+```
+
+## Retrieve metadata
+
+```ts
+import { GetMetadata } from "@antelopejs/interface-core";
+
+class UserController {
+  getUser() {}
+  listUsers() {}
+}
+
+const meta = GetMetadata(UserController.prototype, RouteMetadata);
+meta.routes.set("getUser", "/users/:id");
+meta.routes.set("listUsers", "/users");
+```
+
+Calling `GetMetadata` multiple times with the same target and metadata class returns the same instance. The metadata is stored on the target using `Reflect.defineMetadata`.
+
+## Inheritance
+
+When `inherit` is `true` (the default), `GetMetadata` walks the prototype chain to find parent metadata. If the metadata class defines an `inherit` method, that method is called with the parent metadata. Otherwise, properties from the parent are copied to the child metadata where they do not already exist.
+
+```ts
+class ControllerMeta {
+  static key = Symbol("ControllerMeta");
+
+  public middleware: string[] = [];
+
+  constructor(_target: any) {}
+
+  inherit(parent: ControllerMeta) {
+    this.middleware = [...parent.middleware];
+  }
+}
+
+class BaseController {}
+const baseMeta = GetMetadata(BaseController.prototype, ControllerMeta);
+baseMeta.middleware.push("auth");
+
+class AdminController extends BaseController {}
+const adminMeta = GetMetadata(AdminController.prototype, ControllerMeta);
+// adminMeta.middleware contains ["auth"] (inherited from BaseController)
+
+adminMeta.middleware.push("adminOnly");
+// adminMeta.middleware is now ["auth", "adminOnly"]
+// baseMeta.middleware remains ["auth"]
+```
+
+Without a custom `inherit` method, properties are shallow-copied from parent to child using `Object.getOwnPropertyNames`, but only for keys that do not already exist on the child metadata instance.
+
+## Disable inheritance
+
+Pass `false` as the third argument to prevent prototype chain traversal:
+
+```ts
+const meta = GetMetadata(target, RouteMetadata, false);
+```
+
+## Next steps
+
+- [Decorators](./3.decorators.md) - Combine metadata with decorator factories
+- [Modules](./5.modules.md) - Module lifecycle events and management

package/docs/5.modules.md

@@ -0,0 +1,180 @@
+# Modules
+
+## Overview
+
+The `@antelopejs/interface-core/modules` module provides lifecycle events and management functions for AntelopeJS modules. Modules transition through a defined lifecycle, and each transition emits an event that other modules can observe.
+
+## Import
+
+```ts
+import {
+  Events,
+  ListModules,
+  GetModuleInfo,
+  LoadModule,
+  StartModule,
+  StopModule,
+  DestroyModule,
+  ReloadModule,
+} from "@antelopejs/interface-core/modules";
+```
+
+## Module lifecycle
+
+A module moves through these states:
+
+```
+loaded -> constructed -> active -> constructed -> loaded
+                                   (stopped)     (destroyed)
+```
+
+| State         | Description                                                  |
+| ------------- | ------------------------------------------------------------ |
+| `loaded`      | Module code is loaded but no instance exists                 |
+| `constructed` | Module instance is created but not started                   |
+| `active`      | Module is fully started and providing services               |
+| `unknown`     | Module status cannot be determined                           |
+
+## Lifecycle events
+
+The `Events` namespace exposes four `EventProxy` instances that fire during module lifecycle transitions.
+
+### `Events.ModuleConstructed`
+
+Fires after a module instance is created, before the module is started.
+
+```ts
+import { Events } from "@antelopejs/interface-core/modules";
+
+Events.ModuleConstructed.register((moduleId: string) => {
+  console.log(`Module constructed: ${moduleId}`);
+});
+```
+
+### `Events.ModuleStarted`
+
+Fires after a module has been started and is fully operational.
+
+```ts
+Events.ModuleStarted.register((moduleId: string) => {
+  console.log(`Module started: ${moduleId}`);
+});
+```
+
+### `Events.ModuleStopped`
+
+Fires after a module has been stopped. The module instance still exists but is no longer active.
+
+```ts
+Events.ModuleStopped.register((moduleId: string) => {
+  console.log(`Module stopped: ${moduleId}`);
+});
+```
+
+### `Events.ModuleDestroyed`
+
+Fires after a module instance has been destroyed and all its resources have been released. The system uses this event internally to clean up proxy attachments and event handlers associated with the destroyed module.
+
+```ts
+Events.ModuleDestroyed.register((moduleId: string) => {
+  console.log(`Module destroyed: ${moduleId}`);
+});
+```
+
+## Management functions
+
+These functions are declared as `InterfaceFunction` proxies. They are available once the core runtime provides their implementation.
+
+### `ListModules`
+
+Returns the identifiers of all loaded modules.
+
+```ts
+const modules = await ListModules();
+// ["auth-module", "database-module", "api-module"]
+```
+
+### `GetModuleInfo`
+
+Returns detailed information about a specific module, including its configuration, status, and file system path.
+
+```ts
+import type { ModuleInfo } from "@antelopejs/interface-core/modules";
+
+const info: ModuleInfo = await GetModuleInfo("auth-module");
+// info.status -> "active"
+// info.localPath -> "/path/to/auth-module"
+// info.source -> { type: "package", ... }
+```
+
+### `LoadModule`
+
+Loads a new module with the given configuration. Set `autostart` to `true` to automatically start the module after loading.
+
+```ts
+import type { ModuleDefinition } from "@antelopejs/interface-core/modules";
+
+const definition: ModuleDefinition = {
+  source: { type: "package", package: "@my/module", version: "1.0.0" },
+  config: { key: "value" },
+};
+
+await LoadModule("my-module", definition, true);
+```
+
+### `StartModule`
+
+Starts a loaded but inactive module.
+
+```ts
+await StartModule("my-module");
+```
+
+### `StopModule`
+
+Stops an active module. The module instance remains but stops providing services.
+
+```ts
+await StopModule("my-module");
+```
+
+### `DestroyModule`
+
+Destroys a stopped module instance. The module code remains loaded.
+
+```ts
+await DestroyModule("my-module");
+```
+
+### `ReloadModule`
+
+Stops, destroys, unloads, and reloads a module from its source. This is useful for applying updates without restarting the application.
+
+```ts
+await ReloadModule("my-module");
+```
+
+## `ModuleDefinition`
+
+The configuration object for defining a module.
+
+| Property           | Type                              | Description                                        |
+| ------------------ | --------------------------------- | -------------------------------------------------- |
+| `source`           | `{ type: string } & Record<...>` | Source location and loading mechanism               |
+| `config`           | `unknown`                         | Optional configuration data for the module          |
+| `importOverrides`  | `Record<string, string[]>`        | Optional mapping of import paths to alternatives    |
+| `disabledExports`  | `string[]`                        | Optional list of exports to hide from this module   |
+
+## `ModuleInfo`
+
+Extends `ModuleDefinition` with runtime information.
+
+| Property    | Type     | Description                              |
+| ----------- | -------- | ---------------------------------------- |
+| `status`    | `string` | Current lifecycle state of the module    |
+| `localPath` | `string` | File system path where the module exists |
+
+## Next steps
+
+- [Logging](./6.logging.md) - Structured logging with channels and levels
+- [Configuration](./7.configuration.md) - Project configuration types

package/docs/6.logging.md

@@ -0,0 +1,106 @@
+# Logging
+
+## Overview
+
+The `@antelopejs/interface-core/logging` module provides a structured logging system with multiple severity levels and named channels. Log entries are emitted as events through an `EventProxy`, allowing any part of the application to listen for and process log output.
+
+## Import
+
+```ts
+import { Logging } from "@antelopejs/interface-core/logging";
+```
+
+## Severity levels
+
+The `Logging.Level` enum defines the available severity levels:
+
+| Level       | Value | Purpose                                      |
+| ----------- | ----- | -------------------------------------------- |
+| `ERROR`     | 40    | Critical errors that may cause failure       |
+| `WARN`      | 30    | Issues that do not prevent operation         |
+| `INFO`      | 20    | General status updates and information       |
+| `DEBUG`     | 10    | Detailed information for debugging           |
+| `TRACE`     | 0     | Highly detailed tracing information          |
+| `NO_PREFIX` | -1    | Messages displayed without a level prefix    |
+
+## Log to the main channel
+
+The `Logging` namespace exposes convenience functions that write to the `"main"` channel:
+
+```ts
+import { Logging } from "@antelopejs/interface-core/logging";
+
+Logging.Error("Database connection failed", error);
+Logging.Warn("Cache miss for key:", cacheKey);
+Logging.Info("Server started on port", port);
+Logging.Debug("Request payload:", payload);
+Logging.Trace("Entering function processItem");
+```
+
+Each function accepts any number of arguments of any type.
+
+## Use named channels
+
+For categorized logging, create a `Logging.Channel` instance with a channel name:
+
+```ts
+import { Logging } from "@antelopejs/interface-core/logging";
+
+const dbLog = new Logging.Channel("database");
+const httpLog = new Logging.Channel("http");
+
+dbLog.Info("Connected to", dbHost);
+dbLog.Error("Query failed:", query, error);
+
+httpLog.Info("GET /api/users", statusCode);
+httpLog.Debug("Response headers:", headers);
+```
+
+Channels provide the same methods as the main logging functions: `Error`, `Warn`, `Info`, `Debug`, and `Trace`.
+
+## Write at a custom level
+
+Use the `Write` function for logs at a custom severity level:
+
+```ts
+// Static function on the Logging namespace
+Logging.Write(25, "custom-channel", "Custom level message");
+
+// Instance method on a channel
+const channel = new Logging.Channel("metrics");
+channel.Write(15, "Custom level within the metrics channel");
+```
+
+## Log entry structure
+
+Each log entry emitted through the event system has the following structure:
+
+```ts
+interface Log {
+  time: number;      // Timestamp in milliseconds since epoch
+  channel: string;   // Channel name (e.g., "main", "database")
+  levelId: number;   // Numeric severity level
+  args: any[];       // The logged values
+}
+```
+
+## Listen for log events
+
+The logging system uses an `EventProxy` as its transport. Import the listener to register custom log handlers:
+
+```ts
+import eventLog from "@antelopejs/interface-core/logging/listener";
+
+eventLog.register((log) => {
+  const date = new Date(log.time).toISOString();
+  const level = log.levelId >= 40 ? "ERROR" : log.levelId >= 30 ? "WARN" : "INFO";
+  console.log(`[${date}] [${level}] [${log.channel}]`, ...log.args);
+});
+```
+
+The listener is module-aware. Handlers registered by a module are automatically removed when that module is unloaded.
+
+## Next steps
+
+- [Configuration](./7.configuration.md) - Project configuration with logging settings
+- [Proxies](./2.proxies.md) - Understand the `EventProxy` that powers the logging transport