@opra/sqb/types/sqb-entity-service.d.ts

Opra SQB adapter package

import { ComplexType } from '@opra/common';
import { ExecutionContext, ServiceBase } from '@opra/core';
import { EntityMetadata, Repository } from '@sqb/connect';
import type { Nullish, PartialDTO, PatchDTO, RequiredSome, StrictOmit, Type } from 'ts-gems';
import { type IsObject } from 'valgen';
import { SQBAdapter } from './sqb-adapter.js';
import { SqbServiceBase } from './sqb-service-base.js';
/**
 * @namespace SqbEntityService
 */
export declare namespace SqbEntityService {
    interface Options extends SqbServiceBase.Options {
        resourceName?: SqbEntityService<any>['resourceName'];
        onError?: SqbEntityService<any>['onError'];
        commonFilter?: SqbEntityService<any>['commonFilter'];
        interceptor?: SqbEntityService<any>['interceptor'];
        scope?: SqbEntityService<any>['scope'];
    }
    type CrudOp = 'create' | 'read' | 'update' | 'delete';
    interface CommandInfo {
        crud: SqbEntityService.CrudOp;
        method: string;
        byId: boolean;
        documentId?: SQBAdapter.IdOrIds;
        input?: Record<string, any>;
        options?: Record<string, any>;
    }
    type CommonFilter = SQBAdapter.FilterInput | ((args: SqbEntityService.CommandInfo, _this: SqbEntityService<any>) => SQBAdapter.FilterInput | Promise<SQBAdapter.FilterInput> | undefined);
    /**
     * Represents options for "create" operation
     *
     * @interface
     */
    interface CreateOptions extends Repository.CreateOptions {
    }
    /**
     * Represents options for "count" operation
     *
     * @interface
     */
    interface CountOptions extends StrictOmit<Repository.CountOptions, 'filter'> {
        filter?: Repository.CountOptions['filter'] | string;
    }
    /**
     * Represents options for "delete" operation
     *
     * @interface
     */
    interface DeleteOptions extends StrictOmit<Repository.DeleteOptions, 'filter'> {
        filter?: Repository.DeleteOptions['filter'] | string;
    }
    /**
     * Represents options for "deleteMany" operation
     *
     * @interface
     */
    interface DeleteManyOptions extends StrictOmit<Repository.DeleteManyOptions, 'filter'> {
        filter?: Repository.DeleteManyOptions['filter'] | string;
    }
    /**
     * Represents options for "exists" operation
     *
     * @interface
     */
    interface ExistsOptions extends StrictOmit<Repository.ExistsOptions, 'filter'> {
        filter?: Repository.ExistsOptions['filter'] | string;
    }
    /**
     * Represents options for "findOne" operation
     *
     * @interface
     */
    interface FindOneOptions extends StrictOmit<Repository.FindOneOptions, 'filter' | 'offset'> {
        filter?: Repository.FindOneOptions['filter'] | string;
        skip?: number;
    }
    /**
     * Represents options for "findMany" operation
     *
     * @interface
     */
    interface FindManyOptions extends StrictOmit<Repository.FindManyOptions, 'filter' | 'offset'> {
        filter?: Repository.FindManyOptions['filter'] | string;
        skip?: number;
    }
    /**
     * Represents options for "update" operation
     *
     * @interface
     */
    interface UpdateOneOptions extends StrictOmit<Repository.UpdateOptions, 'filter'> {
        filter?: Repository.UpdateOptions['filter'] | string;
    }
    /**
     * Represents options for "updateMany" operation
     *
     * @interface
     */
    interface UpdateManyOptions extends StrictOmit<Repository.UpdateManyOptions, 'filter'> {
        filter?: Repository.UpdateManyOptions['filter'] | string;
    }
    interface CreateCommand<T> extends StrictOmit<RequiredSome<CommandInfo, 'input'>, 'documentId'> {
        crud: 'create';
        input: PatchDTO<T>;
        options?: CreateOptions;
    }
    interface CountCommand extends StrictOmit<CommandInfo, 'documentId' | 'input'> {
        crud: 'read';
        options?: CountOptions;
    }
    interface DeleteOneCommand extends StrictOmit<CommandInfo, 'input'> {
        crud: 'delete';
        options?: DeleteOptions;
    }
    interface DeleteManyCommand extends StrictOmit<CommandInfo, 'input'> {
        crud: 'delete';
        options?: DeleteManyOptions;
    }
    interface ExistsCommand extends StrictOmit<CommandInfo, 'input'> {
        crud: 'read';
        options?: ExistsOptions;
    }
    interface FindOneCommand extends StrictOmit<CommandInfo, 'input'> {
        crud: 'read';
        options?: FindOneOptions;
    }
    interface FindManyCommand extends StrictOmit<CommandInfo, 'input'> {
        crud: 'read';
        options?: FindManyOptions;
    }
    interface UpdateOneCommand<T> extends CommandInfo {
        crud: 'update';
        input: PatchDTO<T>;
        options?: UpdateOneOptions;
    }
    interface UpdateManyCommand<T> extends CommandInfo {
        crud: 'update';
        input: PatchDTO<T>;
        options?: UpdateManyOptions;
    }
}
export interface SqbEntityService {
    /**
     * Interceptor function for handling callback execution with provided arguments.
     * @type Function
     * @param next - The callback function to be intercepted.
     * @param {SqbEntityService.CommandInfo} command - The arguments object containing the following properties:
     * @param _this - The reference to the current object.
     * @returns - The promise that resolves to the result of the callback execution.
     */
    interceptor?(next: () => any, command: SqbEntityService.CommandInfo, _this: any): Promise<any>;
}
/**
 * @class SqbEntityService
 * @template T - The data type class type of the resource
 */
export declare class SqbEntityService<T extends object = object> extends SqbServiceBase {
    protected _dataTypeScope?: string;
    protected _dataType_: Type | string;
    protected _dataType?: ComplexType;
    protected _dataTypeClass?: Type;
    protected _entityMetadata?: EntityMetadata;
    protected _inputCodecs: Record<string, IsObject.Validator<T>>;
    protected _outputCodecs: Record<string, IsObject.Validator<T>>;
    /**
     * Defines comma delimited scopes for api document
     */
    scope?: string;
    /**
     * Represents the name of a resource.
     * @type {string}
     */
    resourceName?: string | ((_this: this) => string);
    /**
     * Represents a common filter function for a service.
     *
     * @type {SqbEntityService.Filter | Function}
     */
    commonFilter?: SqbEntityService.CommonFilter | SqbEntityService.CommonFilter[];
    /**
     * Callback function for handling errors.
     *
     * @param {unknown} error - The error object.
     * @param {SqbEntityService} _this - The context object.
     */
    onError?: (error: unknown, _this: any) => void | Promise<void>;
    /**
     * Constructs a new instance
     *
     * @param dataType - The data type of the returning results
     * @param [options] - The options for the service.
     * @constructor
     */
    constructor(dataType: Type<T> | string, options?: SqbEntityService.Options);
    /**
     * Retrieves the OPRA data type
     *
     * @throws {NotAcceptableError} If the data type is not a ComplexType.
     */
    get dataType(): ComplexType;
    /**
     * Retrieves the Class of the data type
     *
     * @throws {NotAcceptableError} If the data type is not a ComplexType.
     */
    get dataTypeClass(): Type;
    /**
     * Retrieves the SQB entity metadata object
     *
     * @throws {TypeError} If metadata is not available
     */
    get entityMetadata(): EntityMetadata;
    for<C extends ExecutionContext, P extends Partial<this>>(context: C | ServiceBase, overwriteProperties?: Nullish<P>, overwriteContext?: Partial<C>): this & Required<P>;
    /**
     * Retrieves the resource name.
     *
     * @returns {string} The resource name.
     * @throws {Error} If the collection name is not defined.
     */
    getResourceName(): string;
    /**
     * Retrieves the codec for the specified operation.
     *
     * @param operation - The operation to retrieve the encoder for. Valid values are 'create' and 'update'.
     */
    getInputCodec(operation: string): IsObject.Validator<T>;
    /**
     * Retrieves the codec.
     */
    getOutputCodec(operation: string): IsObject.Validator<T>;
    /**
     * Insert a new record into database
     *
     * @param command
     * @returns - A promise that resolves to the created resource
     * @protected
     */
    protected _create(command: SqbEntityService.CreateCommand<T>): Promise<PartialDTO<T>>;
    /**
     * Insert a new record into database
     *
     * @param command
     * @returns - A promise that resolves to the created resource
     * @protected
     */
    protected _createOnly(command: SqbEntityService.CreateCommand<T>): Promise<any>;
    /**
     * Returns the count of records based on the provided options
     *
     * @param command
     * @return - A promise that resolves to the count of records
     * @protected
     */
    protected _count(command: SqbEntityService.CountCommand): Promise<number>;
    /**
     * Deletes a record from the collection.
     *
     * @param command
     * @return - A Promise that resolves to the number of documents deleted.
     * @protected
     */
    protected _delete(command: SqbEntityService.DeleteOneCommand): Promise<number>;
    /**
     * Deletes multiple documents from the collection that meet the specified filter criteria.
     *
     * @param command
     * @return - A promise that resolves to the number of documents deleted.
     * @protected
     */
    protected _deleteMany(command: SqbEntityService.DeleteManyCommand): Promise<number>;
    /**
     * Checks if a record with the given id exists.
     *
     * @param command
     * @protected
     */
    protected _exists(command: SqbEntityService.ExistsCommand): Promise<boolean>;
    /**
     * Checks if a record with the given arguments exists.
     *
     * @param command
     * @return - A Promise that resolves to a boolean indicating whether the record exists or not.
     * @protected
     */
    protected _existsOne(command: SqbEntityService.ExistsCommand): Promise<boolean>;
    /**
     * Finds a record by ID.
     *
     * @param command
     * @return - A promise resolving to the found document, or undefined if not found.
     * @protected
     */
    protected _findById(command: SqbEntityService.FindOneCommand): Promise<PartialDTO<T> | undefined>;
    /**
     * Finds a record in the collection that matches the specified options.
     *
     * @param command
     * @return - A promise that resolves with the found document or undefined if no document is found.
     * @protected
     */
    protected _findOne(command: SqbEntityService.FindOneCommand): Promise<PartialDTO<T> | undefined>;
    /**
     * Finds multiple records in collection.
     *
     * @param command
     * @return - A Promise that resolves to an array of partial outputs of type T.
     * @protected
     */
    protected _findMany(command: SqbEntityService.FindManyCommand): Promise<PartialDTO<T>[]>;
    /**
     * Updates a record with the given id in the collection.
     *
     * @param command
     * @returns  A promise that resolves to the updated document or undefined if the document was not found.
     * @protected
     */
    protected _update(command: SqbEntityService.UpdateOneCommand<T>): Promise<PartialDTO<T> | undefined>;
    /**
     * Updates a record in the collection with the specified ID and returns updated record count
     *
     * @param command
     * @returns - A promise that resolves to the number of documents modified.
     * @protected
     */
    protected _updateOnly(command: SqbEntityService.UpdateOneCommand<T>): Promise<number>;
    /**
     * Updates multiple records in the collection based on the specified input and options.
     *
     * @param command
     * @return - A promise that resolves to the number of documents matched and modified.
     * @protected
     */
    protected _updateMany(command: SqbEntityService.UpdateOneCommand<T>): Promise<number>;
    /**
     * Acquires a connection and performs Repository.create operation
     *
     * @param input - The document to insert
     * @param options - Optional settings for the command
     * @protected
     */
    protected _dbCreate(input: PartialDTO<T>, options?: Repository.CreateOptions): Promise<PartialDTO<T>>;
    /**
     * Acquires a connection and performs Repository.count operation
     *
     * @param options - The options for counting documents.
     * @protected
     */
    protected _dbCount(options?: Repository.CountOptions): Promise<number>;
    /**
     * Acquires a connection and performs Repository.delete operation
     *
     * @param id - Value of the key field used to select the record
     * @param options - Optional settings for the command
     * @protected
     */
    protected _dbDelete(id: SQBAdapter.IdOrIds, options?: Repository.DeleteOptions): Promise<number>;
    /**
     * Acquires a connection and performs Repository.deleteMany operation
     *
     * @param options - Optional settings for the command
     * @protected
     */
    protected _dbDeleteMany(options?: Repository.DeleteManyOptions): Promise<number>;
    /**
     * Acquires a connection and performs Repository.exists operation
     *
     * @param id - Value of the key field used to select the record
     * @param options - Optional settings for the command
     * @protected
     */
    protected _dbExists(id: SQBAdapter.IdOrIds, options?: Repository.ExistsOptions): Promise<boolean>;
    /**
     * Acquires a connection and performs Repository.existsOne operation
     *
     * @param options - Optional settings for the command
     * @protected
     */
    protected _dbExistsOne(options?: Repository.ExistsOptions): Promise<boolean>;
    /**
     * Acquires a connection and performs Repository.findById operation
     *
     * @param id - Value of the key field used to select the record
     * @param options - Optional settings for the command
     * @protected
     */
    protected _dbFindById(id: SQBAdapter.IdOrIds, options?: Repository.FindOptions): Promise<PartialDTO<T> | undefined>;
    /**
     * Acquires a connection and performs Repository.findOne operation
     *
     * @param options - Optional settings for the command
     * @protected
     */
    protected _dbFindOne(options?: StrictOmit<Repository.FindOneOptions, 'offset'> & {
        skip?: number;
    }): Promise<PartialDTO<T> | undefined>;
    /**
     * Acquires a connection and performs Repository.findMany operation
     *
     * @param options - Optional settings for the command
     * @protected
     */
    protected _dbFindMany(options?: StrictOmit<Repository.FindManyOptions, 'offset'> & {
        skip?: number;
    }): Promise<PartialDTO<T>[]>;
    /**
     * Acquires a connection and performs Repository.update operation
     *
     * @param id - Value of the key field used to select the record
     * @param data - The update values to be applied to the document
     * @param options - Optional settings for the command
     * @protected
     */
    protected _dbUpdate(id: SQBAdapter.IdOrIds, data: PatchDTO<T>, options?: Repository.UpdateOptions): Promise<PartialDTO<T> | undefined>;
    /**
     * Acquires a connection and performs Repository.updateOnly operation
     *
     * @param id - Value of the key field used to select the record
     * @param data - The update values to be applied to the document
     * @param options - Optional settings for the command
     * @protected
     */
    protected _dbUpdateOnly(id: SQBAdapter.IdOrIds, data: PatchDTO<T>, options?: Repository.UpdateOptions): Promise<number>;
    /**
     * Acquires a connection and performs Repository.updateMany operation
     *
     * @param data - The update values to be applied to the document
     * @param options - Optional settings for the command
     * @protected
     */
    protected _dbUpdateMany(data: PatchDTO<T>, options?: Repository.UpdateManyOptions): Promise<number>;
    /**
     * Retrieves the common filter used for querying documents.
     * This method is mostly used for security issues like securing multi-tenant applications.
     *
     * @protected
     * @returns {FilterInput | Promise<FilterInput> | undefined} The common filter or a Promise
     * that resolves to the common filter, or undefined if not available.
     */
    protected _getCommonFilter(command: SqbEntityService.CommandInfo): SQBAdapter.FilterInput | Promise<SQBAdapter.FilterInput> | undefined;
    protected _executeCommand(command: SqbEntityService.CommandInfo, commandFn: () => any): Promise<any>;
    protected _beforeCreate(command: SqbEntityService.CreateCommand<T>): Promise<void>;
    protected _beforeUpdate(command: SqbEntityService.UpdateOneCommand<T>): Promise<void>;
    protected _beforeUpdateMany(command: SqbEntityService.UpdateManyCommand<T>): Promise<void>;
    protected _beforeDelete(command: SqbEntityService.DeleteOneCommand): Promise<void>;
    protected _beforeDeleteMany(command: SqbEntityService.DeleteManyCommand): Promise<void>;
    protected _afterCreate(command: SqbEntityService.CreateCommand<T>, result: PartialDTO<T>): Promise<void>;
    protected _afterUpdate(command: SqbEntityService.UpdateOneCommand<T>, result?: PartialDTO<T>): Promise<void>;
    protected _afterUpdateMany(command: SqbEntityService.UpdateManyCommand<T>, affected: number): Promise<void>;
    protected _afterDelete(command: SqbEntityService.DeleteOneCommand, affected: number): Promise<void>;
    protected _afterDeleteMany(command: SqbEntityService.DeleteManyCommand, affected: number): Promise<void>;
}