@nitrostack/core 1.0.0

package/dist/core/component.d.ts

@@ -0,0 +1,111 @@
+import { ExecutionContext } from './types.js';
+/**
+ * Component metadata for UI rendering
+ */
+export interface ComponentMetadata {
+    /** Unique identifier for the component */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of what the component displays */
+    description?: string;
+    /** HTML content or path to HTML file */
+    html: string;
+    /** CSS content or path to CSS file */
+    css?: string;
+    /** JavaScript content or path to JS file */
+    js?: string;
+    /** Whether component can initiate tool calls */
+    canInvokeTools?: boolean;
+    /** Content Security Policy domains */
+    csp?: {
+        connectDomains?: string[];
+        resourceDomains?: string[];
+    };
+    /** Custom subdomain for component rendering */
+    subdomain?: string;
+    /** Whether to show border around component */
+    prefersBorder?: boolean;
+    /** Provider-specific metadata */
+    providerMetadata?: Record<string, unknown>;
+    /** Internal metadata (not exposed to MCP) */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Component definition
+ */
+export interface ComponentDefinition extends ComponentMetadata {
+    /** Data transformation function for structuredContent */
+    transformer?: (data: unknown, context: ExecutionContext) => unknown;
+    /** Data transformation function for _meta (widget state) */
+    metaTransformer?: (data: unknown, context: ExecutionContext) => unknown;
+    /** Component initialization logic */
+    onInit?: (context: ExecutionContext) => void | Promise<void>;
+}
+/**
+ * Component class for defining UI components
+ */
+export declare class Component {
+    private definition;
+    private compiled;
+    private bundle;
+    constructor(definition: ComponentDefinition);
+    private validateDefinition;
+    /**
+     * Get component ID
+     */
+    get id(): string;
+    /**
+     * Get component name
+     */
+    get name(): string;
+    /**
+     * Get component description
+     */
+    get description(): string | undefined;
+    /**
+     * Compile component bundle
+     */
+    compile(): Promise<void>;
+    /**
+     * Get compiled bundle as HTML document
+     */
+    getBundle(): string;
+    /**
+     * Get component URI for resource registration
+     */
+    getResourceUri(): string;
+    /**
+     * Check if component is in dev mode
+     */
+    isDevMode(): boolean;
+    /**
+     * Get dev URL if in dev mode
+     */
+    getDevUrl(): string | null;
+    /**
+     * Transform data for component
+     */
+    transformData(data: unknown, context: ExecutionContext): Promise<unknown>;
+    /**
+     * Get widget metadata (state)
+     */
+    getWidgetMeta(data: unknown, context: ExecutionContext): Promise<unknown>;
+    /**
+     * Get provider-specific metadata
+     */
+    getProviderMetadata(provider: 'openai' | 'anthropic' | 'generic'): Record<string, unknown>;
+    /**
+     * Get resource metadata for MCP
+     */
+    getResourceMetadata(): Record<string, unknown>;
+    /**
+     * Initialize component
+     */
+    initialize(context: ExecutionContext): Promise<void>;
+}
+/**
+ * Helper function to create a component
+ */
+export declare function createComponent(definition: ComponentDefinition): Component;
+//# sourceMappingURL=component.d.ts.map

package/dist/core/component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/core/component.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IAEX,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IAEb,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IAEb,sCAAsC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,4CAA4C;IAC5C,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ,gDAAgD;IAChD,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB,sCAAsC;IACtC,GAAG,CAAC,EAAE;QACJ,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;KAC5B,CAAC;IAEF,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,iCAAiC;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE3C,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,iBAAiB;IAC5D,yDAAyD;IACzD,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC;IAEpE,4DAA4D;IAC5D,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC;IAExE,qCAAqC;IACrC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAED;;GAEG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,UAAU,CAAsB;IACxC,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,MAAM,CAIG;gBAEL,UAAU,EAAE,mBAAmB;IAK3C,OAAO,CAAC,kBAAkB;IAa1B;;OAEG;IACH,IAAI,EAAE,IAAI,MAAM,CAEf;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,GAAG,SAAS,CAEpC;IAED;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAoD9B;;OAEG;IACH,SAAS,IAAI,MAAM;IAoBnB;;OAEG;IACH,cAAc,IAAI,MAAM;IAQxB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,SAAS,IAAI,MAAM,GAAG,IAAI;IAK1B;;OAEG;IACG,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAO/E;;OAEG;IACG,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAS/E;;OAEG;IACH,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAiD1F;;OAEG;IACH,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAoB9C;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAK3D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,mBAAmB,GAAG,SAAS,CAE1E"}

package/dist/core/component.js

@@ -0,0 +1,228 @@
+/**
+ * Component class for defining UI components
+ */
+export class Component {
+    definition;
+    compiled = false;
+    bundle = { html: '' };
+    constructor(definition) {
+        this.definition = definition;
+        this.validateDefinition();
+    }
+    validateDefinition() {
+        if (!this.definition.id) {
+            throw new Error('Component ID is required');
+        }
+        if (!this.definition.name) {
+            throw new Error('Component name is required');
+        }
+        // HTML is required unless we are in dev mode or using static exports
+        if (!this.definition.html && !this.definition._meta?.devMode) {
+            // We'll check for static files during compile
+        }
+    }
+    /**
+     * Get component ID
+     */
+    get id() {
+        return this.definition.id;
+    }
+    /**
+     * Get component name
+     */
+    get name() {
+        return this.definition.name;
+    }
+    /**
+     * Get component description
+     */
+    get description() {
+        return this.definition.description;
+    }
+    /**
+     * Compile component bundle
+     */
+    async compile() {
+        if (this.compiled)
+            return;
+        // Check if we should load from static export (esbuild output)
+        // We assume the widgets are built to src/widgets/out
+        // and the file name corresponds to the component ID (e.g. id="weather" -> weather.html)
+        const fs = await import('fs');
+        const path = await import('path');
+        const widgetsOutDir = path.resolve(process.cwd(), 'src/widgets/out');
+        // Try exact ID first
+        let componentHtmlPath = path.join(widgetsOutDir, `${this.id}.html`);
+        // If not found and ID starts with 'next-', try without the prefix
+        // This handles the case where createComponentFromNextRoute adds 'next-' prefix
+        // but the actual file is named without it (e.g., calculator-result.html)
+        if (!fs.existsSync(componentHtmlPath) && this.id.startsWith('next-')) {
+            const idWithoutPrefix = this.id.substring(5); // Remove 'next-' prefix
+            componentHtmlPath = path.join(widgetsOutDir, `${idWithoutPrefix}.html`);
+        }
+        if (fs.existsSync(componentHtmlPath)) {
+            try {
+                // The esbuild bundler already creates self-contained HTML files
+                // with all JavaScript and CSS inlined, so we just read the file
+                const htmlContent = fs.readFileSync(componentHtmlPath, 'utf-8');
+                this.bundle = {
+                    html: htmlContent
+                };
+                this.compiled = true;
+                return;
+            }
+            catch (err) {
+                console.warn(`Failed to read widget file for ${this.id}:`, err);
+            }
+        }
+        // Fallback to inline definition
+        this.bundle = {
+            html: this.definition.html || '',
+            css: this.definition.css,
+            js: this.definition.js,
+        };
+        if (!this.bundle.html && !this.definition._meta?.devMode) {
+            console.warn(`Warning: Component ${this.id} has no HTML content and no static file found at ${componentHtmlPath}`);
+        }
+        this.compiled = true;
+    }
+    /**
+     * Get compiled bundle as HTML document
+     */
+    getBundle() {
+        if (!this.compiled) {
+            throw new Error('Component not compiled. Call compile() first.');
+        }
+        const cssTag = this.bundle.css
+            ? `<style>${this.bundle.css}</style>`
+            : '';
+        const jsTag = this.bundle.js
+            ? `<script type="module">${this.bundle.js}</script>`
+            : '';
+        return `
+${this.bundle.html}
+${cssTag}
+${jsTag}
+    `.trim();
+    }
+    /**
+     * Get component URI for resource registration
+     */
+    getResourceUri() {
+        // In dev mode, return the dev URL if available
+        if (this.definition._meta?.devMode && this.definition._meta?.devUrl) {
+            return String(this.definition._meta.devUrl);
+        }
+        return `ui://widget/${this.definition.id}.html`;
+    }
+    /**
+     * Check if component is in dev mode
+     */
+    isDevMode() {
+        return this.definition._meta?.devMode === true;
+    }
+    /**
+     * Get dev URL if in dev mode
+     */
+    getDevUrl() {
+        const devUrl = this.definition._meta?.devUrl;
+        return devUrl ? String(devUrl) : null;
+    }
+    /**
+     * Transform data for component
+     */
+    async transformData(data, context) {
+        if (this.definition.transformer) {
+            return await this.definition.transformer(data, context);
+        }
+        return data;
+    }
+    /**
+     * Get widget metadata (state)
+     */
+    async getWidgetMeta(data, context) {
+        if (this.definition.metaTransformer) {
+            return await this.definition.metaTransformer(data, context);
+        }
+        // Default: return empty object or maybe the data itself if appropriate?
+        // For now, let's return null so the server knows there's no specific meta
+        return null;
+    }
+    /**
+     * Get provider-specific metadata
+     */
+    getProviderMetadata(provider) {
+        const metadata = {};
+        switch (provider) {
+            case 'openai':
+                metadata['openai/outputTemplate'] = this.getResourceUri();
+                metadata['openai/widgetAccessible'] = this.definition.canInvokeTools || false;
+                if (this.definition.description) {
+                    metadata['openai/widgetDescription'] = this.definition.description;
+                }
+                if (this.definition.prefersBorder) {
+                    metadata['openai/widgetPrefersBorder'] = true;
+                }
+                if (this.definition.subdomain) {
+                    metadata['openai/widgetDomain'] = this.definition.subdomain;
+                }
+                if (this.definition.csp) {
+                    metadata['openai/widgetCSP'] = {
+                        connect_domains: this.definition.csp.connectDomains || [],
+                        resource_domains: this.definition.csp.resourceDomains || [],
+                    };
+                }
+                break;
+            case 'anthropic':
+                // Future: Anthropic-specific metadata
+                metadata['anthropic/ui'] = this.getResourceUri();
+                break;
+            case 'generic':
+            default:
+                // Generic provider metadata
+                metadata['ui/template'] = this.getResourceUri();
+                metadata['ui/interactive'] = this.definition.canInvokeTools || false;
+                break;
+        }
+        // Merge with custom provider metadata
+        if (this.definition.providerMetadata) {
+            Object.assign(metadata, this.definition.providerMetadata);
+        }
+        return metadata;
+    }
+    /**
+     * Get resource metadata for MCP
+     */
+    getResourceMetadata() {
+        const metadata = {
+            mimeType: 'text/html',
+        };
+        // Add OpenAI-specific metadata
+        const openaiMeta = this.getProviderMetadata('openai');
+        if (openaiMeta['openai/widgetCSP']) {
+            metadata['openai/widgetCSP'] = openaiMeta['openai/widgetCSP'];
+        }
+        if (openaiMeta['openai/widgetDescription']) {
+            metadata['openai/widgetDescription'] = openaiMeta['openai/widgetDescription'];
+        }
+        if (openaiMeta['openai/widgetPrefersBorder']) {
+            metadata['openai/widgetPrefersBorder'] = openaiMeta['openai/widgetPrefersBorder'];
+        }
+        return metadata;
+    }
+    /**
+     * Initialize component
+     */
+    async initialize(context) {
+        if (this.definition.onInit) {
+            await this.definition.onInit(context);
+        }
+    }
+}
+/**
+ * Helper function to create a component
+ */
+export function createComponent(definition) {
+    return new Component(definition);
+}
+//# sourceMappingURL=component.js.map

package/dist/core/component.js.map

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

package/dist/core/config-module.d.ts

@@ -0,0 +1,62 @@
+import 'reflect-metadata';
+/**
+ * Configuration Module Options
+ */
+export interface ConfigModuleOptions {
+    /**
+     * Path to .env file (relative to project root)
+     */
+    envFilePath?: string;
+    /**
+     * Whether to ignore .env file if it doesn't exist
+     */
+    ignoreEnvFile?: boolean;
+    /**
+     * Whether to validate environment variables
+     */
+    validate?: (config: Record<string, any>) => boolean;
+    /**
+     * Default values for environment variables
+     */
+    defaults?: Record<string, string>;
+}
+/**
+ * Configuration Service
+ * Provides type-safe access to environment variables
+ */
+export declare class ConfigService {
+    private config;
+    constructor(options?: ConfigModuleOptions);
+    /**
+     * Get a configuration value
+     */
+    get<T = string>(key: string): T | undefined;
+    get<T = string>(key: string, defaultValue: T): T;
+    /**
+     * Get a required configuration value
+     * Throws if not found
+     */
+    getOrThrow<T = string>(key: string): T;
+    /**
+     * Get all configuration
+     */
+    getAll(): Record<string, string>;
+}
+/**
+ * Dynamic module result type
+ */
+export interface DynamicModuleResult {
+    providers: Array<{
+        provide: any;
+        useValue: unknown;
+    }>;
+    exports: any[];
+}
+/**
+ * Configuration Module
+ * NestJS-style configuration management
+ */
+export declare class ConfigModule {
+    static forRoot(options?: ConfigModuleOptions): DynamicModuleResult;
+}
+//# sourceMappingURL=config-module.d.ts.map

package/dist/core/config-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-module.d.ts","sourceRoot":"","sources":["../../src/core/config-module.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAI1B;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,OAAO,CAAC;IAEpD;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAyCD;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAyB;gBAE3B,OAAO,GAAE,mBAAwB;IAqB7C;;OAEG;IACH,GAAG,CAAC,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAC3C,GAAG,CAAC,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,GAAG,CAAC;IAShD;;;OAGG;IACH,UAAU,CAAC,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC;IAQtC;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAGjC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAElC,SAAS,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,GAAG,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAEtD,OAAO,EAAE,GAAG,EAAE,CAAC;CAChB;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,mBAAwB,GAAG,mBAAmB;CAQvE"}

package/dist/core/config-module.js

@@ -0,0 +1,94 @@
+import 'reflect-metadata';
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * Parse .env file manually to avoid stdout pollution
+ * (dotenv.config() can write to stdout which breaks MCP stdio protocol)
+ */
+function parseEnvFile(filePath) {
+    const envVars = {};
+    if (!fs.existsSync(filePath)) {
+        return envVars;
+    }
+    const content = fs.readFileSync(filePath, 'utf-8');
+    content.split('\n').forEach(line => {
+        line = line.trim();
+        // Skip empty lines and comments
+        if (!line || line.startsWith('#')) {
+            return;
+        }
+        // Parse KEY=VALUE
+        const [key, ...valueParts] = line.split('=');
+        if (key && valueParts.length > 0) {
+            let value = valueParts.join('=').trim();
+            // Remove quotes if present
+            if ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'"))) {
+                value = value.slice(1, -1);
+            }
+            envVars[key.trim()] = value;
+        }
+    });
+    return envVars;
+}
+/**
+ * Configuration Service
+ * Provides type-safe access to environment variables
+ */
+export class ConfigService {
+    config;
+    constructor(options = {}) {
+        this.config = { ...options.defaults };
+        // Load environment variables from .env file
+        if (!options.ignoreEnvFile) {
+            const envPath = options.envFilePath || '.env';
+            const fullPath = path.resolve(process.cwd(), envPath);
+            const parsed = parseEnvFile(fullPath);
+            this.config = { ...this.config, ...parsed };
+        }
+        // Merge with process.env (already loaded by Studio)
+        this.config = { ...this.config, ...process.env };
+        // Validate if validator provided
+        if (options.validate && !options.validate(this.config)) {
+            throw new Error('Environment variable validation failed');
+        }
+    }
+    get(key, defaultValue) {
+        const value = this.config[key];
+        if (value === undefined) {
+            return defaultValue;
+        }
+        return value;
+    }
+    /**
+     * Get a required configuration value
+     * Throws if not found
+     */
+    getOrThrow(key) {
+        const value = this.get(key);
+        if (value === undefined) {
+            throw new Error(`Configuration key "${key}" is required but not found`);
+        }
+        return value;
+    }
+    /**
+     * Get all configuration
+     */
+    getAll() {
+        return { ...this.config };
+    }
+}
+/**
+ * Configuration Module
+ * NestJS-style configuration management
+ */
+export class ConfigModule {
+    static forRoot(options = {}) {
+        const configService = new ConfigService(options);
+        return {
+            providers: [{ provide: ConfigService, useValue: configService }],
+            exports: [ConfigService],
+        };
+    }
+}
+//# sourceMappingURL=config-module.js.map

package/dist/core/config-module.js.map

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

package/dist/core/decorators/cache.decorator.d.ts

@@ -0,0 +1,61 @@
+import 'reflect-metadata';
+/**
+ * Cache options
+ */
+export interface CacheOptions {
+    /** Time to live in seconds */
+    ttl: number;
+    /** Custom cache key generator */
+    key?: (input: unknown, context: unknown) => string;
+    /** Cache storage (default: in-memory) */
+    storage?: CacheStorage;
+}
+/**
+ * Cache storage interface
+ */
+export interface CacheStorage {
+    get(key: string): Promise<unknown> | unknown;
+    set(key: string, value: unknown, ttl: number): Promise<void> | void;
+    delete(key: string): Promise<void> | void;
+    clear(): Promise<void> | void;
+}
+/**
+ * Default in-memory cache storage
+ */
+export declare class InMemoryCacheStorage implements CacheStorage {
+    private cache;
+    get(key: string): unknown;
+    set(key: string, value: unknown, ttl: number): void;
+    delete(key: string): void;
+    clear(): void;
+    private cleanup;
+}
+/**
+ * Cache decorator - caches tool results for a specified duration
+ *
+ * @example
+ * ```typescript
+ * @Tool({ name: 'get_products', ... })
+ * @Cache({ ttl: 300 }) // Cache for 5 minutes
+ * async getProducts(input: unknown) {
+ *   return await this.database.query('SELECT * FROM products');
+ * }
+ *
+ * // With custom cache key
+ * @Cache({
+ *   ttl: 300,
+ *   key: (input) => `products:${(input as {category: string}).category}`
+ * })
+ * async getProducts(input: unknown) { }
+ * ```
+ */
+export declare function Cache(options: CacheOptions): MethodDecorator;
+/**
+ * Get cache options from metadata
+ */
+export declare function getCacheMetadata(target: object, propertyKey: string | symbol): CacheOptions | undefined;
+/**
+ * Clear cache for a specific key or all keys
+ */
+export declare function clearCache(key?: string): Promise<void>;
+//# sourceMappingURL=cache.decorator.d.ts.map

package/dist/core/decorators/cache.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.decorator.d.ts","sourceRoot":"","sources":["../../../src/core/decorators/cache.decorator.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAI1B;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,8BAA8B;IAC9B,GAAG,EAAE,MAAM,CAAC;IAEZ,iCAAiC;IACjC,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC;IAEnD,yCAAyC;IACzC,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IAC7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC/B;AAED;;GAEG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,KAAK,CAA0D;IAEvE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAYzB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAOnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,KAAK,IAAI,IAAI;IAKb,OAAO,CAAC,OAAO;CAQhB;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,eAAe,CA4C5D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,YAAY,GAAG,SAAS,CAEvG;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM5D"}