@kadi.build/core 0.0.1-alpha.0 → 0.0.1-alpha.10

package/dist/abilities/AbilityLoader.js

@@ -0,0 +1,277 @@
+/**
+ * Ability Loader
+ *
+ * Orchestrates ability loading with excellent developer experience:
+ * - Smart transport inference (auto-detect or explicit)
+ * - Intelligent caching (composite keys)
+ * - Runtime validation (catch issues early)
+ * - Helpful error messages (actionable suggestions)
+ *
+ * @module abilities/AbilityLoader
+ */
+import { KadiError, ErrorCode } from '../types/index.js';
+import { BrokerTransport } from '../transports/BrokerTransport.js';
+import { AbilityProxy } from './AbilityProxy.js';
+import { AbilityCache } from './AbilityCache.js';
+import { AbilityValidator } from './AbilityValidator.js';
+/**
+ * Ability Loader
+ *
+ * Orchestrates the complete ability loading process:
+ * - Transport inference (smart auto-detection)
+ * - Caching (avoid duplicate loads)
+ * - Transport creation (factory pattern)
+ * - Validation (runtime checks)
+ * - Error handling (helpful messages)
+ *
+ * Single responsibility: Load abilities, nothing else.
+ *
+ * @example
+ * ```typescript
+ * const loader = new AbilityLoader();
+ *
+ * // Auto-detect (recommended)
+ * const calc = await loader.load('calculator', {}, brokerClient);
+ *
+ * // Explicit transport
+ * const remote = await loader.load('service', {
+ *   transport: 'broker',
+ *   networks: ['global']
+ * }, brokerClient);
+ *
+ * // With validation
+ * const typed = await loader.load<CalcAPI>('calc', {
+ *   validate: true
+ * }, brokerClient);
+ * ```
+ */
+export class AbilityLoader {
+    /**
+     * Ability cache with composite key strategy
+     *
+     * Handles complex scenarios:
+     * - Same name, different transports
+     * - Same name, different versions
+     * - Same name, different brokers
+     */
+    cache = new AbilityCache();
+    /**
+     * Load an ability with explicit transport
+     *
+     * **Features:**
+     * - Explicit transport (no magic)
+     * - Smart caching (composite keys)
+     * - Runtime validation (optional)
+     * - Dynamic method access
+     *
+     * @param name - Ability name
+     * @param transport - Transport type (native, stdio, or broker)
+     * @param options - Load options (transport-specific)
+     * @param brokerClient - Broker client interface
+     * @returns Loaded ability with dynamic method access
+     *
+     * @throws {KadiError} If loading fails
+     *
+     * @example
+     * ```typescript
+     * // Broker transport
+     * const remote = await loader.load('service', 'broker', {
+     *   networks: ['global']
+     * }, brokerClient);
+     *
+     * // With runtime validation
+     * const calc = await loader.load('calc', 'broker', {
+     *   validate: true
+     * }, brokerClient);
+     *
+     * // Native transport
+     * const local = await loader.load('local-lib', 'native', {
+     *   path: './abilities/local-lib'
+     * });
+     * ```
+     */
+    async load(name, transport, options = {}, brokerClient) {
+        // Step 1: Check cache first (avoid duplicate loading)
+        const cacheKey = {
+            name,
+            transport,
+            version: options.version,
+            broker: 'broker' in options ? options.broker : undefined
+        };
+        const cached = this.cache.get(cacheKey);
+        if (cached && cached.__isConnected()) {
+            // Cache hit! Return existing ability
+            return cached;
+        }
+        // Step 2: Create appropriate transport
+        const transportInstance = this.createTransport(name, transport, options, brokerClient);
+        // Step 3: Connect to ability
+        await transportInstance.connect();
+        // Step 4: Create proxy for natural method calling
+        const ability = AbilityProxy.create(name, transportInstance, transport);
+        // Step 5: Validate if requested
+        if (options.validate) {
+            AbilityValidator.validate(ability);
+        }
+        // Step 6: Cache for future use
+        this.cache.set(cacheKey, ability);
+        return ability;
+    }
+    /**
+     * Unload all abilities
+     *
+     * Disconnects all transports and clears cache.
+     *
+     * @example
+     * ```typescript
+     * await loader.unloadAll();
+     * ```
+     */
+    async unloadAll() {
+        // Step 1: Get all cached abilities
+        const abilities = this.cache.getAll();
+        // Step 2: Disconnect all transports in parallel
+        const disconnectPromises = abilities.map(ability => ability.__disconnect().catch(() => {
+            // Ignore disconnect errors during cleanup
+        }));
+        await Promise.all(disconnectPromises);
+        // Step 3: Clear cache
+        this.cache.clear();
+    }
+    /**
+     * Get all loaded abilities
+     *
+     * @returns Array of loaded abilities
+     *
+     * @example
+     * ```typescript
+     * const abilities = loader.getAll();
+     * console.log(`Loaded ${abilities.length} abilities`);
+     * ```
+     */
+    getAll() {
+        return this.cache.getAll();
+    }
+    /**
+     * Get cache statistics
+     *
+     * Useful for debugging and monitoring.
+     *
+     * @returns Cache statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = loader.getStats();
+     * console.log(`Cached: ${stats.totalCached}, Connected: ${stats.connected}`);
+     * ```
+     */
+    getStats() {
+        return this.cache.getStats();
+    }
+    /**
+     * Cleanup disconnected abilities
+     *
+     * Removes stale cache entries.
+     *
+     * @returns Number of stale entries removed
+     *
+     * @example
+     * ```typescript
+     * const removed = loader.cleanup();
+     * console.log(`Cleaned up ${removed} disconnected abilities`);
+     * ```
+     */
+    cleanup() {
+        return this.cache.cleanup();
+    }
+    /**
+     * Create appropriate transport instance
+     *
+     * Clean factory pattern - delegates to specialized creation methods.
+     * Each transport type has its own dedicated method with proper validation.
+     *
+     * @param name - Ability name
+     * @param transport - Transport type (from inference)
+     * @param options - Load options
+     * @param brokerClient - Broker client (for broker transport)
+     * @returns Transport instance ready to connect
+     *
+     * @throws {KadiError} If transport creation fails
+     */
+    createTransport(name, transport, options, brokerClient) {
+        // Delegate to appropriate transport creation method
+        switch (transport) {
+            case 'broker':
+                return this.createBrokerTransport(name, options, brokerClient);
+            case 'native':
+                // TODO: Implement native transport
+                // Phase 2 implementation
+                throw new KadiError('Native transport not yet implemented', ErrorCode.NOT_IMPLEMENTED, 501, {
+                    abilityName: name,
+                    transport: 'native',
+                    suggestion: 'Use broker transport for now: { transport: "broker" }',
+                    roadmap: 'Native transport coming in Phase 2',
+                    documentation: 'See docs/ability-loading-design.md for implementation guide'
+                });
+            case 'stdio':
+                // TODO: Implement stdio transport
+                // Phase 2 implementation
+                throw new KadiError('Stdio transport not yet implemented', ErrorCode.NOT_IMPLEMENTED, 501, {
+                    abilityName: name,
+                    transport: 'stdio',
+                    suggestion: 'Use broker transport for now: { transport: "broker" }',
+                    roadmap: 'Stdio transport coming in Phase 2',
+                    documentation: 'See docs/ability-chaining-corrected.md for implementation guide'
+                });
+            default:
+                // TypeScript exhaustiveness check ensures this is unreachable
+                const never = transport;
+                throw new KadiError(`Unknown transport type: ${never}`, ErrorCode.INVALID_CONFIG, 400, { abilityName: name });
+        }
+    }
+    /**
+     * Create broker transport with excellent error handling
+     *
+     * Validates broker connection and creates transport with proper configuration.
+     *
+     * @param name - Ability name
+     * @param options - Load options (broker-specific)
+     * @param brokerClient - Broker client interface
+     * @returns Broker transport instance
+     *
+     * @throws {KadiError} If broker client missing or invalid config
+     */
+    createBrokerTransport(name, options, brokerClient) {
+        // Step 1: Validate broker client exists
+        if (!brokerClient) {
+            throw new KadiError('Cannot use broker transport - not connected to broker', ErrorCode.BROKER_NOT_CONNECTED, 503, {
+                abilityName: name,
+                transport: 'broker',
+                reason: 'Broker client not provided to AbilityLoader',
+                suggestion: 'Connect to broker first: await client.connect()',
+                alternatives: [
+                    'Connect to broker before loading abilities',
+                    'Use different transport like native or stdio'
+                ],
+                hint: 'Broker transport requires active broker connection'
+            });
+        }
+        // Step 2: Extract broker-specific options (type-safe!)
+        const brokerOptions = options;
+        // Step 3: Determine networks to search
+        // Priority: explicit options > client networks
+        const networks = brokerOptions.networks ?? brokerClient.networks;
+        // Step 4: Determine which broker to use
+        // Priority: explicit broker > client default
+        const broker = brokerOptions.broker ?? brokerClient.getBrokerManager().getDefaultBrokerName() ?? undefined;
+        // Step 5: Create transport with validated config
+        return new BrokerTransport({
+            abilityName: name,
+            brokerUrl: '', // Not needed - using existing connection
+            brokerName: broker,
+            networks,
+            timeout: options.timeout
+        }, brokerClient);
+    }
+}
+//# sourceMappingURL=AbilityLoader.js.map

package/dist/abilities/AbilityLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbilityLoader.js","sourceRoot":"","sources":["../../src/abilities/AbilityLoader.ts"],"names":[],"mappings":"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"}