@quark-fw/entity 0.1.6 → 0.1.8

package/dist/createEntity.js

@@ -0,0 +1,287 @@
+import { TRPCError } from "@trpc/server";
+import { z } from "zod";
+import { publicProcedure, router, } from "@quark-fw/plugin-trpc/src/trpc.js";
+import { invoke, modelByName } from "./helpers.js";
+// Сериализуемая сортировка: 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(),
+});
+/**
+ * Сущность поверх модели контракта.
+ *
+ * Тип строки берётся из самой модели по её имени, поэтому дженерик передавать
+ * не нужно: `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/helpers.d.ts

@@ -0,0 +1,15 @@
+import type { CustomMethod, EntityModelHandle } from "./createEntity.js";
+export declare const invoke: (m: CustomMethod, data: unknown) => unknown;
+/** модели контракта по имени: конкретный набор знает только приложение */
+type OrmModels = Record<string, EntityModelHandle | undefined>;
+/**
+ * Модели контракта.
+ *
+ * Тип `quark.db` объявляет само приложение (аугментация Quark), поэтому
+ * пакету он не виден — но форма, на которую пакет опирается, известна и
+ * описана здесь. Заодно ловим ненастроенный prisma-плагин внятной ошибкой
+ * вместо `Cannot read properties of undefined`.
+ */
+export declare const ormModels: () => OrmModels;
+export declare const modelByName: (name: string) => EntityModelHandle;
+export {};

package/dist/helpers.js

@@ -0,0 +1,24 @@
+export const invoke = (m, data) => typeof m === "function" ? m(data) : m.handler(m.input.parse(data));
+/**
+ * Модели контракта.
+ *
+ * Тип `quark.db` объявляет само приложение (аугментация Quark), поэтому
+ * пакету он не виден — но форма, на которую пакет опирается, известна и
+ * описана здесь. Заодно ловим ненастроенный prisma-плагин внятной ошибкой
+ * вместо `Cannot read properties of undefined`.
+ */
+export 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;
+};
+export const modelByName = (name) => {
+    const model = ormModels()[name];
+    if (!model) {
+        throw new Error(`@quark-fw/entity: модели "${name}" нет в контракте`);
+    }
+    return model;
+};

package/dist/index.d.ts

@@ -1,216 +1,2 @@
-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;
-        }>;
-    }>>;
-};
+export { createEntity, sortSchema, type CreateEntityArgs, type CustomMethod, type CustomMethodFn, type CustomMethodValidated, type EntityModelHandle, type EntityProcedure, type EntityRelation, type EntitySort, } from "./createEntity.js";