@opra/sqb/sqb-collection-service.d.ts

Opra SQB adapter package

import type { SqlElement } from '@sqb/builder';
import type { DTO, PartialDTO, PatchDTO, RequiredSome, Type } from 'ts-gems';
import { SQBAdapter } from './sqb-adapter.js';
import { SqbEntityService } from './sqb-entity-service.js';
/**
 * Options for SqbCollectionService.
 */
export declare namespace SqbCollectionService {
    /**
     * Configuration options for SqbCollectionService.
     */
    interface Options extends SqbEntityService.Options {
        /**
         * Default maximum number of records returned by `findMany`.
         */
        defaultLimit?: SqbCollectionService<any>['defaultLimit'];
        /**
         * Optional interceptor for the service operations.
         */
        interceptor?: SqbCollectionService<any>['interceptor'];
    }
}
/**
 * Service for managing a collection of entities backed by an SQB data source.
 *
 * @typeParam T - The entity type managed by this service
 */
export declare class SqbCollectionService<T extends object = object> extends SqbEntityService<T> {
    /**
     * Default maximum number of records returned by `findMany`.
     */
    defaultLimit: number;
    /**
     * Constructs a new instance.
     *
     * @param dataType - The data type of the collection elements.
     * @param options - Options for the collection service.
     */
    constructor(dataType: Type<T> | string, options?: SqbCollectionService.Options);
    /**
     * Asserts that a resource with the given ID exists.
     * Throws {@link ResourceNotAvailableError} if it does not.
     *
     * @param id - The ID of the resource to check.
     * @param options - Optional existence check options.
     * @throws {@link ResourceNotAvailableError} If the resource does not exist.
     */
    assert(id: SQBAdapter.IdOrIds, options?: SqbEntityService.ExistsOptions): Promise<void>;
    /**
     * Creates a new resource and returns it with the requested projection.
     *
     * @param input - The input data for the new resource.
     * @param options - Options including a required `projection`.
     * @returns The created resource as a partial DTO.
     */
    create(input: PartialDTO<T>, options: RequiredSome<SqbEntityService.CreateOptions, 'projection'>): Promise<PartialDTO<T>>;
    /**
     * Creates a new resource and returns the full DTO.
     *
     * @param input - The input data for the new resource.
     * @param options - Optional create options.
     * @returns The created resource as a full DTO.
     */
    create(input: PartialDTO<T>, options?: SqbEntityService.CreateOptions): Promise<T>;
    /**
     * Creates a new resource without returning it.
     *
     * @param input - The input data for the new resource.
     * @param options - Optional create options.
     */
    createOnly(input: PartialDTO<T>, options?: SqbEntityService.CreateOptions): Promise<void>;
    /**
     * Returns the number of records matching the given options.
     *
     * @param options - Options for the count operation.
     * @returns The number of matching records.
     */
    count(options?: SqbEntityService.CountOptions): Promise<number>;
    /**
     * Deletes the record with the given ID.
     *
     * @param id - The ID of the record to delete.
     * @param options - Optional delete options.
     * @returns The number of records deleted.
     */
    delete(id: SQBAdapter.IdOrIds, options?: SqbEntityService.DeleteOptions): Promise<number>;
    /**
     * Deletes all records matching the given options.
     *
     * @param options - Options including filter criteria.
     * @returns The number of records deleted.
     */
    deleteMany(options?: SqbEntityService.DeleteManyOptions): Promise<number>;
    /**
     * Checks whether a record with the given ID exists.
     *
     * @param id - The ID to check.
     * @param options - Optional query options.
     * @returns `true` if the record exists, `false` otherwise.
     */
    exists(id: SQBAdapter.IdOrIds, options?: SqbEntityService.ExistsOptions): Promise<boolean>;
    /**
     * Checks whether any record matching the given options exists.
     *
     * @param options - Optional query options.
     * @returns `true` if at least one matching record exists, `false` otherwise.
     */
    existsOne(options?: SqbEntityService.ExistsOptions): Promise<boolean>;
    /**
     * Finds a record by ID and returns it with the requested projection.
     *
     * @param id - The ID of the record.
     * @param options - Options including a required `projection`.
     * @returns The found record as a partial DTO, or `undefined` if not found.
     */
    findById(id: SQBAdapter.IdOrIds, options?: RequiredSome<SqbEntityService.FindOneOptions, 'projection'>): Promise<PartialDTO<T> | undefined>;
    /**
     * Finds a record by ID and returns the whole DTO.
     *
     * @param id - The ID of the record.
     * @param options - Optional query options.
     * @returns The found record, or `undefined` if not found.
     */
    findById(id: SQBAdapter.IdOrIds, options?: SqbEntityService.FindOneOptions): Promise<DTO<T> | undefined>;
    /**
     * Finds the first record matching the given options and returns it with the requested projection.
     *
     * @param options - Options including a required `projection`.
     * @returns A promise that resolves to the found record as a partial DTO, or `undefined` if not found.
     */
    findOne(options: RequiredSome<SqbEntityService.FindOneOptions, 'projection'>): Promise<PartialDTO<T> | undefined>;
    /**
     * Finds the first record matching the given options and returns the whole DTO.
     *
     * @param options - Optional query options.
     * @returns A promise that resolves to the found record, or `undefined` if not found.
     */
    findOne(options?: SqbEntityService.FindOneOptions): Promise<DTO<T> | undefined>;
    /**
     * Finds multiple records matching the given options and returns partial DTOs.
     *
     * @param options - Options including a required `projection`.
     * @returns An array of matching records as partial DTOs.
     */
    findMany(options?: RequiredSome<SqbEntityService.FindManyOptions, 'projection'>): Promise<PartialDTO<T>[]>;
    /**
     * Finds multiple records matching the given options and returns whole DTOs.
     *
     * @param options - Optional query options.
     * @returns An array of matching records as full DTOs.
     */
    findMany(options?: SqbEntityService.FindManyOptions): Promise<DTO<T>[]>;
    /**
     * Finds multiple records and returns them together with the total count of matches.
     *
     * @param options - Options including a required `projection`.
     * @returns An object with `items` (partial DTOs) and `count` (total matches).
     */
    findManyWithCount(options?: RequiredSome<SqbEntityService.FindManyOptions, 'projection'>): Promise<{
        count: number;
        items: PartialDTO<T>[];
    }>;
    /**
     * Finds multiple records and returns them together with the total count of matches.
     *
     * @param options - Optional query options.
     * @returns An object with `items` (full DTOs) and `count` (total matches).
     */
    findManyWithCount(options?: SqbEntityService.FindManyOptions): Promise<{
        count: number;
        items: DTO<T>[];
    }>;
    /**
     * Retrieves a record by ID. Throws if the record does not exist.
     *
     * @param id - The ID of the record to retrieve.
     * @param options - Options including a required `projection`.
     * @returns The record as a partial DTO.
     * @throws {@link ResourceNotAvailableError} If the record does not exist.
     */
    get(id: SQBAdapter.IdOrIds, options?: RequiredSome<SqbEntityService.FindOneOptions, 'projection'>): Promise<PartialDTO<T>>;
    /**
     * Retrieves a record by ID. Throws if the record does not exist.
     *
     * @param id - The ID of the record to retrieve.
     * @param options - Optional query options.
     * @returns The record as a full DTO.
     * @throws {@link ResourceNotAvailableError} If the record does not exist.
     */
    get(id: SQBAdapter.IdOrIds, options?: SqbEntityService.FindOneOptions): Promise<DTO<T>>;
    /**
     * Updates a record by ID and returns the updated record with the requested projection.
     *
     * @param id - The ID of the record to update.
     * @param input - The fields to update.
     * @param options - Options including a required `projection`.
     * @returns The updated record as a partial DTO, or `undefined` if not found.
     */
    update(id: SQBAdapter.IdOrIds, input: PatchDTO<T, SqlElement>, options?: RequiredSome<SqbEntityService.UpdateOneOptions, 'projection'>): Promise<PartialDTO<T> | undefined>;
    /**
     * Updates a record by ID and returns the full updated DTO.
     *
     * @param id - The ID of the record to update.
     * @param input - The fields to update.
     * @param options - Optional update options.
     * @returns The updated record as a full DTO, or `undefined` if not found.
     */
    update(id: SQBAdapter.IdOrIds, input: PatchDTO<T, SqlElement>, options?: SqbEntityService.UpdateOneOptions): Promise<DTO<T> | undefined>;
    /**
     * Updates a record by ID without returning it.
     *
     * @param id - The ID of the record to update.
     * @param input - The fields to update.
     * @param options - Optional update options.
     * @returns The number of records modified.
     */
    updateOnly(id: SQBAdapter.IdOrIds, input: PatchDTO<T, SqlElement>, options?: SqbEntityService.UpdateOneOptions): Promise<number>;
    /**
     * Updates all records matching the given options.
     *
     * @param input - The fields to update.
     * @param options - Options including filter criteria.
     * @returns The number of records modified.
     */
    updateMany(input: PatchDTO<T, SqlElement>, options?: SqbEntityService.UpdateManyOptions): Promise<number>;
}