@vireocodedev/query

export type CompiledQueryFilterWhere = {
    sql: string;
    params: unknown[];
    filterCount: number;
};

export type CreateQueryEngineApiOptions = {
    /** Consumer-owned schema used to validate/normalize entity keys in responses. Defaults to `z.string()`. */
    entityKeySchema?: z.ZodType<QueryEngineEntityKey>;
    /** Optional legacy path key for back-compat retries (return `undefined` when there is none). */
    legacyEntityKey?: (entityKey: QueryEngineEntityKey) => string | undefined;
};

export type CreateQueryEngineConfigSqliteHandlersConfig = {
    tableName: string;
    singletonKey?: string;
    requestTypes?: {
        replace: string;
        get: string;
    };
    parseJson?: <T>(value: string, fallback: T) => T;
};

export type CreateSqliteQueryExecutorConfig = {
    executePagedQuery: (request: ParameterizedSqlitePagedQueryRequest) => Promise<ParameterizedSqlitePagedQueryResult>;
    executeQuery: (request: ParameterizedSqliteQueryRequest) => Promise<ParameterizedSqliteQueryResult>;
    now?: () => number;
    log?: (message: string, details: Record<string, unknown>) => void;
};

export type ParameterizedSqlitePagedQueryRequest = {
    selectSql: string;
    fromSql: string;
    whereSql: string;
    whereParams: unknown[];
    orderBySql: string;
    limit: number | null;
    offset: number | null;
    includeTotalCount: boolean;
    clientSentAtMs?: number;
};

export type ParameterizedSqlitePagedQueryResult = ParameterizedSqliteQueryResult & {
    totalElements: number | null;
    queueWaitMs?: number;
    workerExecMs?: number;
};

export type ParameterizedSqliteQueryRequest = {
    sql: string;
    params: unknown[];
};

export type ParameterizedSqliteQueryResult = {
    columns: string[];
    rows: unknown[][];
};

export interface QueryEngineApi {
    listEntities(options?: QueryEngineRequestOptions): Promise<QueryEngineEntitySummary[]>;
    describeEntity(entityKey: QueryEngineEntityKey, options?: QueryEngineRequestOptions): Promise<QueryEngineEntityDefinition>;
    listRelationOptions(entityKey: QueryEngineEntityKey, fieldPath: string, searchText?: string, options?: QueryEngineRequestOptions): Promise<QueryEngineRelationOption[]>;
}

export type QueryEngineConfigClient = {
    replace: (config: SqliteQueryEngineConfigRecord) => Promise<void>;
    get: () => Promise<SqliteQueryEngineConfigRecord | null>;
    setFallback: (config: SqliteQueryEngineConfigRecord | null) => void;
    getFallback: () => SqliteQueryEngineConfigRecord | null;
    dispose: () => void;
};

export type QueryEngineConfigClientRuntime = {
    shouldUseInMemoryFallback: () => boolean;
    registerInMemoryStore: (store: {
        clear: () => void;
    }) => () => void;
};

export type QueryEngineConfigClientTransport = {
    sendRequest: <TResponse>(type: string, payload?: Record<string, unknown>) => Promise<TResponse>;
};

export type QueryEngineConfigSqliteDatabase = {
    prepare: (sql: string) => QueryEngineConfigSqliteStatement;
};

export type QueryEngineConfigSqliteOperationMap = {
    replaceQueryEngineConfig: {
        request: {
            config: SqliteQueryEngineConfigRecord;
        };
        response: null;
    };
    getQueryEngineConfig: {
        request: Record<string, never>;
        response: SqliteQueryEngineConfigRecord | null;
    };
};

export type QueryEngineConfigSqliteRequest = Record<string, unknown>;

export type QueryEngineConfigSqliteRequestHandler = (db: QueryEngineConfigSqliteDatabase, request: QueryEngineConfigSqliteRequest) => unknown;

export type QueryEngineConfigSqliteStatement = {
    bind: (values: readonly unknown[]) => unknown;
    step: () => boolean;
    get: (target: unknown[]) => unknown[];
    finalize: () => unknown;
};

The published shape of an entity. Backends are free to send more — the parse schemas pass unknown keys through untouched, so a consumer can widen this type with its own backend-specific fields: ```ts type AppEntityDefinition = QueryEngineEntityDefinition & { javaType: string }; ```

/**
 * The published shape of an entity. Backends are free to send more — the parse
 * schemas pass unknown keys through untouched, so a consumer can widen this type
 * with its own backend-specific fields:
 *
 * ```ts
 * type AppEntityDefinition = QueryEngineEntityDefinition & { javaType: string };
 * ```
 */
export interface QueryEngineEntityDefinition {
    key: QueryEngineEntityKey;
    title: string;
    fields: QueryEngineFieldDefinition[];
}

Entity keys are opaque strings at the library level. The consuming app owns its entity-key set and injects a validating/normalizing schema via {@link createQueryEngineEntitySchemas} (see createQueryEngineApi options).

/**
 * Entity keys are opaque strings at the library level. The consuming app owns
 * its entity-key set and injects a validating/normalizing schema via
 * {@link createQueryEngineEntitySchemas} (see createQueryEngineApi options).
 */
export type QueryEngineEntityKey = string;

export type QueryEngineEntitySchemas = {
    fieldDefinition: z.ZodType<QueryEngineFieldDefinition>;
    entityDefinition: z.ZodType<QueryEngineEntityDefinition>;
    entitySummary: z.ZodType<QueryEngineEntitySummary>;
};

export interface QueryEngineEntitySummary {
    key: QueryEngineEntityKey;
    filterableFieldCount: number;
}

export interface QueryEngineFieldDefinition {
    path: string;
    label: string;
    type: QueryEngineFieldType;
    enumType: string | null;
    enumValues: string[];
    operators: QueryEngineOperator[];
    relation: boolean;
    relationEntityKey: QueryEngineEntityKey | null;
    relationMode: QueryEngineRelationMode;
    multiple: boolean;
    relationSelectionLabelFields: string[];
    expandable: boolean;
    maxDepth: number;
    children: QueryEngineFieldDefinition[];
}

export type QueryEngineFieldType = z.infer<typeof QueryEngineFieldTypeSchema>;

export declare const QueryEngineFieldTypeSchema: z.ZodEnum<{
    STRING: "STRING";
    NUMBER: "NUMBER";
    BOOLEAN: "BOOLEAN";
    DATE: "DATE";
    ENUM: "ENUM";
    RELATION: "RELATION";
}>;

Port the query engine needs from its host application. The app injects an adapter (e.g. wrapping its axios client) so this module stays free of any HTTP/infrastructure dependency.

/**
 * Port the query engine needs from its host application. The app injects an
 * adapter (e.g. wrapping its axios client) so this module stays free of any
 * HTTP/infrastructure dependency.
 */
export interface QueryEngineHttpClient {
    /** GET a JSON resource relative to the query-engine base path. Returns raw JSON. */
    get(path: string, options?: QueryEngineRequestOptions): Promise<unknown>;
}

export type QueryEngineOperator = z.infer<typeof QueryEngineOperatorSchema>;

export declare const QueryEngineOperatorSchema: z.ZodEnum<{
    EQUALS: "EQUALS";
    NOT_EQUALS: "NOT_EQUALS";
    CONTAINS: "CONTAINS";
    STARTS_WITH: "STARTS_WITH";
    ENDS_WITH: "ENDS_WITH";
    IN: "IN";
    GREATER_THAN: "GREATER_THAN";
    GREATER_OR_EQUAL: "GREATER_OR_EQUAL";
    LESS_THAN: "LESS_THAN";
    LESS_OR_EQUAL: "LESS_OR_EQUAL";
    DATE_RANGE: "DATE_RANGE";
    IS_NULL: "IS_NULL";
    IS_NOT_NULL: "IS_NOT_NULL";
}>;

export declare const QueryEngineQueryKey: {
    readonly entities: "queryengineEntities";
    readonly entityDefinition: "queryengineEntityDefinition";
    readonly entityDefinitions: "queryengineEntityDefinitions";
};

export interface QueryEngineRelationFieldOptionsRequest {
    entityKey: QueryEngineEntityKey;
    fieldPath: string;
    searchText?: string;
}

export type QueryEngineRelationMode = z.infer<typeof QueryEngineRelationModeSchema>;

export declare const QueryEngineRelationModeSchema: z.ZodEnum<{
    CHILD: "CHILD";
    SELECTION: "SELECTION";
    BOTH: "BOTH";
}>;

export interface QueryEngineRelationOption {
    value: string;
    label: string;
}

export declare const QueryEngineRelationOptionSchema: z.ZodType<QueryEngineRelationOption>;

Transport-neutral request options — no dependency on a specific HTTP client.

/** Transport-neutral request options — no dependency on a specific HTTP client. */
export type QueryEngineRequestOptions = {
    params?: Record<string, unknown>;
    signal?: AbortSignal;
};

export type QueryExecutorSqliteDatabase = {
    prepare: (sql: string) => QueryExecutorSqliteStatement;
};

export type QueryExecutorSqliteStatement = {
    bind: (values: readonly unknown[]) => unknown;
    step: () => boolean;
    get: (target: unknown[]) => unknown[];
    getColumnNames?: (target?: string[]) => string[];
    finalize: () => unknown;
};

export type SqlitePageableParams = {
    page: number;
    rowsPerPage: number;
    sortBy?: string;
    sortDirection?: string;
};

export type SqlitePageableResponse<TRow> = {
    content: TRow[];
    number: number;
    size: number;
    totalElements: number;
    totalPages: number;
};

export type SqlitePagedSearchArgs<TKey extends string | number, TEntityKey extends string, TRow> = {
    adapter: SqliteQueryFilterAdapter<TKey, TEntityKey>;
    queryFiltersJson: string | null;
    pageable: SqlitePageableParams;
    selectColumns: SqliteSearchSelectColumn[];
    sortBy: string | undefined;
    sortDirection: string | undefined;
    defaultSortExpression: string;
    sortExpressionsByKey: Record<string, string>;
    mapRow: (row: unknown[], columnIndexes: Record<string, number>) => TRow;
    searchText?: string;
    searchExpressions?: string[];
    includeTotalCount?: boolean;
};

export type SqliteQueryEngineConfigRecord = {
    entities: unknown[];
    entityDefinitions: Record<string, unknown>;
};

export declare const SqliteQueryEngineConfigRecordSchema: z.ZodType<SqliteQueryEngineConfigRecord>;

export type SqliteQueryExecutor = {
    pagedSearch: <TKey extends string | number, TEntityKey extends string, TRow>(args: SqlitePagedSearchArgs<TKey, TEntityKey, TRow>) => Promise<SqlitePageableResponse<TRow>>;
    findMatchingKeys: <TKey extends string | number, TEntityKey extends string>(adapter: SqliteQueryFilterAdapter<TKey, TEntityKey>, queryFiltersJson: string | null) => Promise<Set<TKey> | null>;
};

export type SqliteQueryFilterAdapter<TKey extends string | number, TEntityKey extends string = string> = {
    entity: TEntityKey;
    fromClause: string;
    keyExpression: string;
    keyAlias: string;
    baseWhereClause?: string;
    fieldAdapters: Record<string, SqliteQueryFilterFieldAdapter>;
    parseKey: (raw: unknown) => TKey;
};

export type SqliteQueryFilterFieldAdapter = {
    expression: string;
    valueType: SqliteQueryFilterValueType;
};

export type SqliteQueryFilterValueType = "string" | "number" | "boolean";

export type SqliteSearchColumn = SqliteSearchSelectColumn & {
    valueType: SqliteQueryFilterValueType;
    /** Defaults to the alias; `false` makes the selected column unavailable to filters. */
    filterAs?: string | false;
    /** Defaults to the alias; `false` makes the selected column unavailable to sorting. */
    sortAs?: string | false;
};

export type SqliteSearchColumnBindings = {
    fieldAdapters: Record<string, SqliteQueryFilterFieldAdapter>;
    selectColumns: SqliteSearchSelectColumn[];
    sortExpressionsByKey: Record<string, string>;
};

export type SqliteSearchSelectColumn = {
    alias: string;
    expression: string;
};

export declare function bindSqliteSearchColumns(columns: readonly SqliteSearchColumn[], filterOnlyFields?: Record<string, SqliteQueryFilterFieldAdapter>): SqliteSearchColumnBindings;

export declare function compileQueryFilterWhere<TKey extends string | number, TEntityKey extends string>(adapter: SqliteQueryFilterAdapter<TKey, TEntityKey>, queryFiltersJson: string | null): CompiledQueryFilterWhere;

export declare function compileSearchTextWhere(searchText: string | undefined, searchExpressions: readonly string[] | undefined): CompiledClause | null;

Builds a {@link QueryEngineApi} bound to a host-provided HTTP client.

/** Builds a {@link QueryEngineApi} bound to a host-provided HTTP client. */
export declare function createQueryEngineApi(http: QueryEngineHttpClient, options?: CreateQueryEngineApiOptions): QueryEngineApi;

export declare function createQueryEngineConfigClient(config: {
    runtime: QueryEngineConfigClientRuntime;
    transport: QueryEngineConfigClientTransport;
    requestTypes?: {
        replace: string;
        get: string;
    };
}): QueryEngineConfigClient;

export declare function createQueryEngineConfigSqliteRequestHandlers(config: CreateQueryEngineConfigSqliteHandlersConfig): Record<string, QueryEngineConfigSqliteRequestHandler>;

Builds the entity-key-dependent parse schemas. Pass a consumer-owned `entityKeySchema` (e.g. an enum with legacy normalization) to validate keys; defaults to a non-empty string schema so the engine stays generic over any key set while still rejecting unusable identifiers.

/**
 * Builds the entity-key-dependent parse schemas. Pass a consumer-owned
 * `entityKeySchema` (e.g. an enum with legacy normalization) to validate keys;
 * defaults to a non-empty string schema so the engine stays generic over any
 * key set while still rejecting unusable identifiers.
 */
export declare function createQueryEngineEntitySchemas(entityKeySchema?: z.ZodType<QueryEngineEntityKey>): QueryEngineEntitySchemas;

export declare function createSqliteQueryExecutor(config: CreateSqliteQueryExecutorConfig): SqliteQueryExecutor;

export declare function executeParameterizedSqlitePagedQuery(db: QueryExecutorSqliteDatabase, request: ParameterizedSqlitePagedQueryRequest, now?: () => number): ParameterizedSqlitePagedQueryResult;

export declare function executeParameterizedSqliteQuery(db: QueryExecutorSqliteDatabase, request: ParameterizedSqliteQueryRequest): ParameterizedSqliteQueryResult;

export declare function getQueryEngineConfig(db: QueryEngineConfigSqliteDatabase, options: {
    tableName: string;
    singletonKey?: string;
    parseJson?: <T>(value: string, fallback: T) => T;
}): SqliteQueryEngineConfigRecord | null;

export declare function replaceQueryEngineConfig(db: QueryEngineConfigSqliteDatabase, config: SqliteQueryEngineConfigRecord, options: {
    tableName: string;
    singletonKey?: string;
}): void;