/**
 *  Copyright 2026 Angus.Fenying <fenying@litert.org>
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *    https://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
import { ESequenceStrategy, ETimeReversedStrategy } from './Constants.js';
/**
 * @deprecated Use `ETimeReversedStrategy` instead.
 */
export { ETimeReversedStrategy as ESnowflakeTimeReversedStrategy } from './Constants.js';
/**
 * @deprecated Use `ESequenceStrategy` instead.
 */
export { ESequenceStrategy as ESnowflakeSequenceStrategy } from './Constants.js';
/**
 * The options for bulk generation of snowflake IDs.
 */
export interface IBulkGenerationOptions {
    /**
     * The maximum number of sequential retries for generating IDs in bulk.
     *
     * If the failures exceeded this limit, the original error will be thrown.
     *
     * @default 3
     */
    maxRetries?: number;
    /**
     * The delay between each retry attempt in milliseconds.
     *
     * @default 1
     */
    retryDelayMs?: number;
}
/**
 * The strategy for handling time changes in Snowflake ID generation.
 */
export type ISnowflakeUpdateSequenceOnTimeChanged<T extends number | bigint> = (current: T) => T;
/**
 * The options for the standard Snowflake ID generator.
 */
export interface ISnowflakeOptions extends Pick<SnowflakeGenerator, 'machineId'>, Partial<Pick<SnowflakeGenerator, 'epoch'>> {
    /**
     * The strategy for handling time reversal events.
     *
     * @default ETimeReversedStrategy.THROW_ERROR
     */
    onTimeReversed?: ETimeReversedStrategy;
    /**
     * The strategy for handling the sequence number when the time changes.
     *
     * This option also accepts a custom function that takes the current sequence number
     * and returns the new sequence number.
     *
     * @default ESequenceStrategy.RESET
     */
    onTimeChanged?: ESequenceStrategy | ISnowflakeUpdateSequenceOnTimeChanged<bigint>;
    /**
     * When the sequence strategy is set to `ESequenceStrategy.RESET`,
     * this option specifies the threshold for resetting the sequence number.
     * So only when the sequence number exceeds this threshold, the sequence number
     * will be reset to 0.
     *
     * @default 0
     */
    sequenceResetThreshold?: number;
}
/**
 * The default strategy for the time reversal event,
 * which throws an `E_TIME_REVERSED` error.
 */
export declare const SNOWFLAKE_DEFAULT_TIME_REVERSAL_STRATEGY = ETimeReversedStrategy.THROW_ERROR;
/**
 * The default strategy for the time changed event,
 * which reset the sequence number to 0.
 */
export declare const SNOWFLAKE_DEFAULT_TIME_CHANGED_STRATEGY = ESequenceStrategy.RESET;
/**
 * The class for generating Snowflake IDs.
 */
export declare class SnowflakeGenerator {
    /**
     * The strategy for the time reversal event.
     */
    private readonly _onTimeReversedStrategy;
    private readonly _onTimeChangedCallback;
    private readonly _onTimeChangedStrategy;
    private readonly _onTimeChangedResetThreshold;
    /**
     * The minimum machine ID that can be used by the generator.
     */
    static readonly MIN_MACHINE_ID = 0;
    /**
     * The maximum machine ID that can be used by the generator.
     */
    static readonly MAX_MACHINE_ID = 1023;
    /**
     * The identifier of the machine that generates the UUID.
     *
     * For the snowflake ID of a specific resource, each generator must use a unique machine ID
     * so that the generated IDs will not conflict with each other.
     *
     * @range 0 - 1023
     */
    readonly machineId: number;
    /**
     * The epoch of the generator.
     *
     * The value is recommended to be the time when the service/application goes online.
     *
     * @default 0
     */
    readonly epoch: number;
    private readonly _biInstId;
    private _prevTime;
    private _seq;
    private _countPerMs;
    constructor(opts: ISnowflakeOptions);
    /**
     * Generate a bulk of Snowflake IDs.
     *
     * This method helps generate batch of Snowflake IDs, handling the time
     * reversed and sequence overflow scenarios automatically.
     *
     * @param qty The quantity of IDs to generate.
     * @param opts The options for bulk generation.
     *
     * @returns A promise that resolves to an array of Snowflake IDs.
     */
    bulkGenerate(qty: number, opts?: IBulkGenerationOptions): Promise<bigint[]>;
    /**
     * Generate the next Snowflake ID, based on the current time and the next sequence number.
     *
     * @returns A Snowflake ID, which is a 64-bit integer (BigInt).
     *
     * @throws {E_TIME_REVERSED} If the current time is earlier than the previous time.
     * @throws {E_SEQUENCE_OVERFLOWED} If the sequence number exceeds the maximum value.
     * @throws {E_TIME_BEFORE_EPOCH} If the current time is before the epoch.
     */
    generate(): bigint;
    /**
     * Generate a Snowflake ID by specifying the timestamp and sequence number.
     *
     * @param timestamp The timestamp to use for the ID.
     * @param sequence The sequence number to use for the ID (0 ~ 4095).
     *
     * @returns A Snowflake ID, which is a 64-bit integer (BigInt).
     *
     * @throws {E_SEQUENCE_OVERFLOWED} If the sequence number exceeds the maximum value.
     * @throws {E_TIME_BEFORE_EPOCH} If the timestamp is before the epoch.
     */
    generateBy(timestamp: number, sequence: number): bigint;
}
//# sourceMappingURL=Snowflake.d.ts.map