fraci/dist/dev/drizzle.d.cts

Fractional indexing that's robust, performant, and secure, with first-class support for Drizzle ORM and Prisma ORM.

import { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core';
import { Table, Column, ColumnBaseConfig } from 'drizzle-orm';
import { A as AnyFraci, a as AnyFractionalIndex, b as AnyBinaryFractionalIndex, F as FractionalIndexOf } from './types-Gn-I8HuO.cjs';
import { MySqlDatabase } from 'drizzle-orm/mysql-core';
import { PgDatabase } from 'drizzle-orm/pg-core';

/**
 * Represents a Drizzle ORM column that stores a fractional index.
 * This type extends the standard Drizzle Column type with additional
 * type information to ensure type safety when working with fractional indices.
 *
 * @template FI - The specific fractional index type this column will store
 */
type DrizzleFraciColumn<FI extends AnyFractionalIndex = AnyFractionalIndex> = Column<ColumnBaseConfig<FI extends AnyBinaryFractionalIndex ? "buffer" : "string", string>, object> & {
    _: {
        data: FI;
    };
};
/**
 * Configuration for using fractional indexing with Drizzle ORM.
 * This type defines the structure needed to integrate fractional indexing
 * into a Drizzle ORM database schema, including the table, column, and
 * grouping information.
 *
 * @template F - The fractional indexing utility type
 * @template T - The Drizzle table type
 * @template FraciColumn - The column type that stores fractional indices
 * @template Group - The record type for grouping columns
 * @template Cursor - The record type for cursor columns
 */
interface DrizzleFraciConfig<F extends AnyFraci = AnyFraci, T extends Table = Table, FraciColumn extends DrizzleFraciColumn<FractionalIndexOf<F>> = DrizzleFraciColumn<FractionalIndexOf<F>>, Group extends Record<string, Column> = Record<string, Column>, Cursor extends Record<string, Column> = Record<string, Column>> {
    /** A fraci instance. */
    readonly fraci: F;
    /** The table to which the fractional index belongs. */
    readonly table: T;
    /**
     * The column that stores the fractional index.
     * Must be branded with the fractional index type using `$type<FractionalIndexOf<F>>()`.
     *
     * @see {@link FractionalIndexOf}
     */
    readonly column: FraciColumn;
    /** The columns that define the grouping context for the fractional index. */
    readonly group: Group;
    /** The columns that uniquely identify a row within a group. */
    readonly cursor: Cursor;
}
/**
 * Represents a cursor for navigating through fractionally indexed rows.
 * This type maps the cursor columns defined in the configuration to their
 * corresponding data types, creating a type-safe cursor object.
 *
 * @template Config - The Drizzle fractional indexing configuration
 */
type DrizzleFraciCursor<Config extends DrizzleFraciConfig> = {
    [K in keyof Config["cursor"]]: Config["cursor"][K]["_"]["data"];
};
/**
 * Represents a group context for fractional indices.
 * This type maps the group columns defined in the configuration to their
 * corresponding data types, creating a type-safe group object.
 *
 * @template Config - The Drizzle fractional indexing configuration
 */
type DrizzleFraciGroup<Config extends DrizzleFraciConfig> = {
    [K in keyof Config["group"]]: Config["group"][K]["_"]["data"];
};
/**
 * The fractional index type associated with a specific configuration.
 * This type alias extracts the exact fractional index type from the
 * configuration's fraci instance.
 *
 * @template Config - The Drizzle fractional indexing configuration
 */
type DrizzleFractionalIndex<Config extends DrizzleFraciConfig> = FractionalIndexOf<Config["fraci"]>;

/**
 * Type representing supported synchronous Drizzle database clients.
 * This is specifically for Bun SQLite, which is the only synchronous database engine currently available.
 */
type SupportedDrizzleDatabaseSync = BaseSQLiteDatabase<"sync", any, any>;
/**
 * Type representing the enhanced fractional indexing utility for Drizzle ORM with synchronous database engine.
 * This type extends the base fractional indexing utility with additional
 * methods for retrieving indices based on synchronous database queries.
 *
 * This is the synchronous counterpart to the {@link FraciForDrizzle} type.
 *
 * @template Config - The type of the fractional indexing configuration
 *
 * @see {@link Fraci} - The base fractional indexing utility type
 * @see {@link drizzleFraciSync} - The main function to create an instance of this type
 * @see {@link FraciForDrizzle} - The asynchronous version of this type
 */
type FraciForDrizzleSync<Config extends DrizzleFraciConfig> = Config["fraci"] & {
    /**
     * Returns the indices to calculate the new index of the item to be inserted after the cursor.
     *
     * @param group - A record of the columns that uniquely identifies the group.
     * @param cursor - A record of the cursor row columns that uniquely identifies the item within a group. If `null`, this function returns the indices to calculate the new index of the first item in the group.
     * @returns The indices to calculate the new index of the item to be inserted after the cursor.
     */
    readonly indicesForAfter: {
        (group: DrizzleFraciGroup<Config>, cursor: DrizzleFraciCursor<Config>): [
            DrizzleFractionalIndex<Config>,
            DrizzleFractionalIndex<Config> | null
        ] | undefined;
        (group: DrizzleFraciGroup<Config>, cursor: null): [null, DrizzleFractionalIndex<Config> | null];
    };
    /**
     * Returns the indices to calculate the new index of the item to be inserted before the cursor.
     *
     * @param group - A record of the columns that uniquely identifies the group.
     * @param cursor - A record of the cursor row columns that uniquely identifies the item within a group. If `null`, this function returns the indices to calculate the new index of the last item in the group.
     * @returns The indices to calculate the new index of the item to be inserted before the cursor.
     */
    readonly indicesForBefore: {
        (group: DrizzleFraciGroup<Config>, cursor: DrizzleFraciCursor<Config>): [
            DrizzleFractionalIndex<Config> | null,
            DrizzleFractionalIndex<Config>
        ] | undefined;
        (group: DrizzleFraciGroup<Config>, cursor: null): [DrizzleFractionalIndex<Config> | null, null];
    };
    /**
     * Returns the indices to calculate the new index of the first item in the group.
     * Identical to {@link FraciForDrizzleSync.indicesForAfter `indicesForAfter(null, group)`}.
     *
     * @param group - A record of the columns that uniquely identifies the group.
     * @returns The indices to calculate the new index of the first item in the group.
     */
    readonly indicesForFirst: (group: DrizzleFraciGroup<Config>) => [null, DrizzleFractionalIndex<Config> | null];
    /**
     * Returns the indices to calculate the new index of the last item in the group.
     * Identical to {@link FraciForDrizzleSync.indicesForBefore `indicesForBefore(null, group)`}.
     *
     * @param group - A record of the columns that uniquely identifies the group.
     * @returns The indices to calculate the new index of the last item in the group.
     */
    readonly indicesForLast: (group: DrizzleFraciGroup<Config>) => [DrizzleFractionalIndex<Config> | null, null];
};
/**
 * Creates a synchronous fractional indexing utility for Drizzle ORM.
 * This function enhances a fractional indexing instance with Drizzle-specific
 * methods for retrieving indices based on synchronous database queries.
 *
 * This is the synchronous counterpart to the {@link drizzleFraci} function.
 * Use this function when working with Bun SQLite.
 * The API is identical except that methods return values directly instead of Promises.
 *
 * @template Config - The type of the fractional indexing configuration
 *
 * @param client - The synchronous Drizzle database client to use for queries (SQLite in sync mode)
 * @param config - The configuration for fractional indexing
 * @returns An enhanced fractional indexing utility with Drizzle-specific synchronous methods
 *
 * @example
 * ```typescript
 * const db = drizzle(connection);
 * const taskFraci = drizzleFraciSync(db, defineDrizzleFraci({
 *   fraciString({ lengthBase: BASE62, digitBase: BASE62 }),
 *   tasks,
 *   tasks.position,
 *   { userId: tasks.userId },
 *   { id: tasks.id }
 * }));
 *
 * // Get indices for inserting at the beginning of a user's task list
 * // Note: No await needed since this is synchronous
 * const [a, b] = taskFraci.indicesForFirst({ userId: 123 });
 * const [newPosition] = taskFraci.generateKeyBetween(a, b);
 * ```
 *
 * @see {@link drizzleFraci} - The asynchronous version of this function
 */
declare function drizzleFraciSync<Config extends DrizzleFraciConfig>(client: SupportedDrizzleDatabaseSync, config: Config): FraciForDrizzleSync<Config>;

/**
 * Union type of supported asynchronous Drizzle database clients.
 * This type includes SQLite (in async API), PostgreSQL, and MySQL database clients
 * that can be used with the fractional indexing functionality.
 */
type SupportedDrizzleDatabase = BaseSQLiteDatabase<"async", any, any> | PgDatabase<any, any, any> | MySqlDatabase<any, any, any, any>;
/**
 * Type representing the enhanced fractional indexing utility for Drizzle ORM with asynchronous database engine.
 * This type extends the base fractional indexing utility with additional
 * methods for retrieving indices based on asynchronous database queries.
 *
 * @template Config - The type of the fractional indexing configuration
 *
 * @see {@link drizzleFraci} - The main function to create an instance of this type
 * @see {@link FraciForDrizzleSync} - The synchronous version of this type
 */
type FraciForDrizzle<Config extends DrizzleFraciConfig> = Config["fraci"] & {
    /**
     * Returns the indices to calculate the new index of the item to be inserted after the cursor.
     *
     * @param group - A record of the columns that uniquely identifies the group.
     * @param cursor - A record of the cursor row columns that uniquely identifies the item within a group. If `null`, this function returns the indices to calculate the new index of the first item in the group.
     * @returns The indices to calculate the new index of the item to be inserted after the cursor.
     */
    readonly indicesForAfter: {
        (group: DrizzleFraciGroup<Config>, cursor: DrizzleFraciCursor<Config>): Promise<[
            DrizzleFractionalIndex<Config>,
            DrizzleFractionalIndex<Config> | null
        ] | undefined>;
        (group: DrizzleFraciGroup<Config>, cursor: null): Promise<[null, DrizzleFractionalIndex<Config> | null]>;
    };
    /**
     * Returns the indices to calculate the new index of the item to be inserted before the cursor.
     *
     * @param group - A record of the columns that uniquely identifies the group.
     * @param cursor - A record of the cursor row columns that uniquely identifies the item within a group. If `null`, this function returns the indices to calculate the new index of the last item in the group.
     * @returns The indices to calculate the new index of the item to be inserted before the cursor.
     */
    readonly indicesForBefore: {
        (group: DrizzleFraciGroup<Config>, cursor: DrizzleFraciCursor<Config>): Promise<[
            DrizzleFractionalIndex<Config> | null,
            DrizzleFractionalIndex<Config>
        ] | undefined>;
        (group: DrizzleFraciGroup<Config>, cursor: null): Promise<[DrizzleFractionalIndex<Config> | null, null]>;
    };
    /**
     * Returns the indices to calculate the new index of the first item in the group.
     * Identical to {@link FraciForDrizzle.indicesForAfter `indicesForAfter(null, group)`}.
     *
     * @param group - A record of the columns that uniquely identifies the group.
     * @returns The indices to calculate the new index of the first item in the group.
     */
    readonly indicesForFirst: (group: DrizzleFraciGroup<Config>) => Promise<[null, DrizzleFractionalIndex<Config> | null]>;
    /**
     * Returns the indices to calculate the new index of the last item in the group.
     * Identical to {@link FraciForDrizzle.indicesForBefore `indicesForBefore(null, group)`}.
     *
     * @param group - A record of the columns that uniquely identifies the group.
     * @returns The indices to calculate the new index of the last item in the group.
     */
    readonly indicesForLast: (group: DrizzleFraciGroup<Config>) => Promise<[DrizzleFractionalIndex<Config> | null, null]>;
};
/**
 * Creates an asynchronous fractional indexing utility for Drizzle ORM.
 * This function enhances a fractional indexing instance with Drizzle-specific
 * methods for retrieving indices based on asynchronous database queries.
 *
 * This is the asynchronous version that works with all supported database engines.
 * For Bun SQLite, use the {@link drizzleFraciSync} function.
 * The API is identical except that methods return Promises instead of direct values.
 *
 * @template Config - The type of the fractional indexing configuration
 *
 * @param client - The asynchronous Drizzle database client to use for queries
 * @param config - The configuration for fractional indexing
 * @returns An enhanced fractional indexing utility with Drizzle-specific asynchronous methods
 *
 * @example
 * ```typescript
 * const db = drizzle(connection);
 * const taskFraci = drizzleFraci(db, defineDrizzleFraci({
 *   fraciString({ lengthBase: BASE62, digitBase: BASE62 }),
 *   tasks,
 *   tasks.position,
 *   { userId: tasks.userId },
 *   { id: tasks.id }
 * }));
 *
 * // Get indices for inserting at the beginning of a user's task list
 * // Note: await is needed since this is asynchronous
 * const [a, b] = await taskFraci.indicesForFirst({ userId: 123 });
 * const [newPosition] = taskFraci.generateKeyBetween(a, b);
 * ```
 *
 * @see {@link drizzleFraciSync} - The synchronous version of this function
 */
declare function drizzleFraci<Config extends DrizzleFraciConfig>(client: SupportedDrizzleDatabase, config: Config): FraciForDrizzle<Config>;

/**
 * Creates a configuration object for fractional indexing with Drizzle ORM.
 * This function defines how fractional indices are integrated into a Drizzle schema,
 * specifying the table, column, grouping context, and cursor information.
 *
 * @template F - The fractional indexing utility type
 * @template T - The Drizzle table type
 * @template FraciColumn - The column type that stores fractional indices
 * @template Group - The record type for grouping columns
 * @template Cursor - The record type for cursor columns
 *
 * @param fraci - The fractional indexing utility instance
 * @param table - The Drizzle table object
 * @param column - The column that will store the fractional index
 * @param group - The columns that define the grouping context
 * @param cursor - The columns that uniquely identify a row within a group
 * @returns A configuration object for fractional indexing
 */
declare function defineDrizzleFraci<F extends AnyFraci, T extends Table, FraciColumn extends DrizzleFraciColumn<FractionalIndexOf<F>>, Group extends Record<string, Column>, Cursor extends Record<string, Column>>(fraci: F, table: T, column: FraciColumn, group: Group, cursor: Cursor): DrizzleFraciConfig<F, T, FraciColumn, Group, Cursor>;

export { type DrizzleFraciColumn, type DrizzleFraciConfig, type DrizzleFraciCursor, type DrizzleFraciGroup, type DrizzleFractionalIndex, type FraciForDrizzle, type FraciForDrizzleSync, type SupportedDrizzleDatabase, type SupportedDrizzleDatabaseSync, defineDrizzleFraci, drizzleFraci, drizzleFraciSync };