@microsoft/terraform-cdk-constructs 0.0.3-pre.6 → 1.0.0

package/lib/core-azure/lib/index.d.ts

@@ -1,3 +1,18 @@
-export * from "./diagsettings";
-export * from "./rbac";
-export * from "./resource";
+/**
+ * Core Azure AZAPI functionality
+ *
+ * This module provides the foundational classes and utilities for AZAPI-based Azure constructs:
+ *
+ * - VersionedAzapiResource: Unified framework base class with automatic version management
+ * - ApiVersionManager: Singleton for centralized version management
+ * - SchemaMapper: Property transformation and validation engine
+ * - Version management utilities and interfaces
+ * - AZAPI provider integrations
+ */
+export * from "./azapi/azapi-resource";
+export * from "./version-manager/api-version-manager";
+export * from "./azapi/schema-mapper/schema-mapper";
+export * from "./version-manager/interfaces/version-interfaces";
+import * as azapiProviders from "./azapi/providers-azapi";
+export { azapiProviders };
+export * from "./azapi/azapi-exports";

package/lib/core-azure/lib/index.js

@@ -1,4 +1,15 @@
 "use strict";
+/**
+ * Core Azure AZAPI functionality
+ *
+ * This module provides the foundational classes and utilities for AZAPI-based Azure constructs:
+ *
+ * - VersionedAzapiResource: Unified framework base class with automatic version management
+ * - ApiVersionManager: Singleton for centralized version management
+ * - SchemaMapper: Property transformation and validation engine
+ * - Version management utilities and interfaces
+ * - AZAPI provider integrations
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -14,7 +25,16 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./diagsettings"), exports);
-__exportStar(require("./rbac"), exports);
-__exportStar(require("./resource"), exports);
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvY29yZS1henVyZS9saWIvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7OztBQUFBLGlEQUErQjtBQUMvQix5Q0FBdUI7QUFDdkIsNkNBQTJCIiwic291cmNlc0NvbnRlbnQiOlsiZXhwb3J0ICogZnJvbSBcIi4vZGlhZ3NldHRpbmdzXCI7XG5leHBvcnQgKiBmcm9tIFwiLi9yYmFjXCI7XG5leHBvcnQgKiBmcm9tIFwiLi9yZXNvdXJjZVwiO1xuIl19
+exports.azapiProviders = void 0;
+// Export unified AZAPI resource class
+__exportStar(require("./azapi/azapi-resource"), exports);
+__exportStar(require("./version-manager/api-version-manager"), exports);
+__exportStar(require("./azapi/schema-mapper/schema-mapper"), exports);
+// Export version management interfaces
+__exportStar(require("./version-manager/interfaces/version-interfaces"), exports);
+// Export AZAPI provider components with namespace prefix to avoid conflicts
+const azapiProviders = require("./azapi/providers-azapi");
+exports.azapiProviders = azapiProviders;
+// Export convenience imports for commonly used classes
+__exportStar(require("./azapi/azapi-exports"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvY29yZS1henVyZS9saWIvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IjtBQUFBOzs7Ozs7Ozs7O0dBVUc7Ozs7Ozs7Ozs7Ozs7Ozs7O0FBRUgsc0NBQXNDO0FBQ3RDLHlEQUF1QztBQUN2Qyx3RUFBc0Q7QUFDdEQsc0VBQW9EO0FBRXBELHVDQUF1QztBQUN2QyxrRkFBZ0U7QUFFaEUsNEVBQTRFO0FBQzVFLDBEQUEwRDtBQUNqRCx3Q0FBYztBQUV2Qix1REFBdUQ7QUFDdkQsd0RBQXNDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBDb3JlIEF6dXJlIEFaQVBJIGZ1bmN0aW9uYWxpdHlcbiAqXG4gKiBUaGlzIG1vZHVsZSBwcm92aWRlcyB0aGUgZm91bmRhdGlvbmFsIGNsYXNzZXMgYW5kIHV0aWxpdGllcyBmb3IgQVpBUEktYmFzZWQgQXp1cmUgY29uc3RydWN0czpcbiAqXG4gKiAtIFZlcnNpb25lZEF6YXBpUmVzb3VyY2U6IFVuaWZpZWQgZnJhbWV3b3JrIGJhc2UgY2xhc3Mgd2l0aCBhdXRvbWF0aWMgdmVyc2lvbiBtYW5hZ2VtZW50XG4gKiAtIEFwaVZlcnNpb25NYW5hZ2VyOiBTaW5nbGV0b24gZm9yIGNlbnRyYWxpemVkIHZlcnNpb24gbWFuYWdlbWVudFxuICogLSBTY2hlbWFNYXBwZXI6IFByb3BlcnR5IHRyYW5zZm9ybWF0aW9uIGFuZCB2YWxpZGF0aW9uIGVuZ2luZVxuICogLSBWZXJzaW9uIG1hbmFnZW1lbnQgdXRpbGl0aWVzIGFuZCBpbnRlcmZhY2VzXG4gKiAtIEFaQVBJIHByb3ZpZGVyIGludGVncmF0aW9uc1xuICovXG5cbi8vIEV4cG9ydCB1bmlmaWVkIEFaQVBJIHJlc291cmNlIGNsYXNzXG5leHBvcnQgKiBmcm9tIFwiLi9hemFwaS9hemFwaS1yZXNvdXJjZVwiO1xuZXhwb3J0ICogZnJvbSBcIi4vdmVyc2lvbi1tYW5hZ2VyL2FwaS12ZXJzaW9uLW1hbmFnZXJcIjtcbmV4cG9ydCAqIGZyb20gXCIuL2F6YXBpL3NjaGVtYS1tYXBwZXIvc2NoZW1hLW1hcHBlclwiO1xuXG4vLyBFeHBvcnQgdmVyc2lvbiBtYW5hZ2VtZW50IGludGVyZmFjZXNcbmV4cG9ydCAqIGZyb20gXCIuL3ZlcnNpb24tbWFuYWdlci9pbnRlcmZhY2VzL3ZlcnNpb24taW50ZXJmYWNlc1wiO1xuXG4vLyBFeHBvcnQgQVpBUEkgcHJvdmlkZXIgY29tcG9uZW50cyB3aXRoIG5hbWVzcGFjZSBwcmVmaXggdG8gYXZvaWQgY29uZmxpY3RzXG5pbXBvcnQgKiBhcyBhemFwaVByb3ZpZGVycyBmcm9tIFwiLi9hemFwaS9wcm92aWRlcnMtYXphcGlcIjtcbmV4cG9ydCB7IGF6YXBpUHJvdmlkZXJzIH07XG5cbi8vIEV4cG9ydCBjb252ZW5pZW5jZSBpbXBvcnRzIGZvciBjb21tb25seSB1c2VkIGNsYXNzZXNcbmV4cG9ydCAqIGZyb20gXCIuL2F6YXBpL2F6YXBpLWV4cG9ydHNcIjtcbiJdfQ==

package/lib/core-azure/lib/version-manager/api-version-manager.d.ts

@@ -0,0 +1,253 @@
+/**
+ * ApiVersionManager - A JSII-compliant singleton for managing Azure API versions
+ *
+ * This class provides centralized version management for Azure resources, including:
+ * - Version registry and metadata storage
+ * - Version resolution and compatibility analysis
+ * - Migration analysis between versions
+ * - Thread-safe singleton operations
+ *
+ * The singleton pattern is implemented in a JSII-compliant way using instance methods
+ * rather than static classes to ensure multi-language compatibility.
+ *
+ * @packageDocumentation
+ */
+import { VersionConfig, MigrationAnalysis, VersionLifecycle, VersionConstraints } from "./interfaces/version-interfaces";
+/**
+ * ApiVersionManager singleton class for centralized version management
+ *
+ * This class manages API versions for Azure resources, providing version resolution,
+ * compatibility analysis, and migration guidance. It implements a JSII-compliant
+ * singleton pattern for thread-safe operations across multiple language bindings.
+ *
+ * Key Features:
+ * - Thread-safe singleton implementation
+ * - Version registry management with full lifecycle support
+ * - Advanced version resolution with constraint-based selection
+ * - Comprehensive migration analysis with effort estimation
+ * - Extensive validation and error handling
+ *
+ * @example
+ * const manager = ApiVersionManager.getInstance();
+ * manager.registerResourceType('Microsoft.Resources/resourceGroups', versions);
+ * const latest = manager.getLatestVersion('Microsoft.Resources/resourceGroups');
+ * const analysis = manager.analyzeMigration('Microsoft.Resources/resourceGroups', '2024-01-01', '2024-11-01');
+ *
+ * @stability stable
+ */
+export declare class ApiVersionManager {
+    /**
+     * Gets the singleton instance of ApiVersionManager
+     *
+     * This method implements a thread-safe singleton pattern that's compatible
+     * with JSII multi-language bindings. The instance is lazily created on
+     * first access and reused for all subsequent calls.
+     *
+     * @returns The singleton ApiVersionManager instance
+     *
+     * @example
+     * const manager = ApiVersionManager.instance();
+     */
+    static instance(): ApiVersionManager;
+    private static _instance;
+    private readonly _resourceRegistry;
+    /**
+     * Private constructor to enforce singleton pattern
+     * Initializes the internal registries and data structures
+     */
+    private constructor();
+    /**
+     * Registers a resource type with its version configurations
+     *
+     * This method stores version metadata for a specific Azure resource type,
+     * including schemas, lifecycle information, and migration data. It validates
+     * the input and maintains internal indexes for efficient lookups.
+     *
+     * @param resourceType - The Azure resource type (e.g., 'Microsoft.Resources/resourceGroups')
+     * @param versions - Array of version configurations for the resource type
+     *
+     * @throws Error if resourceType is empty or versions array is empty
+     * @throws Error if duplicate versions are found in the versions array
+     * @throws Error if version configurations are invalid
+     *
+     * @example
+     * manager.registerResourceType('Microsoft.Resources/resourceGroups', [
+     *   {
+     *     version: '2024-01-01',
+     *     schema: { resourceType: 'Microsoft.Resources/resourceGroups', version: '2024-01-01', properties: {}, required: [] },
+     *     supportLevel: VersionSupportLevel.ACTIVE,
+     *     releaseDate: '2024-01-01'
+     *   }
+     * ]);
+     */
+    registerResourceType(resourceType: string, versions: VersionConfig[]): void;
+    /**
+     * Gets the latest active version for a resource type
+     *
+     * Returns the most recent version with ACTIVE support level. If no active
+     * versions are found, returns the most recent version regardless of support level.
+     *
+     * @param resourceType - The Azure resource type to get the latest version for
+     * @returns The latest version string, or undefined if the resource type is not registered
+     *
+     * @example
+     * const latest = manager.latestVersion('Microsoft.Resources/resourceGroups');
+     * // Returns: "2024-11-01"
+     */
+    latestVersion(resourceType: string): string | undefined;
+    /**
+     * Gets the configuration for a specific version of a resource type
+     *
+     * Retrieves the complete version configuration including schema, lifecycle
+     * information, breaking changes, and migration metadata.
+     *
+     * @param resourceType - The Azure resource type
+     * @param version - The specific version to retrieve
+     * @returns The version configuration, or undefined if not found
+     *
+     * @example
+     * const config = manager.versionConfig('Microsoft.Resources/resourceGroups', '2024-01-01');
+     * if (config) {
+     *   console.log(`Support level: ${config.supportLevel}`);
+     *   console.log(`Release date: ${config.releaseDate}`);
+     * }
+     */
+    versionConfig(resourceType: string, version: string): VersionConfig | undefined;
+    /**
+     * Gets all supported versions for a resource type
+     *
+     * Returns an array of all registered version strings for the specified
+     * resource type, sorted by release date (newest first).
+     *
+     * @param resourceType - The Azure resource type
+     * @returns Array of supported version strings, empty if resource type not registered
+     *
+     * @example
+     * const versions = manager.supportedVersions('Microsoft.Resources/resourceGroups');
+     * // Returns: ["2024-11-01", "2024-01-01", "2023-07-01"]
+     */
+    supportedVersions(resourceType: string): string[];
+    /**
+     * Analyzes migration requirements between two versions
+     *
+     * Performs comprehensive analysis of the migration path between source and
+     * target versions, including compatibility assessment, breaking changes
+     * identification, effort estimation, and upgrade feasibility.
+     *
+     * @param resourceType - The Azure resource type
+     * @param fromVersion - The source version to migrate from
+     * @param toVersion - The target version to migrate to
+     * @returns Detailed migration analysis results
+     *
+     * @throws Error if either version is not registered for the resource type
+     * @throws Error if resourceType is not registered
+     *
+     * @example
+     * const analysis = manager.analyzeMigration(
+     *   'Microsoft.Resources/resourceGroups',
+     *   '2024-01-01',
+     *   '2024-11-01'
+     * );
+     *
+     * console.log(`Compatible: ${analysis.compatible}`);
+     * console.log(`Effort: ${analysis.estimatedEffort}`);
+     * console.log(`Breaking changes: ${analysis.breakingChanges.length}`);
+     */
+    analyzeMigration(resourceType: string, fromVersion: string, toVersion: string): MigrationAnalysis;
+    /**
+     * Validates whether a version is supported for a resource type
+     *
+     * Checks if the specified version is registered and available for use
+     * with the given resource type.
+     *
+     * @param resourceType - The Azure resource type
+     * @param version - The version to validate
+     * @returns True if the version is supported, false otherwise
+     *
+     * @example
+     * if (manager.validateVersionSupport('Microsoft.Resources/resourceGroups', '2024-01-01')) {
+     *   // Version is supported, proceed with resource creation
+     * } else {
+     *   // Handle unsupported version
+     * }
+     */
+    validateVersionSupport(resourceType: string, version: string): boolean;
+    /**
+     * Gets all registered resource types
+     *
+     * Returns an array of all Azure resource types that have been registered
+     * with the version manager.
+     *
+     * @returns Array of registered resource type strings
+     *
+     * @example
+     * const resourceTypes = manager.registeredResourceTypes();
+     * // Returns: ["Microsoft.Resources/resourceGroups", "Microsoft.Storage/storageAccounts", ...]
+     */
+    registeredResourceTypes(): string[];
+    /**
+     * Gets version lifecycle information for a specific version
+     *
+     * Provides lifecycle metadata including current phase, transition dates,
+     * and projected sunset timeline.
+     *
+     * @param resourceType - The Azure resource type
+     * @param version - The version to get lifecycle information for
+     * @returns Version lifecycle information, or undefined if not found
+     *
+     * @example
+     * const lifecycle = manager.versionLifecycle('Microsoft.Resources/resourceGroups', '2024-01-01');
+     * if (lifecycle) {
+     *   console.log(`Current phase: ${lifecycle.phase}`);
+     *   console.log(`Sunset date: ${lifecycle.estimatedSunsetDate}`);
+     * }
+     */
+    versionLifecycle(resourceType: string, version: string): VersionLifecycle | undefined;
+    /**
+     * Finds the best version matching the given constraints
+     *
+     * Selects the optimal version for a resource type based on specified
+     * constraints such as support level, feature requirements, and age limits.
+     *
+     * @param resourceType - The Azure resource type
+     * @param constraints - Version selection constraints
+     * @returns The best matching version, or undefined if no version matches
+     * @internal
+     *
+     * @example
+     * const version = manager._findVersionByConstraints('Microsoft.Resources/resourceGroups', {
+     *   supportLevel: VersionSupportLevel.ACTIVE,
+     *   excludeDeprecated: true,
+     *   notOlderThan: new Date('2024-01-01')
+     * });
+     */
+    _findVersionByConstraints(resourceType: string, constraints: VersionConstraints): string | undefined;
+    /**
+     * Validates resource type and versions input
+     */
+    private _validateResourceTypeInput;
+    /**
+     * Validates a single version configuration
+     */
+    private _validateVersionConfig;
+    /**
+     * Collects all breaking changes between two versions
+     */
+    private _collectBreakingChanges;
+    /**
+     * Generates migration warnings
+     */
+    private _generateMigrationWarnings;
+    /**
+     * Calculates migration effort based on breaking changes and version differences
+     */
+    private _calculateMigrationEffort;
+    /**
+     * Determines if automatic upgrade is possible
+     */
+    private _canAutoUpgrade;
+    /**
+     * Determines the next phase in the version lifecycle
+     */
+    private _determineNextPhase;
+}