@quark-fw/entity 0.1.7 → 0.1.9

package/dist/client/createEntityContext.d.ts

@@ -0,0 +1,22 @@
+import { ReactNode } from "react";
+import type { Serialize } from "@quark-fw/store/src/serialize.js";
+import type { EntitiesContextType, EntityContextType } from "./types.js";
+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/createEntityContext.js

@@ -0,0 +1,291 @@
+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, 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";
+import { matchesEverything, matchesWhere, useSafeContext } from "./helpers.js";
+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());
+        // Массивы, которые провайдер САМ записал в кэш store. Их эхо приходит
+        // назад через fresh, и без пометки эффект синхронизации принимал его
+        // за серверные данные: оптимистичный массив, попавший в кэш до отката,
+        // перетирал откат (mutationsInFlight к этому моменту уже обнулён).
+        const ownCacheWrites = useRef(new WeakSet());
+        const setList = (updater) => {
+            const syncCache = (arr) => {
+                ownCacheWrites.current.add(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 (ownCacheWrites.current.has(fresh)) {
+                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/client/helpers.d.ts

@@ -0,0 +1,5 @@
+import { Context } from "react";
+/** Условия, которые можно проверить на клиенте (простые равенства). */
+export declare const matchesEverything: (where: Record<string, unknown>) => boolean;
+export declare const matchesWhere: (row: Record<string, unknown>, where: Record<string, unknown>) => boolean;
+export declare function useSafeContext<T>(errorMessage: string, Ctx: Context<T | null>): () => T & ({} | undefined);

package/dist/client/helpers.js

@@ -0,0 +1,21 @@
+// Хелперы клиентской части сущностей.
+import { useContext } from "react";
+/** Условия, которые можно проверить на клиенте (простые равенства). */
+export const matchesEverything = (where) => Object.keys(where).length === 0;
+export const matchesWhere = (row, where) => Object.entries(where).every(([field, expected]) => {
+    // операторы вида { in: [...] } на клиенте не разбираем — доверяем серверу
+    if (expected && typeof expected === "object")
+        return true;
+    return row?.[field] === expected;
+});
+export function useSafeContext(errorMessage, Ctx) {
+    return () => {
+        // хук зовётся из возвращённой функции, которая сама используется как
+        // хук потребителем (useEntities/useEntity) — порядок вызовов стабилен
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        const ctx = useContext(Ctx);
+        if (ctx === null)
+            throw new Error(errorMessage);
+        return ctx;
+    };
+}

package/dist/client/types.d.ts

@@ -0,0 +1,138 @@
+import type { 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 TinyBranch<Row> = {
+    entity: Record<string, EntityTinyCaller<Row>>;
+};
+export type TrpcBranch<Row> = {
+    entity: Record<string, EntityTrpcCaller<Row>>;
+};
+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>>;
+};

package/dist/client/types.js

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

package/dist/client.d.ts

@@ -1,153 +1,2 @@
-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;
-}>];
+export { createEntityContext } from "./client/createEntityContext.js";
+export type { EntitiesContextType, EntitiesListParams, EntityContextType, EntityListArgs, EntityTinyCaller, EntityTrpcCaller, } from "./client/types.js";