@decaf-ts/core/lib/persistence/Sequence.d.ts

Core persistence module for the decaf framework

import { Model } from "@decaf-ts/decorator-validation";
import { SequenceOptions, SequenceOptionsType } from "../interfaces/SequenceOptions";
import { Constructor } from "@decaf-ts/decoration";
import { ContextualLoggedClass, MaybeContextualArg } from "../utils/ContextualLoggedClass";
import { Adapter } from "./Adapter";
import { Repo } from "../repository/Repository";
import { SequenceModel } from "../model/SequenceModel";
import { Context } from "./Context";
import { MultiLock } from "@decaf-ts/transactional-decorators";
/**
 * @description Abstract base class for sequence generation
 * @summary Provides a framework for generating sequential values (like primary keys) in the persistence layer.
 * Implementations of this class handle the specifics of how sequences are stored and incremented in different
 * database systems.
 * @param {SequenceOptions} options - Configuration options for the sequence generator
 * @class Sequence
 * @example
 * ```typescript
 * // Example implementation for a specific database
 * class PostgresSequence extends Sequence {
 *   constructor(options: SequenceOptions) {
 *     super(options);
 *   }
 *
 *   async next(): Promise<number> {
 *     // Implementation to get next value from PostgreSQL sequence
 *     const result = await this.options.executor.raw(`SELECT nextval('${this.options.name}')`);
 *     return parseInt(result.rows[0].nextval);
 *   }
 *
 *   async current(): Promise<number> {
 *     // Implementation to get current value from PostgreSQL sequence
 *     const result = await this.options.executor.raw(`SELECT currval('${this.options.name}')`);
 *     return parseInt(result.rows[0].currval);
 *   }
 *
 *   async range(count: number): Promise<number[]> {
 *     // Implementation to get a range of values
 *     const values: number[] = [];
 *     for (let i = 0; i < count; i++) {
 *       values.push(await this.next());
 *     }
 *     return values;
 *   }
 * }
 *
 * // Usage
 * const sequence = new PostgresSequence({
 *   name: 'user_id_seq',
 *   executor: dbExecutor
 * });
 *
 * const nextId = await sequence.next();
 * ```
 */
export declare class Sequence extends ContextualLoggedClass<any> {
    protected readonly options: SequenceOptions;
    protected readonly adapter: Adapter<any, any, any>;
    protected repo: Repo<SequenceModel>;
    protected static readonly lock: MultiLock;
    /**
     * @description Creates a new sequence instance
     * @summary Protected constructor that initializes the sequence with the provided options
     */
    constructor(options: SequenceOptions, adapter: Adapter<any, any, any>);
    /**
     * @description Retrieves the current value of the sequence
     * @summary Gets the current value of the sequence from storage. If the sequence
     * doesn't exist yet, it returns the configured starting value.
     * @return A promise that resolves to the current sequence value
     */
    current(...args: MaybeContextualArg<any>): Promise<string | number | bigint>;
    /**
     * @description Increments the sequence value
     * @summary Increases the current sequence value by the specified amount and persists
     * the new value to storage. This method handles both numeric and BigInt sequence types.
     * @param {string | number | bigint} current - The current value of the sequence
     * @param {number} [count] - Optional amount to increment by, defaults to the sequence's incrementBy value
     * @return A promise that resolves to the new sequence value after incrementing
     */
    protected increment(count: number | undefined, ctx: Context<any>): Promise<string | number | bigint>;
    /**
     * @description Gets the next value in the sequence
     * @summary Retrieves the current value of the sequence and increments it by the
     * configured increment amount. This is the main method used to get a new sequential value.
     * @return A promise that resolves to the next value in the sequence
     */
    next(...argz: MaybeContextualArg<any>): Promise<number | string | bigint>;
    /**
     * @description Generates a range of sequential values
     * @summary Retrieves a specified number of sequential values from the sequence.
     * This is useful when you need to allocate multiple IDs at once.
     * The method increments the sequence by the total amount needed and returns all values in the range.
     * @param {number} count - The number of sequential values to generate
     * @return A promise that resolves to an array of sequential values
     */
    range(count: number, ...argz: MaybeContextualArg<any>): Promise<(number | string | bigint)[]>;
    protected parse(value: string | number | bigint): string | number | bigint;
    /**
     * @description Gets the primary key sequence name for a model
     * @summary Utility method that returns the standardized sequence name for a model's primary key
     * @template M - The model type
     * @param {M|Constructor<M>} model - The model instance or constructor
     * @return {string} The sequence name for the model's primary key
     */
    static pk<M extends Model>(model: M | Constructor<M>): string;
    /**
     * @description Parses a sequence value to the appropriate type
     * @summary Converts a sequence value to the specified type (Number or BigInt)
     * @param {"Number"|"BigInt"|undefined} type - The target type to convert to
     * @param {string|number|bigint} value - The value to convert
     * @return {string|number|bigint} The converted value
     */
    static parseValue(type: SequenceOptionsType, value: string | number | bigint): string | number | bigint;
}