@fluojs/core 1.0.0-beta.1 → 1.0.0-beta.2

package/README.ko.md

@@ -60,6 +60,14 @@ class UserService {
 
 fluo는 TC39 표준 데코레이터를 사용하므로 `experimentalDecorators: true`나 `emitDecoratorMetadata: true`에 의존하지 않습니다.
 
+core 메타데이터는 fluo가 소유한 저장소와 TC39 `Symbol.metadata` 통합 지점을 통해 기록되며, `reflect-metadata`나 컴파일러가 생성하는 design type 메타데이터를 사용하지 않습니다. 런타임이 사용자 정의 표준 데코레이터를 평가하기 전에 `Symbol.metadata` 폴리필을 설치해야 한다면 테스트나 부트스트랩 경계에서 `ensureMetadataSymbol()`을 호출하세요.
+
+```ts
+import { ensureMetadataSymbol } from '@fluojs/core';
+
+ensureMetadataSymbol();
+```
+
 ### 명시적인 의존성 메타데이터
 
 `@Inject(...)`는 리플렉션 기반 추론 대신 코드 안에서 의존성 토큰을 직접 드러냅니다. 상속된 constructor 토큰을 명시적으로 비우려면 `@Inject()`를 사용하면 됩니다.
@@ -75,10 +83,14 @@ class UsesConfigValue {
 
 여러 토큰을 지정할 때는 `@Inject(A, B)`처럼 variadic 호출을 사용하면 됩니다.
 
+마이그레이션 기간 동안 legacy 배열 형식인 `@Inject([A, B])`도 계속 정규화되지만, 새 코드는 constructor 토큰을 표준 데코레이터 사용 방식과 맞추기 위해 variadic 형식을 권장합니다.
+
 ### 형제 패키지를 위한 공용 메타데이터 헬퍼
 
 내부 메타데이터 reader/writer는 `@fluojs/core/internal` 아래에 있으며, `@fluojs/di`, `@fluojs/http`, `@fluojs/runtime` 같은 패키지들이 같은 메타데이터 모델을 공유할 수 있게 합니다.
 
+애플리케이션 코드는 공개 데코레이터와 `ensureMetadataSymbol()`을 `@fluojs/core`에서 import해야 합니다. `@fluojs/core/internal` 서브패스는 메타데이터 레코드를 읽거나, 명시적 저장소와 `Symbol.metadata`를 병합하거나, 프레임워크 수준 데코레이터를 만드는 fluo 패키지를 위한 경로입니다. 표준 metadata bag helper는 current/native `Symbol.metadata`와 fallback symbol이 섞인 lookup을 처리합니다. 어느 era에서 온 own metadata든 같은 key에 대해서는 어느 era에서 온 inherited metadata보다 우선하지만, child가 다른 key만 소유한 경우 parent constructor의 inherited key는 계속 보입니다. DI와 모듈 그래프 hot path의 allocation을 줄이기 위해 `getModuleMetadata()`, `getOwnClassDiMetadata()`, `getInheritedClassDiMetadata()`, `getClassDiMetadata()`는 frozen snapshot을 반환하며 write 사이에는 같은 reference를 재사용할 수 있습니다. 이 결과, collection 필드, module provider descriptor wrapper와 middleware route-config wrapper(그 안의 `routes` 배열 포함)는 immutable로 취급해야 합니다. `useValue` payload 객체와 runtime middleware/guard/interceptor instance는 mutable reference로 유지되며 이 snapshot 때문에 freeze되지 않습니다. 다른 metadata reader는 각 reader의 테스트가 stable-reference 재사용을 문서화하지 않는 한 기존 defensive-read 동작을 유지합니다.
+
 ```ts
 import { getModuleMetadata } from '@fluojs/core/internal';
 
@@ -149,6 +161,7 @@ class Logger {}
 
 - **데코레이터**: `Module`, `Global`, `Inject`, `Scope`
 - **에러**: `FluoError`, `InvariantError`, `FluoCodeError`
+- **메타데이터 런타임**: `ensureMetadataSymbol`
 - **타입**: `Constructor<T>`, `Token<T>`, `MaybePromise<T>`, `AsyncModuleOptions`
 - **내부 서브패스**: `@fluojs/core/internal`을 통한 메타데이터 헬퍼
 

package/README.md

@@ -62,6 +62,14 @@ class UserService {
 
 fluo uses TC39 standard decorators. You do not need `experimentalDecorators: true` or `emitDecoratorMetadata: true` to use `@Module`, `@Inject`, `@Global`, or `@Scope`.
 
+Core metadata is written through fluo-owned stores and TC39 `Symbol.metadata` integration points, never through `reflect-metadata` or compiler-emitted design types. Call `ensureMetadataSymbol()` at test or bootstrap boundaries when a runtime needs the `Symbol.metadata` polyfill installed before evaluating custom standard decorators.
+
+```ts
+import { ensureMetadataSymbol } from '@fluojs/core';
+
+ensureMetadataSymbol();
+```
+
 ### 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.
@@ -77,10 +85,14 @@ class UsesConfigValue {
 
 Pass multiple tokens as variadic arguments such as `@Inject(A, B)`.
 
+The legacy array form `@Inject([A, B])` remains normalized during the migration window, but new code should prefer the variadic form so constructor tokens stay aligned with standard decorator usage.
+
 ### 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.
 
+Application code should import public decorators and `ensureMetadataSymbol()` from `@fluojs/core`. The `@fluojs/core/internal` subpath is reserved for fluo packages that need to read metadata records, merge explicit stores with `Symbol.metadata`, or build framework-level decorators. Standard metadata bag helpers handle mixed-era lookups across current/native `Symbol.metadata` and the fallback symbol: own metadata from either era overrides inherited metadata from either era for the same key, while inherited keys from parent constructors remain visible when the child owns a different key. To reduce DI and module-graph hot-path allocations, `getModuleMetadata()`, `getOwnClassDiMetadata()`, `getInheritedClassDiMetadata()`, and `getClassDiMetadata()` return frozen snapshots and may reuse the same reference between writes. Treat those results, their collection fields, and module provider descriptor wrappers, and middleware route-config wrappers (including their `routes` arrays) as immutable. `useValue` payload objects and runtime middleware/guard/interceptor instances remain mutable references and are not frozen by these snapshots. Other metadata readers keep their existing defensive-read behavior unless their own tests document stable-reference reuse.
+
 ```ts
 import { getModuleMetadata } from '@fluojs/core/internal';
 
@@ -151,6 +163,7 @@ Standard decorators cannot automatically infer types for abstract classes or int
 
 - **Decorators**: `Module`, `Global`, `Inject`, `Scope`
 - **Errors**: `FluoError`, `InvariantError`, `FluoCodeError`
+- **Metadata runtime**: `ensureMetadataSymbol`
 - **Types**: `Constructor<T>`, `Token<T>`, `MaybePromise<T>`, `AsyncModuleOptions`
 - **Internal subpath**: metadata helpers via `@fluojs/core/internal`
 

package/dist/metadata/class-di.d.ts

@@ -10,7 +10,7 @@ export declare function defineClassDiMetadata(target: Function, metadata: ClassD
  * Reads only the DI metadata defined directly on a class.
  *
  * @param target Class being inspected.
- * @returns A defensive clone of the class's own DI metadata, or `undefined` when absent.
+ * @returns A frozen class DI metadata snapshot, or `undefined` when absent.
  */
 export declare function getOwnClassDiMetadata(target: Function): ClassDiMetadata | undefined;
 /**

package/dist/metadata/class-di.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"class-di.d.ts","sourceRoot":"","sources":["../../src/metadata/class-di.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAyBlD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAKvF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,GAAG,eAAe,GAAG,SAAS,CAEnF;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,QAAQ,GAAG,eAAe,GAAG,SAAS,CAiBzF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,QAAQ,GAAG,eAAe,GAAG,SAAS,CAEhF"}
+{"version":3,"file":"class-di.d.ts","sourceRoot":"","sources":["../../src/metadata/class-di.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AA2BlD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAQvF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,GAAG,eAAe,GAAG,SAAS,CAEnF;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,QAAQ,GAAG,eAAe,GAAG,SAAS,CA4BzF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,QAAQ,GAAG,eAAe,GAAG,SAAS,CAEhF"}

package/dist/metadata/class-di.js

@@ -1,10 +1,11 @@
-import { createClonedWeakMapStore } from './store.js';
-const classDiMetadataStore = createClonedWeakMapStore(cloneClassDiMetadata);
-function cloneClassDiMetadata(metadata) {
-  return {
-    inject: metadata.inject ? [...metadata.inject] : undefined,
+const classDiMetadataStore = new WeakMap();
+const inheritedClassDiMetadataCache = new WeakMap();
+let classDiMetadataVersion = 0;
+function freezeClassDiMetadata(metadata) {
+  return Object.freeze({
+    inject: metadata.inject ? Object.freeze([...metadata.inject]) : undefined,
     scope: metadata.scope
-  };
+  });
 }
 function getClassMetadataLineage(target) {
   const lineage = [];
@@ -24,20 +25,22 @@ function getClassMetadataLineage(target) {
  * @param metadata Partial or complete DI metadata payload.
  */
 export function defineClassDiMetadata(target, metadata) {
-  classDiMetadataStore.update(target, existing => ({
+  const existing = classDiMetadataStore.get(target);
+  classDiMetadataStore.set(target, freezeClassDiMetadata({
     inject: metadata.inject !== undefined ? metadata.inject : existing?.inject,
     scope: metadata.scope ?? existing?.scope
   }));
+  classDiMetadataVersion += 1;
 }
 
 /**
  * Reads only the DI metadata defined directly on a class.
  *
  * @param target Class being inspected.
- * @returns A defensive clone of the class's own DI metadata, or `undefined` when absent.
+ * @returns A frozen class DI metadata snapshot, or `undefined` when absent.
  */
 export function getOwnClassDiMetadata(target) {
-  return classDiMetadataStore.read(target);
+  return classDiMetadataStore.get(target);
 }
 
 /**
@@ -47,18 +50,26 @@ export function getOwnClassDiMetadata(target) {
  * @returns The effective inherited DI metadata, or `undefined` when no lineage metadata exists.
  */
 export function getInheritedClassDiMetadata(target) {
+  const cached = inheritedClassDiMetadataCache.get(target);
+  if (cached?.version === classDiMetadataVersion) {
+    return cached.metadata ?? undefined;
+  }
   let effective;
   for (const constructor of getClassMetadataLineage(target)) {
-    const metadata = classDiMetadataStore.read(constructor);
+    const metadata = classDiMetadataStore.get(constructor);
     if (!metadata) {
       continue;
     }
-    effective = {
+    effective = freezeClassDiMetadata({
       inject: metadata.inject ?? effective?.inject,
       scope: metadata.scope ?? effective?.scope
-    };
+    });
   }
-  return effective ? cloneClassDiMetadata(effective) : undefined;
+  inheritedClassDiMetadataCache.set(target, {
+    metadata: effective ?? null,
+    version: classDiMetadataVersion
+  });
+  return effective;
 }
 
 /**

package/dist/metadata/module.d.ts

@@ -7,10 +7,10 @@ import type { ModuleMetadata } from './types.js';
  */
 export declare function defineModuleMetadata(target: Function, metadata: ModuleMetadata): void;
 /**
- * Reads cloned module metadata for the provided module class.
+ * Reads frozen module metadata for the provided module class.
  *
  * @param target Module class being inspected.
- * @returns A defensive clone of module metadata, or `undefined` when none was defined.
+ * @returns A frozen module metadata snapshot, or `undefined` when none was defined.
  */
 export declare function getModuleMetadata(target: Function): ModuleMetadata | undefined;
 //# sourceMappingURL=module.d.ts.map

package/dist/metadata/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../src/metadata/module.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAkCjD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,GAAG,IAAI,CASrF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,GAAG,cAAc,GAAG,SAAS,CAE9E"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../src/metadata/module.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA8FjD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,GAAG,IAAI,CAWrF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,GAAG,cAAc,GAAG,SAAS,CAE9E"}

package/dist/metadata/module.js

@@ -1,33 +1,76 @@
 import { cloneCollection, cloneMutableValue } from './shared.js';
-import { createClonedWeakMapStore } from './store.js';
-const moduleMetadataStore = createClonedWeakMapStore(cloneModuleMetadata);
+const moduleMetadataStore = new WeakMap();
 function isValueProvider(provider) {
   return typeof provider === 'object' && provider !== null && 'useValue' in provider;
 }
+function cloneProviderDescriptorFields(provider) {
+  const clonedProvider = {
+    ...provider
+  };
+  if (Array.isArray(clonedProvider.inject)) {
+    clonedProvider.inject = [...clonedProvider.inject];
+  }
+  return clonedProvider;
+}
+function freezeProviderDescriptor(provider) {
+  const inject = provider.inject;
+  if (Array.isArray(inject)) {
+    Object.freeze(inject);
+  }
+  return Object.freeze(provider);
+}
 function cloneProvider(provider) {
   if (isValueProvider(provider)) {
-    // Shallow-copy the provider descriptor but preserve the useValue reference.
+    // Shallow-copy descriptor fields but preserve the useValue reference.
     // Deep-cloning useValue would sever object identity for externally supplied
     // instances (e.g. transport adapters) that callers hold references to.
-    return {
-      ...provider
-    };
+    return freezeProviderDescriptor(cloneProviderDescriptorFields(provider));
   }
-  return cloneMutableValue(provider);
+  const clonedProvider = cloneMutableValue(provider);
+  return typeof clonedProvider === 'object' && clonedProvider !== null ? freezeProviderDescriptor(clonedProvider) : clonedProvider;
 }
 function cloneProviders(providers) {
   return providers ? providers.map(cloneProvider) : undefined;
 }
+function isMiddlewareRouteConfig(middleware) {
+  return typeof middleware === 'object' && middleware !== null && 'middleware' in middleware && 'routes' in middleware;
+}
+function cloneMiddlewareRouteConfig(middleware) {
+  const routes = Array.isArray(middleware.routes) ? Object.freeze([...middleware.routes]) : middleware.routes;
+  return Object.freeze({
+    ...middleware,
+    routes
+  });
+}
+function cloneMiddleware(middleware) {
+  return isMiddlewareRouteConfig(middleware) ? cloneMiddlewareRouteConfig(middleware) : middleware;
+}
+function cloneMiddlewareCollection(middleware) {
+  return middleware ? middleware.map(cloneMiddleware) : undefined;
+}
 function cloneModuleMetadata(metadata) {
   return {
     controllers: cloneCollection(metadata.controllers),
     exports: cloneCollection(metadata.exports),
     global: metadata.global,
     imports: cloneCollection(metadata.imports),
-    middleware: cloneCollection(metadata.middleware),
+    middleware: cloneMiddlewareCollection(metadata.middleware),
     providers: cloneProviders(metadata.providers)
   };
 }
+function freezeCollection(collection) {
+  return collection ? Object.freeze(collection) : undefined;
+}
+function freezeModuleMetadata(metadata) {
+  return Object.freeze({
+    controllers: freezeCollection(metadata.controllers),
+    exports: freezeCollection(metadata.exports),
+    global: metadata.global,
+    imports: freezeCollection(metadata.imports),
+    middleware: freezeCollection(metadata.middleware),
+    providers: freezeCollection(metadata.providers)
+  });
+}
 
 /**
  * Defines module metadata while preserving previously written fields for partial decorator passes.
@@ -36,22 +79,23 @@ function cloneModuleMetadata(metadata) {
  * @param metadata Partial or complete module metadata payload.
  */
 export function defineModuleMetadata(target, metadata) {
-  moduleMetadataStore.update(target, existing => ({
+  const existing = moduleMetadataStore.get(target);
+  moduleMetadataStore.set(target, freezeModuleMetadata(cloneModuleMetadata({
     controllers: metadata.controllers ?? existing?.controllers,
     exports: metadata.exports ?? existing?.exports,
     global: metadata.global !== undefined ? metadata.global : existing?.global,
     imports: metadata.imports ?? existing?.imports,
     middleware: metadata.middleware ?? existing?.middleware,
     providers: metadata.providers ?? existing?.providers
-  }));
+  })));
 }
 
 /**
- * Reads cloned module metadata for the provided module class.
+ * Reads frozen module metadata for the provided module class.
  *
  * @param target Module class being inspected.
- * @returns A defensive clone of module metadata, or `undefined` when none was defined.
+ * @returns A frozen module metadata snapshot, or `undefined` when none was defined.
  */
 export function getModuleMetadata(target) {
-  return moduleMetadataStore.read(target);
+  return moduleMetadataStore.get(target);
 }

package/dist/metadata/shared.d.ts

@@ -71,14 +71,36 @@ export declare function getOrCreatePropertyMap<T>(store: WeakMap<object, Map<Met
  */
 export declare function mergeUnique<T>(existing: readonly T[] | undefined, values: readonly T[] | undefined): T[] | undefined;
 /**
- * Reads the standard metadata bag stored directly on a target.
+ * Reads the standard metadata bag owned directly by a constructor.
+ *
+ * Own current/native metadata wins over own fallback-era metadata. When the
+ * constructor owns neither era, this helper returns `undefined`; it does not
+ * inspect inherited constructors.
+ *
+ * @param constructor Constructor whose own metadata bag should be inspected.
+ * @returns The own metadata bag when present, otherwise `undefined`.
+ */
+export declare function getOwnStandardConstructorMetadataBag(constructor: Function): StandardMetadataBag | undefined;
+/**
+ * Reads the effective standard metadata bag for a target.
+ *
+ * Lookup prefers the target's own current/native metadata bag, then the target's
+ * own fallback-era bag, then inherited bags using the same per-object era order.
+ * When an own bag from either era exists alongside inherited metadata from
+ * either era, the returned bag preserves own-key precedence while allowing
+ * property lookup to fall through to inherited records.
  *
  * @param target Target object that may own standard metadata.
  * @returns The metadata bag when present, otherwise `undefined`.
  */
 export declare function getStandardMetadataBag(target: object): StandardMetadataBag | undefined;
 /**
- * Reads the standard metadata bag stored on a target's constructor.
+ * Reads the effective standard metadata bag stored on a target's constructor.
+ *
+ * Constructor lookup delegates to {@link getStandardMetadataBag}, so it uses the
+ * constructor's own current/native bag, own fallback-era bag, then inherited
+ * constructor bags. Own current/native records retain precedence while inherited
+ * records remain visible through property lookup.
  *
  * @param target Instance or prototype whose constructor metadata should be inspected.
  * @returns The constructor metadata bag when present, otherwise `undefined`.

package/dist/metadata/shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/metadata/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGvD;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AAG/D;;GAEG;AACH,eAAO,IAAI,cAAc,QAAoE,CAAC;AAE9F;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAY7C;AAcD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAMhD;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;CAOvB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;;;CASf,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,GAAG,SAAS,GAAG,CAAC,EAAE,GAAG,SAAS,CAExF;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAAC,EACnD,MAAM,EAAE,MAAM,GACb,GAAG,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAS7B;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,GAAG,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,GAAG,SAAS,GAAG,CAAC,EAAE,GAAG,SAAS,CAgBpH;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAQtF;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAIjG;AAED;;;;;;GAMG;AACH,wBAAgB,oCAAoC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAElG;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,mBAAmB,EAAE,CAAC,CAAC,GAAG,SAAS,CAEzH;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,SAAS,EAC1D,MAAM,EAAE,WAAW,CAAC,mBAAmB,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7D,QAAQ,EAAE,WAAW,CAAC,mBAAmB,EAAE,SAAS,CAAC,GAAG,SAAS,GAChE,mBAAmB,EAAE,CAkBvB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,mBAAmB,EAAE,CAAC,EAAE,CAAC,CAAC,EACrD,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,mBAAmB,EAChC,KAAK,EAAE,CAAC,GACP,IAAI,CAUN;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CASrG"}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/metadata/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGvD;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AAK/D;;GAEG;AACH,eAAO,IAAI,cAAc,QAAwD,CAAC;AAElF;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAY7C;AA+ED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAMhD;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB;;;;;;;CAOvB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;;;;;CASf,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE,GAAG,SAAS,GAAG,CAAC,EAAE,GAAG,SAAS,CAExF;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAAC,EACnD,MAAM,EAAE,MAAM,GACb,GAAG,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAS7B;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,EAAE,GAAG,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,GAAG,SAAS,GAAG,CAAC,EAAE,GAAG,SAAS,CAgBpH;AAGD;;;;;;;;;GASG;AACH,wBAAgB,oCAAoC,CAAC,WAAW,EAAE,QAAQ,GAAG,mBAAmB,GAAG,SAAS,CAE3G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAiBtF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAIjG;AAED;;;;;;GAMG;AACH,wBAAgB,oCAAoC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAElG;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC,mBAAmB,EAAE,CAAC,CAAC,GAAG,SAAS,CAEzH;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,SAAS,EAC1D,MAAM,EAAE,WAAW,CAAC,mBAAmB,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7D,QAAQ,EAAE,WAAW,CAAC,mBAAmB,EAAE,SAAS,CAAC,GAAG,SAAS,GAChE,mBAAmB,EAAE,CAkBvB;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,mBAAmB,EAAE,CAAC,EAAE,CAAC,CAAC,EACrD,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,mBAAmB,EAChC,KAAK,EAAE,CAAC,GACP,IAAI,CAUN;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CASrG"}

package/dist/metadata/shared.js

@@ -5,10 +5,12 @@ import { fallbackClone } from '../utils.js';
  */
 
 const symbolWithMetadata = Symbol;
+const fallbackMetadataSymbol = Symbol.for('fluo.symbol.metadata');
+
 /**
  * Active symbol key used to read and write standard metadata bags.
  */
-export let metadataSymbol = symbolWithMetadata.metadata ?? Symbol.for('fluo.symbol.metadata');
+export let metadataSymbol = symbolWithMetadata.metadata ?? fallbackMetadataSymbol;
 
 /**
  * Ensures `Symbol.metadata` exists and returns the symbol used by Fluo metadata helpers.
@@ -27,6 +29,50 @@ export function ensureMetadataSymbol() {
   return metadataSymbol;
 }
 void ensureMetadataSymbol();
+function getActiveMetadataSymbol() {
+  const nativeMetadataSymbol = symbolWithMetadata.metadata;
+  if (nativeMetadataSymbol && nativeMetadataSymbol !== metadataSymbol) {
+    metadataSymbol = nativeMetadataSymbol;
+  }
+  return metadataSymbol;
+}
+function getOwnStandardMetadataBagFromSymbol(target, symbol) {
+  if (!Object.prototype.hasOwnProperty.call(target, symbol)) {
+    return undefined;
+  }
+  const metadata = Reflect.get(target, symbol);
+  if (typeof metadata !== 'object' || metadata === null) {
+    return undefined;
+  }
+  return metadata;
+}
+function getOwnStandardMetadataBagForEra(target, activeMetadataSymbol) {
+  const activeMetadata = getOwnStandardMetadataBagFromSymbol(target, activeMetadataSymbol);
+  if (activeMetadata) {
+    return activeMetadata;
+  }
+  if (activeMetadataSymbol !== fallbackMetadataSymbol) {
+    return getOwnStandardMetadataBagFromSymbol(target, fallbackMetadataSymbol);
+  }
+  return undefined;
+}
+function getInheritedStandardMetadataBag(target, activeMetadataSymbol) {
+  let prototype = Object.getPrototypeOf(target);
+  while (prototype) {
+    const inheritedMetadata = getOwnStandardMetadataBagForEra(prototype, activeMetadataSymbol);
+    if (inheritedMetadata) {
+      return inheritedMetadata;
+    }
+    prototype = Object.getPrototypeOf(prototype);
+  }
+  return undefined;
+}
+function overlayStandardMetadataBag(ownMetadata, inheritedMetadata) {
+  if (!inheritedMetadata) {
+    return ownMetadata;
+  }
+  return Object.create(inheritedMetadata, Object.getOwnPropertyDescriptors(ownMetadata));
+}
 function isPlainObject(value) {
   if (typeof value !== 'object' || value === null) {
     return false;
@@ -126,21 +172,53 @@ export function mergeUnique(existing, values) {
 }
 
 /**
- * Reads the standard metadata bag stored directly on a target.
+ * Reads the standard metadata bag owned directly by a constructor.
+ *
+ * Own current/native metadata wins over own fallback-era metadata. When the
+ * constructor owns neither era, this helper returns `undefined`; it does not
+ * inspect inherited constructors.
+ *
+ * @param constructor Constructor whose own metadata bag should be inspected.
+ * @returns The own metadata bag when present, otherwise `undefined`.
+ */
+export function getOwnStandardConstructorMetadataBag(constructor) {
+  return getOwnStandardMetadataBagForEra(constructor, getActiveMetadataSymbol());
+}
+
+/**
+ * Reads the effective standard metadata bag for a target.
+ *
+ * Lookup prefers the target's own current/native metadata bag, then the target's
+ * own fallback-era bag, then inherited bags using the same per-object era order.
+ * When an own bag from either era exists alongside inherited metadata from
+ * either era, the returned bag preserves own-key precedence while allowing
+ * property lookup to fall through to inherited records.
  *
  * @param target Target object that may own standard metadata.
  * @returns The metadata bag when present, otherwise `undefined`.
  */
 export function getStandardMetadataBag(target) {
-  const metadata = Reflect.get(target, metadataSymbol);
-  if (typeof metadata !== 'object' || metadata === null) {
-    return undefined;
+  const activeMetadataSymbol = getActiveMetadataSymbol();
+  const ownActiveMetadata = getOwnStandardMetadataBagFromSymbol(target, activeMetadataSymbol);
+  if (ownActiveMetadata) {
+    return overlayStandardMetadataBag(ownActiveMetadata, getInheritedStandardMetadataBag(target, activeMetadataSymbol));
   }
-  return metadata;
+  if (activeMetadataSymbol !== fallbackMetadataSymbol) {
+    const ownFallbackMetadata = getOwnStandardMetadataBagFromSymbol(target, fallbackMetadataSymbol);
+    if (ownFallbackMetadata) {
+      return overlayStandardMetadataBag(ownFallbackMetadata, getInheritedStandardMetadataBag(target, activeMetadataSymbol));
+    }
+  }
+  return getInheritedStandardMetadataBag(target, activeMetadataSymbol);
 }
 
 /**
- * Reads the standard metadata bag stored on a target's constructor.
+ * Reads the effective standard metadata bag stored on a target's constructor.
+ *
+ * Constructor lookup delegates to {@link getStandardMetadataBag}, so it uses the
+ * constructor's own current/native bag, own fallback-era bag, then inherited
+ * constructor bags. Own current/native records retain precedence while inherited
+ * records remain visible through property lookup.
  *
  * @param target Instance or prototype whose constructor metadata should be inspected.
  * @returns The constructor metadata bag when present, otherwise `undefined`.

package/dist/metadata.d.ts

@@ -2,7 +2,7 @@ export { getClassDiMetadata, getInheritedClassDiMetadata, getOwnClassDiMetadata,
 export { defineControllerMetadata, defineRouteMetadata, getControllerMetadata, getRouteMetadata } from './metadata/controller-route.js';
 export { defineInjectionMetadata, getInjectionSchema } from './metadata/injection.js';
 export { defineModuleMetadata, getModuleMetadata } from './metadata/module.js';
-export { ensureMetadataSymbol, metadataKeys, metadataSymbol } from './metadata/shared.js';
+export { ensureMetadataSymbol, getOwnStandardConstructorMetadataBag, getStandardConstructorMetadataBag, getStandardMetadataBag, metadataKeys, metadataSymbol, } from './metadata/shared.js';
 export { ensureSymbolMetadataPolyfill } from './metadata/symbol-metadata-polyfill.js';
 export { appendClassValidationRule, appendDtoFieldValidationRule, defineDtoFieldBindingMetadata, getClassValidationRules, getDtoBindingSchema, getDtoFieldBindingMetadata, getDtoFieldValidationRules, getDtoValidationSchema, } from './metadata/validation.js';
 export type { ClassDiMetadata, ClassValidationRule, ConditionalFieldValidator, ControllerMetadata, CustomClassValidator, CustomFieldValidationContext, CustomFieldValidator, CustomValidationDecoratorOptions, DtoBindingSchemaEntry, DtoFieldBindingMetadata, DtoFieldValidationRule, DtoValidationSchemaEntry, InjectionMetadata, InjectionSchemaEntry, MetadataCollection, ModuleMetadata, RouteHeader, RouteMetadata, RouteRedirect, ValidationDecoratorOptions, ValidationIssueMetadata, ValidationRuleResult, } from './metadata/types.js';

package/dist/metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACvI,OAAO,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACxI,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC1F,OAAO,EAAE,4BAA4B,EAAE,MAAM,wCAAwC,CAAC;AACtF,OAAO,EACL,yBAAyB,EACzB,4BAA4B,EAC5B,6BAA6B,EAC7B,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,4BAA4B,EAC5B,oBAAoB,EACpB,gCAAgC,EAChC,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,EACxB,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,aAAa,EACb,aAAa,EACb,0BAA0B,EAC1B,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACvI,OAAO,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACxI,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EACL,oBAAoB,EACpB,oCAAoC,EACpC,iCAAiC,EACjC,sBAAsB,EACtB,YAAY,EACZ,cAAc,GACf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,4BAA4B,EAAE,MAAM,wCAAwC,CAAC;AACtF,OAAO,EACL,yBAAyB,EACzB,4BAA4B,EAC5B,6BAA6B,EAC7B,uBAAuB,EACvB,mBAAmB,EACnB,0BAA0B,EAC1B,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,yBAAyB,EACzB,kBAAkB,EAClB,oBAAoB,EACpB,4BAA4B,EAC5B,oBAAoB,EACpB,gCAAgC,EAChC,qBAAqB,EACrB,uBAAuB,EACvB,sBAAsB,EACtB,wBAAwB,EACxB,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,aAAa,EACb,aAAa,EACb,0BAA0B,EAC1B,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC"}

package/dist/metadata.js

@@ -2,6 +2,6 @@ export { getClassDiMetadata, getInheritedClassDiMetadata, getOwnClassDiMetadata,
 export { defineControllerMetadata, defineRouteMetadata, getControllerMetadata, getRouteMetadata } from './metadata/controller-route.js';
 export { defineInjectionMetadata, getInjectionSchema } from './metadata/injection.js';
 export { defineModuleMetadata, getModuleMetadata } from './metadata/module.js';
-export { ensureMetadataSymbol, metadataKeys, metadataSymbol } from './metadata/shared.js';
+export { ensureMetadataSymbol, getOwnStandardConstructorMetadataBag, getStandardConstructorMetadataBag, getStandardMetadataBag, metadataKeys, metadataSymbol } from './metadata/shared.js';
 export { ensureSymbolMetadataPolyfill } from './metadata/symbol-metadata-polyfill.js';
 export { appendClassValidationRule, appendDtoFieldValidationRule, defineDtoFieldBindingMetadata, getClassValidationRules, getDtoBindingSchema, getDtoFieldBindingMetadata, getDtoFieldValidationRules, getDtoValidationSchema } from './metadata/validation.js';

package/package.json

@@ -9,7 +9,7 @@
     "types",
     "foundation"
   ],
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "private": false,
   "license": "MIT",
   "repository": {