@postxl/generators 0.2.2

package/dist/backend-core/template/libs/e2e/src/e2e.controller.ts

@@ -0,0 +1,30 @@
+import { Controller, Get, Logger, Put, Res } from '@nestjs/common'
+
+import { FastifyReply } from 'fastify'
+
+import { TestDataService } from './test-data.service'
+
+@Controller('test')
+export class E2EController {
+  private readonly logger = new Logger(E2EController.name)
+  constructor(private readonly testData: TestDataService) {}
+
+  @Put('reset')
+  reset(@Res({ passthrough: true }) res: FastifyReply): void {
+    if (this.testData.config.isStateful === false) {
+      res.status(404).send('Cannot reset stateless backend')
+      return
+    }
+
+    this.testData.resetTestData()
+
+    res.status(200).send('OK')
+  }
+
+  @Get('mode')
+  getMode(): { mode: string } {
+    const backendMode = this.testData.config.isStateful ? 'stateful' : 'stateless'
+
+    return { mode: backendMode }
+  }
+}

package/dist/backend-core/template/libs/e2e/src/e2e.module.ts

@@ -0,0 +1,18 @@
+import { DynamicModule } from '@nestjs/common'
+
+import { TestConfig_Test } from 'apps/api/src/api.config'
+
+import { E2EController } from './e2e.controller'
+import { provideTestDataService } from './test-data.service'
+
+export class E2EModule {
+  static forRoot(config: TestConfig_Test): DynamicModule {
+    return {
+      module: E2EModule,
+      imports: [],
+      controllers: [E2EController],
+      providers: [provideTestDataService(config)],
+      exports: [],
+    }
+  }
+}

package/dist/backend-core/template/libs/e2e/src/test-data.service.ts

@@ -0,0 +1,20 @@
+import { Logger, Provider } from '@nestjs/common'
+
+import { TestConfig_Test } from 'apps/api/src/api.config'
+
+export class TestDataService {
+  private logger = new Logger(TestDataService.name)
+
+  constructor(public readonly config: TestConfig_Test) {}
+  public resetTestData() {
+    if (!this.config.isStateful) {
+      throw new Error('TestDataService.resetTestData() was called but should not have been!')
+    }
+    this.logger.log('✅ Reset test data')
+  }
+}
+
+export const provideTestDataService = (testConfig: TestConfig_Test): Provider<TestDataService> => ({
+  provide: TestDataService,
+  useValue: new TestDataService(testConfig),
+})

package/dist/backend-core/template/libs/utils/src/pagination.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from '@jest/globals'
+
+import { DEFAULT_PAGINATION, paginate, Pagination, paginationDecoder } from './pagination'
+
+describe('paginate function', () => {
+  const mockData = [1, 2, 3, 4, 5]
+
+  it('should return empty data with total 0 if input data is empty', () => {
+    const pagination: Pagination = { cursor: 1, limit: 10 }
+    const result = paginate([], pagination)
+    expect(result.data).toEqual([])
+    expect(result.total).toBe(0)
+    expect(result.currentPage).toBe(1)
+    expect(result.perPage).toBe(10)
+    expect(result.cursor).toBeNull()
+  })
+
+  it('should paginate data correctly with cursor and limit', () => {
+    const pagination: Pagination = { cursor: 2, limit: 2 }
+    const result = paginate(mockData, pagination)
+    expect(result.data).toEqual([3, 4])
+    expect(result.total).toBe(5)
+    expect(result.currentPage).toBe(2)
+    expect(result.perPage).toBe(2)
+    expect(result.cursor).toBe(3)
+  })
+
+  it('should paginate data correctly when reaching the end', () => {
+    const pagination: Pagination = { cursor: 3, limit: 2 }
+    const result = paginate(mockData, pagination)
+    expect(result.data).toEqual([5])
+    expect(result.total).toBe(5)
+    expect(result.currentPage).toBe(3)
+    expect(result.perPage).toBe(2)
+    expect(result.cursor).toBeNull()
+  })
+})
+
+describe('paginationDecoder', () => {
+  it('should validate and parse valid pagination object', () => {
+    const validPagination = { cursor: 1, limit: 10 }
+    const parsed = paginationDecoder.parse(validPagination)
+    expect(parsed.cursor).toBe(1)
+    expect(parsed.limit).toBe(10)
+  })
+
+  it('should use default limit if not provided', () => {
+    const validPagination = { cursor: 1 }
+    const parsed = paginationDecoder.parse(validPagination)
+    expect(parsed.cursor).toBe(1)
+    expect(parsed.limit).toBe(DEFAULT_PAGINATION.limit)
+  })
+
+  it('should throw error on invalid pagination object', () => {
+    const invalidPagination = { cursor: 1, limit: -10 }
+    expect(() => paginationDecoder.parse(invalidPagination)).toThrowError()
+  })
+})

package/dist/backend-core/template/libs/utils/src/pagination.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod'
+
+export const LIMIT_ALL = -1
+
+export type Pagination = {
+  /**
+   * The cursor is the page number that the user is currently on.
+   *
+   * NOTE: We do not use the term "page" because React Query/tRPC standardizes on "cursor" - see https://trpc.io/docs/client/react/useInfiniteQuery
+   */
+  cursor: number
+  /**
+   * The number of items per page.
+   */
+  limit: number
+}
+export const DEFAULT_PAGINATION: Pagination = { cursor: 1, limit: 100 }
+
+export const paginationDecoder = z.object({
+  cursor: z.number().int().nonnegative().optional().default(1),
+  limit: z.number().int().positive().optional().default(DEFAULT_PAGINATION.limit),
+})
+
+export const paginationDecoderFromQuery = z.object({
+  cursor: z.coerce.number().int().nonnegative().optional().default(1),
+  limit: z.coerce.number().int().positive().optional().default(DEFAULT_PAGINATION.limit),
+})
+
+export type PaginatedResult<T> = {
+  data: T[]
+  total: number
+  currentPage: number
+  perPage: number
+  cursor: number | null
+}
+
+export const paginatedResultDecoder = <T extends z.ZodTypeAny>(itemSchema: T) =>
+  z.object({
+    data: z.array(itemSchema),
+    total: z.number(),
+    currentPage: z.number(),
+    perPage: z.number(),
+    cursor: z.number().nullable(),
+  })
+
+export function paginate<T>(data: T[], pagination: Pagination): PaginatedResult<T> {
+  if (data.length === 0) {
+    return {
+      data: [],
+      total: 0,
+      perPage: pagination.limit,
+      currentPage: pagination.cursor,
+      cursor: null,
+    }
+  }
+
+  const paginatedData =
+    pagination.limit === LIMIT_ALL
+      ? data
+      : data.slice((pagination.cursor - 1) * pagination.limit, pagination.cursor * pagination.limit)
+  return {
+    data: paginatedData,
+    total: data.length,
+    perPage: pagination.limit,
+    currentPage: pagination.cursor,
+    cursor: pagination.cursor * pagination.limit < data.length ? pagination.cursor + 1 : null,
+  }
+}

package/dist/backend-core/template/libs/utils/tsconfig.lib.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "outDir": "../../dist/libs/utils"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test", "**/*spec.ts"]
+}

package/dist/backend-core/template/libs/xlport/README.md

@@ -0,0 +1,90 @@
+# xlPort library
+
+This library is a wrapper for xlport - the API we are using to export and import data to and from Excel.
+
+It provides the `XlPortService` which can be used by any other module. The service provides the following methods:
+
+- `exportToFile` - exports data to Excel
+- `importFromFile` - imports data from Excel
+- `replaceBlankTables` - replaces blank tables from an Excel import with blank arrays
+- `replaceBlankStringsWithNull` - Helper function to replace blank strings with null values (as Excel does not allow null values as formula results)
+
+## Usage
+
+### Export
+
+Here is a typical controller method to export data to Excel:
+
+```typescript
+@Get('export/:id')
+async export(@Res({ passthrough: true }) response: FastifyReply, @Param('id') id: string) {
+  
+  const data = await this.getData(id)
+
+  const request: Export.TemplateIdBody = {
+    // NOTE: The template must be uploaded to xlport's templates folder
+    templateId: 'project/template.xlsx',
+    data,
+  }
+
+  // NOTE: Change this to mimeTypes.xlsm in case template contains macros
+  const returnType = mimeTypes.xlsx
+  const filename = `${timeStamp()} ${submission.name}`
+  
+  void response.type(returnType)
+  void response.header('Content-Disposition', `attachment; filename=${filename}.{returnType === mimeTypes.xlsx ? 'xlsx' : 'xlsm'}`)
+  return this.xlPort.exportToFile(request)
+}
+```
+
+### Import
+
+```typescript
+@Post('/import/:id')
+@UseGuards(UploadAndLogGuard)
+@UseGuards(AuthGuard)
+async importSurveyForParticipant(
+  @Param('id') id: string,
+  @Req() req: FastifyRequestWithFileAndId,
+  @FileStream() file: MultipartFile,
+  @UserParam() user: User,
+): Promise<SubmissionImportResult> {
+  
+  if (!file) {
+    throw new BadRequestException('No attachment was provided')
+  }
+
+  const start = Date.now()
+  const xlData = await this.xlPort.importFromFile(await file.toBuffer())
+
+  if (xlData.status !== 'success') {
+    this.logger.warn(xlData.message)
+    throw new Error(`Error in reading Excel data: ${JSON.stringify(xlData.message)}`)
+  }
+
+  // NOTE: You need to provide a decoder for your data
+  const dataParsed = decoder.safeParse(
+    this.xlPort.replaceBlankTables(this.xlPort.replaceBlankStringsWithNull(xlData.data.tables)),
+  )
+  
+  if (!dataParsed.success) {
+    this.logger.warn(dataParsed.error.format())
+    throw new Error(`Error in parsing Excel data: ${JSON.stringify(dataParsed.error.flatten())}`)
+  }
+  this.logger.log(dataParsed.data)
+
+  const result = await this.handleImport({
+    data: dataParsed.data,
+    user,
+  })
+
+  if (result.type === 'error') {
+    this.logger.error(
+      `Error importing data for (${id}) in ${file.filename}: ${JSON.stringify(result.error)}`,
+    )
+    return result
+  }
+
+  return result
+}
+```

package/dist/backend-core/template/libs/xlport/src/xlport.config.ts

@@ -0,0 +1,8 @@
+export type Config = {
+  readonly apiKey: string
+  readonly url?: string
+}
+
+export class XlPortConfig {
+  constructor(public readonly config: Config) {}
+}

package/dist/backend-core/template/libs/xlport/src/xlport.module.ts

@@ -0,0 +1,20 @@
+import { DynamicModule, Provider } from '@nestjs/common'
+
+import { Config, XlPortConfig } from './xlport.config'
+import { XlPortService } from './xlport.service'
+
+export class XlPortModule {
+  static forRoot(config: Config): DynamicModule {
+    const configProvider: Provider = {
+      provide: XlPortConfig,
+      useFactory: () => new XlPortConfig(config),
+    }
+    return {
+      module: XlPortModule,
+      imports: [],
+      providers: [configProvider, XlPortService],
+      exports: [XlPortService],
+      global: true,
+    }
+  }
+}

package/dist/backend-core/template/libs/xlport/src/xlport.service.ts

@@ -0,0 +1,171 @@
+import { Injectable } from '@nestjs/common'
+
+import { Client, Export, Import } from 'xlport'
+
+import { XlPortConfig } from './xlport.config'
+
+@Injectable()
+export class XlPortService {
+  private readonly client: Client
+
+  constructor(config: XlPortConfig) {
+    this.client = new Client({ apiKey: config.config.apiKey, url: config.config.url })
+  }
+
+  /**
+   * Loads data from an Excel file and returns the result.
+   *
+   * ## Example:
+   * Here is a typical controller method that uses this function:
+   *
+   * ```typescript
+   * \@Post('/import/:id')
+   * \@UseGuards(UploadAndLogGuard)
+   * \@UseGuards(AuthGuard)
+   * async importSurveyForParticipant(
+   *   \@Param('id') id: string,
+   *   \@Req() req: FastifyRequestWithFileAndId,
+   *   \@FileStream() file: MultipartFile,
+   *   \@UserParam() user: User,
+   * ): Promise<SubmissionImportResult> {
+   *
+   *   if (!file) {
+   *     throw new BadRequestException('No attachment was provided')
+   *   }
+   *
+   *   const start = Date.now()
+   *   const xlData = await this.xlPort.importFromFile(await file.toBuffer())
+   *
+   *   if (xlData.status !== 'success') {
+   *     this.logger.warn(xlData.message)
+   *     throw new Error(`Error in reading Excel data: ${JSON.stringify(xlData.message)}`)
+   *   }
+   *
+   *   // NOTE: You need to provide a decoder for your data
+   *   const dataParsed = decoder.safeParse(
+   *     this.xlPort.replaceBlankTables(this.xlPort.replaceBlankStringsWithNull(xlData.data.tables)),
+   *   )
+   *
+   *   if (!dataParsed.success) {
+   *     this.logger.warn(dataParsed.error.format())
+   *     throw new Error(`Error in parsing Excel data: ${JSON.stringify(dataParsed.error.flatten())}`)
+   *   }
+   *   this.logger.log(dataParsed.data)
+   *
+   *   const result = await this.handleImport({
+   *     data: dataParsed.data,
+   *     user,
+   *   })
+   *
+   *   if (result.type === 'error') {
+   *     this.logger.error(
+   *       `Error importing data for (${id}) in ${file.filename}: ${JSON.stringify(result.error)}`,
+   *     )
+   *     return result
+   *   }
+   *
+   *   return result
+   * }
+   * ```
+   */
+  public async importFromFile(file: string | Buffer, request?: Import.Request) {
+    return this.client.importFromFile(file, request)
+  }
+
+  /**
+   * Loads data into an Excel template and returns the result as a file.
+   *
+   * ## Example:
+   * Here is a typical controller method that uses this function:
+   *
+   * ```typescript
+   * \@Get('export/:id')
+   * async export(@Res({ passthrough: true }) response: FastifyReply, \@Param('id') id: string) {
+   *
+   *   const data = await this.getData(id)
+   *
+   *   const request: Export.TemplateIdBody = {
+   *     // NOTE: The template must be uploaded to xlport's templates folder
+   *     templateId: 'project/template.xlsx',
+   *     data,
+   *   }
+   *
+   *   // NOTE: Change this to mimeTypes.xlsm in case template contains macros
+   *   const returnType = mimeTypes.xlsx
+   *   const filename = `${timeStamp()} ${submission.name}`
+   *
+   *   void response.type(returnType)
+   *   void response.header('Content-Disposition', `attachment; filename=${filename}.{returnType === mimeTypes.xlsx ? 'xlsx' : 'xlsm'}`)
+   *   return this.xlPort.exportToFile(request)
+   * }
+   * ```
+   */
+  public exportToFile(body: Export.Body) {
+    return this.client.exportToFile(body)
+  }
+
+  /**
+   * Replaces blank tables with empty arrays.
+   *
+   * A blank table in Excel still always has one row that is empty.
+   * xlPort will return this row as an object with each field as null.
+   * This function replaces these tables with blank arrays.
+   *
+   * Known shortcoming: This function will not replace tables if the table
+   * has calculated columns that return non-null values by default!
+   * This case must be accounted for manually.
+   */
+  public replaceBlankTables(body: Import.Data['tables']): Import.Data['tables'] {
+    if (!body) {
+      return body
+    }
+
+    for (const [key, table] of Object.entries(body)) {
+      // we are only interested in tables that have exactly one row
+      if (table.length !== 1) {
+        continue
+      }
+      // we currently only support tables with objects as rows
+      if (!Array.isArray(table)) {
+        continue
+      }
+
+      const row = table[0] as object
+      if (Object.values(row).every((value) => value === null)) {
+        body[key] = []
+      }
+    }
+    return body
+  }
+
+  /**
+   * Replaces blank strings with null.
+   *
+   * Excel does not allow formula expressions to return null.
+   * Instead, one often returns a blank string.
+   * However, this distorts the decoders for any non-string types.
+   */
+  public replaceBlankStringsWithNull(body: Import.Data['tables'], tablesToReplace?: string[]): Import.Data['tables'] {
+    if (!body) {
+      return body
+    }
+
+    for (const [key, table] of Object.entries(body)) {
+      if (tablesToReplace && !tablesToReplace.includes(key)) {
+        continue
+      }
+      // we currently only support tables with objects as rows
+      if (!Array.isArray(table)) {
+        continue
+      }
+      for (const row of table) {
+        for (const [field, value] of Object.entries(row)) {
+          if (typeof value === 'string' && value.trim() === '') {
+            row[field] = null
+          }
+        }
+      }
+    }
+    return body
+  }
+}

package/dist/backend-core/template/libs/xlport/tsconfig.lib.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "outDir": "../../dist/libs/xlport"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "test", "**/*spec.ts"]
+}

package/dist/backend-core/template/nest-cli.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "apps/api/src",
+  "compilerOptions": {
+    "webpack": false,
+    "tsConfigPath": "apps/api/tsconfig.app.json"
+  },
+  "monorepo": true,
+  "root": "apps/api",
+  "projects": {
+    "api": {
+      "type": "application",
+      "root": "apps/api",
+      "entryFile": "main",
+      "sourceRoot": "apps/api/src",
+      "compilerOptions": {
+        "tsConfigPath": "apps/api/tsconfig.app.json"
+      }
+    }
+  }
+}

package/dist/backend-core/template/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["node_modules", "test", "dist", "**/*spec.ts"]
+}

package/dist/backend-core/types.d.ts

@@ -0,0 +1,145 @@
+import * as Generator from '@postxl/generator';
+export type WithBackend<Context extends Generator.Context = Generator.Context> = Generator.ExtendContext<Context, {
+    /**
+     * The global configuration for the NestJS generator.
+     *
+     * Allows to register NestJS modules and npm dependencies for backend projects.
+     */
+    backend: BackendContextEntry;
+}>;
+/**
+ * The global configuration for the NestJS generator.
+ *
+ * Allows to register NestJS modules and npm dependencies for backend projects.
+ */
+export type BackendContextEntry = {
+    /**
+     * Contains references to all modules that should be registered in addition to the default modules.
+     */
+    modules: NestJSModule[];
+    packageJson: Generator.PackageJsonConfig;
+    /**
+     * Any additional tsconfig references that should be added to the main tsconfig.json file.
+     */
+    tsConfigReferences: string[];
+};
+/**
+ * A NestJS module that should be registered in the app.
+ */
+export type NestJSModule = {
+    /**
+     * The name of the module.
+     *
+     * Example: `s3`
+     */
+    name: Generator.BackendModuleName;
+    /**
+     * Indicates if the generated module exposes an index.ts file.
+     */
+    hasIndex?: boolean;
+    /**
+     * If the module provides a Module class, this contains the class name and import location.
+     *
+     * Most modules will have a module class and need to be injected - however, the `@types` module
+     * only exposes the types and does not need to be injected, hence it is optional.
+     */
+    moduleClass?: Generator.ImportableItem;
+    /**
+     * NestJS Module registration statement to register the module with NestJS's dependency injection.
+     */
+    apiModuleRegistration?: {
+        /**
+         * The import code for the module.
+         *
+         * If not provided, it will be derived from the `name` and `importLocation` property.
+         * This should be used for more complicated imports, for instance:
+         * ```
+         * import { DatabaseModule } from '@database/database.module'
+         * import { DatabaseConfigModule } from '@database/database.config'
+         * ```
+         */
+        import?: Generator.Typescript;
+        /**
+         * NestJS Module registration statement to register the module with NestJS's dependency injection.
+         *
+         * Example: `S3Module.forRoot()`
+         *
+         * If not provided, the default will be the className
+         */
+        code?: Generator.Typescript;
+        provider?: Generator.Typescript[];
+    };
+    /**
+     * In case the module requires a env configuration, this is the decoder and transformer to use.
+     */
+    envConfig?: EnvConfig;
+    /**
+     * The code that should be executed when the app is bootstrapped.
+     *
+     * Example: `await app.get(TRPCPlugin).register(app)`
+     */
+    bootStrap?: {
+        /**
+         * The import statement that should be added to the main file.
+         *
+         * Example: `import { TRPCPlugin } from '@trpc/trpc.plugin'`
+         */
+        import: Generator.Typescript;
+        /**
+         * The code that should be executed when the app is bootstrapped.
+         *
+         * Example: `await app.get(TRPCPlugin).register(app)`
+         */
+        code: Generator.Typescript;
+    };
+    /**
+     * The libraries' generated code.
+     */
+    vfs?: Generator.VirtualFileSystem;
+};
+export type EnvConfig = {
+    /**
+     * Example:
+     *    AWS_ACCESS_KEY: z.string(),
+     *    AWS_SECRET_ACCESS_KEY: z.string(),
+     *    AWS_BUCKET: z.string(),
+     *    AWS_REGION: z.string(),
+     */
+    decoder: Generator.Typescript;
+    /**
+     * Example:
+     * aws: {
+     *      accessKey: val.AWS_ACCESS_KEY,
+     *      secretAccessKey: val.AWS_SECRET_ACCESS_KEY,
+     *      bucket: val.AWS_BUCKET,
+     *      region: val.AWS_REGION,
+     *    },
+     */
+    transformer: Generator.Typescript;
+    /**
+     * An example for the module's env configuration.
+     *
+     * Example:
+     * AWS_ACCESS_KEY=""
+     * AWS_SECRET_ACCESS_KEY=""
+     * AWS_BUCKET=""
+     * AWS_REGION="eu-central-1"
+     */
+    dotEnvExample: string;
+    /**
+     * Any config type definitions that the module should expose.
+     *
+     * Example:
+     * export type TestConfig = TestConfig_NoTest | TestConfig_Test
+     *     type TestConfig_NoTest = {
+     *       isTest: false
+     *     }
+     *
+     *     export type TestConfig_Test = {
+     *       isTest: true
+     *       isStateful: boolean
+     *     }
+     *   }
+     */
+    type?: Generator.Typescript;
+};

package/dist/backend-core/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/backend-core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/backend-core/types.ts"],"names":[],"mappings":""}