منصوبے کے بارے میں
# @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/) تین بنیادی 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 کو cover کرتا ہے: optional `fields` parse کرنا، endpoint-required includes کو client `include` values کے ساتھ merge کرنا، منتخب 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 کے لیے، مکمل DTO کو mutate کیے بغیر filter کریں:
```ts
return filterCaslFields(dto, 'Customer', ability);
```
Helper بطور default `read` action استعمال کرتا ہے۔ جب application uppercase یا enum-backed actions استعمال کرے تو `{ action: RoleAction.READ }` pass کریں۔ یہ صرف serialized DTO fields filter کرتا ہے؛ database reads کو بھی constrain کرنے کے لیے ability کو `QueryService` کو pass کرتے رہیں۔
## 🎯 Fields
`fields` بطور default اختیاری ہے۔ جب omit کیا جائے، تو Query Kit مکمل DTO response return کرتا ہے۔ جب موجود ہو، تو یہ syntax اور منتخب fields validate کرتا ہے، required relation includes شامل کرتا ہے، اور واپس آنے والے DTOs project کرتا ہے۔ Outer braces اختیاری ہیں، لہٰذا `{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={}`) `{}` return کرتا ہے۔ Empty nested selections بھی valid ہیں: `items{}` empty item objects پیدا کرتا ہے، جبکہ `meta{page}` صرف requested page metadata رکھتا ہے۔ صرف whitespace پر مشتمل value invalid رہتی ہے۔
`prepareFieldsQuery` براہ راست استعمال کریں جب controller کو custom service orchestration درکار ہو:
```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's file watcher۔
`pnpm test:coverage` تمام source files collect کرتا ہے، coverage summary print کرتا ہے، اور HTML اور LCOV reports `coverage/` میں لکھتا ہے۔ GitHub Actions وہی command چلاتا ہے اور report کو workflow artifact کے طور پر محفوظ رکھتا ہے۔
Comments
0 Rating appears after 10 ratings
Sign in to join the discussion.