@quark-fw/entity 0.1.6 → 0.1.8

package/dist/client.js

@@ -1,295 +1,5 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-/* eslint-disable react-hooks/rules-of-hooks */
-// Порт createEntityContext из druslee/ugliest под quark:
-// пара React-контекстов на entity с оптимистичным состоянием и откатом.
+// Публичная поверхность клиентской части: реализация разложена по файлам
+// src/client/ (1 функция = 1 файл), здесь — реэкспорт под прежним путём
+// (@quark-fw/entity/src/client.js), на который завязаны приложения.
 // ВАЖНО: клиентский модуль — не импортировать серверный ./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];
-}
+export { createEntityContext } from "./client/createEntityContext.js";

package/dist/createEntity.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 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;
+        }>;
+    }>>;
+};
+export {};