@singlestore/client - npm Package Compare versions

Comparing version 0.0.28 to 0.0.29

dist/index.d.ts

 import { AnyAI, CreateChatCompletionResult } from '@singlestore/ai';
-import * as mysql2_promise from 'mysql2/promise';
-import { PoolOptions, Pool, ResultSetHeader, RowDataPacket } from 'mysql2/promise';
+import { PoolOptions, Pool, ResultSetHeader, FieldPacket, RowDataPacket } from 'mysql2/promise';
 export { ResultSetHeader, RowDataPacket } from 'mysql2/promise';
-import * as mysql2 from 'mysql2';
 
+/**
+ * Configuration object for initializing a database connection.
+ *
+ * Extends `Partial<Omit<PoolOptions, "name" | "database">>` to allow the configuration of any `PoolOptions`
+ * properties except `name` and `database`, which are omitted.
+ */
 interface ConnectionConfig extends Partial<Omit<PoolOptions, "name" | "database">> {
 }
+/**
+ * Class representing a database connection, providing methods to manage the connection pool.
+ *
+ * @property {Pool} client - The MySQL connection pool created with the provided configuration.
+ */
 declare class Connection {
     config: ConnectionConfig;
     client: Pool;
+    /**
+     * Constructs a new `Connection` instance and initializes the connection pool.
+     *
+     * @param {ConnectionConfig} config - The configuration object for the connection pool.
+     */
     constructor(config: ConnectionConfig);
+    /**
+     * Factory method to create a new `Connection` instance.
+     *
+     * @param {ConnectionConfig} config - The configuration object for the connection pool.
+     *
+     * @returns {Connection} A new `Connection` instance.
+     */
     static create(config: ConnectionConfig): Connection;
+    /**
+     * Disconnects from the database by closing the connection pool.
+     *
+     * @returns {Promise<void>} A promise that resolves when the connection pool is closed.
+     */
     disconnect(): Promise<void>;
 }
 
-type ColumnType = any;
-interface ColumnSchema {
-    name: string;
-    type: string;
-    nullable?: boolean;
-    primaryKey?: boolean;
-    autoIncrement?: boolean;
-    default?: any;
-    clauses?: string[];
-}
-interface ColumnInfo<T extends string = string> {
-    name: T;
-    type: string;
-    null: string;
-    key: string;
-    default: any;
-    extra: string;
-}
-declare class Column {
-    private _connection;
-    databaseName: string;
-    tableName: string;
-    name: string;
-    private _path;
-    constructor(_connection: Connection, databaseName: string, tableName: string, name: string);
-    static normalizeInfo<T extends string = string>(info: any): ColumnInfo<T>;
-    static schemaToClauses(schema: ColumnSchema): string;
-    static add(connection: Connection, databaseName: string, tableName: string, schema: ColumnSchema): Promise<Column>;
-    static drop(connection: Connection, databaseName: string, tableName: string, name: string): Promise<[ResultSetHeader, mysql2_promise.FieldPacket[]]>;
-    showInfo(): Promise<ColumnInfo<string>>;
-    drop(): Promise<[ResultSetHeader, mysql2_promise.FieldPacket[]]>;
-    modify(schema: Partial<Omit<ColumnSchema, "name">>): Promise<[ResultSetHeader, mysql2_promise.FieldPacket[]]>;
-    rename(newName: string): Promise<[ResultSetHeader, mysql2_promise.FieldPacket[]]>;
-}
-
+/**
+ * Type representing a generic schema for database queries.
+ *
+ * This type is a record where each key is a string representing a column name,
+ * and the value can be of any type, representing the data type of that column.
+ */
 type QuerySchema = Record<string, any>;
 
+/**
+ * Type representing the various operators that can be used in query filters.
+ *
+ * @typeParam T - The type of the value being filtered. The default is `any`.
+ *
+ * @property {T} [eq] - Equal to a specific value.
+ * @property {T} [ne] - Not equal to a specific value.
+ * @property {T} [gt] - Greater than a specific value.
+ * @property {T} [gte] - Greater than or equal to a specific value.
+ * @property {T} [lt] - Less than a specific value.
+ * @property {T} [lte] - Less than or equal to a specific value.
+ * @property {T[]} [in] - Within an array of specific values.
+ * @property {T[]} [nin] - Not within an array of specific values.
+ * @property {string} [like] - Matches a specific pattern (only applicable to string types).
+ */
 type QueryFilterOperators<T = any> = {
@@ -65,3 +77,16 @@ eq?: T;
 };
+/**
+ * Type representing a single filter value, which can be either a direct value or a set of operators.
+ *
+ * @typeParam T - The type of the value being filtered.
+ */
 type QueryFilterValue<T> = T | QueryFilterOperators<T>;
+/**
+ * Type representing logical conditions for combining multiple query filters.
+ *
+ * @typeParam T - The schema type being filtered.
+ *
+ * @property {QueryFilters<T>[]} [and] - Logical AND condition combining multiple filters.
+ * @property {QueryFilters<T>[]} [or] - Logical OR condition combining multiple filters.
+ */
 type QueryFilterLogicalConditions<T extends QuerySchema> = {
@@ -71,5 +96,21 @@ and?: QueryFilters<T>[];
 };
+/**
+ * Type representing the filters that can be applied to a query.
+ *
+ * @typeParam T - The schema type being filtered.
+ *
+ * This type combines the individual column filters and logical conditions for combining them.
+ */
 type QueryFilters<T extends QuerySchema> = {
     [K in keyof T]?: QueryFilterValue<T[K]>;
 } & QueryFilterLogicalConditions<T>;
+/**
+ * Class responsible for building SQL WHERE clauses from query filters.
+ *
+ * @typeParam T - The schema type being filtered.
+ *
+ * @property {string} clause - The SQL WHERE clause generated from the filters.
+ * @property {T[keyof T][]} values - The array of values corresponding to the placeholders in the WHERE clause.
+ * @property {QueryFilters<T>} [filters] - The query filters used to generate the WHERE clause and values.
+ */
 declare class QueryFiltersBuilder<T extends QuerySchema> {
@@ -80,7 +121,41 @@ filters?: QueryFilters<T> | undefined;
     constructor(filters?: QueryFilters<T> | undefined);
+    /**
+     * Builds an SQL condition string for a specific column and operator.
+     *
+     * @param {string} column - The name of the column.
+     * @param {keyof QueryFilterOperators} operator - The operator to apply.
+     * @param {any} value - The value to compare against.
+     *
+     * @returns {string} The SQL condition string.
+     */
     private _buildWhereCondition;
+    /**
+     * Builds an SQL WHERE clause from the provided filters.
+     *
+     * @param {QueryFilters<T>} [filters] - The filters to convert into an SQL WHERE clause.
+     *
+     * @returns {string} The generated SQL WHERE clause.
+     */
     private _buildWhereClause;
+    /**
+     * Extracts the values from the filters to be used in the prepared statement corresponding to the WHERE clause.
+     *
+     * @param {QueryFilters<T>} [filters] - The filters to extract values from.
+     *
+     * @returns {T[keyof T][]} An array of values extracted from the filters.
+     */
     private _extractValues;
 }
 
+/**
+ * Type representing the options that can be applied to a query.
+ *
+ * @typeParam T - The schema type being queried.
+ *
+ * @property {(keyof T)[]} [columns] - An optional array of column names to select in the query.
+ * @property {(keyof T)[]} [groupBy] - An optional array of column names to group the results by.
+ * @property {Record<keyof T, "asc" | "desc">} [orderBy] - An optional object defining the columns to order by and the direction of sorting.
+ * @property {number} [limit] - An optional number to limit the number of results returned.
+ * @property {number} [offset] - An optional number to offset the results by a specific number of rows.
+ */
 type QueryOptions<T extends QuerySchema> = {
@@ -95,3 +170,17 @@ columns?: (keyof T)[];
 };
+/**
+ * An array of keys that correspond to valid query options.
+ *
+ * Used to validate and handle query options in the `QueryOptionsBuilder`.
+ */
 declare const queryOptionKeys: Exclude<keyof QueryOptions<QuerySchema>, undefined>[];
+/**
+ * Class responsible for building SQL clauses from query options.
+ *
+ * @typeParam T - The schema type being queried.
+ *
+ * @property {string} columns - The SQL columns clause generated from the query options.
+ * @property {Record<Exclude<keyof QueryOptions<T>, "columns">, string>} clauses - An object containing the SQL clauses generated from the query options.
+ * @property {QueryOptions<T>} [options] - The query options used to generate the SQL clauses.
+ */
 declare class QueryOptionsBuilder<T extends QuerySchema> {
@@ -102,10 +191,65 @@ options?: QueryOptions<T> | undefined;
     constructor(options?: QueryOptions<T> | undefined);
+    /**
+     * Builds the SQL columns clause based on the provided columns option.
+     *
+     * @param {QueryOptions<T>["columns"]} [columns] - The columns to select in the query.
+     *
+     * @returns {string} The SQL columns clause.
+     */
     private _buildColumnsClause;
+    /**
+     * Builds the SQL GROUP BY clause based on the provided groupBy option.
+     *
+     * @param {QueryOptions<T>["groupBy"]} [groupBy] - The columns to group the results by.
+     *
+     * @returns {string} The SQL GROUP BY clause.
+     */
     private _buildGroupByClause;
+    /**
+     * Builds the SQL ORDER BY clause based on the provided orderBy option.
+     *
+     * @param {QueryOptions<T>["orderBy"]} [orderBy] - The columns to order the results by and the direction of sorting.
+     *
+     * @returns {string} The SQL ORDER BY clause.
+     */
     private _buildOrderByClause;
+    /**
+     * Builds the SQL LIMIT clause based on the provided limit option.
+     *
+     * @param {QueryOptions<T>["limit"]} [limit] - The number to limit the results by.
+     *
+     * @returns {string} The SQL LIMIT clause.
+     */
     private _buildLimitClause;
+    /**
+     * Builds the SQL OFFSET clause based on the provided offset option.
+     *
+     * @param {QueryOptions<T>["offset"]} [offset] - The number to offset the results by.
+     *
+     * @returns {string} The SQL OFFSET clause.
+     */
     private _buildOffsetClause;
 }
 
+/**
+ * Type representing the possible argument combinations that can be passed to the `QueryBuilder` constructor.
+ *
+ * @typeParam T - The schema type being queried.
+ *
+ * This type allows for the following combinations:
+ * - Only filters
+ * - Only options
+ * - Both filters and options
+ */
 type QueryBuilderArgs<T extends QuerySchema> = [filters?: QueryFilters<T>] | [options?: QueryOptions<T>] | [filters?: QueryFilters<T>, options?: QueryOptions<T>];
+/**
+ * Class responsible for building SQL query strings from filters and options.
+ *
+ * @typeParam T - The schema type being queried.
+ *
+ * @property {string} columns - The SQL columns clause generated from the query options.
+ * @property {Record<"where" | Exclude<keyof QueryOptions<T>, "columns">, string>} clauses - An object containing the SQL clauses generated from the filters and options.
+ * @property {string} clause - The complete SQL query string composed of all the clauses.
+ * @property {T[keyof T][]} values - The array of values corresponding to the placeholders in the SQL query.
+ */
 declare class QueryBuilder<T extends QuerySchema> {
@@ -116,11 +260,185 @@ columns: string;
     values: T[keyof T][];
+    /**
+     * Constructs a new `QueryBuilder` instance.
+     *
+     * @param {...QueryBuilderArgs<T>} args - The filters and/or options used to build the SQL query.
+     *
+     * This constructor initializes the query builder by processing the provided filters and options,
+     * and generates the corresponding SQL query string and values.
+     */
     constructor(...args: QueryBuilderArgs<T>);
 }
 
+/**
+ * Type utility to extract the `QueryOptions` from the arguments passed to the `QueryBuilder`.
+ *
+ * @typeParam T - The arguments passed to the `QueryBuilder`.
+ *
+ * This type checks if the first or second argument is of type `QueryOptions`.
+ * If found, it returns the `QueryOptions`, otherwise it returns `never`.
+ */
 type ExtractQueryOptions<T extends QueryBuilderArgs<any>> = T extends [infer A] ? A extends QueryOptions<any> ? A : never : T extends [any, infer B] ? B extends QueryOptions<any> ? B : never : never;
+/**
+ * Type utility to extract the columns specified in the `QueryOptions`.
+ *
+ * @typeParam T - The schema type being queried.
+ * @typeParam U - The extracted `QueryOptions`.
+ *
+ * If the `columns` option is specified in `QueryOptions`, this type returns a `Pick` of the schema with only those columns.
+ * If `columns` is not specified, it returns the entire schema.
+ */
 type ExtractQueryColumns<T extends QuerySchema, U extends ExtractQueryOptions<any>> = U["columns"] extends never ? T : U["columns"] extends string[] ? Pick<T, U["columns"][number]> : T;
 
+/**
+ * Represents a type for database column definitions. This is currently set to `any`
+ * to allow flexibility in defining various column types.
+ */
+type ColumnType = any;
+/**
+ * Interface representing the schema of a database column.
+ *
+ * @property {string} name - The name of the column.
+ * @property {string} type - The SQL data type of the column.
+ * @property {boolean} [nullable] - Indicates whether the column allows NULL values.
+ * @property {boolean} [primaryKey] - Indicates whether the column is a primary key.
+ * @property {boolean} [autoIncrement] - Indicates whether the column is auto-incremented.
+ * @property {any} [default] - The default value for the column.
+ * @property {string[]} [clauses] - Additional SQL clauses for the column definition.
+ */
+interface ColumnSchema {
+    name: string;
+    type: string;
+    nullable?: boolean;
+    primaryKey?: boolean;
+    autoIncrement?: boolean;
+    default?: any;
+    clauses?: string[];
+}
+/**
+ * Interface representing information about a column in the database.
+ *
+ * @typeParam T - A string literal representing the column name.
+ *
+ * @property {T} name - The name of the column.
+ * @property {string} type - The SQL data type of the column.
+ * @property {string} null - Indicates whether the column allows NULL values (`"YES"` or `"NO"`).
+ * @property {string} key - The key type of the column (`"PRI"` for primary key, `"UNI"` for unique key, etc.).
+ * @property {any} default - The default value for the column.
+ * @property {string} extra - Any extra information about the column (e.g., `auto_increment`).
+ */
+interface ColumnInfo<T extends string = string> {
+    name: T;
+    type: string;
+    null: string;
+    key: string;
+    default: any;
+    extra: string;
+}
+/**
+ * Class representing a database column and providing methods to manage its schema.
+ */
+declare class Column {
+    private _connection;
+    databaseName: string;
+    tableName: string;
+    name: string;
+    private _path;
+    /**
+     * Constructs a new `Column` instance.
+     *
+     * @param {Connection} _connection - The database connection used to execute queries.
+     * @param {string} databaseName - The name of the database containing the column.
+     * @param {string} tableName - The name of the table containing the column.
+     * @param {string} name - The name of the column.
+     */
+    constructor(_connection: Connection, databaseName: string, tableName: string, name: string);
+    /**
+     * Normalizes raw database column information into a structured `ColumnInfo` object.
+     *
+     * @typeParam T - A string literal representing the column name.
+     *
+     * @param {any} info - Raw column information from the database.
+     *
+     * @returns {ColumnInfo<T>} A structured `ColumnInfo` object.
+     */
+    static normalizeInfo<T extends string = string>(info: any): ColumnInfo<T>;
+    /**
+     * Converts a `ColumnSchema` object into an SQL column definition string.
+     *
+     * @param {ColumnSchema} schema - The schema of the column to be converted.
+     *
+     * @returns {string} An SQL string representing the column definition.
+     */
+    static schemaToClauses(schema: ColumnSchema): string;
+    /**
+     * Adds a new column to a specified table in the database.
+     *
+     * @param {Connection} connection - The database connection used to execute the query.
+     * @param {string} databaseName - The name of the database where the table is located.
+     * @param {string} tableName - The name of the table where the column will be added.
+     * @param {ColumnSchema} schema - The schema of the column to be added.
+     *
+     * @returns {Promise<Column>} A promise that resolves to the created `Column` instance.
+     */
+    static add(connection: Connection, databaseName: string, tableName: string, schema: ColumnSchema): Promise<Column>;
+    /**
+     * Drops a column from a specified table in the database.
+     *
+     * @param {Connection} connection - The database connection used to execute the query.
+     * @param {string} databaseName - The name of the database where the table is located.
+     * @param {string} tableName - The name of the table containing the column.
+     * @param {string} name - The name of the column to be dropped.
+     *
+     * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the column is dropped.
+     */
+    static drop(connection: Connection, databaseName: string, tableName: string, name: string): Promise<[ResultSetHeader, FieldPacket[]]>;
+    /**
+     * Retrieves information about the current column from the database.
+     *
+     * @returns {Promise<ColumnInfo<string>>} A promise that resolves to the `ColumnInfo` object containing details about the column.
+     */
+    showInfo(): Promise<ColumnInfo<string>>;
+    /**
+     * Drops the current column from the table.
+     *
+     * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the column is dropped.
+     */
+    drop(): Promise<[ResultSetHeader, FieldPacket[]]>;
+    /**
+     * Modifies the current column in the table based on the provided schema.
+     *
+     * @param {Partial<Omit<ColumnSchema, "name">>} schema - The schema containing modifications to be applied to the column.
+     *
+     * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the column is modified.
+     */
+    modify(schema: Partial<Omit<ColumnSchema, "name">>): Promise<[ResultSetHeader, FieldPacket[]]>;
+    /**
+     * Renames the current column in the table.
+     *
+     * @param {string} newName - The new name for the column.
+     *
+     * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the column is renamed.
+     */
+    rename(newName: string): Promise<[ResultSetHeader, FieldPacket[]]>;
+}
+
+/**
+ * Interface representing the structure of a table type, including its columns.
+ *
+ * @property {Record<string, ColumnType>} columns - A record where the keys are column names and the values are their respective column types.
+ */
 interface TableType {
     columns: Record<string, ColumnType>;
 }
+/**
+ * Interface representing the schema of a table, including its columns, primary keys, full-text keys, and additional clauses.
+ *
+ * @typeParam T - A type extending `TableType` that defines the structure of the table.
+ *
+ * @property {string} name - The name of the table.
+ * @property {Object} columns - An object where each key is a column name and each value is the schema of that column, excluding the name.
+ * @property {string[]} [primaryKeys] - An optional array of column names that form the primary key.
+ * @property {string[]} [fulltextKeys] - An optional array of column names that form full-text keys.
+ * @property {string[]} [clauses] - An optional array of additional SQL clauses for the table definition.
+ */
 interface TableSchema<T extends TableType> {
@@ -135,5 +453,21 @@ name: string;
 }
+/**
+ * Interface representing basic information about a table.
+ *
+ * @typeParam T - A string literal representing the table name.
+ *
+ * @property {T} name - The name of the table.
+ */
 interface TableInfo<T extends string> {
     name: T;
 }
+/**
+ * Interface extending `TableInfo` to include additional details about the table's type, distribution, and storage.
+ *
+ * @typeParam T - A string literal representing the table name.
+ *
+ * @property {string} tableType - The type of the table.
+ * @property {boolean} distributed - Indicates whether the table is distributed.
+ * @property {string} storageType - The storage type of the table.
+ */
 interface TableInfoExtended<T extends string> extends TableInfo<T> {
@@ -144,4 +478,25 @@ tableType: string;
 }
+/**
+ * Type representing the name of a column within a specific table type.
+ *
+ * @typeParam T - The type of the table.
+ */
 type TableColumnName<T extends TableType> = Extract<keyof T["columns"], string>;
+/**
+ * Type representing a key used for vector scoring in vector search queries.
+ */
 type VectorScoreKey = "v_score";
+/**
+ * Class representing a table in SingleStore, providing methods to manage its columns, query data, and perform vector search.
+ *
+ * @typeParam T - The type of the table, which extends `TableType`.
+ * @typeParam U - The type of AI functionalities integrated with the table, which can be undefined.
+ *
+ * @property {Connection} _connection - The connection to the database containing the table.
+ * @property {string} databaseName - The name of the database containing the table.
+ * @property {string} name - The name of the table.
+ * @property {U} [ai] - Optional AI functionalities associated with the table.
+ * @property {string} _path - The full path of the table, composed of the database name and table name.
+ * @property {VectorScoreKey} vScoreKey - The key used for vector scoring in vector search queries, defaulting to `"v_score"`.
+ */
 declare class Table<T extends TableType = TableType, U extends AnyAI | undefined = undefined> {
@@ -156,18 +511,151 @@ private _connection;
     private get ai();
+    /**
+     * Normalizes raw table information into a structured object.
+     *
+     * @typeParam T - A string literal representing the table name.
+     * @typeParam U - A boolean indicating whether extended information is requested.
+     *
+     * @param {any} info - The raw table information to normalize.
+     * @param {U} [extended] - Whether to include extended information.
+     *
+     * @returns {U extends true ? TableInfoExtended<T> : TableInfo<T>} A structured object containing normalized table information.
+     */
     static normalizeInfo<T extends string, U extends boolean>(info: any, extended?: U): U extends true ? TableInfoExtended<T> : TableInfo<T>;
+    /**
+     * Converts a `TableSchema` object into an SQL table definition string.
+     *
+     * @param {TableSchema<any>} schema - The schema of the table to be converted.
+     *
+     * @returns {string} An SQL string representing the table definition.
+     */
     static schemaToClauses(schema: TableSchema<any>): string;
+    /**
+     * Creates a new table in the database with the specified schema.
+     *
+     * @typeParam T - The type of the table to create.
+     * @typeParam U - The type of AI functionalities associated with the table, which can be undefined.
+     *
+     * @param {Connection} connection - The connection to the database.
+     * @param {string} databaseName - The name of the database where the table will be created.
+     * @param {TableSchema<T>} schema - The schema defining the structure of the table.
+     * @param {U} [ai] - Optional AI functionalities to associate with the table.
+     *
+     * @returns {Promise<Table<T, U>>} A promise that resolves to the created `Table` instance.
+     */
     static create<T extends TableType = TableType, U extends AnyAI | undefined = undefined>(connection: Connection, databaseName: string, schema: TableSchema<T>, ai?: U): Promise<Table<T, U>>;
-    static drop(connection: Connection, databaseName: string, name: string): Promise<[ResultSetHeader, mysql2_promise.FieldPacket[]]>;
-    showInfo<K extends boolean>(extended?: K): Promise<K extends true ? TableInfoExtended<string> : TableInfo<string>>;
-    drop(): Promise<[ResultSetHeader, mysql2_promise.FieldPacket[]]>;
+    /**
+     * Drops an existing table from the database by name.
+     *
+     * @param {Connection} connection - The connection to the database.
+     * @param {string} databaseName - The name of the database where the table is located.
+     * @param {string} name - The name of the table to drop.
+     *
+     * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the table is dropped.
+     */
+    static drop(connection: Connection, databaseName: string, name: string): Promise<[ResultSetHeader, FieldPacket[]]>;
+    /**
+     * Retrieves information about the table, optionally including extended details.
+     *
+     * @typeParam K - A boolean indicating whether extended information is requested.
+     *
+     * @param {K} [extended] - Whether to include extended information.
+     *
+     * @returns {Promise<K extends true ? TableInfoExtended<string> : TableInfo<string>>} A promise that resolves to the table information.
+     */
+    showInfo<K extends boolean = false>(extended?: K): Promise<K extends true ? TableInfoExtended<string> : TableInfo<string>>;
+    /**
+     * Drops the current table from the database.
+     *
+     * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the table is dropped.
+     */
+    drop(): Promise<[ResultSetHeader, FieldPacket[]]>;
+    /**
+     * Retrieves a `Column` instance representing a specific column in the table.
+     *
+     * @param {TableColumnName<T> | (string & {})} name - The name of the column to retrieve.
+     *
+     * @returns {Column} A `Column` instance representing the specified column.
+     */
     column(name: TableColumnName<T> | (string & {})): Column;
-    showColumnsInfo(): Promise<ColumnInfo<Extract<keyof T["columns"], string>>[]>;
+    /**
+     * Retrieves information about all columns in the table.
+     *
+     * @returns {Promise<ColumnInfo<TableColumnName<T>>[]>} A promise that resolves to an array of column information objects.
+     */
+    showColumnsInfo(): Promise<ColumnInfo<TableColumnName<T>>[]>;
+    /**
+     * Adds a new column to the table with the specified schema.
+     *
+     * @param {ColumnSchema} schema - The schema defining the structure of the column to be added.
+     *
+     * @returns {Promise<Column>} A promise that resolves to the created `Column` instance.
+     */
     addColumn(schema: ColumnSchema): Promise<Column>;
-    dropColumn(name: TableColumnName<T> | (string & {})): Promise<[ResultSetHeader, mysql2_promise.FieldPacket[]]>;
-    truncate(): Promise<[ResultSetHeader, mysql2_promise.FieldPacket[]]>;
-    rename(newName: string): Promise<[ResultSetHeader, mysql2_promise.FieldPacket[]]>;
-    insert(values: Partial<T["columns"]> | Partial<T["columns"]>[]): Promise<[ResultSetHeader, mysql2_promise.FieldPacket[]][]>;
+    /**
+     * Drops a specific column from the table by name.
+     *
+     * @param {TableColumnName<T> | (string & {})} name - The name of the column to drop.
+     *
+     * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the column is dropped.
+     */
+    dropColumn(name: TableColumnName<T> | (string & {})): Promise<[ResultSetHeader, FieldPacket[]]>;
+    /**
+     * Truncates the table, removing all rows while keeping the table structure intact.
+     *
+     * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the table is truncated.
+     */
+    truncate(): Promise<[ResultSetHeader, FieldPacket[]]>;
+    /**
+     * Renames the current table to a new name.
+     *
+     * @param {string} newName - The new name for the table.
+     *
+     * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the table is renamed.
+     */
+    rename(newName: string): Promise<[ResultSetHeader, FieldPacket[]]>;
+    /**
+     * Inserts one or more rows into the table.
+     *
+     * @param {Partial<T["columns"]> | Partial<T["columns"]>[]} values - The values to insert into the table. Can be a single row or an array of rows.
+     *
+     * @returns {Promise<[ResultSetHeader, FieldPacket[]][]>} A promise that resolves to an array of `ResultSetHeader` objects for each inserted row.
+     */
+    insert(values: Partial<T["columns"]> | Partial<T["columns"]>[]): Promise<[ResultSetHeader, FieldPacket[]][]>;
+    /**
+     * Selects rows from the table based on the specified query arguments.
+     *
+     * @typeParam K - The type of the query builder arguments.
+     *
+     * @param {...K} args - The arguments defining the query, including selected columns, filters, and other options.
+     *
+     * @returns {Promise<(ExtractQueryColumns<T["columns"], ExtractQueryOptions<K>> & RowDataPacket)[]>} A promise that resolves to an array of selected rows.
+     */
     select<K extends QueryBuilderArgs<T["columns"]>>(...args: K): Promise<(ExtractQueryColumns<T["columns"], ExtractQueryOptions<K>> & RowDataPacket)[]>;
-    update(values: Partial<T["columns"]>, filters: QueryFilters<T["columns"]>): Promise<[ResultSetHeader, mysql2_promise.FieldPacket[]]>;
-    delete(filters?: QueryFilters<T["columns"]>): Promise<[ResultSetHeader, mysql2_promise.FieldPacket[]]>;
+    /**
+     * Updates rows in the table based on the specified values and filters.
+     *
+     * @param {Partial<T["columns"]>} values - The values to update in the table.
+     * @param {QueryFilters<T["columns"]>} filters - The filters to apply to the update query.
+     *
+     * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the update is complete.
+     */
+    update(values: Partial<T["columns"]>, filters: QueryFilters<T["columns"]>): Promise<[ResultSetHeader, FieldPacket[]]>;
+    /**
+     * Deletes rows from the table based on the specified filters. If no filters are provided, the table is truncated.
+     *
+     * @param {QueryFilters<T["columns"]>} [filters] - The filters to apply to the delete query.
+     *
+     * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the delete operation is complete.
+     */
+    delete(filters?: QueryFilters<T["columns"]>): Promise<[ResultSetHeader, FieldPacket[]]>;
+    /**
+     * Performs a vector search on the table using a prompt and a vector column.
+     *
+     * @typeParam K - The parameters required for the vector search, including the prompt and vector column.
+     * @typeParam V - The query builder arguments used to refine the search.
+     *
+     * @param {...[params: K, ...V]} args - The arguments defining the vector search, including the prompt, vector column, and query options.
+     *
+     * @returns {Promise<(ExtractQueryColumns<T["columns"], ExtractQueryOptions<V>> & { [K in VectorScoreKey]: number } & RowDataPacket)[]>} A promise that resolves to an array of rows matching the vector search.
+     */
     vectorSearch<K extends {
@@ -180,2 +668,12 @@ prompt: string;
     } & RowDataPacket)[]>;
+    /**
+     * Creates a chat completion using a vector search to provide context, and generates a response based on the prompt.
+     *
+     * @typeParam K - The parameters required for the vector search and chat completion, including the prompt and vector column.
+     * @typeParam V - The query builder arguments used to refine the search.
+     *
+     * @param {...[params: K, ...V]} args - The arguments defining the chat completion, including the prompt, vector column, and query options.
+     *
+     * @returns {Promise<CreateChatCompletionResult<K["stream"]>>} A promise that resolves to the chat completion result.
+     */
     createChatCompletion<K extends Parameters<this["vectorSearch"]>[0] & (U extends AnyAI ? Parameters<U["chatCompletions"]["create"]>[0] : never) & {
@@ -186,5 +684,18 @@ template?: string;
 
+/**
+ * Interface representing the structure of a database type, which includes a record of tables.
+ *
+ * @property {Record<string, TableType>} tables - A record where the keys are table names and the values are their respective table types.
+ */
 interface DatabaseType {
     tables: Record<string, TableType>;
 }
+/**
+ * Interface representing the schema of a database, including its name and optional table schemas.
+ *
+ * @typeParam T - A type extending `DatabaseType` that defines the structure of the database.
+ *
+ * @property {string} name - The name of the database.
+ * @property {Object} [tables] - An optional object where each key is a table name and each value is the schema of that table, excluding the name.
+ */
 interface DatabaseSchema<T extends DatabaseType> {
@@ -196,5 +707,34 @@ name: string;
 }
+/**
+ * Interface representing basic information about a database.
+ *
+ * @typeParam T - A string literal representing the database name.
+ *
+ * @property {T} name - The name of the database.
+ */
 interface DatabaseInfo<T extends string = string> {
     name: T;
 }
+/**
+ * Interface extending `DatabaseInfo` to include additional details about the database's state and performance.
+ *
+ * @typeParam T - A string literal representing the database name.
+ *
+ * @property {number} commits - The number of commits made in the database.
+ * @property {string} role - The role of the database in the cluster.
+ * @property {string} state - The current state of the database.
+ * @property {string} position - The current replication position of the database.
+ * @property {string} details - Additional details about the database.
+ * @property {number} asyncSlaves - The number of asynchronous slaves connected to the database.
+ * @property {string} syncSlaves - The identifier of the synchronous slave.
+ * @property {number} consensusSlaves - The number of consensus slaves in the cluster.
+ * @property {string} committedPosition - The position of the last committed transaction.
+ * @property {string} hardenedPosition - The position of the last hardened transaction.
+ * @property {string} replayPosition - The position of the last replayed transaction.
+ * @property {number} term - The current term in the database's consensus protocol.
+ * @property {number} lastPageTerm - The term of the last page in the database.
+ * @property {number} memoryMBs - The amount of memory used by the database in megabytes.
+ * @property {number} pendingIOs - The number of pending I/O operations.
+ * @property {number} pendingBlobFSyncs - The number of pending blob fsync operations.
+ */
 interface DatabaseInfoExtended<T extends string> extends DatabaseInfo<T> {
@@ -218,7 +758,34 @@ commits: number;
 }
+/**
+ * Type representing a mapping of database tables to their respective records.
+ *
+ * @typeParam T - A record of tables where each key is the table name and each value is the table type.
+ */
 type DatabaseTablesToRecords<T extends DatabaseType["tables"]> = {
     [K in keyof T]: T[K]["columns"][];
 };
+/**
+ * Type representing any database instance, with its associated `Embeddings` and `AI` functionalities.
+ *
+ * @typeParam T - The type of the database.
+ * @typeParam U - The type of the AI functionalities, which can be undefined.
+ */
 type AnyDatabase = Database<any, AnyAI | undefined>;
+/**
+ * Type representing the name of a table within a specific database type.
+ *
+ * @typeParam T - The type of the database.
+ */
 type DatabaseTableName<T extends DatabaseType> = Extract<keyof T["tables"], string>;
+/**
+ * Class representing a database and providing methods to manage its tables and query data.
+ *
+ * @typeParam T - The type of the database, which extends `DatabaseType`.
+ * @typeParam U - The type of AI functionalities integrated with the database, which can be undefined.
+ *
+ * @property {Connection} _connection - The connection to the database.
+ * @property {string} name - The name of the database.
+ * @property {string} [workspaceName] - The name of the workspace the database is associated with.
+ * @property {U} [ai] - Optional AI functionalities associated with the database.
+ */
 declare class Database<T extends DatabaseType = DatabaseType, U extends AnyAI | undefined = undefined> {
@@ -230,6 +797,52 @@ private _connection;
     constructor(_connection: Connection, name: string, workspaceName?: string | undefined, _ai?: U | undefined);
-    static normalizeInfo<T extends string, U extends boolean>(info: any, extended?: U): U extends true ? DatabaseInfoExtended<T> : DatabaseInfo<T>;
+    /**
+     * Normalizes raw database information into a structured object.
+     *
+     * @typeParam T - A string literal representing the database name.
+     * @typeParam U - A boolean indicating whether extended information is requested.
+     *
+     * @param {any} info - The raw database information to normalize.
+     * @param {U} [extended] - Whether to include extended information.
+     *
+     * @returns {U extends true ? DatabaseInfoExtended<T> : DatabaseInfo<T>} A structured object containing normalized database information.
+     */
+    static normalizeInfo<T extends string = string, U extends boolean = false>(info: any, extended?: U): U extends true ? DatabaseInfoExtended<T> : DatabaseInfo<T>;
+    /**
+     * Creates a new database with the specified schema and initializes its tables.
+     *
+     * @typeParam T - The type of the database to create.
+     * @typeParam U - The type of AI functionalities associated with the database, which can be undefined.
+     *
+     * @param {Connection} connection - The connection to the database.
+     * @param {DatabaseSchema<T>} schema - The schema defining the structure of the database.
+     * @param {string} [workspaceName] - The name of the workspace the database is associated with.
+     * @param {U} [ai] - Optional AI functionalities to associate with the database.
+     *
+     * @returns {Promise<Database<T, U>>} A promise that resolves to the created `Database` instance.
+     */
     static create<T extends DatabaseType = DatabaseType, U extends AnyAI | undefined = undefined>(connection: Connection, schema: DatabaseSchema<T>, workspaceName?: string, ai?: U): Promise<Database<T, U>>;
-    static drop(connection: Connection, name: string): Promise<[ResultSetHeader, mysql2_promise.FieldPacket[]]>;
-    showInfo<K extends boolean>(extended?: K): Promise<K extends true ? DatabaseInfoExtended<string> : DatabaseInfo<string>>;
+    /**
+     * Drops an existing database by name.
+     *
+     * @param {Connection} connection - The connection to the database.
+     * @param {string} name - The name of the database to drop.
+     *
+     * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the database is dropped.
+     */
+    static drop(connection: Connection, name: string): Promise<[ResultSetHeader, FieldPacket[]]>;
+    /**
+     * Retrieves information about the database, optionally including extended details.
+     *
+     * @typeParam K - A boolean indicating whether extended information is requested.
+     *
+     * @param {K} [extended] - Whether to include extended information.
+     *
+     * @returns {Promise<K extends true ? DatabaseInfoExtended<string> : DatabaseInfo<string>>} A promise that resolves to the database information.
+     */
+    showInfo<K extends boolean = false>(extended?: K): Promise<K extends true ? DatabaseInfoExtended<string> : DatabaseInfo<string>>;
+    /**
+     * Describes the database by providing its detailed information along with the structure of its tables.
+     *
+     * @returns {Promise<any>} A promise that resolves to an object containing the database's details and table structures.
+     */
     describe(): Promise<{
@@ -261,13 +874,75 @@ tables: {
     }>;
-    drop(): Promise<[ResultSetHeader, mysql2_promise.FieldPacket[]]>;
+    /**
+     * Drops the current database.
+     *
+     * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the database is dropped.
+     */
+    drop(): Promise<[ResultSetHeader, FieldPacket[]]>;
+    /**
+     * Retrieves a `Table` instance representing a specific table in the database.
+     *
+     * @typeParam K - The type of the table.
+     * @typeParam V - The name of the table, which can be a string literal or a generic string.
+     *
+     * @param {V} name - The name of the table to retrieve.
+     *
+     * @returns {K extends TableType ? K : T["tables"][V] extends TableType ? T["tables"][V] : TableType} A `Table` instance representing the specified table.
+     */
     table<K, V extends DatabaseTableName<T> | (string & {}) = DatabaseTableName<T> | (string & {})>(name: V): Table<K extends TableType ? K : T["tables"][V] extends TableType ? T["tables"][V] : TableType, U>;
-    showTablesInfo<K extends boolean>(extended?: K): Promise<(K extends true ? TableInfoExtended<Extract<keyof T["tables"], string>> : TableInfo<Extract<keyof T["tables"], string>>)[]>;
+    /**
+     * Retrieves information about all tables in the database, optionally including extended details.
+     *
+     * @typeParam K - A boolean indicating whether extended information is requested.
+     *
+     * @param {K} [extended] - Whether to include extended information.
+     *
+     * @returns {Promise<Result<Extract<keyof T["tables"], string>, K>[]>} A promise that resolves to an array of table information objects.
+     */
+    showTablesInfo<K extends boolean = false>(extended?: K): Promise<(K extends true ? TableInfoExtended<Extract<keyof T["tables"], string>> : TableInfo<Extract<keyof T["tables"], string>>)[]>;
+    /**
+     * Creates a new table in the database with the specified schema.
+     *
+     * @typeParam K - The type of the table to create.
+     *
+     * @param {TableSchema<K>} schema - The schema defining the structure of the table.
+     *
+     * @returns {Promise<Table<K, U>>} A promise that resolves to the created `Table` instance.
+     */
     createTable<K extends TableType = TableType>(schema: TableSchema<K>): Promise<Table<K, U>>;
-    dropTable(name: DatabaseTableName<T> | (string & {})): Promise<[ResultSetHeader, mysql2_promise.FieldPacket[]]>;
-    query<K extends any[]>(statement: string): Promise<K>;
+    /**
+     * Drops a specific table from the database.
+     *
+     * @param {DatabaseTableName<T> | (string & {})} name - The name of the table to drop.
+     *
+     * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the table is dropped.
+     */
+    dropTable(name: DatabaseTableName<T> | (string & {})): Promise<[ResultSetHeader, FieldPacket[]]>;
+    /**
+     * Executes a query against the database after selecting the current database context.
+     *
+     * @typeParam K - The expected result type of the query.
+     *
+     * @param {string} statement - The SQL query statement to execute.
+     *
+     * @returns {Promise<K[]>} A promise that resolves to the result of the query.
+     */
+    query<K extends any[]>(statement: string): Promise<K[]>;
 }
 
+/**
+ * Interface representing the structure of a workspace type, which includes a record of databases.
+ *
+ * @property {Record<string, DatabaseType>} databases - A record where the keys are database names and the values are their respective database types.
+ */
 interface WorkspaceType {
     databases: Record<string, DatabaseType>;
 }
+/**
+ * Interface representing the schema of a workspace, including its name and database schemas.
+ *
+ * @typeParam T - A type extending `WorkspaceType` that defines the structure of the workspace.
+ *
+ * @property {string} name - The name of the workspace.
+ * @property {Object} databases - An object where each key is a database name and each value is the schema of that database, excluding the name.
+ */
 interface WorkspaceSchema<T extends WorkspaceType> {
@@ -279,2 +954,13 @@ name: string;
 }
+/**
+ * Configuration object for connecting to a workspace within `Workspace`.
+ *
+ * Extends `ConnectionConfig` to include optional properties `name` and `ai`.
+ *
+ * @typeParam T - The type of the workspace to connect to.
+ * @typeParam U - The type of AI functionalities integrated with the workspace, which can be undefined.
+ *
+ * @property {string} [name] - The name of the workspace.
+ * @property {U} [ai] - Optional AI functionalities to associate with the workspace.
+ */
 interface ConnectWorkspaceConfig<T extends WorkspaceType, U extends AnyAI | undefined> extends ConnectionConfig {
@@ -284,3 +970,18 @@ name?: WorkspaceSchema<T>["name"];
 }
+/**
+ * Type representing the name of a database within a specific workspace type.
+ *
+ * @typeParam T - The type of the workspace.
+ */
 type WorkspaceDatabaseName<T extends WorkspaceType> = Extract<keyof T["databases"], string>;
+/**
+ * Class representing a workspace in SingleStore, providing methods to manage its databases and perform operations.
+ *
+ * @typeParam T - The type of the workspace, which extends `WorkspaceType`.
+ * @typeParam U - The type of AI functionalities integrated with the workspace, which can be undefined.
+ *
+ * @property {Connection} connection - The connection to the workspace.
+ * @property {string} [name] - The name of the workspace.
+ * @property {U} [ai] - Optional AI functionalities associated with the workspace.
+ */
 declare class Workspace<T extends WorkspaceType = WorkspaceType, U extends AnyAI | undefined = undefined> {
@@ -291,17 +992,99 @@ connection: Connection;
     constructor(connection: Connection, name?: string | undefined, _ai?: U | undefined);
+    /**
+     * Connects to a workspace in SingleStore, establishing a connection and associating AI functionalities if provided.
+     *
+     * @typeParam T - The type of the workspace to connect to.
+     * @typeParam U - The type of AI functionalities associated with the workspace, which can be undefined.
+     *
+     * @param {ConnectWorkspaceConfig<T, U>} config - The configuration object for connecting to the workspace.
+     *
+     * @returns {Workspace<T, U>} A `Workspace` instance representing the connected workspace.
+     */
     static connect<T extends WorkspaceType = WorkspaceType, U extends AnyAI | undefined = undefined>({ ai, name, ...config }: ConnectWorkspaceConfig<T, U>): Workspace<T, U>;
+    /**
+     * Retrieves a `Database` instance representing a specific database in the workspace.
+     *
+     * @typeParam K - The type of the database.
+     * @typeParam V - The name of the database, which can be a string literal or a generic string.
+     *
+     * @param {V} name - The name of the database to retrieve.
+     *
+     * @returns {Database<K extends DatabaseType ? K : T["databases"][V] extends DatabaseType ? T["databases"][V] : DatabaseType, U>} A `Database` instance representing the specified database.
+     */
     database<K, V extends WorkspaceDatabaseName<T> | (string & {}) = WorkspaceDatabaseName<T> | (string & {})>(name: V): Database<K extends DatabaseType ? K : T["databases"][V] extends DatabaseType ? T["databases"][V] : DatabaseType, U>;
+    /**
+     * Creates a new database in the workspace with the specified schema.
+     *
+     * @typeParam K - The type of the database to create.
+     *
+     * @param {DatabaseSchema<K>} schema - The schema defining the structure of the database.
+     *
+     * @returns {Promise<Database<K, U>>} A promise that resolves to the created `Database` instance.
+     */
     createDatabase<K extends DatabaseType = DatabaseType>(schema: DatabaseSchema<K>): Promise<Database<K, U>>;
-    dropDatabase(name: WorkspaceDatabaseName<T> | (string & {})): Promise<[mysql2.ResultSetHeader, mysql2.FieldPacket[]]>;
-    showDatabasesInfo<K extends boolean>(extended?: K): Promise<(K extends true ? DatabaseInfoExtended<Extract<keyof T["databases"], string>> : DatabaseInfo<Extract<keyof T["databases"], string>>)[]>;
+    /**
+     * Drops a specific database from the workspace.
+     *
+     * @param {WorkspaceDatabaseName<T> | (string & {})} name - The name of the database to drop.
+     *
+     * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the database is dropped.
+     */
+    dropDatabase(name: WorkspaceDatabaseName<T> | (string & {})): Promise<[ResultSetHeader, FieldPacket[]]>;
+    /**
+     * Retrieves information about all databases in the workspace, optionally including extended details.
+     *
+     * @typeParam K - A boolean indicating whether extended information is requested.
+     *
+     * @param {K} [extended] - Whether to include extended information.
+     *
+     * @returns {Promise<(K extends true ? DatabaseInfoExtended<WorkspaceDatabaseName<T>> : DatabaseInfo<WorkspaceDatabaseName<T>>)[]>} A promise that resolves to an array of database information objects.
+     */
+    showDatabasesInfo<K extends boolean = false>(extended?: K): Promise<(K extends true ? DatabaseInfoExtended<WorkspaceDatabaseName<T>> : DatabaseInfo<WorkspaceDatabaseName<T>>)[]>;
 }
 
+/**
+ * Configuration object for initializing a `SingleStoreClient` instance.
+ *
+ * @typeParam T - The type of AI functionalities integrated with the client, which can be undefined.
+ *
+ * @property {T} [ai] - Optional AI functionalities to associate with the `SingleStoreClient`.
+ */
 interface SingleStoreClientConfig<T extends AnyAI | undefined> {
     ai?: T;
 }
+/**
+ * Configuration object for connecting to a workspace within `SingleStoreClient`.
+ *
+ * Extends `Omit<ConnectWorkspaceConfig<T, U>, "ai">` to include all properties of `ConnectWorkspaceConfig`
+ * except `ai`, which is provided by the `SingleStoreClient` itself.
+ *
+ * @typeParam T - The type of the workspace to connect to.
+ * @typeParam U - The type of AI functionalities integrated with the workspace, which can be undefined.
+ */
 interface WorkspaceConfig<T extends WorkspaceType, U extends AnyAI | undefined> extends Omit<ConnectWorkspaceConfig<T, U>, "ai"> {
 }
+/**
+ * Main client class for interacting with SingleStore, including the ability to connect to workspaces.
+ *
+ * @typeParam T - The type of AI functionalities integrated with the client, which can be undefined.
+ *
+ * @property {T} _ai - The AI functionalities associated with the `SingleStoreClient`.
+ */
 declare class SingleStoreClient<T extends AnyAI | undefined = undefined> {
     private _ai;
+    /**
+     * Constructs a new `SingleStoreClient` instance.
+     *
+     * @param {SingleStoreClientConfig<T>} [config] - The configuration object for initializing the `SingleStoreClient`.
+     */
     constructor(config?: SingleStoreClientConfig<T>);
+    /**
+     * Connects to a workspace within the SingleStore environment.
+     *
+     * @typeParam U - The type of the workspace to connect to.
+     *
+     * @param {WorkspaceConfig<U, T>} config - The configuration object for connecting to the workspace.
+     *
+     * @returns {Workspace<U, T>} A `Workspace` instance representing the connected workspace.
+     */
     workspace<U extends WorkspaceType = WorkspaceType>(config: WorkspaceConfig<U, T>): Workspace<U, T>;
@@ -308,0 +1091,0 @@ }

dist/index.js

@@ -30,2 +30,7 @@ "use strict";
 var Connection = class _Connection {
+  /**
+   * Constructs a new `Connection` instance and initializes the connection pool.
+   *
+   * @param {ConnectionConfig} config - The configuration object for the connection pool.
+   */
   constructor(config) {
@@ -36,5 +41,17 @@ this.config = config;
   client;
+  /**
+   * Factory method to create a new `Connection` instance.
+   *
+   * @param {ConnectionConfig} config - The configuration object for the connection pool.
+   *
+   * @returns {Connection} A new `Connection` instance.
+   */
   static create(config) {
     return new _Connection(config);
   }
+  /**
+   * Disconnects from the database by closing the connection pool.
+   *
+   * @returns {Promise<void>} A promise that resolves when the connection pool is closed.
+   */
   async disconnect() {
@@ -47,2 +64,10 @@ await this.client.end();
 var Column = class _Column {
+  /**
+   * Constructs a new `Column` instance.
+   *
+   * @param {Connection} _connection - The database connection used to execute queries.
+   * @param {string} databaseName - The name of the database containing the column.
+   * @param {string} tableName - The name of the table containing the column.
+   * @param {string} name - The name of the column.
+   */
   constructor(_connection, databaseName, tableName, name) {
@@ -56,2 +81,11 @@ this._connection = _connection;
   _path;
+  /**
+   * Normalizes raw database column information into a structured `ColumnInfo` object.
+   *
+   * @typeParam T - A string literal representing the column name.
+   *
+   * @param {any} info - Raw column information from the database.
+   *
+   * @returns {ColumnInfo<T>} A structured `ColumnInfo` object.
+   */
   static normalizeInfo(info) {
@@ -67,2 +101,9 @@ return {
   }
+  /**
+   * Converts a `ColumnSchema` object into an SQL column definition string.
+   *
+   * @param {ColumnSchema} schema - The schema of the column to be converted.
+   *
+   * @returns {string} An SQL string representing the column definition.
+   */
   static schemaToClauses(schema) {
@@ -77,2 +118,12 @@ const clauses = [`\`${schema.name}\``];
   }
+  /**
+   * Adds a new column to a specified table in the database.
+   *
+   * @param {Connection} connection - The database connection used to execute the query.
+   * @param {string} databaseName - The name of the database where the table is located.
+   * @param {string} tableName - The name of the table where the column will be added.
+   * @param {ColumnSchema} schema - The schema of the column to be added.
+   *
+   * @returns {Promise<Column>} A promise that resolves to the created `Column` instance.
+   */
   static async add(connection, databaseName, tableName, schema) {
@@ -84,2 +135,12 @@ const clauses = _Column.schemaToClauses(schema);
   }
+  /**
+   * Drops a column from a specified table in the database.
+   *
+   * @param {Connection} connection - The database connection used to execute the query.
+   * @param {string} databaseName - The name of the database where the table is located.
+   * @param {string} tableName - The name of the table containing the column.
+   * @param {string} name - The name of the column to be dropped.
+   *
+   * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the column is dropped.
+   */
   static drop(connection, databaseName, tableName, name) {
@@ -89,2 +150,7 @@ return connection.client.execute(`      ALTER TABLE ${databaseName}.${tableName} DROP COLUMN ${name}
   }
+  /**
+   * Retrieves information about the current column from the database.
+   *
+   * @returns {Promise<ColumnInfo<string>>} A promise that resolves to the `ColumnInfo` object containing details about the column.
+   */
   async showInfo() {
@@ -96,5 +162,17 @@ const [rows] = await this._connection.client.query(
   }
+  /**
+   * Drops the current column from the table.
+   *
+   * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the column is dropped.
+   */
   drop() {
     return _Column.drop(this._connection, this.databaseName, this.tableName, this.name);
   }
+  /**
+   * Modifies the current column in the table based on the provided schema.
+   *
+   * @param {Partial<Omit<ColumnSchema, "name">>} schema - The schema containing modifications to be applied to the column.
+   *
+   * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the column is modified.
+   */
   modify(schema) {
@@ -105,2 +183,9 @@ const clauses = _Column.schemaToClauses({ type: "", ...schema, name: this.name });
   }
+  /**
+   * Renames the current column in the table.
+   *
+   * @param {string} newName - The new name for the column.
+   *
+   * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the column is renamed.
+   */
   async rename(newName) {
@@ -123,2 +208,11 @@ const result = await this._connection.client.execute(`      ALTER TABLE ${this._path} CHANGE ${this.name} ${newName}
   values = [];
+  /**
+   * Builds an SQL condition string for a specific column and operator.
+   *
+   * @param {string} column - The name of the column.
+   * @param {keyof QueryFilterOperators} operator - The operator to apply.
+   * @param {any} value - The value to compare against.
+   *
+   * @returns {string} The SQL condition string.
+   */
   _buildWhereCondition(column, operator, value) {
@@ -148,2 +242,9 @@ switch (operator) {
   }
+  /**
+   * Builds an SQL WHERE clause from the provided filters.
+   *
+   * @param {QueryFilters<T>} [filters] - The filters to convert into an SQL WHERE clause.
+   *
+   * @returns {string} The generated SQL WHERE clause.
+   */
   _buildWhereClause(filters) {
@@ -166,2 +267,9 @@ if (!filters) return "";
   }
+  /**
+   * Extracts the values from the filters to be used in the prepared statement corresponding to the WHERE clause.
+   *
+   * @param {QueryFilters<T>} [filters] - The filters to extract values from.
+   *
+   * @returns {T[keyof T][]} An array of values extracted from the filters.
+   */
   _extractValues(filters) {
@@ -211,8 +319,29 @@ if (!filters) return [];
   };
+  /**
+   * Builds the SQL columns clause based on the provided columns option.
+   *
+   * @param {QueryOptions<T>["columns"]} [columns] - The columns to select in the query.
+   *
+   * @returns {string} The SQL columns clause.
+   */
   _buildColumnsClause(columns) {
     return columns?.length ? columns.join(", ") : "*";
   }
+  /**
+   * Builds the SQL GROUP BY clause based on the provided groupBy option.
+   *
+   * @param {QueryOptions<T>["groupBy"]} [groupBy] - The columns to group the results by.
+   *
+   * @returns {string} The SQL GROUP BY clause.
+   */
   _buildGroupByClause(groupBy) {
     return groupBy?.length ? `GROUP BY ${groupBy.join(", ")}` : "";
   }
+  /**
+   * Builds the SQL ORDER BY clause based on the provided orderBy option.
+   *
+   * @param {QueryOptions<T>["orderBy"]} [orderBy] - The columns to order the results by and the direction of sorting.
+   *
+   * @returns {string} The SQL ORDER BY clause.
+   */
   _buildOrderByClause(orderBy) {
@@ -223,5 +352,19 @@ if (!orderBy) return "";
   }
+  /**
+   * Builds the SQL LIMIT clause based on the provided limit option.
+   *
+   * @param {QueryOptions<T>["limit"]} [limit] - The number to limit the results by.
+   *
+   * @returns {string} The SQL LIMIT clause.
+   */
   _buildLimitClause(limit) {
     return limit ? `LIMIT ${limit}` : "";
   }
+  /**
+   * Builds the SQL OFFSET clause based on the provided offset option.
+   *
+   * @param {QueryOptions<T>["offset"]} [offset] - The number to offset the results by.
+   *
+   * @returns {string} The SQL OFFSET clause.
+   */
   _buildOffsetClause(offset) {
@@ -244,2 +387,10 @@ return offset ? `OFFSET ${offset}` : "";
   values = [];
+  /**
+   * Constructs a new `QueryBuilder` instance.
+   *
+   * @param {...QueryBuilderArgs<T>} args - The filters and/or options used to build the SQL query.
+   *
+   * This constructor initializes the query builder by processing the provided filters and options,
+   * and generates the corresponding SQL query string and values.
+   */
   constructor(...args) {
@@ -282,2 +433,13 @@ let filtersBuilder = new QueryFiltersBuilder();
   }
+  /**
+   * Normalizes raw table information into a structured object.
+   *
+   * @typeParam T - A string literal representing the table name.
+   * @typeParam U - A boolean indicating whether extended information is requested.
+   *
+   * @param {any} info - The raw table information to normalize.
+   * @param {U} [extended] - Whether to include extended information.
+   *
+   * @returns {U extends true ? TableInfoExtended<T> : TableInfo<T>} A structured object containing normalized table information.
+   */
   static normalizeInfo(info, extended) {
@@ -293,2 +455,9 @@ const name = info[Object.keys(info).find((key) => key.startsWith("Tables_in_"))];
   }
+  /**
+   * Converts a `TableSchema` object into an SQL table definition string.
+   *
+   * @param {TableSchema<any>} schema - The schema of the table to be converted.
+   *
+   * @returns {string} An SQL string representing the table definition.
+   */
   static schemaToClauses(schema) {
@@ -304,2 +473,15 @@ const clauses = [
   }
+  /**
+   * Creates a new table in the database with the specified schema.
+   *
+   * @typeParam T - The type of the table to create.
+   * @typeParam U - The type of AI functionalities associated with the table, which can be undefined.
+   *
+   * @param {Connection} connection - The connection to the database.
+   * @param {string} databaseName - The name of the database where the table will be created.
+   * @param {TableSchema<T>} schema - The schema defining the structure of the table.
+   * @param {U} [ai] - Optional AI functionalities to associate with the table.
+   *
+   * @returns {Promise<Table<T, U>>} A promise that resolves to the created `Table` instance.
+   */
   static async create(connection, databaseName, schema, ai) {
@@ -311,2 +493,11 @@ const clauses = _Table.schemaToClauses(schema);
   }
+  /**
+   * Drops an existing table from the database by name.
+   *
+   * @param {Connection} connection - The connection to the database.
+   * @param {string} databaseName - The name of the database where the table is located.
+   * @param {string} name - The name of the table to drop.
+   *
+   * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the table is dropped.
+   */
   static drop(connection, databaseName, name) {
@@ -316,2 +507,11 @@ return connection.client.execute(`      DROP TABLE IF EXISTS ${databaseName}.${name}
   }
+  /**
+   * Retrieves information about the table, optionally including extended details.
+   *
+   * @typeParam K - A boolean indicating whether extended information is requested.
+   *
+   * @param {K} [extended] - Whether to include extended information.
+   *
+   * @returns {Promise<K extends true ? TableInfoExtended<string> : TableInfo<string>>} A promise that resolves to the table information.
+   */
   async showInfo(extended) {
@@ -324,8 +524,25 @@ const clauses = [`SHOW TABLES IN ${this.databaseName}`];
   }
+  /**
+   * Drops the current table from the database.
+   *
+   * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the table is dropped.
+   */
   drop() {
     return _Table.drop(this._connection, this.databaseName, this.name);
   }
+  /**
+   * Retrieves a `Column` instance representing a specific column in the table.
+   *
+   * @param {TableColumnName<T> | (string & {})} name - The name of the column to retrieve.
+   *
+   * @returns {Column} A `Column` instance representing the specified column.
+   */
   column(name) {
     return new Column(this._connection, this.databaseName, this.name, name);
   }
+  /**
+   * Retrieves information about all columns in the table.
+   *
+   * @returns {Promise<ColumnInfo<TableColumnName<T>>[]>} A promise that resolves to an array of column information objects.
+   */
   async showColumnsInfo() {
@@ -335,8 +552,27 @@ const [rows] = await this._connection.client.query(`SHOW COLUMNS IN ${this.name} IN ${this.databaseName}`);
   }
+  /**
+   * Adds a new column to the table with the specified schema.
+   *
+   * @param {ColumnSchema} schema - The schema defining the structure of the column to be added.
+   *
+   * @returns {Promise<Column>} A promise that resolves to the created `Column` instance.
+   */
   addColumn(schema) {
     return Column.add(this._connection, this.databaseName, this.name, schema);
   }
+  /**
+   * Drops a specific column from the table by name.
+   *
+   * @param {TableColumnName<T> | (string & {})} name - The name of the column to drop.
+   *
+   * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the column is dropped.
+   */
   dropColumn(name) {
     return Column.drop(this._connection, this.databaseName, this.name, name);
   }
+  /**
+   * Truncates the table, removing all rows while keeping the table structure intact.
+   *
+   * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the table is truncated.
+   */
   truncate() {
@@ -346,2 +582,9 @@ return this._connection.client.execute(`      TRUNCATE TABLE ${this._path}
   }
+  /**
+   * Renames the current table to a new name.
+   *
+   * @param {string} newName - The new name for the table.
+   *
+   * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the table is renamed.
+   */
   async rename(newName) {
@@ -354,2 +597,9 @@ const result = await this._connection.client.execute(`      ALTER TABLE ${this._path} RENAME TO ${newName}
   }
+  /**
+   * Inserts one or more rows into the table.
+   *
+   * @param {Partial<T["columns"]> | Partial<T["columns"]>[]} values - The values to insert into the table. Can be a single row or an array of rows.
+   *
+   * @returns {Promise<[ResultSetHeader, FieldPacket[]][]>} A promise that resolves to an array of `ResultSetHeader` objects for each inserted row.
+   */
   insert(values) {
@@ -366,3 +616,11 @@ const _values = Array.isArray(values) ? values : [values];
   }
-  // TODO: Add joins support
+  /**
+   * Selects rows from the table based on the specified query arguments.
+   *
+   * @typeParam K - The type of the query builder arguments.
+   *
+   * @param {...K} args - The arguments defining the query, including selected columns, filters, and other options.
+   *
+   * @returns {Promise<(ExtractQueryColumns<T["columns"], ExtractQueryOptions<K>> & RowDataPacket)[]>} A promise that resolves to an array of selected rows.
+   */
   async select(...args) {
@@ -374,2 +632,10 @@ const { columns, clause, values } = new QueryBuilder(...args);
   }
+  /**
+   * Updates rows in the table based on the specified values and filters.
+   *
+   * @param {Partial<T["columns"]>} values - The values to update in the table.
+   * @param {QueryFilters<T["columns"]>} filters - The filters to apply to the update query.
+   *
+   * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the update is complete.
+   */
   update(values, filters) {
@@ -381,2 +647,9 @@ const { clause, values: _values } = new QueryBuilder(filters);
   }
+  /**
+   * Deletes rows from the table based on the specified filters. If no filters are provided, the table is truncated.
+   *
+   * @param {QueryFilters<T["columns"]>} [filters] - The filters to apply to the delete query.
+   *
+   * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the delete operation is complete.
+   */
   delete(filters) {
@@ -388,2 +661,12 @@ if (!filters) return this.truncate();
   }
+  /**
+   * Performs a vector search on the table using a prompt and a vector column.
+   *
+   * @typeParam K - The parameters required for the vector search, including the prompt and vector column.
+   * @typeParam V - The query builder arguments used to refine the search.
+   *
+   * @param {...[params: K, ...V]} args - The arguments defining the vector search, including the prompt, vector column, and query options.
+   *
+   * @returns {Promise<(ExtractQueryColumns<T["columns"], ExtractQueryOptions<V>> & { [K in VectorScoreKey]: number } & RowDataPacket)[]>} A promise that resolves to an array of rows matching the vector search.
+   */
   async vectorSearch(...args) {
@@ -405,2 +688,12 @@ const [{ prompt, vectorColumn }, ...queryBuilderArgs] = args;
   }
+  /**
+   * Creates a chat completion using a vector search to provide context, and generates a response based on the prompt.
+   *
+   * @typeParam K - The parameters required for the vector search and chat completion, including the prompt and vector column.
+   * @typeParam V - The query builder arguments used to refine the search.
+   *
+   * @param {...[params: K, ...V]} args - The arguments defining the chat completion, including the prompt, vector column, and query options.
+   *
+   * @returns {Promise<CreateChatCompletionResult<K["stream"]>>} A promise that resolves to the chat completion result.
+   */
   async createChatCompletion(...args) {
@@ -432,2 +725,13 @@ const [
   }
+  /**
+   * Normalizes raw database information into a structured object.
+   *
+   * @typeParam T - A string literal representing the database name.
+   * @typeParam U - A boolean indicating whether extended information is requested.
+   *
+   * @param {any} info - The raw database information to normalize.
+   * @param {U} [extended] - Whether to include extended information.
+   *
+   * @returns {U extends true ? DatabaseInfoExtended<T> : DatabaseInfo<T>} A structured object containing normalized database information.
+   */
   static normalizeInfo(info, extended) {
@@ -456,2 +760,15 @@ const name = info[Object.keys(info).find((key) => key.startsWith("Database"))];
   }
+  /**
+   * Creates a new database with the specified schema and initializes its tables.
+   *
+   * @typeParam T - The type of the database to create.
+   * @typeParam U - The type of AI functionalities associated with the database, which can be undefined.
+   *
+   * @param {Connection} connection - The connection to the database.
+   * @param {DatabaseSchema<T>} schema - The schema defining the structure of the database.
+   * @param {string} [workspaceName] - The name of the workspace the database is associated with.
+   * @param {U} [ai] - Optional AI functionalities to associate with the database.
+   *
+   * @returns {Promise<Database<T, U>>} A promise that resolves to the created `Database` instance.
+   */
   static async create(connection, schema, workspaceName, ai) {
@@ -470,5 +787,22 @@ const clauses = [`CREATE DATABASE IF NOT EXISTS ${schema.name}`];
   }
+  /**
+   * Drops an existing database by name.
+   *
+   * @param {Connection} connection - The connection to the database.
+   * @param {string} name - The name of the database to drop.
+   *
+   * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the database is dropped.
+   */
   static drop(connection, name) {
     return connection.client.execute(`DROP DATABASE IF EXISTS ${name}`);
   }
+  /**
+   * Retrieves information about the database, optionally including extended details.
+   *
+   * @typeParam K - A boolean indicating whether extended information is requested.
+   *
+   * @param {K} [extended] - Whether to include extended information.
+   *
+   * @returns {Promise<K extends true ? DatabaseInfoExtended<string> : DatabaseInfo<string>>} A promise that resolves to the database information.
+   */
   async showInfo(extended) {
@@ -481,2 +815,7 @@ const clauses = ["SHOW DATABASES"];
   }
+  /**
+   * Describes the database by providing its detailed information along with the structure of its tables.
+   *
+   * @returns {Promise<any>} A promise that resolves to an object containing the database's details and table structures.
+   */
   async describe() {
@@ -491,8 +830,37 @@ const [info, tablesInfo] = await Promise.all([this.showInfo(true), this.showTablesInfo(true)]);
   }
+  /**
+   * Drops the current database.
+   *
+   * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the database is dropped.
+   */
   drop() {
     return _Database.drop(this._connection, this.name);
   }
+  /**
+   * Retrieves a `Table` instance representing a specific table in the database.
+   *
+   * @typeParam K - The type of the table.
+   * @typeParam V - The name of the table, which can be a string literal or a generic string.
+   *
+   * @param {V} name - The name of the table to retrieve.
+   *
+   * @returns {K extends TableType ? K : T["tables"][V] extends TableType ? T["tables"][V] : TableType} A `Table` instance representing the specified table.
+   */
   table(name) {
-    return new Table(this._connection, this.name, name, this._ai);
+    return new Table(
+      this._connection,
+      this.name,
+      name,
+      this._ai
+    );
   }
+  /**
+   * Retrieves information about all tables in the database, optionally including extended details.
+   *
+   * @typeParam K - A boolean indicating whether extended information is requested.
+   *
+   * @param {K} [extended] - Whether to include extended information.
+   *
+   * @returns {Promise<Result<Extract<keyof T["tables"], string>, K>[]>} A promise that resolves to an array of table information objects.
+   */
   async showTablesInfo(extended) {
@@ -504,8 +872,33 @@ const clauses = [`SHOW TABLES IN ${this.name}`];
   }
+  /**
+   * Creates a new table in the database with the specified schema.
+   *
+   * @typeParam K - The type of the table to create.
+   *
+   * @param {TableSchema<K>} schema - The schema defining the structure of the table.
+   *
+   * @returns {Promise<Table<K, U>>} A promise that resolves to the created `Table` instance.
+   */
   createTable(schema) {
     return Table.create(this._connection, this.name, schema, this._ai);
   }
+  /**
+   * Drops a specific table from the database.
+   *
+   * @param {DatabaseTableName<T> | (string & {})} name - The name of the table to drop.
+   *
+   * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the table is dropped.
+   */
   dropTable(name) {
     return Table.drop(this._connection, this.name, name);
   }
+  /**
+   * Executes a query against the database after selecting the current database context.
+   *
+   * @typeParam K - The expected result type of the query.
+   *
+   * @param {string} statement - The SQL query statement to execute.
+   *
+   * @returns {Promise<K[]>} A promise that resolves to the result of the query.
+   */
   async query(statement) {
@@ -525,2 +918,12 @@ const statements = [`USE ${this.name}`, statement].join(";\n");
   }
+  /**
+   * Connects to a workspace in SingleStore, establishing a connection and associating AI functionalities if provided.
+   *
+   * @typeParam T - The type of the workspace to connect to.
+   * @typeParam U - The type of AI functionalities associated with the workspace, which can be undefined.
+   *
+   * @param {ConnectWorkspaceConfig<T, U>} config - The configuration object for connecting to the workspace.
+   *
+   * @returns {Workspace<T, U>} A `Workspace` instance representing the connected workspace.
+   */
   static connect({
@@ -534,11 +937,46 @@ ai,
   }
+  /**
+   * Retrieves a `Database` instance representing a specific database in the workspace.
+   *
+   * @typeParam K - The type of the database.
+   * @typeParam V - The name of the database, which can be a string literal or a generic string.
+   *
+   * @param {V} name - The name of the database to retrieve.
+   *
+   * @returns {Database<K extends DatabaseType ? K : T["databases"][V] extends DatabaseType ? T["databases"][V] : DatabaseType, U>} A `Database` instance representing the specified database.
+   */
   database(name) {
     return new Database(this.connection, name, this.name, this._ai);
   }
+  /**
+   * Creates a new database in the workspace with the specified schema.
+   *
+   * @typeParam K - The type of the database to create.
+   *
+   * @param {DatabaseSchema<K>} schema - The schema defining the structure of the database.
+   *
+   * @returns {Promise<Database<K, U>>} A promise that resolves to the created `Database` instance.
+   */
   createDatabase(schema) {
     return Database.create(this.connection, schema, this.name, this._ai);
   }
+  /**
+   * Drops a specific database from the workspace.
+   *
+   * @param {WorkspaceDatabaseName<T> | (string & {})} name - The name of the database to drop.
+   *
+   * @returns {Promise<[ResultSetHeader, FieldPacket[]]>} A promise that resolves when the database is dropped.
+   */
   dropDatabase(name) {
     return Database.drop(this.connection, name);
   }
+  /**
+   * Retrieves information about all databases in the workspace, optionally including extended details.
+   *
+   * @typeParam K - A boolean indicating whether extended information is requested.
+   *
+   * @param {K} [extended] - Whether to include extended information.
+   *
+   * @returns {Promise<(K extends true ? DatabaseInfoExtended<WorkspaceDatabaseName<T>> : DatabaseInfo<WorkspaceDatabaseName<T>>)[]>} A promise that resolves to an array of database information objects.
+   */
   async showDatabasesInfo(extended) {
@@ -555,5 +993,19 @@ const clauses = ["SHOW DATABASES"];
   _ai;
+  /**
+   * Constructs a new `SingleStoreClient` instance.
+   *
+   * @param {SingleStoreClientConfig<T>} [config] - The configuration object for initializing the `SingleStoreClient`.
+   */
   constructor(config) {
     this._ai = config?.ai;
   }
+  /**
+   * Connects to a workspace within the SingleStore environment.
+   *
+   * @typeParam U - The type of the workspace to connect to.
+   *
+   * @param {WorkspaceConfig<U, T>} config - The configuration object for connecting to the workspace.
+   *
+   * @returns {Workspace<U, T>} A `Workspace` instance representing the connected workspace.
+   */
   workspace(config) {
@@ -560,0 +1012,0 @@ return Workspace.connect({ ...config, ai: this._ai });

package.json

 {
   "name": "@singlestore/client",
-  "version": "0.0.28",
+  "version": "0.0.29",
   "license": "Apache-2.0",
@@ -5,0 +5,0 @@ "sideEffects": false,

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

338301

increased by126%

Lines of code

2978

increased by130.67%

No dependency changes