@fluojs/core 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,165 @@
+# @fluojs/core
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+모든 fluo 패키지가 공통으로 사용하는 표준 데코레이터, 공유 계약, 메타데이터 프리미티브를 제공하는 기반 패키지입니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [주요 기능](#주요-기능)
+- [문제 해결](#문제-해결)
+- [공개 API](#공개-api)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+npm install @fluojs/core
+```
+
+## 사용 시점
+
+- 표준 데코레이터로 모듈, 프로바이더, 컨트롤러를 선언할 때
+- fluo 모듈 그래프에 참여하는 프레임워크 확장이나 내부 라이브러리를 만들 때
+- `Constructor<T>`, `Token<T>`, 프레임워크 공통 에러 같은 기본 타입과 계약을 직접 다뤄야 할 때
+
+## 빠른 시작
+
+모든 fluo 애플리케이션은 `@fluojs/core`가 기록하는 모듈 메타데이터에서 시작합니다.
+
+```ts
+import { Global, Inject, Module, Scope } from '@fluojs/core';
+
+@Global()
+@Module({
+  providers: [DatabaseService],
+  exports: [DatabaseService],
+})
+class CoreModule {}
+
+@Module({
+  imports: [CoreModule],
+  providers: [UserService],
+})
+class AppModule {}
+
+@Inject(DatabaseService)
+@Scope('singleton')
+class UserService {
+  constructor(private readonly db: DatabaseService) {}
+}
+```
+
+## 주요 기능
+
+### TC39 데코레이터를 사용하는 표준 데코레이터
+
+fluo는 TC39 표준 데코레이터를 사용하므로 `experimentalDecorators: true`나 `emitDecoratorMetadata: true`에 의존하지 않습니다.
+
+### 명시적인 의존성 메타데이터
+
+`@Inject(...)`는 리플렉션 기반 추론 대신 코드 안에서 의존성 토큰을 직접 드러냅니다. 상속된 constructor 토큰을 명시적으로 비우려면 `@Inject()`를 사용하면 됩니다.
+
+```ts
+const CONFIG_TOKEN = Symbol('CONFIG_TOKEN');
+
+@Inject(CONFIG_TOKEN)
+class UsesConfigValue {
+  constructor(private readonly config: Config) {}
+}
+```
+
+여러 토큰을 지정할 때는 `@Inject(A, B)`처럼 variadic 호출을 사용하면 됩니다.
+
+### 형제 패키지를 위한 공용 메타데이터 헬퍼
+
+내부 메타데이터 reader/writer는 `@fluojs/core/internal` 아래에 있으며, `@fluojs/di`, `@fluojs/http`, `@fluojs/runtime` 같은 패키지들이 같은 메타데이터 모델을 공유할 수 있게 합니다.
+
+```ts
+import { getModuleMetadata } from '@fluojs/core/internal';
+
+const metadata = getModuleMetadata(AppModule);
+console.log(metadata.providers);
+```
+
+### 동적 설정을 위한 AsyncModuleOptions
+
+`AsyncModuleOptions<T>`는 외부 `ConfigService` 등에 의존하여 비동기적으로 초기화가 필요한 모듈을 위한 표준 계약입니다.
+
+```ts
+import { AsyncModuleOptions, MaybePromise, Token } from '@fluojs/core';
+
+interface Config {
+  apiKey: string;
+}
+
+class EmailModule {
+  static forRootAsync(options: AsyncModuleOptions<Config>) {
+    return {
+      module: EmailModule,
+      providers: [
+        {
+          provide: 'CONFIG',
+          useFactory: options.useFactory,
+          inject: options.inject,
+        },
+      ],
+    };
+  }
+}
+```
+
+### @Scope를 이용한 생명주기 제어
+
+`@Scope` 데코레이터는 프로바이더 인스턴스의 생존 범위를 결정합니다. fluo는 세 가지 스코프를 지원합니다.
+
+- `singleton` (기본값): 애플리케이션 전체에서 단 하나의 인스턴스를 공유합니다.
+- `request`: 각 HTTP 요청마다 새로운 인스턴스를 생성합니다.
+- `transient`: 주입될 때마다 매번 새로운 인스턴스를 생성합니다.
+
+```ts
+import { Scope } from '@fluojs/core';
+
+@Scope('request')
+class TransactionContext {}
+
+@Scope('transient')
+class Logger {}
+```
+
+## 문제 해결
+
+### 데코레이터 메타데이터를 찾을 수 없음
+
+표준 TC39 데코레이터를 사용하고 있는지 확인하세요. fluo는 `reflect-metadata`를 사용하지 않습니다. NestJS에서 전환하는 경우, `tsconfig.json`에서 `experimentalDecorators`와 `emitDecoratorMetadata` 설정을 제거하여 표준 데코레이터 동작과 충돌하지 않도록 하세요.
+
+### 모듈 간 순환 참조
+
+두 모듈이 서로를 import하면 모듈 그래프를 컴파일할 수 없습니다. 공통 의존성을 담은 "Common"이나 "Core" 모듈을 만들어 분리하거나, 공유 로직을 별도 패키지로 추출하세요.
+
+### 추상 클래스에 대한 @Inject 누락
+
+표준 데코레이터는 추상 클래스나 인터페이스의 타입을 자동으로 추론할 수 없습니다. 구체적인 클래스 생성자가 아닌 대상을 주입할 때는 반드시 `@Inject(TOKEN)`을 사용하세요.
+
+## 공개 API
+
+- **데코레이터**: `Module`, `Global`, `Inject`, `Scope`
+- **에러**: `FluoError`, `InvariantError`, `FluoCodeError`
+- **타입**: `Constructor<T>`, `Token<T>`, `MaybePromise<T>`, `AsyncModuleOptions`
+- **내부 서브패스**: `@fluojs/core/internal`을 통한 메타데이터 헬퍼
+
+## 관련 패키지
+
+- `@fluojs/di`: 여기서 선언된 토큰과 스코프를 실제 인스턴스로 해석합니다.
+- `@fluojs/runtime`: `@Module` 메타데이터로 모듈 그래프를 컴파일합니다.
+- `@fluojs/http`: 동일한 메타데이터 프리미티브 위에서 컨트롤러와 라우트 정보를 읽습니다.
+
+## 예제 소스
+
+- `packages/core/src/index.ts`
+- `packages/core/src/decorators.ts`
+- `packages/core/src/metadata.ts`

package/README.md

@@ -0,0 +1,167 @@
+# @fluojs/core
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+Shared contracts, standard decorators, and metadata primitives that every fluo package builds on.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to Use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Key Capabilities](#key-capabilities)
+- [Troubleshooting](#troubleshooting)
+- [Public API](#public-api)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+npm install @fluojs/core
+```
+
+## When to Use
+
+Use this package when you are:
+
+- defining modules, providers, or controllers with fluo's standard decorators
+- building framework extensions that need to participate in the module graph
+- working with shared framework errors, tokens, or constructor-based utility types
+
+## Quick Start
+
+Every fluo application starts with module metadata declared through `@fluojs/core`.
+
+```ts
+import { Global, Inject, Module, Scope } from '@fluojs/core';
+
+@Global()
+@Module({
+  providers: [DatabaseService],
+  exports: [DatabaseService],
+})
+class CoreModule {}
+
+@Module({
+  imports: [CoreModule],
+  providers: [UserService],
+})
+class AppModule {}
+
+@Inject(DatabaseService)
+@Scope('singleton')
+class UserService {
+  constructor(private readonly db: DatabaseService) {}
+}
+```
+
+## Key Capabilities
+
+### Standard decorators with TC39 decorator support
+
+fluo uses TC39 standard decorators. You do not need `experimentalDecorators: true` or `emitDecoratorMetadata: true` to use `@Module`, `@Inject`, `@Global`, or `@Scope`.
+
+### Explicit dependency metadata
+
+`@Inject(...)` keeps dependency wiring visible in code instead of relying on emitted reflection metadata. Call `@Inject()` when you want to record an explicit empty override for inherited constructor tokens.
+
+```ts
+const CONFIG_TOKEN = Symbol('CONFIG_TOKEN');
+
+@Inject(CONFIG_TOKEN)
+class UsesConfigValue {
+  constructor(private readonly config: Config) {}
+}
+```
+
+Pass multiple tokens as variadic arguments such as `@Inject(A, B)`.
+
+### Shared metadata helpers for sibling packages
+
+Internal readers and writers live under `@fluojs/core/internal`, which is how packages like `@fluojs/di`, `@fluojs/http`, and `@fluojs/runtime` consume the same metadata model.
+
+```ts
+import { getModuleMetadata } from '@fluojs/core/internal';
+
+const metadata = getModuleMetadata(AppModule);
+console.log(metadata.providers);
+```
+
+### AsyncModuleOptions for dynamic configuration
+
+`AsyncModuleOptions<T>` is the standard contract for modules that require asynchronous initialization, such as those relying on an external `ConfigService`.
+
+```ts
+import { AsyncModuleOptions, MaybePromise, Token } from '@fluojs/core';
+
+interface Config {
+  apiKey: string;
+}
+
+class EmailModule {
+  static forRootAsync(options: AsyncModuleOptions<Config>) {
+    return {
+      module: EmailModule,
+      providers: [
+        {
+          provide: 'CONFIG',
+          useFactory: options.useFactory,
+          inject: options.inject,
+        },
+      ],
+    };
+  }
+}
+```
+
+### Lifecycle scopes with @Scope
+
+The `@Scope` decorator controls the lifetime of a provider instance. fluo supports three distinct levels:
+
+- `singleton` (default): A single instance is shared across the entire application.
+- `request`: A new instance is created for every incoming HTTP request.
+- `transient`: A new instance is created every time it is injected into a consumer.
+
+```ts
+import { Scope } from '@fluojs/core';
+
+@Scope('request')
+class TransactionContext {}
+
+@Scope('transient')
+class Logger {}
+```
+
+## Troubleshooting
+
+### Decorator metadata not found
+
+Ensure you are using standard TC39 decorators. fluo does not use `reflect-metadata`. If you are migrating from NestJS, remove `experimentalDecorators` and `emitDecoratorMetadata` from your `tsconfig.json` to prevent conflicts with standard decorator behavior.
+
+### Circular dependencies in modules
+
+If two modules import each other, the module graph cannot be compiled. Use a shared "Common" or "Core" module to house providers that both modules depend on, or refactor the shared logic into a separate package.
+
+### Missing @Inject for abstract classes
+
+Standard decorators cannot automatically infer types for abstract classes or interfaces. Always use `@Inject(TOKEN)` when injecting anything that is not a concrete class constructor.
+
+## Public API
+
+- **Decorators**: `Module`, `Global`, `Inject`, `Scope`
+- **Errors**: `FluoError`, `InvariantError`, `FluoCodeError`
+- **Types**: `Constructor<T>`, `Token<T>`, `MaybePromise<T>`, `AsyncModuleOptions`
+- **Internal subpath**: metadata helpers via `@fluojs/core/internal`
+
+## Related Packages
+
+- `@fluojs/di`: resolves the tokens and scopes defined here into live instances
+- `@fluojs/runtime`: compiles the module graph from `@Module` metadata
+- `@fluojs/http`: consumes controller and route metadata built on the same primitives
+
+## Example Sources
+
+- `packages/core/src/index.ts`
+- `packages/core/src/decorators.ts`
+- `packages/core/src/metadata.ts`

package/dist/decorators.d.ts

@@ -0,0 +1,51 @@
+import { type ClassDiMetadata, type ModuleMetadata } from './metadata.js';
+import type { Token } from './types.js';
+type StandardClassDecoratorFn = (value: Function, context: ClassDecoratorContext) => void;
+type TupleOnly<T extends readonly unknown[]> = number extends T['length'] ? never : T;
+/**
+ * Declares module-level metadata (`imports`, `providers`, `controllers`, `exports`, `global`) on a class.
+ *
+ * @param definition Module composition metadata consumed by the runtime module-graph compiler.
+ * @returns A standard class decorator that records the module contract on the target class.
+ */
+export declare function Module(definition: ModuleMetadata): StandardClassDecoratorFn;
+/**
+ * Marks the decorated module as global so its exported providers are visible without explicit imports.
+ *
+ * @returns A standard class decorator that marks the target module as globally visible.
+ */
+export declare function Global(): StandardClassDecoratorFn;
+/**
+ * Defines explicit constructor injection tokens for the decorated class.
+ *
+ * Passing tokens variadically (`@Inject(A, B)`) is the canonical API. Calling `@Inject()` records an
+ * explicit empty inject list so subclasses can intentionally clear inherited constructor tokens.
+ * During the staged migration window, the legacy array form (`@Inject([A, B])`) is still normalized.
+ *
+ * @param tokens Constructor-parameter token list used by `@fluojs/di` during dependency resolution.
+ * @returns A standard class decorator that stores explicit injection metadata on the target class.
+ */
+export declare function Inject(): StandardClassDecoratorFn;
+/**
+ * Defines explicit constructor injection tokens for the decorated class.
+ *
+ * @param tokens Constructor-parameter token list used by `@fluojs/di` during dependency resolution.
+ * @returns A standard class decorator that stores explicit injection metadata on the target class.
+ */
+export declare function Inject<const TTokens extends readonly Token[]>(...tokens: TupleOnly<TTokens>): StandardClassDecoratorFn;
+/**
+ * Defines explicit constructor injection tokens for the decorated class.
+ *
+ * @param tokens Constructor-parameter token list used by `@fluojs/di` during dependency resolution.
+ * @returns A standard class decorator that stores explicit injection metadata on the target class.
+ */
+export declare function Inject(tokens: readonly Token[]): StandardClassDecoratorFn;
+/**
+ * Sets the provider lifecycle scope used by the DI container.
+ *
+ * @param scope Provider lifetime strategy (`singleton`, `request`, or `transient`).
+ * @returns A standard class decorator that stores scope metadata on the target class.
+ */
+export declare function Scope(scope: NonNullable<ClassDiMetadata['scope']>): StandardClassDecoratorFn;
+export {};
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,KAAK,wBAAwB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAE1F,KAAK,SAAS,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,IAAI,MAAM,SAAS,CAAC,CAAC,QAAQ,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;AAEtF;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,UAAU,EAAE,cAAc,GAAG,wBAAwB,CAI3E;AAED;;;;GAIG;AACH,wBAAgB,MAAM,IAAI,wBAAwB,CAIjD;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,IAAI,wBAAwB,CAAC;AACnD;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,KAAK,CAAC,OAAO,SAAS,SAAS,KAAK,EAAE,EAC3D,GAAG,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,GAC5B,wBAAwB,CAAC;AAC5B;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,wBAAwB,CAAC;AAiB3E;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,WAAW,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,GAAG,wBAAwB,CAI5F"}

package/dist/decorators.js

@@ -0,0 +1,79 @@
+import { defineClassDiMetadata, defineModuleMetadata } from './metadata.js';
+/**
+ * Declares module-level metadata (`imports`, `providers`, `controllers`, `exports`, `global`) on a class.
+ *
+ * @param definition Module composition metadata consumed by the runtime module-graph compiler.
+ * @returns A standard class decorator that records the module contract on the target class.
+ */
+export function Module(definition) {
+  return target => {
+    defineModuleMetadata(target, definition);
+  };
+}
+
+/**
+ * Marks the decorated module as global so its exported providers are visible without explicit imports.
+ *
+ * @returns A standard class decorator that marks the target module as globally visible.
+ */
+export function Global() {
+  return target => {
+    defineModuleMetadata(target, {
+      global: true
+    });
+  };
+}
+
+/**
+ * Defines explicit constructor injection tokens for the decorated class.
+ *
+ * Passing tokens variadically (`@Inject(A, B)`) is the canonical API. Calling `@Inject()` records an
+ * explicit empty inject list so subclasses can intentionally clear inherited constructor tokens.
+ * During the staged migration window, the legacy array form (`@Inject([A, B])`) is still normalized.
+ *
+ * @param tokens Constructor-parameter token list used by `@fluojs/di` during dependency resolution.
+ * @returns A standard class decorator that stores explicit injection metadata on the target class.
+ */
+
+/**
+ * Defines explicit constructor injection tokens for the decorated class.
+ *
+ * @param tokens Constructor-parameter token list used by `@fluojs/di` during dependency resolution.
+ * @returns A standard class decorator that stores explicit injection metadata on the target class.
+ */
+
+/**
+ * Defines explicit constructor injection tokens for the decorated class.
+ *
+ * @param tokens Constructor-parameter token list used by `@fluojs/di` during dependency resolution.
+ * @returns A standard class decorator that stores explicit injection metadata on the target class.
+ */
+
+/**
+ * Defines explicit constructor injection tokens for the decorated class.
+ *
+ * @param tokensOrList Constructor-parameter token list used by `@fluojs/di` during dependency resolution.
+ * @returns A standard class decorator that stores explicit injection metadata on the target class.
+ */
+export function Inject(...tokensOrList) {
+  const tokens = tokensOrList.length === 1 && Array.isArray(tokensOrList[0]) ? [...tokensOrList[0]] : [...tokensOrList];
+  return target => {
+    defineClassDiMetadata(target, {
+      inject: [...tokens]
+    });
+  };
+}
+
+/**
+ * Sets the provider lifecycle scope used by the DI container.
+ *
+ * @param scope Provider lifetime strategy (`singleton`, `request`, or `transient`).
+ * @returns A standard class decorator that stores scope metadata on the target class.
+ */
+export function Scope(scope) {
+  return target => {
+    defineClassDiMetadata(target, {
+      scope
+    });
+  };
+}

package/dist/errors.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Options for creating a {@link FluoError}.
+ */
+export interface FluoErrorOptions {
+    /** Stable error code for programmatic identification. */
+    code?: string;
+    /** Original error that caused this failure. */
+    cause?: unknown;
+    /** Additional structured metadata for diagnostics. */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Base error class for all fluo framework errors.
+ */
+export declare class FluoError extends Error {
+    /** Stable error code. */
+    readonly code: string;
+    /** Additional structured metadata. */
+    readonly meta?: Record<string, unknown>;
+    /**
+     * Creates a new FluoError.
+     *
+     * @param message Human-readable error message.
+     * @param options Optional error configuration including `code`, `cause`, and `meta`.
+     */
+    constructor(message: string, options?: FluoErrorOptions);
+}
+/**
+ * Error thrown when a system invariant is violated.
+ */
+export declare class InvariantError extends FluoError {
+    /**
+     * Creates an invariant error.
+     *
+     * @param message Human-readable description of the violation.
+     * @param options Optional error configuration.
+     */
+    constructor(message: string, options?: Omit<FluoErrorOptions, 'code'>);
+}
+/**
+ * Abstract base class for errors that require a specific error code.
+ */
+export declare abstract class FluoCodeError extends FluoError {
+    /**
+     * Creates a code-specific error.
+     *
+     * @param message Human-readable error message.
+     * @param code Programmatic error code.
+     * @param options Optional error configuration.
+     */
+    constructor(message: string, code: string, options?: Omit<FluoErrorOptions, 'code'>);
+}
+/**
+ * Formats a DI token into a human-readable string for error messages.
+ *
+ * @param token The token to format.
+ * @returns A string representation of the token.
+ */
+export declare function formatTokenName(token: unknown): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,yBAAyB;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAExC;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB;CAgB5D;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,SAAS;IAC3C;;;;;OAKG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAM;CAG1E;AAED;;GAEG;AACH,8BAAsB,aAAc,SAAQ,SAAS;IACnD;;;;;;OAMG;gBACS,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAM;CAGxF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUtD"}

package/dist/errors.js

@@ -0,0 +1,89 @@
+/**
+ * Options for creating a {@link FluoError}.
+ */
+
+/**
+ * Base error class for all fluo framework errors.
+ */
+export class FluoError extends Error {
+  /** Stable error code. */
+  code;
+  /** Additional structured metadata. */
+  meta;
+
+  /**
+   * Creates a new FluoError.
+   *
+   * @param message Human-readable error message.
+   * @param options Optional error configuration including `code`, `cause`, and `meta`.
+   */
+  constructor(message, options = {}) {
+    super(message, options.cause instanceof Error ? {
+      cause: options.cause
+    } : undefined);
+    this.name = new.target.name;
+    this.code = options.code ?? 'FLUO_ERROR';
+    this.meta = options.meta;
+    if (!(options.cause instanceof Error) && options.cause !== undefined) {
+      Object.defineProperty(this, 'cause', {
+        configurable: true,
+        enumerable: false,
+        value: options.cause,
+        writable: true
+      });
+    }
+  }
+}
+
+/**
+ * Error thrown when a system invariant is violated.
+ */
+export class InvariantError extends FluoError {
+  /**
+   * Creates an invariant error.
+   *
+   * @param message Human-readable description of the violation.
+   * @param options Optional error configuration.
+   */
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      code: 'INVARIANT_ERROR'
+    });
+  }
+}
+
+/**
+ * Abstract base class for errors that require a specific error code.
+ */
+export class FluoCodeError extends FluoError {
+  /**
+   * Creates a code-specific error.
+   *
+   * @param message Human-readable error message.
+   * @param code Programmatic error code.
+   * @param options Optional error configuration.
+   */
+  constructor(message, code, options = {}) {
+    super(message, {
+      ...options,
+      code
+    });
+  }
+}
+
+/**
+ * Formats a DI token into a human-readable string for error messages.
+ *
+ * @param token The token to format.
+ * @returns A string representation of the token.
+ */
+export function formatTokenName(token) {
+  if (typeof token === 'function' && 'name' in token && token.name) {
+    return String(token.name);
+  }
+  if (typeof token === 'symbol') {
+    return token.toString();
+  }
+  return String(token);
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Global, Inject, Module, Scope } from './decorators.js';
+export { InvariantError, FluoCodeError, FluoError, formatTokenName, type FluoErrorOptions } from './errors.js';
+export { ensureMetadataSymbol } from './metadata.js';
+export type { AsyncModuleOptions, Constructor, MaybePromise, MetadataPropertyKey, MetadataSource, Token } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,SAAS,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/G,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,YAAY,EAAE,kBAAkB,EAAE,WAAW,EAAE,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Global, Inject, Module, Scope } from './decorators.js';
+export { InvariantError, FluoCodeError, FluoError, formatTokenName } from './errors.js';
+export { ensureMetadataSymbol } from './metadata.js';

package/dist/internal.d.ts

@@ -0,0 +1,3 @@
+export * from './metadata.js';
+export { cloneWithFallback, fallbackClone } from './utils.js';
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/dist/internal.js

@@ -0,0 +1,2 @@
+export * from './metadata.js';
+export { cloneWithFallback, fallbackClone } from './utils.js';