azion/packages/sql/dist/index.d.mts

Azion Packages for Edge Computing.

type JsonObjectQueryExecutionResponse = {
    results?: {
        statement?: string;
        rows: {
            [key: string]: any;
        }[];
    }[];
};

type AzionDatabaseResponse<T> = {
    data?: T;
    error?: {
        message: string;
        operation: string;
    };
};
interface AzionDatabase {
    id: number;
    name: string;
    clientId: string;
    status: string;
    createdAt: string;
    updatedAt: string;
    deletedAt: string | null;
    /**
     * Executes a query or multiple queries on the database.
     *
     * @param {string[]} statements - An array of SQL statements to execute.
     * @param {AzionClientOptions} [options] - Additional options for the query execution.
     * @returns {Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>} A promise that resolves to the query response or error if the operation faile>d.
     *
     * @example
     * const result = await database.query([
     *   'SELECT * FROM users WHERE id = ?',
     *   'UPDATE users SET last_login = NOW() WHERE id = ?'
     * ], { debug: true });
     */
    query: (statements: string[], options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>>;
    /**
     * Executes one or more SQL statements on the database.
     *
     * @param {string[]} statements - An array of SQL statements to execute.
     * @param {AzionClientOptions} [options] - Additional options for the execution.
     * @returns {Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>} A promise that resolves to the query response or error if the operation faile>d.
     *
     * @example
     * const result = await database.execute([
     *   'INSERT INTO users (name, email) VALUES (?, ?)',
     *   'DELETE FROM old_users WHERE last_login < ?'
     * ], { force: true });
     */
    execute: (statements: string[], options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>>;
    /**
     * Retrieves a list of tables in the database.
     *
     * @param {AzionClientOptions} [options] - Additional options for listing tables.
     * @returns {Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>} A promise that resolves to the query response or error if the operation faile>d.
     *
     * @example
     * const { data: tables, error } = await database.getTables({ debug: true });
     */
    getTables: (options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>>;
}
type AzionQueryParams = string | number | boolean | null;
type AzionQueryExecutionParams = {
    statements: string[];
    params?: (AzionQueryParams | Record<string, AzionQueryParams>)[];
};
type QueryResult = {
    columns?: string[];
    rows?: (number | string)[][];
    statement?: string;
};
type AzionDatabaseQueryResponse = {
    state?: 'pending' | 'failed' | 'executed' | 'executed-runtime';
    results?: QueryResult[];
    toObject: () => JsonObjectQueryExecutionResponse | null;
};
type AzionDatabaseExecutionResponse = AzionDatabaseQueryResponse;
type AzionDatabaseCollectionOptions = {
    ordering?: string;
    page?: number;
    page_size?: number;
    search?: string;
};
type AzionDatabaseCollections = {
    databases?: AzionDatabase[];
    count?: number;
};
type AzionDatabaseDeleteResponse = {
    state: 'pending' | 'failed' | 'executed';
    id: number;
};
interface AzionSQLClient {
    /**
     * Creates a new database with the specified name.
     *
     * @param {string} name - Name of the database to create.
     * @returns {Promise<AzionDatabaseResponse>} Object confirming creation of the database or an error message.
     *
     * @example
     * const { data, error } = await sqlClient.createDatabase('my-db');
     * if (data) {
     *  console.log(`Database ${data.name} created successfully`);
     * } else {
     * console.error(`Failed to create database: ${error.message}`);
     *
     */
    createDatabase: (name: string) => Promise<AzionDatabaseResponse<AzionDatabase>>;
    /**
     * Deletes a database by its ID.
     *
     * @param {number} id - ID of the database to delete.
     * @returns {Promise<AzionDatabaseResponse<AzionDatabaseDeleteResponse>>} Object confirming deletion or error if the operation failed.
     *
     * @example
     * const { data, error } = await sqlClient.deleteDatabase(123);
     * if (data) {
     * console.log(`Database ${data.name} (ID: ${data.id}) deleted successfully`);
     * } else {
     * console.error(`Failed to delete database: ${error.message}`);
     *
     */
    deleteDatabase: (id: number) => Promise<AzionDatabaseResponse<AzionDatabaseDeleteResponse>>;
    /**
     * Retrieves a database by its Name.
     *
     * @param {string} name - Name of the database to retrieve.
     * @returns {Promise<AzionDatabaseResponse<AzionDatabase>>} The retrieved database object or null if not found.
     *
     * @example
     * const { data, error } = await sqlClient.getDatabase('my-db');
     * if (data) {
     *  console.log(`Retrieved database ${data.name} (ID: ${data.id})`);
     * } else {
     * console.error(`Failed to retrieve database: ${error.message}`);
     *
     */
    getDatabase: (name: string) => Promise<AzionDatabaseResponse<AzionDatabase>>;
    /**
     * Retrieves a list of databases with optional filtering and pagination.
     *
     * @param {AzionDatabaseCollectionOptions} [params] - Optional parameters for filtering and pagination.
     * @param {string} [params.ordering] - Field to order the results by.
     * @param {number} [params.page] - Page number for pagination.
     * @param {number} [params.page_size] - Number of items per page.
     * @param {string} [params.search] - Search term to filter databases.
     * @returns {Promise<AzionDatabaseResponse>} Array of database objects or error message.
     *
     * @example
     * const { data, error } = await sqlClient.getDatabases({ page: 1, page_size: 10, search: 'test' });
     * if (data) {
     * console.log(`Retrieved ${data.length} databases`);
     * } else {
     * console.error(`Failed to retrieve databases: ${error.message}`);
     *
     */
    getDatabases: (params?: {
        ordering?: string;
        page?: number;
        page_size?: number;
        search?: string;
    }) => Promise<AzionDatabaseResponse<AzionDatabaseCollections>>;
}
/**
 * Defines the execution environment for the Azion client.
 *
 * @type {('development' | 'staging' | 'production')}
 *
 * @property {'development'} development - Development environment for local testing
 * @property {'staging'} staging - Staging/testing environment
 * @property {'production'} production - Production environment
 *
 * @example
 * const environment: AzionEnvironment = 'development';
 *
 * @example
 * const clientOptions = {
 *   env: 'production' as AzionEnvironment
 * };
 */
type AzionEnvironment = 'development' | 'staging' | 'production';
/**
 * Options for configuring the Azion client behavior.
 *
 * @property {boolean} [debug] - Enable debug mode for detailed logging.
 * @property {boolean} [force] - Force the operation even if it might be destructive.
 * @property {AzionEnvironment} [env] - Environment to use (dev, stage, prod).
 * @property {boolean} [external] - Force using external REST API instead of built-in runtime API.
 *
 * @example
 * const options: AzionClientOptions = {
 *   debug: true,
 *   force: false,
 *   env: 'dev',
 *   external: true
 * };
 */
type AzionClientOptions = {
    /** Enable debug mode for detailed logging */
    debug?: boolean;
    /** Force the operation even if it might be destructive */
    force?: boolean;
    /** Environment to use (dev, stage, prod) */
    env?: AzionEnvironment;
    /** Force using external REST API instead of built-in runtime API */
    external?: boolean;
};
/**
 * Function type for creating an Azion SQL Client.
 *
 * @param {Object} [config] - Configuration options for the SQL client.
 * @param {string} [config.token] - Authentication token for Azion API. If not provided,
 * the client will attempt to use the AZION_TOKEN environment variable.
 * @param {AzionClientOptions} [config.options] - Additional client options.
 *
 * @returns {AzionSQLClient} An instance of the Azion SQL Client.
 *
 * @example
 * // Create an SQL client with a token and debug mode enabled
 * const sqlClient = createAzionSQLClient({
 *   token: 'your-api-token',
 *   options: { debug: true }
 * });
 *
 * @example
 * // Create an SQL client using environment variables for token
 * const sqlClient = createAzionSQLClient();
 */
type CreateAzionSQLClient = (config?: Partial<{
    token?: string;
    options?: AzionClientOptions;
}>) => AzionSQLClient;

/**
 * Creates a new database.
 *
 * @param {string} name - Name of the database to create.
 * @param {AzionClientOptions} [options] - Optional parameters for the deletion.
 * @returns {Promise<AzionDatabaseResponse<AzionDatabase>>} The created database object or error if creation failed.
 *
 * @example
 * const { data, error } = await createDatabase('my-new-database', { debug: true });
 * if (data) {
 *  console.log(`Database ${data.id} created successfully`);
 * } else {
 *  console.error(`Failed to create database: ${error.message}`);
 * }
 */
declare const createDatabaseWrapper: (name: string, options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabase>>;
/**
 * Deletes a database by its ID.
 *
 * @param {number} id - ID of the database to delete.
 * @param {AzionClientOptions} [options] - Optional parameters for the deletion.
 * @returns {Promise<AzionDatabaseResponse<AzionDatabaseDeleteResponse>>} Object confirming deletion or error if deletion failed.
 *
 * @example
 * const { data, error } = await deleteDatabase(123, { debug: true });
 * if (data) {
 * console.log(`Database ${data.id} deleted successfully`);
 * } else {
 * console.error(`Failed to delete database: ${error.message}`);
 *
 */
declare const deleteDatabaseWrapper: (id: number, options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabaseDeleteResponse>>;
/**
 * Retrieves a database by its Name.
 *
 * @param {string} name - Name of the database to retrieve.
 * @param {AzionClientOptions} [options] - Optional parameters for the deletion.
 * @returns {Promise<AzionDatabaseResponse<AzionDatabase>>} The retrieved database object or error if not found.
 *
 * @example
 * const { data, error } = await getDatabase('my-db', { debug: true });
 * if (data) {
 *  console.log(`Retrieved database ${data.name} (ID: ${data.id})`);
 * } else {
 *  console.error(`Failed to retrieve database: ${error.message}`);
 * }
 */
declare const getDatabaseWrapper: (name: string, options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabase>>;
/**
 * Retrieves a list of databases with optional filtering and pagination.
 *
 * @param {Partial<AzionDatabaseCollectionOptions>} [params] - Optional parameters for filtering and pagination.
 * @param {AzionClientOptions} [options] - Optional parameters for the deletion.
 * @returns {Promise<AzionDatabaseResponse<AzionDatabaseCollections>>} Array of database objects or error if retrieval failed.
 *
 * @example
 * const { data: allDatabases, error } = await getDatabases({ page: 1, page_size: 10 }, { debug: true });
 * if (allDatabases) {
 * console.log(`Retrieved ${allDatabases.count} databases`);
 * allDatabases.results.forEach(db => console.log(`- ${db.name} (ID: ${db.id})`));
 * } else {
 * console.error('Failed to retrieve databases', error);
 * }
 *
 */
declare const getDatabasesWrapper: (params?: Partial<AzionDatabaseCollectionOptions>, options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabaseCollections>>;
/**
 * List tables from a database.
 * @param databaseName Name of the database to list tables from.
 * @param options Optional parameters for the query.
 * @returns The query response object or null if the query failed.
 */
declare const listTablesWrapper: (databaseName: string, options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>>;
/**
 * Use Query to execute a query on a database.
 * @param name Name of the database to query.
 * @param statements Array of SQL statements to execute.
 * @param options Optional parameters for the query.
 * @param options.debug Debug mode for detailed logging.
 * @param options.force Force the query execution.
 * @returns The query response object or null if the query failed.
 * @example
 * const { data, error } = await useQuery('my-db', ['SELECT * FROM users']);
 * if (data) {
 *  console.log(`Query executed with success`, data);
 * } else {
 * console.error(`Failed to execute query: ${error.message}`);
 *
 */
declare const useQuery: (name: string, statements: string[], options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>>;
/**
 * Use Execute to execute a set of SQL statements on a database.
 * @param name Name of the database to execute the statements on.
 * @param statements Array of SQL statements to execute.
 * @param options.debug Debug mode for detailed logging.
 * @param options.force Force the query execution.
 * @returns The query response object or null if the query failed.
 *
 * @example
 * const { data, error } = await useExecute('my-db', ['INSERT INTO users (name) VALUES ("John")']);
 * if (data) {
 * console.log(`Statements executed with success`, data);
 * } else {
 * console.error(`Failed to execute statements: `, error);
 *
 */
declare const useExecute: (name: string, statements: string[], options?: AzionClientOptions) => Promise<AzionDatabaseResponse<AzionDatabaseQueryResponse>>;
/**
 * Creates an SQL client with methods to interact with Azion Edge SQL databases.
 *
 * @param {Partial<{ token?: string; options?: AzionClientOptions; }>} [config] - Configuration options for the SQL client.
 * @returns {AzionSQLClient} An object with methods to interact with SQL databases.
 *
 * @example
 * const sqlClient = createClient({ token: 'your-api-token', options: { debug: true } });
 *
 * // Create a new database
 * const { data: newDatabase } = await sqlClient.createDatabase('my-new-db');
 *
 * // Get all databases
 * const allDatabases = await sqlClient.getDatabases();
 *
 * // Query a database
 * const queryResult = await newDatabase.query(['SELECT * FROM users']);
 */
declare const client: CreateAzionSQLClient;

export { type AzionClientOptions, type AzionDatabase, type AzionDatabaseCollectionOptions, type AzionDatabaseCollections, type AzionDatabaseDeleteResponse, type AzionDatabaseExecutionResponse, type AzionDatabaseQueryResponse, type AzionDatabaseResponse, type AzionEnvironment, type AzionQueryExecutionParams, type AzionQueryParams, type AzionSQLClient, type CreateAzionSQLClient, type QueryResult, client as createClient, createDatabaseWrapper as createDatabase, client as default, deleteDatabaseWrapper as deleteDatabase, getDatabaseWrapper as getDatabase, getDatabasesWrapper as getDatabases, listTablesWrapper as getTables, useExecute, useQuery };