Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .git-blame-ignore-revs
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Formatted with oxfmt when the repository moved off Biome.
3fe82af4730f9132bb94294a7b64a9ce30e04d83
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -26,5 +26,7 @@ jobs:
echo "$PR_TITLE" | grep -Eq '^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([^)]+\))?!?: .+'
- run: pnpm install --frozen-lockfile
- run: pnpm lint
- run: pnpm format:check
- run: pnpm knip
- run: pnpm test
- run: pnpm test:package
8 changes: 4 additions & 4 deletions .github/workflows/stale.yml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
name: 'Close stale issues'
name: "Close stale issues"

on:
schedule:
- cron: '30 * * * *'
- cron: "30 * * * *"
workflow_dispatch:

permissions:
Expand All @@ -17,8 +17,8 @@ jobs:
- uses: actions/stale@v9
with:
exempt-issue-labels: pending
stale-issue-message: 'This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 30 days.'
close-issue-message: 'This issue was closed because it has been stalled for 30 days with no activity.'
stale-issue-message: "This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 30 days."
close-issue-message: "This issue was closed because it has been stalled for 30 days with no activity."
days-before-stale: 60
days-before-close: 30
operations-per-run: 200
Expand Down
18 changes: 9 additions & 9 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
| --------------------- | --------------------------------------------------------------------------------------- |
| English only | All code must be in English: variable names, function names, comments |
| PNPM only | Always use pnpm, never npm or yarn |
| NO COMMENTS | Code must be self-documenting through clear naming. TSDoc is allowed for public APIs |
| NO COMMENTS | Code must be self-documenting through clear naming. TSDoc is allowed for public APIs |
| NO switch/case | Use objects, maps, or arrays instead |
| NO inline types | Define proper interfaces/types, never use anonymous types like `{a: string, b: number}` |
| Functions ≤ 40 lines | Split into subfunctions if longer |
Expand All @@ -35,23 +35,23 @@ Never use `switch/case` or `if param === 'XXX'` chains. Instead:
// BAD
function getStatus(code: string) {
switch (code) {
case 'A':
return 'Active';
case 'I':
return 'Inactive';
case "A":
return "Active";
case "I":
return "Inactive";
default:
return 'Unknown';
return "Unknown";
}
}

// GOOD
const STATUS_MAP: Record<string, string> = {
A: 'Active',
I: 'Inactive',
A: "Active",
I: "Inactive",
};

function getStatus(code: string) {
return STATUS_MAP[code] ?? 'Unknown';
return STATUS_MAP[code] ?? "Unknown";
}
```

Expand Down
2 changes: 0 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,12 +146,10 @@

## v0.0.2


### 🏡 Chore

- Initial commit ([3fa476d](https://github.com/AntelopeJS/interface-core/commit/3fa476d))

### ❤️ Contributors

- Antony Rizzitelli <upd4ting@gmail.com>

56 changes: 0 additions & 56 deletions biome.json

This file was deleted.

17 changes: 14 additions & 3 deletions docs/1.introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,24 @@ The package exposes several entry points:

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

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

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

// Logging system
import { Logging } from "@antelopejs/interface-core/logging";
Expand Down
24 changes: 19 additions & 5 deletions docs/2.proxies.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,8 @@ Manually removes the attached callback. After detaching, subsequent calls are qu
import { InterfaceFunction } from "@antelopejs/interface-core";

// Declare a typed interface function
const GetUser = InterfaceFunction<(id: string) => { name: string; email: string }>();
const GetUser =
InterfaceFunction<(id: string) => { name: string; email: string }>();

// Call it like a regular async function
const user = await GetUser("user-123");
Expand Down Expand Up @@ -106,7 +107,9 @@ Removes a specific handler by function reference.
```ts
import { RegisteringProxy } from "@antelopejs/interface-core";

const routeRegistry = new RegisteringProxy<(id: string, path: string, handler: Function) => void>();
const routeRegistry = new RegisteringProxy<
(id: string, path: string, handler: Function) => void
>();

// Register entries - queued if no callback is attached yet
routeRegistry.register("home", "/", homeHandler);
Expand Down Expand Up @@ -154,7 +157,12 @@ Manually removes both the register and unregister callbacks. Registered entries
`ImplementInterface` connects an interface declaration to its implementation. It iterates over the declaration object and wires up each proxy to the corresponding implementation function.

```ts
import { InterfaceFunction, EventProxy, RegisteringProxy, ImplementInterface } from "@antelopejs/interface-core";
import {
InterfaceFunction,
EventProxy,
RegisteringProxy,
ImplementInterface,
} from "@antelopejs/interface-core";

// Declaration
const GetItem = InterfaceFunction<(id: string) => { name: string }>();
Expand Down Expand Up @@ -188,7 +196,10 @@ In test stub mode, using a proxy that has no provider attached fails with a `Mis
This error is the supported way to detect the "no provider" condition. The contract is the type and its stable `code` property (`"ERR_NO_PROVIDER"`, exported as `MISSING_PROVIDER_CODE`) - never the message text, which may change between versions.

```ts
import { isMissingProviderError, MissingProviderError } from "@antelopejs/interface-core";
import {
isMissingProviderError,
MissingProviderError,
} from "@antelopejs/interface-core";

try {
registry.register("my-entry", data);
Expand All @@ -205,7 +216,10 @@ Prefer the `isMissingProviderError` guard over `instanceof`: it checks the `code
These functions retrieve information about active interface connections for the current module.

```ts
import { GetInterfaceInstances, GetInterfaceInstance } from "@antelopejs/interface-core";
import {
GetInterfaceInstances,
GetInterfaceInstance,
} from "@antelopejs/interface-core";

// Get all connections for an interface
const connections = GetInterfaceInstances("database");
Expand Down
52 changes: 32 additions & 20 deletions docs/3.decorators.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,11 +54,13 @@ Creates a decorator factory that targets properties. The handler receives the ta
```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);
});
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")
Expand All @@ -74,7 +76,12 @@ Creates a decorator factory that targets methods and accessors. The handler rece
import { MakeMethodDecorator } from "@antelopejs/interface-core/decorators";

const Log = MakeMethodDecorator(
(target: any, key: PropertyKey, descriptor: PropertyDescriptor, level: string) => {
(
target: any,
key: PropertyKey,
descriptor: PropertyDescriptor,
level: string,
) => {
const original = descriptor.value;
descriptor.value = function (...args: any[]) {
console.log(`[${level}] Calling ${String(key)}`);
Expand Down Expand Up @@ -117,27 +124,32 @@ class Controller {

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 |
| 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) => {
(
target: any,
key: PropertyKey | undefined,
descriptor: PropertyDescriptor | undefined,
category: string,
) => {
if (descriptor) {
// Applied to a method
const original = descriptor.value;
Expand Down
14 changes: 9 additions & 5 deletions docs/4.metadata.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,16 +13,20 @@ import { GetMetadata } from "@antelopejs/interface-core";
## `GetMetadata`

```ts
function GetMetadata<T, U>(target: U, meta: Class<T, [U]> & { key: symbol }, inherit?: boolean): T
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 |
| 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 |
| `inherit` | `boolean` | `true` | Whether to inherit metadata from the prototype chain |

### Return value

Expand Down
24 changes: 12 additions & 12 deletions docs/5.modules.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,12 +28,12 @@ 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 |
| 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 |

## Module execution context

Expand Down Expand Up @@ -180,12 +180,12 @@ await ReloadModule("my-module");

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 |
| 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`

Expand Down
Loading
Loading