@rushdb/javascript-sdk/dist/api/api.d.ts

RushDB Javascript SDK

import type { HttpClient } from '../network/HttpClient.js';
import type { DBRecordCreationOptions, DBRecordTarget, Relation, RelationDetachOptions, RelationOptions, RelationTarget } from '../sdk/record.js';
import { DBRecordInstance, DBRecordsArrayInstance } from '../sdk/record.js';
import type { SDKConfig } from '../sdk/types.js';
import type { AnyObject, InferSchemaTypesWrite, MaybeArray, OrderDirection, Property, PropertyDraft, PropertyValuesData, Schema, SearchQuery } from '../types/index.js';
import type { ApiResponse } from './types.js';
import { createFetcher } from '../network/index.js';
import { Transaction } from '../sdk/transaction.js';
export declare class RestAPI {
    fetcher: ReturnType<typeof createFetcher>;
    options: SDKConfig['options'];
    logger: SDKConfig['logger'];
    constructor(token?: string, config?: SDKConfig & {
        httpClient: HttpClient;
    });
    _extractTargetIds(target: RelationTarget, operation: string): Array<string>;
    /**
     * API methods for managing database records
     */
    records: {
        /**
         * Attaches a relation between records
         * @param source - The source record to create relation from
         * @param target - The target record(s) to create relation to
         * @param options - Optional relation configuration
         * @param options.type - The type of relation to create
         * @param options.direction - The direction of the relation
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise with the API response
         */
        attach: ({ source, target, options }: {
            source: DBRecordTarget;
            target: RelationTarget;
            options?: RelationOptions;
        }, transaction?: Transaction | string) => Promise<ApiResponse<{
            message: string;
        }>>;
        /**
         * Detaches (removes) a relation between records
         * @param source - The source record to remove relation from
         * @param target - The target record(s) to remove relation to
         * @param options - Optional detach configuration
         * @param options.typeOrTypes - The type(s) of relations to remove
         * @param options.direction - The direction of relations to remove
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise with the API response
         */
        detach: ({ source, target, options }: {
            source: DBRecordTarget;
            target: RelationTarget;
            options?: RelationDetachOptions;
        }, transaction?: Transaction | string) => Promise<ApiResponse<{
            message: string;
        }>>;
        /**
         * Creates a new record in the database
         * @param label - The label/type of the record
         * @param data - The record data, either as a flat object or array of property drafts
         * @param options - Optional write configuration
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise resolving to the created DBRecordInstance
         * @throws Error if data is not a flat object and createMany should be used instead
         */
        create: <S extends Schema = any>({ label, data: rawData, options }: {
            label: string;
            data: InferSchemaTypesWrite<S> | Array<PropertyDraft>;
            options?: Omit<DBRecordCreationOptions, "returnResult" | "capitalizeLabels" | "relationshipType">;
        }, transaction?: Transaction | string) => Promise<DBRecordInstance<S>>;
        /**
         * Creates multiple records in a single operation
         * @param data - Object containing label, options and data array or object for multiple records
         * @param data.label - The label/type for all records
         * @param data.options - Optional write configuration
         * @param data.data - Array of record data to create
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise resolving to DBRecordsArrayInstance containing created records
         */
        createMany: <S extends Schema = any>(data: {
            label: string;
            data: MaybeArray<AnyObject>;
            options?: DBRecordCreationOptions;
        }, transaction?: Transaction | string) => Promise<DBRecordsArrayInstance<S>>;
        /**
         * Deletes records matching the search query
         * @param searchQuery - Query to identify records to delete
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise with the API response
         * @throws EmptyTargetError if query is empty and force delete is not allowed
         */
        delete: <S extends Schema = any>(searchQuery: SearchQuery<S>, transaction?: Transaction | string) => Promise<ApiResponse<{
            message: string;
        }>>;
        /**
         * Deletes record(s) by ID
         * @param idOrIds - Single ID or array of IDs to delete
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise with the API response
         */
        deleteById: (idOrIds: MaybeArray<string>, transaction?: Transaction | string) => Promise<ApiResponse<{
            message: string;
        }>>;
        /**
         * Exports records matching the search query to CSV format
         * @param searchQuery - Query to identify records to export
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise with the API response containing CSV data
         */
        export: <S extends Schema = any>(searchQuery: SearchQuery<S>, transaction?: Transaction | string) => Promise<ApiResponse<{
            dateTime: string;
            fileContent: string;
        }>>;
        /**
         * Searches for records matching the query criteria
         * @param searchQueryWithEntryPoint - Search query with optional entry point ID
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise resolving to DBRecordsArrayInstance containing matched records
         */
        find: <S extends Schema = any, Q extends SearchQuery<S> = SearchQuery<S>>(searchQueryWithEntryPoint: Q & {
            id?: string;
        }, transaction?: Transaction | string) => Promise<DBRecordsArrayInstance<S, Q>>;
        /**
         * Retrieves record(s) by ID
         * @param idOrIds - Single ID or array of IDs to retrieve
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise resolving to DBRecordInstance or DBRecordsArrayInstance depending on input
         */
        findById: <S extends Schema = Schema, Arg extends MaybeArray<string> = MaybeArray<string>, Result = Arg extends string[] ? DBRecordsArrayInstance<S, SearchQuery<S>> : DBRecordInstance<S, SearchQuery<S>>>(idOrIds: Arg, transaction?: Transaction | string) => Promise<Result>;
        /**
         * Finds a single record matching the search query
         * @param searchQuery - Query to identify the record
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise resolving to DBRecordInstance
         */
        findOne: <S extends Schema = any, Q extends SearchQuery<S> = SearchQuery<S>>(searchQuery: Q, transaction?: Transaction | string) => Promise<DBRecordInstance<S>>;
        /**
         * Finds a unique record matching the search query
         * @param searchQuery - Query to identify the record
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise resolving to DBRecordInstance
         * @throws NonUniqueResultError if multiple records match the query
         */
        findUniq: <S extends Schema = any, Q extends SearchQuery<S> = SearchQuery<S>>(searchQuery: Q, transaction?: Transaction | string) => Promise<DBRecordInstance<S, Q>>;
        /**
         * Sets (overwrites) record data
         * @param target - The record to update
         * @param label - The label/type of the record
         * @param data - The new record data
         * @param options - Optional write configuration
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise resolving to updated DBRecordInstance
         * @throws Error if data is not a flat object
         */
        set: <S extends Schema = any>({ target, label, data: rawData, options }: {
            target: DBRecordTarget;
            label: string;
            data: InferSchemaTypesWrite<S> | Array<PropertyDraft>;
            options?: Omit<DBRecordCreationOptions, "returnResult" | "capitalizeLabels" | "relationshipType">;
        }, transaction?: Transaction | string) => Promise<DBRecordInstance<S, SearchQuery<S>>>;
        /**
         * Updates record data (partial update)
         * @param target - The record to update
         * @param label - The label/type of the record
         * @param data - The partial record data to update
         * @param options - Optional write configuration
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise resolving to updated DBRecordInstance
         * @throws Error if data is not a flat object
         */
        update: <S extends Schema = any>({ target, label, data: rawData, options }: {
            target: DBRecordTarget;
            label: string;
            data: Partial<InferSchemaTypesWrite<S>> | Array<PropertyDraft>;
            options?: Omit<DBRecordCreationOptions, "returnResult" | "capitalizeLabels" | "relationshipType">;
        }, transaction?: Transaction | string) => Promise<DBRecordInstance<S, SearchQuery<S>>>;
    };
    /**
     * API methods for managing relations between records
     */
    relationships: {
        /**
         * Searches for relations matching the query criteria
         * @param searchQuery - Query to identify relations
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise with the API response containing matched relations
         */
        find: <S extends Schema = any>(searchQuery: SearchQuery<S>, transaction?: Transaction | string) => Promise<ApiResponse<Relation[]>>;
    };
    /**
     * API methods for managing properties in the database
     */
    properties: {
        /**
         * Deletes a property by its ID
         * @param id - The unique identifier of the property to delete
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise with the API response containing the deleted property
         */
        delete: (id: string, transaction?: Transaction | string) => Promise<ApiResponse<Property>>;
        /**
         * Searches for properties based on the provided query
         * @param searchQuery - Query parameters to filter properties
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise with the API response containing an array of matching properties
         */
        find: <S extends Schema = any>(searchQuery: SearchQuery<S>, transaction?: Transaction | string) => Promise<ApiResponse<Property[]>>;
        /**
         * Retrieves a specific property by its ID
         * @param id - The unique identifier of the property to retrieve
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise with the API response containing the requested property
         */
        findById: (id: string, transaction?: Transaction | string) => Promise<ApiResponse<Property>>;
        /**
         * Retrieves values for a specific property
         * @param id - The unique identifier of the property
         * @param searchQuery - Query parameters to filter properties
         * @param searchQuery.query - Filter query for values
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise with the API response containing the property and its values
         */
        values: (id: string, searchQuery?: SearchQuery & {
            query?: string;
            orderBy?: OrderDirection;
        }, transaction?: Transaction | string) => Promise<ApiResponse<{
            metadata?: string;
            name: string;
            type: import("../types/value.js").PropertyType;
        } & {
            id: string;
        } & PropertyValuesData>>;
    };
    /**
     * API methods for managing labels in the database
     */
    labels: {
        /**
         * Searches for labels based on the provided query
         * @param searchQuery - Query parameters to filter labels
         * @param transaction - Optional transaction for atomic operations
         * @returns Promise with the API response containing a record of label names and their counts
         */
        find: <S extends Schema = any>(searchQuery: SearchQuery<S>, transaction?: Transaction | string) => Promise<ApiResponse<Record<string, number>>>;
    };
    /**
     * API methods for managing database transactions
     */
    tx: {
        /**
         * Begins a new database transaction
         * @param config - Optional configuration object for the transaction
         * @param config.ttl - Time-to-live in milliseconds for the transaction
         * @returns A new Transaction instance that can be used for subsequent operations
         * @throws If the transaction cannot be started
         */
        begin: (config?: Partial<{
            ttl: number;
        }>) => Promise<Transaction>;
        /**
         * Commits a transaction, making its changes permanent
         * @param tx - The ID of the transaction or Transaction instance to commit
         * @returns An ApiResponse indicating success or failure of the commit
         * @throws If the transaction cannot be committed or doesn't exist
         */
        commit: (tx: string | Transaction) => Promise<ApiResponse<{
            message: string;
        }>>;
        /**
         * Retrieves an existing transaction by its ID
         * @param tx - The ID of the transaction or Transaction instance to retrieve
         * @returns A Transaction instance representing the retrieved transaction
         * @throws If the transaction doesn't exist or cannot be retrieved
         */
        get: (tx: string | Transaction) => Promise<Transaction>;
        /**
         * Rolls back a transaction, undoing all changes made within it
         * @param tx - The ID of the transaction or Transaction instance to roll back
         * @returns An ApiResponse indicating success or failure of the rollback
         * @throws If the transaction cannot be rolled back or doesn't exist
         */
        rollback: (tx: string | Transaction) => Promise<ApiResponse<{
            message: string;
        }>>;
    };
    settings: {
        get: () => Promise<ApiResponse<{
            selfHosted: boolean;
            dashboardUrl: string;
            googleOAuthEnabled: boolean;
            githubOAuthEnabled: boolean;
            customDB?: boolean;
        } | undefined>>;
    };
}