@rytass/cms-base-nestjs-graphql-module 0.1.24 → 0.1.26

package/llms.txt

@@ -0,0 +1,361 @@
+# @rytass/cms-base-nestjs-graphql-module
+
+Rytass Content Management System NestJS GraphQL Module - A GraphQL extension for the CMS base module providing GraphQL resolvers, queries, mutations, and DTOs for building GraphQL-enabled CMS applications.
+
+## Installation
+
+```bash
+npm install @rytass/cms-base-nestjs-graphql-module
+```
+
+## Features
+
+### GraphQL Resolvers
+- **ArticleResolver**: Basic article field resolution with author and category relationships
+- **BackstageArticleResolver**: Administrative article management operations
+- **ArticleSignatureResolver**: Article approval workflow resolution
+- **BackstageCategoryResolver**: Administrative category management
+
+### Queries & Mutations
+- **ArticleQueries**: Public article data queries
+- **CategoryQueries**: Public category data queries  
+- **ArticleMutations**: Article CRUD operations
+- **CategoryMutations**: Category CRUD operations
+
+### Data Loaders
+- **ArticleDataLoader**: Efficient GraphQL article loading
+- **MemberDataLoader**: User/author data loading for article relationships
+
+### GraphQL DTOs
+- **ArticleDto**: Public article representation
+- **BackstageArticleDto**: Administrative article with full metadata
+- **CategoryDto**: Public category representation
+- **BackstageCategoryDto**: Administrative category operations
+- **ArticleCollectionDto**: Paginated article collections
+
+### Custom Scalars
+- **QuadratsElementScalar**: Support for rich content editor elements
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { Module } from '@nestjs/common';
+import { GraphQLModule } from '@nestjs/graphql';
+import { CMSBaseGraphQLModule } from '@rytass/cms-base-nestjs-graphql-module';
+
+@Module({
+  imports: [
+    GraphQLModule.forRoot({
+      autoSchemaFile: true,
+    }),
+    CMSBaseGraphQLModule.forRoot({
+      multipleLanguageMode: true,
+      enableDraftMode: true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Async Configuration
+
+```typescript
+@Module({
+  imports: [
+    CMSBaseGraphQLModule.forRootAsync({
+      imports: [ConfigModule],
+      useFactory: (config: ConfigService) => ({
+        multipleLanguageMode: config.get('CMS_MULTI_LANG'),
+        enableDraftMode: config.get('CMS_DRAFT_MODE'),
+      }),
+      inject: [ConfigService],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## GraphQL Schema Examples
+
+### Article Queries
+
+```graphql
+# Get public articles
+query GetArticles($first: Int!, $after: String) {
+  articles(first: $first, after: $after) {
+    edges {
+      node {
+        articleId
+        title
+        content
+        publishedAt
+        author {
+          id
+          name
+        }
+        categories {
+          id
+          name
+        }
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+}
+
+# Get single article
+query GetArticle($id: ID!) {
+  article(id: $id) {
+    articleId
+    title
+    content
+    publishedAt
+    categories {
+      id
+      name
+    }
+  }
+}
+```
+
+### Backstage Operations
+
+```graphql
+# Create article (admin)
+mutation CreateArticle($input: CreateArticleInput!) {
+  createArticle(input: $input) {
+    id
+    title
+    stage
+    createdAt
+  }
+}
+
+# Update article (admin)
+mutation UpdateArticle($id: ID!, $input: UpdateArticleInput!) {
+  updateArticle(id: $id, input: $input) {
+    id
+    title
+    updatedAt
+  }
+}
+```
+
+### Category Operations
+
+```graphql
+# Get categories
+query GetCategories {
+  categories {
+    id
+    name
+    slug
+    parent {
+      id
+      name
+    }
+    children {
+      id
+      name
+    }
+  }
+}
+
+# Create category (admin)
+mutation CreateCategory($input: CreateCategoryInput!) {
+  createCategory(input: $input) {
+    id
+    name
+    slug
+  }
+}
+```
+
+## TypeScript Integration
+
+### Using GraphQL DTOs
+
+```typescript
+import { Field, ObjectType, ID } from '@nestjs/graphql';
+import { ArticleDto, CategoryDto } from '@rytass/cms-base-nestjs-graphql-module';
+
+@ObjectType()
+export class CustomArticleDto extends ArticleDto {
+  @Field(() => String, { nullable: true })
+  customField?: string;
+}
+```
+
+### Custom Resolvers
+
+```typescript
+import { Resolver, Query, Args } from '@nestjs/graphql';
+import { ArticleDto } from '@rytass/cms-base-nestjs-graphql-module';
+
+@Resolver(() => ArticleDto)
+export class CustomArticleResolver {
+  @Query(() => [ArticleDto])
+  async featuredArticles(): Promise<ArticleDto[]> {
+    // custom logic
+    return [];
+  }
+}
+```
+
+## Configuration Options
+
+Inherits all options from `@rytass/cms-base-nestjs-module` plus:
+
+```typescript
+interface CMSGraphqlBaseModuleOptionsDto extends CMSBaseModuleOptionsDto {
+  // All base CMS options are available
+  multipleLanguageMode?: boolean;
+  enableDraftMode?: boolean;
+  // ... other CMS base options
+}
+```
+
+## Key GraphQL Types
+
+```typescript
+// Article representation
+@ObjectType()
+export class ArticleDto {
+  @Field(() => ID)
+  articleId: string;
+
+  @Field()
+  title: string;
+
+  @Field()
+  content: string;
+
+  @Field(() => Date, { nullable: true })
+  publishedAt?: Date;
+
+  @Field(() => [CategoryDto])
+  categories: CategoryDto[];
+
+  @Field(() => UserDto, { nullable: true })
+  author?: UserDto;
+}
+
+// Category representation
+@ObjectType()
+export class CategoryDto {
+  @Field(() => ID)
+  id: string;
+
+  @Field()
+  name: string;
+
+  @Field()
+  slug: string;
+
+  @Field(() => CategoryDto, { nullable: true })
+  parent?: CategoryDto;
+
+  @Field(() => [CategoryDto])
+  children: CategoryDto[];
+}
+
+// Collection with pagination
+@ObjectType()
+export class ArticleCollectionDto {
+  @Field(() => [ArticleDto])
+  edges: ArticleDto[];
+
+  @Field()
+  totalCount: number;
+
+  @Field(() => PageInfo)
+  pageInfo: PageInfo;
+}
+```
+
+## Data Loading
+
+The module uses DataLoader pattern for efficient N+1 query prevention:
+
+```typescript
+// Automatic batched loading
+@ResolveField(() => UserDto)
+async author(@Root() article: ArticleDto): Promise<UserDto> {
+  return this.memberDataLoader.load(article.authorId);
+}
+
+@ResolveField(() => [CategoryDto])
+async categories(@Root() article: ArticleDto): Promise<CategoryDto[]> {
+  return this.articleDataLoader.loadCategories(article.id);
+}
+```
+
+## Language Support
+
+When `multipleLanguageMode` is enabled:
+
+```typescript
+// Language-aware resolvers
+@ResolveField(() => String)
+title(
+  @Root() article: ArticleDto,
+  @Language() language: string
+): string {
+  return this.getLocalizedContent(article, language, 'title');
+}
+```
+
+## Dependencies
+
+- `@rytass/cms-base-nestjs-module`: Core CMS functionality
+- `@rytass/member-base-nestjs-module`: User management integration
+- `dataloader`: Efficient data loading
+- `lru-cache`: Caching support
+
+## Peer Dependencies
+
+- `@nestjs/common`: NestJS framework
+- `@nestjs/typeorm`: Database integration
+- `@node-rs/jieba`: Text processing
+- `@quadrats/core`: Rich content support
+- `typeorm`: ORM
+
+## Testing
+
+```typescript
+import { Test } from '@nestjs/testing';
+import { ArticleResolver } from '@rytass/cms-base-nestjs-graphql-module';
+
+describe('ArticleResolver', () => {
+  let resolver: ArticleResolver;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [
+        ArticleResolver,
+        {
+          provide: 'MemberDataLoader',
+          useValue: mockDataLoader,
+        },
+      ],
+    }).compile();
+
+    resolver = module.get<ArticleResolver>(ArticleResolver);
+  });
+
+  // tests...
+});
+```
+
+## License
+
+MIT
+
+## Support
+
+For issues and questions, visit the [GitHub repository](https://github.com/Rytass/Utils/issues).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rytass/cms-base-nestjs-graphql-module",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "Rytass Content Management System NestJS Base GraphQL Module",
   "keywords": [
     "rytass",
@@ -15,6 +15,13 @@
     "type": "git",
     "url": "git+https://github.com/Rytass/Utils.git"
   },
+  "scripts": {
+    "clean": "nx clean",
+    "build": "nx build",
+    "lint": "nx lint",
+    "test": "nx test",
+    "test:watch": "nx test:watch"
+  },
   "bugs": {
     "url": "https://github.com/Rytass/Utils/issues"
   },
@@ -26,12 +33,9 @@
     "typeorm": "*"
   },
   "dependencies": {
-    "@rytass/cms-base-nestjs-module": "^0.2.12",
+    "@rytass/cms-base-nestjs-module": "^0.2.14",
     "@rytass/member-base-nestjs-module": "^0.2.18",
     "dataloader": "^2.2.3",
     "lru-cache": "^11.2.4"
-  },
-  "main": "./index.cjs.js",
-  "module": "./index.js",
-  "typings": "./index.d.ts"
+  }
 }

package/project.json

@@ -0,0 +1,23 @@
+{
+  "name": "@rytass/cms-base-nestjs-graphql-module",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "projectType": "library",
+  "sourceRoot": "packages/cms-base-nestjs-graphql-module/src",
+  "targets": {
+    "test": {
+      "executor": "@nx/jest:jest"
+    },
+    "test:watch": {
+      "executor": "@nx/jest:jest"
+    },
+    "lint": {
+      "executor": "nx:run-commands"
+    },
+    "clean": {
+      "executor": "nx:run-commands"
+    },
+    "build": {
+      "executor": "nx:run-commands"
+    }
+  }
+}

package/src/cms-base-graphql.module.ts

@@ -0,0 +1,101 @@
+import { Module, DynamicModule, Provider, Type } from '@nestjs/common';
+import { CMSBaseModule } from '@rytass/cms-base-nestjs-module';
+import { ArticleMutations } from './mutations/article.mutations';
+import { CategoryMutations } from './mutations/category.mutations';
+import { ArticleQueries } from './queries/article.queries';
+import { CategoryQueries } from './queries/category.queries';
+import { MemberDataLoader } from './data-loaders/members.dataloader';
+import { ArticleDataLoader } from './data-loaders/article.dataloader';
+import { ArticleResolver } from './resolvers/article.resolver';
+import { BackstageArticleResolver } from './resolvers/backstage-article.resolver';
+import { ArticleSignatureResolver } from './resolvers/article-signature.resolver';
+import { BackstageCategoryResolver } from './resolvers/backstage-category.resolver';
+import { CMSGraphqlBaseModuleOptionsDto } from './typings/cms-graphql-base-root-module-options.dto';
+import { CMSGraphqlBaseModuleAsyncOptionsDto } from './typings/cms-graphql-base-root-module-async-options.dto';
+import { OptionProviders } from './constants/option-providers';
+import { CMS_BASE_GRAPHQL_MODULE_OPTIONS } from './typings/cms-graphql-base-providers';
+import { CMSGraphqlBaseModuleOptionFactory } from './typings/cms-graphql-base-root-module-option-factory';
+
+@Module({})
+export class CMSBaseGraphQLModule {
+  static forRootAsync(options: CMSGraphqlBaseModuleAsyncOptionsDto): DynamicModule {
+    return {
+      module: CMSBaseGraphQLModule,
+      imports: [...(options.imports || []), CMSBaseModule.forRootAsync(options)],
+      exports: [CMSBaseModule],
+      providers: [
+        ...this.createAsyncProvider(options),
+        ...OptionProviders,
+        MemberDataLoader,
+        ArticleDataLoader,
+        ArticleResolver,
+        BackstageArticleResolver,
+        ArticleSignatureResolver,
+        ArticleQueries,
+        ArticleMutations,
+        CategoryQueries,
+        CategoryMutations,
+        BackstageCategoryResolver,
+      ],
+    };
+  }
+
+  static forRoot(options: CMSGraphqlBaseModuleOptionsDto): DynamicModule {
+    return {
+      module: CMSBaseGraphQLModule,
+      imports: [CMSBaseModule.forRoot(options)],
+      exports: [CMSBaseModule],
+      providers: [
+        {
+          provide: CMS_BASE_GRAPHQL_MODULE_OPTIONS,
+          useValue: options,
+        },
+        ...OptionProviders,
+        MemberDataLoader,
+        ArticleDataLoader,
+        ArticleResolver,
+        BackstageArticleResolver,
+        ArticleSignatureResolver,
+        ArticleQueries,
+        ArticleMutations,
+        CategoryQueries,
+        CategoryMutations,
+        BackstageCategoryResolver,
+      ],
+    };
+  }
+
+  private static createAsyncProvider(options: CMSGraphqlBaseModuleAsyncOptionsDto): Provider[] {
+    if (options.useExisting || options.useFactory) {
+      return [this.createAsyncOptionsProvider(options)];
+    }
+
+    return [
+      this.createAsyncOptionsProvider(options),
+      ...(options.useClass
+        ? [
+            {
+              provide: options.useClass,
+              useClass: options.useClass,
+            },
+          ]
+        : []),
+    ];
+  }
+
+  private static createAsyncOptionsProvider(options: CMSGraphqlBaseModuleAsyncOptionsDto): Provider {
+    if (options.useFactory) {
+      return {
+        provide: CMS_BASE_GRAPHQL_MODULE_OPTIONS,
+        useFactory: options.useFactory,
+        inject: options.inject || [],
+      };
+    }
+
+    return {
+      provide: CMS_BASE_GRAPHQL_MODULE_OPTIONS,
+      useFactory: async (optionsFactory: CMSGraphqlBaseModuleOptionFactory) => await optionsFactory.createCMSOptions(),
+      inject: [(options.useExisting || options.useClass) as Type<CMSGraphqlBaseModuleOptionFactory>],
+    };
+  }
+}

package/src/constants/enum/base-action.enum.ts

@@ -0,0 +1,17 @@
+export enum BaseAction {
+  LIST = 'LIST',
+  READ = 'READ',
+  CREATE = 'CREATE',
+  UPDATE = 'UPDATE',
+  DELETE = 'DELETE',
+  DELETE_VERSION = 'DELETE_VERSION',
+
+  SUBMIT = 'SUBMIT',
+  PUT_BACK = 'PUT_BACK',
+
+  APPROVE = 'APPROVE',
+  REJECT = 'REJECT',
+
+  RELEASE = 'RELEASE',
+  WITHDRAW = 'WITHDRAW',
+}

package/src/constants/enum/base-resource.enum.ts

@@ -0,0 +1,4 @@
+export enum BaseResource {
+  ARTICLE = 'ARTICLE',
+  CATEGORY = 'CATEGORY',
+}

package/src/constants/option-providers.ts

@@ -0,0 +1,35 @@
+import { Provider } from '@nestjs/common';
+import {
+  CMS_BASE_GRAPHQL_MODULE_OPTIONS,
+  MAP_ARTICLE_CUSTOM_FIELDS_TO_ENTITY_COLUMNS,
+  MAP_CATEGORY_CUSTOM_FIELDS_TO_ENTITY_COLUMNS,
+} from '../typings/cms-graphql-base-providers';
+import { CMSGraphqlBaseModuleOptionsDto } from '../typings/cms-graphql-base-root-module-options.dto';
+import { CustomFieldInput } from '../dto/custom-field.input';
+
+export const OptionProviders = [
+  {
+    provide: MAP_ARTICLE_CUSTOM_FIELDS_TO_ENTITY_COLUMNS,
+    useFactory: async (
+      options?: CMSGraphqlBaseModuleOptionsDto,
+    ): Promise<
+      (customFields: CustomFieldInput[]) => Promise<Record<string, string | object>> | Record<string, string | object>
+    > =>
+      options?.mapArticleCustomFieldsToEntityColumns
+        ? options.mapArticleCustomFieldsToEntityColumns
+        : (): Record<string, string | object> => ({}),
+    inject: [CMS_BASE_GRAPHQL_MODULE_OPTIONS],
+  },
+  {
+    provide: MAP_CATEGORY_CUSTOM_FIELDS_TO_ENTITY_COLUMNS,
+    useFactory: async (
+      options?: CMSGraphqlBaseModuleOptionsDto,
+    ): Promise<
+      (customFields: CustomFieldInput[]) => Promise<Record<string, string | object>> | Record<string, string | object>
+    > =>
+      options?.mapCategoryCustomFieldsToEntityColumns
+        ? options.mapCategoryCustomFieldsToEntityColumns
+        : (): Record<string, string | object> => ({}),
+    inject: [CMS_BASE_GRAPHQL_MODULE_OPTIONS],
+  },
+] as Provider[];

package/src/data-loaders/article.dataloader.ts

@@ -0,0 +1,84 @@
+import { Inject, Injectable } from '@nestjs/common';
+import DataLoader from 'dataloader';
+import { Repository } from 'typeorm';
+import { LRUCache } from 'lru-cache';
+import { BaseArticleEntity, DEFAULT_LANGUAGE, RESOLVED_ARTICLE_REPO } from '@rytass/cms-base-nestjs-module';
+import { CategoryDto } from '../dto/category.dto';
+
+@Injectable()
+export class ArticleDataLoader {
+  constructor(
+    @Inject(RESOLVED_ARTICLE_REPO)
+    private readonly articleRepo: Repository<BaseArticleEntity>,
+  ) {}
+
+  private readonly batchLoadCategories = async (
+    queryArgs: readonly {
+      articleId: string;
+      language?: string;
+    }[],
+  ): Promise<CategoryDto[][]> => {
+    const qb = this.articleRepo.createQueryBuilder('articles');
+
+    qb.leftJoinAndSelect('articles.categories', 'categories');
+    qb.leftJoinAndSelect('categories.multiLanguageNames', 'multiLanguageNames');
+
+    qb.andWhere('articles.id IN (:...ids)', {
+      ids: queryArgs.map(arg => arg.articleId),
+    });
+
+    const articles = await qb.getMany();
+
+    const categoryMap = articles.reduce<Record<string, CategoryDto[]>>(
+      (vars, article) =>
+        article.categories.reduce(
+          (cVars, category) =>
+            category.multiLanguageNames.reduce(
+              (mVars, multiLanguageName) => ({
+                ...mVars,
+                [`${article.id}:${multiLanguageName.language}`]: [
+                  ...(mVars[`${article.id}:${multiLanguageName.language}`] || []),
+                  {
+                    ...category,
+                    ...multiLanguageName,
+                  },
+                ],
+              }),
+              cVars,
+            ),
+          vars,
+        ),
+      {},
+    );
+
+    return queryArgs.map(arg => categoryMap[`${arg.articleId}:${arg.language ?? DEFAULT_LANGUAGE}`] ?? []);
+  };
+
+  readonly categoriesLoader = new DataLoader<
+    {
+      articleId: string;
+      language?: string;
+    },
+    CategoryDto[],
+    string
+  >(this.batchLoadCategories, {
+    cache: true,
+    cacheMap: new LRUCache<string, Promise<CategoryDto[]>>({
+      ttl: 1000 * 60, // 1 minute
+      ttlAutopurge: true,
+      max: 1000,
+    }),
+    cacheKeyFn: (queryArgs): string => `${queryArgs.articleId}:${queryArgs.language ?? DEFAULT_LANGUAGE}`,
+  });
+
+  readonly categoriesLoaderNoCache = new DataLoader<
+    {
+      articleId: string;
+      language?: string;
+    },
+    CategoryDto[],
+    string
+  >(this.batchLoadCategories, {
+    cache: false,
+  });
+}

package/src/data-loaders/members.dataloader.ts

@@ -0,0 +1,36 @@
+import { Inject, Injectable } from '@nestjs/common';
+import { BaseMemberEntity, RESOLVED_MEMBER_REPO } from '@rytass/member-base-nestjs-module';
+import DataLoader from 'dataloader';
+import { LRUCache } from 'lru-cache';
+import { Repository } from 'typeorm';
+
+@Injectable()
+export class MemberDataLoader {
+  constructor(
+    @Inject(RESOLVED_MEMBER_REPO)
+    private readonly memberRepo: Repository<BaseMemberEntity>,
+  ) {}
+
+  readonly loader = new DataLoader<string, BaseMemberEntity | null>(
+    async (ids): Promise<(BaseMemberEntity | null)[]> => {
+      const qb = this.memberRepo.createQueryBuilder('members');
+
+      qb.withDeleted();
+      qb.andWhere('members.id IN (:...ids)', { ids });
+
+      const users = await qb.getMany();
+
+      const userMap = new Map(users.map(user => [user.id, user]));
+
+      return ids.map(id => userMap.get(id) ?? null);
+    },
+    {
+      cache: true,
+      cacheMap: new LRUCache<string, Promise<BaseMemberEntity | null>>({
+        ttl: 1000 * 60 * 10, // 10 minutes
+        ttlAutopurge: true,
+        max: 1000,
+      }),
+    },
+  );
+}