@quark-fw/entity 0.0.1

package/dist/client.d.ts

@@ -0,0 +1,153 @@
+import { ReactNode } from "react";
+import type { Serialize } from "@quark-fw/store/src/serialize.js";
+import { useEntityForm } from "./useEntityForm.js";
+export type EntitiesListParams = {
+    /**
+     * Фильтр КОНКРЕТНОГО потребителя (например колонки доски). Применяется
+     * на клиенте к общему списку провайдера: состояние одно на провайдер,
+     * поэтому серверный запрос задаётся пропсами провайдера (filter/sort/limit),
+     * а здесь получается срез этого списка.
+     */
+    filter?: Record<string, unknown>;
+};
+/** аргументы серверного list: то, что уходит в процедуру сущности */
+export type EntityListArgs = {
+    where?: Record<string, unknown>;
+    sort?: {
+        field: string;
+        dir?: "asc" | "desc";
+    };
+    limit?: number;
+    page?: number;
+    /** поиск по подстроке; работает, если у сущности задан searchField */
+    search?: string;
+};
+/**
+ * tiny-вызовы КОНКРЕТНОЙ сущности.
+ *
+ * Имя сущности известно только в рантайме (createEntityContext("project")),
+ * поэтому вывести его из роутера нельзя — но набор процедур у всех сущностей
+ * один и тот же, и он описан здесь.
+ */
+export type EntityTinyCaller<Row> = {
+    list: {
+        mutate(args: EntityListArgs): Row[];
+        setCache(args: EntityListArgs): (rows: Row[]) => void;
+    };
+    count: {
+        mutate(args: {
+            where?: Record<string, unknown>;
+        }): number;
+    };
+    getById: {
+        mutate(id: string): Row | null;
+    };
+};
+/** те же процедуры, но сетевые (не через кэш стора) */
+export type EntityTrpcCaller<Row> = {
+    list: {
+        mutate(args: EntityListArgs): Promise<Row[]>;
+    };
+    create: {
+        mutate(args: {
+            data: Record<string, unknown>;
+        }): Promise<Row>;
+    };
+    update: {
+        mutate(args: {
+            id: string;
+            data: Record<string, unknown>;
+        }): Promise<Row>;
+    };
+    delete: {
+        mutate(args: {
+            id: string;
+        }): Promise<unknown>;
+    };
+    controller: {
+        mutate(args: {
+            id: string;
+            method: string;
+            data?: unknown;
+        }): Promise<unknown>;
+    };
+};
+export type EntitiesContextType<Row extends {
+    id: string;
+}> = {
+    list: (params?: EntitiesListParams) => [
+        Row[],
+        {
+            page: number;
+            setPage: (page: number) => void;
+            count: number | null;
+        }
+    ];
+    tiny: EntityTinyCaller<Row>;
+    /**
+     * Сахар над useEntityForm: форма, создающая запись в этой сущности.
+     *
+     * Форма значений выводится из defaultValues, поэтому `form.values.name`
+     * у потребителя — строка, а не `any`.
+     */
+    forms: {
+        create: <Shape extends Record<string, unknown>>(args?: {
+            defaultValues?: Partial<Shape>;
+            /** доработать значения перед отправкой (подставить projectId и т.п.) */
+            transformSubmitValues?: (values: Shape) => Record<string, unknown>;
+            onSuccess?: (row: Row | null) => void;
+        }) => ReturnType<typeof useEntityForm<Shape>>;
+    };
+    create: (data: Record<string, unknown>) => Promise<Row | null>;
+    update: (id: string, data: Partial<Row>, options?: {
+        clientOnly?: boolean;
+    }) => Promise<void>;
+    deleteById: (id: string) => Promise<void>;
+    /**
+     * Принять запись в локальный список без обращения к серверу.
+     *
+     * Нужна, когда рядом живут несколько провайдеров одной сущности с разными
+     * серверными фильтрами — например колонки доски. Запись, уехавшая из
+     * одного фильтра в другой, для второго провайдера просто не существует:
+     * его запрос уже выполнен. Сохранение делает вызывающий, здесь только
+     * локальное состояние.
+     */
+    adopt: (row: Row) => void;
+    /**
+     * Подгрузить следующую страницу и ДОБАВИТЬ её к списку.
+     *
+     * Обычная смена страницы список заменяет; здесь он копится — это нужно
+     * для догрузки по прокрутке. Возвращает, сколько записей приехало: ноль
+     * означает, что дальше ничего нет.
+     */
+    loadMore: () => Promise<number>;
+    /** сколько записей всего по серверному фильтру провайдера */
+    total: number | null;
+};
+export type EntityContextType<Row extends {
+    id: string;
+}> = {
+    instance: () => Row;
+    update: (data: Partial<Row>) => Promise<void>;
+    delete: () => Promise<void>;
+    controller: Record<string, (data?: unknown) => Promise<unknown>>;
+};
+export declare function createEntityContext<TRow extends {
+    id: string;
+}>(entityKey: string): readonly [({ children, filter, limit, sort, }: {
+    children: ReactNode;
+    /** серверный фильтр списка (общий для всех потребителей) */
+    filter?: Record<string, unknown>;
+    limit?: number;
+    sort?: {
+        field: string;
+        dir?: "asc" | "desc";
+    };
+}) => import("react/jsx-runtime").JSX.Element, ({ children, id, }: {
+    children: ReactNode;
+    id: string;
+}) => import("react/jsx-runtime").JSX.Element, () => EntitiesContextType<Serialize<TRow> & {
+    id: string;
+}>, () => EntityContextType<Serialize<TRow> & {
+    id: string;
+}>];

package/dist/client.js

@@ -0,0 +1,295 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/* eslint-disable react-hooks/rules-of-hooks */
+// Порт createEntityContext из druslee/ugliest под quark:
+// пара React-контекстов на entity с оптимистичным состоянием и откатом.
+// ВАЖНО: клиентский модуль — не импортировать серверный ./index.js.
+import { createContext, startTransition, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { useStore, useTrpc } from "@quark-fw/store";
+import { reportError } from "@quark-fw/store/src/errors.js";
+import { useEntityForm } from "./useEntityForm.js";
+import { uuidv7 } from "./uuidv7.js";
+/** Условия, которые можно проверить на клиенте (простые равенства). */
+const matchesEverything = (where) => Object.keys(where).length === 0;
+const matchesWhere = (row, where) => Object.entries(where).every(([field, expected]) => {
+    // операторы вида { in: [...] } на клиенте не разбираем — доверяем серверу
+    if (expected && typeof expected === "object")
+        return true;
+    return row?.[field] === expected;
+});
+function useSafeContext(errorMessage, Ctx) {
+    return () => {
+        const ctx = useContext(Ctx);
+        if (ctx === null)
+            throw new Error(errorMessage);
+        return ctx;
+    };
+}
+export function createEntityContext(entityKey) {
+    const EntitiesContext = createContext(null);
+    const EntityContext = createContext(null);
+    const useEntities = useSafeContext(`${entityKey} entities context was not found in tree`, EntitiesContext);
+    const useEntity = useSafeContext(`${entityKey} entity context was not found in tree`, EntityContext);
+    const EntitiesProvider = ({ children, filter, limit = 100, sort, }) => {
+        const store = useStore();
+        // Имя сущности приходит параметром, поэтому ветку роутера нельзя
+        // вывести статически — но набор процедур у всех сущностей общий и
+        // описан типами выше.
+        const tinyCaller = store.tiny.entity[entityKey];
+        const trpcCaller = useTrpc().entity[entityKey];
+        const [completeList, setCompleteList] = useState(null);
+        const [page, setPage] = useState(1);
+        // Сколько мутаций сейчас в полёте. Пока хоть одна не завершилась,
+        // синхронизация из серверного списка запрещена: иначе первый же
+        // эффект после монтирования затирает оптимистичное изменение,
+        // сделанное до его выполнения (гонка «создал сразу после загрузки»).
+        const mutationsInFlight = useRef(0);
+        // Наборы аргументов, с которыми список сейчас читают компоненты.
+        // Кэш store обновляем именно по ним — иначе setCache пишет под
+        // ключом, который никто не читает, и после ремонта виден старый список.
+        const liveArgs = useRef(new Map());
+        const setList = (updater) => {
+            const syncCache = (arr) => {
+                for (const args of liveArgs.current.values()) {
+                    tinyCaller.list.setCache(args)(arr);
+                }
+            };
+            if (Array.isArray(updater)) {
+                setCompleteList(updater);
+                syncCache(updater);
+            }
+            else {
+                setCompleteList((prev) => {
+                    const arr = updater(prev);
+                    // побочный эффект вынесен из апдейтера состояния
+                    queueMicrotask(() => syncCache(arr));
+                    return arr;
+                });
+            }
+        };
+        /** Помечает мутацию как выполняющуюся, чтобы её не затёрли данными. */
+        const withMutation = async (fn) => {
+            mutationsInFlight.current += 1;
+            try {
+                return await fn();
+            }
+            finally {
+                mutationsInFlight.current -= 1;
+            }
+        };
+        // при ошибке откатывает список и сообщает через reportError,
+        // возвращая null — вызывающему коду не нужен try/catch
+        const create = async (data) => {
+            const now = new Date().toISOString();
+            // клиентский UUIDv7 = финальный id записи
+            const item = {
+                id: uuidv7(),
+                createdAt: now,
+                ...data,
+            };
+            const old = completeList;
+            setList((prev) => (prev ? [...prev, item] : [item]));
+            return withMutation(async () => {
+                try {
+                    return await trpcCaller.create.mutate({ data: item });
+                }
+                catch (error) {
+                    reportError(error, entityKey);
+                    setList(old ?? []);
+                    return null;
+                }
+            });
+        };
+        const update = async (id, data, { clientOnly } = {}) => {
+            const old = (completeList ?? []).find((e) => e.id === id);
+            setList((prev) => {
+                const arr = prev ? [...prev] : [];
+                const index = arr.findIndex((e) => e.id === id);
+                if (index === -1)
+                    return arr;
+                arr[index] = { ...arr[index], ...data };
+                return arr;
+            });
+            await withMutation(async () => {
+                try {
+                    if (!clientOnly) {
+                        await trpcCaller.update.mutate({ id, data });
+                    }
+                }
+                catch (error) {
+                    reportError(error, entityKey);
+                    setList((prev) => {
+                        if (!prev || !old)
+                            return prev ?? [];
+                        const arr = [...prev];
+                        const index = arr.findIndex((e) => e.id === id);
+                        if (index !== -1)
+                            arr[index] = old;
+                        return arr;
+                    });
+                }
+            });
+        };
+        const deleteById = async (id) => {
+            const old = completeList;
+            setList((prev) => (prev ?? []).filter((e) => e.id !== id));
+            await withMutation(async () => {
+                try {
+                    await trpcCaller.delete.mutate({ id });
+                }
+                catch (error) {
+                    reportError(error, entityKey);
+                    setList(old ?? []);
+                }
+            });
+        };
+        // Сколько страниц уже добавлено в список. Пока страница одна,
+        // провайдер синхронизируется с сервером как обычно; после догрузки
+        // синхронизация выключается — иначе первая страница затрёт накопленное.
+        const loadedPages = useRef(1);
+        /**
+         * Принять запись, приехавшую из другого провайдера этой же сущности.
+         *
+         * Только локальное состояние: запись уже сохранена тем, кто её
+         * передал. Если запись с таким id уже есть — обновляем на месте.
+         */
+        const adopt = (row) => {
+            setList((prev) => {
+                const arr = prev ? [...prev] : [];
+                const index = arr.findIndex((e) => e.id === row.id);
+                if (index === -1)
+                    arr.push(row);
+                else
+                    arr[index] = row;
+                return arr;
+            });
+        };
+        // ЕДИНСТВЕННЫЙ серверный запрос списка на провайдер: состояние тоже
+        // одно, поэтому несколько разных запросов рассинхронизировали бы его
+        // (колонка, синхронизировавшаяся последней, затирала бы остальные).
+        const argsKey = JSON.stringify({
+            ...(filter ? { where: filter } : {}),
+            ...(sort ? { sort } : {}),
+            limit,
+            page,
+        });
+        // объект аргументов должен сохранять идентичность, пока не изменился
+        // их состав: иначе эффект ниже перезапускается на каждый рендер
+        const serverArgs = useMemo(() => JSON.parse(argsKey), [argsKey]);
+        const fresh = tinyCaller.list.mutate(serverArgs);
+        const count = tinyCaller.count.mutate(filter ? { where: filter } : {});
+        const loadMore = async () => {
+            const nextPage = loadedPages.current + 1;
+            const rows = await withMutation(() => trpcCaller.list.mutate({ ...serverArgs, page: nextPage }));
+            if (!rows.length)
+                return 0;
+            loadedPages.current = nextPage;
+            setList((prev) => {
+                const seen = new Set((prev ?? []).map((row) => row.id));
+                return [
+                    ...(prev ?? []),
+                    ...rows.filter((row) => !seen.has(row.id)),
+                ];
+            });
+            return rows.length;
+        };
+        // мутации обновляют кэш store по тем же аргументам, что и чтение
+        useEffect(() => {
+            // ref читаем до подписки: к моменту очистки .current уже может
+            // указывать на другой объект
+            const live = liveArgs.current;
+            live.set(argsKey, serverArgs);
+            return () => {
+                live.delete(argsKey);
+            };
+        }, [argsKey, serverArgs]);
+        // с этой порцией серверных данных мы уже синхронизировались
+        const syncedFrom = useRef(null);
+        useEffect(() => {
+            if (syncedFrom.current === fresh)
+                return;
+            // мутация в полёте — локальное состояние новее серверного
+            if (mutationsInFlight.current > 0)
+                return;
+            // подгруженные страницы: первая страница затёрла бы остальные
+            if (loadedPages.current > 1)
+                return;
+            syncedFrom.current = fresh;
+            startTransition(() => {
+                setList(fresh);
+            });
+            // setList намеренно не в зависимостях: он пересоздаётся каждый
+            // рендер, а сам пишет состояние — с ним эффект зациклится
+            // eslint-disable-next-line react-hooks/exhaustive-deps
+        }, [fresh]);
+        const rows = completeList ?? fresh;
+        const value = {
+            list: ({ filter: extraFilter } = {}) => [
+                // срез общего списка под фильтр потребителя
+                !extraFilter || matchesEverything(extraFilter)
+                    ? rows
+                    : rows.filter((row) => matchesWhere(row, extraFilter)),
+                { page, setPage, count: count ?? null },
+            ],
+            tiny: tinyCaller,
+            forms: {
+                // хук вызывается из компонента (как list выше) — порядок
+                // вызовов стабилен, пока компонент вызывает forms.create()
+                // безусловно в теле рендера
+                create: ({ defaultValues, transformSubmitValues, onSuccess, } = {}) => useEntityForm({
+                    defaultValues,
+                    onSubmit: async (values) => {
+                        const data = transformSubmitValues
+                            ? transformSubmitValues(values)
+                            : values;
+                        const row = await create(data);
+                        onSuccess?.(row);
+                    },
+                }),
+            },
+            create,
+            update,
+            deleteById,
+            adopt,
+            loadMore,
+            total: count ?? null,
+        };
+        return (_jsx(EntitiesContext.Provider, { value: value, children: children }));
+    };
+    const EntityProvider = ({ children, id, }) => {
+        if (!id)
+            throw new Error(`EntityProvider [${entityKey}] id must be provided`);
+        const store = useStore();
+        // Имя сущности приходит параметром, поэтому ветку роутера нельзя
+        // вывести статически — но набор процедур у всех сущностей общий и
+        // описан типами выше.
+        const tinyCaller = store.tiny.entity[entityKey];
+        const trpcCaller = useTrpc().entity[entityKey];
+        const entities = useEntities();
+        const controller = new Proxy({}, {
+            get(_target, method) {
+                return (data) => trpcCaller.controller.mutate({
+                    id,
+                    // ключ прокси может быть символом, а по сети уходит
+                    // имя метода — берём только строковые
+                    method: String(method),
+                    data,
+                });
+            },
+        });
+        const value = {
+            instance: () => {
+                const [list] = entities.list();
+                const item = list.find((e) => e.id === id) ??
+                    tinyCaller.getById.mutate(id);
+                if (!item)
+                    throw new Error(`${entityKey} ${id} not found`);
+                return item;
+            },
+            update: (data) => entities.update(id, data),
+            delete: () => entities.deleteById(id),
+            controller,
+        };
+        return (_jsx(EntityContext.Provider, { value: value, children: children }));
+    };
+    return [EntitiesProvider, EntityProvider, useEntities, useEntity];
+}

package/dist/global.d.ts

@@ -0,0 +1,3 @@
+import "@quark-fw/core/src/global.js";
+
+export {};

package/dist/index.d.ts

@@ -0,0 +1,216 @@
+import { z, ZodType } from "zod";
+import { publicProcedure, type TRPCContext } from "@quark-fw/plugin-trpc/src/trpc.js";
+import type { EntityField, EntityModelName, EntityRow } from "./types.js";
+export type { EntityModels, EntityModelName, EntityRow, EntityField, } from "./types.js";
+export type CustomMethodFn = (input?: unknown) => unknown;
+export type CustomMethodValidated<TSchema extends ZodType = ZodType> = {
+    input: TSchema;
+    handler: (input: z.output<TSchema>) => unknown;
+};
+export type CustomMethod = CustomMethodFn | CustomMethodValidated;
+/**
+ * Одно поле модели в селекторах Prisma 8: `f.name.asc()`, `f.name.ilike(...)`.
+ * Набор операторов зависит от типа колонки, поэтому проверяется в рантайме.
+ */
+type FieldHandle = {
+    [operator: string]: ((...args: string[]) => unknown) | undefined;
+};
+/**
+ * Поля модели в селекторе: `(f) => f.name.asc()`. Конкретный состав известен
+ * только сгенерированному контракту приложения, здесь — структура.
+ */
+type SelectorFields = Record<string, FieldHandle | undefined>;
+/** хелперы агрегатов Prisma 8: `(a) => ({ n: a.count() })` */
+type AggregateHelpers = Record<string, () => unknown>;
+export type EntityModelHandle = {
+    where(where: Record<string, unknown>): EntityModelHandle;
+    where(selector: (fields: SelectorFields) => unknown): EntityModelHandle;
+    skip(n: number): EntityModelHandle;
+    take(n: number): EntityModelHandle;
+    all(): Promise<unknown[]>;
+    first(): Promise<unknown | null>;
+    orderBy(selector: (fields: SelectorFields) => unknown): EntityModelHandle;
+    aggregate(selector: (a: AggregateHelpers) => unknown): Promise<unknown>;
+    create(data: unknown): Promise<unknown>;
+    update(data: unknown): Promise<unknown>;
+    delete(): Promise<unknown>;
+};
+export declare const sortSchema: z.ZodObject<{
+    field: z.ZodString;
+    dir: z.ZodDefault<z.ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+}, z.core.$strip>;
+export type EntitySort = z.output<typeof sortSchema>;
+declare const listSchema: z.ZodObject<{
+    where: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    page: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    sort: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+        dir: z.ZodDefault<z.ZodEnum<{
+            asc: "asc";
+            desc: "desc";
+        }>>;
+    }, z.core.$strip>>;
+    search: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Билдер, на котором строится роутер сущности.
+ *
+ * userProcedure — это publicProcedure.use(...), то есть тот же билдер с
+ * доуточнённым контекстом; в самих процедурах сущности контекст читается
+ * только как `ctx.user?.id`, который есть и в базовом TRPCContext.
+ */
+export type EntityProcedure = typeof publicProcedure;
+/**
+ * Связь с родительской моделью.
+ *
+ * Тип раздаётся по всем моделям контракта, поэтому поля родителя
+ * (parentField, authField) проверяются против ИМЕННО той модели, которая
+ * указана в model.
+ */
+export type EntityRelation<TModel extends string = EntityModelName> = {
+    [TParent in EntityModelName]: {
+        /** колонка-ссылка на этой модели, например "projectId" */
+        field: EntityField<TModel>;
+        /** родительская модель в контракте, например "Project" */
+        model: TParent;
+        /** колонка родителя, с которой сопоставляется ссылка (по умолчанию id) */
+        parentField?: EntityField<TParent>;
+        /** колонка владельца на родителе, например "userId" */
+        authField: EntityField<TParent>;
+    };
+}[EntityModelName];
+export type CreateEntityArgs<TModel extends EntityModelName> = {
+    model: TModel;
+    authField?: EntityField<TModel>;
+    procedure?: EntityProcedure;
+    defaultSort?: {
+        field: EntityField<TModel>;
+        dir?: EntitySort["dir"];
+    };
+    /**
+     * Поле для поиска по подстроке в list({ search }).
+     *
+     * Одно, а не список: билдер Prisma 8 умеет складывать условия только по И
+     * (у полей есть ilike, но ни f.or, ни .or у условия нет), поэтому поиск
+     * сразу по нескольким колонкам выражается только отдельными запросами.
+     */
+    searchField?: EntityField<TModel>;
+    relations?: EntityRelation<TModel>[];
+    extendMethods?: (args: {
+        model: EntityModelHandle;
+    }) => Record<string, CustomMethod>;
+    extendController?: (args: {
+        entity: EntityRow<TModel>;
+    }) => Record<string, CustomMethod>;
+};
+/**
+ * Сущность поверх модели контракта.
+ *
+ * Тип строки берётся из самой модели по её имени, поэтому дженерик передавать
+ * не нужно: `createEntity({ model: "Task", ... })`. Имена полей —
+ * владельца, сортировки, поиска и связей — проверяются против этой модели.
+ */
+export declare function createEntity<TModel extends EntityModelName>(args: CreateEntityArgs<TModel>): {
+    modelName: TModel;
+    getModel: () => EntityModelHandle;
+    methods: {
+        list: (input?: z.input<typeof listSchema> | undefined) => Promise<(EntityRow<TModel> & {
+            id: string;
+        })[]>;
+        getById: (id: string) => Promise<(EntityRow<TModel> & {
+            id: string;
+        }) | null>;
+        /** как getById, но по произвольному where (используется для скоупинга) */
+        getOne: (where: Record<string, unknown>) => Promise<(EntityRow<TModel> & {
+            id: string;
+        }) | null>;
+        create: (data: Record<string, unknown>) => Promise<EntityRow<TModel> & {
+            id: string;
+        }>;
+        update: (id: string, data: Record<string, unknown>) => Promise<EntityRow<TModel> & {
+            id: string;
+        }>;
+        updateWhere: (where: Record<string, unknown>, data: Record<string, unknown>) => Promise<EntityRow<TModel> & {
+            id: string;
+        }>;
+        deleteById: (id: string) => Promise<unknown>;
+        deleteWhere: (where: Record<string, unknown>) => Promise<{}>;
+        count: (where?: Record<string, unknown>) => Promise<number>;
+    };
+    createRouter: () => import("@trpc/server").TRPCBuiltRouter<{
+        ctx: TRPCContext;
+        meta: object;
+        errorShape: import("@trpc/server").TRPCDefaultErrorShape;
+        transformer: false;
+    }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
+        list: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                where?: Record<string, any> | undefined;
+                page?: number | undefined;
+                limit?: number | undefined;
+                sort?: {
+                    field: string;
+                    dir?: "asc" | "desc" | undefined;
+                } | undefined;
+                search?: string | undefined;
+            } | undefined;
+            output: (EntityRow<TModel> & {
+                id: string;
+            })[];
+            meta: object;
+        }>;
+        getById: import("@trpc/server").TRPCMutationProcedure<{
+            input: string;
+            output: (EntityRow<TModel> & {
+                id: string;
+            }) | null;
+            meta: object;
+        }>;
+        create: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                data: Record<string, any>;
+            };
+            output: EntityRow<TModel> & {
+                id: string;
+            };
+            meta: object;
+        }>;
+        update: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                id: string;
+                data: Record<string, any>;
+            };
+            output: EntityRow<TModel> & {
+                id: string;
+            };
+            meta: object;
+        }>;
+        delete: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                id: string;
+            };
+            output: {};
+            meta: object;
+        }>;
+        count: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                where?: Record<string, any> | undefined;
+            } | undefined;
+            output: number;
+            meta: object;
+        }>;
+        controller: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                id: string;
+                method: string;
+                data?: any;
+            };
+            output: unknown;
+            meta: object;
+        }>;
+    }>>;
+};

package/dist/index.js

@@ -0,0 +1,310 @@
+import { TRPCError } from "@trpc/server";
+import { z } from "zod";
+import { publicProcedure, router, } from "@quark-fw/plugin-trpc/src/trpc.js";
+const invoke = (m, data) => typeof m === "function" ? m(data) : m.handler(m.input.parse(data));
+// Сериализуемая сортировка: orderBy в Prisma 8 принимает СЕЛЕКТОР-функцию
+// (f) => f.field.asc(), поэтому по сети передаём {field, dir}, а функцию
+// собираем на сервере. Одно поле: цепочка/массив билдером не поддержаны.
+export const sortSchema = z.object({
+    field: z.string(),
+    dir: z.enum(["asc", "desc"]).default("asc"),
+});
+const listSchema = z.object({
+    where: z.record(z.string(), z.any()).optional(),
+    page: z.number().int().min(1).default(1),
+    limit: z.number().int().min(1).max(100).default(20),
+    sort: sortSchema.optional(),
+    /** поиск по подстроке; поле задаётся в createEntity (searchField) */
+    search: z.string().optional(),
+});
+/**
+ * Модели контракта.
+ *
+ * Тип `quark.db` объявляет само приложение (аугментация Quark), поэтому
+ * пакету он не виден — но форма, на которую пакет опирается, известна и
+ * описана здесь. Заодно ловим ненастроенный prisma-плагин внятной ошибкой
+ * вместо `Cannot read properties of undefined`.
+ */
+const ormModels = () => {
+    const { db } = quark;
+    const models = db?.orm?.public;
+    if (!models) {
+        throw new Error("@quark-fw/entity: quark.db.orm.public недоступен — не подключён @quark/plugin-prisma?");
+    }
+    return models;
+};
+const modelByName = (name) => {
+    const model = ormModels()[name];
+    if (!model) {
+        throw new Error(`@quark-fw/entity: модели "${name}" нет в контракте`);
+    }
+    return model;
+};
+/**
+ * Сущность поверх модели контракта.
+ *
+ * Тип строки берётся из самой модели по её имени, поэтому дженерик передавать
+ * не нужно: `createEntity({ model: "Task", ... })`. Имена полей —
+ * владельца, сортировки, поиска и связей — проверяются против этой модели.
+ */
+export function createEntity(args) {
+    // в конфиге направление необязательно, схема сортировки требует его явно
+    const fallbackSort = args.defaultSort && {
+        field: args.defaultSort.field,
+        dir: args.defaultSort.dir ?? "asc",
+    };
+    // лениво: quark.db появляется после init prisma-плагина
+    const getModel = () => modelByName(args.model);
+    const chain = (where) => {
+        let q = getModel();
+        if (where && Object.keys(where).length)
+            q = q.where(where);
+        return q;
+    };
+    // {field, dir} -> селектор Prisma 8. Не все типы полей сортируемы
+    // (у boolean, например, нет asc/desc) — отвечаем понятной ошибкой.
+    const applySort = (q, sort) => {
+        if (!sort)
+            return q;
+        return q.orderBy((fields) => {
+            const direction = fields?.[sort.field]?.[sort.dir];
+            if (typeof direction !== "function") {
+                throw new TRPCError({
+                    code: "BAD_REQUEST",
+                    message: `Field "${sort.field}" of ${args.model} is not sortable`,
+                });
+            }
+            return direction.call(fields[sort.field]);
+        });
+    };
+    /**
+     * Поиск по подстроке, без учёта регистра (ilike).
+     *
+     * Условие добавляется отдельным where — они складываются по И, поэтому
+     * скоуп владельца и фильтры остаются в силе.
+     */
+    const applySearch = (q, search) => {
+        const term = search?.trim();
+        if (!term || !args.searchField)
+            return q;
+        // % и _ — служебные символы шаблона; экранируем, чтобы «50%» искалось
+        // как текст, а не как «что угодно после 50»
+        const escaped = term.replace(/[\\%_]/g, "\\$&");
+        return q.where((fields) => {
+            const field = fields?.[args.searchField];
+            const ilike = field?.ilike;
+            if (typeof ilike !== "function") {
+                throw new TRPCError({
+                    code: "BAD_REQUEST",
+                    message: `Field "${args.searchField}" of ${args.model} is not searchable`,
+                });
+            }
+            return ilike.call(field, `%${escaped}%`);
+        });
+    };
+    const baseController = (row) => ({
+        update: (data) => chain({ id: row.id }).update(data),
+        delete: () => chain({ id: row.id }).delete(),
+    });
+    const buildController = (row) => ({
+        ...baseController(row),
+        ...(args.extendController?.({ entity: row }) ?? {}),
+    });
+    const withController = (row) => {
+        if (!row || typeof row !== "object")
+            return row;
+        return Object.assign(row, buildController(row));
+    };
+    const methods = {
+        list: async (input) => {
+            const { where, page, limit, sort, search } = listSchema.parse(input ?? {});
+            const rows = (await applySort(applySearch(chain(where), search), sort ?? fallbackSort)
+                .skip(limit * (page - 1))
+                .take(limit)
+                .all());
+            return rows.map(withController);
+        },
+        getById: async (id) => withController((await chain({ id }).first())),
+        /** как getById, но по произвольному where (используется для скоупинга) */
+        getOne: async (where) => withController((await chain(where).first())),
+        create: async (data) => withController((await getModel().create(data))),
+        update: async (id, data) => withController((await chain({ id }).update(data))),
+        // Prisma 8 при непопадании во where возвращает null, а не бросает.
+        // Молчаливый null скрыл бы и опечатку в id, и попытку тронуть чужую
+        // запись — отвечаем NOT_FOUND (существование чужой не подтверждаем).
+        updateWhere: async (where, data) => {
+            const row = (await chain(where).update(data));
+            if (!row) {
+                throw new TRPCError({
+                    code: "NOT_FOUND",
+                    message: `${args.model} not found`,
+                });
+            }
+            return withController(row);
+        },
+        deleteById: (id) => chain({ id }).delete(),
+        deleteWhere: async (where) => {
+            const row = await chain(where).delete();
+            if (!row) {
+                throw new TRPCError({
+                    code: "NOT_FOUND",
+                    message: `${args.model} not found`,
+                });
+            }
+            return row;
+        },
+        // count() билдера доступен только внутри include-рефайнментов —
+        // счёт делается через aggregate
+        count: async (where) => {
+            const { n } = (await chain(where).aggregate((a) => ({
+                n: a.count(),
+            })));
+            return n;
+        },
+    };
+    const createRouter = () => {
+        const proc = args.procedure ?? publicProcedure;
+        // TRPCUser — пустой интерфейс-шов, его поля объявляет плагин
+        // авторизации, поэтому id читаем структурно
+        const ownerId = (ctx) => ctx.user?.id;
+        // where-скоуп владельца: {} если authField не задан
+        const scope = (ctx) => args.authField ? { [args.authField]: ownerId(ctx) } : {};
+        /**
+         * Убирает из присланных данных поля, которые клиент задавать не вправе.
+         *
+         * Колонка владельца проставляется только из контекста. Иначе владельца
+         * можно переписать на чужого: скоуп во where проверяет, что ЭТА запись
+         * твоя, но не мешает после этого отдать её другому — так в чужой
+         * аккаунт подкладывается запись.
+         *
+         * id при обновлении тоже не принимаем: подмена первичного ключа рвёт
+         * ссылки на запись и не имеет смысла как операция.
+         */
+        const stripProtected = (data, also = []) => {
+            const clean = { ...data };
+            if (args.authField)
+                delete clean[args.authField];
+            for (const field of also)
+                delete clean[field];
+            return clean;
+        };
+        // порт checkRelation: записать ссылку на родителя можно, только если
+        // этот родитель принадлежит вызывающему (иначе чужой id «подсунули»)
+        const checkRelations = async (data, ctx) => {
+            for (const relation of args.relations ?? []) {
+                const value = data[relation.field];
+                if (value === undefined || value === null)
+                    continue;
+                const parent = await modelByName(relation.model)
+                    .where({
+                    [relation.parentField ?? "id"]: value,
+                    [relation.authField]: ownerId(ctx),
+                })
+                    .first();
+                if (!parent) {
+                    // NOT_FOUND, а не FORBIDDEN: не подтверждаем существование
+                    // чужой записи
+                    throw new TRPCError({
+                        code: "NOT_FOUND",
+                        message: `${relation.model} ${String(value)} not found`,
+                    });
+                }
+            }
+        };
+        const custom = args.extendMethods?.({ model: getModel() }) ?? {};
+        const customProcedures = Object.fromEntries(Object.entries(custom).map(([name, m]) => [
+            name,
+            typeof m === "function"
+                ? proc
+                    .input(z.any().optional())
+                    .mutation(({ input }) => m(input))
+                : proc
+                    .input(m.input)
+                    .mutation(({ input }) => m.handler(input)),
+        ]));
+        return router({
+            ...customProcedures,
+            list: proc.input(listSchema.optional()).mutation(({ input, ctx }) => methods.list({
+                ...(input ?? {}),
+                where: { ...(input?.where ?? {}), ...scope(ctx) },
+            })),
+            getById: proc
+                .input(z.string())
+                .mutation(({ input, ctx }) => methods.getOne({ id: input, ...scope(ctx) })),
+            create: proc
+                .input(z.object({ data: z.record(z.string(), z.any()) }))
+                .mutation(async ({ input, ctx }) => {
+                const data = stripProtected(input.data);
+                await checkRelations(data, ctx);
+                return methods.create({ ...data, ...scope(ctx) });
+            }),
+            update: proc
+                .input(z.object({
+                id: z.string(),
+                data: z.record(z.string(), z.any()),
+            }))
+                .mutation(async ({ input, ctx }) => {
+                const data = stripProtected(input.data, ["id"]);
+                await checkRelations(data, ctx);
+                // скоуп во where: чужую запись обновить нельзя
+                const where = { id: input.id, ...scope(ctx) };
+                // после отсева могло не остаться ни одного поля —
+                // отвечаем самой записью, а не ложным NOT_FOUND
+                if (!Object.keys(data).length) {
+                    const row = await methods.getOne(where);
+                    if (!row) {
+                        throw new TRPCError({
+                            code: "NOT_FOUND",
+                            message: `${args.model} not found`,
+                        });
+                    }
+                    return row;
+                }
+                return methods.updateWhere(where, data);
+            }),
+            delete: proc
+                .input(z.object({ id: z.string() }))
+                .mutation(({ input, ctx }) => methods.deleteWhere({ id: input.id, ...scope(ctx) })),
+            count: proc
+                .input(z
+                .object({
+                where: z.record(z.string(), z.any()).optional(),
+            })
+                .optional())
+                .mutation(({ input, ctx }) => methods.count({ ...(input?.where ?? {}), ...scope(ctx) })),
+            controller: proc
+                .input(z.object({
+                id: z.string(),
+                method: z.string(),
+                data: z.any().optional(),
+            }))
+                .mutation(async ({ input, ctx }) => {
+                const row = (await chain({
+                    id: input.id,
+                    ...scope(ctx),
+                }).first());
+                if (!row)
+                    throw new TRPCError({ code: "NOT_FOUND" });
+                const controller = buildController(row);
+                // Только собственные методы контроллера: без этой проверки
+                // имя вроде "constructor" или "toString" дотягивается до
+                // прототипа объекта и вызывается как метод сущности.
+                const method = Object.hasOwn(controller, input.method)
+                    ? controller[input.method]
+                    : undefined;
+                if (!method)
+                    throw new TRPCError({
+                        code: "BAD_REQUEST",
+                        message: `Method ${input.method} not found on ${args.model}`,
+                    });
+                return invoke(method, input.data);
+            }),
+        });
+    };
+    return {
+        modelName: args.model,
+        getModel,
+        methods,
+        createRouter,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Шов типизации моделей.
+ *
+ * Пакет не знает контракта приложения — приложение объявляет его само:
+ *
+ *   type Models = (typeof db)["orm"]["public"];
+ *
+ *   declare module "@quark-fw/entity/src/types.js" {
+ *       interface EntityModels
+ *           extends {
+ *               [K in keyof Models]: Awaited<ReturnType<Models[K]["all"]>>[number];
+ *           } {}
+ *   }
+ *
+ * После этого createEntity выводит строку по имени модели, а имена полей
+ * (владелец, сортировка, поиск, связи) проверяются компилятором.
+ */
+export interface EntityModels {
+}
+/** объявило ли приложение свои модели */
+type ModelsDeclared = keyof EntityModels extends never ? false : true;
+/**
+ * Имя модели контракта.
+ *
+ * Пока приложение не заполнило шов, это любая строка: пакет должен собираться
+ * и сам по себе, без приложения рядом.
+ */
+export type EntityModelName = ModelsDeclared extends true ? keyof EntityModels & string : string;
+/** строка модели по её имени */
+export type EntityRow<TModel extends string> = TModel extends keyof EntityModels ? EntityModels[TModel] : Record<string, unknown>;
+/** имя колонки модели */
+export type EntityField<TModel extends string> = TModel extends keyof EntityModels ? keyof EntityModels[TModel] & string : string;
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/useEntityForm.d.ts

@@ -0,0 +1,34 @@
+import { type ChangeEvent } from "react";
+export type EntityFormState = "idle" | "processing";
+/**
+ * Компоненты зовут onChange по-разному: нативные — событием, часть
+ * Mantine-контролов (Select, Checkbox через onChange) — сразу значением.
+ */
+type FieldChange = ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement> | string | number | boolean | null;
+export declare function useEntityForm<Shape extends Record<string, unknown>>({ defaultValues, onSubmit, resetOnSuccess, }: {
+    defaultValues?: Partial<Shape>;
+    onSubmit: (values: Shape) => void | Promise<void>;
+    resetOnSuccess?: boolean;
+}): {
+    values: Partial<Shape>;
+    state: EntityFormState;
+    error: string | null;
+    reset: () => void;
+    submit: () => Promise<void>;
+    setValue: <K extends keyof Shape>(field: K, value: Shape[K]) => void;
+    getInputProps: (field: keyof Shape) => {
+        value: string | number | readonly string[];
+        onChange: (event: FieldChange) => void;
+    };
+    getFormProps: () => {
+        onSubmit: (event?: {
+            preventDefault?: () => void;
+        }) => void;
+    };
+    getSubmitButtonProps: () => {
+        type: "submit";
+        loading: boolean;
+        disabled: boolean;
+    };
+};
+export {};

package/dist/useEntityForm.js

@@ -0,0 +1,67 @@
+import { useState } from "react";
+import { errorMessage } from "@quark-fw/store/src/errors.js";
+export function useEntityForm({ defaultValues, onSubmit, resetOnSuccess = true, }) {
+    const initial = defaultValues ?? {};
+    const [values, setValues] = useState(initial);
+    const [state, setState] = useState("idle");
+    const [error, setError] = useState(null);
+    const reset = () => {
+        setValues(initial);
+        setError(null);
+        setState("idle");
+    };
+    const submit = async () => {
+        setState("processing");
+        setError(null);
+        try {
+            await onSubmit(values);
+            if (resetOnSuccess)
+                setValues(initial);
+        }
+        catch (e) {
+            setError(errorMessage(e));
+        }
+        finally {
+            setState("idle");
+        }
+    };
+    const setValue = (field, value) => {
+        setValues((prev) => ({ ...prev, [field]: value }));
+    };
+    return {
+        values,
+        state,
+        error,
+        reset,
+        submit,
+        setValue,
+        getInputProps: (field) => ({
+            // то, что принимает value у input/textarea
+            value: (values[field] ?? ""),
+            onChange: (event) => {
+                if (event && typeof event === "object" && "target" in event) {
+                    // checked есть только у input, поэтому сначала смотрим на
+                    // type, а уже потом читаем нужное поле
+                    const target = event.target;
+                    const next = target.type === "checkbox"
+                        ? target.checked
+                        : target.value;
+                    setValue(field, next);
+                    return;
+                }
+                setValue(field, event);
+            },
+        }),
+        getFormProps: () => ({
+            onSubmit: (event) => {
+                event?.preventDefault?.();
+                void submit();
+            },
+        }),
+        getSubmitButtonProps: () => ({
+            type: "submit",
+            loading: state === "processing",
+            disabled: state === "processing",
+        }),
+    };
+}

package/dist/uuidv7.d.ts

@@ -0,0 +1 @@
+export declare function uuidv7(): string;

package/dist/uuidv7.js

@@ -0,0 +1,17 @@
+// Клиентская генерация UUIDv7 (RFC 9562): 48 бит unix-времени в мс +
+// версия 7 + случайные биты. Сгенерированный на клиенте id — финальный id
+// записи (оптимистичный элемент списка и есть будущая строка БД).
+export function uuidv7() {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    const ts = BigInt(Date.now());
+    bytes[0] = Number((ts >> 40n) & 0xffn);
+    bytes[1] = Number((ts >> 32n) & 0xffn);
+    bytes[2] = Number((ts >> 24n) & 0xffn);
+    bytes[3] = Number((ts >> 16n) & 0xffn);
+    bytes[4] = Number((ts >> 8n) & 0xffn);
+    bytes[5] = Number(ts & 0xffn);
+    bytes[6] = (bytes[6] & 0x0f) | 0x70; // версия 7
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // вариант RFC
+    const hex = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@quark-fw/entity",
+	"version": "0.0.1",
+	"description": "Entity CRUD layer over tRPC and Prisma for the Quark framework",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json",
+		"./src/*": "./dist/*",
+		"./*": "./dist/*"
+	},
+	"files": ["dist"],
+	"scripts": {
+		"dev": "tsx watch src/index.ts",
+		"build": "tsc -p tsconfig.build.json && node ../../scripts/postbuild.mjs"
+	},
+	"keywords": ["quark"],
+	"author": "",
+	"license": "ISC",
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@quark-fw/plugin-trpc": "0.0.1",
+		"@quark-fw/store": "0.0.1",
+		"@trpc/server": "^11.0.0",
+		"zod": "^4.0.0"
+	},
+	"peerDependencies": {
+		"@quark-fw/core": "0.0.1",
+		"react": "^19.2.4"
+	},
+	"devDependencies": {
+		"@types/react": "^19.2.14"
+	}
+}