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

package/dist/abilities/AbilityCache.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Ability Cache
+ *
+ * Smart caching with composite keys to handle complex scenarios:
+ * - Same ability name, different transports
+ * - Same ability name, different versions
+ * - Same ability name, different brokers
+ *
+ * @module abilities/AbilityCache
+ */
+import type { LoadedAbility } from './AbilityProxy.js';
+import type { TransportType } from './types.js';
+/**
+ * Cache key components
+ *
+ * All factors that make an ability unique in the cache.
+ * Two abilities are considered "same" only if ALL components match.
+ */
+export interface CacheKey {
+    /**
+     * Ability name
+     */
+    name: string;
+    /**
+     * Transport type used to load it
+     *
+     * Same ability via broker vs native are cached separately.
+     */
+    transport: TransportType;
+    /**
+     * Version constraint (optional)
+     *
+     * Same ability, different versions are cached separately.
+     */
+    version?: string;
+    /**
+     * Broker name (optional)
+     *
+     * Same ability from different brokers cached separately.
+     * Only relevant for broker transport.
+     */
+    broker?: string;
+}
+/**
+ * Ability Cache
+ *
+ * Intelligent caching that avoids loading same ability multiple times,
+ * while correctly handling scenarios where same name ≠ same ability.
+ *
+ * **Why Composite Keys?**
+ *
+ * Consider:
+ * ```typescript
+ * const local = await client.load('calc', { transport: 'native' });
+ * const remote = await client.load('calc', { transport: 'broker' });
+ * ```
+ *
+ * These are DIFFERENT abilities (different implementations, different transports)
+ * despite having same name. Cache must treat them separately!
+ *
+ * @example
+ * ```typescript
+ * const cache = new AbilityCache();
+ *
+ * // Store ability
+ * cache.set({ name: 'calc', transport: 'broker' }, ability);
+ *
+ * // Retrieve ability
+ * const cached = cache.get({ name: 'calc', transport: 'broker' });
+ *
+ * // Different transport = different cache entry
+ * const notFound = cache.get({ name: 'calc', transport: 'native' });
+ * // Returns undefined (different transport)
+ * ```
+ */
+export declare class AbilityCache {
+    /**
+     * Internal cache storage
+     *
+     * Key: composite string (name:transport:version:broker)
+     * Value: loaded ability instance
+     */
+    private cache;
+    /**
+     * Generate composite cache key from components
+     *
+     * Format: `name:transport[:version][:broker]`
+     *
+     * Optional components only included if present:
+     * - Basic: "calculator:broker"
+     * - With version: "calculator:broker:2.0.0"
+     * - With broker: "calculator:broker::main-broker"
+     * - Full: "calculator:broker:2.0.0:main-broker"
+     *
+     * @param key - Cache key components
+     * @returns Composite key string
+     *
+     * @example
+     * ```typescript
+     * generateKey({ name: 'calc', transport: 'broker' })
+     * // Returns: "calc:broker"
+     *
+     * generateKey({ name: 'calc', transport: 'broker', version: '2.0.0' })
+     * // Returns: "calc:broker:2.0.0"
+     * ```
+     */
+    private generateKey;
+    /**
+     * Get cached ability
+     *
+     * Returns cached instance if exists and still connected.
+     * Returns undefined if not cached or disconnected.
+     *
+     * @param key - Cache key components
+     * @returns Cached ability or undefined
+     *
+     * @example
+     * ```typescript
+     * const ability = cache.get({
+     *   name: 'calculator',
+     *   transport: 'broker'
+     * });
+     *
+     * if (ability) {
+     *   // Cache hit! Use cached ability
+     *   await ability.add({ a: 5, b: 3 });
+     * } else {
+     *   // Cache miss - need to load
+     * }
+     * ```
+     */
+    get(key: CacheKey): LoadedAbility | undefined;
+    /**
+     * Store ability in cache
+     *
+     * Overwrites existing entry if present.
+     *
+     * @param key - Cache key components
+     * @param ability - Loaded ability to cache
+     *
+     * @example
+     * ```typescript
+     * cache.set(
+     *   { name: 'calculator', transport: 'broker', version: '2.0.0' },
+     *   loadedAbility
+     * );
+     * ```
+     */
+    set(key: CacheKey, ability: LoadedAbility): void;
+    /**
+     * Check if ability exists in cache
+     *
+     * Returns true only if cached AND still connected.
+     *
+     * @param key - Cache key components
+     * @returns true if cached and connected
+     *
+     * @example
+     * ```typescript
+     * if (cache.has({ name: 'calc', transport: 'broker' })) {
+     *   // Can safely use cached version
+     * }
+     * ```
+     */
+    has(key: CacheKey): boolean;
+    /**
+     * Remove ability from cache
+     *
+     * @param key - Cache key components
+     * @returns true if was cached (now removed), false if wasn't cached
+     *
+     * @example
+     * ```typescript
+     * cache.delete({ name: 'calc', transport: 'broker' });
+     * ```
+     */
+    delete(key: CacheKey): boolean;
+    /**
+     * Clear all cached abilities
+     *
+     * Removes everything from cache.
+     * Usually called during client disconnect/cleanup.
+     *
+     * @example
+     * ```typescript
+     * cache.clear();
+     * ```
+     */
+    clear(): void;
+    /**
+     * Get all cached abilities
+     *
+     * Returns array of all cached ability instances.
+     * Useful for bulk operations like disconnect.
+     *
+     * @returns Array of loaded abilities
+     *
+     * @example
+     * ```typescript
+     * // Disconnect all cached abilities
+     * for (const ability of cache.getAll()) {
+     *   await ability.__disconnect();
+     * }
+     * ```
+     */
+    getAll(): LoadedAbility[];
+    /**
+     * Get cache statistics
+     *
+     * Returns info about cache state for debugging/monitoring.
+     *
+     * @returns Cache statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = cache.getStats();
+     * console.log(`Cached: ${stats.totalCached}, Connected: ${stats.connected}`);
+     * ```
+     */
+    getStats(): {
+        totalCached: number;
+        connected: number;
+        disconnected: number;
+        byTransport: Record<TransportType, number>;
+    };
+    /**
+     * Cleanup disconnected abilities
+     *
+     * Removes abilities that are no longer connected.
+     * Returns number of entries removed.
+     *
+     * @returns Number of stale entries removed
+     *
+     * @example
+     * ```typescript
+     * const removed = cache.cleanup();
+     * console.log(`Removed ${removed} disconnected abilities`);
+     * ```
+     */
+    cleanup(): number;
+}
+//# sourceMappingURL=AbilityCache.d.ts.map

package/dist/abilities/AbilityCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AbilityCache.d.ts","sourceRoot":"","sources":["../../src/abilities/AbilityCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,SAAS,EAAE,aAAa,CAAC;IAEzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,YAAY;IACvB;;;;;OAKG;IACH,OAAO,CAAC,KAAK,CAAoC;IAEjD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,WAAW;IAqBnB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,aAAa,GAAG,SAAS;IAkB7C;;;;;;;;;;;;;;;OAeG;IACH,GAAG,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI;IAQhD;;;;;;;;;;;;;;OAcG;IACH,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO;IAI3B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO;IAQ9B;;;;;;;;;;OAUG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;;;;;;;;;;;OAeG;IACH,MAAM,IAAI,aAAa,EAAE;IAIzB;;;;;;;;;;;;OAYG;IACH,QAAQ,IAAI;QACV,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;KAC5C;IA6BD;;;;;;;;;;;;;OAaG;IACH,OAAO,IAAI,MAAM;CAalB"}

package/dist/abilities/AbilityCache.js

@@ -0,0 +1,285 @@
+/**
+ * Ability Cache
+ *
+ * Smart caching with composite keys to handle complex scenarios:
+ * - Same ability name, different transports
+ * - Same ability name, different versions
+ * - Same ability name, different brokers
+ *
+ * @module abilities/AbilityCache
+ */
+/**
+ * Ability Cache
+ *
+ * Intelligent caching that avoids loading same ability multiple times,
+ * while correctly handling scenarios where same name ≠ same ability.
+ *
+ * **Why Composite Keys?**
+ *
+ * Consider:
+ * ```typescript
+ * const local = await client.load('calc', { transport: 'native' });
+ * const remote = await client.load('calc', { transport: 'broker' });
+ * ```
+ *
+ * These are DIFFERENT abilities (different implementations, different transports)
+ * despite having same name. Cache must treat them separately!
+ *
+ * @example
+ * ```typescript
+ * const cache = new AbilityCache();
+ *
+ * // Store ability
+ * cache.set({ name: 'calc', transport: 'broker' }, ability);
+ *
+ * // Retrieve ability
+ * const cached = cache.get({ name: 'calc', transport: 'broker' });
+ *
+ * // Different transport = different cache entry
+ * const notFound = cache.get({ name: 'calc', transport: 'native' });
+ * // Returns undefined (different transport)
+ * ```
+ */
+export class AbilityCache {
+    /**
+     * Internal cache storage
+     *
+     * Key: composite string (name:transport:version:broker)
+     * Value: loaded ability instance
+     */
+    cache = new Map();
+    /**
+     * Generate composite cache key from components
+     *
+     * Format: `name:transport[:version][:broker]`
+     *
+     * Optional components only included if present:
+     * - Basic: "calculator:broker"
+     * - With version: "calculator:broker:2.0.0"
+     * - With broker: "calculator:broker::main-broker"
+     * - Full: "calculator:broker:2.0.0:main-broker"
+     *
+     * @param key - Cache key components
+     * @returns Composite key string
+     *
+     * @example
+     * ```typescript
+     * generateKey({ name: 'calc', transport: 'broker' })
+     * // Returns: "calc:broker"
+     *
+     * generateKey({ name: 'calc', transport: 'broker', version: '2.0.0' })
+     * // Returns: "calc:broker:2.0.0"
+     * ```
+     */
+    generateKey(key) {
+        // Step 1: Start with required components
+        const parts = [key.name, key.transport];
+        // Step 2: Add optional version if present
+        if (key.version) {
+            parts.push(key.version);
+        }
+        else if (key.broker) {
+            // If broker but no version, add empty slot to maintain structure
+            parts.push('');
+        }
+        // Step 3: Add optional broker if present
+        if (key.broker) {
+            parts.push(key.broker);
+        }
+        // Step 4: Join with separator
+        return parts.join(':');
+    }
+    /**
+     * Get cached ability
+     *
+     * Returns cached instance if exists and still connected.
+     * Returns undefined if not cached or disconnected.
+     *
+     * @param key - Cache key components
+     * @returns Cached ability or undefined
+     *
+     * @example
+     * ```typescript
+     * const ability = cache.get({
+     *   name: 'calculator',
+     *   transport: 'broker'
+     * });
+     *
+     * if (ability) {
+     *   // Cache hit! Use cached ability
+     *   await ability.add({ a: 5, b: 3 });
+     * } else {
+     *   // Cache miss - need to load
+     * }
+     * ```
+     */
+    get(key) {
+        // Step 1: Generate composite key
+        const cacheKey = this.generateKey(key);
+        // Step 2: Retrieve from cache
+        const ability = this.cache.get(cacheKey);
+        // Step 3: Validate still connected (defensive check)
+        if (ability && !ability.__isConnected()) {
+            // Disconnected ability - remove from cache
+            this.cache.delete(cacheKey);
+            return undefined;
+        }
+        // Step 4: Return cached ability
+        return ability;
+    }
+    /**
+     * Store ability in cache
+     *
+     * Overwrites existing entry if present.
+     *
+     * @param key - Cache key components
+     * @param ability - Loaded ability to cache
+     *
+     * @example
+     * ```typescript
+     * cache.set(
+     *   { name: 'calculator', transport: 'broker', version: '2.0.0' },
+     *   loadedAbility
+     * );
+     * ```
+     */
+    set(key, ability) {
+        // Step 1: Generate composite key
+        const cacheKey = this.generateKey(key);
+        // Step 2: Store in cache
+        this.cache.set(cacheKey, ability);
+    }
+    /**
+     * Check if ability exists in cache
+     *
+     * Returns true only if cached AND still connected.
+     *
+     * @param key - Cache key components
+     * @returns true if cached and connected
+     *
+     * @example
+     * ```typescript
+     * if (cache.has({ name: 'calc', transport: 'broker' })) {
+     *   // Can safely use cached version
+     * }
+     * ```
+     */
+    has(key) {
+        return this.get(key) !== undefined;
+    }
+    /**
+     * Remove ability from cache
+     *
+     * @param key - Cache key components
+     * @returns true if was cached (now removed), false if wasn't cached
+     *
+     * @example
+     * ```typescript
+     * cache.delete({ name: 'calc', transport: 'broker' });
+     * ```
+     */
+    delete(key) {
+        // Step 1: Generate composite key
+        const cacheKey = this.generateKey(key);
+        // Step 2: Remove from cache
+        return this.cache.delete(cacheKey);
+    }
+    /**
+     * Clear all cached abilities
+     *
+     * Removes everything from cache.
+     * Usually called during client disconnect/cleanup.
+     *
+     * @example
+     * ```typescript
+     * cache.clear();
+     * ```
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get all cached abilities
+     *
+     * Returns array of all cached ability instances.
+     * Useful for bulk operations like disconnect.
+     *
+     * @returns Array of loaded abilities
+     *
+     * @example
+     * ```typescript
+     * // Disconnect all cached abilities
+     * for (const ability of cache.getAll()) {
+     *   await ability.__disconnect();
+     * }
+     * ```
+     */
+    getAll() {
+        return Array.from(this.cache.values());
+    }
+    /**
+     * Get cache statistics
+     *
+     * Returns info about cache state for debugging/monitoring.
+     *
+     * @returns Cache statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = cache.getStats();
+     * console.log(`Cached: ${stats.totalCached}, Connected: ${stats.connected}`);
+     * ```
+     */
+    getStats() {
+        let connected = 0;
+        let disconnected = 0;
+        const byTransport = {
+            broker: 0,
+            native: 0,
+            stdio: 0
+        };
+        // Analyze cache contents
+        for (const ability of this.cache.values()) {
+            if (ability.__isConnected()) {
+                connected++;
+            }
+            else {
+                disconnected++;
+            }
+            const transport = ability.__transport;
+            byTransport[transport] = (byTransport[transport] || 0) + 1;
+        }
+        return {
+            totalCached: this.cache.size,
+            connected,
+            disconnected,
+            byTransport: byTransport
+        };
+    }
+    /**
+     * Cleanup disconnected abilities
+     *
+     * Removes abilities that are no longer connected.
+     * Returns number of entries removed.
+     *
+     * @returns Number of stale entries removed
+     *
+     * @example
+     * ```typescript
+     * const removed = cache.cleanup();
+     * console.log(`Removed ${removed} disconnected abilities`);
+     * ```
+     */
+    cleanup() {
+        let removed = 0;
+        // Find and remove disconnected abilities
+        for (const [key, ability] of this.cache.entries()) {
+            if (!ability.__isConnected()) {
+                this.cache.delete(key);
+                removed++;
+            }
+        }
+        return removed;
+    }
+}
+//# sourceMappingURL=AbilityCache.js.map

package/dist/abilities/AbilityCache.js.map

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