@mshima/generator-jhipster-nodejs 0.0.0-stage → 0.0.1

package/generators/node-server/templates/server/README.md.ejs

@@ -0,0 +1,269 @@
+<p align="center">
+  <a href="http://nestjs.com/" target="blank"><img src="https://nestjs.com/img/logo_text.svg" width="320" alt="Nest Logo" /></a>
+</p>
+
+[travis-image]: https://api.travis-ci.org/nestjs/nest.svg?branch=master
+[travis-url]: https://travis-ci.org/nestjs/nest
+[linux-image]: https://img.shields.io/travis/nestjs/nest/master.svg?label=linux
+[linux-url]: https://travis-ci.org/nestjs/nest
+
+  <p align="center">A progressive <a href="http://nodejs.org" target="blank">Node.js</a> framework for building efficient and scalable server-side applications, heavily inspired by <a href="https://angular.io" target="blank">Angular</a>.</p>
+    <p align="center">
+        <a href="https://www.npmjs.com/~nestjscore"><img src="https://img.shields.io/npm/v/@nestjs/core.svg" alt="NPM Version" /></a>
+        <a href="https://www.npmjs.com/~nestjscore"><img src="https://img.shields.io/npm/l/@nestjs/core.svg" alt="Package License" /></a>
+        <a href="https://www.npmjs.com/~nestjscore"><img src="https://img.shields.io/npm/dm/@nestjs/core.svg" alt="NPM Downloads" /></a>
+        <a href="https://travis-ci.org/nestjs/nest"><img src="https://api.travis-ci.org/nestjs/nest.svg?branch=master" alt="Travis" /></a>
+        <a href="https://travis-ci.org/nestjs/nest"><img src="https://img.shields.io/travis/nestjs/nest/master.svg?label=linux" alt="Linux" /></a>
+        <a href="https://coveralls.io/github/nestjs/nest?branch=master"><img src="https://coveralls.io/repos/github/nestjs/nest/badge.svg?branch=master#5" alt="Coverage" /></a>
+        <a href="https://discord.gg/G7Qnnhy" target="_blank"><img src="https://img.shields.io/badge/discord-online-brightgreen.svg" alt="Discord"/></a>
+        <a href="https://opencollective.com/nest#backer"><img src="https://opencollective.com/nest/backers/badge.svg" alt="Backers on Open Collective" /></a>
+        <a href="https://opencollective.com/nest#sponsor"><img src="https://opencollective.com/nest/sponsors/badge.svg" alt="Sponsors on Open Collective" /></a>
+          <a href="https://paypal.me/kamilmysliwiec"><img src="https://img.shields.io/badge/Donate-PayPal-dc3d53.svg"/></a>
+          <a href="https://twitter.com/nestframework"><img src="https://img.shields.io/twitter/follow/nestframework.svg?style=social&label=Follow"></a>
+        </p>
+          <!--[![Backers on Open Collective](https://opencollective.com/nest/backers/badge.svg)](https://opencollective.com/nest#backer)
+          [![Sponsors on Open Collective](https://opencollective.com/nest/sponsors/badge.svg)](https://opencollective.com/nest#sponsor)-->
+
+## Description
+
+[NestJS Framework](https://github.com/nestjs/nest) server project generated from official [JHipster NodeJS blueprint](https://github.com/jhipster/generator-jhipster-nodejs).
+
+## Installation
+
+```bash
+$ npm install
+```
+
+## Project structure
+
+The server is organized by feature, like the modules NestJS generates (`nest g resource`): each feature folder of `src`
+has its module, its controllers, its services, its entities and its DTOs, the unit tests (`*.spec.ts`) next to the code
+they test, the end-to-end tests in `e2e`.
+
+- `src/entities/<entity>/`: an entity of the JDL, its TypeORM entity, its DTO (`dto/`), its mapper, its service, its
+  REST controller and its module; `src/entities/enumeration/` the enumerations of the entities.
+<%_ if (generateBuiltInUserEntity) { _%>
+- `src/users/`: the users and their authorities, their administration API.
+<%_ } _%>
+- `src/auth/`: the authentication, its guards, its decorators, its strategies and the account API.
+<%_ if (generateUserManagement) { _%>
+- `src/mail/`: the emails of the user management.
+<%_ } _%>
+- `src/management/`: the management endpoints (health, metrics, loggers, configuration, API documentation).
+<%_ if (serviceDiscoveryAny) { _%>
+- `src/registry/`: the registration of the service in its registry.
+<%_ } _%>
+- `src/common/`: the helpers of every feature: the errors, the HTTP helpers, the base entity and the column types
+  (`database/`), the base DTO.
+- `src/config/`: the configuration of each profile; `src/migrations/`: the migrations of the database schema.
+
+## TypeORM configuration
+
+### The database of each profile
+
+The database of each profile is the `database` section of its configuration file, read by
+[src/orm.config.ts](src/orm.config.ts) (the TypeORM options):
+
+- [src/config/application-dev.yml](src/config/application-dev.yml): the database of development, the one of the
+  `docker` folder<% if (databaseTypeSql) { %> (or a SQLite file)<% } %>;
+- [src/config/application-test.yml](src/config/application-test.yml): <%= databaseTypeSql ? 'an in-memory SQLite database' : 'an in-memory MongoDB server' %> for the tests;
+- [src/config/application-prod.yml](src/config/application-prod.yml): the production database, the service of the
+  docker compose files by default.
+
+```yaml
+database:
+  type: <%= nodeProdDatabaseType %>
+  host: localhost
+  port: 5432
+  username: YOUR_USER
+  password: 'YOUR_PASSWORD'
+  name: YOUR_DATABASE_NAME
+  logging: false
+```
+
+Like every property, an environment variable overrides them: `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_USERNAME`,
+`DATABASE_PASSWORD`, `DATABASE_NAME`. Keep the production password out of the file this way.
+
+### Configuration from environment variables
+
+Like in a Spring Boot application, an environment variable overrides a property of the `src/config/application*.yml`
+files: its name is the property in upper case, with the dots as underscores and the dashes removed (or as
+underscores). For example, `JHIPSTER_MAIL_BASEURL` sets `jhipster.mail.base-url`. Secrets, like the JWT secret, can
+be kept out of the configuration files this way in production.
+
+### Migration data and schema
+
+According [typeORM migration guide](https://github.com/typeorm/typeorm/blob/master/docs/migrations.md),
+there are under [src/migrations/](src/migrations/) the scripts to create the database schema and after to insert data seed.
+The application runs the ones not run yet at startup, in the order of the timestamp of their name.
+<%_ if (databaseTypeSql) { _%>
+
+Like the Liquibase changelogs of JHipster Spring Boot, JHipster generates the migrations of the schema: `CreateTables`
+creates the tables of the users and of the authorities, then each entity has the migration adding its table
+(`<timestamp>-AddedEntity<Entity>.ts`, the timestamp of its `changelogDate`) and, when it has relationships, the one adding
+its foreign keys and its join tables (`<timestamp>-AddedEntityConstraints<Entity>.ts`, its timestamp plus 3000000000000),
+run after the tables of every entity, like the constraints changelogs of Liquibase. A database the application ran them
+on already is not changed by a regeneration of a migration: when an entity changes, add the migration of the change
+(`npm run typeorm:migration:generate`) or recreate the development database. Like the Liquibase changelogs without
+incremental changelogs, a regeneration rewrites the migrations of the entity changed (a new column in the migration of its
+table): restore the migrations a database ran already (`git restore src/migrations`), keeping the entities, before
+generating the migration of the change, so an empty database runs them all.
+
+The application runs the migrations [src/orm.config.ts](src/orm.config.ts) lists: import the class of a migration of
+your own and add it to `migrations`, so the application runs it at startup, like the ones JHipster adds. The
+`typeorm:migration:run` script runs every migration of the `src/migrations` folder (built in `dist/migrations`).
+
+TypeORM runs the migrations in the order of the timestamp ending their class name. The `typeorm:migration:create` and
+`typeorm:migration:generate` scripts give a migration of your own its time plus <%= nodejsMigrationTimestampOffset %>
+(see [typeorm-migration.ts](typeorm-migration.ts)), so it runs after the migrations JHipster generates for the entities,
+on an empty database too, like the changelogs added at the end of the `master.xml` of Liquibase.
+<%_ } _%>
+
+The `typeorm` npm scripts build the server and run the typeorm CLI on the database `BACKEND_ENV` selects (see
+[ormconfig.ts](ormconfig.ts)):
+
+```bash
+<%_ if (databaseTypeSql) { _%>
+# generate a migration from the changes of the entities
+$ npm run typeorm:migration:generate
+<%_ } _%>
+# create an empty migration
+$ npm run typeorm:migration:create
+# run, revert or list the migrations
+$ npm run typeorm:migration:run
+$ npm run typeorm:migration:revert
+$ npm run typeorm:migration:show
+<%_ if (databaseTypeSql) { _%>
+# show the SQL that would synchronize the schema with the entities
+$ npm run typeorm:schema:log
+<%_ } _%>
+```
+<%_ if (databaseTypeMongodb) { _%>
+
+With MongoDB, they run on the MongoDB of the dev profile (`npm run docker:db:up`), the test profile using an in-memory server. MongoDB has no
+schema to compare, so migrations are written by hand with the MongoDB API (`queryRunner.query()` does not support
+MongoDB): use `queryRunner.dataSource.mongoManager`.
+<%_ } _%>
+
+## Running the app
+
+```bash
+# development
+$ npm run start
+
+# watch mode
+$ npm run start:dev
+
+# build transpiling files in javascript
+$ npm run build
+
+# run javascript build from the source project
+$ npm run start:prod
+
+# run javascript build with node
+$ node dist/main.js
+```
+
+### Development profile and .env file
+
+The development scripts (`npm start`, `npm run start:dev`, `npm run start:debug`) run with the **BACKEND_ENV** of the
+[.env.dev](.env.dev) file, **dev**: the dev database and settings, the sample secrets and the API documentation. The
+built application (`npm run start:prod`, `node dist/main.js`, the Docker image) does not read it, like a Spring Boot jar
+built with the prod profile: set **BACKEND_ENV** where it runs, like `prod`.
+
+An optional `.env` file, ignored by git, holds local settings, like secrets: the application loads it with
+[dotenv](https://www.npmjs.com/package/dotenv) when it exists. A variable set in the environment wins over both files.
+
+### Profiles
+
+Like `spring.profiles.active` in a Spring Boot application, **BACKEND_ENV** is a comma separated list of profiles, for
+example `prod,api-docs`. Each profile loads its `application-{profile}.yml` file of the [config folder](src/config), when
+there is one, in the order of the list (the last one wins), and the profiles of its group (`profiles.group` of
+[application.yml](src/config/application.yml)): `dev` activates `secret-samples` and `api-docs`, `test` activates
+`secret-samples`. The standard profiles are:
+
+- `dev`, `prod` and `test`: the database and the settings of each environment;
+- `api-docs`: the OpenAPI document of the API at `/v3/api-docs`, for the administrators like JHipster Spring Boot<%= skipClient ? '' : ', read by the API page of the client' %>;
+- `secret-samples`: samples of the secrets (<%= authenticationType === 'oauth2' ? 'the session secret and the OAuth2 client' : authenticationType === 'session' ? 'the session secret' : 'the JWT secret' %><%= databaseTypeSql ? ', the username and the password of the database' : '' %>) for development and CI, in
+  [application-secret-samples.yml](src/config/application-secret-samples.yml). In production, set them with environment
+  variables instead, like `<%= authenticationType === 'oauth2' ? 'JHIPSTER_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENTSECRET' : authenticationType === 'session' ? 'JHIPSTER_SECURITY_SESSION_SECRET' : 'JHIPSTER_SECURITY_AUTHENTICATION_JWT_BASE64SECRET' %>`;
+- `tls`: HTTPS, with your PKCS#12 keystore (`SERVER_SSL_KEY_STORE` and `SERVER_SSL_KEY_STORE_PASSWORD`);
+- `tls-samples`: with `tls`, the self-signed sample keystore of [src/config/tls](src/config/tls), for development only.
+
+> You can define your custom profiles, with an application-{profile}.yml file in your [config folder](src/config); an
+> environment of its own needs the `database` section of that environment.
+
+The `/management/info` endpoint gives the active profiles to the client, which shows its ribbon on the
+`info.display-ribbon-on-profiles` ones.
+
+**BACKEND_ENV** can also be set in the environment of the process.
+For example:
+
+```bash
+
+# development in prod environment, with the API documentation and the sample secrets
+# in linux
+$ BACKEND_ENV=prod,api-docs,secret-samples npm run start
+# in windows
+$ set BACKEND_ENV=prod,api-docs,secret-samples&& npm run start
+
+# run javascript build with node in prod environment
+# in linux
+$ BACKEND_ENV=prod node dist/main.js
+# in windows
+$ set BACKEND_ENV=prod&& node dist/main.js
+```
+
+## Lint
+
+```bash
+# run lint
+$ npm run lint
+
+# fix lint issues
+$ npm run lint:fix
+
+```
+
+## Debug
+
+```bash
+# run this and after you can execute debug task in VSCode
+$ npm run start:debug
+
+```
+
+## Test
+
+```bash
+# unit tests
+$ npm run test
+
+# lint
+$ npm run lint
+
+# fix lint issues
+$ npm run lint:fix
+
+# test coverage of unit tests
+$ npm run test:cov
+
+# e2e tests with full app coverage report
+$ npm run test:e2e
+
+```
+
+## Support
+
+Nest is an MIT-licensed open source project. It can grow thanks to the sponsors and support by the amazing backers. If you'd like to join them, please [read more here](https://docs.nestjs.com/support).
+
+## Stay in touch
+
+- Community - [jhipster homepage](https://www.jhipster.tech)
+- Stream Lead - [Angelo Manganiello](https://github.com/amanganiello90)
+- Website And Guide - [https://nestjs.com](https://nestjs.com/)
+- Twitter - [@nestframework](https://twitter.com/nestframework)
+
+## License
+
+Nest is [MIT licensed](LICENSE).

package/generators/node-server/templates/server/e2e/_entityFileName_.database.e2e-spec.ts.ejs

@@ -0,0 +1,192 @@
+<%_
+// The values of the fields as the API exchanges them, reproducible: the faker of the entity is seeded for this test.
+resetFakerSeed('nodejs-database-e2e');
+const created = nodejsApiFakeEntity();
+const updated = nodejsApiFakeEntity();
+const approximateFields = created.approximateFields;
+// The relationships of the entity with a join column or a join table (the persistableRelationships of JHipster): stored
+// by the id of the related record.
+const storedRelationships = databaseTypeSql ? persistableRelationships : [];
+const anyUserRelationship = storedRelationships.some(relationship => relationship.otherEntity.builtInUser);
+// The relationships the other entity stores (nodejsMappedByRelationships), with another entity of the application.
+const inverseRelationships = databaseTypeSql
+  ? nodejsMappedByRelationships.filter(relationship => !relationship.otherEntity.builtIn && relationship.otherRelationship?.propertyName)
+  : [];
+const literal = value => JSON.stringify(value);
+_%>
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { INestApplication } from '@nestjs/common';
+import { Test, TestingModule } from '@nestjs/testing';
+import request from 'supertest';
+<%_ if (anyUserRelationship) { _%>
+import { DataSource } from 'typeorm';
+<%_ } _%>
+
+import { AppModule } from '../src/app.module.ts';
+import { configureApp } from '../src/app.config.ts';
+<%_ if (anyUserRelationship) { _%>
+import { <%= user.persistClass %> } from '../src/users/user.entity.ts';
+<%_ } _%>
+import { AuthGuard } from '../src/auth/guards/auth.guard.ts';
+import { RolesGuard } from '../src/auth/guards/roles.guard.ts';
+
+/**
+ * <%= entityClass %> stored in the database and read back through the REST API, like the resource tests of JHipster
+ * Spring Boot: the values of every field as the API exchanges them<% if (storedRelationships.length > 0) { %>, and the relationships stored by the id of the related
+ * record, without changing it<% } %>.
+ */
+describe('<%= entityClass %> on the database', () => {
+  let app: INestApplication;
+
+  // The values of the fields, of a creation then of an update.
+  const createdValues: Record<string, any> = {
+<%_ for (const [name, value] of Object.entries(created.values)) { _%>
+    <%= name %>: <%- literal(value) %>,
+<%_ } _%>
+  };
+  const updatedValues: Record<string, any> = {
+<%_ for (const [name, value] of Object.entries(updated.values)) { _%>
+    <%= name %>: <%- literal(value) %>,
+<%_ } _%>
+  };
+
+  /** The values read back: a Float is approximate on the databases keeping it in single precision. */
+  const expected = (values: Record<string, any>): Record<string, any> => ({
+    ...values,
+<%_ for (const name of approximateFields) { _%>
+    <%= name %>: expect.closeTo(values.<%= name %>, 1),
+<%_ } _%>
+  });
+
+  beforeAll(async () => {
+    const moduleFixture: TestingModule = await Test.createTestingModule({
+      imports: [AppModule],
+    })
+      .overrideGuard(AuthGuard)
+      .useValue({ canActivate: () => true })
+      .overrideGuard(RolesGuard)
+      .useValue({ canActivate: () => true })
+      .compile();
+
+    app = moduleFixture.createNestApplication();
+    configureApp(app);
+    await app.init();
+  });
+
+  afterAll(async () => {
+    await app?.close();
+  });
+
+  it('should store every field and read it back, then update and delete it', async () => {
+    const server = app.getHttpServer();
+    const { body: stored } = await request(server).post('/api/<%= entityApiUrl %>').send(createdValues).expect(201);
+    const { body: read } = await request(server).get(`/api/<%= entityApiUrl %>/${stored.<%= primaryKey.name %>}`).expect(200);
+    expect(read).toMatchObject(expected(createdValues));
+
+    await request(server)
+      .put(`/api/<%= entityApiUrl %>/${stored.<%= primaryKey.name %>}`)
+      .send({ ...updatedValues, <%= primaryKey.name %>: stored.<%= primaryKey.name %> })
+      .expect(200);
+    const { body: readUpdated } = await request(server).get(`/api/<%= entityApiUrl %>/${stored.<%= primaryKey.name %>}`).expect(200);
+    expect(readUpdated).toMatchObject(expected(updatedValues));
+
+    await request(server).delete(`/api/<%= entityApiUrl %>/${stored.<%= primaryKey.name %>}`).expect(204);
+    await request(server).get(`/api/<%= entityApiUrl %>/${stored.<%= primaryKey.name %>}`).expect(404);
+  });
+<%_ for (const relationship of storedRelationships) {
+    const otherEntity = relationship.otherEntity;
+    const otherId = otherEntity.primaryKey.name;
+    const collection = relationship.relationshipType === 'many-to-many';
+    const property = relationship.propertyName;
+    const otherValues = relationship.nodejsRelatedValues;
+    // A text field of the related record, sent changed with its id: the relationship does not store it (no cascade).
+    const otherTextField = otherValues && otherEntity.fields.find(field => !field.id && field.fieldType === 'String' && field.fieldName in otherValues);
+_%>
+
+  it('should store the <%= property %> relationship by the id of the related record, without changing it', async () => {
+    const server = app.getHttpServer();
+<%_ if (otherEntity.builtInUser) { _%>
+    // A user of this test: the applications without seed users (OAuth2) have none.
+    const users = app.get(DataSource).getRepository(<%= user.persistClass %>);
+    const related = await users.save(
+      users.create({
+        login: '<%= entityInstance.toLowerCase() %>-<%= property.toLowerCase() %>-e2e',
+        email: '<%= entityInstance.toLowerCase() %>-<%= property.toLowerCase() %>-e2e@localhost',
+        password: '',
+        activationKey: 'e2e-activation-key',
+        resetKey: 'e2e-reset-key',
+      }),
+    );
+<%_ } else { _%>
+    const relatedValues: Record<string, any> = <%- literal(otherValues) %>;
+    const { body: related } = await request(server).post('/api/<%= otherEntity.entityApiUrl %>').send(relatedValues).expect(201);
+<%_ } _%>
+<%_ if (otherTextField) { _%>
+    const reference = { <%= otherId %>: related.<%= otherId %>, <%= otherTextField.fieldName %>: 'not stored through the relationship' };
+<%_ } else { _%>
+    const reference = { <%= otherId %>: related.<%= otherId %> };
+<%_ } _%>
+    const { body: stored } = await request(server)
+      .post('/api/<%= entityApiUrl %>')
+      .send({ ...createdValues, <%= property %>: <%- collection ? '[reference]' : 'reference' %> })
+      .expect(201);
+
+    const { body: read } = await request(server).get(`/api/<%= entityApiUrl %>/${stored.<%= primaryKey.name %>}`).expect(200);
+<%_ if (collection) { _%>
+    expect(read.<%= property %>).toEqual([expect.objectContaining({ <%= otherId %>: related.<%= otherId %> })]);
+<%_ } else { _%>
+    expect(read.<%= property %>).toMatchObject({ <%= otherId %>: related.<%= otherId %> });
+<%_ } _%>
+<%_ if (otherEntity.builtInUser) { _%>
+    // The keys of the user never in a response, like the @JsonIgnore keys of JHipster Spring Boot.
+    expect(JSON.stringify(read.<%= property %>)).not.toMatch(/e2e-(activation|reset)-key/);
+<%_ } _%>
+<%_ if (otherTextField) { _%>
+    const { body: relatedRead } = await request(server).get(`/api/<%= otherEntity.entityApiUrl %>/${related.<%= otherId %>}`).expect(200);
+    expect(relatedRead.<%= otherTextField.fieldName %>).toBe(relatedValues.<%= otherTextField.fieldName %>);
+<%_ } _%>
+
+    await request(server).delete(`/api/<%= entityApiUrl %>/${stored.<%= primaryKey.name %>}`).expect(204);
+<%_ if (otherEntity.builtInUser) { _%>
+    await users.remove(related);
+<%_ } else if (!otherEntity.builtIn) { _%>
+    await request(server).delete(`/api/<%= otherEntity.entityApiUrl %>/${related.<%= otherId %>}`).expect(204);
+<%_ } _%>
+  });
+<%_ } _%>
+<%_ for (const relationship of inverseRelationships) {
+    const otherEntity = relationship.otherEntity;
+    const otherId = otherEntity.primaryKey.name;
+    const property = relationship.propertyName;
+    const collection = relationship.relationshipType !== 'one-to-one';
+    const otherProperty = relationship.otherRelationship.propertyName;
+    const otherCollection = relationship.relationshipType === 'many-to-many';
+    const otherValues = relationship.nodejsRelatedValues;
+_%>
+
+  it('should not store the <%= property %> relationship from this side, like the mappedBy side of JHipster Spring Boot', async () => {
+    const server = app.getHttpServer();
+    const { body: stored } = await request(server).post('/api/<%= entityApiUrl %>').send(createdValues).expect(201);
+    const reference = { <%= primaryKey.name %>: stored.<%= primaryKey.name %> };
+    const { body: related } = await request(server)
+      .post('/api/<%= otherEntity.entityApiUrl %>')
+      .send({ ...<%- literal(otherValues) %>, <%= otherProperty %>: <%- otherCollection ? '[reference]' : 'reference' %> })
+      .expect(201);
+
+    await request(server)
+      .put(`/api/<%= entityApiUrl %>/${stored.<%= primaryKey.name %>}`)
+      .send({ ...stored, <%= property %>: <%- collection ? '[]' : 'null' %> })
+      .expect(200);
+
+    const { body: relatedRead } = await request(server).get(`/api/<%= otherEntity.entityApiUrl %>/${related.<%= otherId %>}`).expect(200);
+<%_ if (otherCollection) { _%>
+    expect(relatedRead.<%= otherProperty %>).toEqual([expect.objectContaining(reference)]);
+<%_ } else { _%>
+    expect(relatedRead.<%= otherProperty %>).toMatchObject(reference);
+<%_ } _%>
+
+    await request(server).delete(`/api/<%= otherEntity.entityApiUrl %>/${related.<%= otherId %>}`).expect(204);
+    await request(server).delete(`/api/<%= entityApiUrl %>/${stored.<%= primaryKey.name %>}`).expect(204);
+  });
+<%_ } _%>
+});