staticql/dist/src/QueryBuilder.d.ts

Type-safe query engine for static content including Markdown, YAML, JSON, and more.

import { SourceLoader } from "./SourceLoader.js";
import { Indexer } from "./Indexer.js";
import { SourceConfigResolver as Resolver, SourceRecord } from "./SourceConfigResolver.js";
import { LoggerProvider } from "./logger/LoggerProvider";
import { PageInfo } from "./utils/pagenation.js";
import { Fields, JoinableKeys, PrefixIndexLine } from "./utils/typs.js";
type OrderByDirection = "asc" | "desc";
export interface PageResult<T> {
    data: T[];
    pageInfo: PageInfo;
}
/**
 * QueryBuilder allows for type-safe querying and joining of static structured data.
 */
export declare class QueryBuilder<T extends SourceRecord, TIndexKey extends string> {
    private sourceName;
    private loader;
    private indexer;
    private resolver;
    private logger;
    private joins;
    private filters;
    private _orderByKey?;
    private _orderByDirection;
    private _cursorValue?;
    private _cursorDirection;
    private _pageSize;
    constructor(sourceName: string, loader: SourceLoader<T>, indexer: Indexer, resolver: Resolver, logger: LoggerProvider);
    /**
     * Adds a relation to join with.
     *
     * @param relationKey - Name of the relation as defined in the config.
     * @returns This instance (chainable).
     */
    join<K extends JoinableKeys<T>>(relationKey: K): QueryBuilder<T, TIndexKey>;
    /**
     * Adds a filter condition.
     *
     * @param field - Field to filter by.
     * @param op - Operator: "eq" | "contains" | "in".
     * @param value - Value or values to compare.
     * @returns This instance (chainable).
     */
    where(field: Fields<T> | TIndexKey, op: "eq" | "startsWith", value: string): QueryBuilder<T, TIndexKey>;
    where(field: Fields<T> | TIndexKey, op: "in", value: string[]): QueryBuilder<T, TIndexKey>;
    /**
     * Finds and returns a record by its slug.
     *
     * @param slug The slug (unique identifier) of the record to retrieve.
     * @returns The found record, with joins applied if necessary.
     */
    find(slug: string): Promise<T>;
    /**
     * Specifies the sorting order for the query.
     *
     * @param key - Field to order by. Default is "slug".
     * @param direction - Sort direction: "asc" or "desc". Default is "asc".
     * @returns This instance (for method chaining).
     */
    orderBy(key: Fields<T> | TIndexKey, direction?: OrderByDirection): this;
    /**
     * Sets the pagination cursor for the query.
     *
     * @param cursor - The encoded cursor string (usually Base64).
     *   Use the `endCursor` from the previous page's `pageInfo` for forward pagination,
     *   or the `startCursor` for backward pagination.
     * @param direction - Pagination direction: `"after"` for next page, `"before"` for previous page.
     *   Defaults to `"after"`.
     * @returns This instance (for method chaining).
     */
    cursor(value?: string, direction?: "after" | "before"): this;
    /**
     * Sets the number of records to return per page.
     *
     * @param n - The maximum number of records to return for this query (page size).
     *   Should be a positive integer.
     * @returns This instance (for method chaining).
     */
    pageSize(n: number): this;
    /**
     * Executes the query and returns matching records.
     *
     * @returns Matched data records.
     */
    exec(): Promise<PageResult<T>>;
    /**
     * Returns only the index page without loading full data.
     *
     * @returns Index page, pageInfo.
     */
    peek(): Promise<{
        page: PrefixIndexLine[];
        pageInfo: PageInfo;
    }>;
    /**
     * Compose pages.
     */
    private compose;
    /**
     * Get the starting position from the specified cursor.
     */
    private getStartIdx;
    /**
     * Categorizes filters into index-usable filters.
     */
    private extractIndexFilters;
    /**
     * Applies configured joins (relations) to the result set.
     */
    private applyJoins;
    /**
     * Direct relations: hasOne, hasMany, belongsTo, belongsToMany
     */
    private applyDirectRelation;
    /**
     * For "hasOneThrough" and "hasManyThrough" relations
     */
    private applyThroughRelation;
    /**
     * Resolves matched slugs using index data based on filters.
     */
    private getMatchedIndexes;
}
export {};