@fluojs/microservices 1.0.0-beta.2 → 1.0.0-beta.4

package/README.ko.md

@@ -128,11 +128,7 @@ Behavioral contract notes:
 
 ### provider 배열 헬퍼
 
-`createMicroservicesProviders(...)`는 실제로 low-level provider array 자체가 필요한 호출자에게만 남아 있습니다.
-
-`createMicroservicesProviders(...)`는 커스텀 모듈 조합에 provider 배열이 필요할 때 사용할 수 있습니다.
-
-`createMicroservicesProviders(...)`는 실제로 low-level provider array 자체가 필요한 호출자에게만 남아 있습니다.
+`createMicroservicesProviders(...)`는 커스텀 모듈 조합에 low-level provider array 자체가 필요할 때만 사용하세요. Custom provider/export/non-global registration에는 built-in lifecycle wiring과 export token을 그대로 유지하는 `MicroservicesModule.forRoot({ transport, module: { ... } })` 경로를 우선 사용하세요.
 
 ```ts
 import { Module } from '@fluojs/core';
@@ -156,6 +152,18 @@ class ManualMicroserviceProvidersModule {}
 - `MicroserviceLifecycleService`, `MICROSERVICE`: 런타임 접근용 서비스와 토큰입니다.
 - `createMicroservicePlatformStatusSnapshot`, `ServerStreamWriter`: 상태 스냅샷/TypeScript 계약 헬퍼입니다.
 
+### Programmatic runtime
+
+`MicroserviceLifecycleService`는 programmatic runtime access를 위해 `listen()`, `close()`, `send()`, `emit()`, `serverStream()`, `clientStream()`, `bidiStream()`, `createPlatformStatusSnapshot()`을 제공합니다.
+
+### Type export
+
+Root barrel은 `Microservice`, `MicroserviceModuleOptions`, `MicroserviceModuleRegistrationOptions`, `MicroserviceTransport`, `Pattern`, `ServerStreamWriter`와 `GrpcMicroserviceTransportOptions`, `KafkaMicroserviceTransportOptions`, `MqttMicroserviceTransportOptions`, `NatsMicroserviceTransportOptions`, `RabbitMqMicroserviceTransportOptions`, `RedisPubSubMicroserviceTransportOptions`, `RedisStreamsMicroserviceTransportOptions`, `RedisStreamClientLike` 같은 transport option type을 export합니다.
+
+### 동작 계약
+
+Payload는 dispatch 전에 clone되고, 동시 `listen()` 호출은 dedupe되며, request-scoped provider는 성공/실패 후 dispose됩니다. Event fan-out은 event dispatch마다 하나의 scope를 공유하고, duplicate message match는 결정적으로 실패합니다.
+
 ### 지원되는 트랜스포트 서브패스
 
 - `@fluojs/microservices/tcp`

package/README.md

@@ -125,11 +125,7 @@ Behavioral contract notes:
 
 ### Provider-array helper
 
-`createMicroservicesProviders(...)` remains available only for callers that truly need the low-level provider array itself.
-
-Use `createMicroservicesProviders(...)` when you need a provider array for custom module assembly.
-
-`createMicroservicesProviders(...)` remains available only for callers that truly need the low-level provider array itself.
+Use `createMicroservicesProviders(...)` only when you need the low-level provider array itself for custom module assembly. Prefer `MicroservicesModule.forRoot({ transport, module: { ... } })` for custom providers, exports, or non-global registration because that path keeps the built-in lifecycle wiring and exported tokens intact.
 
 ```typescript
 import { Module } from '@fluojs/core';
@@ -153,6 +149,18 @@ class ManualMicroserviceProvidersModule {}
 - `MicroserviceLifecycleService`, `MICROSERVICE`: programmatic runtime access token and service.
 - `createMicroservicePlatformStatusSnapshot`, `ServerStreamWriter`: status and TypeScript contract helpers.
 
+### Programmatic runtime
+
+`MicroserviceLifecycleService` exposes `listen()`, `close()`, `send()`, `emit()`, `serverStream()`, `clientStream()`, `bidiStream()`, and `createPlatformStatusSnapshot()` for programmatic runtime access.
+
+### Type exports
+
+The root barrel exports `Microservice`, `MicroserviceModuleOptions`, `MicroserviceModuleRegistrationOptions`, `MicroserviceTransport`, `Pattern`, `ServerStreamWriter`, and transport option types such as `GrpcMicroserviceTransportOptions`, `KafkaMicroserviceTransportOptions`, `MqttMicroserviceTransportOptions`, `NatsMicroserviceTransportOptions`, `RabbitMqMicroserviceTransportOptions`, `RedisPubSubMicroserviceTransportOptions`, `RedisStreamsMicroserviceTransportOptions`, and `RedisStreamClientLike`.
+
+### Behavioral contracts
+
+Payloads are cloned before dispatch, concurrent `listen()` calls are deduped, request-scoped providers are disposed after success and failure, event fan-out shares one scope per event dispatch, and duplicate message matches fail deterministically.
+
 ### Supported transport subpaths
 
 - `@fluojs/microservices/tcp`

package/dist/decorators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAgC,OAAO,EAAE,MAAM,YAAY,CAAC;AAGxE,KAAK,mBAAmB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAC;AA0D3F;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAEvE"}
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAgC,OAAO,EAAE,MAAM,YAAY,CAAC;AAGxE,KAAK,mBAAmB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAC;AA2D3F;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,mBAAmB,CAEvE"}

package/dist/decorators.js

@@ -1,7 +1,7 @@
-import { metadataSymbol } from '@fluojs/core/internal';
+import { ensureMetadataSymbol } from '@fluojs/core/internal';
 import { microserviceMetadataSymbol } from './metadata.js';
+ensureMetadataSymbol();
 function getStandardMetadataBag(metadata) {
-  void metadataSymbol;
   return metadata;
 }
 function defineStandardHandlerMetadata(metadata, propertyKey, handlerMetadata) {

package/dist/metadata.d.ts

@@ -1,9 +1,25 @@
 import { type MetadataPropertyKey } from '@fluojs/core';
 import type { HandlerMetadata } from './types.js';
+/**
+ * Define handler metadata.
+ *
+ * @param target The target.
+ * @param propertyKey The property key.
+ * @param metadata The metadata.
+ */
 export declare function defineHandlerMetadata(target: object, propertyKey: MetadataPropertyKey, metadata: HandlerMetadata): void;
+/**
+ * Get handler metadata entries.
+ *
+ * @param target The target.
+ * @returns The get handler metadata entries result.
+ */
 export declare function getHandlerMetadataEntries(target: object): Array<{
     metadata: HandlerMetadata;
     propertyKey: MetadataPropertyKey;
 }>;
+/**
+ * Provides the microservice metadata symbol value.
+ */
 export declare const microserviceMetadataSymbol: symbol;
 //# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAuClD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,mBAAmB,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAKvH;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,GACb,KAAK,CAAC;IAAE,QAAQ,EAAE,eAAe,CAAC;IAAC,WAAW,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAkBxE;AAED,eAAO,MAAM,0BAA0B,QAAkC,CAAC"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AA+BlD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,mBAAmB,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAKvH;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,GACb,KAAK,CAAC;IAAE,QAAQ,EAAE,eAAe,CAAC;IAAC,WAAW,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAkBxE;AAED;;GAEG;AACH,eAAO,MAAM,0BAA0B,QAAkC,CAAC"}

package/dist/metadata.js

@@ -1,4 +1,4 @@
-import { ensureSymbolMetadataPolyfill, metadataSymbol } from '@fluojs/core/internal';
+import { ensureSymbolMetadataPolyfill, getStandardConstructorMetadataBag } from '@fluojs/core/internal';
 void ensureSymbolMetadataPolyfill();
 const standardMicroserviceMetadataKey = Symbol.for('fluo.microservices.standard.handler');
 const handlerMetadataStore = new WeakMap();
@@ -8,12 +8,8 @@ function cloneHandlerMetadata(metadata) {
     pattern: metadata.pattern
   };
 }
-function getStandardMetadataBag(target) {
-  return target[metadataSymbol];
-}
 function getStandardHandlerMap(target) {
-  const constructor = target.constructor;
-  return constructor ? getStandardMetadataBag(constructor)?.[standardMicroserviceMetadataKey] : undefined;
+  return getStandardConstructorMetadataBag(target)?.[standardMicroserviceMetadataKey];
 }
 function getOrCreateHandlerMap(target) {
   let map = handlerMetadataStore.get(target);
@@ -23,12 +19,27 @@ function getOrCreateHandlerMap(target) {
   }
   return map;
 }
+
+/**
+ * Define handler metadata.
+ *
+ * @param target The target.
+ * @param propertyKey The property key.
+ * @param metadata The metadata.
+ */
 export function defineHandlerMetadata(target, propertyKey, metadata) {
   const map = getOrCreateHandlerMap(target);
   const current = map.get(propertyKey) ?? [];
   current.push(cloneHandlerMetadata(metadata));
   map.set(propertyKey, current);
 }
+
+/**
+ * Get handler metadata entries.
+ *
+ * @param target The target.
+ * @returns The get handler metadata entries result.
+ */
 export function getHandlerMetadataEntries(target) {
   const stored = handlerMetadataStore.get(target) ?? new Map();
   const standard = getStandardHandlerMap(target) ?? new Map();
@@ -45,4 +56,8 @@ export function getHandlerMetadataEntries(target) {
   }
   return entries;
 }
+
+/**
+ * Provides the microservice metadata symbol value.
+ */
 export const microserviceMetadataSymbol = standardMicroserviceMetadataKey;

package/dist/status.d.ts

@@ -1,5 +1,11 @@
 import type { PlatformHealthReport, PlatformReadinessReport, PlatformSnapshot } from '@fluojs/runtime';
+/**
+ * Defines the microservice lifecycle state type.
+ */
 export type MicroserviceLifecycleState = 'created' | 'starting' | 'ready' | 'stopping' | 'stopped' | 'failed';
+/**
+ * Describes the microservice handler counts contract.
+ */
 export interface MicroserviceHandlerCounts {
     'bidi-stream': number;
     'client-stream': number;
@@ -7,6 +13,9 @@ export interface MicroserviceHandlerCounts {
     message: number;
     'server-stream': number;
 }
+/**
+ * Describes the microservice transport capabilities contract.
+ */
 export interface MicroserviceTransportCapabilities {
     bidiStream: boolean;
     clientStream: boolean;
@@ -14,17 +23,29 @@ export interface MicroserviceTransportCapabilities {
     send: boolean;
     serverStream: boolean;
 }
+/**
+ * Describes the microservice status adapter input contract.
+ */
 export interface MicroserviceStatusAdapterInput {
     handlerCounts: MicroserviceHandlerCounts;
     lastListenError?: string;
     lifecycleState: MicroserviceLifecycleState;
     transportCapabilities: MicroserviceTransportCapabilities;
 }
+/**
+ * Describes the microservice platform status snapshot contract.
+ */
 export interface MicroservicePlatformStatusSnapshot {
     readiness: PlatformReadinessReport;
     health: PlatformHealthReport;
     ownership: PlatformSnapshot['ownership'];
     details: Record<string, unknown>;
 }
+/**
+ * Create microservice platform status snapshot.
+ *
+ * @param input The input.
+ * @returns The create microservice platform status snapshot result.
+ */
 export declare function createMicroservicePlatformStatusSnapshot(input: MicroserviceStatusAdapterInput): MicroservicePlatformStatusSnapshot;
 //# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvG,MAAM,MAAM,0BAA0B,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE9G,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iCAAiC;IAChD,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,8BAA8B;IAC7C,aAAa,EAAE,yBAAyB,CAAC;IACzC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,0BAA0B,CAAC;IAC3C,qBAAqB,EAAE,iCAAiC,CAAC;CAC1D;AAED,MAAM,WAAW,kCAAkC;IACjD,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAqED,wBAAgB,wCAAwC,CACtD,KAAK,EAAE,8BAA8B,GACpC,kCAAkC,CAoBpC"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEvG;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE9G;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,iCAAiC;IAChD,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,aAAa,EAAE,yBAAyB,CAAC;IACzC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,0BAA0B,CAAC;IAC3C,qBAAqB,EAAE,iCAAiC,CAAC;CAC1D;AAED;;GAEG;AACH,MAAM,WAAW,kCAAkC;IACjD,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAqED;;;;;GAKG;AACH,wBAAgB,wCAAwC,CACtD,KAAK,EAAE,8BAA8B,GACpC,kCAAkC,CAoBpC"}

package/dist/status.js

@@ -1,3 +1,23 @@
+/**
+ * Defines the microservice lifecycle state type.
+ */
+
+/**
+ * Describes the microservice handler counts contract.
+ */
+
+/**
+ * Describes the microservice transport capabilities contract.
+ */
+
+/**
+ * Describes the microservice status adapter input contract.
+ */
+
+/**
+ * Describes the microservice platform status snapshot contract.
+ */
+
 function createReadiness(input) {
   if (input.lifecycleState === 'ready') {
     return {
@@ -56,6 +76,13 @@ function createHealth(input) {
     status: 'healthy'
   };
 }
+
+/**
+ * Create microservice platform status snapshot.
+ *
+ * @param input The input.
+ * @returns The create microservice platform status snapshot result.
+ */
 export function createMicroservicePlatformStatusSnapshot(input) {
   return {
     details: {

package/dist/transports/event-handler-logger.d.ts

@@ -1,3 +1,10 @@
 import type { MicroserviceTransportLogger } from '../types.js';
+/**
+ * Log transport event handler failure.
+ *
+ * @param logger The logger.
+ * @param transportName The transport name.
+ * @param error The error.
+ */
 export declare function logTransportEventHandlerFailure(logger: MicroserviceTransportLogger | undefined, transportName: string, error: unknown): void;
 //# sourceMappingURL=event-handler-logger.d.ts.map

package/dist/transports/event-handler-logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-handler-logger.d.ts","sourceRoot":"","sources":["../../src/transports/event-handler-logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAE/D,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,2BAA2B,GAAG,SAAS,EAC/C,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,OAAO,GACb,IAAI,CAEN"}
+{"version":3,"file":"event-handler-logger.d.ts","sourceRoot":"","sources":["../../src/transports/event-handler-logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,2BAA2B,GAAG,SAAS,EAC/C,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,OAAO,GACb,IAAI,CAEN"}

package/dist/transports/event-handler-logger.js

@@ -1,3 +1,10 @@
+/**
+ * Log transport event handler failure.
+ *
+ * @param logger The logger.
+ * @param transportName The transport name.
+ * @param error The error.
+ */
 export function logTransportEventHandlerFailure(logger, transportName, error) {
   logger?.error('Event handler failed.', error, transportName);
 }

package/package.json

@@ -13,7 +13,7 @@
     "grpc",
     "mqtt"
   ],
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.4",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -68,9 +68,9 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.0-beta.1",
-    "@fluojs/di": "^1.0.0-beta.2",
-    "@fluojs/runtime": "^1.0.0-beta.2"
+    "@fluojs/core": "^1.0.0-beta.4",
+    "@fluojs/di": "^1.0.0-beta.6",
+    "@fluojs/runtime": "^1.0.0-beta.11"
   },
   "peerDependencies": {
     "@grpc/grpc-js": "^1.0.0",