{"version":3,"file":"cassandra.d.cts","names":["AsyncCallerParams","Client","DseClientOptions","types","driverTypes","AstraServiceProviderArgs","URL","CassandraServiceProviderArgs","CassandraClientArgs","CassandraClientFactory","Promise","Column","Index","Filter","WhereClause","Record","CassandraTableArgs","CassandraTable","ResultSet"],"sources":["../../src/utils/cassandra.d.ts"],"sourcesContent":["import { AsyncCallerParams } from \"@langchain/core/utils/async_caller\";\nimport { Client, DseClientOptions, types as driverTypes } from \"cassandra-driver\";\n/**\n * Defines the configuration options for connecting to Astra DB, DataStax's cloud-native Cassandra-as-a-Service.\n * This interface specifies the necessary parameters required to establish a connection with an Astra DB instance,\n * including authentication and targeting specific data centers or regions.\n *\n * Properties:\n * - `token`: The authentication token required for accessing the Astra DB instance. Essential for establishing a secure connection.\n * - `endpoint`: Optional. The URL or network address of the Astra DB instance. Can be used to directly specify the connection endpoint.\n * - `datacenterID`: Optional. The unique identifier of the data center to connect to. Used to compute the endpoint.\n * - `regionName`: Optional. The region name of the Astra DB instance. Used to compute the endpoint. Default to the primary region.\n * - `bundleUrlTemplate`: Optional. The URL template for downloading the secure connect bundle. Used to customize the bundle URL. \"database_id\" variable will be resolved at runtime.\n *\n * Either `endpoint` or `datacenterID` must be provided to establish a connection to Astra DB.\n */\nexport interface AstraServiceProviderArgs {\n    token: string;\n    endpoint?: string | URL;\n    datacenterID?: string;\n    regionName?: string;\n    bundleUrlTemplate?: string;\n}\n/**\n * Encapsulates the service provider-specific arguments required for creating a Cassandra client.\n * This interface acts as a wrapper for configurations pertaining to various Cassandra service providers,\n * allowing for extensible and flexible client configuration.\n *\n * Currently, it supports:\n * - `astra`: Optional. Configuration parameters specific to Astra DB, DataStax's cloud-native Cassandra service.\n *            Utilizing this property enables tailored connections to Astra DB instances with custom configurations.\n *\n * This structure is designed to be extended with additional service providers in the future, ensuring adaptability\n * and extensibility for connecting to various Cassandra services with distinct configuration requirements.\n */\nexport interface CassandraServiceProviderArgs {\n    astra?: AstraServiceProviderArgs;\n}\n/**\n * Extends the DataStax driver's client options with additional configurations for service providers,\n * enabling the customization of Cassandra client instances based on specific service requirements.\n * This interface integrates native driver configurations with custom extensions, facilitating the\n * connection to Cassandra databases, including managed services like Astra DB.\n *\n * - `serviceProviderArgs`: Optional. Contains the connection arguments for specific Cassandra service providers,\n *                           such as Astra DB. This allows for detailed and service-specific client configurations,\n *                           enhancing connectivity and functionality across different Cassandra environments.\n *\n * Incorporating this interface into client creation processes ensures a comprehensive setup, encompassing both\n * standard and extended options for robust and versatile Cassandra database interactions.\n */\nexport interface CassandraClientArgs extends DseClientOptions {\n    serviceProviderArgs?: CassandraServiceProviderArgs;\n}\n/**\n * Provides a centralized and streamlined factory for creating and configuring instances of the Cassandra client.\n * This class abstracts the complexities involved in instantiating and configuring Cassandra client instances,\n * enabling straightforward integration with Cassandra databases. It supports customization through various\n * configuration options, allowing for the creation of clients tailored to specific needs, such as connecting\n * to different clusters or utilizing specialized authentication and connection options.\n *\n * Key Features:\n * - Simplifies the Cassandra client creation process with method-based configurations.\n * - Supports customization for connecting to various Cassandra environments, including cloud-based services like Astra.\n * - Ensures consistent and optimal client configuration, incorporating best practices.\n *\n * Example Usage (Apache Cassandra®):\n * ```\n * const cassandraArgs = {\n *   contactPoints: ['h1', 'h2'],\n *   localDataCenter: 'datacenter1',\n *   credentials: {\n *     username: <...> as string,\n *     password: <...> as string,\n *   },\n * };\n * const cassandraClient = CassandraClientFactory.getClient(cassandraArgs);\n * ```\n *\n * Example Usage (DataStax AstraDB):\n * ```\n * const astraArgs = {\n *   serviceProviderArgs: {\n *     astra: {\n *       token: <...> as string,\n *       endpoint: <...> as string,\n *     },\n *   },\n * };\n * const cassandraClient = CassandraClientFactory.getClient(astraArgs);\n * ``` *\n */\nexport declare class CassandraClientFactory {\n    /**\n     * Asynchronously obtains a configured Cassandra client based on the provided arguments.\n     * This method processes the given CassandraClientArgs to produce a configured Client instance\n     * from the cassandra-driver, suitable for interacting with Cassandra databases.\n     *\n     * @param args The configuration arguments for the Cassandra client, including any service provider-specific options.\n     * @returns A Promise resolving to a Client object configured according to the specified arguments.\n     */\n    static getClient(args: CassandraClientArgs): Promise<Client>;\n    /**\n     * Processes the provided CassandraClientArgs for creating a Cassandra client.\n     *\n     * @param args The arguments for creating the Cassandra client, including service provider configurations.\n     * @returns A Promise resolving to the processed CassandraClientArgs, ready for client initialization.\n     * @throws Error if the configuration is unsupported, specifically if serviceProviderArgs are provided\n     * but do not include valid configurations for Astra.\n     */\n    private static processArgs;\n    private static processAstraArgs;\n    private static getAstraDefaultBundleLocation;\n    private static setAstraBundle;\n    private static downloadAstraSecureConnectBundle;\n}\n/**\n * Represents the definition of a column within a Cassandra table schema.\n * This interface is used to specify the properties of table columns during table creation\n * and to define how columns are utilized in select queries.\n *\n * Properties:\n * - `name`: The name of the column.\n * - `type`: The data type of the column, used during table creation to define the schema.\n * - `partition`: Optional. Specifies whether the column is part of the partition key. Important for table creation.\n * - `alias`: Optional. An alias for the column that can be used in select queries for readability or to avoid naming conflicts.\n * - `binds`: Optional. Specifies values to be bound to the column in queries, supporting parameterized query construction.\n *\n */\nexport interface Column {\n    name: string;\n    type: string;\n    partition?: boolean;\n    alias?: string;\n    binds?: unknown | [unknown, ...unknown[]];\n}\n/**\n * Defines an index on a Cassandra table column, facilitating efficient querying by column values.\n * This interface specifies the necessary configuration for creating secondary indexes on table columns,\n * enhancing query performance and flexibility.\n *\n * Properties:\n * - `name`: The name of the index. Typically related to the column it indexes for clarity.\n * - `value`: The name of the column on which the index is created.\n * - `options`: Optional. Custom options for the index, specified as a string. This can include various index\n *               configurations supported by Cassandra, such as using specific indexing classes or options.\n *\n */\nexport interface Index {\n    name: string;\n    value: string;\n    options?: string;\n}\n/**\n * Represents a filter condition used in constructing WHERE clauses for querying Cassandra tables.\n * Filters specify the criteria used to select rows from a table, based on column values.\n *\n * Properties:\n * - `name`: The name of the column to filter on.\n * - `value`: The value(s) to match against the column. Can be a single value or an array of values for operations like IN.\n * - `operator`: Optional. The comparison operator to use (e.g., '=', '<', '>', 'IN'). Defaults to '=' if not specified.\n *\n */\nexport interface Filter {\n    name: string;\n    value: unknown | [unknown, ...unknown[]];\n    operator?: string;\n}\n/**\n * Defines a type for specifying WHERE clause conditions in Cassandra queries.\n * This can be a single `Filter` object, an array of `Filter` objects for multiple conditions,\n * or a `Record<string, unknown>` for simple equality conditions keyed by column name.\n */\nexport type WhereClause = Filter[] | Filter | Record<string, unknown>;\n/**\n * Defines the configuration arguments for initializing a Cassandra table within an application.\n * This interface extends `AsyncCallerParams`, incorporating asynchronous operation configurations,\n * and adds specific properties for table creation, query execution, and data manipulation in a\n * Cassandra database context.\n *\n * Properties:\n * - `table`: The name of the table to be used or created.\n * - `keyspace`: The keyspace within which the table exists or will be created.\n * - `primaryKey`: Specifies the column(s) that constitute the primary key of the table. This can be a single\n *                 `Column` object for a simple primary key or an array of `Column` objects for composite keys.\n * - `nonKeyColumns`: Defines columns that are not part of the primary key. Similar to `primaryKey`, this can be a\n *                    single `Column` object or an array of `Column` objects, supporting flexible table schema definitions.\n * - `withClause`: Optional. A string containing additional CQL table options to be included in the CREATE TABLE statement.\n *                 This enables the specification of various table behaviors and properties, such as compaction strategies\n *                 and TTL settings.\n * - `indices`: Optional. An array of `Index` objects defining secondary indices on the table for improved query performance\n *               on non-primary key columns.\n * - `batchSize`: Optional. Specifies the default size of batches for batched write operations to the table, affecting\n *                performance and consistency trade-offs.\n *\n */\nexport interface CassandraTableArgs extends AsyncCallerParams {\n    table: string;\n    keyspace: string;\n    primaryKey: Column | Column[];\n    nonKeyColumns: Column | Column[];\n    withClause?: string;\n    indices?: Index[];\n    batchSize?: number;\n}\n/**\n * Represents a Cassandra table, encapsulating functionality for schema definition, data manipulation, and querying.\n * This class provides a high-level abstraction over Cassandra's table operations, including creating tables,\n * inserting, updating, selecting, and deleting records. It leverages the CassandraClient for executing\n * operations and supports asynchronous interactions with the database.\n *\n * Key features include:\n * - Table and keyspace management: Allows for specifying table schema, including primary keys, columns,\n *   and indices, and handles the creation of these elements within the specified keyspace.\n * - Data manipulation: Offers methods for inserting (upserting) and deleting data in batches or individually,\n *   with support for asynchronous operation and concurrency control.\n * - Querying: Enables selecting data with flexible filtering, sorting, and pagination options.\n *\n * The class is designed to be instantiated with a set of configuration arguments (`CassandraTableArgs`)\n * that define the table's structure and operational parameters, providing a streamlined interface for\n * interacting with Cassandra tables in a structured and efficient manner.\n *\n * Usage Example:\n * ```typescript\n * const tableArgs: CassandraTableArgs = {\n *   table: 'my_table',\n *   keyspace: 'my_keyspace',\n *   primaryKey: [{ name: 'id', type: 'uuid', partition: true }],\n *   nonKeyColumns: [{ name: 'data', type: 'text' }],\n * };\n * const cassandraClient = new CassandraClient(clientConfig);\n * const myTable = new CassandraTable(tableArgs, cassandraClient);\n * ```\n *\n * This class simplifies Cassandra database interactions, making it easier to perform robust data operations\n * while maintaining clear separation of concerns and promoting code reusability.\n */\nexport declare class CassandraTable {\n    private client;\n    private readonly keyspace;\n    private readonly table;\n    private primaryKey;\n    private nonKeyColumns;\n    private indices;\n    private withClause;\n    private batchSize;\n    private initializationPromise;\n    private asyncCaller;\n    private constructorArgs;\n    /**\n     * Initializes a new instance of the CassandraTable class with specified configuration.\n     * This includes setting up the table schema (primary key, columns, and indices) and\n     * preparing the environment for executing queries against a Cassandra database.\n     *\n     * @param args Configuration arguments defining the table schema and operational settings.\n     * @param client Optional. A Cassandra Client instance. If not provided, one will be created\n     *               using the configuration specified in `args`.\n     */\n    constructor(args: CassandraTableArgs, client?: Client);\n    /**\n     * Executes a SELECT query on the Cassandra table with optional filtering, ordering, and pagination.\n     * Allows for specifying columns to return, filter conditions, sort order, and limits on the number of results.\n     *\n     * @param columns Optional. Columns to include in the result set. If omitted, all columns are selected.\n     * @param filter Optional. Conditions to apply to the query for filtering results.\n     * @param orderBy Optional. Criteria to sort the result set.\n     * @param limit Optional. Maximum number of records to return.\n     * @param allowFiltering Optional. Enables ALLOW FILTERING option for queries that cannot be executed directly due to Cassandra's query restrictions.\n     * @param fetchSize Optional. The number of rows to fetch per page (for pagination).\n     * @param pagingState Optional. The paging state from a previous query execution, used for pagination.\n     * @returns A Promise resolving to the query result set.\n     */\n    select(columns?: Column[], filter?: WhereClause, orderBy?: Filter[], limit?: number, allowFiltering?: boolean, fetchSize?: number, pagingState?: string): Promise<driverTypes.ResultSet>;\n    /**\n     * Validates the correspondence between provided values and specified columns for database operations.\n     * This method checks if the number of values matches the number of specified columns, ensuring\n     * data integrity before executing insert or update operations. It also defaults to using all table columns\n     * if specific columns are not provided. Throws an error if the validation fails.\n     *\n     * @param values An array of values or an array of arrays of values to be inserted or updated. Each\n     *               inner array represents a set of values corresponding to one row in the table.\n     * @param columns Optional. An array of `Column` objects specifying the columns to be used for the operation.\n     *                If not provided, the method defaults to using both primary key and non-key columns of the table.\n     * @returns An array of `Column` objects that have been validated for the operation.\n     * @throws Error if the number of provided values does not match the number of specified columns.\n     * @private\n     */\n    private _columnCheck;\n    /**\n     * Inserts or updates records in the Cassandra table in batches, managing concurrency and batching size.\n     * This method organizes the provided values into batches and uses `_upsert` to perform the database operations.\n     *\n     * @param values An array of arrays, where each inner array contains values for a single record.\n     * @param columns Optional. Columns to be included in the insert/update operations. Defaults to all table columns.\n     * @param batchSize Optional. The size of each batch for the operation. Defaults to the class's batchSize property.\n     * @returns A Promise that resolves once all records have been upserted.\n     */\n    upsert(values: unknown[][], columns?: Column[], batchSize?: number): Promise<void>;\n    /**\n     * Deletes rows from the Cassandra table that match the specified WHERE clause conditions.\n     *\n     * @param whereClause Defines the conditions that must be met for rows to be deleted. Can be a single filter,\n     * an array of filters, or a key-value map translating to filter conditions.\n     * @returns A Promise that resolves when the DELETE operation has completed.\n     */\n    delete(whereClause: WhereClause): Promise<driverTypes.ResultSet>;\n    /**\n     * Retrieves the Node.js Cassandra client instance associated with this table.\n     * This method ensures that the client is initialized and ready for use, returning the\n     * Cassandra client object that can be used for database operations directly.\n     * It initializes the client if it has not already been initialized.\n     *\n     * @returns A Promise that resolves to the Cassandra Client instance used by this table for database interactions.\n     */\n    getClient(): Promise<Client>;\n    /**\n     * Constructs the PRIMARY KEY clause for a Cassandra CREATE TABLE statement based on the specified columns.\n     * This method organizes the provided columns into partition and clustering keys, forming the necessary syntax\n     * for the PRIMARY KEY clause in a Cassandra table schema definition. It supports complex primary key structures,\n     * including composite partition keys and clustering columns.\n     *\n     * - Partition columns are those marked with the `partition` property. If multiple partition columns are provided,\n     *   they are grouped together in parentheses as a composite partition key.\n     * - Clustering columns are those not marked as partition keys and are listed after the partition key(s).\n     *   They determine the sort order of rows within a partition.\n     *\n     * The method ensures the correct syntax for primary keys, handling both simple and composite key structures,\n     * and throws an error if no partition or clustering columns are provided.\n     *\n     * @param columns An array of `Column` objects representing the columns to be included in the primary key.\n     *                Each column must have a `name` and may have a `partition` boolean indicating if it is part\n     *                of the partition key.\n     * @returns The PRIMARY KEY clause as a string, ready to be included in a CREATE TABLE statement.\n     * @throws Error if no columns are marked as partition keys or if no columns are provided.\n     * @private\n     */\n    private buildPrimaryKey;\n    /**\n     * Type guard that checks if a given object conforms to the `Filter` interface.\n     * This method is used to determine if an object can be treated as a filter for Cassandra\n     * query conditions. It evaluates the object's structure, specifically looking for `name`\n     * and `value` properties, which are essential for defining a filter in Cassandra queries.\n     *\n     * @param obj The object to be evaluated.\n     * @returns A boolean value indicating whether the object is a `Filter`. Returns `true`\n     *          if the object has both `name` and `value` properties, signifying it meets the\n     *          criteria for being used as a filter in database operations; otherwise, returns `false`.\n     * @private\n     */\n    private isFilter;\n    /**\n     * Helper to convert Record<string,unknown> to a Filter[]\n     * @param record: a key-value Record collection\n     * @returns Record as a Filter[]\n     */\n    private convertToFilters;\n    /**\n     * Converts a key-value pair record into an array of `Filter` objects suitable for Cassandra query conditions.\n     * This utility method allows for a more flexible specification of filter conditions by transforming\n     * a simple object notation into the structured format expected by Cassandra query builders. Each key-value\n     * pair in the record is interpreted as a filter condition, where the key represents the column name and\n     * the value represents the filtering criterion.\n     *\n     * The method assumes a default equality operator for each filter. It is particularly useful for\n     * converting concise filter specifications into the detailed format required for constructing CQL queries.\n     *\n     * @param record A key-value pair object where each entry represents a filter condition, with the key\n     *               as the column name and the value as the filter value. The value can be a single value\n     *               or an array to support IN queries with multiple criteria.\n     * @returns An array of `Filter` objects, each representing a condition extracted from the input record.\n     *          The array can be directly used in constructing query WHERE clauses.\n     * @private\n     */\n    private asFilters;\n    /**\n     * Constructs the WHERE clause of a CQL query from an array of `Filter` objects.\n     * This method generates the conditional part of a Cassandra Query Language (CQL) statement,\n     * allowing for complex query constructions based on provided filters. Each filter in the array\n     * translates into a condition within the WHERE clause, with support for various comparison operators.\n     *\n     * The method handles the assembly of these conditions into a syntactically correct CQL WHERE clause,\n     * including the appropriate use of placeholders (?) for parameter binding in prepared statements.\n     * It supports a range of operators, defaulting to \"=\" (equality) if an operator is not explicitly specified\n     * in a filter. Filters with multiple values (e.g., for IN conditions) are also correctly formatted.\n     *\n     * @param filters Optional. An array of `Filter` objects representing the conditions to apply in the WHERE clause.\n     *                Each `Filter` includes a column name (`name`), a value or array of values (`value`), and optionally,\n     *                an operator (`operator`). If no filters are provided, an empty string is returned.\n     * @returns The constructed WHERE clause as a string, ready to be appended to a CQL query. If no filters\n     *          are provided, returns an empty string, indicating no WHERE clause should be applied.\n     * @private\n     */\n    private buildWhereClause;\n    /**\n     * Generates the ORDER BY clause for a CQL query from an array of `Filter` objects.\n     * This method forms the sorting part of a Cassandra Query Language (CQL) statement,\n     * allowing for detailed control over the order of results based on specified column names\n     * and directions. Each filter in the array represents a column and direction to sort by.\n     *\n     * It is important to note that unlike the traditional use of `Filter` objects for filtering,\n     * in this context, they are repurposed to specify sorting criteria. The `name` field indicates\n     * the column to sort by, and the `operator` field is used to specify the sort direction (`ASC` or `DESC`).\n     * The `value` field is not utilized for constructing the ORDER BY clause and can be omitted.\n     *\n     * @param filters Optional. An array of `Filter` objects where each object specifies a column and\n     *                direction for sorting. The `name` field of each filter represents the column name,\n     *                and the `operator` field should contain the sorting direction (`ASC` or `DESC`).\n     *                If no filters are provided, the method returns an empty string.\n     * @returns The constructed ORDER BY clause as a string, suitable for appending to a CQL query.\n     *          If no sorting criteria are provided, returns an empty string, indicating no ORDER BY\n     *          clause should be applied to the query.\n     * @private\n     */\n    private buildOrderByClause;\n    /**\n     * Constructs a CQL search query string for retrieving records from a Cassandra table.\n     * This method combines various query components, including selected columns, filters, sorting criteria,\n     * and pagination options, to form a complete and executable CQL query. It allows for fine-grained control\n     * over the query construction process, enabling the inclusion of conditional filtering, ordering of results,\n     * and limiting the number of returned records, with an optional allowance for filtering.\n     *\n     * The method meticulously constructs the SELECT part of the query using the provided columns, applies\n     * the WHERE clause based on given filters, sorts the result set according to the orderBy criteria, and\n     * restricts the number of results with the limit parameter. Additionally, it can enable the ALLOW FILTERING\n     * option for queries that require server-side filtering beyond the capabilities of primary and secondary indexes.\n     *\n     * @param queryColumns An array of `Column` objects specifying which columns to include in the result set.\n     *                     Each column can also have an alias defined for use in the query's result set.\n     * @param filters Optional. An array of `Filter` objects to apply as conditions in the WHERE clause of the query.\n     * @param orderBy Optional. An array of `Filter` objects specifying the ordering of the returned records.\n     *                Although repurposed as `Filter` objects, here they define the column names and the sort direction (ASC/DESC).\n     * @param limit Optional. A numeric value specifying the maximum number of records the query should return.\n     * @param allowFiltering Optional. A boolean flag that, when true, includes the ALLOW FILTERING clause in the query,\n     *                        permitting Cassandra to execute queries that might not be efficiently indexable.\n     * @returns A string representing the fully constructed CQL search query, ready for execution against a Cassandra table.\n     * @private\n     */\n    private buildSearchQuery;\n    private initialize;\n    private performInitialization;\n    private _upsert;\n}\n//# sourceMappingURL=cassandra.d.ts.map"],"mappings":";;;;;;;AAgBA;AAmBA;AAgBA;AAyCA;;;;AASwD;AA4BxD;AAmBA;AAeA;AAUA;AAA0Ba,UA7JTR,wBAAAA,CA6JSQ;EAAWA,KAAAA,EAAAA,MAAAA;EAASE,QAAAA,CAAAA,EAAAA,MAAAA,GA3JtBT,GA2JsBS;EAAM,YAAA,CAAA,EAAA,MAAA;EAuBnCC,UAAAA,CAAAA,EAAAA,MAAAA;EAGDL,iBAAAA,CAAAA,EAAAA,MAAAA;;;;;;AAH6C;AAyC7D;;;;;;;AAmC8JD,UA7O7IH,4BAAAA,CA6O6IG;EAyBpHC,KAAAA,CAAAA,EArQ9BN,wBAqQ8BM;;;;;;;AAiBlB;;;;;;;;UAvQPH,mBAAAA,SAA4BN;wBACnBK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAwCLE,sBAAAA;;;;;;;;;yBASMD,sBAAsBE,QAAQT;;;;;;;;;;;;;;;;;;;;;;;;;;;;UA4BxCU,MAAAA;;;;;;;;;;;;;;;;;;;UAmBAC,KAAAA;;;;;;;;;;;;;;;UAeAC,MAAAA;;;;;;;;;;KAULC,WAAAA,GAAcD,WAAWA,SAASE;;;;;;;;;;;;;;;;;;;;;;;UAuB7BC,kBAAAA,SAA2BhB;;;cAG5BW,SAASA;iBACNA,SAASA;;YAEdC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmCOK,cAAAA;;;;;;;;;;;;;;;;;;;;;oBAqBCD,6BAA6Bf;;;;;;;;;;;;;;mBAc9BU,mBAAmBG,uBAAuBD,+FAA+FH,QAAQN,KAAAA,CAAYc;;;;;;;;;;;;;;;;;;;;;;;;;wCAyBxIP,+BAA+BD;;;;;;;;sBAQjDI,cAAcJ,QAAQN,KAAAA,CAAYc;;;;;;;;;eASzCR,QAAQT"}