@aerokit/sdk 12.81.0 → 12.82.0

package/dist/dts/db/decorators.d.ts

@@ -1,11 +1,64 @@
 /**
- * * ECMAScript 2025-compliant ORM decorator implementation
+ * @module db/decorators
+ * @package @aerokit/sdk/db
+ * @name Decorators
+ * @overview
+ *
+ * This module provides a set of decorators for defining database entities and their properties in a Dirigible application. The decorators are designed to be compatible with both legacy JavaScript environments (like Mozilla Rhino or older GraalJS) and modern JavaScript environments that support the latest decorator specifications.
+ *
+ * ### Key Features
+ * - **Entity Decorator**: Marks a class as a database entity, allowing it to be registered and managed by the ORM layer.
+ * - **Table Decorator**: Specifies the database table name for the entity, with a default naming convention based on the class name.
+ * - **Column Decorator**: Marks a class property as a database column, with options for column type, length, nullability, and default values.
+ * - **ID Decorator**: Marks a property as the primary key of the entity.
+ * - **Generated Decorator**: Indicates that a property is generated by the database (e.g., auto-increment).
+ * - **Relationship Decorators**: Defines one-to-many and many-to-one relationships between entities.
+ * - **Documentation Decorator**: Adds documentation metadata to classes and properties for better maintainability and clarity.
+ *
+ * ### Use Cases
+ * - Defining database entities in a structured and consistent manner across different tables and relationships.
+ * - Abstracting database interactions to allow for easier maintenance and potential database engine changes in the future.
+ * - Handling complex entity relationships and ensuring data integrity through validation and association management.
+ *
+ * ### Example Usage
+ * ```ts
+ * import { Entity, Table, Column, Id, Generated, OneToMany, ManyToOne, Documentation } from "@aerokit/sdk/db/decorators";
+ *
+ * @Entity('User')
+ * @Table('USERS')
+ * @Documentation('Represents a user in the system')
+ * class User {
+ *   @Id()
+ *   @Generated('IDENTITY')
+ *   @Column({ type: 'integer' })
+ *   id!: number;
+ *
+ *   @Column({ type: 'string', length: 100, nullable: false })
+ *   name!: string;
+ *
+ *   @Column({ type: 'string', length: 255, nullable: false })
+ *   email!: string;
+ *
+ *   @OneToMany(() => Post, { joinColumn: 'user_id', cascade: 'all' })
+ *   posts!: Post[];
+ * }
+ *
+ * @Entity('Post')
+ * @Table('POSTS')
+ * class Post {
+ *   @Id()
+ *   @Generated('IDENTITY')
+ *   @Column({ type: 'integer' })
+ *   id!: number;
+ * }
+ *
+ * ::: info ECMAScript 2025-compliant ORM decorator implementation
  * Compatible with GraalJS runtime.
- * * Features:
  * - Uses context.addInitializer for stable decorator timing
  * - Stores metadata in a global WeakMap cache
  * - Finalizes entity metadata once per class
  * - Defers finalization via microtask (Promise.resolve().then)
+ * :::
  */
 type ClassFieldDecoratorContext = {
     kind: "field";

package/dist/dts/db/index.d.ts

@@ -1,3 +1,22 @@
+/**
+ * @module db/index
+ * @package @aerokit/sdk/db
+ * @overview
+ *
+ * This module provides functionalities for database management within the Aerokit SDK. It includes classes and methods for interacting with databases, executing SQL queries, managing transactions, and working with data repositories.
+ *
+ * The main components of this module are:
+ * - Database: Represents a database connection and provides methods to interact with it, such as executing queries and managing transactions.
+ * - SQLBuilder: Provides a fluent API for building SQL queries programmatically.
+ * - Procedure: Represents a stored procedure in the database and provides methods to execute it.
+ * - Sequence: Represents a database sequence and provides methods to interact with it.
+ * - Query: Represents a database query and provides methods to execute it and retrieve results.
+ * - Update: Represents an update operation in the database and provides methods to execute it.
+ * - Insert: Represents an insert operation in the database and provides methods to execute it.
+ * - Store: Represents a data store that can be used for caching or temporary storage of data.
+ * - Repository: Provides a repository pattern implementation for managing data entities in the database.
+ * - Decorators: Provides decorators for defining database entities, repositories, and other related components in a declarative manner
+ */
 export * as dao from "./dao";
 export * from "./database";
 export { Database as database } from "./database";

package/dist/dts/db/orm.d.ts

@@ -1,3 +1,46 @@
+/**
+ * @module db/orm
+ * @package @aerokit/sdk/db
+ * @name ORM
+ * @overview
+ *
+ * The `ORM` class provides a way to define an Object-Relational Mapping (ORM) schema for a database entity. It allows developers to specify the structure of their entities, including properties, associations, and constraints, in a declarative manner. The ORM definition can then be used by other modules (e.g., `DAO`, `Repository`) to perform database operations while ensuring data integrity and consistency with the defined schema.
+ *
+ * ::: warning
+ * The `ORM` module is deprecated and will be removed in future releases. It is recommended to use the `Repository/Store` modules instead for managing database entities and operations.
+ * :::
+ *
+ * ### Key Features
+ * - **Declarative Schema Definition**: Define your entity's structure, properties, and associations in a clear and structured way.
+ * - **Validation**: The ORM class includes validation logic to ensure that the defined schema is consistent and adheres to expected formats.
+ * - **Association Management**: Supports defining associations between entities (e.g., one-to-one, one-to-many) to model complex relationships in the database.
+ * - **Utility Methods**: Provides methods to retrieve primary keys, mandatory properties, unique properties, and to convert the ORM definition into a table schema format.
+ *
+ * ### Use Cases
+ * - Defining the structure of database entities in a way that can be easily consumed by data access layers.
+ * - Ensuring that database operations are performed in accordance with a well-defined schema, improving data integrity and reducing errors.
+ * - Modeling complex entity relationships through associations, allowing for more sophisticated data interactions.
+ *
+ * ### Example Usage
+ * ```ts
+ * import { ORM } from "@aerokit/sdk/db";
+ *
+ * const userORM = {
+ *  table: "Users",
+ *   properties: [
+ *     { name: "id", column: "ID", type: "INTEGER", id: true, autoIncrement: true },
+ *     { name: "name", column: "NAME", type: "VARCHAR", required: true },
+ *     { name: "email", column: "EMAIL", type: "VARCHAR", unique: true }
+ *  ],
+ *   associations: [
+ *    { name: "profile", joinKey: "PROFILE_ID", type: "one-to-one", targetDao: () => profileDAO }
+ *  ]
+ * };
+ *
+ * const userDAO = new DAO(get(userORM));
+ * // Now you can use userDAO to perform CRUD operations on the Users table while adhering to the defined ORM schema.
+ * ```
+ */
 /**
  * Supported ORM schema:
  * ```

package/dist/dts/db/procedure.d.ts

@@ -1,3 +1,40 @@
+/**
+ * @module db/procedure
+ * @package @aerokit/sdk/db
+ * @name Procedure
+ * @overview
+ *
+ * This module provides a `Procedure` class for executing stored procedures in a database. It allows for both the creation of stored procedures using DDL statements and the execution of existing stored procedures with parameter support. The `execute` method can handle multiple result sets returned by a stored procedure and returns them as an array of JSON objects.
+ *
+ * ### Key Features
+ * - **Create Procedures**: Use the `create` method to execute DDL statements for creating or modifying stored procedures.
+ * - **Execute Procedures**: The `execute` method allows you to call stored procedures with parameters and handles multiple result sets.
+ * - **Parameter Mapping**: Supports both primitive parameters (string and number) and structured parameters using the `ProcedureParameter` interface for explicit type definitions.
+ * - **Resource Management**: Ensures proper closing of database resources (connections, statements, result sets) to prevent leaks.
+ *
+ * ### Use Cases
+ * - Managing complex database operations encapsulated in stored procedures, allowing for cleaner application code and improved performance.
+ * - Handling multiple result sets returned by stored procedures, which is common in scenarios like reporting or batch processing.
+ * - Providing a flexible parameter mapping mechanism that can accommodate various data types and structures when calling stored procedures.
+ *
+ * ### Example Usage
+ * ```ts
+ * import { Procedure } from "@aerokit/sdk/db";
+ *
+ * // Create a stored procedure
+ * const createSql = `
+ *   CREATE PROCEDURE GetUserById(IN userId INT)
+ *   BEGIN
+ *     SELECT * FROM Users WHERE id = userId;
+ *   END
+ * `;
+ * Procedure.create(createSql);
+ *
+ * // Execute the stored procedure with a parameter
+ * const result = Procedure.execute("{CALL GetUserById(?)}", [1]);
+ * console.log(result); // Output: [{ id: 1, name: "Alice", email: "alice@example.com" }]
+ * ```
+ */
 /**
  * @interface ProcedureParameter
  * @description Defines a structured parameter for procedure calls, allowing the type

package/dist/dts/db/query.d.ts

@@ -1,6 +1,30 @@
 /**
- * API Query
+ * @module db/query
+ * @package @aerokit/sdk/db
+ * @name Query
+ * @overview
  *
+ * This module provides a `Query` class for executing parameterized SQL SELECT statements against a database in the Dirigible environment. The `Query` class supports both positional parameters (using '?' placeholders) and named parameters (using ':paramName' placeholders), allowing for flexible query construction and execution. It also includes options for formatting the result set, such as specifying date formats.
+ *
+ * ### Key Features
+ * - **Parameterized Queries**: Supports both positional and named parameters for secure and efficient query execution.
+ * - **Result Formatting**: Allows for custom formatting of query results, including date formatting options.
+ * - **JSON Input Support**: Accepts parameters as JSON strings or JavaScript arrays, providing flexibility in how parameters are passed to the query.
+ * - **Error Handling**: Provides robust error handling for invalid parameter formats and JSON parsing issues.
+ *
+ * ### Use Cases
+ * - Executing complex SQL queries with dynamic parameters in a secure manner to prevent SQL injection.
+ * - Formatting query results according to specific requirements, such as date formats or custom data transformations.
+ * - Integrating with other modules that generate parameters in JSON format, enabling seamless data flow within the application.
+ *
+ * ### Example Usage
+ * ```ts
+ * import { Query } from "@aerokit/sdk/db";
+ *
+ * // Positional parameters example
+ * const result1 = Query.execute("SELECT * FROM Users WHERE age > ?", [30]);
+ * console.log(result1); // Output: [{ id: 1, name: "Alice", age: 35 }, { id: 2, name: "Bob", age: 40 }]
+ * ```
  */
 /**
  * Interface used to wrap complex or specific values for non-named queries.

package/dist/dts/db/repository.d.ts

@@ -1,3 +1,55 @@
+/**
+ * @module db/repository
+ * @package @aerokit/sdk/db
+ * @name Repository
+ * @overview
+ *
+ * This module provides an abstract `Repository` class that serves as a base for data access and business logic layers in the Dirigible environment. The `Repository` class wraps the underlying `store` API, providing a structured way to perform CRUD operations on entities while also handling entity metadata, translation, and event triggering. It is designed to be extended by specific repositories for different entities, allowing for customization of behavior and event handling.
+ *
+ * ### Key Features
+ * - Abstract base class for repositories with built-in support for entity metadata management.
+ * - CRUD operations (Create, Read, Update, Delete) with automatic translation of results.
+ * - Event triggering mechanism for create, update, and delete operations, allowing for custom logic to be executed in response to these events.
+ * - Type safety through TypeScript generics, ensuring that repositories are strongly typed according to their entity definitions.
+ *
+ * ### Use Cases
+ * - Implementing data access layers for various entities in an application, providing a consistent and reusable approach to database interactions.
+ * - Adding custom business logic or side effects in response to entity lifecycle events (e.g., logging, notifications, cache invalidation).
+ * - Managing entity metadata and translations in a centralized manner within the repository layer.
+ *
+ * ### Example Usage
+ * ```ts
+ * import { Repository } from "@aerokit/sdk/db";
+ *
+ * // Define an entity interface
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ * }
+ *
+ * // Create a UserRepository by extending the Repository class
+ * class UserRepository extends Repository<User> {
+ *   constructor() {
+ *     super(User);
+ *   }
+ *
+ *   // Override triggerEvent to add custom logic on create/update/delete
+ *   protected async triggerEvent(data: EntityEvent<User>): Promise<void> {
+ *     console.log(`User ${data.operation}d:`, data.entity);
+ *     // Additional logic such as sending notifications or updating related data can be added here
+ *   }
+ * }
+ *
+ * // Example of using the UserRepository
+ * const userRepo = new UserRepository();
+ * const newUserId = userRepo.create({ name: "Alice", email: "alice@example.com" });
+ * const user = userRepo.findById(newUserId);
+ * console.log(user); // Output: { id: 1, name: "Alice", email: "alice@example.com" }
+ * userRepo.update({ id: newUserId, name: "Alice Smith", email: "alice.smith@example.com" });
+ * userRepo.deleteById(newUserId);
+ * ```
+ */
 import { EntityConstructor, Options } from "@aerokit/sdk/db";
 /**
  * Represents the data structure passed to the event trigger method before/after an operation.

package/dist/dts/db/sequence.d.ts

@@ -1,7 +1,36 @@
 /**
- * API Sequence
+ * @module db/sequence
+ * @package @aerokit/sdk/db
+ * @name Sequence
+ * @overview
  *
- * Provides static methods for managing and accessing database sequences.
+ * This module provides a `Sequence` class for managing database sequences in the Dirigible environment. The `Sequence` class offers static methods to retrieve the next value from a sequence, create new sequences, and drop existing sequences. It abstracts the underlying database interactions, allowing developers to work with sequences in a consistent manner across different database systems supported by Dirigible.
+ *
+ * ### Key Features
+ * - Retrieve the next value from a specified database sequence.
+ * - Create new sequences with optional starting values.
+ * - Drop existing sequences when they are no longer needed.
+ * - Support for specifying datasource names to target specific database connections.
+ *
+ * ### Use Cases
+ * - Generating unique identifiers for records in a database table using sequences.
+ * - Managing database sequences as part of application setup or migration processes.
+ * - Abstracting sequence management to allow for easier maintenance and potential database engine changes in the future.
+ *
+ * ### Example Usage
+ * ```ts
+ * import { Sequence } from "@aerokit/sdk/db";
+ *
+ * // Create a new sequence named "user_id_seq" starting at 1000
+ * Sequence.create("user_id_seq", 1000);
+ *
+ * // Get the next value from the "user_id_seq" sequence
+ * const nextUserId = Sequence.nextval("user_id_seq");
+ * console.log(nextUserId); // Output: 1000
+ *
+ * // Drop the "user_id_seq" sequence when it's no longer needed
+ * Sequence.drop("user_id_seq");
+ * ```
  */
 /**
  * Utility class for interacting with database sequence objects.

package/dist/dts/db/sql.d.ts

@@ -1,3 +1,36 @@
+/**
+ * @module db/sql
+ * @package @aerokit/sdk/db
+ * @name SQL
+ * @overview
+ *
+ * This module provides a fluent API for building SQL statements in a database-agnostic way. It includes builders for SELECT, INSERT, UPDATE, DELETE, CREATE, and DROP statements, as well as a builder for retrieving the next value from a sequence. The builders allow for method chaining to construct complex SQL queries while managing parameters separately to prevent SQL injection. The module abstracts away differences in SQL dialects and provides a consistent interface for constructing SQL statements across different databases.
+ *
+ * ### Key Features
+ * - Fluent API for building SQL statements with method chaining.
+ * - Support for SELECT, INSERT, UPDATE, DELETE, CREATE, and DROP statements.
+ * - Separate parameter management to prevent SQL injection.
+ * - Database-agnostic design that abstracts away SQL dialect differences.
+ * - Integration with the underlying database connection for executing built statements.
+ *
+ * ### Use Cases
+ * - Constructing complex SQL queries in a readable and maintainable way.
+ * - Building SQL statements dynamically based on application logic or user input.
+ * - Abstracting database interactions to allow for easier maintenance and potential database engine changes in the future.
+ *
+ * ### Example Usage
+ * ```ts
+ * import { SQLBuilder } from "@aerokit/sdk/db";
+ *
+ * // Example of building a SELECT statement
+ * const sqlBuilder = SQLBuilder.getDialect();
+ * const selectQuery = sqlBuilder.select()
+ *   .column("id")
+ *   .column("name")
+ *   .from("users")
+ *   .where("id = ?", 1);
+ * ```
+ */
 import { Connection } from "./database";
 /**
  * Union type representing all supported SQL data types.

package/dist/dts/db/store.d.ts

@@ -1,3 +1,30 @@
+/**
+ * @module db/store
+ * @package @aerokit/sdk/db
+ * @name Store
+ * @overview
+ *
+ * This module provides a `Store` class that serves as a facade for interacting with the underlying Dirigible Data Store. The `Store` class offers methods for performing CRUD operations, executing parameterized queries, and retrieving metadata about entities. It abstracts away the complexities of JSON serialization and deserialization when communicating with the native Java facade, allowing developers to work with plain JavaScript objects and arrays seamlessly.
+ *
+ * ### Key Features
+ * - CRUD Operations: Create, read, update, and delete entries in the data store using simple methods.
+ * - Query Execution: Execute parameterized queries with support for both primitive and complex parameters.
+ * - Metadata Retrieval: Access metadata about entities, such as table names and ID fields.
+ * - JSON Handling: Automatically handles JSON serialization and deserialization of JavaScript objects when interacting with the native Java APIs.
+ *
+ * ### Use Cases
+ * - Managing application data in a structured way using the data store.
+ * - Executing complex queries with dynamic parameters to retrieve specific subsets of data.
+ * - Abstracting away database interactions to allow for easier maintenance and potential future changes to the underlying data storage mechanism.
+ *
+ * ### Example Usage
+ * ```ts
+ * import { Store } from "@aerokit/sdk/db";
+ *
+ * // Save a new entry to the "users" entity
+ * const userId = Store.save("users", { name: "Alice", email: "alice@example.com" });
+ * ```
+ */
 /**
  * Defines the available comparison operators for query conditions.
  */

package/dist/dts/db/translator.d.ts

@@ -1,7 +1,40 @@
 /**
- * Provides static methods for translating entity properties based on a dedicated language table.
+ * @module db/translator
+ * @package @aerokit/sdk/db
+ * @name Translator
+ * @overview
+ *
+ * This module provides static methods for translating entity properties based on a dedicated language table.
  * Translation is achieved by querying a separate table (e.g., 'BASE_TABLE_LANG') and merging
  * the translated fields back into the original data.
+ *
+ * ### Key Features
+ * - Translates properties for a list of entities based on a specified language code.
+ * - Translates properties for a single entity based on its ID and a specified language code.
+ * - Handles cases where the language table may not be present, providing error logging.
+ *
+ * ### Use Cases
+ * - Supporting multilingual applications by translating entity properties according to user preferences or locale settings.
+ * - Integrating with existing database schemas that use separate language tables for translations.
+ * - Providing a consistent translation mechanism across different modules that require localized data.
+ *
+ * ### Example Usage
+ * ```ts
+ * import { Translator } from "@aerokit/sdk/db";
+ *
+ * // Example: Translating a list of products to German
+ * const products = [
+ *   { Id: 1, Name: "Laptop", Description: "A portable computer" },
+ *   { Id: 2, Name: "Phone", Description: "A mobile device" }
+ * ];
+ * const translatedProducts = Translator.translateList(products, 'de', 'PRODUCTS');
+ * console.log(translatedProducts);
+ *
+ * // Example: Translating a single user entity to French
+ * const user = { Id: 1, FirstName: "John", LastName: "Doe" };
+ * const translatedUser = Translator.translateEntity(user, 1, 'fr', 'USERS');
+ * console.log(translatedUser);
+ * ```
  */
 export declare class Translator {
     /**

package/dist/dts/db/update.d.ts

@@ -1,3 +1,41 @@
+/**
+ * @module db/update
+ * @package @aerokit/sdk/db
+ * @name Update
+ * @overview
+ *
+ * This module provides the `Update` class, which serves as a facade for executing SQL UPDATE, INSERT, and DELETE statements in the Dirigible environment. The `execute` method allows for parameterized queries using either primitive values or structured parameter objects that specify both type and value. This flexibility enables developers to work with various data types and database-specific requirements when performing update operations.
+ *
+ * ### Key Features
+ * - **Parameterized Queries**: Supports both primitive parameters and structured parameter objects for flexible query execution.
+ * - **Named Parameters**: Allows for named parameters in the form of `:paramName` placeholders, enhancing readability and maintainability of SQL statements.
+ * - **Type Specification**: Structured parameters can include type information, which is useful for databases that require explicit type definitions for certain operations.
+ * - **Datasource Support**: The method accepts an optional datasource name, enabling execution against specific database connections in a multi-database environment.
+ *
+ * ### Use Cases
+ * - Performing update operations on database records with dynamic values.
+ * - Executing complex SQL statements that require specific data types or named parameters.
+ * - Integrating with other modules that generate parameters in JSON format, allowing for seamless data flow within the application.
+ *
+ * ### Example Usage
+ * ```ts
+ * import { Update } from "@aerokit/sdk/db";
+ *
+ * // Example with primitive parameters
+ * const rowsAffected1 = Update.execute("UPDATE Users SET name = ? WHERE id = ?", ["Alice", 1]);
+ * console.log(rowsAffected1); // Output: number of rows updated
+ *
+ * // Example with structured parameters
+ * const rowsAffected2 = Update.execute(
+ *   "INSERT INTO Orders (order_number, total) VALUES (:order_number, :total)",
+ *   [
+ *     { name: "order_number", type: "CHAR", value: "ORD12345" },
+ *     { name: "total", type: "DECIMAL", value: 99.99 }
+ *   ]
+ * );
+ * console.log(rowsAffected2); // Output: number of rows inserted
+ * ```
+ */
 /**
  * Interface used for complex parameter types if needed, otherwise primitive types are used directly.
  */

package/dist/dts/etcd/client.d.ts

@@ -1,3 +1,39 @@
+/**
+ * @module etcd/client
+ * @package @aerokit/sdk/etcd
+ * @name Client
+ * @overview
+ *
+ * This module provides a `Client` class for interacting with the Etcd key-value store within the Dirigible environment. The `Client` class allows developers to perform basic operations such as putting (writing) values, getting values, and deleting keys in Etcd. It also includes utility functions for converting between JavaScript types and the native Java/Etcd types used by the underlying Etcd client library.
+ *
+ * ### Key Features
+ * - Put string or byte array values to Etcd keys.
+ * - Get values from Etcd keys with options for string or byte array formats.
+ * - Retrieve metadata about the Etcd cluster and key-value store through response headers.
+ * - Delete keys from Etcd.
+ *
+ * ### Use Cases
+ * - Storing configuration data or application state in Etcd for distributed applications.
+ * - Retrieving and managing key-value pairs in Etcd for service discovery, configuration management, or coordination tasks.
+ * - Integrating with other modules that require a consistent interface for interacting with Etcd as a backend store.
+ *
+ * ### Example Usage
+ * ```ts
+ * import { Client } from "@aerokit/sdk/etcd";
+ *
+ * const etcdClient = new Client();
+ *
+ * // Put a string value to a key
+ * etcdClient.putStringValue("config/appName", "MyApp");
+ *
+ * // Get the string value of a key
+ * const appName = etcdClient.getKvsStringValue("config/appName");
+ * console.log(appName); // Output: { "config/appName": "MyApp" }
+ *
+ * // Delete a key
+ * etcdClient.delete("config/appName");
+ * ```
+ */
 /**
  * Represents the header metadata of an Etcd response.
  */

package/dist/dts/etcd/index.d.ts

@@ -1,2 +1,12 @@
+/**
+ * @module etcd/index
+ * @package @aerokit/sdk/etcd
+ * @overview
+ *
+ * This module provides functionalities for interacting with an etcd key-value store within the Aerokit SDK. It includes classes and methods for connecting to an etcd server, performing CRUD operations on keys, and managing etcd clusters.
+ *
+ * The main components of this module are:
+ * - Client: Represents a client for connecting to an etcd server and provides methods to perform operations on the key-value store.
+ */
 export * from "./client";
 export { Client as client } from "./client";

package/dist/dts/extensions/decorators.d.ts

@@ -1,3 +1,31 @@
+/**
+ * @module extensions/decorators
+ * @package @aerokit/sdk/extensions
+ * @name Decorators
+ * @overview
+ *
+ * This module provides a set of decorators for defining and managing extensions within the Dirigible environment. The decorators are designed to be compatible with both legacy JavaScript environments (like Mozilla Rhino or older GraalJS) and modern JavaScript environments that support the latest decorator specifications.
+ *
+ * ### Key Features
+ * - **Extension Decorator**: Marks a class as an extension, allowing it to be registered and associated with a specific extension point in the Dirigible application.
+ * - **Metadata Storage**: Uses symbols to store extension metadata on the class, ensuring that the metadata is encapsulated and does not interfere with other properties or methods.
+ * - **Hybrid Decorator Support**: The decorators are implemented to work seamlessly in both legacy and modern JavaScript environments, ensuring broad compatibility across different runtime contexts.
+ *
+ * ### Use Cases
+ * - Defining extensions that can be dynamically loaded and integrated into the application at runtime.
+ * - Associating extensions with specific extension points to enable modular and extensible application design.
+ * - Leveraging the extension mechanism to allow for third-party contributions or customizations without modifying the core application code.
+ *
+ * ### Example Usage
+ * ```ts
+ * import { Extension } from "@aerokit/sdk/extensions";
+ *
+ * @Extension({ name: "MyExtension", to: "my-extension-point" })
+ * class MyExtension {
+ *   // Extension implementation
+ * }
+ * ```
+ */
 export interface ExtensionOptions {
     name: string;
     to: string;

package/dist/dts/extensions/extensions.d.ts

@@ -1,6 +1,35 @@
 /**
- * API Extensions
+ * @module extensions/extensions
+ * @package @aerokit/sdk/extensions
+ * @name Extensions
+ * @overview
  *
+ * This module provides the `Extensions` class, which offers functionality for discovering and loading extensions defined against the Dirigible extension model. The `Extensions` class allows developers to retrieve registered extensions for specific extension points and to load those extensions as modules, ensuring that they meet specified requirements (e.g., exporting certain functions).
+ *
+ * ### Key Features
+ * - Retrieve registered extension module paths for specific extension points.
+ * - Load extension modules with support for both synchronous and asynchronous loading mechanisms.
+ * - Validate loaded extensions against required function exports to ensure they meet expected interfaces.
+ * - Configurable error handling to either log issues or throw exceptions based on the use case.
+ *
+ * ### Use Cases
+ * - Dynamically loading and integrating extensions at runtime based on the application's needs.
+ * - Ensuring that loaded extensions conform to expected interfaces by checking for required functions.
+ * - Managing extensions in a modular application design, allowing for third-party contributions without modifying core code.
+ *
+ * ### Example Usage
+ * ```ts
+ * import { Extensions } from "@aerokit/sdk/extensions";
+ *
+ * // Load extensions for a specific extension point, requiring certain functions to be exported
+ * const loadedExtensions = await Extensions.load("my.extension.point", ["initialize", "execute"], true);
+ *
+ * // Use the loaded extensions
+ * loadedExtensions.forEach(extension => {
+ *   extension.initialize();
+ *   extension.execute();
+ * });
+ * ```
  */
 /**
  * Provides functionality for discovering and loading extensions defined

package/dist/dts/extensions/index.d.ts

@@ -1,3 +1,14 @@
+/**
+ * @module extensions/index
+ * @package @aerokit/sdk/extensions
+ * @overview
+ *
+ * This module provides functionalities for managing extensions within the Aerokit SDK. It includes classes and methods for defining, registering, and managing extensions that can enhance the capabilities of the SDK.
+ *
+ * The main components of this module are:
+ * - Extensions: Represents a registry for managing extensions and provides methods to register and retrieve extensions.
+ * - Decorators: Provides decorators for defining extensions and their properties in a declarative manner.
+ */
 export * from "./extensions";
 export { Extensions as extensions } from "./extensions";
 export * as decorators from "./decorators";

package/dist/dts/git/client.d.ts

@@ -1,3 +1,31 @@
+/**
+ * @module git/client
+ * @package @aerokit/sdk/git
+ * @name Client
+ * @overview
+ *
+ * This module provides a `Client` class for interacting with Git repositories within the Dirigible environment. The `Client` class offers methods for initializing repositories, committing changes, managing branches, and retrieving repository information such as status and history. It abstracts the underlying Git operations through a native Java facade, providing a simplified interface for common Git tasks in the context of workspace projects.
+ *
+ * ### Key Features
+ * - Repository initialization with an initial commit.
+ * - Committing changes with options for staging and commit messages.
+ * - Branch management, including creation, deletion, and renaming of local and remote branches.
+ * - Pulling and pushing changes to remote repositories.
+ * - Retrieving repository status, current branch, and commit history.
+ *
+ * ### Use Cases
+ * - Managing Git repositories for projects within the Dirigible workspace.
+ * - Automating Git operations as part of application workflows or CI/CD pipelines.
+ * - Integrating Git functionality into custom applications or modules that require version control capabilities.
+ *
+ * ### Example Usage
+ * ```ts
+ * import { Client } from "@aerokit/sdk/git";
+ *
+ * // Initialize a new Git repository for a project
+ * Client.initRepository("Alice", "alice@example.com");
+ * ```
+ */
 /**
  * Describes a file within the workspace, potentially with Git status information.
  */

package/dist/dts/git/index.d.ts

@@ -1,2 +1,12 @@
+/**
+ * @module git/index
+ * @package @aerokit/sdk/git
+ * @overview
+ *
+ * This module provides functionalities for interacting with Git repositories within the Aerokit SDK. It includes classes and methods for connecting to Git repositories, performing operations such as cloning, committing, pushing, and pulling changes, and managing Git configurations.
+ *
+ * The main components of this module are:
+ * - Client: Represents a client for connecting to a Git repository and provides methods to perform various Git operations.
+ */
 export * from "./client";
 export { Client as client } from "./client";