@crossfox/query-handler 0.1.0

package/LICENSE

@@ -0,0 +1,118 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both
+strict conditions and as covenants.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything
+you might do with the software that would otherwise infringe the licensor's
+copyright in it for any permitted purpose.  However, you may only distribute
+the software according to [Distribution License](#distribution-license) and
+make modifications or new works based on the software according to
+[Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies
+of the software.  Your license to distribute covers distributing the software
+with changes and new works permitted by
+[Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms or the URL for them above, as well as
+copies of any plain-text lines beginning with `Required Notice:` that the
+licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+Required Notice: Copyright Oleksii Fursov (https://crossfox.online)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make modifications
+and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent
+claims the licensor can license, or becomes able to license, that you infringe
+by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public
+knowledge, personal study, private entertainment, hobby projects, amateur
+pursuits, or religious observance, without any anticipated commercial
+application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research
+organization, public safety or health organization, environmental protection
+organization, or government institution is use for a permitted purpose.
+Use by a for-profit organization, or for-profit activity by a nonprofit
+organization, is not use for a permitted purpose.  The licensor may make an
+exception for a specific organization in writing.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do
+not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses
+to anyone else, or prevent the licensor from granting licenses to anyone else.
+These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to
+infringement of any patent, your patent license for the software granted under
+these terms ends immediately. If your company makes such a claim, your patent
+license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these
+terms, or done anything with the software that is not licensed, your license
+can nonetheless continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within 32 days of
+receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty
+or condition, and the licensor will not be liable to you for any damages
+arising out of these terms or the use or nature of the software, under any
+kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the
+**software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**Control** means ownership of substantially all the assets of an entity, or
+the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -0,0 +1,62 @@
+# @crossfox/query-handler
+
+HTTP list API layer on **[@crossfox/db](https://www.npmjs.com/package/@crossfox/db)**: filters, sort, search, relations (hasMany), cursor pagination, in-memory result cache, optional Elysia plugin.
+
+**Requires [Bun](https://bun.sh)** and peer `@crossfox/db`.
+
+[![npm version](https://img.shields.io/npm/v/@crossfox/query-handler.svg)](https://www.npmjs.com/package/@crossfox/query-handler)
+[![license](https://img.shields.io/npm/l/@crossfox/query-handler.svg)](#license)
+[![bun](https://img.shields.io/badge/runtime-Bun-fbf0df?logo=bun)](https://bun.sh)
+
+## Install
+
+```bash
+bun add @crossfox/query-handler @crossfox/db
+# optional Elysia adapter:
+bun add elysia
+```
+
+## Quick start
+
+```ts
+import { setupDb, mysqlFromEnv, createSchema } from "@crossfox/db";
+import { queryHandler, configureQueryHandler } from "@crossfox/query-handler";
+
+await setupDb({ mysql: mysqlFromEnv() });
+configureQueryHandler({ isDev: true, strictFilters: true });
+
+const User = createSchema<{ id: number; name: string; status: number }>("users", {
+  primaryKey: "id",
+});
+
+// In an Elysia handler — return the instance; plugin calls .run()
+return queryHandler(User, query, {
+  filters: { status: "number", name: "string" },
+  sort: ["id", "!name"],
+  maxLimit: 50,
+});
+```
+
+## Entry points
+
+| import | contents |
+|---|---|
+| `@crossfox/query-handler` | `queryHandler`, `createQueryHandler`, `configureQueryHandler`, cache helpers |
+| `@crossfox/query-handler/elysia` | `queryHandlerPlugin`, `typeQuerySchema` |
+| `@crossfox/query-handler/schema` | TypeBox query schema only |
+
+```ts
+import { Elysia } from "elysia";
+import { queryHandlerPlugin } from "@crossfox/query-handler/elysia";
+
+new Elysia().use(queryHandlerPlugin);
+```
+
+## License
+
+[PolyForm Noncommercial 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0) —
+free for non-commercial use; copyright notice required
+(`Required Notice: Copyright Oleksii Fursov`).
+
+**Commercial use** (for-profit products, SaaS, client work, etc.) needs a separate
+written license from the author: [nodepro777@gmail.com](mailto:nodepro777@gmail.com).

package/dist/cache.d.ts

@@ -0,0 +1,12 @@
+interface CacheEntry {
+    value: unknown[];
+    total: number;
+    expiresAt: number;
+}
+export declare function cacheGet(key: string): CacheEntry | null;
+export declare function cacheSet(key: string, value: unknown[], total: number, ttl: number): void;
+/** Очистить просроченные записи. Вызывайте периодически (например, раз в минуту). */
+export declare function purgeQueryHandlerCache(): number;
+/** Инвалидировать по ключу или RegExp. */
+export declare function invalidateQueryHandlerCache(keyOrPattern: string | RegExp): number;
+export {};

package/dist/cache.js

@@ -0,0 +1,43 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// In-memory кэш с TTL
+// ─────────────────────────────────────────────────────────────────────────────
+const _cache = new Map();
+export function cacheGet(key) {
+    const entry = _cache.get(key);
+    if (!entry)
+        return null;
+    if (entry.expiresAt <= Date.now()) {
+        _cache.delete(key);
+        return null;
+    }
+    return entry;
+}
+export function cacheSet(key, value, total, ttl) {
+    _cache.set(key, { value, total, expiresAt: Date.now() + ttl });
+}
+/** Очистить просроченные записи. Вызывайте периодически (например, раз в минуту). */
+export function purgeQueryHandlerCache() {
+    const now = Date.now();
+    let purged = 0;
+    for (const [k, v] of _cache) {
+        if (v.expiresAt <= now) {
+            _cache.delete(k);
+            purged++;
+        }
+    }
+    return purged;
+}
+/** Инвалидировать по ключу или RegExp. */
+export function invalidateQueryHandlerCache(keyOrPattern) {
+    let deleted = 0;
+    for (const k of _cache.keys()) {
+        const hit = typeof keyOrPattern === 'string'
+            ? k === keyOrPattern
+            : keyOrPattern.test(k);
+        if (hit) {
+            _cache.delete(k);
+            deleted++;
+        }
+    }
+    return deleted;
+}

package/dist/config.d.ts

@@ -0,0 +1,89 @@
+import type { QueryBuilder } from "@crossfox/db";
+import type { QueryHandlerHookCtx } from "./types";
+import type { RateLimitHitFn } from "./rateLimit";
+export type { QueryHandlerHookCtx };
+type BeforeQueryHook = (q: QueryBuilder, ctx: QueryHandlerHookCtx) => void | Promise<void>;
+type AfterQueryHook = (items: unknown[], total: number, ctx: QueryHandlerHookCtx) => void | Promise<void>;
+export interface QueryHandlerLogger {
+    info?(app: string, message: string, data?: unknown): void;
+    warn?(app: string, message: string, data?: unknown): void;
+}
+/** Глобальные настройки queryHandler (env, boot, configureQueryHandler). */
+export interface QueryHandlerGlobalConfig {
+    page?: number;
+    limit?: number;
+    count?: boolean;
+    maxLimit?: number;
+    strictFilters?: boolean;
+    ignoreQueryFields?: boolean;
+    /** Dev-режим: mock, предупреждения о фильтрах. */
+    isDev?: boolean;
+    /** Разрешить options.mock (обычно isDev || test). */
+    allowMock?: boolean;
+    logger?: QueryHandlerLogger;
+    /** Подмена rate-limit store (например Redis в кластере). */
+    rateLimitHit?: RateLimitHitFn;
+    limits?: {
+        searchMinLength?: number;
+        allowedOperators?: string[];
+    };
+    cursorPaginate?: boolean | string | {
+        field?: string;
+        count?: boolean;
+    };
+    initial?: {
+        page?: number;
+        limit?: number;
+        sort?: string | string[];
+        search?: string;
+        relation?: string | string[];
+        after?: number | string;
+        before?: number | string;
+        scope?: string | string[];
+        field?: readonly string[];
+        filter?: Record<string, unknown>;
+    };
+    beforeQuery?: BeforeQueryHook;
+    afterQuery?: AfterQueryHook;
+}
+/** Статические дефолты из env (QUERY_HANDLER_*). */
+export declare const queryHandlerStaticConfig: QueryHandlerGlobalConfig;
+export type QueryHandlerConfigureInput = Partial<QueryHandlerGlobalConfig> | ((current: Readonly<QueryHandlerGlobalConfig>) => Partial<QueryHandlerGlobalConfig>);
+export interface QueryHandlerResolvedDefaults {
+    queryMerge: {
+        page: number;
+        limit: number;
+        sort: string[];
+        search: string;
+        field: string[];
+        relation: string[];
+        scope: string;
+        after: number | string | undefined;
+        before: number | string | undefined;
+        filter: Record<string, unknown>;
+    };
+    runtime: {
+        count: boolean;
+        maxLimit: number;
+        strictFilters: boolean;
+        ignoreQueryFields: boolean;
+        isDev: boolean;
+        allowMock: boolean;
+        limits: NonNullable<QueryHandlerGlobalConfig["limits"]>;
+        cursorPaginate: QueryHandlerGlobalConfig["cursorPaginate"];
+        logger?: QueryHandlerLogger;
+        rateLimitHit: RateLimitHitFn;
+    };
+    initial: NonNullable<QueryHandlerGlobalConfig["initial"]>;
+    beforeQuery?: BeforeQueryHook;
+    afterQuery?: AfterQueryHook;
+}
+export declare function getQueryHandlerGlobalConfig(): Readonly<QueryHandlerGlobalConfig>;
+export declare function getQueryHandlerDefaults(): Readonly<QueryHandlerResolvedDefaults>;
+/**
+ * Глобальный конфигуратор queryHandler.
+ * Вызывайте при старте приложения или в тестах.
+ */
+export declare function configureQueryHandler(input: QueryHandlerConfigureInput): void;
+/** Сброс к значениям из env / {@link queryHandlerStaticConfig} (для тестов). */
+export declare function resetQueryHandlerConfig(): void;

package/dist/config.js

@@ -0,0 +1,114 @@
+import { envBool, envInt, readEnv } from "./env";
+import { fixedWindowHit } from "./rateLimit";
+/** Статические дефолты из env (QUERY_HANDLER_*). */
+export const queryHandlerStaticConfig = {
+    page: envInt(readEnv("QUERY_HANDLER_PAGE"), 1),
+    limit: envInt(readEnv("QUERY_HANDLER_LIMIT"), 10),
+    maxLimit: envInt(readEnv("QUERY_HANDLER_MAX_LIMIT"), 100),
+    count: envBool(readEnv("QUERY_HANDLER_COUNT"), true),
+    strictFilters: envBool(readEnv("QUERY_HANDLER_STRICT_FILTERS"), false),
+    ignoreQueryFields: envBool(readEnv("QUERY_HANDLER_IGNORE_QUERY_FIELD"), false),
+    isDev: readEnv("NODE_ENV") !== "production",
+    limits: {
+        searchMinLength: envInt(readEnv("QUERY_HANDLER_SEARCH_MIN_LENGTH"), 2),
+    },
+};
+const EMPTY_INITIAL = {};
+function readStaticConfig() {
+    const c = queryHandlerStaticConfig;
+    return {
+        page: c.page,
+        limit: c.limit,
+        count: c.count,
+        maxLimit: c.maxLimit,
+        strictFilters: c.strictFilters,
+        ignoreQueryFields: c.ignoreQueryFields,
+        isDev: c.isDev,
+        allowMock: c.allowMock,
+        logger: c.logger,
+        rateLimitHit: c.rateLimitHit,
+        limits: c.limits ? { ...c.limits } : undefined,
+        cursorPaginate: c.cursorPaginate,
+        initial: c.initial ? { ...c.initial } : undefined,
+    };
+}
+function buildResolved(from) {
+    const isDev = from.isDev ?? (readEnv("NODE_ENV") !== "production");
+    return {
+        queryMerge: {
+            page: from.page ?? 1,
+            limit: from.limit ?? 20,
+            sort: [],
+            search: "",
+            field: [],
+            relation: [],
+            scope: "",
+            after: undefined,
+            before: undefined,
+            filter: {},
+        },
+        runtime: {
+            count: from.count ?? true,
+            maxLimit: from.maxLimit ?? 100,
+            strictFilters: from.strictFilters ?? false,
+            ignoreQueryFields: from.ignoreQueryFields ?? false,
+            isDev,
+            allowMock: from.allowMock ?? isDev,
+            limits: { ...from.limits },
+            cursorPaginate: from.cursorPaginate,
+            logger: from.logger,
+            rateLimitHit: from.rateLimitHit ?? fixedWindowHit,
+        },
+        initial: from.initial ? { ...from.initial } : { ...EMPTY_INITIAL },
+        beforeQuery: from.beforeQuery,
+        afterQuery: from.afterQuery,
+    };
+}
+function toGlobalConfig(resolved) {
+    return {
+        page: resolved.queryMerge.page,
+        limit: resolved.queryMerge.limit,
+        count: resolved.runtime.count,
+        maxLimit: resolved.runtime.maxLimit,
+        strictFilters: resolved.runtime.strictFilters,
+        ignoreQueryFields: resolved.runtime.ignoreQueryFields,
+        isDev: resolved.runtime.isDev,
+        allowMock: resolved.runtime.allowMock,
+        logger: resolved.runtime.logger,
+        rateLimitHit: resolved.runtime.rateLimitHit,
+        limits: { ...resolved.runtime.limits },
+        cursorPaginate: resolved.runtime.cursorPaginate,
+        initial: { ...resolved.initial },
+        beforeQuery: resolved.beforeQuery,
+        afterQuery: resolved.afterQuery,
+    };
+}
+function mergeGlobalConfig(base, patch) {
+    return {
+        ...base,
+        ...patch,
+        limits: patch.limits !== undefined ? { ...base.limits, ...patch.limits } : base.limits,
+        initial: patch.initial !== undefined ? { ...base.initial, ...patch.initial } : base.initial,
+        beforeQuery: patch.beforeQuery !== undefined ? patch.beforeQuery : base.beforeQuery,
+        afterQuery: patch.afterQuery !== undefined ? patch.afterQuery : base.afterQuery,
+    };
+}
+let resolvedDefaults = buildResolved(readStaticConfig());
+export function getQueryHandlerGlobalConfig() {
+    return toGlobalConfig(resolvedDefaults);
+}
+export function getQueryHandlerDefaults() {
+    return resolvedDefaults;
+}
+/**
+ * Глобальный конфигуратор queryHandler.
+ * Вызывайте при старте приложения или в тестах.
+ */
+export function configureQueryHandler(input) {
+    const patch = typeof input === "function" ? input(getQueryHandlerGlobalConfig()) : input;
+    resolvedDefaults = buildResolved(mergeGlobalConfig(getQueryHandlerGlobalConfig(), patch));
+}
+/** Сброс к значениям из env / {@link queryHandlerStaticConfig} (для тестов). */
+export function resetQueryHandlerConfig() {
+    resolvedDefaults = buildResolved(readStaticConfig());
+}

package/dist/constants.d.ts

@@ -0,0 +1,14 @@
+import type { FilterFieldType, FilterOperator } from "./types";
+export declare const ALL_FILTER_OPERATORS: Set<FilterOperator>;
+export declare const DEFAULT_OPERATORS_BY_TYPE: Record<FilterFieldType, FilterOperator[]>;
+export declare const DEFAULT_OPERATOR_SETS: Record<FilterFieldType, Set<FilterOperator>>;
+export declare const TYPE_BY_PATTERN: Array<[RegExp, FilterFieldType]>;
+export declare const PARSERS: Record<FilterFieldType, (v: string, field: string) => unknown>;
+export declare const DANGEROUS_KEYS: Set<string>;
+export declare const SIMPLE_ID_RE: RegExp;
+export declare const CUSTOM_SORT_RE: RegExp;
+export declare const KNOWN_OPTION_KEYS: Set<string>;
+export declare const ARRAY_MERGE_KEYS: Set<string>;
+export declare const OBJECT_MERGE_KEYS: Set<string>;
+/** Маркер экземпляра queryHandler (Elysia onAfterHandle, type guard). */
+export declare const QUERY_HANDLER_BRAND: unique symbol;

package/dist/constants.js

@@ -0,0 +1,108 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// Операторы
+// ─────────────────────────────────────────────────────────────────────────────
+export const ALL_FILTER_OPERATORS = new Set([
+    'between', 'in', 'nin', 'like', 'nlike',
+    'gt', 'lt', 'lte', 'gte', 'eq', 'neq', 'null', 'nnull',
+]);
+export const DEFAULT_OPERATORS_BY_TYPE = {
+    string: ['eq', 'neq', 'like', 'nlike', 'in', 'nin', 'null', 'nnull'],
+    number: ['eq', 'neq', 'gt', 'lt', 'gte', 'lte', 'between', 'in', 'nin', 'null', 'nnull'],
+    date: ['eq', 'neq', 'gt', 'lt', 'gte', 'lte', 'between', 'null', 'nnull'],
+    boolean: ['eq'],
+};
+export const DEFAULT_OPERATOR_SETS = {
+    string: new Set(DEFAULT_OPERATORS_BY_TYPE.string),
+    number: new Set(DEFAULT_OPERATORS_BY_TYPE.number),
+    date: new Set(DEFAULT_OPERATORS_BY_TYPE.date),
+    boolean: new Set(DEFAULT_OPERATORS_BY_TYPE.boolean),
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Автоопределение типа по имени поля
+// ─────────────────────────────────────────────────────────────────────────────
+export const TYPE_BY_PATTERN = [
+    [/_id$/, 'number'],
+    [/^id$/, 'number'],
+    [/_at$/, 'date'],
+    [/_date$/, 'date'],
+    [/uuid/, 'string'],
+    [/slug/, 'string'],
+    [/^is_/, 'boolean'],
+    [/^has_/, 'boolean'],
+    [/_count$/, 'number'],
+    [/_price$/, 'number'],
+    [/_amount$/, 'number'],
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// Парсеры значений из URL
+// ─────────────────────────────────────────────────────────────────────────────
+export const PARSERS = {
+    number: (v, field) => {
+        const n = Number(v);
+        if (!isFinite(n))
+            throw new Error(`Filter "${field}": expected a number, got "${v}"`);
+        return n;
+    },
+    date: (v, field) => {
+        if (!/^\d{4}-\d{2}-\d{2}(T[\d:.Z+-]+)?$/.test(v))
+            throw new Error(`Filter "${field}": expected date YYYY-MM-DD, got "${v}"`);
+        if (isNaN(new Date(v).getTime()))
+            throw new Error(`Filter "${field}": invalid date "${v}"`);
+        return v;
+    },
+    string: (v, field) => {
+        if (v.length > 500)
+            throw new Error(`Filter "${field}": value is too long (max 500 chars)`);
+        return v;
+    },
+    boolean: (v, field) => {
+        if (v === '1')
+            return true;
+        if (v === '0')
+            return false;
+        throw new Error(`Filter "${field}": expected 1 or 0, got "${v}"`);
+    },
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Безопасность
+// ─────────────────────────────────────────────────────────────────────────────
+export const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+// ─────────────────────────────────────────────────────────────────────────────
+// RegExp
+// ─────────────────────────────────────────────────────────────────────────────
+export const SIMPLE_ID_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const CUSTOM_SORT_RE = /^!?\$/;
+// ─────────────────────────────────────────────────────────────────────────────
+// Известные ключи опций (для валидации)
+// ─────────────────────────────────────────────────────────────────────────────
+export const KNOWN_OPTION_KEYS = new Set([
+    'query', 'apply',
+    'fields', 'fieldsDefault', 'fieldsForced',
+    'sorts', 'sortsDefault', 'sortsCustom',
+    'search',
+    'filters', 'filtersDefault', 'filtersRequired', 'filtersForced', 'requiredFilters', 'strictFilters',
+    'relations', 'relationsDefault',
+    'cursorPaginate', 'withTotal', 'maxLimit',
+    'scopes', 'scopesDefault', 'extends',
+    'before', 'beforeQuery', 'after', 'afterQuery', 'afterEach',
+    'transform', 'fieldsTransform', 'ignoreQueryFields',
+    'aggregate', 'groupBy', 'having',
+    'distinct', 'mode', 'transaction', 'onEmpty', 'versions', 'chunk', 'randomize', 'rateLimit',
+    'cacheTtl', 'cacheKey',
+    'meta', 'mock',
+    'initial', 'limits', 'expose',
+]);
+// ─────────────────────────────────────────────────────────────────────────────
+// Merge — ключи по стратегии
+// ─────────────────────────────────────────────────────────────────────────────
+export const ARRAY_MERGE_KEYS = new Set([
+    'fields', 'fieldsForced', 'fieldsDefault', 'sorts', 'groupBy',
+    'relationsDefault', 'scopesDefault',
+]);
+export const OBJECT_MERGE_KEYS = new Set([
+    'filters', 'filtersDefault', 'filtersRequired', 'filtersForced',
+    'scopes', 'extends', 'sortsCustom', 'fieldsTransform',
+    'aggregate', 'having', 'expose', 'versions', 'limits', 'relations',
+]);
+/** Маркер экземпляра queryHandler (Elysia onAfterHandle, type guard). */
+export const QUERY_HANDLER_BRAND = Symbol.for("@crossfox/query-handler");

package/dist/cursor.d.ts

@@ -0,0 +1,9 @@
+import type { QueryBuilder } from "@crossfox/db";
+import type { CursorPaginateConfig } from "./types";
+export interface CursorResult {
+    items: unknown[];
+    total: number;
+    nextId: unknown;
+    prevId: unknown;
+}
+export declare function runCursor(q: QueryBuilder, after: unknown, before: unknown, limit: number, field: string, cfg: CursorPaginateConfig, displayDir?: 'ASC' | 'DESC'): Promise<CursorResult>;

package/dist/cursor.js

@@ -0,0 +1,37 @@
+export async function runCursor(q, after, before, limit, field, cfg, displayDir = 'DESC') {
+    let isReversed = false;
+    if (after !== undefined) {
+        q.where({ [field]: { gt: after } }).order(field, 'ASC');
+        if (displayDir === 'DESC')
+            isReversed = true;
+    }
+    else if (before !== undefined) {
+        q.where({ [field]: { lt: before } }).order(field, 'DESC');
+        if (displayDir === 'ASC')
+            isReversed = true;
+    }
+    else {
+        q.order(field, displayDir);
+    }
+    // COUNT клонируется до LIMIT, учитывает GROUP BY
+    const countClone = cfg.allowCount
+        ? q.clone({ from: true, where: true, join: true, groupBy: true })
+        : null;
+    const [rows, total] = await Promise.all([
+        q.limit(limit + 1).run(),
+        countClone
+            ? countClone.count()
+            : Promise.resolve(-2),
+    ]);
+    const hasMore = rows.length > limit;
+    if (hasMore)
+        rows.pop();
+    if (isReversed)
+        rows.reverse();
+    return {
+        items: rows,
+        total: total,
+        nextId: hasMore ? (rows[rows.length - 1]?.[field] ?? null) : null,
+        prevId: before !== undefined ? (rows[0]?.[field] ?? null) : null,
+    };
+}

package/dist/elysia.d.ts

@@ -0,0 +1,33 @@
+import { Elysia } from "elysia";
+/** Если хендлер вернул экземпляр queryHandler — выполняется `run()`. */
+export declare const queryHandlerPlugin: Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {
+        200: Record<string, unknown>;
+    };
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;
+export { typeQuerySchema, queryTypeQuerySchema } from "./schema";

package/dist/elysia.js

@@ -0,0 +1,9 @@
+import { Elysia } from "elysia";
+import { isQueryHandler } from "./helpers";
+/** Если хендлер вернул экземпляр queryHandler — выполняется `run()`. */
+export const queryHandlerPlugin = new Elysia({ name: "crossfox-query-handler" })
+    .onAfterHandle({ as: "global" }, async ({ response }) => {
+    if (isQueryHandler(response))
+        return response.run();
+});
+export { typeQuerySchema, queryTypeQuerySchema } from "./schema";

package/dist/env.d.ts

@@ -0,0 +1,4 @@
+/** Чтение env без зависимости от app config. */
+export declare function envInt(raw: string | undefined, fallback: number): number;
+export declare function envBool(raw: string | undefined, fallback: boolean): boolean;
+export declare function readEnv(key: string): string | undefined;