@crossfox/query-handler 0.1.0

package/dist/env.js

@@ -0,0 +1,30 @@
+/** Чтение env без зависимости от app config. */
+export function envInt(raw, fallback) {
+    if (raw == null || raw === "")
+        return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : fallback;
+}
+export function envBool(raw, fallback) {
+    if (raw == null || raw === "")
+        return fallback;
+    const v = raw.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(v))
+        return true;
+    if (["0", "false", "no", "off"].includes(v))
+        return false;
+    return fallback;
+}
+function bunEnv(key) {
+    try {
+        // Bun.env в runtime; в чистом tsc — process.env
+        const b = globalThis.Bun;
+        return b?.env?.[key] ?? (typeof process !== "undefined" ? process.env[key] : undefined);
+    }
+    catch {
+        return typeof process !== "undefined" ? process.env[key] : undefined;
+    }
+}
+export function readEnv(key) {
+    return bunEnv(key);
+}

package/dist/filter.d.ts

@@ -0,0 +1,6 @@
+import type { QueryBuilder } from "@crossfox/db";
+import type { QueryHandlerOptions, QueryHandlerContext } from "./types";
+export interface ApplyFiltersResult {
+    appliedFilters: Record<string, unknown>;
+}
+export declare function applyFilters($q: QueryBuilder, filter: Record<string, unknown>, options: QueryHandlerOptions, ctx: Omit<QueryHandlerContext, 'filters'>, baseRef?: string): Promise<ApplyFiltersResult>;

package/dist/filter.js

@@ -0,0 +1,207 @@
+import { toArray } from "./util";
+import { getQueryHandlerDefaults } from "./config";
+import { DANGEROUS_KEYS } from "./constants";
+import { err, resolveFieldType, parseValue, resolveAllowedOperators, qualifyWhereColumn, isSchemaFactoryLike, } from "./helpers";
+export async function applyFilters($q, filter, options, ctx, baseRef) {
+    const forcedKeys = new Set(Object.keys(options.filtersForced ?? {}));
+    const appliedFilters = {};
+    const emptyValues = new Set(options.limits?.emptyValues ?? [undefined, null, '']);
+    // ── filterForced ─────────────────────────────────────────────
+    if (forcedKeys.size) {
+        const fw = {};
+        for (const [k, v] of Object.entries(options.filtersForced))
+            fw[qualifyWhereColumn(k, baseRef)] = v;
+        $q.where(fw);
+    }
+    // ── filterRequired ───────────────────────────────────────────
+    if (options.filtersRequired) {
+        const rw = {};
+        for (const [k, v] of Object.entries(options.filtersRequired))
+            rw[qualifyWhereColumn(k, baseRef)] = v;
+        $q.where(rw);
+    }
+    const filterKeys = Object.keys(filter);
+    const allowedFilters = options.filters ?? {};
+    const allowedKeys = Object.keys(allowedFilters);
+    // ── requiredFilters ───────────────────────────────────────────
+    if (options.requiredFilters?.length) {
+        for (const rf of options.requiredFilters) {
+            if (!filterKeys.includes(rf) || emptyValues.has(filter[rf]))
+                err(`filter[${rf}] is required`);
+        }
+    }
+    // ── strictFilters ─────────────────────────────────────────────
+    const { isDev, logger } = getQueryHandlerDefaults().runtime;
+    if (filterKeys.length && !allowedKeys.length) {
+        if (options.strictFilters)
+            err('Filters are not supported for this endpoint');
+        else if (isDev)
+            logger?.info?.('queryHandler', 'filter keys ignored (no whitelist): ' + filterKeys.join(', '));
+        return { appliedFilters };
+    }
+    if (!allowedKeys.length || !filterKeys.length) {
+        // Применяем filterDefault если клиент ничего не передал
+        if (options.filtersDefault) {
+            const dw = {};
+            for (const [k, v] of Object.entries(options.filtersDefault))
+                dw[qualifyWhereColumn(k, baseRef)] = v;
+            if (Object.keys(dw).length)
+                $q.where(dw);
+        }
+        return { appliedFilters };
+    }
+    // ── Обработка фильтров ────────────────────────────────────────
+    const where = {};
+    for (const f of filterKeys) {
+        if (!Object.hasOwn(filter, f))
+            continue;
+        if (DANGEROUS_KEYS.has(f) || forcedKeys.has(f))
+            err('Invalid filter key');
+        if (!Object.prototype.hasOwnProperty.call(allowedFilters, f)) {
+            if (options.strictFilters)
+                err('Filter not found: ' + f);
+            if (isDev)
+                logger?.warn?.('queryHandler', `Unknown filter key ignored: "${f}"`);
+            continue;
+        }
+        const fieldCfg = allowedFilters[f];
+        const fieldType = resolveFieldType(fieldCfg, f);
+        const fullCfg = (typeof fieldCfg === 'object')
+            ? fieldCfg
+            : null;
+        // ── deprecated ────────────────────────────────────────────
+        if (fullCfg?.deprecated && isDev)
+            logger?.warn?.('queryHandler', `Filter "${f}" is deprecated: ${fullCfg.deprecated}`);
+        // ── enable → 403 ──────────────────────────────────────────
+        if (fullCfg?.enable !== undefined) {
+            const enabled = typeof fullCfg.enable === 'function'
+                ? await fullCfg.enable({ ...ctx, filters: appliedFilters })
+                : fullCfg.enable;
+            if (!enabled)
+                err(`Filter "${f}" is not available`, 403);
+        }
+        // ── функция-обработчик ────────────────────────────────────
+        if (typeof fieldCfg === 'function') {
+            await fieldCfg($q, filter[f]);
+            appliedFilters[f] = filter[f];
+            continue;
+        }
+        let val = filter[f];
+        // ── sanitize ──────────────────────────────────────────────
+        if (fullCfg?.sanitize)
+            val = fullCfg.sanitize(val);
+        // ── validate ──────────────────────────────────────────────
+        if (fullCfg?.validate)
+            await fullCfg.validate(val, { ...ctx, filters: appliedFilters });
+        // ── dependsOn ─────────────────────────────────────────────
+        if (fullCfg?.dependsOn) {
+            for (const dep of toArray(fullCfg.dependsOn)) {
+                if (!filterKeys.includes(dep) || emptyValues.has(filter[dep]))
+                    err(`Filter "${f}" requires filter "${dep}"`);
+            }
+        }
+        // ── conflictsWith ─────────────────────────────────────────
+        if (fullCfg?.conflictsWith) {
+            for (const conflict of toArray(fullCfg.conflictsWith)) {
+                if (filterKeys.includes(conflict) && !emptyValues.has(filter[conflict]))
+                    err(`Filter "${f}" conflicts with filter "${conflict}"`);
+            }
+        }
+        // ── enum ──────────────────────────────────────────────────
+        if (fullCfg?.enum !== undefined) {
+            await assertEnum(fullCfg.enum, val, f);
+        }
+        const colName = fullCfg?.column ?? f;
+        const allowedOps = resolveAllowedOperators(options.limits, fieldType);
+        const qCol = qualifyWhereColumn(colName, baseRef);
+        // ── operator объект ───────────────────────────────────────
+        if (val && typeof val === 'object' && !Array.isArray(val)) {
+            const opKeys = Object.keys(val);
+            if (!opKeys.length)
+                err(`Filter "${f}": operator object is empty`);
+            if (opKeys.length > 1)
+                err(`Filter "${f}": only one operator allowed`);
+            const op = opKeys[0].toLowerCase();
+            if (!allowedOps.has(op))
+                err(`Operator "${op}" is not allowed`);
+            if (op === 'between') {
+                const parts = String(val[op]).split(',');
+                if (parts.length < 2)
+                    err(`Filter "${f}": between requires two comma-separated values`);
+                where[qCol] = {
+                    gte: parseValue(parts[0].trim(), fieldType, f),
+                    lte: parseValue(parts[1].trim(), fieldType, f),
+                };
+            }
+            else if (op === 'in' || op === 'nin') {
+                where[qCol] = {
+                    [op]: String(val[op]).split(',')
+                        .map(v => parseValue(v.trim(), fieldType, f)),
+                };
+            }
+            else if (op === 'null') {
+                where[qCol] = null;
+            }
+            else if (op === 'nnull') {
+                where[qCol] = { nnull: true };
+            }
+            else {
+                where[qCol] = { [op]: parseValue(val[op], fieldType, f) };
+            }
+        }
+        else {
+            // ── multiple ──────────────────────────────────────────
+            if (fullCfg?.multiple && typeof val === 'string' && val.includes(',')) {
+                where[qCol] = {
+                    in: val.split(',').map(v => parseValue(v.trim(), fieldType, f)),
+                };
+            }
+            else {
+                let parsed = parseValue(val, fieldType, f);
+                if (fullCfg?.transform)
+                    parsed = fullCfg.transform(parsed);
+                where[qCol] = parsed;
+            }
+        }
+        appliedFilters[f] = where[qCol];
+    }
+    // ── filterDefault — только если ключ не передан ───────────────
+    if (options.filtersDefault) {
+        for (const [k, v] of Object.entries(options.filtersDefault)) {
+            if (!filterKeys.includes(k)) {
+                where[qualifyWhereColumn(k, baseRef)] = v;
+            }
+        }
+    }
+    if (Object.keys(where).length)
+        $q.where(where);
+    return { appliedFilters };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Enum проверка
+// ─────────────────────────────────────────────────────────────────────────────
+async function assertEnum(enumCfg, val, field) {
+    if (Array.isArray(enumCfg)) {
+        if (!enumCfg.includes(val))
+            err(`Filter "${field}": invalid value "${val}"`);
+        return;
+    }
+    if (typeof enumCfg === 'function' && !isSchemaFactoryLike(enumCfg)) {
+        await enumCfg(val);
+        return;
+    }
+    if (isSchemaFactoryLike(enumCfg)) {
+        const model = enumCfg;
+        const pk = model.primaryKey ?? 'id';
+        const row = await model().select(['1']).where({ [pk]: val }).first();
+        if (!row)
+            err(`Filter "${field}": value does not exist`);
+        return;
+    }
+    if (typeof enumCfg === 'object' && 'model' in enumCfg) {
+        const { model, field: enumField } = enumCfg;
+        const row = await model().select(['1']).where({ [enumField]: val }).first();
+        if (!row)
+            err(`Filter "${field}": value does not exist`);
+    }
+}

package/dist/helpers.d.ts

@@ -0,0 +1,36 @@
+import type { FilterFieldType, FilterFieldConfig, FilterOperator, FieldEntry, QueryHandlerOptions, ScopeHandler } from "./types";
+export declare const err: (msg: string, code?: number) => never;
+/** Синхронный или async массив → Promise<T[]> (для присваивания в handler.items). */
+export declare function resolveItems<T>(items: T[] | Promise<T[]>): Promise<T[]>;
+/** `?count=0` — выключить total; `?count=1` — явно включить. */
+export declare function resolveCountFromQuery(count: unknown): boolean | undefined;
+/** Подсчёт total: по умолчанию включён; отключается `withTotal: false` или `?count=0`. */
+export declare function resolveWithTotal(optionValue: boolean | undefined, globalCount: boolean, queryCount: unknown): boolean;
+/** COUNT при cursor: по умолчанию включён; `allowCount: false` или `?count=0` отключают. */
+export declare function resolveCursorAllowCount(cfg: {
+    allowCount?: boolean;
+}, queryCount: unknown): boolean;
+export declare function inferTypeByFieldName(name: string): FilterFieldType | undefined;
+export declare function resolveFieldType(cfg: FilterFieldConfig | undefined, fieldName: string): FilterFieldType | undefined;
+export declare function parseValue(raw: unknown, type: FilterFieldType | undefined, field: string, maxStringLen?: number): unknown;
+export declare function resolveAllowedOperators(limits: QueryHandlerOptions['limits'], fieldType: FilterFieldType | undefined): Set<FilterOperator>;
+export declare const sortDecode: (c: string) => [string, "ASC" | "DESC"];
+export declare const sortColumnName: (token: string) => string;
+export declare const isSortAllowed: (col: string, whitelist: string[]) => boolean;
+export declare function assertSafeColumnRef(raw: string, label: string): string;
+export declare function qualifyWhereColumn(column: string, baseRef?: string): string;
+export declare function qualifySelectField(column: string, baseRef?: string): string;
+/** Имя поля для проверки whitelist: строка, FieldMarker (.column) или `{alias: expr}`. */
+export declare function fieldEntryName(entry: FieldEntry): string;
+export declare function resolveFieldEntry(entry: FieldEntry, baseRef?: string): string;
+export declare function parsePositiveInt(raw: unknown, label: string): number | null;
+export declare function mergeOptions(base: QueryHandlerOptions, patch: Partial<QueryHandlerOptions>): QueryHandlerOptions;
+export declare function assertKnownOptionKeys(opts: object): void;
+export declare function isSchemaFactoryLike(x: unknown): boolean;
+export type QueryHandlerInstance = {
+    run(): Promise<Record<string, unknown>>;
+};
+export declare function isQueryHandler(value: unknown): value is QueryHandlerInstance;
+export declare function resolveNameList(clientParam: unknown, defaultParam?: string | string[] | ReadonlyArray<string>): string[];
+export declare function normalizeRelationMap(relations: QueryHandlerOptions['relations']): Map<string, import("./types").RelationConfig>;
+export declare function normalizeScopeMap(scopes: QueryHandlerOptions['scopes'] | undefined): Map<string, ScopeHandler>;

package/dist/helpers.js

@@ -0,0 +1,262 @@
+import { PARSERS, TYPE_BY_PATTERN, ALL_FILTER_OPERATORS, DEFAULT_OPERATOR_SETS, SIMPLE_ID_RE, ARRAY_MERGE_KEYS, OBJECT_MERGE_KEYS, KNOWN_OPTION_KEYS, QUERY_HANDLER_BRAND, } from "./constants";
+import { isFieldMarker } from "@crossfox/db/markers";
+import { error } from "@crossfox/db";
+import { toArray } from "./util";
+// ─────────────────────────────────────────────────────────────────────────────
+// Ошибки
+// ─────────────────────────────────────────────────────────────────────────────
+export const err = (msg, code = 422) => error(code, 'QueryHandler: ' + msg);
+/** Синхронный или async массив → Promise<T[]> (для присваивания в handler.items). */
+export function resolveItems(items) {
+    return Promise.resolve(items);
+}
+/** `?count=0` — выключить total; `?count=1` — явно включить. */
+export function resolveCountFromQuery(count) {
+    if (count === 0 || count === '0' || count === 'false' || count === false)
+        return false;
+    if (count === 1 || count === '1' || count === 'true' || count === true)
+        return true;
+    return undefined;
+}
+/** Подсчёт total: по умолчанию включён; отключается `withTotal: false` или `?count=0`. */
+export function resolveWithTotal(optionValue, globalCount, queryCount) {
+    return resolveCountFromQuery(queryCount) ?? optionValue ?? globalCount;
+}
+/** COUNT при cursor: по умолчанию включён; `allowCount: false` или `?count=0` отключают. */
+export function resolveCursorAllowCount(cfg, queryCount) {
+    // Приоритет: явный false в конфиге -> query параметр -> дефолтное true
+    if (cfg.allowCount === false)
+        return false;
+    return resolveCountFromQuery(queryCount) ?? true;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Типы фильтров
+// ─────────────────────────────────────────────────────────────────────────────
+export function inferTypeByFieldName(name) {
+    for (const [pattern, type] of TYPE_BY_PATTERN) {
+        if (pattern.test(name))
+            return type;
+    }
+    return undefined;
+}
+export function resolveFieldType(cfg, fieldName) {
+    if (!cfg || cfg === true || typeof cfg === 'function')
+        return inferTypeByFieldName(fieldName);
+    if (typeof cfg === 'string')
+        return cfg;
+    return cfg.type ?? inferTypeByFieldName(fieldName);
+}
+export function parseValue(raw, type, field, maxStringLen = 500) {
+    if (type === undefined)
+        return raw;
+    const str = String(raw);
+    if (type === 'string' && str.length > maxStringLen)
+        err(`Filter "${field}": value is too long (max ${maxStringLen} chars)`);
+    try {
+        return PARSERS[type](str, field);
+    }
+    catch (e) {
+        err(e.message);
+    }
+}
+export function resolveAllowedOperators(limits, fieldType) {
+    const custom = limits?.allowedOperators;
+    if (custom?.length)
+        return new Set(custom);
+    if (fieldType)
+        return DEFAULT_OPERATOR_SETS[fieldType];
+    return ALL_FILTER_OPERATORS;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Сортировка
+// ─────────────────────────────────────────────────────────────────────────────
+export const sortDecode = (c) => {
+    const isAsc = c.startsWith('!');
+    return [isAsc ? c.slice(1) : c, isAsc ? 'ASC' : 'DESC'];
+};
+export const sortColumnName = (token) => token.startsWith('!') ? token.slice(1) : token;
+export const isSortAllowed = (col, whitelist) => {
+    if (!whitelist.length)
+        return true;
+    const name = sortColumnName(col);
+    return whitelist.some(w => sortColumnName(w) === name);
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Колонки / SQL безопасность
+// ─────────────────────────────────────────────────────────────────────────────
+export function assertSafeColumnRef(raw, label) {
+    const s = raw.trim();
+    if (s === '*')
+        return '*';
+    const dot = s.indexOf('.');
+    if (dot === -1) {
+        if (!SIMPLE_ID_RE.test(s))
+            err(`${label}: invalid column "${raw}"`, 422);
+        return s;
+    }
+    if (dot !== s.lastIndexOf('.'))
+        err(`${label}: only alias.column allowed: "${raw}"`, 422);
+    const a = s.slice(0, dot), b = s.slice(dot + 1);
+    if (!SIMPLE_ID_RE.test(a) || !SIMPLE_ID_RE.test(b))
+        err(`${label}: invalid qualified column "${raw}"`, 422);
+    return s;
+}
+export function qualifyWhereColumn(column, baseRef) {
+    const safe = assertSafeColumnRef(column, 'Column');
+    if (!baseRef || safe === '*' || safe.includes('.'))
+        return safe;
+    return `${baseRef}.${safe}`;
+}
+export function qualifySelectField(column, baseRef) {
+    if (!baseRef)
+        return column;
+    if (column === '*' || !SIMPLE_ID_RE.test(column))
+        return column;
+    return `${baseRef}.${column}`;
+}
+/** Имя поля для проверки whitelist: строка, FieldMarker (.column) или `{alias: expr}`. */
+export function fieldEntryName(entry) {
+    if (typeof entry === 'string')
+        return entry;
+    if (isFieldMarker(entry))
+        return entry.column;
+    return Object.keys(entry)[0];
+}
+export function resolveFieldEntry(entry, baseRef) {
+    if (typeof entry === 'string')
+        return qualifySelectField(entry, baseRef);
+    // FieldMarker (model.field()/fields()) уже несёт алиас в toString → alias.column.
+    if (isFieldMarker(entry))
+        return String(entry);
+    const [alias, expr] = Object.entries(entry)[0];
+    return `${expr} AS ${alias}`;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Парсинг числа из query
+// ─────────────────────────────────────────────────────────────────────────────
+export function parsePositiveInt(raw, label) {
+    if (raw === undefined || raw === null || raw === '')
+        return null;
+    if (typeof raw === 'number') {
+        if (!Number.isFinite(raw) || !Number.isInteger(raw) || raw < 1)
+            err(`${label} must be a positive integer`);
+        return raw;
+    }
+    const s = String(raw).trim();
+    if (!/^\d+$/.test(s))
+        err(`${label} must be a positive integer`);
+    const n = Number(s);
+    if (n < 1)
+        err(`${label} must be a positive integer`);
+    return n;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Merge опций
+// ─────────────────────────────────────────────────────────────────────────────
+export function mergeOptions(base, patch) {
+    const result = { ...base };
+    for (const [key, val] of Object.entries(patch)) {
+        if (val === false && ARRAY_MERGE_KEYS.has(key)) {
+            result[key] = [];
+        }
+        else if (val === false && OBJECT_MERGE_KEYS.has(key)) {
+            result[key] = {};
+        }
+        else if (ARRAY_MERGE_KEYS.has(key) &&
+            Array.isArray(val) &&
+            Array.isArray(result[key])) {
+            result[key] = [...result[key], ...val];
+        }
+        else if (OBJECT_MERGE_KEYS.has(key) &&
+            val && typeof val === 'object' && !Array.isArray(val)) {
+            result[key] = { ...result[key], ...val };
+        }
+        else {
+            result[key] = val;
+        }
+    }
+    return result;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Валидация ключей опций
+// ─────────────────────────────────────────────────────────────────────────────
+export function assertKnownOptionKeys(opts) {
+    if (!opts || typeof opts !== 'object' || Array.isArray(opts))
+        return;
+    for (const key of Object.keys(opts)) {
+        if (key === 'model')
+            err('Передайте модель первым аргументом: queryHandler(model, query, options?)');
+        if (!KNOWN_OPTION_KEYS.has(key))
+            err(`Неизвестная опция: "${key}"`);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// SchemaFactory guard
+// ─────────────────────────────────────────────────────────────────────────────
+export function isSchemaFactoryLike(x) {
+    return typeof x === 'function' && 'table' in x;
+}
+export function isQueryHandler(value) {
+    return typeof value === 'object'
+        && value !== null
+        && QUERY_HANDLER_BRAND in value
+        && typeof value.run === 'function';
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Списки имён (relation / scope из query или *Default)
+// ─────────────────────────────────────────────────────────────────────────────
+export function resolveNameList(clientParam, defaultParam) {
+    const fromClient = toArray(clientParam)
+        // @ts-ignore
+        .flatMap((s) => String(s).split(','))
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (fromClient.length)
+        return fromClient;
+    if (!defaultParam)
+        return [];
+    return toArray(defaultParam)
+        // @ts-ignore
+        .flatMap((s) => String(s).split(','))
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Нормализация relation map
+// ─────────────────────────────────────────────────────────────────────────────
+export function normalizeRelationMap(relations) {
+    const out = new Map();
+    if (!relations)
+        return out;
+    if (Array.isArray(relations)) {
+        for (const name of relations) {
+            if (typeof name === 'string' && name)
+                out.set(name, { with: name });
+        }
+        return out;
+    }
+    for (const [name, cfg] of Object.entries(relations)) {
+        if (cfg !== false)
+            out.set(name, cfg);
+    }
+    return out;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Нормализация scope map
+// ─────────────────────────────────────────────────────────────────────────────
+export function normalizeScopeMap(scopes) {
+    const out = new Map();
+    if (!scopes)
+        return out;
+    for (const [name, cfg] of Object.entries(scopes)) {
+        if (cfg === false)
+            continue;
+        if (cfg === true) {
+            out.set(name, (q) => { q.scope(name); });
+        }
+        else {
+            out.set(name, cfg);
+        }
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { configureQueryHandler, getQueryHandlerGlobalConfig, getQueryHandlerDefaults, resetQueryHandlerConfig, type QueryHandlerConfigureInput, type QueryHandlerGlobalConfig } from "./config";
+import { queryHandlerWorker } from "./worker";
+import type { SchemaFactoryLike, QueryHandlerOptions, QueryHandlerCallOptions, QueryHandlerBuilderOptions, QueryHandlerQueryArg } from "./types";
+export { configureQueryHandler, getQueryHandlerGlobalConfig, getQueryHandlerDefaults, resetQueryHandlerConfig };
+export type { QueryHandlerConfigureInput, QueryHandlerGlobalConfig };
+export { purgeQueryHandlerCache, invalidateQueryHandlerCache } from "./cache";
+export { isQueryHandler } from "./helpers";
+export type { QueryHandlerInstance } from "./helpers";
+export { purgeRateLimitBuckets } from "./rateLimit";
+export { QUERY_HANDLER_BRAND } from "./constants";
+export type { SchemaFactoryLike, InferSchemaRow, QueryHandlerOptions, QueryHandlerCallOptions, QueryHandlerBuilderOptions, QueryHandlerQueryArg, QueryHandlerUrlQuery, QueryHandlerContext, WorkerOptions, FieldEntry, FilterFieldType, FilterFieldConfig, FilterFieldFullConfig, FilterOperator, FilterEnumConfig, FilterDefMap, RelationConfig, RelationMapInput, ExtendHooks, ScopeHandler, ScopeShorthand, ScopeDefMap, InferSchemaScopeNames, ApplyEntry, ApplyObject, ApplyFn, CursorPaginateConfig, ChunkConfig, ChunkMeta, RandomizeConfig, RateLimitConfig, QueryHandlerFilter, QueryHandlerFilterForced, QueryHandlerInitial, ForcedWhereMap, } from "./types";
+/**
+ * Рекомендуемый вызов: модель первым аргументом — TS выводит ключи строки.
+ *
+ * @example
+ * queryHandler(modelOrder, query, { filtersForced: { deleted_at: null } })
+ */
+export declare function queryHandler<M extends SchemaFactoryLike>(model: M, query: QueryHandlerQueryArg, options?: QueryHandlerCallOptions<M>): ReturnType<typeof queryHandlerWorker>;
+/** Готовый QueryBuilder вместо model */
+export declare function queryHandler(query: QueryHandlerQueryArg, options: QueryHandlerBuilderOptions): ReturnType<typeof queryHandlerWorker>;
+/**
+ * Фабрика с привязанной моделью — IDE стабильно выводит ключи строки.
+ *
+ * @example
+ * const qhOrder = queryHandlerFor(modelOrder)
+ * qhOrder(query, { filtersForced: { status: 'active' } })
+ */
+export declare function queryHandlerFor<M extends SchemaFactoryLike>(model: M): (query: QueryHandlerQueryArg, options?: QueryHandlerCallOptions<M>) => ReturnType<typeof queryHandlerWorker>;
+/**
+ * Создать инстанцию с фиксированными настройками.
+ * Приоритет: глобальный конфиг → инстанция → локальные опции.
+ *
+ * @example
+ * const adminQH = createQueryHandler({ maxLimit: 1000, strictFilters: false })
+ * adminQH(modelOrder, query, { filters: { status: 'string' } })
+ *
+ * const qhOrder = adminQH.for(modelOrder)
+ * qhOrder(query, options)
+ */
+export declare function createQueryHandler(instanceDefaults: Partial<QueryHandlerOptions>): {
+    <M extends SchemaFactoryLike>(model: M, query: QueryHandlerQueryArg, options?: QueryHandlerCallOptions<M>): ReturnType<typeof queryHandlerWorker>;
+    for<M extends SchemaFactoryLike>(model: M): (query: QueryHandlerQueryArg, options?: QueryHandlerCallOptions<M>) => import("./worker").QueryHandlerWorkerResult;
+};
+export default queryHandler;

package/dist/index.js

@@ -0,0 +1,66 @@
+import { configureQueryHandler, getQueryHandlerGlobalConfig, getQueryHandlerDefaults, resetQueryHandlerConfig, } from "./config";
+import { mergeOptions, assertKnownOptionKeys, isSchemaFactoryLike } from "./helpers";
+import { queryHandlerWorker } from "./worker";
+// ─────────────────────────────────────────────────────────────────────────────
+// Re-exports
+// ─────────────────────────────────────────────────────────────────────────────
+export { configureQueryHandler, getQueryHandlerGlobalConfig, getQueryHandlerDefaults, resetQueryHandlerConfig };
+export { purgeQueryHandlerCache, invalidateQueryHandlerCache } from "./cache";
+export { isQueryHandler } from "./helpers";
+export { purgeRateLimitBuckets } from "./rateLimit";
+export { QUERY_HANDLER_BRAND } from "./constants";
+export function queryHandler(arg1, arg2, arg3) {
+    if (arguments.length >= 3 && !isSchemaFactoryLike(arg1)) {
+        throw new Error("QueryHandler: при вызове с тремя аргументами первым должна быть фабрика модели (createSchema). " +
+            "Варианты: queryHandler(model, query, options?) или queryHandler(query, { query: builder, … }).");
+    }
+    if (isSchemaFactoryLike(arg1)) {
+        const opts = arg3 !== undefined && typeof arg3 === 'object' && arg3 !== null
+            ? { ...arg3 } : {};
+        assertKnownOptionKeys(opts);
+        return queryHandlerWorker(arg2, { ...opts, model: arg1 });
+    }
+    const opts = (arg2 ?? {});
+    assertKnownOptionKeys(opts);
+    return queryHandlerWorker(arg1, opts);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// queryHandlerFor — привязанная модель
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Фабрика с привязанной моделью — IDE стабильно выводит ключи строки.
+ *
+ * @example
+ * const qhOrder = queryHandlerFor(modelOrder)
+ * qhOrder(query, { filtersForced: { status: 'active' } })
+ */
+export function queryHandlerFor(model) {
+    return (query, options) => {
+        assertKnownOptionKeys(options ?? {});
+        return queryHandlerWorker(query, { ...options, model });
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// createQueryHandler — инстанция со своими дефолтами
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Создать инстанцию с фиксированными настройками.
+ * Приоритет: глобальный конфиг → инстанция → локальные опции.
+ *
+ * @example
+ * const adminQH = createQueryHandler({ maxLimit: 1000, strictFilters: false })
+ * adminQH(modelOrder, query, { filters: { status: 'string' } })
+ *
+ * const qhOrder = adminQH.for(modelOrder)
+ * qhOrder(query, options)
+ */
+export function createQueryHandler(instanceDefaults) {
+    function instanceHandler(model, query, options) {
+        const merged = mergeOptions(instanceDefaults, options ?? {});
+        assertKnownOptionKeys(merged);
+        return queryHandlerWorker(query, { ...merged, model });
+    }
+    instanceHandler.for = (model) => (query, options) => instanceHandler(model, query, options);
+    return instanceHandler;
+}
+export default queryHandler;