इस प्रोजेक्ट के बारे में
# @querry-kit/nest
Query Kit APIs के लिए एकत्रित NestJS helpers: fields projection, Prisma-style query services, CASL policies, OpenAPI decorators, pipes, pagination DTOs, और object utilities।
## 🌐 Querry Kit Ecosystem
[Querry Kit overview](https://querry-kit.github.io/querry-kit/) तीन core packages को जोड़ता है:
- [`@querry-kit/nest`](https://github.com/querry-kit/nest) NestJS API और controller patterns प्रदान करता है।
- [`@querry-kit/nuxt`](https://github.com/querry-kit/nuxt) typed API clients और headless Vue/Nuxt data primitives प्रदान करता है।
- [`@querry-kit/nuxt-ui`](https://github.com/querry-kit/nuxt-ui) उन primitives पर बने Nuxt UI table controls प्रदान करता है।
## 📦 Install
```sh
pnpm add @querry-kit/nest
pnpm add @nestjs/common @nestjs/core @nestjs/swagger class-transformer class-validator reflect-metadata
```
वैकल्पिक CASL adapter के लिए:
```sh
pnpm add @casl/ability @casl/prisma
```
वर्तमान package version npm पर प्रकाशित है। npm प्राथमिक distribution channel है।
GitHub release tags fallback के रूप में उपलब्ध रहते हैं:
```sh
pnpm add github:querry-kit/nest#v0.0.1
```
## 🚀 Release Workflow
Releases Changesets और GitHub Actions द्वारा संचालित होते हैं। `main` branch में committed `dist` files नहीं होतीं; इसमें केवल source, README, और workflow configuration होती है।
Package-visible changes में changeset शामिल होना चाहिए:
```sh
pnpm changeset
```
जब changes `main` पर आते हैं, तो `changesets` workflow एक release PR बनाता या अपडेट करता है। उस PR में version bump और changelog updates होते हैं जो इससे उत्पन्न होते हैं:
```sh
pnpm changeset version
```
npm publish workflow GitHub Actions OIDC के माध्यम से npm Trusted Publishing का उपयोग करता है। npm package को npm package publishing settings में इस repository और workflow से जोड़ा जाना चाहिए:
- Repository: `querry-kit/nest`
- Workflow file: `release.yml`
- Environment: unset
Release PR merge होने के बाद, `npm publish` workflow version/changelog changes के लिए चलता है। यह package checks चलाता है, CI में `dist` build करता है, `@querry-kit/nest` को npm पर publish करता है, release commit को `vX.Y.Z` के रूप में tag करता है, और GitHub Release बनाता है।
Consumers को npm से install करना चाहिए:
```sh
pnpm add @querry-kit/nest
```
## 🧩 Usage
`ResourceQuery` सामान्य controller flow को कवर करता है: optional `fields` parse करना, endpoint-required includes को client `include` values के साथ merge करना, selected relations के लिए Prisma includes generate करना, `QueryService` call करना, models को DTOs में map करना, और response project करना।
```ts
import { Get, Query, Req } from '@nestjs/common';
import { ApiErrorResponses, ApiPaginatedResponse, ApiResourceQuery, QueryDTO, ResourceQuery } from '@querry-kit/nest';
@Get()
@ApiResourceQuery()
@ApiPaginatedResponse({ model: CustomerDTO })
@ApiErrorResponses({ badRequestDescription: 'Invalid query parameter.' })
async query(@Req() req: AuthRequest, @Query() query: QueryDTO<CustomerTypeMap>) {
return ResourceQuery.query({
service: this.customersService,
query,
schema: CustomerDTO,
ability: req.ability,
map: (customer, ability) => CustomerDTO.fromModel(customer, ability),
});
}
```
`QueryService` और Prisma-compatible delegate के साथ resource services बनाएं:
```ts
import { Injectable } from '@nestjs/common';
import { QueryService, type BaseDelegateTypeMap } from '@querry-kit/nest';
import { Prisma, PrismaService } from '../prisma';
interface CustomerTypeMap extends BaseDelegateTypeMap {
select: Prisma.CustomerSelect;
include: Prisma.CustomerInclude;
whereInput: Prisma.CustomerWhereInput;
orderByWithRelationInput: Prisma.CustomerOrderByWithRelationInput;
whereUniqueInput: Prisma.CustomerWhereUniqueInput;
scalarFieldEnum: Prisma.CustomerScalarFieldEnum;
}
@Injectable()
export class CustomersService extends QueryService<typeof PrismaService.prototype.customer, CustomerTypeMap> {
constructor(prisma: PrismaService) {
super(prisma.customer);
}
}
```
छोटे imports के लिए focused subpaths उपलब्ध हैं:
```ts
import { createCaslAccessibleWhere, filterCaslFields } from '@querry-kit/nest/casl';
import { ApiResourceQuery } from '@querry-kit/nest/decorators';
import { Fields } from '@querry-kit/nest/fields';
import { parseObject } from '@querry-kit/nest/object';
import { QueryService } from '@querry-kit/nest/query-service';
```
## 🔐 CASL
CASL वैकल्पिक है। `ability` केवल तब pass करें जब endpoint को `QueryService` के माध्यम से authorization-aware `where` clause merge करना हो; उन APIs के लिए इसे omit करें जो CASL का उपयोग नहीं करते।
```ts
import { createCaslAccessibleWhere } from '@querry-kit/nest/casl';
super(prisma.customer, {
subject: 'Customer',
accessibleWhere: createCaslAccessibleWhere({ action: 'read' }),
});
```
जब `query` को ability pass की जाती है, तो service CASL where clause को user filters के साथ `{ AND: [accessibleWhere, parsedWhere] }` के रूप में combine करती है।
Field-level response permissions के लिए, completed DTO को mutate किए बिना filter करें:
```ts
return filterCaslFields(dto, 'Customer', ability);
```
Helper डिफ़ॉल्ट रूप से `read` action का उपयोग करता है। जब application uppercase या enum-backed actions का उपयोग करता है तो `{ action: RoleAction.READ }` pass करें। यह केवल serialized DTO fields को filter करता है; database reads को भी constrain करने के लिए ability को `QueryService` में pass करते रहें।
## 🎯 Fields
`fields` डिफ़ॉल्ट रूप से optional है। जब omit किया जाता है, Query Kit पूरा DTO response लौटाता है। जब present होता है, यह syntax और selected fields को validate करता है, required relation includes जोड़ता है, और returned DTOs को project करता है। Outer braces optional हैं, इसलिए `{id,title}` `id,title` के समान है।
```txt
GET /books?fields=id,title
GET /books?fields={id,title}
GET /books?fields=items{id,title},meta{page,perPage,itemCount,pageCount}
GET /books?fields=items{},meta{page}
```
एक explicit empty value (`?fields=`) या empty outer selection (`?fields={}`) `{}` लौटाता है। Empty nested selections भी valid हैं: `items{}` empty item objects उत्पन्न करता है, जबकि `meta{page}` केवल requested page metadata रखता है। केवल whitespace वाला value invalid रहता है।
जब controller को custom service orchestration चाहिए तो सीधे `prepareFieldsQuery` का उपयोग करें:
```ts
import { Fields, prepareFieldsQuery } from '@querry-kit/nest/fields';
const prepared = prepareFieldsQuery({
fields: query.fields,
include: query.include,
schema: BookDTO,
requiredInclude: { author: true },
});
const { items, pageMeta } = await booksService.query({ ...query, include: prepared.include });
return {
items: Fields.project(items.map(BookDTO.fromModel), prepared.projection),
meta: Fields.project(pageMeta, prepared.metaProjection),
};
```
## 📖 Documentation
- [Getting Started](https://querry-kit.github.io/querry-kit/docs/nest/guide/getting-started)
- [Complete API Example](https://querry-kit.github.io/querry-kit/docs/nest/guide/example-app)
- [CRUD Controller](https://querry-kit.github.io/querry-kit/docs/nest/guide/crud-controller)
- [Fields](https://querry-kit.github.io/querry-kit/docs/nest/api/fields/)
- [Query Service](https://querry-kit.github.io/querry-kit/docs/nest/api/query-service)
- [DTOs and Pagination](https://querry-kit.github.io/querry-kit/docs/nest/api/dtos-pagination)
- [OpenAPI Decorators](https://querry-kit.github.io/querry-kit/docs/nest/api/openapi)
- [CASL](https://querry-kit.github.io/querry-kit/docs/nest/api/casl)
- [API Reference](https://querry-kit.github.io/querry-kit/docs/nest/api/)
## 🛠 Development
```sh
pnpm install
pnpm lint
pnpm check
pnpm test
pnpm test:coverage
pnpm build
```
Workspace build allowlist test और documentation toolchain के लिए आवश्यक native scripts की अनुमति देता है, जिसमें Parcel का file watcher भी शामिल है।
`pnpm test:coverage` सभी source files collect करता है, coverage summary print करता है, और HTML और LCOV reports `coverage/` में लिखता है। GitHub Actions वही command चलाता है और report को workflow artifact के रूप में retain करता है।
Comments
0 Rating appears after 10 ratings
Sign in to join the discussion.