@tragedy-labs/sprite/dist/server/Server.d.ts

A TypeScript driver for ArcadeDB

import { ServerSession } from '../session/ServerSession.js';
import { SpriteDatabase } from '../database/SpriteDatabase.js';
/**
 * The level of detail that should be returned for a
 * `SpriteServer.getInformation()` request
 * @default 'default'
 */
export type ArcadeServerInformationLevel = 'basic' | 'default' | 'cluster';
/**
 * The metadata returned from the server on every operation.
 */
export type ArcadeServerBasicInformation = {
    /** The user who performed the operation */
    user: string;
    /** The version of ArcadeDB on the server */
    version: string;
    /** The name of the server */
    serverName: string;
};
export type ArcadeServerInfoSetting = {
    key: string;
    value: unknown;
    description: string;
    overridden: boolean;
    default: unknown;
};
export type ArcadeServerInfoMetrics = {
    meters: object;
    events: {
        errors: number;
        warnings: number;
        info: number;
        hints: number;
    };
    profiler: {
        readCacheUsed: object;
        writeCacheUsed: object;
        cacheMax: object;
        pagesRead: object;
        pagesWritten: object;
        pagesReadSize: object;
        pagesWrittenSize: object;
        pageFlushQueueLength: object;
        asyncQueueLength: object;
        asyncParallelLevel: object;
        pageCacheHits: object;
        pageCacheMiss: object;
        totalOpenFiles: object;
        maxOpenFiles: object;
        walPagesWritten: object;
        walBytesWritten: object;
        walTotalFiles: 8;
        concurrentModificationExceptions: object;
        txCommits: object;
        txRollbacks: object;
        createRecord: object;
        readRecord: object;
        updateRecord: object;
        deleteRecord: object;
        queries: object;
        commands: object;
        scanType: object;
        scanBucket: object;
        iterateType: object;
        iterateBucket: object;
        countType: object;
        countBucket: object;
        evictionRuns: object;
        pagesEvicted: object;
        readCachePages: object;
        writeCachePages: object;
        indexCompactions: object;
        diskFreeSpace: object;
        diskTotalSpace: object;
        diskFreeSpacePerc: object;
        gcTime: object;
        ramHeapUsed: object;
        ramHeapMax: object;
        ramHeapAvailablePerc: object;
        ramOsUsed: object;
        ramOsTotal: object;
        cpuLoad: object;
        jvmSafePointTime: object;
        jvmSafePointCount: object;
        jvmAvgSafePointTime: object;
        totalDatabases: object;
        cpuCores: object;
        configuration: object;
    };
};
export type ArcadeServerDefaultInformation = ArcadeServerBasicInformation & {
    metrics: ArcadeServerInfoMetrics;
    settings: ArcadeServerInfoSetting[];
};
export type ArcadeServerClusterInformation = object;
export type ArcadeServerInformation<T extends ArcadeServerInformationLevel> = {
    basic: ArcadeServerBasicInformation;
    default: ArcadeServerDefaultInformation;
    cluster: ArcadeServerClusterInformation;
}[T];
/**
 * Parameters necessary to create a user in ArcadeDB
 */
export interface ISpriteCreateArcadeUser {
    /** The username of the database user to create */
    username: string;
    /** The password of the database user to create */
    password: string;
    /**
     * An object containing databases to add the user to, and the
     * permisisions to grant them \
     * (i.e. `{ myDatabase: "ADMIN" }`)
     */
    databases: Record<string, string>;
}
/** Describes an event on the ArcadeDB server */
export type SpriteArcadeServerEvent = {
    time: string;
    type: string;
    message: string;
};
/** The ArcadeDB Server Events Log */
export type SpriteArcadeServerEvents = {
    /** The list of server events */
    events: SpriteArcadeServerEvent[];
    /** Event log files */
    files: string[];
};
/**
 * Static methods to interact with an ArcadeDB server.
 */
declare class Server {
    /**
     * Returns a `boolean` value indicating if the ArcadeDB server is ready.\
     * Useful for remote monitoring of server readiness.
     * @param session The session to use to check the server status.
     * @returns `true` if the server is ready, otherwise `false`.
     * @throws `Error` if the server status could not be checked.
     */
    static serverReady: (session: ServerSession) => Promise<boolean>;
    /**
     * Close a database on the ArcadeDB server.
     * @param session The session to use to close the database.
     * @param databaseName The name of the database to close.
     * @returns The response from the server.
     * @throws `Error` if the database could not be closed.
     */
    static closeDatabase: (session: ServerSession, databaseName: string) => Promise<boolean>;
    /**
     * Open a database on the ArcadeDB server
     * @param session The session to use to open the database.
     * @param databaseName The name of the database to open.
     * @returns `true` if the database was opened.
     * @throws `Error` if the database could not be opened.
     */
    static openDatabase: (session: ServerSession, databaseName: string) => Promise<boolean>;
    /**
     * Returns an `SpriteDatabase` instance for the supplied `databaseName`,
     * using the authorization details of the `Session` instance.
     * @param session The session to use to create the database client.
     * @param databaseName The name of the database to create a client for.
     * @returns An instance of `SpriteDatabase`.
     * @throws `Error` if the database could not be created.
     */
    static database: (session: ServerSession, databaseName: string) => SpriteDatabase;
    /**
     * Sends a command to the ArcadeDB server and returns the response.
     * @param session The session to use to send the command.
     * @param command The command to send to the server.
     * @returns The response from the server.
     * @throws `Error` if the command could not be executed.
     */
    static command: <T>(session: ServerSession, command: string) => Promise<T>;
    /**
     * Internal method for sending commands to the server in which a JSON response
     * containing an `ok` value in the `result` property is expected. `ok` is then
     * returned as a simple boolean (`true`) value
     * @param session The session to use to send the command.
     * @param command The [command](https://docs.arcadedb.com/#HTTP-ServerCommand) to send to the server, such as `CREATE DATABASE`.
     * @returns `true` if the command was successful.
     * @throws `Error` if the command could not be executed.
     */
    private static _booleanCommand;
    /**
     * Connects this server to a cluster with `address`.
     * @param session The session to use to connect to the cluster.
     * @param address The address of the cluster to connect (i.e. 192.168.0.1)
     * @returns The response from the server.
     * @throws `Error` if the cluster could not be connected.
     */
    static connectCluster: (session: ServerSession, address: string) => Promise<boolean>;
    /**
     * Create a database
     * @param session The session to use to create the database.
     * @param databaseName The name of the database to create.
     * @returns An instance of `SpriteDatabase`, targeting the created database.
     * @throws `Error` if the database could not be created.
     */
    static createDatabase: (session: ServerSession, databaseName: string) => Promise<SpriteDatabase>;
    /**
     * Create a user. `username`, `password`, and access controls to multiple databases
     * can be established using the `databases` property of the input parameters.
     * @param session The session to use to create the user.
     * @param username The `username` of the user to create.
     * @param password The `password` of the user to create.
     * @param databases An object of databases to add the user to, and their permissions (groups they belong to).
     * @returns `true` if the user was created successfully.
     * @throws `Error` if the user could not be created.
     */
    static createUser: (session: ServerSession, params: ISpriteCreateArcadeUser) => Promise<boolean>;
    /**
     * Disconnects the server from the cluster.
     * @param session The session to use to disconnect from the cluster.
     * @returns The response from the server.
     * @throws `Error` if the cluster could not be disconnected.
     */
    static disconnectCluster: (session: ServerSession) => Promise<boolean>;
    /**
     * Drop a database
     * @param session The session to use to drop the database.
     * @param databaseName The name of the database to drop.
     * @returns `true` if successfully dropped.
     * @throws `Error` if the database could not be dropped.
     */
    static dropDatabase: (session: ServerSession, databaseName: string) => Promise<boolean>;
    /**
     * Drop a user from the ArcadeDB server.
     * @param session The session to use to drop the user.
     * @param username The `username` of the user to drop from the ArcadeDB server.
     * @returns `true` if the user was successfully dropped.
     * @throws `Error` if the user could not be dropped.
     */
    static dropUser: (session: ServerSession, username: string) => Promise<boolean>;
    /**
     * Retrieves a list of server events, optionally a filename of the form
     * `server-event-log-yyyymmdd-HHMMSS.INDEX.jsonl` (where INDEX is a integer, i.e. 0)
     * can be given to retrieve older event logs.
     * @param session The session to use to retrieve the server events.
     * @returns An object containing he server events from the server, and filenames of the associated logs.
     * @throws `Error` if there was a problem fetching the event logs.
     */
    static getEvents: (session: ServerSession) => Promise<SpriteArcadeServerEvents>;
    /**
     * Returns the current configuration.
     * @param session The session to use to retrieve the configuration.
     * @param mode The level of informatio detail to return.
     * * `basic` returns minimal server information
     * * `default` returns full server configuration (default value when no parameter is given)
     * * `cluster` returns the cluster layout
     * @returns The server information.
     * @throws `Error` if the server information could not be retrieved.
     */
    static getInformation: <M extends ArcadeServerInformationLevel = "default">(session: ServerSession, mode?: M) => Promise<ArcadeServerInformation<M>>;
    /**
     * Returns a list of database names that are present on the server.
     * @param session The session to use to retrieve the database list.
     * @returns {Promise<Array<string>>} A list (array) of database names present on the server.
     * @throws `Error` if the database list could not be retrieved.
     */
    static listDatabases: (session: ServerSession) => Promise<Array<string>>;
    /**
     * Gracefully shutdown the server.\
     * `TODO:` This works, in that it does shutdown the server, but the fetch throws
     * before it resolves, guessing because the server is shutting down. A CURL, however,
     * returns an empty `204` response as the documentation indicates.
     * @param session The session to use to shutdown the server.
     * @returns `true` if the server is successfully shutdown.
     * @throws `Error` if there is a problem attempting the shutdown.
     */
    static shutdown: (session: ServerSession) => Promise<boolean>;
}
export { Server };