diff --git a/.travis.yml b/.travis.yml index 7643c50baf..bb82d630f7 100644 --- a/.travis.yml +++ b/.travis.yml @@ -48,6 +48,7 @@ cache: script: - npm run lint:all - npm run test:ci:all + - npm run docs:coverage - npm run build:showcase - npm run docs:publish - npm run release:publish diff --git a/docs/ENVIRONMENTS.md b/docs/ENVIRONMENTS.md index d1d5b78187..662376bdf4 100644 --- a/docs/ENVIRONMENTS.md +++ b/docs/ENVIRONMENTS.md @@ -1,4 +1,4 @@ -# Environments support +# Environments support ## Environment.ts @@ -12,10 +12,11 @@ export interface Environment { ... ``` -`production`, which is a boolean, will specify is your application runs under a production environment, -while `hmr` will indicate if it runs under a Hot Module Replacement environment. +`production`, which is a boolean, will specify is your application runs under a production environment, +while `hmr` will indicate if it runs under a Hot Module Replacement environment. + +This interface will then be defined by default in `src/environments/environment.ts`: -This interface will then be defined by default in `src/environments/environment.ts`: ``` ... export const environment: Environment = { @@ -25,41 +26,42 @@ export const environment: Environment = { ... ``` -## How to find out which environment is your application is currently using? +## How to find out which environment is your application is currently using? + +All you have to do is to import the environment.ts constant anywhere you want in your application: -All you have to do is to import the environment.ts constant anywhere you want in your application: ``` import { environment } from "environments/environment"; ``` This way, you will be able to programmatically determine which environment is used in your app -with simple checks, as follows: +with simple checks, as follows: ``` -environment.production -// if the output of this line is true, we are in production environment. -// Otherwise, we are in hmr environment. +environment.production +// if the output of this line is true, we are in production environment. +// Otherwise, we are in hmr environment. ``` ## How to add a new environment ? -First, create you new Ts file in the `src/environments` folder. +First, create you new Ts file in the `src/environments` folder. Then, make sure your new environment extends the `src/environments/model.ts` interface. -Finally, define the options and file replacement of your new environment in the `angular.json` file. +Finally, define the options and file replacement of your new environment in the `angular.json` file. -For exemple, the environment.dummyEnv.ts file: +For exemple, the environment.dummyEnv.ts file: -```` +``` import { enableProdMode, NgModuleRef } from "@angular/core"; import { disableDebugTools } from "@angular/platform-browser"; import { Environment } from "./model"; enableProdMode(); -export const environment: Environment = { - +export const environment: Environment = { + production: false, hmr: false, @@ -69,11 +71,11 @@ export const environment: Environment = { }, ENV_PROVIDERS: [] } -```` +``` -And in the angular.json file: +And in the angular.json file: -```` +``` "dummyEnv" : { "fileReplacements": [ { @@ -82,4 +84,4 @@ And in the angular.json file: } ] } -```` \ No newline at end of file +``` diff --git a/package.json b/package.json index e9a04252bc..747122b61d 100644 --- a/package.json +++ b/package.json @@ -87,7 +87,7 @@ "commit": "./node_modules/.bin/git-cz", "commitmsg": "commitlint -e $GIT_PARAMS", "docs": "npm run docs:clean && npm run docs:all", - "docs:all": "npm run docs:stark-core:generate && npm run docs:stark-ui:generate", + "docs:all": "npm run docs:stark-core:generate && npm run docs:stark-ui:generate && npm run docs:starter:generate", "docs:clean": "npx rimraf reports/api-docs", "docs:coverage": "npm run docs:stark-core:coverage && npm run docs:stark-ui:coverage && npm run docs:starter:coverage", "docs:publish": "bash ./gh-deploy.sh --trace", @@ -124,7 +124,7 @@ "install:ci:starter": "cd starter && npm ci && cd ..", "install:travis:all": "npm run install:stark-build && npm run install:stark-testing && npm run install:stark-core && npm run install:stark-ui && npm run build:trace && npm run update:starter && npm run update:showcase", "ngc": "ngc", - "precommit": "lint-staged", + "precommit": "lint-staged && npm run docs:coverage", "prettier-check": "prettier **/*.{css,js,json,md,pcss,scss,ts} --write", "preupdate:showcase": "npm run clean:showcase", "preupdate:starter": "npm run clean:starter", diff --git a/packages/stark-build/config/build-utils.js b/packages/stark-build/config/build-utils.js index fc25f1514c..dfca931cd1 100644 --- a/packages/stark-build/config/build-utils.js +++ b/packages/stark-build/config/build-utils.js @@ -39,13 +39,12 @@ function readTsConfig(tsConfigPath) { } /** - * Method which returns the path of the environment file of the received environment. * The method reads the content of angular.json for getting the path (read with value or replace in "fileReplacements" of environment. * * See: https://github.com/angular/angular-cli/wiki/angular-workspace * * @param environment - * @returns {*} + * @returns {*} - the path of the environment file of the received environment. */ function getEnvironmentFile(environment) { if (typeof environment === "string") { diff --git a/packages/stark-build/config/helpers.js b/packages/stark-build/config/helpers.js index 41d9000ef4..88a595239e 100644 --- a/packages/stark-build/config/helpers.js +++ b/packages/stark-build/config/helpers.js @@ -24,7 +24,7 @@ function isWebpackDevServer() { /** * Retrieve the relative path from the config directory to the path argument value (if provided). That path argument can be passed to only execute a subset of the unit tests (see spec-bundle.ts) * @param args the arguments to look into - * @returns {*} The relative path from this directory (config) to the location pointed at by the path argument value (if provided), an empty string otherwise + * @returns The relative path from this directory (config) to the location pointed at by the path argument value (if provided), an empty string otherwise */ function getTestPath(args) { for (let i = 0; i < args.length; ++i) { diff --git a/packages/stark-build/config/json-server.common.js b/packages/stark-build/config/json-server.common.js index c7ffe98aa1..2c45538b90 100644 --- a/packages/stark-build/config/json-server.common.js +++ b/packages/stark-build/config/json-server.common.js @@ -47,7 +47,7 @@ const starkMetadata = { * @param middlewares {object} Middlewares to be applied just after the default Stark middlewares * @param routes {object} (Optional) Routes to be rewritten (in order to support nested resources) * @param uploadEndpoints {object} (Optional) Endpoints for file uploads - * @returns {server} ExpressJS server definition + * @returns ExpressJS server definition */ function getJSONServer(data, middlewares, routes, uploadEndpoints) { var server = jsonServer.create(); @@ -176,8 +176,6 @@ function transformRequests(req, res, next) { * - Request: the current request * - Response: the current response (containing the default changes made by Stark middleware) * - StarkMetadata: metadata object constructed by the Stark middleware (only for Collection responses) - * - * @returns {Function} */ function composeTransformResponses(transformFn) { return function(req, res) { @@ -205,7 +203,7 @@ function composeTransformResponses(transformFn) { * Default Stark response transformations: metadata and etags * @param req {*} The current request (already changed by Stark default middleware) * @param res {*} The current response (already changed by Stark default middleware) - * @param collectionMetadata {object} Metadata object constructed by the Stark middleware (only for Collection responses) + * @param collectionMetadata : Metadata object constructed by the Stark middleware (only for Collection responses) */ function transformResponses(req, res, collectionMetadata) { console.log("transformResponses Stark middleware"); @@ -238,8 +236,8 @@ function transformResponses(req, res, collectionMetadata) { /** * Extract the query parameters from the request url - * @param url {string} Request url - * @returns {object} Object containing the different query parameters + * @param url: Request url + * @returns Object containing the different query parameters */ function extractUrlParams(url) { var queryParams = {}; @@ -260,7 +258,7 @@ function extractUrlParams(url) { /** * Replace Stark pagination params by JSON-server pagination params - * @param req {*} The current request + * @param req : The current request */ function transformPaginationParams(req) { const limit = parseInt(req.query[starkQueryParam.LIMIT], 10) || 10; // defaults to 10 @@ -276,7 +274,7 @@ function transformPaginationParams(req) { /** * Replace Stark sorting params by JSON-server sorting params - * @param req {*} The current request + * @param req : The current request */ function transformSortingParams(req) { const sortingRegex = /(\w+)\+(ASC|DESC)/g; // perform a global search to match all the sort items @@ -301,7 +299,7 @@ function transformSortingParams(req) { /** * Change POST requests to PATCH for an existing resource (when the uuid is defined) - * @param req {*} The current request + * @param req : The current request */ function convertUpdateRequestMethod(req) { if (req.method === "POST" && req.body && req.body.uuid) { @@ -312,9 +310,9 @@ function convertUpdateRequestMethod(req) { /** * Add "pagination" object to metadata for Collection responses * See https://github.com/NationalBankBelgium/REST-API-Design-Guide/wiki/Pagination-Rules-and-metadata - * @param req {*} The current request - * @param res {*} The current response - * @param collectionMetadata {object} Metadata object constructed by the Stark middleware (only for Collection responses) + * @param req : The current request + * @param res : The current response + * @param collectionMetadata : Metadata object constructed by the Stark middleware (only for Collection responses) */ function addPaginationMetadata(req, res, collectionMetadata) { var pagination = (collectionMetadata["pagination"] = {}); @@ -348,8 +346,8 @@ function addPaginationMetadata(req, res, collectionMetadata) { /** * In case the metadata object is passed, the "etags" object is added to it (Collection responses) * Otherwise the "etag" header is added to the response (single item responses) - * @param res {*} The current request - * @param collectionMetadata {object} Metadata object constructed by the Stark middleware (only for Collection responses) + * @param res : The current request + * @param collectionMetadata : Metadata object constructed by the Stark middleware (only for Collection responses) */ function addEtagInfo(res, collectionMetadata) { const data = res.locals.data; @@ -400,8 +398,7 @@ function addSortingMetadata(req, collectionMetadata) { * Check whether the request is a GetCollection request. * GetCollection requests are the ones with a "mockCollectionRequest" query param. * See: https://jira.prd.nbb/browse/NG-1335 - * @param req {*} The current request - * @returns {boolean} + * @param req : The current request */ function isGetCollectionRequest(req) { var params = extractUrlParams(req.originalUrl); @@ -411,8 +408,7 @@ function isGetCollectionRequest(req) { /** * Check whether the request is aimed to get a nested resource (from a many-to-one relationship). * Such requests have a '_expand' query parameter - * @param req {*} The current request - * @returns {boolean} + * @param req : The current request */ function isNestedResourceQuery(req) { return req.method === "GET" && typeof req.query["_expand"] !== "undefined"; @@ -421,8 +417,7 @@ function isNestedResourceQuery(req) { /** * Get the name of the nested resource to be fetched in the request (from a many-to-one relationship). * Such resource is the one passed in the '_expand' query parameter. - * @param req {*} The current request - * @returns {string|undefined} + * @param req : The current request */ function getNestedResourceName(req) { return req.query["_expand"]; @@ -431,7 +426,6 @@ function getNestedResourceName(req) { /** * Generate an Etag random value * @param item - * @returns {string} */ function generateEtagValue(item) { return _uniqueId( @@ -469,8 +463,7 @@ function deepReplaceProperty(item, property, newProperty) { /** * Add to the original routes for nested resources (those that will be rewritten with a '_expand' query parameter) * with an optional query param regex so that the route can match regardless of whether it has or not query params - * @param routes {object} Routes to be rewritten (in order to support nested resources) - * @returns {object} + * @param routes : Routes to be rewritten (in order to support nested resources) */ function expandRewrittenRoutes(routes) { const nestedResourceRegex = /^\/(\w+)\/:(\w+)\/(\w+)$/; diff --git a/packages/stark-core/package.json b/packages/stark-core/package.json index 4571e5d554..da9d2f99f5 100644 --- a/packages/stark-core/package.json +++ b/packages/stark-core/package.json @@ -60,7 +60,7 @@ "clean:modules": "npx rimraf ./node_modules package-lock.json", "clean:all": "npm run clean && npm run clean:modules", "docs": "node ../../node_modules/@compodoc/compodoc/bin/index-cli src --theme material --tsconfig ../tsconfig.json --output ../../reports/api-docs/stark-core", - "docs:coverage": "npm run docs -- --coverageTest --coverageThresholdFail true", + "docs:coverage": "npm run docs -- --coverageTest 85 --coverageThresholdFail true", "docs:serve": "npm run docs -- --watch --serve --port 4321", "ngc": "node ../../node_modules/@angular/compiler-cli/src/main.js -p tsconfig-build.json", "lint": "node ../../node_modules/tslint/bin/tslint --config ./tslint.json --project ./tsconfig.spec.json --format codeFrame", diff --git a/packages/stark-core/public_api.ts b/packages/stark-core/public_api.ts index 7d8e7bfed3..12c1a91a9a 100644 --- a/packages/stark-core/public_api.ts +++ b/packages/stark-core/public_api.ts @@ -1,6 +1,4 @@ /** - * @module - * @description * Entry point for all public APIs of this package. */ export * from "./src/stark-core"; diff --git a/packages/stark-core/src/common/error/error.ts b/packages/stark-core/src/common/error/error.ts index fecd404de3..915db1ffe7 100644 --- a/packages/stark-core/src/common/error/error.ts +++ b/packages/stark-core/src/common/error/error.ts @@ -1,8 +1,11 @@ +/* tslint:disable:completed-docs*/ import moment from "moment"; import { autoserialize } from "cerialize"; import { StarkError } from "./error.intf"; - +/** + * @ignore + */ export class StarkErrorImpl implements StarkError { @autoserialize public message?: string; @autoserialize public name?: string; diff --git a/packages/stark-core/src/common/routes/routes.ts b/packages/stark-core/src/common/routes/routes.ts index d449d84b3c..f342441ba5 100644 --- a/packages/stark-core/src/common/routes/routes.ts +++ b/packages/stark-core/src/common/routes/routes.ts @@ -2,23 +2,52 @@ import { Location } from "@angular/common"; import { STARK_ROUTING_SERVICE, StarkRoutingService, StarkStateConfigWithParams } from "../../modules/routing/services"; import { StatesModule } from "@uirouter/angular"; +/** + * Name of the initialization states of the application + */ export const starkAppInitStateName: string = "starkAppInit"; +/** + * Name of the exit states of the application + */ export const starkAppExitStateName: string = "starkAppExit"; - +/** + * Name of the login state of the application + */ export const starkLoginStateName: string = "starkAppInit.starkLogin"; +/** + * URL of the login state of the application + */ export const starkLoginStateUrl: string = "/starkLogin"; - +/** + * Name of the preloading state of the application + */ export const starkPreloadingStateName: string = "starkAppInit.starkPreloading"; +/** + * URL of the preloading state of the application + */ export const starkPreloadingStateUrl: string = "/starkPreloading"; - +/** + * Name of the SessionExpired state of the application + */ export const starkSessionExpiredStateName: string = "starkAppExit.starkSessionExpired"; +/** + * URL of the SessionExpired state of the application + */ export const starkSessionExpiredStateUrl: string = "/starkSessionExpired"; - +/** + * Name of the SessionLogout state of the application + */ export const starkSessionLogoutStateName: string = "starkAppExit.starkSessionLogout"; +/** + * URL of the SessionLogout state of the application + */ export const starkSessionLogoutStateUrl: string = "/starkSessionLogout"; // FIXME Fix states declaration /* tslint:disable:no-duplicate-string */ +/** + * Configuration of the route state of the application + */ export const starkCoreRouteConfig: StatesModule = { states: [ { diff --git a/packages/stark-core/src/common/store/stark-core-application-state.ts b/packages/stark-core/src/common/store/stark-core-application-state.ts index 00540c29ad..159fba89a8 100644 --- a/packages/stark-core/src/common/store/stark-core-application-state.ts +++ b/packages/stark-core/src/common/store/stark-core-application-state.ts @@ -1,10 +1,9 @@ -/** - * Interface defining the shape of the application state of Stark Core (i.e., what's stored in Redux by Stark) - */ import { StarkLoggingState } from "../../modules/logging/reducers"; import { StarkSessionState } from "../../modules/session/reducers"; import { StarkSettingsState } from "../../modules/settings/reducers"; - +/** + * Interface defining the shape of the application state of Stark Core (i.e., what's stored in Redux by Stark) + */ export interface StarkCoreApplicationState extends StarkLoggingState, StarkSessionState, StarkSettingsState { // FIXME: still needed? // starkApplicationMetadata: StarkApplicationMetadata; diff --git a/packages/stark-core/src/common/translations/locale.intf.ts b/packages/stark-core/src/common/translations/locale.intf.ts index 31d64e1248..d096fcfc7a 100644 --- a/packages/stark-core/src/common/translations/locale.intf.ts +++ b/packages/stark-core/src/common/translations/locale.intf.ts @@ -1,4 +1,14 @@ +/** + * Contains the translation for a specific language + */ export interface StarkLocale { + /** + * The code of the language that we want to retrieve + */ languageCode: string; + + /** + * The actual translation of the text + */ translations: Object; } diff --git a/packages/stark-core/src/common/translations/translations.ts b/packages/stark-core/src/common/translations/translations.ts index 4f2cbac3bf..8bff629384 100644 --- a/packages/stark-core/src/common/translations/translations.ts +++ b/packages/stark-core/src/common/translations/translations.ts @@ -1,4 +1,7 @@ import { TranslateService } from "@ngx-translate/core"; +/** + * @ignore + */ const _cloneDeep: Function = require("lodash/cloneDeep"); import { StarkLocale } from "./locale.intf"; diff --git a/packages/stark-core/src/common/translations/translations/en.ts b/packages/stark-core/src/common/translations/translations/en.ts index 4938648e22..b5126abc35 100644 --- a/packages/stark-core/src/common/translations/translations/en.ts +++ b/packages/stark-core/src/common/translations/translations/en.ts @@ -1,3 +1,6 @@ +/** + * @ignore + */ export const translationsEn: object = { STARK: { LANGUAGES: { diff --git a/packages/stark-core/src/common/translations/translations/fr.ts b/packages/stark-core/src/common/translations/translations/fr.ts index 2412cfebdb..af7cd26f36 100644 --- a/packages/stark-core/src/common/translations/translations/fr.ts +++ b/packages/stark-core/src/common/translations/translations/fr.ts @@ -1,3 +1,6 @@ +/** + * @ignore + */ export const translationsFr: object = { STARK: { LANGUAGES: { diff --git a/packages/stark-core/src/common/translations/translations/nl.ts b/packages/stark-core/src/common/translations/translations/nl.ts index 4270d58d25..afdff31cdf 100644 --- a/packages/stark-core/src/common/translations/translations/nl.ts +++ b/packages/stark-core/src/common/translations/translations/nl.ts @@ -1,3 +1,6 @@ +/** + * @ignore + */ export const translationsNl: object = { STARK: { LANGUAGES: { diff --git a/packages/stark-core/src/configuration/entities/application/app-config.entity.intf.ts b/packages/stark-core/src/configuration/entities/application/app-config.entity.intf.ts index fbd88a5978..2e62c000d7 100644 --- a/packages/stark-core/src/configuration/entities/application/app-config.entity.intf.ts +++ b/packages/stark-core/src/configuration/entities/application/app-config.entity.intf.ts @@ -1,6 +1,9 @@ import { StarkBackend } from "../../../modules/http/entities/backend"; import { InjectionToken } from "@angular/core"; +/** + * The InjectionToken that defines the StarkApplicationConfig, in case an injection is needed. + */ export const STARK_APP_CONFIG: InjectionToken = new InjectionToken("STARK_APP_CONFIG"); /** @@ -29,9 +32,11 @@ export interface StarkApplicationConfig { errorStateName: string; /** - * Enable Angular's debug runtime information - * @link https://docs.angularjs.org/guide/production#disabling-debug-data - * @link https://docs.angularjs.org/api/ng/provider/$compileProvider#debugInfoEnabled + * Enable Angular's debug runtime information. + * + * See https://docs.angularjs.org/guide/production#disabling-debug-data. + * + * See https://docs.angularjs.org/api/ng/provider/$compileProvider#debugInfoEnabled */ angularDebugInfoEnabled: boolean; @@ -43,7 +48,7 @@ export interface StarkApplicationConfig { /** * When the number of log messages reaches the loggingFlushPersistSize value, * the log messages are sent to the back-end and removed from the redux store. - * Default: 15 + * Default - 15 */ loggingFlushPersistSize?: number; @@ -60,7 +65,7 @@ export interface StarkApplicationConfig { /** * Option to disable the logging flush if it not needed for the application. - * Default: false + * Default - false */ loggingFlushDisabled?: boolean; @@ -71,7 +76,7 @@ export interface StarkApplicationConfig { /** * Enable router visualizer. Only in DEV (the router visualizer is not available in PROD) - * Default: false + * Default - false */ routerVisualizerEnabled?: boolean; @@ -82,7 +87,7 @@ export interface StarkApplicationConfig { /** * Seconds before the session is ended (due to no user interaction) when the timeout warning event will be emitted. - * Default: 15 + * Default - 15 */ sessionTimeoutWarningPeriod: number; @@ -98,7 +103,7 @@ export interface StarkApplicationConfig { /** * Option to disable the keepAlive if it is not needed for the application. - * Default: false + * Default - false */ keepAliveDisabled?: boolean; @@ -126,11 +131,14 @@ export interface StarkApplicationConfig { /** * Map containing the different back-ends that the application will interact with. + * @link StarkBackend */ backends: Map; /** * Get a back-end by name + * + * @link StarkBackend * @param name - Name of the back-end object to get * @returns The requested backend object */ @@ -138,18 +146,24 @@ export interface StarkApplicationConfig { /** * Add a back-end + * + * @link StarkBackend * @param backend - Back-end object to add */ addBackend(backend: StarkBackend): void; /** * Define all back-ends + * + * @link StarkBackend * @param backends - Array of back-end objects to add */ setBackends(backends: StarkBackend[]): void; /*** * Get all currently defined back-end objects + * + * @link StarkBackend * @returns A Map containing the different back-end objects */ getBackends(): Map; diff --git a/packages/stark-core/src/configuration/entities/application/app-config.entity.ts b/packages/stark-core/src/configuration/entities/application/app-config.entity.ts index ee31046490..01b7dff500 100644 --- a/packages/stark-core/src/configuration/entities/application/app-config.entity.ts +++ b/packages/stark-core/src/configuration/entities/application/app-config.entity.ts @@ -1,3 +1,4 @@ +/* tslint:disable:completed-docs*/ import { IsBoolean, IsDefined, IsNotEmpty, IsPositive, IsString, IsUrl, Matches, Min, ValidateIf, validateSync } from "class-validator"; import { autoserialize, autoserializeAs, Deserialize } from "cerialize"; import { StarkApplicationConfig } from "./app-config.entity.intf"; @@ -5,7 +6,9 @@ import { StarkBackend, StarkBackendImpl } from "../../../modules/http/entities/b import { stringMap } from "../../../serialization"; import { StarkValidationErrorsUtil } from "../../../util"; import { StarkMapNotEmpty, StarkMapIsValid } from "../../../validation/decorators"; - +/** + * @ignore + */ export class StarkApplicationConfigImpl implements StarkApplicationConfig { // FIXME: properties of the group "temp" are not used yet. Will they still be used? @@ -169,10 +172,22 @@ export class StarkApplicationConfigImpl implements StarkApplicationConfig { return this.backends; } + /** + * Check whether the keepAlive option in the StarkApplicationConfig is disabled + * + * @param instance - the instance of the stark application configuration + * @returns boolean - if keepAlive is in use, the value of keepAliveDisabled is set to false + */ public static validateIfKeepAliveEnabled(instance: StarkApplicationConfig): boolean { return instance.keepAliveDisabled !== true; } + /** + * Check whether the loggingFlush option in the StarkApplicationConfig is disabled + * + * @param instance - the instance of the stark application configuration + * @returns boolean - if loggingFlush is in use, the value of loggingFlushDisabled is set to false + */ public static validateIfLoggingFlushEnabled(instance: StarkApplicationConfig): boolean { return instance.loggingFlushDisabled !== true; } diff --git a/packages/stark-core/src/configuration/entities/language/language.constants.ts b/packages/stark-core/src/configuration/entities/language/language.constants.ts index 126550fca1..ed0c4d03c3 100644 --- a/packages/stark-core/src/configuration/entities/language/language.constants.ts +++ b/packages/stark-core/src/configuration/entities/language/language.constants.ts @@ -4,24 +4,36 @@ import { StarkLanguage } from "./language.entity.intf"; * Lists of languages currently supported by Stark. */ export class StarkLanguages { + /** + * English language + */ public static EN_US: StarkLanguage = { isoCode: "en-US", translationKey: "STARK.LANGUAGES.EN", code: "en", region: "US" }; + /** + * French language + */ public static FR_BE: StarkLanguage = { isoCode: "fr-BE", translationKey: "STARK.LANGUAGES.FR", code: "fr", region: "BE" }; + /** + * Dutch language + */ public static NL_BE: StarkLanguage = { isoCode: "nl-BE", translationKey: "STARK.LANGUAGES.NL", code: "nl", region: "BE" }; + /** + * German language + */ public static DE_DE: StarkLanguage = { isoCode: "de-DE", translationKey: "STARK.LANGUAGES.DE", diff --git a/packages/stark-core/src/configuration/entities/language/language.entity.ts b/packages/stark-core/src/configuration/entities/language/language.entity.ts index c1b789280e..6c4eae5601 100644 --- a/packages/stark-core/src/configuration/entities/language/language.entity.ts +++ b/packages/stark-core/src/configuration/entities/language/language.entity.ts @@ -2,7 +2,9 @@ import { IsNotEmpty, IsString, Matches } from "class-validator"; import { autoserialize } from "cerialize"; import { StarkLanguage } from "./language.entity.intf"; import { StarkIsSupportedLanguage } from "../../../validation/decorators/is-supported-language"; - +/** + * @ignore + */ export class StarkLanguageImpl implements StarkLanguage { @IsNotEmpty({ always: true }) // validation must be performed always, regardless of validation groups used. @IsString({ always: true }) diff --git a/packages/stark-core/src/configuration/entities/metadata/application-metadata.entity.intf.ts b/packages/stark-core/src/configuration/entities/metadata/application-metadata.entity.intf.ts index 8f9a10915b..3361c80f7a 100644 --- a/packages/stark-core/src/configuration/entities/metadata/application-metadata.entity.intf.ts +++ b/packages/stark-core/src/configuration/entities/metadata/application-metadata.entity.intf.ts @@ -1,6 +1,9 @@ import { StarkLanguage } from "../language"; import { InjectionToken } from "@angular/core"; +/** + * The InjectionToken that defines the Application Metadata, in case an injection is needed. + */ export const STARK_APP_METADATA: InjectionToken = new InjectionToken( "STARK_APP_METADATA" ); @@ -42,6 +45,7 @@ export interface StarkApplicationMetadata { /** * Array of languages to be supported in the application + * @link StarkLanguage */ supportedLanguages: StarkLanguage[]; } diff --git a/packages/stark-core/src/configuration/entities/metadata/application-metadata.entity.ts b/packages/stark-core/src/configuration/entities/metadata/application-metadata.entity.ts index 1edb542cb4..d21184a69b 100644 --- a/packages/stark-core/src/configuration/entities/metadata/application-metadata.entity.ts +++ b/packages/stark-core/src/configuration/entities/metadata/application-metadata.entity.ts @@ -6,6 +6,9 @@ import { StarkLanguageImpl } from "../language"; import { StarkLanguage } from "../language/language.entity.intf"; import { StarkLanguages } from "../language/language.constants"; +/** + * @ignore + */ export class StarkApplicationMetadataImpl implements StarkApplicationMetadata { // FIXME: properties of the group "temp" are not used yet. Will they still be used? diff --git a/packages/stark-core/src/configuration/entities/mock-data/mock-data.entity.intf.ts b/packages/stark-core/src/configuration/entities/mock-data/mock-data.entity.intf.ts index 1cc4e7a8c2..087e3fc6a2 100644 --- a/packages/stark-core/src/configuration/entities/mock-data/mock-data.entity.intf.ts +++ b/packages/stark-core/src/configuration/entities/mock-data/mock-data.entity.intf.ts @@ -1,8 +1,14 @@ import { InjectionToken } from "@angular/core"; import { StarkUser } from "../../../modules/user"; - +/** + * The InjectionToken that defines the StarkApplicationConfig, in case an injection is needed. + */ export const STARK_MOCK_DATA: InjectionToken = new InjectionToken("STARK_MOCK_DATA"); +/** + * Mock data entity + * Describes how the mock data should look like when a developer wants to mock its backend data to be fetched via JSON Server + */ export interface StarkMockData { [key: string]: any; profiles?: StarkUser[]; diff --git a/packages/stark-core/src/modules/http/builder/http-abstract-base-request-builder.intf.ts b/packages/stark-core/src/modules/http/builder/http-abstract-base-request-builder.intf.ts index 87b1ca65f6..fac499d1ca 100644 --- a/packages/stark-core/src/modules/http/builder/http-abstract-base-request-builder.intf.ts +++ b/packages/stark-core/src/modules/http/builder/http-abstract-base-request-builder.intf.ts @@ -1,5 +1,9 @@ import { StarkHttpRequest, StarkQueryParam, StarkResource } from "../entities"; +/** + * The StarkHttpBaseRequestBuilder interface is used to build a HTTP request. + * Thanks to this class, headers, query parameters, ... can be added to the request. + */ export interface StarkHttpBaseRequestBuilder { /** * Adds a header to the request @@ -11,6 +15,8 @@ export interface StarkHttpBaseRequestBuilder { /** * Adds a query parameter to the request (if the parameter already exists it will be overwritten) + * + * @link StarkQueryParam * @param name - Query parameter name * @param value - Query parameter value * @param allowUndefined - (Optional) Whether to include the query parameter even if it has an undefined value. Default: false. @@ -21,6 +27,8 @@ export interface StarkHttpBaseRequestBuilder { /** * Adds query parameters to the request (adds them to the existing query parameters) + * + * @link StarkQueryParam * @param params - Object with the query parameters to be added to the request * @param allowUndefined - (Optional) Whether to include the query parameters even if they have undefined values. Default: false. * @param allowEmpty - (Optional) Whether to include the query parameter even if it is an empty string. Default: false. @@ -30,6 +38,8 @@ export interface StarkHttpBaseRequestBuilder { /** * Sets query parameters to the request (all existing query parameters will be lost) + * + * @link StarkQueryParam * @param params - Object with the query parameters to be added to the request * @param allowUndefined - (Optional) Whether to include the query parameters even if they have undefined values. Default: false. * @param allowEmpty - (Optional) Whether to include the query parameter even if it is an empty string. Default: false. @@ -53,6 +63,8 @@ export interface StarkHttpBaseRequestBuilder { /** * Returns an instance of the constructed StarkHttpRequest. It should be always the last method to be called. + * + * @link StarkHttpRequest * @returns The constructed request */ build(): StarkHttpRequest; diff --git a/packages/stark-core/src/modules/http/builder/http-abstract-base-request-builder.ts b/packages/stark-core/src/modules/http/builder/http-abstract-base-request-builder.ts index 337b8a63c5..a0d28fc496 100644 --- a/packages/stark-core/src/modules/http/builder/http-abstract-base-request-builder.ts +++ b/packages/stark-core/src/modules/http/builder/http-abstract-base-request-builder.ts @@ -1,7 +1,10 @@ +/* tslint:disable:completed-docs*/ import { StarkHttpRequest, StarkQueryParam, StarkResource } from "../entities"; import { StarkHttpBaseRequestBuilder } from "./http-abstract-base-request-builder.intf"; import { StarkUrlUtil } from "../../../util/url-util"; - +/** + * @ignore + */ export abstract class StarkAbstractHttpBaseRequestBuilder implements StarkHttpBaseRequestBuilder { protected request: StarkHttpRequest; diff --git a/packages/stark-core/src/modules/http/builder/http-abstract-fetch-resource-request-builder.intf.ts b/packages/stark-core/src/modules/http/builder/http-abstract-fetch-resource-request-builder.intf.ts index f9fae4d9e7..a33b3e9102 100644 --- a/packages/stark-core/src/modules/http/builder/http-abstract-fetch-resource-request-builder.intf.ts +++ b/packages/stark-core/src/modules/http/builder/http-abstract-fetch-resource-request-builder.intf.ts @@ -1,9 +1,14 @@ import { StarkLanguage } from "../../../configuration/entities/language"; import { StarkSortItem } from "../entities"; +/** + * This StarkHttpFetchResourceRequestBuilder interface describes the different operations supported by Http request builders for resource-fetching requests + */ export interface StarkHttpFetchResourceRequestBuilder { /** * Adds language codes to the "Accept-Language" header + * + * @link StarkLanguage * @param languages - Language(s) in which the response should be returned * @returns The current builder */ @@ -25,6 +30,8 @@ export interface StarkHttpFetchResourceRequestBuilder { /** * Adds a "sort" query parameter to the request + * + * @link StarkSortItem * @param sortItems - Sort parameters to define the order in which the items will be returned * @returns The current builder */ diff --git a/packages/stark-core/src/modules/http/builder/http-abstract-fetch-resource-request-builder.ts b/packages/stark-core/src/modules/http/builder/http-abstract-fetch-resource-request-builder.ts index 37eac89f23..022c21721c 100644 --- a/packages/stark-core/src/modules/http/builder/http-abstract-fetch-resource-request-builder.ts +++ b/packages/stark-core/src/modules/http/builder/http-abstract-fetch-resource-request-builder.ts @@ -1,10 +1,13 @@ +/* tslint:disable:completed-docs*/ import { StarkLanguage } from "../../../configuration/entities/language"; import { StarkSortItem } from "../entities/metadata"; import { StarkHttpHeaders, StarkHttpQueryParameters } from "../constants"; import { StarkHttpFetchResourceRequestBuilder } from "./http-abstract-fetch-resource-request-builder.intf"; import { StarkAbstractHttpBaseRequestBuilder } from "./http-abstract-base-request-builder"; import { StarkResource } from "../entities/resource.entity.intf"; - +/** + * @ignore + */ export abstract class StarkAbstractHttpFetchResourceRequestBuilder extends StarkAbstractHttpBaseRequestBuilder implements StarkHttpFetchResourceRequestBuilder { public addAcceptedLanguage(...languages: StarkLanguage[]): this { diff --git a/packages/stark-core/src/modules/http/builder/http-create-request-builder.intf.ts b/packages/stark-core/src/modules/http/builder/http-create-request-builder.intf.ts index d024bfeb38..22dded1941 100644 --- a/packages/stark-core/src/modules/http/builder/http-create-request-builder.intf.ts +++ b/packages/stark-core/src/modules/http/builder/http-create-request-builder.intf.ts @@ -2,9 +2,14 @@ import { StarkHttpEchoType } from "../constants"; import { StarkHttpBaseRequestBuilder } from "./http-abstract-base-request-builder.intf"; import { StarkResource } from "../entities/resource.entity.intf"; +/** + * This StarkHttpCreateRequestBuilder interface describes the different operations supported by Http request builders for resource-creating requests + */ export interface StarkHttpCreateRequestBuilder extends StarkHttpBaseRequestBuilder { /** * Adds an "echo" query parameter to the request + * + * @link StarkHttpEchoType * @param echo - Echo parameter to specify whether the response should contain a response body * @returns The current builder */ diff --git a/packages/stark-core/src/modules/http/builder/http-delete-request-builder.intf.ts b/packages/stark-core/src/modules/http/builder/http-delete-request-builder.intf.ts index 7587d20ce0..e30a1c8fb6 100644 --- a/packages/stark-core/src/modules/http/builder/http-delete-request-builder.intf.ts +++ b/packages/stark-core/src/modules/http/builder/http-delete-request-builder.intf.ts @@ -1,4 +1,7 @@ import { StarkHttpBaseRequestBuilder } from "./http-abstract-base-request-builder.intf"; import { StarkResource } from "../entities/resource.entity.intf"; +/** + * This StarkHttpDeleteRequestBuilder interface describes the different operations supported by Http request builders for resource-deleting requests + */ export interface StarkHttpDeleteRequestBuilder extends StarkHttpBaseRequestBuilder {} diff --git a/packages/stark-core/src/modules/http/builder/http-get-collection-request-builder.intf.ts b/packages/stark-core/src/modules/http/builder/http-get-collection-request-builder.intf.ts index 424afcd6b1..88cad8201e 100644 --- a/packages/stark-core/src/modules/http/builder/http-get-collection-request-builder.intf.ts +++ b/packages/stark-core/src/modules/http/builder/http-get-collection-request-builder.intf.ts @@ -2,6 +2,9 @@ import { StarkHttpBaseRequestBuilder } from "./http-abstract-base-request-builde import { StarkHttpFetchResourceRequestBuilder } from "./http-abstract-fetch-resource-request-builder.intf"; import { StarkResource } from "../entities/resource.entity.intf"; +/** + * This StarkHttpGetCollectionRequestBuilder interface describes the different operations supported by Http request builders for resource-fetching (collection) requests + */ export interface StarkHttpGetCollectionRequestBuilder extends StarkHttpBaseRequestBuilder, StarkHttpFetchResourceRequestBuilder {} diff --git a/packages/stark-core/src/modules/http/builder/http-get-request-builder.intf.ts b/packages/stark-core/src/modules/http/builder/http-get-request-builder.intf.ts index 255c4e660c..4dd3490470 100644 --- a/packages/stark-core/src/modules/http/builder/http-get-request-builder.intf.ts +++ b/packages/stark-core/src/modules/http/builder/http-get-request-builder.intf.ts @@ -2,6 +2,9 @@ import { StarkHttpBaseRequestBuilder } from "./http-abstract-base-request-builde import { StarkHttpFetchResourceRequestBuilder } from "./http-abstract-fetch-resource-request-builder.intf"; import { StarkResource } from "../entities/resource.entity.intf"; +/** + * This StarkHttpGetRequestBuilder interface describes the different operations supported by Http request builders for resource-fetching requests + */ export interface StarkHttpGetRequestBuilder extends StarkHttpBaseRequestBuilder, StarkHttpFetchResourceRequestBuilder {} diff --git a/packages/stark-core/src/modules/http/builder/http-request-builder.spec.ts b/packages/stark-core/src/modules/http/builder/http-request-builder.spec.ts index c6dfe7efd3..70d2c201de 100644 --- a/packages/stark-core/src/modules/http/builder/http-request-builder.spec.ts +++ b/packages/stark-core/src/modules/http/builder/http-request-builder.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { serialize, serializeAs } from "cerialize"; import { StarkHttpCreateRequestBuilderImpl, @@ -525,7 +526,7 @@ function testAddSortBy(beforeEachFn: () => StarkHttpRequestBuilderSpecVariables< }); } -/* tslint:disable:no-duplicate-string no-null-keyword no-big-function */ +/* tslint:disable:no-duplicate-string no-null-keyword no-big-function completed-docs*/ function testCommonFunctionality(typeOfBuilder: "create" | "delete" | "getSingle" | "getCollection" | "search" | "update"): void { describe("common functionality", () => { const mockBackend: StarkBackend = new StarkBackendImpl(); @@ -868,7 +869,7 @@ function testCommonFunctionality(typeOfBuilder: "create" | "delete" | "getSingle } // FIXME: re-enable this TSLINT rule and refactor this function to reduce its cognitive complexity -// tslint:disable-next-line:cognitive-complexity +// tslint:disable-next-line:cognitive-complexity completed-docs function testCustomSerialization(typeOfBuilder: "create" | "delete" | "getSingle" | "getCollection" | "search" | "update"): void { describe("custom serialization", () => { const mockBackend: StarkBackend = new StarkBackendImpl(); @@ -1311,8 +1312,6 @@ function testCustomSerialization(typeOfBuilder: "create" | "delete" | "getSingle }); }); } -/* tslint:enable */ - function testUUIDPathParamNormalization(typeOfBuilder: "delete" | "getSingle" | "update"): void { describe("UUID path parameter normalization", () => { const mockBackend: StarkBackend = new StarkBackendImpl(); @@ -1427,7 +1426,7 @@ function testUUIDPathParamNormalization(typeOfBuilder: "delete" | "getSingle" | }); } -// tslint:disable-next-line:no-big-function +// tslint:disable-next-line:no-big-function completed-docs*/ describe("Builder: StarkHttpRequestBuilder", () => { const mockBackend: StarkBackend = new StarkBackendImpl(); let requestBuilder: StarkHttpRequestBuilder; @@ -1550,7 +1549,7 @@ describe("Builder: StarkHttpRequestBuilder", () => { const request: StarkHttpRequest = searchRequestBuilder.build(); const requestCriteria: { [key: string]: any } = <{ [key: string]: any }>request.item; expect(requestCriteria).not.toBe(mockCriteria); - /* tslint:disable:no-null-keyword */ + /* tslint:disable:no-null-keyword completed-docs */ expect(requestCriteria).toEqual({ field1: "anything", field2: { @@ -1566,7 +1565,7 @@ describe("Builder: StarkHttpRequestBuilder", () => { undefinedField: null // due to Serialize => with undefined returns null // emptyField: undefined // empty values are omitted }); - /* tslint:enable */ + /*tslint:disable:completed-docs*/ }); it("should leave the criteria 'as is', even those with empty value (allowEmptyCriteria = true)", () => { diff --git a/packages/stark-core/src/modules/http/builder/http-request-builder.ts b/packages/stark-core/src/modules/http/builder/http-request-builder.ts index e567007ee1..e47bfd1899 100644 --- a/packages/stark-core/src/modules/http/builder/http-request-builder.ts +++ b/packages/stark-core/src/modules/http/builder/http-request-builder.ts @@ -1,3 +1,4 @@ +/* tslint:disable:completed-docs*/ import { Serialize } from "cerialize"; import { StarkBackend, StarkHttpRequestType, StarkResource } from "../entities"; import { StarkSerializable } from "../../../serialization"; @@ -23,7 +24,9 @@ import { StarkHttpSerializer, StarkHttpSerializerImpl } from "../serializer"; import { StarkHttpBaseRequestBuilder } from "./http-abstract-base-request-builder.intf"; import { StarkAbstractHttpBaseRequestBuilder } from "./http-abstract-base-request-builder"; import { StarkAbstractHttpFetchResourceRequestBuilder } from "./http-abstract-fetch-resource-request-builder"; - +/** + * @ignore + */ export class StarkHttpRequestBuilderImpl implements StarkHttpRequestBuilder { private resourcePath: string; private backend: StarkBackend; @@ -272,7 +275,9 @@ export class StarkHttpRequestBuilderImpl implements Sta }); } } - +/** + * @ignore + */ export class StarkHttpCreateRequestBuilderImpl extends StarkAbstractHttpBaseRequestBuilder implements StarkHttpCreateRequestBuilder { public echo(echo: StarkHttpEchoType): this { @@ -280,18 +285,28 @@ export class StarkHttpCreateRequestBuilderImpl extends return this; } } - +/** + * @ignore + */ export class StarkHttpUpdateRequestBuilderImpl extends StarkAbstractHttpBaseRequestBuilder implements StarkHttpUpdateRequestBuilder {} - +/** + * @ignore + */ export class StarkHttpDeleteRequestBuilderImpl extends StarkAbstractHttpBaseRequestBuilder implements StarkHttpDeleteRequestBuilder {} - +/** + * @ignore + */ export class StarkHttpGetRequestBuilderImpl extends StarkAbstractHttpFetchResourceRequestBuilder implements StarkHttpGetRequestBuilder {} - +/** + * @ignore + */ export class StarkHttpGetCollectionRequestBuilderImpl extends StarkAbstractHttpFetchResourceRequestBuilder implements StarkHttpGetCollectionRequestBuilder {} - +/** + * @ignore + */ export class StarkHttpSearchRequestBuilderImpl extends StarkAbstractHttpFetchResourceRequestBuilder implements StarkHttpSearchRequestBuilder {} diff --git a/packages/stark-core/src/modules/http/builder/http-request-parameters.intf.ts b/packages/stark-core/src/modules/http/builder/http-request-parameters.intf.ts index 2e26e680bc..bd7a6ed68e 100644 --- a/packages/stark-core/src/modules/http/builder/http-request-parameters.intf.ts +++ b/packages/stark-core/src/modules/http/builder/http-request-parameters.intf.ts @@ -1,5 +1,8 @@ import { StarkSerializable } from "../../../serialization"; +/** + * This interface defines the structure to follow when providing additional parameters to the StarkHttpRequestBuilder. + */ export interface StarkHttpRequestParams { /** * Whether to allow query parameters with undefined value or not. Default: false. @@ -32,10 +35,19 @@ export interface StarkHttpRequestParams { serializationType?: StarkSerializable; } +/** + * Extra parameters to customize the create Http request to be sent. + */ export interface StarkHttpCreateRequestParams extends StarkHttpRequestParams {} +/** + * Extra parameters to customize the get Http request to be sent. + */ export interface StarkHttpGetRequestParams extends StarkHttpRequestParams {} +/** + * Extra parameters to customize the update Http request to be sent. + */ export interface StarkHttpUpdateRequestParams extends StarkHttpRequestParams { /** * When true, the request-type uses HTTP PUT else it uses HTTP POST. Default: false @@ -43,6 +55,9 @@ export interface StarkHttpUpdateRequestParams extends StarkHttpRequestParams { isIdempotent?: boolean; } +/** + * Extra parameters to customize the delete Http request to be sent. + */ export interface StarkHttpDeleteRequestParams extends StarkHttpRequestParams { /** * Whether the delete should be enforced or not. Default: false @@ -52,8 +67,14 @@ export interface StarkHttpDeleteRequestParams extends StarkHttpRequestParams { force?: boolean; } +/** + * Extra parameters to customize the get collection Http request to be sent. + */ export interface StarkHttpGetCollectionRequestParams extends StarkHttpRequestParams {} +/** + * Extra parameters to customize the search Http request to be sent. + */ export interface StarkHttpSearchRequestParams extends StarkHttpRequestParams { /** * Whether to allow criteria with empty value ('') or not. Default: false. diff --git a/packages/stark-core/src/modules/http/builder/http-search-request-builder.intf.ts b/packages/stark-core/src/modules/http/builder/http-search-request-builder.intf.ts index ec15a5873f..dfad2fbcf4 100644 --- a/packages/stark-core/src/modules/http/builder/http-search-request-builder.intf.ts +++ b/packages/stark-core/src/modules/http/builder/http-search-request-builder.intf.ts @@ -2,6 +2,9 @@ import { StarkHttpBaseRequestBuilder } from "./http-abstract-base-request-builde import { StarkHttpFetchResourceRequestBuilder } from "./http-abstract-fetch-resource-request-builder.intf"; import { StarkResource } from "../entities/resource.entity.intf"; +/** + * This StarkHttpSearchRequestBuilder interface describes the different operations supported by Http request builders for resource-searching requests + */ export interface StarkHttpSearchRequestBuilder extends StarkHttpBaseRequestBuilder, StarkHttpFetchResourceRequestBuilder {} diff --git a/packages/stark-core/src/modules/http/builder/http-update-request-builder.intf.ts b/packages/stark-core/src/modules/http/builder/http-update-request-builder.intf.ts index 2608e360e0..838270084c 100644 --- a/packages/stark-core/src/modules/http/builder/http-update-request-builder.intf.ts +++ b/packages/stark-core/src/modules/http/builder/http-update-request-builder.intf.ts @@ -1,4 +1,7 @@ import { StarkHttpBaseRequestBuilder } from "./http-abstract-base-request-builder.intf"; import { StarkResource } from "../entities/resource.entity.intf"; +/** + * This StarkHttpUpdateRequestBuilder interface describes the different operations supported by Http request builders for resource-updating requests + */ export interface StarkHttpUpdateRequestBuilder extends StarkHttpBaseRequestBuilder {} diff --git a/packages/stark-core/src/modules/http/constants/echo-type.constants.ts b/packages/stark-core/src/modules/http/constants/echo-type.constants.ts index 30fa18a05b..478771e249 100644 --- a/packages/stark-core/src/modules/http/constants/echo-type.constants.ts +++ b/packages/stark-core/src/modules/http/constants/echo-type.constants.ts @@ -1,4 +1,13 @@ +/** + * Class used to specify whether a Http response should contain a response body. + */ export class StarkHttpEchoType { + /** + * NONE is used when the response does not contain a response body. + */ public static NONE: string = "NONE"; + /** + * ID is used to retrieve the reponse body's id. + */ public static ID: string = "ID"; } diff --git a/packages/stark-core/src/modules/http/constants/http-headers.constants.ts b/packages/stark-core/src/modules/http/constants/http-headers.constants.ts index e76c5fbe5f..180e8f7b78 100644 --- a/packages/stark-core/src/modules/http/constants/http-headers.constants.ts +++ b/packages/stark-core/src/modules/http/constants/http-headers.constants.ts @@ -1,19 +1,61 @@ +/** + * This class contains http headers needed when performing a Http Request + */ export class StarkHttpHeaders { + /** + * Contains information about the language preference of a user + */ public static ACCEPT_LANGUAGE: string = "Accept-Language"; + /** + * The ETag value + */ public static ETAG: string = "etag"; + /** + * The request will perform the action only if the entity given by the client matches the same entity on the server. + */ public static IF_MATCH: string = "If-Match"; + /** + * The media type of the body request + */ public static CONTENT_TYPE: string = "Content-Type"; + /** + * Used to prevent Cross Site Request Forgery + */ public static XSRF_TOKEN: string = "X-XSRF-TOKEN"; // NBB HTTP headers - // correlation ID + /** + * The correlation id between front-end and back-end. + * It is generated in the front-end and is sent on every request to the backend. + */ public static NBB_CORRELATION_ID: string = "nbb-correlation-id"; // authentication + /** + * The user's username + */ public static NBB_USER_NAME: string = "nbbuser"; + /** + * The user's firstname + */ public static NBB_FIRST_NAME: string = "nbbfirstname"; + /** + * The user's lastname + */ public static NBB_LAST_NAME: string = "nbblastname"; + /** + * The user's email adress + */ public static NBB_MAIL: string = "nbbmail"; + /** + * The user's language + */ public static NBB_LANGUAGE: string = "nbblanguage"; + /** + * Used to describe the user (team, workspace, ...) + */ public static NBB_DESCRIPTION: string = "nbbdescription"; + /** + * The user's groups (ADMIN, ...) + */ public static NBB_ROLES: string = "nbbgroups"; } diff --git a/packages/stark-core/src/modules/http/constants/http-query-parameters.constants.ts b/packages/stark-core/src/modules/http/constants/http-query-parameters.constants.ts index 286594cb7e..f3730dac9c 100644 --- a/packages/stark-core/src/modules/http/constants/http-query-parameters.constants.ts +++ b/packages/stark-core/src/modules/http/constants/http-query-parameters.constants.ts @@ -1,6 +1,21 @@ +/** + * This class defines the different query parameters supported by Stark. + */ export class StarkHttpQueryParameters { + /** + * the fields concerned by the queries + */ public static FIELDS: string = "fields"; + /** + * specifies the language of the content + */ public static LANG: string = "lang"; + /** + * specifies the style to apply to the reponse's elements + */ public static STYLE: string = "style"; + /** + * specifies if the reponse must be sorted or not + */ public static SORT: string = "sort"; } diff --git a/packages/stark-core/src/modules/http/constants/sort-order.constants.ts b/packages/stark-core/src/modules/http/constants/sort-order.constants.ts index b6dd3a3213..c82b706ab3 100644 --- a/packages/stark-core/src/modules/http/constants/sort-order.constants.ts +++ b/packages/stark-core/src/modules/http/constants/sort-order.constants.ts @@ -1,4 +1,13 @@ +/** + * Used to indicate if the elements retrieved with a request must be sorted ASC or DESC + */ export class StarkSortOrder { + /** + * The fields will be sorted ASC + */ public static ASC: string = "ASC"; + /** + * The fields will be sorted DESC + */ public static DESC: string = "DESC"; } diff --git a/packages/stark-core/src/modules/http/entities/backend/backend.entity.intf.ts b/packages/stark-core/src/modules/http/entities/backend/backend.entity.intf.ts index 75a717c84f..a18d4ad6cd 100644 --- a/packages/stark-core/src/modules/http/entities/backend/backend.entity.intf.ts +++ b/packages/stark-core/src/modules/http/entities/backend/backend.entity.intf.ts @@ -16,6 +16,7 @@ export interface StarkBackend { /** * Authentication type for that back-end. + * @link StarkBackendAuthenticationTypes */ authenticationType: StarkBackendAuthenticationTypes; diff --git a/packages/stark-core/src/modules/http/entities/backend/backend.entity.ts b/packages/stark-core/src/modules/http/entities/backend/backend.entity.ts index 1eb9ab03aa..ca857590f2 100644 --- a/packages/stark-core/src/modules/http/entities/backend/backend.entity.ts +++ b/packages/stark-core/src/modules/http/entities/backend/backend.entity.ts @@ -2,7 +2,9 @@ import { IsDefined, IsNotEmpty, IsString, IsUrl } from "class-validator"; import { autoserialize, autoserializeAs } from "cerialize"; import { StarkBackend } from "./backend.entity.intf"; import { StarkBackendAuthenticationTypes } from "./backend-authentication-types"; - +/** + * @ignore + */ export class StarkBackendImpl implements StarkBackend { // validation must be performed always, regardless of validation groups used @IsNotEmpty({ message: "each backend object MUST have a name", always: true }) diff --git a/packages/stark-core/src/modules/http/entities/error/http-error-base.entity.intf.ts b/packages/stark-core/src/modules/http/entities/error/http-error-base.entity.intf.ts index ec70e01406..47988bcf23 100644 --- a/packages/stark-core/src/modules/http/entities/error/http-error-base.entity.intf.ts +++ b/packages/stark-core/src/modules/http/entities/error/http-error-base.entity.intf.ts @@ -1,11 +1,36 @@ import { StarkError } from "../../../../common"; +/** + * The StarkHttpErrorBase class contains all the basic information about the error(s) that are part of the Http + * error in case of failure of any type of request performed by the Stark Http Service. + */ export interface StarkHttpErrorBase extends StarkError { + /** + * The absolute URI that identifies the problem type. + */ type: string; + /** + * Short human-readable summary of the problem type. + */ title: string; + /** + * A message key for the summary of the problem type. + */ titleKey: string; + /** + * An array of strings, each string being the value of a parameter in the titleKey + */ titleKeyParameters?: string[]; + /** + * Identifies the specific occurrence of the problem. + */ instance?: string; + /** + * Provides a timestamp for the error message. + */ timestamp?: string; + /** + * Provides additional error metadata. + */ metadata?: object; } diff --git a/packages/stark-core/src/modules/http/entities/error/http-error-base.entity.ts b/packages/stark-core/src/modules/http/entities/error/http-error-base.entity.ts index 4d863ab4bb..dcc591b901 100644 --- a/packages/stark-core/src/modules/http/entities/error/http-error-base.entity.ts +++ b/packages/stark-core/src/modules/http/entities/error/http-error-base.entity.ts @@ -2,7 +2,9 @@ import { autoserialize, inheritSerialization } from "cerialize"; import { StarkErrorImpl } from "../../../../common"; import { StarkHttpErrorBase } from "./http-error-base.entity.intf"; - +/** + * @ignore + */ @inheritSerialization(StarkErrorImpl) export class StarkHttpErrorBaseImpl extends StarkErrorImpl implements StarkHttpErrorBase { public constructor(error: Error) { diff --git a/packages/stark-core/src/modules/http/entities/error/http-error-detail.entity.intf.ts b/packages/stark-core/src/modules/http/entities/error/http-error-detail.entity.intf.ts index 1d127b5d0c..0e2cdaa21c 100644 --- a/packages/stark-core/src/modules/http/entities/error/http-error-detail.entity.intf.ts +++ b/packages/stark-core/src/modules/http/entities/error/http-error-detail.entity.intf.ts @@ -1,10 +1,31 @@ import { StarkHttpErrorBase } from "./http-error-base.entity.intf"; - +/** + * The StarkHttpErrorDetail class contains all the information about the error(s) that are part of the Http + * error in case of failure of any type of request performed by the Stark Http Service and it is wrapped in a StarkHttpError. + */ export interface StarkHttpErrorDetail extends StarkHttpErrorBase { + /** + * Human-readable explanation specific to this occurrence of the problem. + */ detail: string; + /** + * A message key for the detailed explanation specific to this occurrence of the problem. + */ detailKey: string; + /** + * An array of strings, each string being the value of a parameter in a detailKey. + */ detailKeyParameters?: string[]; + /** + * An array of strings, each string being the identifier of a field related to this specific error. + */ fields?: string[]; + /** + * The Http status code for this specific error. + */ status?: string; + /** + * An integer value (zero-based) corresponding to the position in the source collection + */ index?: number; } diff --git a/packages/stark-core/src/modules/http/entities/error/http-error-detail.entity.ts b/packages/stark-core/src/modules/http/entities/error/http-error-detail.entity.ts index 6b6d37c95f..b02287587c 100644 --- a/packages/stark-core/src/modules/http/entities/error/http-error-detail.entity.ts +++ b/packages/stark-core/src/modules/http/entities/error/http-error-detail.entity.ts @@ -1,7 +1,9 @@ import { autoserialize, inheritSerialization } from "cerialize"; import { StarkHttpErrorBaseImpl } from "./http-error-base.entity"; import { StarkHttpErrorDetail } from "./http-error-detail.entity.intf"; - +/** + * @ignore + */ @inheritSerialization(StarkHttpErrorBaseImpl) export class StarkHttpErrorDetailImpl extends StarkHttpErrorBaseImpl implements StarkHttpErrorDetail { @autoserialize public detail: string; diff --git a/packages/stark-core/src/modules/http/entities/error/http-error-wrapper.entity.intf.ts b/packages/stark-core/src/modules/http/entities/error/http-error-wrapper.entity.intf.ts index 70340d7c5a..545e5bd1ce 100644 --- a/packages/stark-core/src/modules/http/entities/error/http-error-wrapper.entity.intf.ts +++ b/packages/stark-core/src/modules/http/entities/error/http-error-wrapper.entity.intf.ts @@ -1,6 +1,16 @@ import { StarkHttpResponse } from "../response"; import { StarkHttpError } from "./http-error.entity.intf"; +/** + * This class is used by the Stark Http Service in order to wrap the Http error in + * case of failure of any type of request, either single item or collection request. + */ export interface StarkHttpErrorWrapper extends StarkHttpResponse { + /** + * Contains all the information about the Http error in case of + * failure of any type of request performed by the Stark Http Service. + * + * @link StarkHttpError + */ httpError: StarkHttpError; } diff --git a/packages/stark-core/src/modules/http/entities/error/http-error-wrapper.entity.ts b/packages/stark-core/src/modules/http/entities/error/http-error-wrapper.entity.ts index b1b34f1a4b..977f38c6c2 100644 --- a/packages/stark-core/src/modules/http/entities/error/http-error-wrapper.entity.ts +++ b/packages/stark-core/src/modules/http/entities/error/http-error-wrapper.entity.ts @@ -4,7 +4,9 @@ import { StarkHttpError } from "./http-error.entity.intf"; import { StarkHttpErrorImpl } from "./http-error.entity"; import { StarkHttpErrorWrapper } from "./http-error-wrapper.entity.intf"; import { StarkHttpStatusCodes } from "../../enumerators"; - +/** + * @ignore + */ export class StarkHttpErrorWrapperImpl implements StarkHttpErrorWrapper { /** @internal */ private _starkHttpStatusCode: StarkHttpStatusCodes; diff --git a/packages/stark-core/src/modules/http/entities/error/http-error.entity.intf.ts b/packages/stark-core/src/modules/http/entities/error/http-error.entity.intf.ts index d0745159f4..c567ac8817 100644 --- a/packages/stark-core/src/modules/http/entities/error/http-error.entity.intf.ts +++ b/packages/stark-core/src/modules/http/entities/error/http-error.entity.intf.ts @@ -1,6 +1,14 @@ import { StarkHttpErrorBase } from "./http-error-base.entity.intf"; import { StarkHttpErrorDetail } from "./http-error-detail.entity.intf"; +/** + * The StarkHttpError class contains all the information about the Http error in case of failure of + * any type of request performed by the Stark Http Service and it is wrapped in a StarkHttpErrorWrapper. + */ export interface StarkHttpError extends StarkHttpErrorBase { + /** + * All information about the Http error. + * @link StarkHttpErrorDetail + */ errors: StarkHttpErrorDetail[]; } diff --git a/packages/stark-core/src/modules/http/entities/error/http-error.entity.ts b/packages/stark-core/src/modules/http/entities/error/http-error.entity.ts index e26d6adcc2..778192abd7 100644 --- a/packages/stark-core/src/modules/http/entities/error/http-error.entity.ts +++ b/packages/stark-core/src/modules/http/entities/error/http-error.entity.ts @@ -3,7 +3,9 @@ import { StarkHttpErrorBaseImpl } from "./http-error-base.entity"; import { StarkHttpError } from "./http-error.entity.intf"; import { StarkHttpErrorDetail } from "./http-error-detail.entity.intf"; import { StarkHttpErrorDetailImpl } from "./http-error-detail.entity"; - +/** + * @ignore + */ @inheritSerialization(StarkHttpErrorBaseImpl) export class StarkHttpErrorImpl extends StarkHttpErrorBaseImpl implements StarkHttpError { public constructor(error: Error) { diff --git a/packages/stark-core/src/modules/http/entities/http-request-type.entity.ts b/packages/stark-core/src/modules/http/entities/http-request-type.entity.ts index b8efef9f09..00195f3386 100644 --- a/packages/stark-core/src/modules/http/entities/http-request-type.entity.ts +++ b/packages/stark-core/src/modules/http/entities/http-request-type.entity.ts @@ -1,12 +1,48 @@ +/** + * A list of all Http request types supported by Stark + */ export class StarkHttpRequestType { + /** + * The Http Create request type. + */ public static CREATE: string = "CREATE"; + /** + * The Http Create (bulk) request type. + * Used to create several items with the same characteristics at a time. + */ public static CREATE_BULK: string = "CREATE_BULK"; + /** + * The Http Update request type (POST). + */ public static UPDATE: string = "UPDATE"; + /** + * The Http Update request type (PUT). + */ public static UPDATE_IDEMPOTENT: string = "UPDATE_IDEMPOTENT"; + /** + * The Http Update (bulk) request type. + * Used to update several items with the same characteristics at a time. + */ public static UPDATE_BULK: string = "UPDATE_BULK"; + /** + * The Http Delete request type. + */ public static DELETE: string = "DELETE"; + /** + * The Http Delete (bulk) request type. + * Used to delete several items with the same characteristics at a time. + */ public static DELETE_BULK: string = "DELETE_BULK"; + /** + * The Http Get request type. + */ public static GET: string = "GET"; + /** + * The Http Get Collection request type, to fetch several items at a time. + */ public static GET_COLLECTION: string = "GET_COLLECTION"; + /** + * The Http Search request type. + */ public static SEARCH: string = "SEARCH"; } diff --git a/packages/stark-core/src/modules/http/entities/http-request.entity.intf.ts b/packages/stark-core/src/modules/http/entities/http-request.entity.intf.ts index 91dbcc5cb2..184e03030f 100644 --- a/packages/stark-core/src/modules/http/entities/http-request.entity.intf.ts +++ b/packages/stark-core/src/modules/http/entities/http-request.entity.intf.ts @@ -6,15 +6,55 @@ import { StarkHttpSerializer } from "../serializer"; export type StarkQueryParam = string | string[] | undefined; +/** + * This interface describes all the available options of an Http request performed via the StarkHttpService. + */ export interface StarkHttpRequest

{ + /** + * The backend that the request will target. + * @link StarkBackend + */ backend: StarkBackend; + /** + * The path of the request's target resource. + */ resourcePath: string; + /** + * The sort criteria that will be sent along with the request as query parameters. + * @link StarkSortItem + */ sortItems?: StarkSortItem[]; + /** + * Array of fields that the backend is requested to include in the response. + */ fieldsToInclude?: string[]; + /** + * Map containing the headers to be sent with the request. + */ headers: Map; + /** + * Map containing the parameters that will be included as query parameters. + * The query parameters might be undefined values in case the allowUndefinedQueryParams option is enabled and passed to the corresponding builder. + * If an array of strings is defined as value, then the parameter will be added to the URL for every value in the array. + * @link StarkQueryParam + */ queryParameters: Map; + /** + * The type of request according to the different CRUD operations. + * @link StarkHttpRequestType + */ requestType: StarkHttpRequestType; + /** + * The items/resources to send in the request (if needed). + */ item?: P | { [param: string]: any }; + /** + * A serializer class that will perform the serialization/deserialization of the items to be sent/received to/from the backend. + * @link StarkHttpSerializer + */ serializer: StarkHttpSerializer

; + /** + * The number of times the request will be retried in case of error. + */ retryCount?: number; } diff --git a/packages/stark-core/src/modules/http/entities/metadata/collection-metadata.entity.intf.ts b/packages/stark-core/src/modules/http/entities/metadata/collection-metadata.entity.intf.ts index 862ae05c6a..0adf656fc8 100644 --- a/packages/stark-core/src/modules/http/entities/metadata/collection-metadata.entity.intf.ts +++ b/packages/stark-core/src/modules/http/entities/metadata/collection-metadata.entity.intf.ts @@ -3,16 +3,22 @@ import { StarkPaginationMetadata } from "./metadata-pagination.entity.intf"; import { StarkETags } from "./metadata-etags.entity.intf"; import { StarkWarnings } from "./metadata-warnings.entity.intf"; +/** + * Stark Collection Metadata + * Contains all the metadata related to the collection of items in the response of GetCollection or Search request. + */ export interface StarkCollectionMetadata extends StarkETags, StarkWarnings { /** * Object containing sorting metadata * @link https://github.com/NationalBankBelgium/REST-API-Design-Guide/wiki/Sorting-Metadata + * @link StarkSortItem */ sortedBy: StarkSortItem[]; /** * Object containing pagination metadata * @link https://github.com/NationalBankBelgium/REST-API-Design-Guide/wiki/Pagination-Rules-and-metadata#pagination-metadata + * @link StarkPaginationMetadata */ pagination: StarkPaginationMetadata; diff --git a/packages/stark-core/src/modules/http/entities/metadata/collection-metadata.entity.ts b/packages/stark-core/src/modules/http/entities/metadata/collection-metadata.entity.ts index a7497c71eb..f9318660de 100644 --- a/packages/stark-core/src/modules/http/entities/metadata/collection-metadata.entity.ts +++ b/packages/stark-core/src/modules/http/entities/metadata/collection-metadata.entity.ts @@ -6,7 +6,9 @@ import { StarkSortItemImpl } from "./metadata-sort-item.entity"; import { StarkPaginationMetadata } from "./metadata-pagination.entity.intf"; import { StarkPaginationMetadataImpl } from "./metadata-pagination.entity"; import { StarkHttpErrorDetail, StarkHttpErrorDetailImpl } from "../error"; - +/** + * @ignore + */ export class StarkCollectionMetadataImpl implements StarkCollectionMetadata { @deserializeAs(StarkSortItemImpl) public sortedBy: StarkSortItem[]; diff --git a/packages/stark-core/src/modules/http/entities/metadata/metadata-etags.entity.intf.ts b/packages/stark-core/src/modules/http/entities/metadata/metadata-etags.entity.intf.ts index 3f48d529b2..c0ea6dfff4 100644 --- a/packages/stark-core/src/modules/http/entities/metadata/metadata-etags.entity.intf.ts +++ b/packages/stark-core/src/modules/http/entities/metadata/metadata-etags.entity.intf.ts @@ -1,3 +1,6 @@ +/** + * Interface that describes the etags array to be included in a GetCollection response + */ export interface StarkETags { /** * For collection responses only. diff --git a/packages/stark-core/src/modules/http/entities/metadata/metadata-pagination.entity.ts b/packages/stark-core/src/modules/http/entities/metadata/metadata-pagination.entity.ts index da4a9f1c87..a5ebaac072 100644 --- a/packages/stark-core/src/modules/http/entities/metadata/metadata-pagination.entity.ts +++ b/packages/stark-core/src/modules/http/entities/metadata/metadata-pagination.entity.ts @@ -1,6 +1,8 @@ import { deserialize } from "cerialize"; import { StarkPaginationMetadata } from "./metadata-pagination.entity.intf"; - +/** + * @ignore + */ export class StarkPaginationMetadataImpl implements StarkPaginationMetadata { @deserialize public offset: number; diff --git a/packages/stark-core/src/modules/http/entities/metadata/metadata-sort-item.entity.intf.ts b/packages/stark-core/src/modules/http/entities/metadata/metadata-sort-item.entity.intf.ts index 85d4d8a8c8..65771d9087 100644 --- a/packages/stark-core/src/modules/http/entities/metadata/metadata-sort-item.entity.intf.ts +++ b/packages/stark-core/src/modules/http/entities/metadata/metadata-sort-item.entity.intf.ts @@ -1,5 +1,19 @@ +/** + * The StarkSortItem class contains the different sort criteria for the items contained in the response of a collection request performed by the Stark Http Service. + * This information is serialized by the service into the request query parameters and deserialized from the response in the StarkCollectionMetadata object. + */ export interface StarkSortItem { + /** + * The field on which the sorting is done. + */ field: string; + /** + * The order of the sorting on that field: ASC|DESC. + */ order: string; + /** + * The combination of field + order. + * This is the computed value that is sent in the request as query parameter. For example: title+DESC + */ sortValue?: string; } diff --git a/packages/stark-core/src/modules/http/entities/metadata/metadata-sort-item.entity.ts b/packages/stark-core/src/modules/http/entities/metadata/metadata-sort-item.entity.ts index 9be2dc91eb..ec8088c796 100644 --- a/packages/stark-core/src/modules/http/entities/metadata/metadata-sort-item.entity.ts +++ b/packages/stark-core/src/modules/http/entities/metadata/metadata-sort-item.entity.ts @@ -1,7 +1,9 @@ import { deserialize } from "cerialize"; import { StarkSortItem } from "./metadata-sort-item.entity.intf"; - +/** + * @ignore + */ export class StarkSortItemImpl implements StarkSortItem { @deserialize public field: string; diff --git a/packages/stark-core/src/modules/http/entities/metadata/metadata-warnings.entity.intf.ts b/packages/stark-core/src/modules/http/entities/metadata/metadata-warnings.entity.intf.ts index 18d6aa0a15..46a5898e2a 100644 --- a/packages/stark-core/src/modules/http/entities/metadata/metadata-warnings.entity.intf.ts +++ b/packages/stark-core/src/modules/http/entities/metadata/metadata-warnings.entity.intf.ts @@ -1,5 +1,8 @@ import { StarkHttpErrorDetail } from "../error"; +/** + * Interface that describes the warnings array to be included in an http response. + */ export interface StarkWarnings { /** * Warnings sent by the backend as a result of server-side validations. @@ -7,6 +10,7 @@ export interface StarkWarnings { * in the collection "metadata" object for collection responses. * @link https://github.com/NationalBankBelgium/REST-API-Design-Guide/wiki/Pagination-Rules-and-metadata * @link https://github.com/NationalBankBelgium/REST-API-Design-Guide/wiki/Error-handling-Warnings + * @link StarkHttpErrorDetail */ warnings?: StarkHttpErrorDetail[]; } diff --git a/packages/stark-core/src/modules/http/entities/metadata/single-item-metadata.entity.intf.ts b/packages/stark-core/src/modules/http/entities/metadata/single-item-metadata.entity.intf.ts index 923c5752cc..e1d0180692 100644 --- a/packages/stark-core/src/modules/http/entities/metadata/single-item-metadata.entity.intf.ts +++ b/packages/stark-core/src/modules/http/entities/metadata/single-item-metadata.entity.intf.ts @@ -1,3 +1,6 @@ import { StarkWarnings } from "./metadata-warnings.entity.intf"; +/** + * The StarkSingleItemMetadata interface extends the StarkWarnings interface that describes the "warnings" property with no additions. + */ export interface StarkSingleItemMetadata extends StarkWarnings {} diff --git a/packages/stark-core/src/modules/http/entities/metadata/single-item-metadata.entity.ts b/packages/stark-core/src/modules/http/entities/metadata/single-item-metadata.entity.ts index 15490d02e4..a1b773f314 100644 --- a/packages/stark-core/src/modules/http/entities/metadata/single-item-metadata.entity.ts +++ b/packages/stark-core/src/modules/http/entities/metadata/single-item-metadata.entity.ts @@ -2,6 +2,9 @@ import { deserializeAs } from "cerialize"; import { StarkSingleItemMetadata } from "./single-item-metadata.entity.intf"; import { StarkHttpErrorDetail, StarkHttpErrorDetailImpl } from "../error"; +/** + * @ignore + */ export class StarkSingleItemMetadataImpl implements StarkSingleItemMetadata { @deserializeAs(StarkHttpErrorDetailImpl) public warnings?: StarkHttpErrorDetail[]; } diff --git a/packages/stark-core/src/modules/http/entities/resource.entity.intf.ts b/packages/stark-core/src/modules/http/entities/resource.entity.intf.ts index 649f1ceb80..eadc8f76ab 100644 --- a/packages/stark-core/src/modules/http/entities/resource.entity.intf.ts +++ b/packages/stark-core/src/modules/http/entities/resource.entity.intf.ts @@ -1,12 +1,26 @@ import { StarkSingleItemMetadata } from "./metadata"; +/** + * StarkResource is an interface that describes a Resource. + * This interface must be implemented by all entities that are related to back-end REST resources. + */ export interface StarkResource { + /** + * The uuid of this item. + * this SHOULD always be the UUID of the resource! + */ uuid: string; + + /** + * The ETAG of this item. + * this value will be handled by the Stark HTTP API automatically for you + */ etag?: string; /** * Optionally, in single item responses only, the backend may return warnings along with the resource itself * @link https://github.com/NationalBankBelgium/REST-API-Design-Guide/wiki/Error-handling-Warnings + * @link StarkSingleItemMetadata */ metadata?: StarkSingleItemMetadata; } diff --git a/packages/stark-core/src/modules/http/entities/response/collection-response-wrapper.entity.intf.ts b/packages/stark-core/src/modules/http/entities/response/collection-response-wrapper.entity.intf.ts index d4d133cfa3..bfceecdedd 100644 --- a/packages/stark-core/src/modules/http/entities/response/collection-response-wrapper.entity.intf.ts +++ b/packages/stark-core/src/modules/http/entities/response/collection-response-wrapper.entity.intf.ts @@ -2,6 +2,13 @@ import { StarkResponseWrapper } from "./response-wrapper.entity.intf"; import { StarkResource } from "../resource.entity.intf"; import { StarkCollectionMetadata } from "../metadata"; +/** + * This class is used by the Stark Http Service in order to wrap the Http response from all requests aimed to return a collection of items. + */ export interface StarkCollectionResponseWrapper

extends StarkResponseWrapper { + /** + * Holds the metadata related to the collection of items contained in the response. + * @link StarkCollectionMetadata + */ metadata: StarkCollectionMetadata; } diff --git a/packages/stark-core/src/modules/http/entities/response/collection-response-wrapper.entity.ts b/packages/stark-core/src/modules/http/entities/response/collection-response-wrapper.entity.ts index 8b4ff9acfe..386e083ee7 100644 --- a/packages/stark-core/src/modules/http/entities/response/collection-response-wrapper.entity.ts +++ b/packages/stark-core/src/modules/http/entities/response/collection-response-wrapper.entity.ts @@ -2,7 +2,9 @@ import { StarkCollectionResponseWrapper } from "./collection-response-wrapper.en import { StarkResource } from "../resource.entity.intf"; import { StarkCollectionMetadata } from "../metadata"; import { StarkHttpStatusCodes } from "../../enumerators"; - +/** + * @ignore + */ export class StarkCollectionResponseWrapperImpl implements StarkCollectionResponseWrapper { /** @internal */ private _starkHttpStatusCode: StarkHttpStatusCodes; diff --git a/packages/stark-core/src/modules/http/entities/response/http-raw-collection-response-data.intf.ts b/packages/stark-core/src/modules/http/entities/response/http-raw-collection-response-data.intf.ts index d646885bb6..c0dc8c7f6d 100644 --- a/packages/stark-core/src/modules/http/entities/response/http-raw-collection-response-data.intf.ts +++ b/packages/stark-core/src/modules/http/entities/response/http-raw-collection-response-data.intf.ts @@ -1,6 +1,16 @@ import { StarkCollectionMetadata } from "../metadata"; +/** + * This class represents a raw collection of data retrieved with a GetCollection request. + */ export interface StarkHttpRawCollectionResponseData

{ + /** + * Contains a raw collection of items. + */ items: P[]; + /** + * Contains all the metadata related to the collection of items in the response. + * @link StarkCollectionMetadata + */ metadata: StarkCollectionMetadata; } diff --git a/packages/stark-core/src/modules/http/entities/response/http-response.entity.intf.ts b/packages/stark-core/src/modules/http/entities/response/http-response.entity.intf.ts index f28789c6da..9b1ca48725 100644 --- a/packages/stark-core/src/modules/http/entities/response/http-response.entity.intf.ts +++ b/packages/stark-core/src/modules/http/entities/response/http-response.entity.intf.ts @@ -1,6 +1,16 @@ import { StarkHttpStatusCodes } from "../../enumerators"; +/** + * This interface represents an HttpResponse + */ export interface StarkHttpResponse { + /** + * The corresponding status code of the request matching one of the StarkHttpStatusCodes. + * @link StarkHttpStatusCodes + */ starkHttpStatusCode: StarkHttpStatusCodes; + /** + * A map containing the Http response headers sent back by the backend. + */ starkHttpHeaders: Map; } diff --git a/packages/stark-core/src/modules/http/entities/response/response-wrapper.entity.intf.ts b/packages/stark-core/src/modules/http/entities/response/response-wrapper.entity.intf.ts index a3150f873e..8073120921 100644 --- a/packages/stark-core/src/modules/http/entities/response/response-wrapper.entity.intf.ts +++ b/packages/stark-core/src/modules/http/entities/response/response-wrapper.entity.intf.ts @@ -1,5 +1,11 @@ import { StarkHttpResponse } from "./http-response.entity.intf"; +/** + * This class is used by the Stark Http Service in order to wrap the Http response from all requests aimed to return item(s). + */ export interface StarkResponseWrapper extends StarkHttpResponse { + /** + * Holds the data if the Http request was successful. + */ data: T; } diff --git a/packages/stark-core/src/modules/http/entities/response/single-item-response-wrapper.entity.intf.ts b/packages/stark-core/src/modules/http/entities/response/single-item-response-wrapper.entity.intf.ts index baa7d3f335..e635e61d58 100644 --- a/packages/stark-core/src/modules/http/entities/response/single-item-response-wrapper.entity.intf.ts +++ b/packages/stark-core/src/modules/http/entities/response/single-item-response-wrapper.entity.intf.ts @@ -1,4 +1,7 @@ import { StarkResponseWrapper } from "./response-wrapper.entity.intf"; import { StarkResource } from "../resource.entity.intf"; +/** + * This class is used by the Stark Http Service in order to wrap the Http response from all requests aimed to return a single item. + */ export interface StarkSingleItemResponseWrapper extends StarkResponseWrapper {} diff --git a/packages/stark-core/src/modules/http/entities/response/single-item-response-wrapper.entity.ts b/packages/stark-core/src/modules/http/entities/response/single-item-response-wrapper.entity.ts index 84265d9bfd..13efa142ac 100644 --- a/packages/stark-core/src/modules/http/entities/response/single-item-response-wrapper.entity.ts +++ b/packages/stark-core/src/modules/http/entities/response/single-item-response-wrapper.entity.ts @@ -1,7 +1,9 @@ import { StarkSingleItemResponseWrapper } from "./single-item-response-wrapper.entity.intf"; import { StarkResource } from "../resource.entity.intf"; import { StarkHttpStatusCodes } from "../../enumerators"; - +/** + * @ignore + */ export class StarkSingleItemResponseWrapperImpl implements StarkSingleItemResponseWrapper { /** @internal */ private _starkHttpStatusCode: StarkHttpStatusCodes; diff --git a/packages/stark-core/src/modules/http/enumerators/http-status-code.enum.ts b/packages/stark-core/src/modules/http/enumerators/http-status-code.enum.ts index b50d762672..e2a820d460 100644 --- a/packages/stark-core/src/modules/http/enumerators/http-status-code.enum.ts +++ b/packages/stark-core/src/modules/http/enumerators/http-status-code.enum.ts @@ -1,3 +1,6 @@ +/** + * All status code for Http Request supported by Stark + */ export enum StarkHttpStatusCodes { HTTP_200_OK = 200, HTTP_201_CREATED = 201, diff --git a/packages/stark-core/src/modules/http/http.module.ts b/packages/stark-core/src/modules/http/http.module.ts index 2aa5655f30..042f211973 100644 --- a/packages/stark-core/src/modules/http/http.module.ts +++ b/packages/stark-core/src/modules/http/http.module.ts @@ -6,9 +6,12 @@ import { STARK_HTTP_SERVICE, StarkHttpServiceImpl } from "./services"; imports: [HttpClientModule] }) export class StarkHttpModule { - // instantiate the services only once since they should be singletons - // so the forRoot() should be called only by the AppModule - // see https://angular.io/guide/singleton-services#forroot + /** + * Instantiates the services only once since they should be singletons + * so the forRoot() should be called only by the AppModule + * @link https://angular.io/guide/singleton-services#forroot + * @returns a module with providers + */ public static forRoot(): ModuleWithProviders { return { ngModule: StarkHttpModule, @@ -16,8 +19,11 @@ export class StarkHttpModule { }; } - // prevent this module from being re-imported - // see https://angular.io/guide/singleton-services#prevent-reimport-of-the-coremodule + /** + * prevent this module from being re-imported + * @link https://angular.io/guide/singleton-services#prevent-reimport-of-the-coremodule + * @param the parent module + */ public constructor( @Optional() @SkipSelf() diff --git a/packages/stark-core/src/modules/http/repository/http-abstract-repository.spec.ts b/packages/stark-core/src/modules/http/repository/http-abstract-repository.spec.ts index 2ca267fae6..0fa39773fd 100644 --- a/packages/stark-core/src/modules/http/repository/http-abstract-repository.spec.ts +++ b/packages/stark-core/src/modules/http/repository/http-abstract-repository.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { Observable } from "rxjs"; import { AbstractStarkHttpRepository } from "./http-abstract-repository"; import { StarkSerializable } from "../../../serialization"; diff --git a/packages/stark-core/src/modules/http/repository/http-abstract-repository.ts b/packages/stark-core/src/modules/http/repository/http-abstract-repository.ts index f598491017..bae6fdfd3d 100644 --- a/packages/stark-core/src/modules/http/repository/http-abstract-repository.ts +++ b/packages/stark-core/src/modules/http/repository/http-abstract-repository.ts @@ -16,13 +16,46 @@ import { StarkLoggingService } from "../../logging/services"; import { StarkSerializable } from "../../../serialization"; import { StarkHttpSerializer, StarkHttpSerializerImpl } from "../serializer"; +/** + * This abstract class provides methods for the most common requests to be performed so it can be extended by your own Http repositories. + */ export abstract class AbstractStarkHttpRepository { + /** + * The Http Service provided by Stark + * @link StarkHttpService + */ protected starkHttpService: StarkHttpService; + /** + * The logging service. + * @link StarkLoggingService + */ protected logger: StarkLoggingService; + /** + * The backend that this HttpRespository will target. + * @link StarkBackend + */ protected backend: StarkBackend; + /** + * + * The resource path that will be used as default for all the requests performed by this HttpRespository. + * This will be replaced by the resourcePath provided (if any) in the getRequestBuilder() method. + */ protected resourcePath: string; + /** + * + * The serializer that will be attached by default to every StarkHttpRequest sent by this HttpRespository + * to serialize/deserialize the items to be sent/received to/from the backend. + */ protected serializer: StarkHttpSerializer; + /** + * Class constructor + * @param starkHttpService - the Http Service provided by Stark + * @param logger - the logging service + * @param backend - the backend to target + * @param resourcePath - the path used by default + * @param serializer - the serializer used by default + */ public constructor( starkHttpService: StarkHttpService, logger: StarkLoggingService, @@ -51,6 +84,11 @@ export abstract class AbstractStarkHttpRepository { } } + /** + * Perform an Http request to create a resource item. + * @param item - the item to create + * @param params - the parameters used to create the item + */ public create(item: T, params?: StarkHttpCreateRequestParams): Observable> { return this.starkHttpService.executeSingleItemRequest( this.getRequestBuilder() @@ -59,6 +97,11 @@ export abstract class AbstractStarkHttpRepository { ); } + /** + * Perform an Http request to update an existing resource item. + * @param item - the item to update + * @param params - the parameters used to update the item + */ public update(item: T, params?: StarkHttpUpdateRequestParams): Observable> { return this.starkHttpService.executeSingleItemRequest( this.getRequestBuilder() @@ -67,6 +110,11 @@ export abstract class AbstractStarkHttpRepository { ); } + /** + * Perform an Http request to delete a resource item. + * @param item - the item to delete + * @param params - the parameters used to delete the item + */ public delete(item: T, params?: StarkHttpDeleteRequestParams): Observable> { return this.starkHttpService.executeSingleItemRequest( this.getRequestBuilder() @@ -75,6 +123,11 @@ export abstract class AbstractStarkHttpRepository { ); } + /** + * Perform an Http request to fetch a resource item. + * @param uuid - the uuid of the item to fetch + * @param params - the parameters used to fetch the item + */ public get(uuid: string, params?: StarkHttpGetRequestParams): Observable> { return this.starkHttpService.executeSingleItemRequest( this.getRequestBuilder() @@ -83,6 +136,12 @@ export abstract class AbstractStarkHttpRepository { ); } + /** + * Perform an Http request to fetch a range of resource items based on the limit and offset. + * @param limit - the limit to apply to the request + * @param offset - the offset to apply to the request + * @param params - the parameters to apply to the request + */ public getCollection( limit: number, offset: number, @@ -95,6 +154,13 @@ export abstract class AbstractStarkHttpRepository { ); } + /** + * Perform an Http request to fetch a range of resource items that match with the given criteria. + * @param criteria - the criteria of the request + * @param limit - the limit to apply to the request + * @param offset - the offset to apply to the request + * @param params - the parameters to apply to the request + */ public search( criteria: { [param: string]: string }, limit: number, @@ -108,6 +174,10 @@ export abstract class AbstractStarkHttpRepository { ); } + /** + * Return a new instance of StarkHttpRequestBuilder which can be used to construct an StarkHttpRequest via one of the StarkHttpBuilder variants. + * @param resourcePath: the resourcePath of the requestBuilder + */ // the default resourcePath of the returned builder will be replaced with the one that is passed here (if any) public getRequestBuilder(resourcePath?: string): StarkHttpRequestBuilder { // set the default serializer in case no custom serializer was defined @@ -116,5 +186,11 @@ export abstract class AbstractStarkHttpRepository { return new StarkHttpRequestBuilderImpl(this.backend, resourcePath || this.resourcePath, this.serializer); } + /** + * Return the type of a class to be used in order to deserialize (using the default StarkHttpSerializerImpl + * or a custom serializer) the Http response of the different requests. + * This method must be implemented in every Http repository that extends this abstract class + * and the returned class should have the correct serialization decorators. + */ protected abstract get type(): StarkSerializable; } diff --git a/packages/stark-core/src/modules/http/serializer/http-discriminator-serializer.spec.ts b/packages/stark-core/src/modules/http/serializer/http-discriminator-serializer.spec.ts index 320d46384e..ae7718def9 100644 --- a/packages/stark-core/src/modules/http/serializer/http-discriminator-serializer.spec.ts +++ b/packages/stark-core/src/modules/http/serializer/http-discriminator-serializer.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { StarkHttpDiscriminatorSerializer } from "./http-discriminator-serializer"; import { autoserialize, inheritSerialization } from "cerialize"; import { StarkSerializable } from "../../../serialization"; diff --git a/packages/stark-core/src/modules/http/serializer/http-discriminator-serializer.ts b/packages/stark-core/src/modules/http/serializer/http-discriminator-serializer.ts index c0ef383437..6a149961f6 100644 --- a/packages/stark-core/src/modules/http/serializer/http-discriminator-serializer.ts +++ b/packages/stark-core/src/modules/http/serializer/http-discriminator-serializer.ts @@ -8,11 +8,17 @@ import { StarkSerializable } from "../../../serialization"; * */ export class StarkHttpDiscriminatorSerializer extends StarkHttpSerializerImpl { + /** + * The discriminator property to decide what class to use for serialization + */ private discriminatorProperty: string; + /** + * Map of types based on the discriminator property value + */ private typesMap: Map; /** - * + * Constructor for StarkHttpDiscriminatorSerializer * @param discriminatorProperty - The discriminator property * @param typesMap - Map of types based on the discriminator property value */ @@ -22,6 +28,10 @@ export class StarkHttpDiscriminatorSerializer extends S this.typesMap = typesMap; } + /** + * Get the serializable class to use for deserialization/serialization. + * @param rawOrResource: the string or object which type we want to retrieve + */ public getType(rawOrResource: T | object | string): StarkSerializable | undefined { let obj: object; if (typeof rawOrResource === "string") { diff --git a/packages/stark-core/src/modules/http/serializer/http-serializer.intf.ts b/packages/stark-core/src/modules/http/serializer/http-serializer.intf.ts index aa2dbc248b..5fd3180e2d 100644 --- a/packages/stark-core/src/modules/http/serializer/http-serializer.intf.ts +++ b/packages/stark-core/src/modules/http/serializer/http-serializer.intf.ts @@ -2,7 +2,7 @@ import { HttpResponse } from "@angular/common/http"; import { StarkHttpRawCollectionResponseData, StarkHttpRequest, StarkResource } from "../entities"; /** - * @whatItDoes This is the base interface for entities' serializers used mainly by the HTTP Service. + * This is the base interface for entities' serializers used mainly by the HTTP Service. * * ResourceType type that this serializer handles. * RequestType, defaults to StarkHttpRequest diff --git a/packages/stark-core/src/modules/http/serializer/http-serializer.ts b/packages/stark-core/src/modules/http/serializer/http-serializer.ts index 6d91565332..d4df579e4f 100644 --- a/packages/stark-core/src/modules/http/serializer/http-serializer.ts +++ b/packages/stark-core/src/modules/http/serializer/http-serializer.ts @@ -4,26 +4,38 @@ import { StarkResource } from "../entities"; import { StarkSerializable } from "../../../serialization"; /** + * @ignore * Implementation of {@link StarkHttpSerializer} which uses the cerialize library behind the hoods. * This is the default implementation used by {@link StarkHttpServiceImpl} for serializing/deserializing entities. * * The class takes optionally a type Serializable in its constructor.. */ export class StarkHttpSerializerImpl implements StarkHttpSerializer { - /** @internal */ + /** + * Serializable class to be used for serialization. + */ protected _type: StarkSerializable | undefined; /** + * Class constructor * @param type - Default Type Serializable */ public constructor(type?: StarkSerializable) { this._type = type; } + /** + * Serialize the given resource entity into an object or a string. + * @param resource - the resource to serialize + */ public serialize(resource: T): string | object { return Serialize(resource, this.getType(resource)); } + /** + * Deserialize provided string or object into the corresponding resource entity. + * @param raw - the raw string or object to deserialize + */ public deserialize(raw: string | object): T { return Deserialize(raw, this.getType(raw)); } diff --git a/packages/stark-core/src/modules/http/services/http.service.intf.ts b/packages/stark-core/src/modules/http/services/http.service.intf.ts index a31981d468..ec907bbae4 100644 --- a/packages/stark-core/src/modules/http/services/http.service.intf.ts +++ b/packages/stark-core/src/modules/http/services/http.service.intf.ts @@ -3,7 +3,13 @@ import { HttpClient } from "@angular/common/http"; import { StarkCollectionResponseWrapper, StarkHttpRequest, StarkResource, StarkSingleItemResponseWrapper } from "../entities"; import { Observable } from "rxjs"; +/** + * The name of the service in case an injection is needed + */ export const starkHttpServiceName: string = "StarkHttpService"; +/** + * The InjectionToken version of the service name + */ export const STARK_HTTP_SERVICE: InjectionToken> = new InjectionToken>(starkHttpServiceName); /** diff --git a/packages/stark-core/src/modules/http/services/http.service.spec.ts b/packages/stark-core/src/modules/http/services/http.service.spec.ts index b10df518dc..9ce73df945 100644 --- a/packages/stark-core/src/modules/http/services/http.service.spec.ts +++ b/packages/stark-core/src/modules/http/services/http.service.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import createSpyObj = jasmine.createSpyObj; import Spy = jasmine.Spy; import SpyObj = jasmine.SpyObj; diff --git a/packages/stark-core/src/modules/http/services/http.service.ts b/packages/stark-core/src/modules/http/services/http.service.ts index 98b14306c0..0e2b968eec 100644 --- a/packages/stark-core/src/modules/http/services/http.service.ts +++ b/packages/stark-core/src/modules/http/services/http.service.ts @@ -1,3 +1,7 @@ +/* tslint:disable:completed-docs*/ +/** + * @ignore + */ const _cloneDeep: Function = require("lodash/cloneDeep"); import { Deserialize, Serialize } from "cerialize"; import { Observable, throwError, timer } from "rxjs"; @@ -25,13 +29,8 @@ import { STARK_LOGGING_SERVICE, StarkLoggingService } from "../../logging/servic import { STARK_SESSION_SERVICE, StarkSessionService } from "../../session/services"; /** - * @ngdoc service - * @name stark-core.service:StarkHttpService - * @description Service to make HTTP calls in compliance with the guidelines from the NBB REST API Design Guide. - * - * @requires StarkLoggingService - * @requires StarkSessionService - * @requires HttpClient + * @ignore + * Service to make HTTP calls in compliance with the guidelines from the NBB REST API Design Guide. */ @Injectable() export class StarkHttpServiceImpl

implements StarkHttpService

{ diff --git a/packages/stark-core/src/modules/http/testing/http.mock.ts b/packages/stark-core/src/modules/http/testing/http.mock.ts index f25c31f541..341ad11322 100644 --- a/packages/stark-core/src/modules/http/testing/http.mock.ts +++ b/packages/stark-core/src/modules/http/testing/http.mock.ts @@ -2,13 +2,31 @@ import { StarkHttpService } from "../services"; import { StarkHttpRequest, StarkSingleItemResponseWrapper, StarkCollectionResponseWrapper } from "../entities"; import { HttpClient } from "@angular/common/http"; import { Observable } from "rxjs"; - +/** + * Mock class of the StarkHttpService interface. + * @link StarkHttpService + */ export class MockStarkHttpService implements StarkHttpService { + /** + * Gets the core Angular HTTP API (HttpClient) + * @returns Angular Http client + */ public readonly rawHttpClient: HttpClient; + /** + * Executes requests to fetch a single resource + * @param request - The HTTP request to be executed + * @returns Observable that will emit the single item response wrapper + */ public executeSingleItemRequest: (request: StarkHttpRequest) => Observable> = jasmine.createSpy( "executeSingleItemRequest" ); + + /** + * Executes requests to fetch an array of resources + * @param request - The HTTP request to be executed + * @returns Observable that will emit the collection response wrapper + */ public executeCollectionRequest: (request: StarkHttpRequest) => Observable> = jasmine.createSpy( "executeCollectionRequest" ); diff --git a/packages/stark-core/src/modules/logging/actions/logging.actions.ts b/packages/stark-core/src/modules/logging/actions/logging.actions.ts index a5e94a61b7..f2f0470f75 100644 --- a/packages/stark-core/src/modules/logging/actions/logging.actions.ts +++ b/packages/stark-core/src/modules/logging/actions/logging.actions.ts @@ -4,7 +4,6 @@ import { StarkLogMessage } from "../entities"; /** * Actions related to stark logging service */ - export enum StarkLoggingActionTypes { SET_LOGGING_APPLICATION_ID = "[StarkLogging] Set Logging Application Id", LOG_MESSAGE = "[StarkLogging] Log Message", @@ -13,32 +12,52 @@ export enum StarkLoggingActionTypes { /** * Add the Application Name to the logging object - * @returns The created action object */ export class StarkSetLoggingApplicationId implements Action { + /** + * The type of action + * @link StarkLoggingActionTypes + */ public readonly type: StarkLoggingActionTypes.SET_LOGGING_APPLICATION_ID = StarkLoggingActionTypes.SET_LOGGING_APPLICATION_ID; + /** + * Class constructor + * @param applicationId - the id of the application + */ public constructor(public applicationId: string) {} } /** * Store a debug/info/warning/error message - * @param message - The message to log - * @returns The created action object */ export class StarkLogMessageAction implements Action { + /** + * The type of action + * @link StarkLoggingActionTypes + */ public readonly type: StarkLoggingActionTypes.LOG_MESSAGE = StarkLoggingActionTypes.LOG_MESSAGE; + /** + * Class constructor + * @param message - the message to log + */ public constructor(public message: StarkLogMessage) {} } /** * Persists the log messages in the redux store to the back-end - * @returns The created action object */ export class StarkFlushLogMessages implements Action { + /** + * The type of action + * @link StarkLoggingActionTypes + */ public readonly type: StarkLoggingActionTypes.FLUSH_LOG = StarkLoggingActionTypes.FLUSH_LOG; + /** + * Class constructor + * @param numberOfMessagesToFlush - the number of messages to flush + */ public constructor(public numberOfMessagesToFlush: number) {} } diff --git a/packages/stark-core/src/modules/logging/entities/log-message-type.entity.ts b/packages/stark-core/src/modules/logging/entities/log-message-type.entity.ts index fa0aeba9b9..d45e439dc0 100644 --- a/packages/stark-core/src/modules/logging/entities/log-message-type.entity.ts +++ b/packages/stark-core/src/modules/logging/entities/log-message-type.entity.ts @@ -1,6 +1,21 @@ +/** + * The type of logging messages that can be sent to the back-end + */ export class StarkLogMessageType { + /** + * The debug type + */ public static DEBUG: string = "DEBUG"; + /** + * The info type + */ public static INFO: string = "INFO"; + /** + * The warning type + */ public static WARNING: string = "WARNING"; + /** + * The error type + */ public static ERROR: string = "ERROR"; } diff --git a/packages/stark-core/src/modules/logging/entities/log-message.entity.intf.ts b/packages/stark-core/src/modules/logging/entities/log-message.entity.intf.ts index f551ab5757..4833cd1b4c 100644 --- a/packages/stark-core/src/modules/logging/entities/log-message.entity.intf.ts +++ b/packages/stark-core/src/modules/logging/entities/log-message.entity.intf.ts @@ -1,10 +1,30 @@ import { StarkLogMessageType } from "./log-message-type.entity"; import { StarkError } from "../../../common"; +/** + * Log message for Stark Application + */ export interface StarkLogMessage { + /** + * the timestamp of the message + */ timestamp: string; + /** + * the log message + */ message: string; + /** + * the type of message (debug, warn, info,...) + * @link StarkLogMessageType + */ type: StarkLogMessageType; + /** + * the correlation id of the log message + */ correlationId: string; + /** + * the (optional) error linked to the log message + * @link StarkError + */ error?: StarkError; } diff --git a/packages/stark-core/src/modules/logging/entities/log-message.entity.ts b/packages/stark-core/src/modules/logging/entities/log-message.entity.ts index 5d87d98239..e6ef6019fa 100644 --- a/packages/stark-core/src/modules/logging/entities/log-message.entity.ts +++ b/packages/stark-core/src/modules/logging/entities/log-message.entity.ts @@ -3,7 +3,9 @@ import { serialize, serializeAs } from "cerialize"; import { StarkLogMessageType } from "./log-message-type.entity"; import { StarkLogMessage } from "./log-message.entity.intf"; import { StarkError, StarkErrorImpl } from "../../../common"; - +/** + * @ignore + */ export class StarkLogMessageImpl implements StarkLogMessage { @serialize public timestamp: string; @serialize public message: string; diff --git a/packages/stark-core/src/modules/logging/entities/logging.entity.intf.ts b/packages/stark-core/src/modules/logging/entities/logging.entity.intf.ts index d4f14940e6..d671e65d13 100644 --- a/packages/stark-core/src/modules/logging/entities/logging.entity.intf.ts +++ b/packages/stark-core/src/modules/logging/entities/logging.entity.intf.ts @@ -1,7 +1,20 @@ import { StarkLogMessage } from "./log-message.entity.intf"; +/** + * The StarkLogging entity to be kept in the application state + */ export interface StarkLogging { + /** + * the uuid of the entity + */ uuid: string; + /** + * the id of the application + */ applicationId: string; + /** + * the messages being logged + * @link StarkLogMessage + */ messages: StarkLogMessage[]; } diff --git a/packages/stark-core/src/modules/logging/entities/logging.entity.ts b/packages/stark-core/src/modules/logging/entities/logging.entity.ts index 7aaba8291f..6404c45077 100644 --- a/packages/stark-core/src/modules/logging/entities/logging.entity.ts +++ b/packages/stark-core/src/modules/logging/entities/logging.entity.ts @@ -2,7 +2,9 @@ import { StarkLogMessage } from "./log-message.entity.intf"; import { StarkLogging } from "./logging.entity.intf"; import { serialize, serializeAs } from "cerialize"; import { StarkLogMessageImpl } from "./log-message.entity"; - +/** + * @ignore + */ export class StarkLoggingImpl implements StarkLogging { @serialize public uuid: string; @serialize public applicationId: string; diff --git a/packages/stark-core/src/modules/logging/logging.module.ts b/packages/stark-core/src/modules/logging/logging.module.ts index c7477bdee8..2b07528a2f 100644 --- a/packages/stark-core/src/modules/logging/logging.module.ts +++ b/packages/stark-core/src/modules/logging/logging.module.ts @@ -7,9 +7,12 @@ import { STARK_LOGGING_SERVICE, StarkLoggingServiceImpl } from "./services"; imports: [StoreModule.forFeature("StarkLogging", starkLoggingReducers)] }) export class StarkLoggingModule { - // instantiate the services only once since they should be singletons - // so the forRoot() should be called only by the AppModule - // see https://angular.io/guide/singleton-services#forroot + /** + * Instantiates the services only once since they should be singletons + * so the forRoot() should be called only by the AppModule + * @link https://angular.io/guide/singleton-services#forroot + * @returns a module with providers + */ public static forRoot(): ModuleWithProviders { return { ngModule: StarkLoggingModule, @@ -17,8 +20,11 @@ export class StarkLoggingModule { }; } - // prevent this module from being re-imported - // see https://angular.io/guide/singleton-services#prevent-reimport-of-the-coremodule + /** + * prevent this module from being re-imported + * @link https://angular.io/guide/singleton-services#prevent-reimport-of-the-coremodule + * @param the parent module + */ public constructor( @Optional() @SkipSelf() diff --git a/packages/stark-core/src/modules/logging/reducers/index.ts b/packages/stark-core/src/modules/logging/reducers/index.ts index 8ab7cf2a5a..f14de54667 100644 --- a/packages/stark-core/src/modules/logging/reducers/index.ts +++ b/packages/stark-core/src/modules/logging/reducers/index.ts @@ -3,14 +3,29 @@ import { StarkLogging } from "../entities"; import { loggingReducer } from "../reducers"; import { StarkLoggingActions } from "../actions"; +/** + * We define part of the state assigned to the logging module + */ export interface StarkLoggingState { + /** + * The logging property + */ logging: StarkLogging; } +/** + * We assign a reducer to our logging property + */ export const starkLoggingReducers: ActionReducerMap = { + /** + * the reducer is assigned to our property + */ logging: loggingReducer }; +/** + * The selector will return the part of the state assigned to the logging when called + */ export const selectStarkLogging: MemoizedSelector = createSelector( createFeatureSelector("StarkLogging"), (state: StarkLoggingState) => state.logging diff --git a/packages/stark-core/src/modules/logging/reducers/logging.reducer.spec.ts b/packages/stark-core/src/modules/logging/reducers/logging.reducer.spec.ts index c24d920bbd..f66888cfd3 100644 --- a/packages/stark-core/src/modules/logging/reducers/logging.reducer.spec.ts +++ b/packages/stark-core/src/modules/logging/reducers/logging.reducer.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { StarkLogging, StarkLogMessageImpl, StarkLogMessageType } from "../entities"; import { loggingReducer } from "./logging.reducer"; import { StarkSetLoggingApplicationId, StarkLogMessageAction, StarkFlushLogMessages } from "../actions"; diff --git a/packages/stark-core/src/modules/logging/reducers/logging.reducer.ts b/packages/stark-core/src/modules/logging/reducers/logging.reducer.ts index c9bb7eeeb8..642ac64490 100644 --- a/packages/stark-core/src/modules/logging/reducers/logging.reducer.ts +++ b/packages/stark-core/src/modules/logging/reducers/logging.reducer.ts @@ -1,14 +1,26 @@ import { StarkLoggingActions, StarkLoggingActionTypes } from "../actions"; import { StarkLogging, StarkLogMessage } from "../entities"; +/** + * The store key will allow the application to find the reducer in the store + */ export const starkLoggingStoreKey: string = "starkLogging"; +/** + * Defines the initial state of the reducer + * @link StarkLogging + */ const INITIAL_STATE: Readonly = { uuid: "", applicationId: "", messages: [] }; +/** + * Definition of the logging reducer. + * @param state - the state of the reducer + * @param action - the action to perform + */ export function loggingReducer( state: Readonly = INITIAL_STATE, action: Readonly diff --git a/packages/stark-core/src/modules/logging/services/logging.service.intf.ts b/packages/stark-core/src/modules/logging/services/logging.service.intf.ts index b857744f7e..842b5cf98e 100644 --- a/packages/stark-core/src/modules/logging/services/logging.service.intf.ts +++ b/packages/stark-core/src/modules/logging/services/logging.service.intf.ts @@ -1,7 +1,13 @@ import { InjectionToken } from "@angular/core"; import { StarkError } from "../../../common"; +/** + * The name of the service in case an injection is needed + */ export const starkLoggingServiceName: string = "StarkLoggingService"; +/** + * The InjectionToken version of the service name + */ export const STARK_LOGGING_SERVICE: InjectionToken = new InjectionToken(starkLoggingServiceName); /** @@ -9,10 +15,41 @@ export const STARK_LOGGING_SERVICE: InjectionToken = new In * Service that integrates logging with the Redux store and also integrates the notion of correlation identifier. */ export interface StarkLoggingService { + /** + * Gets the current correlationId. In fact when the logging service is created, it gets a unique correlation Id. + * This value can be used while displaying a generic error message. + */ readonly correlationId: string; + + /** + * Generates a new correlationId. This method can be used at the start of a new action, for instance when the user clicks a button to save data. + */ generateNewCorrelationId(): string; + + /** + * Logs debug messages to be used only in development to track issues. + * The debug messages are only logged (and afterwards stored in the Redux store) only when the debugLoggingEnabled configuration setting from the StarkApplicationConfig is set to true. + * @param args - the arguments to log + */ debug(...args: any[]): void; + + /** + * Logs information messages. These messages are also stored in the Redux store. + * @param args - the arguments to log + */ info(...args: any[]): void; + + /** + * Logs warning messages. Warning messages can, for instance, indicate a non blocking problem in the software. These messages are also stored in the Redux store. + * @param args - the arguments to log + */ warn(...args: any[]): void; + + /** + * Logs error messages. Error messages should be logged when there was an unexpected error while executing the code. + * They are typically logged in the catch method of a try-catch block. These messages are also stored in the Redux store. + * @param message - the message to log + * @param error - the error to log + */ error(message: string, error?: StarkError | Error): void; } diff --git a/packages/stark-core/src/modules/logging/services/logging.service.spec.ts b/packages/stark-core/src/modules/logging/services/logging.service.spec.ts index b1e1ffa615..b631fd762b 100644 --- a/packages/stark-core/src/modules/logging/services/logging.service.spec.ts +++ b/packages/stark-core/src/modules/logging/services/logging.service.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import Spy = jasmine.Spy; import SpyObj = jasmine.SpyObj; import { Store } from "@ngrx/store"; diff --git a/packages/stark-core/src/modules/logging/services/logging.service.ts b/packages/stark-core/src/modules/logging/services/logging.service.ts index 8cd9c6956e..f12db69041 100644 --- a/packages/stark-core/src/modules/logging/services/logging.service.ts +++ b/packages/stark-core/src/modules/logging/services/logging.service.ts @@ -1,3 +1,4 @@ +/* tslint:disable:completed-docs*/ import uuid from "uuid"; import { Serialize } from "cerialize"; @@ -18,18 +19,16 @@ import { StarkFlushLogMessages, StarkLogMessageAction } from "../actions"; import { selectStarkLogging } from "../reducers"; import { StarkError, StarkErrorImpl } from "../../../common/error"; import { StarkConfigurationUtil } from "../../../util/configuration.util"; - +/** + * @ignore + */ const _noop: Function = require("lodash/noop"); /** + * @ignore * @ngdoc service - * @name stark-core.service:StarkLoggingService * @description Basic logging service implementation. * Integrates logging with the Redux store - * - * @requires ngrx-store.Store - * @requires StarkApplicationConfig - * @requires StarkXSRFService */ @Injectable() export class StarkLoggingServiceImpl implements StarkLoggingService { diff --git a/packages/stark-core/src/modules/logging/testing/logging.mock.ts b/packages/stark-core/src/modules/logging/testing/logging.mock.ts index 7b217e42f5..47724fc001 100644 --- a/packages/stark-core/src/modules/logging/testing/logging.mock.ts +++ b/packages/stark-core/src/modules/logging/testing/logging.mock.ts @@ -1,12 +1,46 @@ import { StarkLoggingService } from "../services"; +/** + * Mock class of the StarkLoggingService interface. + * @link StarkLoggingService + */ export class MockStarkLoggingService implements StarkLoggingService { + /** + * Gets the current correlationId. In fact when the logging service is created, it gets a unique correlation Id. + * This value can be used while displaying a generic error message. + */ public correlationId: string; + /** + * Logs debug messages to be used only in development to track issues. + * The debug messages are only logged (and afterwards stored in the Redux store) only when the debugLoggingEnabled configuration setting from the StarkApplicationConfig is set to true. + * @param args - the arguments to log + */ public debug: () => void = jasmine.createSpy("debug"); + + /** + * Logs information messages. These messages are also stored in the Redux store. + * @param args - the arguments to log + */ public info: () => void = jasmine.createSpy("info"); + + /** + * Logs warning messages. Warning messages can, for instance, indicate a non blocking problem in the software. These messages are also stored in the Redux store. + * @param args - the arguments to log + */ public warn: () => void = jasmine.createSpy("warn"); + + /** + * Logs error messages. Error messages should be logged when there was an unexpected error while executing the code. + * They are typically logged in the catch method of a try-catch block. These messages are also stored in the Redux store. + * @param message - the message to log + * @param error - the arguments to log + */ public error: () => void = jasmine.createSpy("error"); + + /** + * Method to generate a new correlationId. + */ public generateNewCorrelationId: () => string = jasmine.createSpy("generateNewCorrelationId"); public constructor(correlationId: string = "dummyCorrelationId") { diff --git a/packages/stark-core/src/modules/routing/actions/routing.actions.ts b/packages/stark-core/src/modules/routing/actions/routing.actions.ts index 6edcba73bb..be759329b5 100644 --- a/packages/stark-core/src/modules/routing/actions/routing.actions.ts +++ b/packages/stark-core/src/modules/routing/actions/routing.actions.ts @@ -1,6 +1,9 @@ import { Action } from "@ngrx/store"; import { RawParams, TransitionOptions } from "@uirouter/core"; +/** + * Enumeration of Routing NGRX Actions + */ export enum StarkRoutingActionTypes { NAVIGATE = "[StarkRouting] Navigate", NAVIGATE_SUCCESS = "[StarkRouting] Navigate Success", @@ -12,9 +15,23 @@ export enum StarkRoutingActionTypes { RELOAD_FAILURE = "[StarkRouting] Reload Failure" } +/** + * Triggered when the navigateTo() method is called, just before starting the navigation. + */ export class StarkNavigate implements Action { + /** + * The action type + * @link StarkRoutingActionTypes + */ public readonly type: StarkRoutingActionTypes.NAVIGATE = StarkRoutingActionTypes.NAVIGATE; + /** + * Class constructor + * @param currentState - name of the current state before the navigation starts. + * @param newState - name of the state to be navigated to. + * @param params - state params object to be passed to the navigated state. + * @param options - Transition options object to change the behavior of the transition. + */ public constructor( public currentState: string, public newState: string, @@ -23,44 +40,134 @@ export class StarkNavigate implements Action { ) {} } +/** + * Triggered when a navigation has succeeded and finished. + * This action is dispatched for any navigation, including those navigations triggered not by the navigateTo() method but by any other + * mean such as navigateToPrevious(), navigateToHome(), reload(), routing directives for menu links or by direct usage of the router library API. + */ export class StarkNavigateSuccess implements Action { + /** + * The action type + * @link StarkRoutingActionTypes + */ public readonly type: StarkRoutingActionTypes.NAVIGATE_SUCCESS = StarkRoutingActionTypes.NAVIGATE_SUCCESS; + /** + * Class constructor + * @param previousState - name of the initial state where the navigation was started. + * @param currentState - name of the state that was navigated to. + * @param params - state params object that was passed to the navigated state. + */ public constructor(public previousState: string, public currentState: string, public params?: RawParams) {} } +/** + * Triggered when a navigation failed. + * This action is dispatched for any navigation, including those navigations triggered not by + * the navigateTo() method but by any other mean such as menu links or by direct usage of the router library API. + */ export class StarkNavigateFailure implements Action { + /** + * The action type + * @link StarkRoutingActionTypes + */ public readonly type: StarkRoutingActionTypes.NAVIGATE_FAILURE = StarkRoutingActionTypes.NAVIGATE_FAILURE; + /** + * Class constructor + * @param currentState - name of the current state before the navigation started. + * @param newState - name of the state tried to be navigated to. + * @param params - state params object passed to the navigated state. + * @param error - the error describing the reason of the navigation failure. + */ public constructor(public currentState: string, public newState: string, public params: RawParams, public error: string) {} } +/** + * Triggered when a navigation was intentionally rejected with a known rejection reason added via the addKnownNavigationRejectionCause() method. + * The custom logic to intentionally reject a transition can be normally be injected via a transition Hook by calling the addTransitionHook() method. + */ export class StarkNavigateRejection implements Action { + /** + * The action type + * @link StarkRoutingActionTypes + */ public readonly type: StarkRoutingActionTypes.NAVIGATE_REJECTION = StarkRoutingActionTypes.NAVIGATE_REJECTION; + /** + * Class constructor + * @param currentState - name of the current state before the navigation started. + * @param newState - name of the state tried to be navigated to. + * @param params - state params object passed to the navigated state. + * @param reason - the reason describing why the navigation was rejected. This is normally a reason already known by the developer. + */ public constructor(public currentState: string, public newState: string, public params: RawParams, public reason: string) {} } +/** + * Triggered when the navigateToPrevious() method is called and there are no more previous states in the history to navigate to. + * This action is just triggered in case the reload was done by calling the reload() method. + */ export class StarkNavigationHistoryLimitReached implements Action { + /** + * Defines the type of NGRX action to perform. + * @link StarkRoutingActionTypes + */ public readonly type: StarkRoutingActionTypes.NAVIGATION_HISTORY_LIMIT_REACHED = StarkRoutingActionTypes.NAVIGATION_HISTORY_LIMIT_REACHED; } +/** + * Triggered when the reload() method is called, just before starting the state reloading. + */ export class StarkReload implements Action { + /** + * The action type + * @link StarkRoutingActionTypes + */ public readonly type: StarkRoutingActionTypes.RELOAD = StarkRoutingActionTypes.RELOAD; + /** + * Class constructor + * @param state - name of the state to be reloaded. + */ public constructor(public state: string) {} } - +/** + * Triggered when a reload succeeded and finished. + * This action is dispatched for any navigation, including those navigations triggered not by the navigateTo() + * method but by any other mean such as menu links or by direct usage of the router library API. + */ export class StarkReloadSuccess implements Action { + /** + * The action type + * @link StarkRoutingActionTypes + */ public readonly type: StarkRoutingActionTypes.RELOAD_SUCCESS = StarkRoutingActionTypes.RELOAD_SUCCESS; + /** + * Class constructor + * @param state - name of the state that was reloaded. + * @param params - state params object passed to the reloaded state. + */ public constructor(public state: string, public params: RawParams) {} } - +/** + * Triggered when a reload failed. + * This action is just triggered in case the reload was done by calling the reload() method. + */ export class StarkReloadFailure implements Action { + /** + * The action type + * @link StarkRoutingActionTypes + */ public readonly type: StarkRoutingActionTypes.RELOAD_FAILURE = StarkRoutingActionTypes.RELOAD_FAILURE; + /** + * Class constructor + * @param state - name of the state tried to be reloaded. + * @param params - state params object passed to the reloaded state. + */ public constructor(public state: string, public params: RawParams) {} } diff --git a/packages/stark-core/src/modules/routing/routing.module.ts b/packages/stark-core/src/modules/routing/routing.module.ts index 4477636c93..2c3821eac1 100644 --- a/packages/stark-core/src/modules/routing/routing.module.ts +++ b/packages/stark-core/src/modules/routing/routing.module.ts @@ -6,9 +6,12 @@ import { StarkRoutingServiceImpl, STARK_ROUTING_SERVICE } from "./services"; imports: [UIRouterModule.forChild()] }) export class StarkRoutingModule { - // instantiate the services only once since they should be singletons - // so the forRoot() should be called only by the AppModule - // see https://angular.io/guide/singleton-services#forroot + /** + * Instantiates the services only once since they should be singletons + * so the forRoot() should be called only by the AppModule + * @link https://angular.io/guide/singleton-services#forroot + * @returns a module with providers + */ public static forRoot(): ModuleWithProviders { return { ngModule: StarkRoutingModule, @@ -16,8 +19,11 @@ export class StarkRoutingModule { }; } - // prevent this module from being re-imported - // see https://angular.io/guide/singleton-services#prevent-reimport-of-the-coremodule + /** + * prevent this module from being re-imported + * @link https://angular.io/guide/singleton-services#prevent-reimport-of-the-coremodule + * @param the parent module + */ public constructor( @Optional() @SkipSelf() diff --git a/packages/stark-core/src/modules/routing/services/routing-transition-hook.constants.ts b/packages/stark-core/src/modules/routing/services/routing-transition-hook.constants.ts index ff70f26f22..84f0dc98c5 100644 --- a/packages/stark-core/src/modules/routing/services/routing-transition-hook.constants.ts +++ b/packages/stark-core/src/modules/routing/services/routing-transition-hook.constants.ts @@ -1,14 +1,45 @@ /** - * Transition lifecycle hooks available in the router implementation - * @link https://ui-router.github.io/ng1/docs/latest/interfaces/transition.ihookregistry.html + * This class provides all the transition lifecycle hooks available in the router implementation. See UI-router Transition IHookRegistry */ export class StarkRoutingTransitionHook { + /** + * Transition lifecycle hook invoked before a transition even begins. + * @link https://ui-router.github.io/ng1/docs/latest/interfaces/transition.ihookregistry.html#onbefore + */ public static ON_BEFORE: string = "ON_BEFORE"; + /** + * Transition lifecycle hook invoked as a transition starts running. + * @link https://ui-router.github.io/ng1/docs/latest/interfaces/transition.ihookregistry.html#onstart + */ public static ON_START: string = "ON_START"; + /** + * Transition lifecycle hook invoked (during a transition) for a specific state that was previously active will remain active (is not being entered nor exited). + * @link https://ui-router.github.io/ng1/docs/latest/interfaces/transition.ihookregistry.html#onretain + */ public static ON_RETAIN: string = "ON_RETAIN"; + /** + * Transition lifecycle hook invoked (during a transition) when a specific state is being entered. + * @link https://ui-router.github.io/ng1/docs/latest/interfaces/transition.ihookregistry.html#onenter + */ public static ON_ENTER: string = "ON_ENTER"; + /** + * Transition lifecycle hook invoked just before a transition finishes. This hook is a last chance to cancel or redirect a transition. + * @link https://ui-router.github.io/ng1/docs/latest/interfaces/transition.ihookregistry.html#onfinish + */ public static ON_FINISH: string = "ON_FINISH"; + /** + * Transition lifecycle hook invoked (during a transition) when a specific state is being exited. + * @link https://ui-router.github.io/ng1/docs/latest/interfaces/transition.ihookregistry.html#onexit + */ public static ON_EXIT: string = "ON_EXIT"; + /** + * Transition lifecycle hook invoked after a transition successfully completes. + * @link https://ui-router.github.io/ng1/docs/latest/interfaces/transition.ihookregistry.html#onsuccess + */ public static ON_SUCCESS: string = "ON_SUCCESS"; + /** + * Transition lifecycle hook invoked after a transition has been rejected for any reason. + * @link https://ui-router.github.io/ng1/docs/latest/interfaces/transition.ihookregistry.html#onerror + */ public static ON_ERROR: string = "ON_ERROR"; } diff --git a/packages/stark-core/src/modules/routing/services/routing.service.intf.ts b/packages/stark-core/src/modules/routing/services/routing.service.intf.ts index 415c314472..6a6e9d1c2f 100644 --- a/packages/stark-core/src/modules/routing/services/routing.service.intf.ts +++ b/packages/stark-core/src/modules/routing/services/routing.service.intf.ts @@ -4,7 +4,13 @@ import { HookFn, HookMatchCriteria, HookRegOptions, RawParams, StateDeclaration, import { StarkStateConfigWithParams } from "./state-config-with-params.intf"; import { InjectionToken } from "@angular/core"; +/** + * The name of the Stark Routing Service, in case injection is needed + */ export const starkRoutingServiceName: string = "StarkRoutingService"; +/** + * The injection Token version of the service name + */ export const STARK_ROUTING_SERVICE: InjectionToken = new InjectionToken(starkRoutingServiceName); /** diff --git a/packages/stark-core/src/modules/routing/services/routing.service.spec.ts b/packages/stark-core/src/modules/routing/services/routing.service.spec.ts index bfc05b92fe..96db795594 100644 --- a/packages/stark-core/src/modules/routing/services/routing.service.spec.ts +++ b/packages/stark-core/src/modules/routing/services/routing.service.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { Component, NgModuleFactoryLoader, NO_ERRORS_SCHEMA, SystemJsNgModuleLoader } from "@angular/core"; import { fakeAsync, inject, TestBed, tick } from "@angular/core/testing"; import { Ng2StateDeclaration, UIRouterModule } from "@uirouter/angular"; diff --git a/packages/stark-core/src/modules/routing/services/routing.service.ts b/packages/stark-core/src/modules/routing/services/routing.service.ts index 283f8d42df..3c1f7c3aec 100644 --- a/packages/stark-core/src/modules/routing/services/routing.service.ts +++ b/packages/stark-core/src/modules/routing/services/routing.service.ts @@ -1,3 +1,4 @@ +/* tslint:disable:completed-docs */ import { Action, Store } from "@ngrx/store"; import { EMPTY, from, Observable } from "rxjs"; import { Inject, Injectable } from "@angular/core"; @@ -42,23 +43,23 @@ import { StarkStateConfigWithParams } from "./state-config-with-params.intf"; import { StarkCoreApplicationState } from "../../../common/store"; import { StarkConfigurationUtil } from "../../../util/configuration.util"; +/** + * @ignore + */ const _isEmpty: Function = require("lodash/isEmpty"); +/** + * @ignore + */ interface StarkState { name: string; params: RawParams | undefined; } /** + * @ignore * @ngdoc service - * @name stark-core.service:StarkRoutingService * @description Service that can be used to interact with the router implementation. - * - * @requires StarkLoggingService - * @requires ngrx-store.Store - * @requires StarkApplicationConfig - * @requires $state - * @requires $transitions */ @Injectable() export class StarkRoutingServiceImpl implements StarkRoutingService { @@ -264,7 +265,7 @@ export class StarkRoutingServiceImpl implements StarkRoutingService { default: throw new Error(starkRoutingServiceName + ": lifecycle hook unknown => " + lifecycleHook); } - /* tslint:enable */ + /* tslint:enable:no-useless-cast */ } /** @@ -272,7 +273,7 @@ export class StarkRoutingServiceImpl implements StarkRoutingService { * It logs an error and dispatches a NAVIGATE_FAILURE action to the NGRX Store */ // FIXME: re-enable this TSLINT rule and refactor this function to reduce its cognitive complexity - // tslint:disable-next-line:cognitive-complexity + // tslint:disable-next-line cognitive-complexity private addNavigationErrorHandlers(): void { this.logger.debug(starkRoutingServiceName + ": adding navigation error handlers"); @@ -531,6 +532,7 @@ export class StarkRoutingServiceImpl implements StarkRoutingService { } } + // tslint:disable-next-line completed-docs private extractResolvablesData(resolvables: Resolvable[]): { [key: string]: any } { const resolvablesData: { [key: string]: any } = {}; @@ -567,3 +569,4 @@ export class StarkRoutingServiceImpl implements StarkRoutingService { return stateTranslationKey; } } +// tslint:enable completed-docs diff --git a/packages/stark-core/src/modules/routing/services/state-config-with-params.intf.ts b/packages/stark-core/src/modules/routing/services/state-config-with-params.intf.ts index 317ee6accd..99b340f49f 100644 --- a/packages/stark-core/src/modules/routing/services/state-config-with-params.intf.ts +++ b/packages/stark-core/src/modules/routing/services/state-config-with-params.intf.ts @@ -1,6 +1,15 @@ import { StateDeclaration, RawParams } from "@uirouter/core"; +/** + * This interface is used by StarkRoutingService in order to return the matching state based on a given URL. + */ export interface StarkStateConfigWithParams { + /** + * Object containing the UI-Router definition of the route state. + */ state: StateDeclaration; + /** + * An object containing the parameters key/value pairs passed at runtime to the current route state. + */ paramValues: RawParams; } diff --git a/packages/stark-core/src/modules/routing/testing/routing.mock.ts b/packages/stark-core/src/modules/routing/testing/routing.mock.ts index 9b7d033343..66ac2c9b91 100644 --- a/packages/stark-core/src/modules/routing/testing/routing.mock.ts +++ b/packages/stark-core/src/modules/routing/testing/routing.mock.ts @@ -1,7 +1,9 @@ import { StarkRoutingService, StarkStateConfigWithParams } from "../services"; import { Observable } from "rxjs"; import { HookFn, HookMatchCriteria, HookRegOptions, RawParams, StateDeclaration, StateObject, TransitionOptions } from "@uirouter/core"; - +/** + * @ignore + */ export class MockStarkRoutingService implements StarkRoutingService { public navigateTo: (newState: string, params?: RawParams, options?: TransitionOptions) => Observable = jasmine.createSpy( "navigateTo" diff --git a/packages/stark-core/src/modules/session/actions/session.actions.ts b/packages/stark-core/src/modules/session/actions/session.actions.ts index b963f13aae..74ae5a1f63 100644 --- a/packages/stark-core/src/modules/session/actions/session.actions.ts +++ b/packages/stark-core/src/modules/session/actions/session.actions.ts @@ -1,6 +1,9 @@ import { Action } from "@ngrx/store"; import { StarkUser } from "../../user/entities"; +/** + * Actions related to stark session service + */ export enum StarkSessionActionTypes { CHANGE_LANGUAGE = "[StarkSession] Change Language", CHANGE_LANGUAGE_SUCCESS = "[StarkSession] Change Language Success", @@ -17,66 +20,186 @@ export enum StarkSessionActionTypes { USER_ACTIVITY_TRACKING_RESUME = "[StarkSession] User Activity Tracking Resume" } +/** + * Triggered when the setCurrentLanguage() method is called, just before changing the current session's language. + */ export class StarkChangeLanguage implements Action { + /** + * The type of action + * @link StarkSessionActionTypes + */ public readonly type: StarkSessionActionTypes.CHANGE_LANGUAGE = StarkSessionActionTypes.CHANGE_LANGUAGE; - + /** + * Class constructor + * @param languageId - The target language to change to. + */ public constructor(public languageId: string) {} } +/** + * Triggered when the current session's language has been successfully changed by calling the setCurrentLanguage() method. + */ export class StarkChangeLanguageSuccess implements Action { + /** + * The type of action + * @link StarkSessionActionTypes + */ public readonly type: StarkSessionActionTypes.CHANGE_LANGUAGE_SUCCESS = StarkSessionActionTypes.CHANGE_LANGUAGE_SUCCESS; + /** + * Class constructor + * @param languageId - The target language that was successfully changed to. + */ public constructor(public languageId: string) {} } +/** + * Triggered when the change of the current session's language failed. + */ export class StarkChangeLanguageFailure implements Action { + /** + * The type of action + * @link StarkSessionActionTypes + */ public readonly type: StarkSessionActionTypes.CHANGE_LANGUAGE_FAILURE = StarkSessionActionTypes.CHANGE_LANGUAGE_FAILURE; + /** + * Class constructor + * @param error - The error that caused the language change to fail. + */ public constructor(public error: any) {} } +/** + * Triggered by the login() method before the process to initialize the session for the given user starts. + */ export class StarkInitializeSession implements Action { + /** + * The type of action + * @link StarkSessionActionTypes + */ public readonly type: StarkSessionActionTypes.INITIALIZE_SESSION = StarkSessionActionTypes.INITIALIZE_SESSION; + /** + * Class constructor + * @param user - The user whose session will be initialized. + */ public constructor(public user: StarkUser) {} } +/** + * Triggered when the initialization of the user's session has finished succesfully. + */ export class StarkInitializeSessionSuccess implements Action { + /** + * The type of action + * @link StarkSessionActionTypes + */ public readonly type: StarkSessionActionTypes.INITIALIZE_SESSION_SUCCESS = StarkSessionActionTypes.INITIALIZE_SESSION_SUCCESS; } +/** + * Triggered before the process to destroy the user's session starts right after the HTTP logout call has been sent. + * This action is dispatched whenever the user is going to be logged out due to: + * 1) Manually clicking in the App Logout component + * 2) Calling the logout() method. + * 3) Closing the browser tab. + * 4) Being inactive for a certain period of time reaching the idle timeout defined by the application. + */ export class StarkDestroySession implements Action { + /** + * The type of action + * @link StarkSessionActionTypes + */ public readonly type: StarkSessionActionTypes.DESTROY_SESSION = StarkSessionActionTypes.DESTROY_SESSION; } +/** + * Triggered when the destruction of the user's session has finished successfully. + * This action is the last action to be dispatched when the user is logged out (either manually by himself or automatically due to inactivity). + */ export class StarkDestroySessionSuccess implements Action { + /** + * The type of action + * @link StarkSessionActionTypes + */ public readonly type: StarkSessionActionTypes.DESTROY_SESSION_SUCCESS = StarkSessionActionTypes.DESTROY_SESSION_SUCCESS; } +/** + * Triggered when the countdown to automatically destroy the user's session due to inactivity starts. + * The countdown is defined in the sessionTimeoutWarningPeriod option in the application configuration. By default is set to 15 seconds. + */ export class StarkSessionTimeoutCountdownStart implements Action { + /** + * The type of action + * @link StarkSessionActionTypes + */ public readonly type: StarkSessionActionTypes.SESSION_TIMEOUT_COUNTDOWN_START = StarkSessionActionTypes.SESSION_TIMEOUT_COUNTDOWN_START; + /** + * Class constructor + * @param countdown - The countdown until the session will be automatically destroyed. + */ public constructor(public countdown: number) {} } +/** + * Triggered when the countdown to automatically destroy the user's session due to inactivity stops. + * This countdown stops automatically when the user is active again and no longer idle. + */ export class StarkSessionTimeoutCountdownStop implements Action { + /** + * The type of action + * @link StarkSessionActionTypes + */ public readonly type: StarkSessionActionTypes.SESSION_TIMEOUT_COUNTDOWN_STOP = StarkSessionActionTypes.SESSION_TIMEOUT_COUNTDOWN_STOP; } +/** + * Triggered when the countdown to automatically destroy the user's session has finished. In this case the user will be automatically logged out. + */ export class StarkSessionTimeoutCountdownFinish implements Action { + /** + * Defines the type of NGRX action to perform. + * @link StarkSessionActionTypes + */ public readonly type: StarkSessionActionTypes.SESSION_TIMEOUT_COUNTDOWN_FINISH = StarkSessionActionTypes.SESSION_TIMEOUT_COUNTDOWN_FINISH; } +/** + * Triggered when the user is about to be logged out and the HTTP logout call to be sent. This action is called before the process to destroy the user's session starts. + * This action is dispatched by the logout() method or in case the browser tab was closed. + * This action is dispatched before the StarkSessionActions.DESTROY_SESSION action. + */ export class StarkSessionLogout implements Action { + /** + * The type of action + * @link StarkSessionActionTypes + */ public readonly type: StarkSessionActionTypes.SESSION_LOGOUT = StarkSessionActionTypes.SESSION_LOGOUT; } +/** + * Triggered by the pauseUserActivityTracking() method when the user activity tracking (automatically done by the Session service) is paused. + */ export class StarkUserActivityTrackingPause implements Action { + /** + * The type of action + * @link StarkSessionActionTypes + */ public readonly type: StarkSessionActionTypes.USER_ACTIVITY_TRACKING_PAUSE = StarkSessionActionTypes.USER_ACTIVITY_TRACKING_PAUSE; } +/** + * Triggered by the resumeUserActivityTracking() method when the user activity tracking (automatically done by the Session service) is resumed. + */ export class StarkUserActivityTrackingResume implements Action { + /** + * The type of action + * @link StarkSessionActionTypes + */ public readonly type: StarkSessionActionTypes.USER_ACTIVITY_TRACKING_RESUME = StarkSessionActionTypes.USER_ACTIVITY_TRACKING_RESUME; } diff --git a/packages/stark-core/src/modules/session/entities/pre-authentication.intf.ts b/packages/stark-core/src/modules/session/entities/pre-authentication.intf.ts index c4f7032d9f..34a6f51300 100644 --- a/packages/stark-core/src/modules/session/entities/pre-authentication.intf.ts +++ b/packages/stark-core/src/modules/session/entities/pre-authentication.intf.ts @@ -1,9 +1,32 @@ +/** + * NBB's Java back-ends are usually configured to expect pre-authentication; that is the fact that when a request comes in, if should have been authenticated before by "something else". + * The way it works is that each request must include NBB-specific HTTP headers along with each request. + * When you are working against a development environment (e.g., back-end running on your own machine), the infrastructure is not there, so we must simulate it. + */ export interface StarkPreAuthentication { + /** + * The separator to use for the roles (must match the role separator defined on the back-end) + */ roleSeparator: string; + /** + * The separator to use for the description (must match the role separator defined on the back-end) + */ descriptionSeparator: string; + /** + * The default headers + */ defaults: { + /** + * The user's language + */ language: string; + /** + * The user's workpost + */ workpost: string; + /** + * The user's reference number + */ referenceNumber: string; }; } diff --git a/packages/stark-core/src/modules/session/entities/session.entity.intf.ts b/packages/stark-core/src/modules/session/entities/session.entity.intf.ts index c87bf5fd2a..828e8ffa20 100644 --- a/packages/stark-core/src/modules/session/entities/session.entity.intf.ts +++ b/packages/stark-core/src/modules/session/entities/session.entity.intf.ts @@ -1,5 +1,8 @@ import { StarkUser } from "../../user/entities"; +/** + * The StarkSession interface describes the information that is stored and available during the whole session of a user. + */ export interface StarkSession { /** * The current session's language @@ -8,6 +11,7 @@ export interface StarkSession { /** * The current user logged in the application (if there is one logged in), otherwise it will be undefined + * @link StarkUser */ user: StarkUser | undefined; } diff --git a/packages/stark-core/src/modules/session/entities/session.entity.ts b/packages/stark-core/src/modules/session/entities/session.entity.ts index a618ae1e4d..3fb34037ab 100644 --- a/packages/stark-core/src/modules/session/entities/session.entity.ts +++ b/packages/stark-core/src/modules/session/entities/session.entity.ts @@ -1,6 +1,8 @@ import { StarkUser } from "../../user/entities"; import { StarkSession } from "./session.entity.intf"; - +/** + * @ignore + */ export class StarkSessionImpl implements StarkSession { public currentLanguage: string; diff --git a/packages/stark-core/src/modules/session/reducers/index.ts b/packages/stark-core/src/modules/session/reducers/index.ts index 63c55f34f7..7e3663c5be 100644 --- a/packages/stark-core/src/modules/session/reducers/index.ts +++ b/packages/stark-core/src/modules/session/reducers/index.ts @@ -3,18 +3,37 @@ import { StarkSession } from "../entities"; import { StarkSessionActions } from "../actions"; import { sessionReducer } from "../reducers"; +/** + * We define part of the state assigned to the session module + */ export interface StarkSessionState { + /** + * The session property + * @link StarkSession + */ session: StarkSession; } +/** + * We assign a reducer to our session property + */ export const starkSessionReducers: ActionReducerMap = { + /** + * the reducer is assigned to our property + */ session: sessionReducer }; +/** + * This will create the session feature used by the selector to find the session module in the state + */ export const selectStarkSessionFeature: MemoizedSelector = createFeatureSelector( "StarkSession" ); +/** + * The selector will return the part of the state assigned to the logging when called + */ export const selectStarkSession: MemoizedSelector = createSelector( selectStarkSessionFeature, (state: StarkSessionState) => state.session diff --git a/packages/stark-core/src/modules/session/reducers/session.reducer.spec.ts b/packages/stark-core/src/modules/session/reducers/session.reducer.spec.ts index 13d78a6197..3e140618b0 100644 --- a/packages/stark-core/src/modules/session/reducers/session.reducer.spec.ts +++ b/packages/stark-core/src/modules/session/reducers/session.reducer.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { StarkSession } from "../entities"; import { StarkUser } from "../../user/entities"; import { sessionReducer } from "./session.reducer"; diff --git a/packages/stark-core/src/modules/session/reducers/session.reducer.ts b/packages/stark-core/src/modules/session/reducers/session.reducer.ts index 78bd0c3982..48be8134dc 100644 --- a/packages/stark-core/src/modules/session/reducers/session.reducer.ts +++ b/packages/stark-core/src/modules/session/reducers/session.reducer.ts @@ -1,10 +1,22 @@ import { StarkSessionActionTypes, StarkSessionActions } from "../actions"; import { StarkSession, StarkSessionImpl } from "../entities"; +/** + * Key defined to find the service in a store + */ export const starkSessionStoreKey: string = "starkSession"; +/** + * Defines the initial state of the reducer + */ const INITIAL_STATE: StarkSession = new StarkSessionImpl(); +/** + * Definition of the session reducer + * @param state: the state of the reducer + * @param action: the action to apply to the reducer + * @returns a starkSession instance + */ export function sessionReducer( state: Readonly = INITIAL_STATE, action: Readonly diff --git a/packages/stark-core/src/modules/session/services/session.service.intf.ts b/packages/stark-core/src/modules/session/services/session.service.intf.ts index 20e63895d2..5492e63df3 100644 --- a/packages/stark-core/src/modules/session/services/session.service.intf.ts +++ b/packages/stark-core/src/modules/session/services/session.service.intf.ts @@ -2,7 +2,13 @@ import { InjectionToken } from "@angular/core"; import { Observable } from "rxjs"; import { StarkUser } from "../../user/entities"; +/** + * Name of the Session Service, in case injection is required + */ export const starkSessionServiceName: string = "StarkSessionService"; +/** + * Injection Token version of the Service Name + */ export const STARK_SESSION_SERVICE: InjectionToken = new InjectionToken(starkSessionServiceName); /** @@ -19,6 +25,7 @@ export interface StarkSessionService { /** * Returns the session's current user * + * @link StarkUser * @returns Observable that will emit the current user and the latest value whenever it changes */ getCurrentUser(): Observable; @@ -40,6 +47,8 @@ export interface StarkSessionService { /** * Performs the login of the user. Internally, it performs all the necessary actions to initialize the session. + * + * @link StarkUser * @param user - The user to log in. */ login(user: StarkUser): void; diff --git a/packages/stark-core/src/modules/session/services/session.service.spec.ts b/packages/stark-core/src/modules/session/services/session.service.spec.ts index 61a8bdf3aa..bff4c471f5 100644 --- a/packages/stark-core/src/modules/session/services/session.service.spec.ts +++ b/packages/stark-core/src/modules/session/services/session.service.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { HttpHeaders, HttpRequest } from "@angular/common/http"; import { EventEmitter, Injector } from "@angular/core"; import { DEFAULT_INTERRUPTSOURCES, Idle, InterruptSource } from "@ng-idle/core"; diff --git a/packages/stark-core/src/modules/session/services/session.service.ts b/packages/stark-core/src/modules/session/services/session.service.ts index c4b5e2b49d..a9a1928422 100644 --- a/packages/stark-core/src/modules/session/services/session.service.ts +++ b/packages/stark-core/src/modules/session/services/session.service.ts @@ -1,3 +1,4 @@ +/* tslint:disable:completed-docs*/ import { HttpHeaders, HttpRequest } from "@angular/common/http"; import { Inject, Injectable, Injector } from "@angular/core"; import { DEFAULT_INTERRUPTSOURCES, Idle } from "@ng-idle/core"; @@ -38,20 +39,15 @@ import { selectStarkSession } from "../reducers"; import { StarkConfigurationUtil } from "../../../util/configuration.util"; import { StarkValidationErrorsUtil } from "../../../util"; +/** + * @ignore + */ export const starkUnauthenticatedUserError: string = "StarkSessionService => user not authenticated"; /** + * @ignore * @ngdoc service - * @name stark-core.service:StarkSessionService * @description Service to get/set session settings (language, ...). - * - * @requires ngrx-store.Store - * @requires StarkLoggingService - * @requires StarkRoutingService - * @requires StarkApplicationConfig - * @requires ng-idle-core.Idle - * @requires $injector - * @requires TranslateService */ @Injectable() export class StarkSessionServiceImpl implements StarkSessionService { diff --git a/packages/stark-core/src/modules/session/session.module.ts b/packages/stark-core/src/modules/session/session.module.ts index 8d8ea3084c..93303d8f38 100644 --- a/packages/stark-core/src/modules/session/session.module.ts +++ b/packages/stark-core/src/modules/session/session.module.ts @@ -7,9 +7,12 @@ import { STARK_SESSION_SERVICE, StarkSessionServiceImpl } from "./services"; imports: [StoreModule.forFeature("StarkSession", starkSessionReducers)] }) export class StarkSessionModule { - // instantiate the services only once since they should be singletons - // so the forRoot() should be called only by the AppModule - // see https://angular.io/guide/singleton-services#forroot + /** + * Instantiates the services only once since they should be singletons + * so the forRoot() should be called only by the AppModule + * @link https://angular.io/guide/singleton-services#forroot + * @returns a module with providers + */ public static forRoot(): ModuleWithProviders { return { ngModule: StarkSessionModule, @@ -17,8 +20,11 @@ export class StarkSessionModule { }; } - // prevent this module from being re-imported - // see https://angular.io/guide/singleton-services#prevent-reimport-of-the-coremodule + /** + * prevent this module from being re-imported + * @link https://angular.io/guide/singleton-services#prevent-reimport-of-the-coremodule + * @param the parent module + */ public constructor( @Optional() @SkipSelf() diff --git a/packages/stark-core/src/modules/session/testing/session.mock.ts b/packages/stark-core/src/modules/session/testing/session.mock.ts index 5a74ed6279..1a26d27705 100644 --- a/packages/stark-core/src/modules/session/testing/session.mock.ts +++ b/packages/stark-core/src/modules/session/testing/session.mock.ts @@ -1,7 +1,9 @@ import { StarkHttpHeaders } from "../../http/constants"; import { StarkSessionService } from "../services"; import { Observable } from "rxjs"; - +/** + * @ignore + */ export class MockStarkSessionService implements StarkSessionService { public fakePreAuthenticationHeaders: Map; diff --git a/packages/stark-core/src/modules/settings/actions/settings.actions.ts b/packages/stark-core/src/modules/settings/actions/settings.actions.ts index 277812d1d5..73bd294a27 100644 --- a/packages/stark-core/src/modules/settings/actions/settings.actions.ts +++ b/packages/stark-core/src/modules/settings/actions/settings.actions.ts @@ -1,5 +1,8 @@ import { Action } from "@ngrx/store"; +/** + * All the Settings action types + */ export enum StarkSettingsActionTypes { PERSIST_PREFERRED_LANGUAGE = "[StarkSettings] Persist Preferred Language", PERSIST_PREFERRED_LANGUAGE_SUCCESS = "[StarkSettings] Persist Preferred Language Success", @@ -9,12 +12,19 @@ export enum StarkSettingsActionTypes { /** * Action that requires to persist the given language locally so that the language remains the same when the user comes back - * @param language the language to persist * @returns The created action object */ export class StarkPersistPreferredLanguage implements Action { + /** + * The type of action + * @link StarkSettingsActionTypes + */ public readonly type: StarkSettingsActionTypes.PERSIST_PREFERRED_LANGUAGE = StarkSettingsActionTypes.PERSIST_PREFERRED_LANGUAGE; + /** + * Class constructor + * @param language - the language to persist + */ public constructor(public language: string) {} } @@ -23,30 +33,45 @@ export class StarkPersistPreferredLanguage implements Action { * @returns The created action object */ export class StarkPersistPreferredLanguageSuccess implements Action { + /** + * The type of action + */ public readonly type: StarkSettingsActionTypes.PERSIST_PREFERRED_LANGUAGE_SUCCESS = StarkSettingsActionTypes.PERSIST_PREFERRED_LANGUAGE_SUCCESS; } /** * Action that notifies the application that the preferred language could not be persisted. - * @param error the reason why the preferred language could not be persisted * @returns The created action object */ export class StarkPersistPreferredLanguageFailureimplements implements Action { + /** + * The type of action + */ public readonly type: StarkSettingsActionTypes.PERSIST_PREFERRED_LANGUAGE_FAILURE = StarkSettingsActionTypes.PERSIST_PREFERRED_LANGUAGE_FAILURE; + /** + * Class constructor + * @param error - the reason why the preferred language could not be persisted + */ public constructor(public error: any) {} } /** * Action that notifies the application that the preferred language should be changed. - * @param language the new preferred language * @returns The created action object */ export class StarkSetPreferredLanguage implements Action { + /** + * The type of action + */ public readonly type: StarkSettingsActionTypes.SET_PREFERRED_LANGUAGE = StarkSettingsActionTypes.SET_PREFERRED_LANGUAGE; + /** + * Class constructor + * @param language - the new preferred language + */ public constructor(public language: string) {} } diff --git a/packages/stark-core/src/modules/settings/effects/settings.effects.spec.ts b/packages/stark-core/src/modules/settings/effects/settings.effects.spec.ts index 3b0db819a0..bd32eb0dc3 100644 --- a/packages/stark-core/src/modules/settings/effects/settings.effects.spec.ts +++ b/packages/stark-core/src/modules/settings/effects/settings.effects.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import Spy = jasmine.Spy; import createSpyObj = jasmine.createSpyObj; import { StarkSettingsEffects } from "./settings.effects"; diff --git a/packages/stark-core/src/modules/settings/effects/settings.effects.ts b/packages/stark-core/src/modules/settings/effects/settings.effects.ts index 38cc012a6b..ab20f7dacc 100644 --- a/packages/stark-core/src/modules/settings/effects/settings.effects.ts +++ b/packages/stark-core/src/modules/settings/effects/settings.effects.ts @@ -6,14 +6,29 @@ import { map } from "rxjs/operators"; import { StarkSetPreferredLanguage, StarkSettingsActionTypes } from "../actions"; import { STARK_SESSION_SERVICE, StarkSessionService } from "../../session/services"; +/** + * This class is used to modified the settings of a session + */ @Injectable() export class StarkSettingsEffects { + /** + * The session service + * @link StarkSessionService + */ public sessionService: StarkSessionService; + /** + * Class constructor + * @param actions$ - the action to perform + * @param sessionService - the session Service + */ public constructor(private actions$: Actions, @Inject(STARK_SESSION_SERVICE) sessionService: StarkSessionService) { this.sessionService = sessionService; } + /** + * The Set preffered language action will be used to change the language of the current session + */ @Effect() public setPreferredLanguage$(): Observable { return this.actions$.pipe( diff --git a/packages/stark-core/src/modules/settings/entities/settings.entity.ts b/packages/stark-core/src/modules/settings/entities/settings.entity.ts index 7ed10cffab..8aeb3facc0 100644 --- a/packages/stark-core/src/modules/settings/entities/settings.entity.ts +++ b/packages/stark-core/src/modules/settings/entities/settings.entity.ts @@ -1,3 +1,9 @@ +/** + * Used to store the preferences of the user + */ export class StarkSettings { + /** + * the user's preferred language + */ public preferredLanguage: string; } diff --git a/packages/stark-core/src/modules/settings/reducers/index.ts b/packages/stark-core/src/modules/settings/reducers/index.ts index b2cc44db01..f1c06fbf03 100644 --- a/packages/stark-core/src/modules/settings/reducers/index.ts +++ b/packages/stark-core/src/modules/settings/reducers/index.ts @@ -3,18 +3,37 @@ import { StarkSettings } from "../entities"; import { settingsReducer } from "../reducers"; import { StarkSettingsActions } from "../actions"; +/** + * We define part of the state assigned to the settings module + */ export interface StarkSettingsState { + /** + * The settings property + * @link StarkSettings + */ settings: StarkSettings; } +/** + * We assign a reducer to our settings property + */ export const starkSettingsReducers: ActionReducerMap = { + /** + * the reducer is assigned to our property + */ settings: settingsReducer }; +/** + * This will create the session feature used by the selector to find the settings module in the state + */ export const selectStarkSettingsFeature: MemoizedSelector = createFeatureSelector( "StarkSettings" ); +/** + * The selector will return the part of the state assigned to the settings when called + */ export const selectStarkSettings: MemoizedSelector = createSelector( selectStarkSettingsFeature, (state: StarkSettingsState) => state.settings diff --git a/packages/stark-core/src/modules/settings/reducers/settings.reducer.spec.ts b/packages/stark-core/src/modules/settings/reducers/settings.reducer.spec.ts index da1dc220d7..c7b024690a 100644 --- a/packages/stark-core/src/modules/settings/reducers/settings.reducer.spec.ts +++ b/packages/stark-core/src/modules/settings/reducers/settings.reducer.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { StarkSetPreferredLanguage } from "../actions"; import { StarkSettings } from "../entities"; import { settingsReducer } from "./settings.reducer"; diff --git a/packages/stark-core/src/modules/settings/reducers/settings.reducer.ts b/packages/stark-core/src/modules/settings/reducers/settings.reducer.ts index c8279d7f07..fbfb0f181d 100644 --- a/packages/stark-core/src/modules/settings/reducers/settings.reducer.ts +++ b/packages/stark-core/src/modules/settings/reducers/settings.reducer.ts @@ -1,10 +1,22 @@ import { StarkSettingsActions, StarkSettingsActionTypes } from "../actions"; import { StarkSettings } from "../entities"; +/** + * Key defined to find the service in a store + */ export const starkSettingsStoreKey: string = "starkSettings"; - +/** + * Defines the initial state of the reducer + * @link StarkSettings + */ const INITIAL_STATE: StarkSettings = new StarkSettings(); +/** + * Definition of the settings reducer + * @param state - the state of the reducer + * @param action - the action to apply to the reducer + * @returns a StarkSettings instance + */ export function settingsReducer( state: Readonly = INITIAL_STATE, action: Readonly diff --git a/packages/stark-core/src/modules/settings/services/settings.service.intf.ts b/packages/stark-core/src/modules/settings/services/settings.service.intf.ts index 7d300d2794..ef822059ad 100644 --- a/packages/stark-core/src/modules/settings/services/settings.service.intf.ts +++ b/packages/stark-core/src/modules/settings/services/settings.service.intf.ts @@ -1,6 +1,13 @@ import { InjectionToken } from "@angular/core"; +/** + * Name of the Settings service, in case injection is needed + */ export const starkSettingsServiceName: string = "StarkSettingsService"; +/** + * Injection Token version of the service name + * @link InjectionToken + */ export const STARK_SETTINGS_SERVICE: InjectionToken = new InjectionToken( starkSettingsServiceName ); diff --git a/packages/stark-core/src/modules/settings/services/settings.service.spec.ts b/packages/stark-core/src/modules/settings/services/settings.service.spec.ts index b7504f6e79..553586ab6a 100644 --- a/packages/stark-core/src/modules/settings/services/settings.service.spec.ts +++ b/packages/stark-core/src/modules/settings/services/settings.service.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { Store } from "@ngrx/store"; import { StarkLoggingService } from "../../logging/services"; import { MockStarkLoggingService } from "../../logging/testing"; diff --git a/packages/stark-core/src/modules/settings/services/settings.service.ts b/packages/stark-core/src/modules/settings/services/settings.service.ts index cf6ea8f4ed..fd2b17ae78 100644 --- a/packages/stark-core/src/modules/settings/services/settings.service.ts +++ b/packages/stark-core/src/modules/settings/services/settings.service.ts @@ -1,3 +1,4 @@ +/* tslint:disable:completed-docs*/ import { Inject, Injectable } from "@angular/core"; import { Store } from "@ngrx/store"; import { filter } from "rxjs/operators"; @@ -18,15 +19,9 @@ import { StarkCoreApplicationState } from "../../../common/store"; import { StarkConfigurationUtil } from "../../../util/configuration.util"; /** + * @ignore * @ngdoc service - * @name stark-core.service:StarkSettingsService * @description Service that allows the manipulation of application settings, some of which can be persisted. - * - * @requires StarkLoggingService - * @requires StarkSessionService - * @requires StarkApplicationMetadata - * @requires StarkApplicationConfig - * @requires ngrx-store.Store */ @Injectable() export class StarkSettingsServiceImpl implements StarkSettingsService { diff --git a/packages/stark-core/src/modules/settings/settings.module.ts b/packages/stark-core/src/modules/settings/settings.module.ts index 022ed6e9b4..5c8dd38e3c 100644 --- a/packages/stark-core/src/modules/settings/settings.module.ts +++ b/packages/stark-core/src/modules/settings/settings.module.ts @@ -9,9 +9,12 @@ import { StarkSettingsEffects } from "./effects"; imports: [StoreModule.forFeature("StarkSettings", starkSettingsReducers), EffectsModule.forFeature([StarkSettingsEffects])] }) export class StarkSettingsModule { - // instantiate the services only once since they should be singletons - // so the forRoot() should be called only by the AppModule - // see https://angular.io/guide/singleton-services#forroot + /** + * instantiates the services only once since they should be singletons + * so the forRoot() should be called only by the AppModule + * @link https://angular.io/guide/singleton-services#forroot + * @returns a module with providers + */ public static forRoot(): ModuleWithProviders { return { ngModule: StarkSettingsModule, @@ -19,8 +22,11 @@ export class StarkSettingsModule { }; } - // prevent this module from being re-imported - // see https://angular.io/guide/singleton-services#prevent-reimport-of-the-coremodule + /** + * prevent this module from being re-imported + * @link https://angular.io/guide/singleton-services#prevent-reimport-of-the-coremodule + * @param parentModule - thee parents module + */ public constructor( @Optional() @SkipSelf() diff --git a/packages/stark-core/src/modules/user/actions/user.actions.ts b/packages/stark-core/src/modules/user/actions/user.actions.ts index 984737376b..51ec6aeedb 100644 --- a/packages/stark-core/src/modules/user/actions/user.actions.ts +++ b/packages/stark-core/src/modules/user/actions/user.actions.ts @@ -2,6 +2,9 @@ import { Action } from "@ngrx/store"; import { StarkUser } from "../entities"; import { StarkHttpErrorWrapper } from "../../http/entities/error"; +/** + * Enumeration of the User action types + */ export enum StarkUserActionTypes { FETCH_USER_PROFILE = "[StarkUser] Get User", FETCH_USER_PROFILE_SUCCESS = "[StarkUser] Fetch User Profile Success", @@ -10,36 +13,89 @@ export enum StarkUserActionTypes { GET_ALL_USERS_SUCCESS = "[StarkUser] Get All Users Success", GET_ALL_USERS_FAILURE = "[StarkUser] Get All Users Failure" } - +/** + * Triggered when the fetchUserProfile() method is called, just before performing the HTTP to the REST API. + */ export class StarkFetchUserProfile implements Action { + /** + * The type of Action + * @link StarkUserActionTypes + */ public readonly type: StarkUserActionTypes.FETCH_USER_PROFILE = StarkUserActionTypes.FETCH_USER_PROFILE; } - +/** + * Triggered when the user profile has been successfully fetched from the REST API. + */ export class StarkFetchUserProfileSuccess implements Action { + /** + * The type of Action + * @link StarkUserActionTypes + */ public readonly type: StarkUserActionTypes.FETCH_USER_PROFILE_SUCCESS = StarkUserActionTypes.FETCH_USER_PROFILE_SUCCESS; + /** + * Class constructor + * @param user - The user fetched from the REST API + */ public constructor(public user: StarkUser) {} } - +/** + * Triggered when the HTTP call to fetch the user profile failed or when the user profile fetched is not valid. + */ export class StarkFetchUserProfileFailure implements Action { + /** + * The type of Action + * @link StarkUserActionTypes + */ public readonly type: StarkUserActionTypes.FETCH_USER_PROFILE_FAILURE = StarkUserActionTypes.FETCH_USER_PROFILE_FAILURE; + /** + * Class constructor + * @param error - The error that caused the user fetching to fail. + */ public constructor(public error: StarkHttpErrorWrapper | Error) {} } - +/** + * Triggered when the getAllUsers() method is called. + * The getAllUsers() method should only be used in development. + */ export class StarkGetAllUsers implements Action { + /** + * The type of Action + * @link StarkUserActionTypes + */ public readonly type: StarkUserActionTypes.GET_ALL_USERS = StarkUserActionTypes.GET_ALL_USERS; } - +/** + * Triggered when the users defined in the mock data are returned. + */ export class StarkGetAllUsersSuccess implements Action { + /** + * The type of Action + * @link StarkUserActionTypes + */ public readonly type: StarkUserActionTypes.GET_ALL_USERS_SUCCESS = StarkUserActionTypes.GET_ALL_USERS_SUCCESS; + /** + * Class constructor + * @param users - The users retrieved from the the mock data. + */ public constructor(public users: StarkUser[]) {} } - +/** + * Triggered when there are no users defined in the mock data. + */ export class StarkGetAllUsersFailure implements Action { + /** + * The type of Action + * @link StarkUserActionTypes + */ public readonly type: StarkUserActionTypes.GET_ALL_USERS_FAILURE = StarkUserActionTypes.GET_ALL_USERS_FAILURE; + /** + * Class constructor + * @param message - The message describing all the users failure. + */ public constructor(public message: string) {} } diff --git a/packages/stark-core/src/modules/user/entities/user-profile.entity.intf.ts b/packages/stark-core/src/modules/user/entities/user-profile.entity.intf.ts index db0e65b647..ad4ae5a824 100644 --- a/packages/stark-core/src/modules/user/entities/user-profile.entity.intf.ts +++ b/packages/stark-core/src/modules/user/entities/user-profile.entity.intf.ts @@ -1,13 +1,39 @@ +/** + * The profile of the User + */ export interface StarkUserProfile { + /** + * The user's username + */ username: string; + /** + * The user's firstname + */ firstName: string; + /** + * The user's lastname + */ lastName: string; + /** + * The user's email address + */ email?: string; + /** + * The user's phone number + */ phone?: string; + /** + * The user's language + */ language?: string; + /** + * The user's reference number + */ referenceNumber?: string; + /** + * Is the user anonymous or not? + */ isAnonymous?: boolean; - /** * This property will contain any additional details for the user profile returned by the backend */ diff --git a/packages/stark-core/src/modules/user/entities/user-security-profile.entity.intf.ts b/packages/stark-core/src/modules/user/entities/user-security-profile.entity.intf.ts index 84139a0191..d3a04f7730 100644 --- a/packages/stark-core/src/modules/user/entities/user-security-profile.entity.intf.ts +++ b/packages/stark-core/src/modules/user/entities/user-security-profile.entity.intf.ts @@ -1,4 +1,13 @@ +/** + * Class used to determine the user's security profile + */ export interface StarkUserSecurityProfile { + /** + * roles allocated to the user + */ roles: string[]; + /** + * the workpost of the user + */ workpost?: string; } diff --git a/packages/stark-core/src/modules/user/entities/user.entity.ts b/packages/stark-core/src/modules/user/entities/user.entity.ts index d29d8be299..813a7b71a4 100644 --- a/packages/stark-core/src/modules/user/entities/user.entity.ts +++ b/packages/stark-core/src/modules/user/entities/user.entity.ts @@ -5,6 +5,9 @@ import { StarkResource } from "../../http/entities"; import { IsArray, IsBoolean, IsDefined, IsEmail, IsString, ValidateIf } from "class-validator"; import { StarkClassValidationUtil } from "../../../util"; +/** + * @ignore + */ export class StarkUser implements StarkUserProfile, StarkUserSecurityProfile, StarkResource { @IsDefined() @IsString() diff --git a/packages/stark-core/src/modules/user/repository/user.repository.intf.ts b/packages/stark-core/src/modules/user/repository/user.repository.intf.ts index 261684feb1..b327b9ce44 100644 --- a/packages/stark-core/src/modules/user/repository/user.repository.intf.ts +++ b/packages/stark-core/src/modules/user/repository/user.repository.intf.ts @@ -3,7 +3,14 @@ import { Observable } from "rxjs"; import { StarkUser } from "../entities"; import { StarkSingleItemResponseWrapper } from "../../http/entities"; +/** + * Name of the User Repository, in case injection is needed + */ export const starkUserRepositoryName: string = "StarkUserRepository"; +/** + * Injection Token version of the Repository Name + * @link InjectionToken + */ export const STARK_USER_REPOSITORY: InjectionToken = new InjectionToken(starkUserRepositoryName); /** diff --git a/packages/stark-core/src/modules/user/repository/user.repository.ts b/packages/stark-core/src/modules/user/repository/user.repository.ts index 6f260850de..8afa7c6697 100644 --- a/packages/stark-core/src/modules/user/repository/user.repository.ts +++ b/packages/stark-core/src/modules/user/repository/user.repository.ts @@ -11,13 +11,9 @@ import { AbstractStarkHttpRepository } from "../../http/repository"; import { StarkConfigurationUtil } from "../../../util/configuration.util"; /** + * @ignore * @ngdoc service - * @name stark-core.repository:StarkUserRepository * @description Repository to fetch user profile from the backend. - * - * @requires StarkHttpService - * @requires StarkLoggingService - * @requires StarkApplicationConfig */ @Injectable() export class StarkUserRepositoryImpl extends AbstractStarkHttpRepository implements StarkUserRepository { diff --git a/packages/stark-core/src/modules/user/services/user.service.intf.ts b/packages/stark-core/src/modules/user/services/user.service.intf.ts index 5d25553aba..4c12ed526d 100644 --- a/packages/stark-core/src/modules/user/services/user.service.intf.ts +++ b/packages/stark-core/src/modules/user/services/user.service.intf.ts @@ -2,7 +2,13 @@ import { InjectionToken } from "@angular/core"; import { Observable } from "rxjs"; import { StarkUser } from "../entities"; +/** + * Name of the User service, in case injection is needed + */ export const starkUserServiceName: string = "StarkUserService"; +/** + * InjectionToken version of the service name + */ export const STARK_USER_SERVICE: InjectionToken = new InjectionToken(starkUserServiceName); /** @@ -14,6 +20,7 @@ export interface StarkUserService { /** * Triggers an HTTP call to the REST API to fetch the user profile * + * @link StarkUser * @returns Observable that will emit the user profile fetched from the REST API */ fetchUserProfile(): Observable; @@ -22,6 +29,7 @@ export interface StarkUserService { * Gets all user profiles defined in the mock data (to be used only in development). * This only makes sense during development, where user profiles and the profile selection screen are necessary * + * @link StarkUser * @returns Observable that will emit the user profiles defined in the mock data */ getAllUsers(): StarkUser[]; diff --git a/packages/stark-core/src/modules/user/services/user.service.spec.ts b/packages/stark-core/src/modules/user/services/user.service.spec.ts index 8cd62585a7..4fa4379664 100644 --- a/packages/stark-core/src/modules/user/services/user.service.spec.ts +++ b/packages/stark-core/src/modules/user/services/user.service.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import SpyObj = jasmine.SpyObj; import createSpyObj = jasmine.createSpyObj; import { Store } from "@ngrx/store"; diff --git a/packages/stark-core/src/modules/user/services/user.service.ts b/packages/stark-core/src/modules/user/services/user.service.ts index 193a64dee5..a299750d96 100644 --- a/packages/stark-core/src/modules/user/services/user.service.ts +++ b/packages/stark-core/src/modules/user/services/user.service.ts @@ -1,3 +1,4 @@ +/* tslint:disable:completed-docs*/ import { Inject, Injectable } from "@angular/core"; import { Store } from "@ngrx/store"; import { validateSync } from "class-validator"; @@ -21,18 +22,16 @@ import { STARK_MOCK_DATA, StarkMockData } from "../../../configuration/entities/ import { StarkCoreApplicationState } from "../../../common/store"; import { StarkValidationErrorsUtil } from "../../../util"; +/** + * @ignore + */ const userErrorMessagePrefix: string = starkUserServiceName + ": invalid user profile."; /** + * @ignore * @ngdoc service - * @name stark-core.service:StarkUserService * @description Service to fetch the user profile from the REST API. In Development, it can also be used to * set the user profile manually and to retrieve a list of profiles from a mock data file. - * - * @requires StarkLoggingService - * @requires StarkUserRepository - * @requires starkMockData the mock data to retrieve the profiles from - * @requires ngrx-store.Store */ @Injectable() export class StarkUserServiceImpl implements StarkUserService { diff --git a/packages/stark-core/src/modules/user/user.module.ts b/packages/stark-core/src/modules/user/user.module.ts index 0c09a41267..adeb0c91e3 100644 --- a/packages/stark-core/src/modules/user/user.module.ts +++ b/packages/stark-core/src/modules/user/user.module.ts @@ -4,9 +4,12 @@ import { STARK_USER_REPOSITORY, StarkUserRepositoryImpl } from "./repository"; @NgModule({}) export class StarkUserModule { - // instantiate the services only once since they should be singletons - // so the forRoot() should be called only by the AppModule - // see https://angular.io/guide/singleton-services#forroot + /** + * instantiates the services only once since they should be singletons + * so the forRoot() should be called only by the AppModule + * @link https://angular.io/guide/singleton-services#forroot + * @returns a module with providers + */ public static forRoot(): ModuleWithProviders { return { ngModule: StarkUserModule, @@ -17,8 +20,11 @@ export class StarkUserModule { }; } - // prevent this module from being re-imported - // see https://angular.io/guide/singleton-services#prevent-reimport-of-the-coremodule + /** + * prevents this module from being re-imported + * @link https://angular.io/guide/singleton-services#prevent-reimport-of-the-coremodule + * @param the parent module + */ public constructor( @Optional() @SkipSelf() diff --git a/packages/stark-core/src/serialization/string-map.ts b/packages/stark-core/src/serialization/string-map.ts index ef21f74161..1e61b39aff 100644 --- a/packages/stark-core/src/serialization/string-map.ts +++ b/packages/stark-core/src/serialization/string-map.ts @@ -1,10 +1,12 @@ -// solution proposed by @weichx for Maps having string keys -// in this way the custom behavior for handling ES6 Maps is defined once instead of doing it every time a Map is used -// See https://github.com/weichx/cerialize/issues/32 -// See https://github.com/weichx/cerialize/issues/33 - import { Deserialize, ISerializable, Serialize } from "cerialize"; +/** + * Ssolution proposed by @weichx for Maps having string keys + * in this way the custom behavior for handling ES6 Maps is defined once instead of doing it every time a Map is used + * @link https://github.com/weichx/cerialize/issues/32 + * @link https://github.com/weichx/cerialize/issues/33 + * @param targetType - the type in which we want to serialize a file + */ export const stringMap: Function = (targetType: any): ISerializable => { return { Serialize: (map: Map): object => { diff --git a/packages/stark-core/src/util/configuration.util.spec.ts b/packages/stark-core/src/util/configuration.util.spec.ts index 1476832d9b..10201da808 100644 --- a/packages/stark-core/src/util/configuration.util.spec.ts +++ b/packages/stark-core/src/util/configuration.util.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { StarkConfigurationUtil, StarkConfigValidationGroups, StarkMetadataValidationGroups } from "./configuration.util"; import { STARK_APP_CONFIG, diff --git a/packages/stark-core/src/util/configuration.util.ts b/packages/stark-core/src/util/configuration.util.ts index ac7b0847e7..6d28e8d74b 100644 --- a/packages/stark-core/src/util/configuration.util.ts +++ b/packages/stark-core/src/util/configuration.util.ts @@ -6,6 +6,9 @@ import { STARK_APP_METADATA, StarkApplicationMetadata } from "../configuration/e export type StarkConfigValidationGroups = "logging" | "routing" | "session" | "settings" | "http"; export type StarkMetadataValidationGroups = "settings"; +/** + * Util class used to validate AppConfig and AppMetadata instances + */ export class StarkConfigurationUtil { /** * Validates the given AppConfig instance and throws an error in case it is not valid diff --git a/packages/stark-core/src/util/date.util.ts b/packages/stark-core/src/util/date.util.ts index 6d5ec7d5e2..083c69a74c 100644 --- a/packages/stark-core/src/util/date.util.ts +++ b/packages/stark-core/src/util/date.util.ts @@ -1,5 +1,8 @@ import moment from "moment"; +/** + * Util class used to parse and format Date objects. + */ export class StarkDateUtil { /** * Returns a Date object when the specified dateString is a valid date according to the specified format, diff --git a/packages/stark-core/src/util/url-util.ts b/packages/stark-core/src/util/url-util.ts index 84dda40185..d0b626b9e9 100644 --- a/packages/stark-core/src/util/url-util.ts +++ b/packages/stark-core/src/util/url-util.ts @@ -1,3 +1,6 @@ +/** + * Util class that provides util methods to parse and interpolate URL params. + */ export class StarkUrlUtil { /** * Extracts all the expected parameters defined in the URL. These are defined by a placeholder like ":paramName". diff --git a/packages/stark-core/src/util/validation-class.util.ts b/packages/stark-core/src/util/validation-class.util.ts index 67c3b90108..7f9cdc112a 100644 --- a/packages/stark-core/src/util/validation-class.util.ts +++ b/packages/stark-core/src/util/validation-class.util.ts @@ -1,3 +1,6 @@ +/** + * Class containing utils to be used for class validation decorators of the 'class-validator' library + */ export class StarkClassValidationUtil { /** * Returns true if the given value is NOT undefined. diff --git a/packages/stark-core/src/util/validation-errors.util.spec.ts b/packages/stark-core/src/util/validation-errors.util.spec.ts index 7311095c1d..19eaaedd6a 100644 --- a/packages/stark-core/src/util/validation-errors.util.spec.ts +++ b/packages/stark-core/src/util/validation-errors.util.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { ArrayNotEmpty, IsNotEmpty, Matches, ValidateNested, validateSync, ValidationError } from "class-validator"; import { StarkValidationErrorsUtil } from "./validation-errors.util"; diff --git a/packages/stark-core/src/util/validation-errors.util.ts b/packages/stark-core/src/util/validation-errors.util.ts index bd4baecf4d..1f75ebf731 100644 --- a/packages/stark-core/src/util/validation-errors.util.ts +++ b/packages/stark-core/src/util/validation-errors.util.ts @@ -1,5 +1,8 @@ import { ValidationError } from "class-validator"; +/** + * Class used to format the validation errors in a readable way. + */ export class StarkValidationErrorsUtil { /** * Throws an error in case there are validation errors. The error contains the description of the different errors. diff --git a/packages/stark-core/src/validation/decorators/is-bban/is-bban.validator.decorator.spec.ts b/packages/stark-core/src/validation/decorators/is-bban/is-bban.validator.decorator.spec.ts index 2bbfcbb51b..98fab883e5 100644 --- a/packages/stark-core/src/validation/decorators/is-bban/is-bban.validator.decorator.spec.ts +++ b/packages/stark-core/src/validation/decorators/is-bban/is-bban.validator.decorator.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { validateSync, ValidationError } from "class-validator"; import { StarkIsBBAN } from "./is-bban.validator.decorator"; import { starkIsBBANValidatorName } from "../../validators/is-bban"; diff --git a/packages/stark-core/src/validation/decorators/is-bban/is-bban.validator.decorator.ts b/packages/stark-core/src/validation/decorators/is-bban/is-bban.validator.decorator.ts index 561b216cdb..7ec1c31f42 100644 --- a/packages/stark-core/src/validation/decorators/is-bban/is-bban.validator.decorator.ts +++ b/packages/stark-core/src/validation/decorators/is-bban/is-bban.validator.decorator.ts @@ -17,6 +17,11 @@ import { starkIsBBANValidatorName } from "../../validators/is-bban"; */ @ValidatorConstraint({ name: starkIsBBANValidatorName, async: false }) class StarkIsBBANConstraint implements ValidatorConstraintInterface { + /** + * Validates that a give BBAN number is valid. + * @param bban: the bban to validate + * @param validationArguments: the arguments to ensure the bban is valid + */ public validate(bban: string, validationArguments?: ValidationArguments): boolean { const validator: StarkValidator = getFromContainer(StarkValidatorImpl); const constraint: string = validationArguments && validationArguments.constraints[0] ? validationArguments.constraints[0] : ""; @@ -24,6 +29,9 @@ class StarkIsBBANConstraint implements ValidatorConstraintInterface { return validator.starkIsBBAN(bban, validationArguments ? validationArguments.object[constraint] : ""); } + /** + * Default message displayed if the BBAN number is not valid. + */ public defaultMessage(): string { return "$property value is not a valid BBAN number"; } @@ -31,8 +39,8 @@ class StarkIsBBANConstraint implements ValidatorConstraintInterface { /** * Validator decorator that uses the StarkIsBBAN validator constraint - * @param property - * @param validationOptions + * @param property: the bban number + * @param validationOptions: the options to ensure the bban is valid * @returns Function */ export function StarkIsBBAN(property: string, validationOptions?: ValidationOptions): Function { diff --git a/packages/stark-core/src/validation/decorators/is-bic/is-bic.validator.decorator.spec.ts b/packages/stark-core/src/validation/decorators/is-bic/is-bic.validator.decorator.spec.ts index 8b88005987..0094614089 100644 --- a/packages/stark-core/src/validation/decorators/is-bic/is-bic.validator.decorator.spec.ts +++ b/packages/stark-core/src/validation/decorators/is-bic/is-bic.validator.decorator.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { validateSync, ValidationError } from "class-validator"; import { StarkIsBIC } from "./is-bic.validator.decorator"; import { starkIsBICValidatorName } from "../../validators/is-bic"; diff --git a/packages/stark-core/src/validation/decorators/is-bic/is-bic.validator.decorator.ts b/packages/stark-core/src/validation/decorators/is-bic/is-bic.validator.decorator.ts index e534b62dba..42eeafdcf2 100644 --- a/packages/stark-core/src/validation/decorators/is-bic/is-bic.validator.decorator.ts +++ b/packages/stark-core/src/validation/decorators/is-bic/is-bic.validator.decorator.ts @@ -10,11 +10,20 @@ import { starkIsBICValidatorName } from "../../validators/is-bic"; */ @ValidatorConstraint({ name: starkIsBICValidatorName, async: false }) class StarkIsBICConstraint implements ValidatorConstraintInterface { + /** + * Validates that a give BIC address is valid + * @param bic - the bic to validate + * @returns boolean - true if the bic has been validated + */ public validate(bic: string): boolean { const validator: StarkValidator = getFromContainer(StarkValidatorImpl); return validator.starkIsBIC(bic); } + /** + * Default message displayed if the BIC address is not valid + * @returns a default message + */ public defaultMessage(): string { return "$property value is not a valid BIC address"; } @@ -22,7 +31,7 @@ class StarkIsBICConstraint implements ValidatorConstraintInterface { /** * Validator decorator that uses the StarkIsBIC validator constraint - * @param validationOptions + * @param validationOptions : the options used for validation * @returns Function */ export function StarkIsBIC(validationOptions?: ValidationOptions): Function { diff --git a/packages/stark-core/src/validation/decorators/is-company-number/is-company-number.validator.decorator.spec.ts b/packages/stark-core/src/validation/decorators/is-company-number/is-company-number.validator.decorator.spec.ts index d0920e850f..5b87b43a47 100644 --- a/packages/stark-core/src/validation/decorators/is-company-number/is-company-number.validator.decorator.spec.ts +++ b/packages/stark-core/src/validation/decorators/is-company-number/is-company-number.validator.decorator.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { validateSync, ValidationError } from "class-validator"; import { StarkIsCompanyNumber } from "./is-company-number.validator.decorator"; import { starkIsCompanyNumberValidatorName } from "../../validators/is-company-number"; diff --git a/packages/stark-core/src/validation/decorators/is-company-number/is-company-number.validator.decorator.ts b/packages/stark-core/src/validation/decorators/is-company-number/is-company-number.validator.decorator.ts index edf481c4f1..6e606d57f4 100644 --- a/packages/stark-core/src/validation/decorators/is-company-number/is-company-number.validator.decorator.ts +++ b/packages/stark-core/src/validation/decorators/is-company-number/is-company-number.validator.decorator.ts @@ -10,11 +10,20 @@ import { starkIsCompanyNumberValidatorName } from "../../validators/is-company-n */ @ValidatorConstraint({ name: starkIsCompanyNumberValidatorName, async: false }) class StarkIsCompanyNumberConstraint implements ValidatorConstraintInterface { + /** + * Validates that a given Company number is valid + * @param companyNumber - the number to validate + * @returns boolean - true if the company number is valid or not + */ public validate(companyNumber: string): boolean { const validator: StarkValidator = getFromContainer(StarkValidatorImpl); return validator.starkIsCompanyNumber(companyNumber); } + /** + * Default message displayed if the Company number is not valid + * @returns a default message + */ public defaultMessage(): string { return "$property value is not a valid company number"; } @@ -22,7 +31,7 @@ class StarkIsCompanyNumberConstraint implements ValidatorConstraintInterface { /** * Validator decorator that uses the StarkIsCompanyNumber validator constraint - * @param validationOptions + * @param validationOptions, that ensure that the company number is valid * @returns Function */ export function StarkIsCompanyNumber(validationOptions?: ValidationOptions): Function { diff --git a/packages/stark-core/src/validation/decorators/is-establishment-unit-number/is-establishment-unit-number.validator.decorator.spec.ts b/packages/stark-core/src/validation/decorators/is-establishment-unit-number/is-establishment-unit-number.validator.decorator.spec.ts index b9eb69086b..eb1e978f80 100644 --- a/packages/stark-core/src/validation/decorators/is-establishment-unit-number/is-establishment-unit-number.validator.decorator.spec.ts +++ b/packages/stark-core/src/validation/decorators/is-establishment-unit-number/is-establishment-unit-number.validator.decorator.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { validateSync, ValidationError } from "class-validator"; import { StarkIsEstablishmentUnitNumber } from "./is-establishment-unit-number.validator.decorator"; import { starkIsEstablishmentUnitNumberValidatorName } from "../../validators/is-establishment-unit-number"; diff --git a/packages/stark-core/src/validation/decorators/is-establishment-unit-number/is-establishment-unit-number.validator.decorator.ts b/packages/stark-core/src/validation/decorators/is-establishment-unit-number/is-establishment-unit-number.validator.decorator.ts index 2e502638d5..ecae77d621 100644 --- a/packages/stark-core/src/validation/decorators/is-establishment-unit-number/is-establishment-unit-number.validator.decorator.ts +++ b/packages/stark-core/src/validation/decorators/is-establishment-unit-number/is-establishment-unit-number.validator.decorator.ts @@ -10,12 +10,21 @@ import { starkIsEstablishmentUnitNumberValidatorName } from "../../validators/is */ @ValidatorConstraint({ name: starkIsEstablishmentUnitNumberValidatorName, async: false }) class StarkIsEstablishmentUnitNumberConstraint implements ValidatorConstraintInterface { + /** + * Validates that a given Establishment number provided is valid + * @param establishmentNumber - the establishment number to validate + * @returns boolean - true if the establishment number is valida + */ public validate(establishmentNumber: string): boolean { const validator: StarkValidator = getFromContainer(StarkValidatorImpl); return validator.starkIsEstablishmentUnitNumber(establishmentNumber); } + /** + * Default Message displayed if the Establishment number is not valid + * @returns a default message + */ public defaultMessage(): string { return "$property value is not a valid Establishment number"; } @@ -23,7 +32,7 @@ class StarkIsEstablishmentUnitNumberConstraint implements ValidatorConstraintInt /** * Validator decorator that uses the StarkIsIsEstablishmentUnitNumber validator constraint - * @param validationOptions + * @param validationOptions - the options that will define the validity of the establishment number * @returns Function */ export function StarkIsEstablishmentUnitNumber(validationOptions?: ValidationOptions): Function { diff --git a/packages/stark-core/src/validation/decorators/is-iban/is-iban.validator.decorator.spec.ts b/packages/stark-core/src/validation/decorators/is-iban/is-iban.validator.decorator.spec.ts index 1a15d552fb..5ba55b3ba5 100644 --- a/packages/stark-core/src/validation/decorators/is-iban/is-iban.validator.decorator.spec.ts +++ b/packages/stark-core/src/validation/decorators/is-iban/is-iban.validator.decorator.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { validateSync, ValidationError } from "class-validator"; import { StarkIsIBAN } from "./is-iban.validator.decorator"; import { starkIsIBANValidatorName } from "../../validators/is-iban"; diff --git a/packages/stark-core/src/validation/decorators/is-iban/is-iban.validator.decorator.ts b/packages/stark-core/src/validation/decorators/is-iban/is-iban.validator.decorator.ts index b628f5f8ec..1db2c0ab90 100644 --- a/packages/stark-core/src/validation/decorators/is-iban/is-iban.validator.decorator.ts +++ b/packages/stark-core/src/validation/decorators/is-iban/is-iban.validator.decorator.ts @@ -10,11 +10,20 @@ import { starkIsIBANValidatorName } from "../../validators/is-iban"; */ @ValidatorConstraint({ name: starkIsIBANValidatorName, async: false }) class StarkIsIBANConstraint implements ValidatorConstraintInterface { + /** + * Validtes that a given IBAN number is valid + * @param iban - the iban to validate + * @returns boolean - true if the iban is valid + */ public validate(iban: string): boolean { const validator: StarkValidator = getFromContainer(StarkValidatorImpl); return validator.starkIsIBAN(iban); } + /** + * Default message displayed if the IBAN number is not valid + * @returns a default message + */ public defaultMessage(): string { return "$property value is not a valid IBAN number"; } @@ -22,7 +31,7 @@ class StarkIsIBANConstraint implements ValidatorConstraintInterface { /** * Validator decorator that uses the StarkIsIBAN validator constraint - * @param validationOptions + * @param validationOptions, that ensure the iban is valid * @returns Function */ export function StarkIsIBAN(validationOptions?: ValidationOptions): Function { diff --git a/packages/stark-core/src/validation/decorators/is-isin/is-isin.validator.decorator.spec.ts b/packages/stark-core/src/validation/decorators/is-isin/is-isin.validator.decorator.spec.ts index 12405b9eb3..cc27a47ddb 100644 --- a/packages/stark-core/src/validation/decorators/is-isin/is-isin.validator.decorator.spec.ts +++ b/packages/stark-core/src/validation/decorators/is-isin/is-isin.validator.decorator.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { validateSync, ValidationError } from "class-validator"; import { StarkIsISIN } from "./is-isin.validator.decorator"; import { starkIsISINValidatorName } from "../../validators/is-isin"; diff --git a/packages/stark-core/src/validation/decorators/is-isin/is-isin.validator.decorator.ts b/packages/stark-core/src/validation/decorators/is-isin/is-isin.validator.decorator.ts index d2419aadab..fd0aca267f 100644 --- a/packages/stark-core/src/validation/decorators/is-isin/is-isin.validator.decorator.ts +++ b/packages/stark-core/src/validation/decorators/is-isin/is-isin.validator.decorator.ts @@ -10,12 +10,21 @@ import { starkIsISINValidatorName } from "../../validators/is-isin"; */ @ValidatorConstraint({ name: starkIsISINValidatorName, async: false }) class StarkIsISINConstraint implements ValidatorConstraintInterface { + /** + * Validates that the given ISIN number is valid + * @param isin - the isin number to validate + * @returns boolean - true if the isin is valid + */ public validate(isin: string): boolean { const validator: StarkValidator = getFromContainer(StarkValidatorImpl); return validator.starkIsISIN(isin); } + /** + * Displayes message if the ISIN number is not valid + * @returns a default message + */ public defaultMessage(): string { return "$property value is not a valid ISIN number"; } @@ -23,7 +32,7 @@ class StarkIsISINConstraint implements ValidatorConstraintInterface { /** * Validator decorator that uses the StarkIsISIN validator constraint - * @param validationOptions + * @param validationOptions - will ensure if the isin is valid or not * @returns Function */ export function StarkIsISIN(validationOptions?: ValidationOptions): Function { diff --git a/packages/stark-core/src/validation/decorators/is-kbo/is-kbo.validator.decorator.spec.ts b/packages/stark-core/src/validation/decorators/is-kbo/is-kbo.validator.decorator.spec.ts index 26a3f7d386..d2403c66e5 100644 --- a/packages/stark-core/src/validation/decorators/is-kbo/is-kbo.validator.decorator.spec.ts +++ b/packages/stark-core/src/validation/decorators/is-kbo/is-kbo.validator.decorator.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { validateSync, ValidationError } from "class-validator"; import { StarkIsKBO } from "./is-kbo.validator.decorator"; import { starkIsKBOValidatorName } from "../../validators/is-kbo"; diff --git a/packages/stark-core/src/validation/decorators/is-kbo/is-kbo.validator.decorator.ts b/packages/stark-core/src/validation/decorators/is-kbo/is-kbo.validator.decorator.ts index 591fd81ff1..7a789ffe80 100644 --- a/packages/stark-core/src/validation/decorators/is-kbo/is-kbo.validator.decorator.ts +++ b/packages/stark-core/src/validation/decorators/is-kbo/is-kbo.validator.decorator.ts @@ -5,17 +5,26 @@ import { StarkValidator } from "../../validator.intf"; import { starkIsKBOValidatorName } from "../../validators/is-kbo"; /** - * StarkIsBban validator constraint + * StarkIsKbo validator constraint * Validates that the KBO number provided is valid */ @ValidatorConstraint({ name: starkIsKBOValidatorName, async: false }) class StarkIsKBOConstraint implements ValidatorConstraintInterface { + /** + * Validates that the given KBO number is valid + * @param kbo - the kbo to validate + * @returns boolean - true if the kbo has been validated + */ public validate(kbo: string): boolean { const validator: StarkValidator = getFromContainer(StarkValidatorImpl); return validator.starkIsKBO(kbo); } + /** + * Default message displayed if the KBO number is not valid + * @returns a default message + */ public defaultMessage(): string { return "$property value is not a valid KBO number"; } @@ -23,7 +32,7 @@ class StarkIsKBOConstraint implements ValidatorConstraintInterface { /** * Validator decorator that uses the StarkIsKBO validator constraint - * @param validationOptions + * @param validationOptions - the options that will define the validity of the kbo number * @returns Function */ export function StarkIsKBO(validationOptions?: ValidationOptions): Function { diff --git a/packages/stark-core/src/validation/decorators/is-nin/is-nin.validator.decorator.spec.ts b/packages/stark-core/src/validation/decorators/is-nin/is-nin.validator.decorator.spec.ts index c5f4032498..221abbf981 100644 --- a/packages/stark-core/src/validation/decorators/is-nin/is-nin.validator.decorator.spec.ts +++ b/packages/stark-core/src/validation/decorators/is-nin/is-nin.validator.decorator.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { validateSync, ValidationError } from "class-validator"; import { StarkIsNIN } from "./is-nin.validator.decorator"; import { starkIsNINValidatorName } from "../../validators/is-nin"; diff --git a/packages/stark-core/src/validation/decorators/is-nin/is-nin.validator.decorator.ts b/packages/stark-core/src/validation/decorators/is-nin/is-nin.validator.decorator.ts index 81b87a143f..8c1d8b43e5 100644 --- a/packages/stark-core/src/validation/decorators/is-nin/is-nin.validator.decorator.ts +++ b/packages/stark-core/src/validation/decorators/is-nin/is-nin.validator.decorator.ts @@ -17,6 +17,11 @@ import { starkIsNINValidatorName } from "../../validators/is-nin"; */ @ValidatorConstraint({ name: starkIsNINValidatorName, async: false }) class StarkIsNINConstraint implements ValidatorConstraintInterface { + /** + * Validate that the provided NIN number is valid + * @param nin: the nin to validate + * @param validationArguments: the arguments to validate + */ public validate(nin: string, validationArguments?: ValidationArguments): boolean { const validator: StarkValidator = getFromContainer(StarkValidatorImpl); const constraint: string = validationArguments && validationArguments.constraints[0] ? validationArguments.constraints[0] : ""; @@ -24,6 +29,9 @@ class StarkIsNINConstraint implements ValidatorConstraintInterface { return validator.starkIsNIN(nin, validationArguments ? validationArguments.object[constraint] : ""); } + /** + * Default value displayed if the NIN number is not valid + */ public defaultMessage(): string { return "$property value is not a valid NIN number"; } @@ -31,9 +39,8 @@ class StarkIsNINConstraint implements ValidatorConstraintInterface { /** * Validator decorator that uses the StarkIsNIN validator constraint - * @param property - * @param validationOptions - * @returns Function + * @param property : the property to validate + * @param validationOptions - the options that will define if the nin is valid */ export function StarkIsNIN(property: string, validationOptions?: ValidationOptions): Function { return (object: object, propertyName: string): void => { diff --git a/packages/stark-core/src/validation/decorators/is-supported-language/is-supported-language.validator.decorator.spec.ts b/packages/stark-core/src/validation/decorators/is-supported-language/is-supported-language.validator.decorator.spec.ts index 6d766bab45..0f4dcc166f 100644 --- a/packages/stark-core/src/validation/decorators/is-supported-language/is-supported-language.validator.decorator.spec.ts +++ b/packages/stark-core/src/validation/decorators/is-supported-language/is-supported-language.validator.decorator.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { validateSync, ValidationError } from "class-validator"; import { StarkIsSupportedLanguage } from "./is-supported-language.validator.decorator"; import { starkIsSupportedLanguageValidatorName } from "../../validators/is-supported-language"; diff --git a/packages/stark-core/src/validation/decorators/is-supported-language/is-supported-language.validator.decorator.ts b/packages/stark-core/src/validation/decorators/is-supported-language/is-supported-language.validator.decorator.ts index e29fe628dc..8e0ad03b51 100644 --- a/packages/stark-core/src/validation/decorators/is-supported-language/is-supported-language.validator.decorator.ts +++ b/packages/stark-core/src/validation/decorators/is-supported-language/is-supported-language.validator.decorator.ts @@ -10,11 +10,20 @@ import { starkIsSupportedLanguageValidatorName } from "../../validators/is-suppo */ @ValidatorConstraint({ name: starkIsSupportedLanguageValidatorName, async: false }) class StarkIsSupportedLanguageConstraint implements ValidatorConstraintInterface { + /** + * Validates that the language is supported + * @param isoCode - the iseCode to validate + * @returns boolean - true if the isoCode is valid + */ public validate(isoCode: string): boolean { const validator: StarkValidator = getFromContainer(StarkValidatorImpl); return validator.starkIsSupportedLanguage(isoCode); } + /** + * Default message displayed if the language is not supported + * @returns a default message + */ public defaultMessage(): string { return "The language ISO code '$value' is not supported by the Stark framework."; } @@ -22,7 +31,7 @@ class StarkIsSupportedLanguageConstraint implements ValidatorConstraintInterface /** * Validator decorator that uses the StarkIsSupportedLanguage validator constraint - * @param validationOptions + * @param validationOptions - ensures that the language is supported or not * @returns Function */ export function StarkIsSupportedLanguage(validationOptions?: ValidationOptions): Function { diff --git a/packages/stark-core/src/validation/decorators/map-is-valid/map-is-valid.validator.decorator.spec.ts b/packages/stark-core/src/validation/decorators/map-is-valid/map-is-valid.validator.decorator.spec.ts index d8955ae890..83e20a507f 100644 --- a/packages/stark-core/src/validation/decorators/map-is-valid/map-is-valid.validator.decorator.spec.ts +++ b/packages/stark-core/src/validation/decorators/map-is-valid/map-is-valid.validator.decorator.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { IsNotEmpty, MaxLength, validateSync, ValidationError } from "class-validator"; import { StarkMapIsValid, starkMapIsValidValidatorName } from "./map-is-valid.validator.decorator"; diff --git a/packages/stark-core/src/validation/decorators/map-is-valid/map-is-valid.validator.decorator.ts b/packages/stark-core/src/validation/decorators/map-is-valid/map-is-valid.validator.decorator.ts index 89ad91d80d..d58311c679 100644 --- a/packages/stark-core/src/validation/decorators/map-is-valid/map-is-valid.validator.decorator.ts +++ b/packages/stark-core/src/validation/decorators/map-is-valid/map-is-valid.validator.decorator.ts @@ -8,6 +8,9 @@ import { } from "class-validator"; import { StarkValidationErrorsUtil } from "../../../util"; +/** + * Name of the validator, in case injection is needed. + */ export const starkMapIsValidValidatorName: string = "starkMapIsValid"; /** @@ -16,9 +19,20 @@ export const starkMapIsValidValidatorName: string = "starkMapIsValid"; */ @ValidatorConstraint({ name: starkMapIsValidValidatorName, async: false }) class StarkMapIsValidConstraint implements ValidatorConstraintInterface { + /** + * an Array of validation errors' keys + */ public keysValidationErrors: ValidationError[]; + /** + * an Array of validation errors' values + */ public valuesValidationErrors: ValidationError[]; + /** + * Validates that a give Map is valid + * @param map: the map to validate + * @returns boolean - true if the map is valid + */ public validate(map: Map): boolean { if (!(map instanceof Map) || !map.size) { return false; @@ -40,6 +54,10 @@ class StarkMapIsValidConstraint implements ValidatorConstraintInterface { return this.keysValidationErrors.length === 0 && this.valuesValidationErrors.length === 0; } + /** + * Default message displayed when the map contains invalid entries + * @returns a default message + */ public defaultMessage(): string { let keysValidationMessage: string = StarkValidationErrorsUtil.toString(this.keysValidationErrors); let valuesValidationMessage: string = StarkValidationErrorsUtil.toString(this.valuesValidationErrors); @@ -57,7 +75,7 @@ class StarkMapIsValidConstraint implements ValidatorConstraintInterface { /** * Validator decorator that uses the StarkMapIsValid validator constraint - * @param validationOptions + * @param validationOptions, options to determine if the map is valid * @returns Function */ export function StarkMapIsValid(validationOptions?: ValidationOptions): Function { diff --git a/packages/stark-core/src/validation/decorators/map-not-empty/map-not-empty.validator.decorator.spec.ts b/packages/stark-core/src/validation/decorators/map-not-empty/map-not-empty.validator.decorator.spec.ts index 590f1eb9e8..356b504250 100644 --- a/packages/stark-core/src/validation/decorators/map-not-empty/map-not-empty.validator.decorator.spec.ts +++ b/packages/stark-core/src/validation/decorators/map-not-empty/map-not-empty.validator.decorator.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { validateSync, ValidationError } from "class-validator"; import { StarkMapNotEmpty } from "./map-not-empty.validator.decorator"; import { starkMapNotEmptyValidatorName } from "../../validators/map-not-empty"; diff --git a/packages/stark-core/src/validation/decorators/map-not-empty/map-not-empty.validator.decorator.ts b/packages/stark-core/src/validation/decorators/map-not-empty/map-not-empty.validator.decorator.ts index e7fcae462f..a87cfb9d13 100644 --- a/packages/stark-core/src/validation/decorators/map-not-empty/map-not-empty.validator.decorator.ts +++ b/packages/stark-core/src/validation/decorators/map-not-empty/map-not-empty.validator.decorator.ts @@ -10,11 +10,18 @@ import { starkMapNotEmptyValidatorName } from "../../validators/map-not-empty"; */ @ValidatorConstraint({ name: starkMapNotEmptyValidatorName, async: false }) class StarkMapNotEmptyConstraint implements ValidatorConstraintInterface { + /** + * Validates that a given map is not empty + * @param map: the map to validate + */ public validate(map: Map): boolean { const validator: StarkValidator = getFromContainer(StarkValidatorImpl); return validator.starkMapNotEmpty(map); } + /** + * Default message displayed if a map is empty + */ public defaultMessage(): string { return "$property map should not be empty"; } @@ -22,8 +29,7 @@ class StarkMapNotEmptyConstraint implements ValidatorConstraintInterface { /** * Validator decorator that uses the StarkMapNotEmpty validator constraint - * @param validationOptions - * @returns Function + * @param validationOptions, that ensure that the map is valid or not */ export function StarkMapNotEmpty(validationOptions?: ValidationOptions): Function { return (object: object, propertyName: string): void => { diff --git a/packages/stark-core/src/validation/validator.intf.ts b/packages/stark-core/src/validation/validator.intf.ts index 21e09443de..b7c90776c8 100644 --- a/packages/stark-core/src/validation/validator.intf.ts +++ b/packages/stark-core/src/validation/validator.intf.ts @@ -1,16 +1,123 @@ import { Validator } from "class-validator"; +/** + * Interface that defines validators usable in a Stark Project + */ export interface StarkValidator extends Validator { + /** + * Validates that the size of the given array is between the minimum and maximum limits defined + * @param any - an array of selected items + * @param minSize - the minSize we want to apply to the array + * @param maxSize - the maxSize we want to apply to the array + * @returns boolean - true if the array size range is valid + */ starkArraySizeRange(value: any[], minSize: number, maxSize: number): boolean; + + /** + * Validates that the given string is a valid BBAN account. (Based on the country). + * This validation requires a special usage because of the country code. + * @param value - the bban account number to validate + * @param countryCode - the country code that will be used to validate the bban number + * @returns boolean - true if the bban number is valid + */ starkIsBBAN(value: string, countryCode: string): boolean; + + /** + * ISO 9362 (also known as SWIFT-BIC, BIC code, SWIFT ID or SWIFT code) is a standard format of Business Identifier Codes approved + * by the International Organization for Standardization (ISO). It is a unique identification code for both financial and + * non-financial institutions.[1] (When assigned to a non-financial institution, a code may also be known as a Business Entity + * Identifier or BEI. These codes are used when transferring money between banks, particularly for international wire transfers, and + * also for the exchange of other messages between banks. The codes can sometimes be found on account statements. + * + *

    + *
  • 4 letters: Institution Code or bank code.
    • + *
  • 2 letters: ISO 3166-1 alpha-2 country code
    • + *
  • 2 letters or digits: location code + *
      + *
    • if the second character is "0", then it is typically a test BIC as opposed to a BIC used on the live network.
      • + *
    • if the second character is "1", then it denotes a passive participant in the SWIFT network
      • + *
    • if the second character is "2", then it typically indicates a reverse billing BIC, where the recipient pays for the message + * as opposed to the more usual mode whereby the sender pays for the message.
      • + *
    + *
    • + *
  • 3 letters or digits: branch code, optional ('XXX' for primary office)
    • + *
+ * + * http://en.wikipedia.org/wiki/ISO_9362 + * + * @param value - the bic to validate + * @returns boolean - true if the bic is valid + */ starkIsBIC(value: string): boolean; + + /** + * Validates that the given string is a valid company number (Belgium). + * @param value - the company number to validate + * @returns boolean - true if the company number if valid + */ starkIsCompanyNumber(value: string): boolean; + + /** + * Validates that the given string is a valid establishment unit number (Belgium). + * @param value - the establishmentNumber to validate + * @returns boolean - true if the establishment number is valid + */ starkIsEstablishmentUnitNumber(value: string): boolean; + + /** + * Validates that the given string is a valid IBAN. (Based on the country) + * @param value - the iban number to validate + * @returns boolean - true if the iban is valid + */ starkIsIBAN(value: string): boolean; + + /** + * An International Securities Identification Number (ISIN) uniquely identifies a security. Its structure is defined in ISO 6166. + * Securities for which ISINs are issued include bonds, commercial paper, equities and warrants. The ISIN code is a 12-character + * alpha-numerical code that does not contain information characterizing financial instruments but serves for uniform identification + * of a security at trading and settlement. + * + * Checks if the number is a valid ISIN number (Modulus 10 Double Add Double) + * + * @param value - the isin number to validate + * @returns boolean - true if the iban is valid + */ starkIsISIN(value: string): boolean; + + /** + * Validates that the given string is a valid KBO number (Belgium). + * @param value - the kbo number to validate + * @returns boolean - true if the kbo number is valid + */ starkIsKBO(value: string): boolean; + + /** + * Validates that the given string is a valid NIN (National Idenfier Number). + * This validation requires a special usage because of the of the country code. + * @param value - the nin to validate + * @param countryCode - the countrycode to use for the nin validation + * @returns boolean - true if the nin is valid + */ starkIsNIN(value: string, countryCode: string): boolean; + + /** + * Validates that the Map is not empty (it should have entries). + * @param value - the map to validate + * @returns boolean - true if the map is not empty + */ starkMapNotEmpty(value: Map): boolean; + + /** + * Validates that the given StarkLanguage object is a supported language by Stark. + * @param value - the StarkLanguage object to validate + * @returns boolean - true if the object if valid + */ starkIsSupportedLanguage(value: string): boolean; + + /** + * Validates that the given string is a valid date. + * @param value - the string to validate + * @returns boolean - true if the string is a valid date + */ starkIsDateTime(value: string): boolean; } diff --git a/packages/stark-core/src/validation/validator.ts b/packages/stark-core/src/validation/validator.ts index 3dfb15f8a6..181fb621e6 100644 --- a/packages/stark-core/src/validation/validator.ts +++ b/packages/stark-core/src/validation/validator.ts @@ -14,7 +14,9 @@ import { starkIsSupportedLanguage, starkMapNotEmpty } from "./validators"; - +/** + * @ignore + */ export class StarkValidatorImpl extends Validator implements StarkValidator { public constructor() { super(); diff --git a/packages/stark-core/src/validation/validators/array-size-range/array-size-range.validator.fn.spec.ts b/packages/stark-core/src/validation/validators/array-size-range/array-size-range.validator.fn.spec.ts index e77dbd5d82..a1e5a73c2c 100644 --- a/packages/stark-core/src/validation/validators/array-size-range/array-size-range.validator.fn.spec.ts +++ b/packages/stark-core/src/validation/validators/array-size-range/array-size-range.validator.fn.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { starkArraySizeRange } from "./array-size-range.validator.fn"; function getTestArray(numberOfItems: number): number[] { diff --git a/packages/stark-core/src/validation/validators/array-size-range/array-size-range.validator.fn.ts b/packages/stark-core/src/validation/validators/array-size-range/array-size-range.validator.fn.ts index 6e4759dd64..d3c32db1e4 100644 --- a/packages/stark-core/src/validation/validators/array-size-range/array-size-range.validator.fn.ts +++ b/packages/stark-core/src/validation/validators/array-size-range/array-size-range.validator.fn.ts @@ -2,8 +2,20 @@ import { getFromContainer } from "class-validator"; import { StarkValidator } from "../../validator.intf"; import { StarkValidatorImpl } from "../../validator"; +/** + * @ignore + * Name of the validator, in case injection is needed + */ export const starkArraySizeRangeValidatorName: string = "starkArraySizeRange"; +/** + * @ignore + * Validates that the size of the given array is between the minimum and maximum limits defined + * @param array - an array of selected items + * @param minSize - the minSize we want to apply to the array + * @param maxSize - the maxSize we want to apply to the array + * @returns boolean - true if the array size range is valid + */ export function starkArraySizeRange(array: any[], minSize?: number, maxSize?: number): boolean { const validator: StarkValidator = getFromContainer(StarkValidatorImpl); let isValid: boolean = true; diff --git a/packages/stark-core/src/validation/validators/is-bban/is-bban.validator.fn.spec.ts b/packages/stark-core/src/validation/validators/is-bban/is-bban.validator.fn.spec.ts index dce96154ef..64bb2f56ee 100644 --- a/packages/stark-core/src/validation/validators/is-bban/is-bban.validator.fn.spec.ts +++ b/packages/stark-core/src/validation/validators/is-bban/is-bban.validator.fn.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { starkIsBBAN } from "./is-bban.validator.fn"; describe("Validator Function: StarkIsBBAN", () => { diff --git a/packages/stark-core/src/validation/validators/is-bban/is-bban.validator.fn.ts b/packages/stark-core/src/validation/validators/is-bban/is-bban.validator.fn.ts index 0252d65a95..e187f73621 100644 --- a/packages/stark-core/src/validation/validators/is-bban/is-bban.validator.fn.ts +++ b/packages/stark-core/src/validation/validators/is-bban/is-bban.validator.fn.ts @@ -5,8 +5,20 @@ const _floor: Function = require("lodash/floor"); import { isValidBBAN } from "ibantools"; +/** + * @ignore + * Name of the validator, in case injection is needed. + */ export const starkIsBBANValidatorName: string = "starkIsBBAN"; +/** + * @ignore + * Validates that the given string is a valid BBAN account. (Based on the country). + * This validation requires a special usage because of the country code. + * @param bban - the bban account number to validate + * @param countryCode - the country code that will be used to validate the bban number + * @returns boolean - true if the bban number is valid + */ export function starkIsBBAN(bban: string, countryCode: string = ""): boolean { const strippedBban: string = typeof bban === "string" ? bban.replace(/\s/g, "") : bban; if (isValidBBAN(strippedBban, countryCode.toUpperCase())) { @@ -22,6 +34,12 @@ export function starkIsBBAN(bban: string, countryCode: string = ""): boolean { return false; } +/** + * @ignore + * Calculates the check digit, to ensure there is no error with the bban number + * @param bbanNumber - the bban number to validate + * @returns the newly calculated check digits + */ function calculateCheckDigit(bbanNumber: string): number { const firstPart: number = parseInt(bbanNumber.substring(0, bbanNumber.length - 2), 10); let checkDigit: number = _floor(firstPart % 97); diff --git a/packages/stark-core/src/validation/validators/is-bic/is-bic.validator.fn.spec.ts b/packages/stark-core/src/validation/validators/is-bic/is-bic.validator.fn.spec.ts index 9063cfe150..5586900a43 100644 --- a/packages/stark-core/src/validation/validators/is-bic/is-bic.validator.fn.spec.ts +++ b/packages/stark-core/src/validation/validators/is-bic/is-bic.validator.fn.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { starkIsBIC } from "./is-bic.validator.fn"; describe("Validator Function: StarkIsBIC", () => { diff --git a/packages/stark-core/src/validation/validators/is-bic/is-bic.validator.fn.ts b/packages/stark-core/src/validation/validators/is-bic/is-bic.validator.fn.ts index 271e245717..247f2724da 100644 --- a/packages/stark-core/src/validation/validators/is-bic/is-bic.validator.fn.ts +++ b/packages/stark-core/src/validation/validators/is-bic/is-bic.validator.fn.ts @@ -1,6 +1,11 @@ +/** + * @ignore + * Name of the validator, in case injection is needed. + */ export const starkIsBICValidatorName: string = "starkIsBIC"; /** + * @ignore * ISO 9362 (also known as SWIFT-BIC, BIC code, SWIFT ID or SWIFT code) is a standard format of Business Identifier Codes approved * by the International Organization for Standardization (ISO). It is a unique identification code for both financial and * non-financial institutions.[1] (When assigned to a non-financial institution, a code may also be known as a Business Entity diff --git a/packages/stark-core/src/validation/validators/is-company-number/is-company-number.validator.fn.spec.ts b/packages/stark-core/src/validation/validators/is-company-number/is-company-number.validator.fn.spec.ts index 95c1211c8b..82b391549e 100644 --- a/packages/stark-core/src/validation/validators/is-company-number/is-company-number.validator.fn.spec.ts +++ b/packages/stark-core/src/validation/validators/is-company-number/is-company-number.validator.fn.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { starkIsCompanyNumber } from "./is-company-number.validator.fn"; describe("Validator Function: StarkIsCompanyNumber", () => { diff --git a/packages/stark-core/src/validation/validators/is-company-number/is-company-number.validator.fn.ts b/packages/stark-core/src/validation/validators/is-company-number/is-company-number.validator.fn.ts index 908caaba10..09f044d95f 100644 --- a/packages/stark-core/src/validation/validators/is-company-number/is-company-number.validator.fn.ts +++ b/packages/stark-core/src/validation/validators/is-company-number/is-company-number.validator.fn.ts @@ -1,5 +1,14 @@ +/** + * @ignore + * Name of the validator, in case injection is needed. + */ export const starkIsCompanyNumberValidatorName: string = "starkIsCompanyNumber"; +/** + * @ignore + * Validates that the given string is a valid company number (Belgium). + * @param companyNumber - the company number to validate + */ export function starkIsCompanyNumber(companyNumber: string): boolean { let valid: boolean = false; diff --git a/packages/stark-core/src/validation/validators/is-date-time/is-date-time.validator.fn.spec.ts b/packages/stark-core/src/validation/validators/is-date-time/is-date-time.validator.fn.spec.ts index a95c8c0a85..5ab5ee597e 100644 --- a/packages/stark-core/src/validation/validators/is-date-time/is-date-time.validator.fn.spec.ts +++ b/packages/stark-core/src/validation/validators/is-date-time/is-date-time.validator.fn.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { starkIsDateTime } from "./is-date-time.validator.fn"; describe("Validator Function: StarkIsDateTime", () => { diff --git a/packages/stark-core/src/validation/validators/is-date-time/is-date-time.validator.fn.ts b/packages/stark-core/src/validation/validators/is-date-time/is-date-time.validator.fn.ts index f108773d23..d6b272f024 100644 --- a/packages/stark-core/src/validation/validators/is-date-time/is-date-time.validator.fn.ts +++ b/packages/stark-core/src/validation/validators/is-date-time/is-date-time.validator.fn.ts @@ -1,7 +1,17 @@ import moment from "moment"; +/** + * @ignore + * Name of the validator, in case injection is needed + */ export const starkIsDateTimeValidatorName: string = "starkIsDateTime"; +/** + * @ignore + * Validates that the given string is a valid date. + * @param inputString - the date and time to validate + * @param format - the date format used to validate the entered date + */ export function starkIsDateTime(inputString: string, format: string = "DD-MM-YYYY HH:mm:ss"): boolean { return moment(inputString, format, true).isValid(); } diff --git a/packages/stark-core/src/validation/validators/is-establishment-unit-number/is-establishment-unit-number.validator.fn.spec.ts b/packages/stark-core/src/validation/validators/is-establishment-unit-number/is-establishment-unit-number.validator.fn.spec.ts index 1a9ebdff78..00ecd34429 100644 --- a/packages/stark-core/src/validation/validators/is-establishment-unit-number/is-establishment-unit-number.validator.fn.spec.ts +++ b/packages/stark-core/src/validation/validators/is-establishment-unit-number/is-establishment-unit-number.validator.fn.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { starkIsEstablishmentUnitNumber } from "./is-establishment-unit-number.validator.fn"; describe("Validator Function: StarkIsEstablishmentUnitNumber", () => { diff --git a/packages/stark-core/src/validation/validators/is-establishment-unit-number/is-establishment-unit-number.validator.fn.ts b/packages/stark-core/src/validation/validators/is-establishment-unit-number/is-establishment-unit-number.validator.fn.ts index 17a8fed442..bc78b3312a 100644 --- a/packages/stark-core/src/validation/validators/is-establishment-unit-number/is-establishment-unit-number.validator.fn.ts +++ b/packages/stark-core/src/validation/validators/is-establishment-unit-number/is-establishment-unit-number.validator.fn.ts @@ -3,8 +3,17 @@ */ const _floor: Function = require("lodash/floor"); +/** + * @ignore + * Name of the validator, in case injection is needed + */ export const starkIsEstablishmentUnitNumberValidatorName: string = "starkIsEstablishmentUnitNumber"; +/** + * @ignore + * Validates that the given string is a valid establishment unit number (Belgium). + * @param establishmentNumber - the establishmentNumber to validate + */ export function starkIsEstablishmentUnitNumber(establishmentNumber: string): boolean { const controlNumberBeginIndex: number = 8; const controlNumberEndIndex: number = 10; diff --git a/packages/stark-core/src/validation/validators/is-iban/is-iban.validator.fn.spec.ts b/packages/stark-core/src/validation/validators/is-iban/is-iban.validator.fn.spec.ts index f907f3141f..86ff357d0f 100644 --- a/packages/stark-core/src/validation/validators/is-iban/is-iban.validator.fn.spec.ts +++ b/packages/stark-core/src/validation/validators/is-iban/is-iban.validator.fn.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { starkIsIBAN } from "./is-iban.validator.fn"; describe("Validator Function: StarkIsIBAN", () => { diff --git a/packages/stark-core/src/validation/validators/is-iban/is-iban.validator.fn.ts b/packages/stark-core/src/validation/validators/is-iban/is-iban.validator.fn.ts index 1b02433472..8eaf11e7ba 100644 --- a/packages/stark-core/src/validation/validators/is-iban/is-iban.validator.fn.ts +++ b/packages/stark-core/src/validation/validators/is-iban/is-iban.validator.fn.ts @@ -1,7 +1,16 @@ import { isValidIBAN, electronicFormatIBAN } from "ibantools"; +/** + * @ignore + * Name of the validator, in case injection is needed. + */ export const starkIsIBANValidatorName: string = "starkIsIBAN"; +/** + * @ignore + * Validates that the given string is a valid IBAN. (Based on the country) + * @param iban - the iban number to validate + */ export function starkIsIBAN(iban: string): boolean { if (typeof iban === "string") { //Since v2.0.0 of ibantools, isValidIBAN() is false if there is " " in the verified IBAN diff --git a/packages/stark-core/src/validation/validators/is-isin/is-isin.validator.fn.spec.ts b/packages/stark-core/src/validation/validators/is-isin/is-isin.validator.fn.spec.ts index b89ddaf6d4..f9ce400240 100644 --- a/packages/stark-core/src/validation/validators/is-isin/is-isin.validator.fn.spec.ts +++ b/packages/stark-core/src/validation/validators/is-isin/is-isin.validator.fn.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { starkIsISIN } from "./is-isin.validator.fn"; describe("Validator Function: StarkIsISIN", () => { diff --git a/packages/stark-core/src/validation/validators/is-isin/is-isin.validator.fn.ts b/packages/stark-core/src/validation/validators/is-isin/is-isin.validator.fn.ts index d03ae020c4..6cab084f6d 100644 --- a/packages/stark-core/src/validation/validators/is-isin/is-isin.validator.fn.ts +++ b/packages/stark-core/src/validation/validators/is-isin/is-isin.validator.fn.ts @@ -3,9 +3,14 @@ */ const _floor: Function = require("lodash/floor"); +/** + * @ignore + * Name of the validator, in case injection is needed. + */ export const starkIsISINValidatorName: string = "starkIsISIN"; /** + * @ignore * An International Securities Identification Number (ISIN) uniquely identifies a security. Its structure is defined in ISO 6166. * Securities for which ISINs are issued include bonds, commercial paper, equities and warrants. The ISIN code is a 12-character * alpha-numerical code that does not contain information characterizing financial instruments but serves for uniform identification diff --git a/packages/stark-core/src/validation/validators/is-kbo/is-kbo.validator.fn.spec.ts b/packages/stark-core/src/validation/validators/is-kbo/is-kbo.validator.fn.spec.ts index c66d952402..9d0359471f 100644 --- a/packages/stark-core/src/validation/validators/is-kbo/is-kbo.validator.fn.spec.ts +++ b/packages/stark-core/src/validation/validators/is-kbo/is-kbo.validator.fn.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { starkIsKBO } from "./is-kbo.validator.fn"; describe("Validator Function: StarkIsKBO", () => { diff --git a/packages/stark-core/src/validation/validators/is-kbo/is-kbo.validator.fn.ts b/packages/stark-core/src/validation/validators/is-kbo/is-kbo.validator.fn.ts index 743b85ef78..78b76a25fb 100644 --- a/packages/stark-core/src/validation/validators/is-kbo/is-kbo.validator.fn.ts +++ b/packages/stark-core/src/validation/validators/is-kbo/is-kbo.validator.fn.ts @@ -1,8 +1,18 @@ import { starkIsCompanyNumber } from "../is-company-number/is-company-number.validator.fn"; import { starkIsEstablishmentUnitNumber } from "../is-establishment-unit-number/is-establishment-unit-number.validator.fn"; +/** + * @ignore + * Name of the validator, in case injection is needed + */ export const starkIsKBOValidatorName: string = "starkIsKBO"; +/** + * @ignore + * Validates that the given string is a valid KBO number (Belgium). + * @param kbo - the kbo to validate + * @returns boolean - true if the kbo is valid + */ export function starkIsKBO(kbo: string): boolean { return starkIsCompanyNumber(kbo) || starkIsEstablishmentUnitNumber(kbo); } diff --git a/packages/stark-core/src/validation/validators/is-nin/is-nin.validator.fn.spec.ts b/packages/stark-core/src/validation/validators/is-nin/is-nin.validator.fn.spec.ts index d0430b0fc4..10a3931692 100644 --- a/packages/stark-core/src/validation/validators/is-nin/is-nin.validator.fn.spec.ts +++ b/packages/stark-core/src/validation/validators/is-nin/is-nin.validator.fn.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { starkIsNIN } from "./is-nin.validator.fn"; describe("Validator Function: StarkIsNIN", () => { diff --git a/packages/stark-core/src/validation/validators/is-nin/is-nin.validator.fn.ts b/packages/stark-core/src/validation/validators/is-nin/is-nin.validator.fn.ts index 79ee6bfec7..2247290e78 100644 --- a/packages/stark-core/src/validation/validators/is-nin/is-nin.validator.fn.ts +++ b/packages/stark-core/src/validation/validators/is-nin/is-nin.validator.fn.ts @@ -4,15 +4,17 @@ const _floor: Function = require("lodash/floor"); /** + * @ignore * Name of the starkIsNIN validator */ export const starkIsNINValidatorName: string = "starkIsNIN"; /** + * @ignore * Validator function that checks if the given input is a valid national identification number (NIN) - * @param nin the NIN to check - * @param countryCode the country code - * @returns true if the given input is a valid NIN + * @param nin - the NIN to check + * @param countryCode - the country code + * @returns boolean - true if the given input is a valid NIN */ export function starkIsNIN(nin: string, countryCode: string): boolean { let isValid: boolean = false; @@ -27,6 +29,7 @@ export function starkIsNIN(nin: string, countryCode: string): boolean { } /** + * @ignore * Validates that a given String is a valid National Register Number.
*
* The National Registration Number in Belgium is composed of 11 digits:
diff --git a/packages/stark-core/src/validation/validators/is-supported-language/is-supported-language.fn.spec.ts b/packages/stark-core/src/validation/validators/is-supported-language/is-supported-language.fn.spec.ts index 4c22bcef03..7467bac2df 100644 --- a/packages/stark-core/src/validation/validators/is-supported-language/is-supported-language.fn.spec.ts +++ b/packages/stark-core/src/validation/validators/is-supported-language/is-supported-language.fn.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { starkIsSupportedLanguage } from "./is-supported-language.fn"; describe("Validator Function: StarkIsSupportedLanguage", () => { diff --git a/packages/stark-core/src/validation/validators/is-supported-language/is-supported-language.fn.ts b/packages/stark-core/src/validation/validators/is-supported-language/is-supported-language.fn.ts index 9a34b69f2c..2e5bb381bb 100644 --- a/packages/stark-core/src/validation/validators/is-supported-language/is-supported-language.fn.ts +++ b/packages/stark-core/src/validation/validators/is-supported-language/is-supported-language.fn.ts @@ -2,13 +2,15 @@ import { StarkLanguage } from "../../../configuration/entities/language/language import { StarkLanguages } from "../../../configuration/entities/language/language.constants"; /** + * @ignore * Name of the starkIsSupportedLanguage validator. {@link StarkLanguage} */ export const starkIsSupportedLanguageValidatorName: string = "starkIsSupportedLanguage"; /** + * @ignore * Validator function that checks if the given ISO code is supported by Stark or not - * @param isoCode the ISO code to check + * @param isoCode - the ISO code to check * @returns true if the given ISO code is part of {@link StarkLanguage} */ export function starkIsSupportedLanguage(isoCode: string): boolean { diff --git a/packages/stark-core/src/validation/validators/map-not-empty/map-not-empty.validator.fn.spec.ts b/packages/stark-core/src/validation/validators/map-not-empty/map-not-empty.validator.fn.spec.ts index 5bd05c87b6..42e0d0b22a 100644 --- a/packages/stark-core/src/validation/validators/map-not-empty/map-not-empty.validator.fn.spec.ts +++ b/packages/stark-core/src/validation/validators/map-not-empty/map-not-empty.validator.fn.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { starkMapNotEmpty } from "./map-not-empty.validator.fn"; describe("Validator Function: StarkMapNotEmpty", () => { diff --git a/packages/stark-core/tslint.json b/packages/stark-core/tslint.json index eea5d53c7f..ece321191f 100644 --- a/packages/stark-core/tslint.json +++ b/packages/stark-core/tslint.json @@ -1,3 +1,7 @@ { - "extends": ["tslint:latest", "tslint-sonarts", "codelyzer", "tslint-config-prettier", "../stark-build/config/tslint.json"] + "extends": ["tslint:latest", "tslint-sonarts", "codelyzer", "tslint-config-prettier", "../stark-build/config/tslint.json"], + "rules": { + "jsdoc-format": [true, "check-multiline-start"], + "no-redundant-jsdoc": true + } } diff --git a/packages/stark-ui/package.json b/packages/stark-ui/package.json index 6451369988..c489fd4bd3 100644 --- a/packages/stark-ui/package.json +++ b/packages/stark-ui/package.json @@ -51,7 +51,7 @@ "clean:modules": "npx rimraf ./node_modules package-lock.json", "clean:all": "npm run clean && npm run clean:modules", "docs": "node ../../node_modules/@compodoc/compodoc/bin/index-cli src --theme material --tsconfig ../tsconfig.json --output ../../reports/api-docs/stark-ui", - "docs:coverage": "npm run docs -- --coverageTest --coverageThresholdFail true", + "docs:coverage": "npm run docs -- --coverageTest 85 --coverageThresholdFail true", "docs:serve": "npm run docs -- --watch --serve --port 4321", "ngc": "node ../../node_modules/@angular/compiler-cli/src/main.js -p tsconfig-build.json", "lint": "node ../../node_modules/tslint/bin/tslint --config ./tslint.json --project ./tsconfig.spec.json --format codeFrame", diff --git a/packages/stark-ui/src/modules/app-logo/components/app-logo.component.spec.ts b/packages/stark-ui/src/modules/app-logo/components/app-logo.component.spec.ts index 5204185cc2..69918e1485 100644 --- a/packages/stark-ui/src/modules/app-logo/components/app-logo.component.spec.ts +++ b/packages/stark-ui/src/modules/app-logo/components/app-logo.component.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { NO_ERRORS_SCHEMA } from "@angular/core"; import { async, ComponentFixture, TestBed } from "@angular/core/testing"; import { STARK_LOGGING_SERVICE, STARK_ROUTING_SERVICE } from "@nationalbankbelgium/stark-core"; diff --git a/packages/stark-ui/src/modules/app-logo/components/app-logo.component.ts b/packages/stark-ui/src/modules/app-logo/components/app-logo.component.ts index 3444775ae7..dd14fe8c0f 100644 --- a/packages/stark-ui/src/modules/app-logo/components/app-logo.component.ts +++ b/packages/stark-ui/src/modules/app-logo/components/app-logo.component.ts @@ -1,18 +1,11 @@ import { Component, Inject, Input, OnInit, ViewEncapsulation } from "@angular/core"; import { STARK_LOGGING_SERVICE, STARK_ROUTING_SERVICE, StarkLoggingService, StarkRoutingService } from "@nationalbankbelgium/stark-core"; -const componentName: string = "stark-app-logo"; - /** - * @ngdoc component - * @name stark-ui.component:starkAppLogo - * @description Component to display the application's logo - * - * @scope - * @restrict E - * - * @input {object} homeStateParams (optional) Params object to be passed to the UI router state defined as homeState. + * Name of the component */ +const componentName: string = "stark-app-logo"; + // FIXME: tslint rules temporarily disabled. Enable them once we decide the final implementation of component styles /* tslint:disable:enforce-component-selector use-view-encapsulation use-host-property-decorator */ @Component({ @@ -22,9 +15,20 @@ const componentName: string = "stark-app-logo"; host: { class: "stark-app-logo" } }) /* tslint:enable */ +/** + * Component to display the application's logo + */ export class StarkAppLogoComponent implements OnInit { + /** + * Params object to be passed to the UI router state defined as homeState. + */ @Input() public homeStateParams?: { [property: string]: any }; + /** + * Class constructor + * @param logger : the logger of the application + * @param routingService : the routing service of the application + */ public constructor( @Inject(STARK_LOGGING_SERVICE) public logger: StarkLoggingService, @Inject(STARK_ROUTING_SERVICE) public routingService: StarkRoutingService @@ -39,6 +43,10 @@ export class StarkAppLogoComponent implements OnInit { this.logger.debug(componentName + ": controller initialized"); } + /** + * Handles the event when a click is made on the logo + * @param $event: the handled event + */ public logoClickHandler($event: Event): void { // cancel the event otherwise Angular triggers a full page reload :( $event.preventDefault(); diff --git a/packages/stark-ui/testing/public_api.ts b/packages/stark-ui/testing/public_api.ts index 761f64a89d..aa25642a2b 100644 --- a/packages/stark-ui/testing/public_api.ts +++ b/packages/stark-ui/testing/public_api.ts @@ -1,6 +1,4 @@ /** - * @module - * @description * Entry point for all public APIs of this package. */ // FIXME: replace this dummy mock by the actual mocks once implemented => export * from "../src/modules//testing"; diff --git a/packages/stark-ui/tslint.json b/packages/stark-ui/tslint.json index eea5d53c7f..ece321191f 100644 --- a/packages/stark-ui/tslint.json +++ b/packages/stark-ui/tslint.json @@ -1,3 +1,7 @@ { - "extends": ["tslint:latest", "tslint-sonarts", "codelyzer", "tslint-config-prettier", "../stark-build/config/tslint.json"] + "extends": ["tslint:latest", "tslint-sonarts", "codelyzer", "tslint-config-prettier", "../stark-build/config/tslint.json"], + "rules": { + "jsdoc-format": [true, "check-multiline-start"], + "no-redundant-jsdoc": true + } } diff --git a/showcase/README.md b/showcase/README.md index e05fa58911..3e9d8e77fa 100644 --- a/showcase/README.md +++ b/showcase/README.md @@ -60,8 +60,8 @@ This is the showcase of Stark. | | | | en.json # English | | | | fr.json # French | | | \ nl.json # Dutch -| | | -| | \ README.md # +| | | +| | \ README.md # | | | +---assets-base # static assets that will be copied to the root of the application | | | # @@ -70,12 +70,12 @@ This is the showcase of Stark. | | | favicon.ico # icon for bookmarks bar | | | humans.txt # contains information about the website (http://humanstxt.org/) | | | manifest.json # application icons for Android mobile devices -| | | README.md # +| | | README.md # | | | robots.txt # the robots exclusion protocol (http://www.robotstxt.org/) -| | \ service-worker.js # support for building Progressive Web Applications (PWA) with Service Workers +| | \ service-worker.js # support for building Progressive Web Applications (PWA) with Service Workers | | | +---environments # configuration variables for each environment -| | | # +| | | # | | | environment.e2e.prod.ts # e2e tests configuration | | | environment.hmr.ts # development with HMR (Hot Module Replacement) configuration | | | environment.prod.ts # production configuration @@ -92,7 +92,7 @@ This is the showcase of Stark. | | polyfills.browser.ts # this file includes polyfills needed by Angular and should be loaded before the app | | stark-app-config.json # Stark configuration | \ stark-app-metadata.json # Application metadata like: name, description, version... -| +| | .dockerignore # files and directories to be excluded by the Docker build | .gitignore # files and directories to be excluded by git | .prettierignore # files and directories to be excluded by prettier @@ -104,7 +104,7 @@ This is the showcase of Stark. | Dockerfile # the commands that will be executed by the Docker Build command | karma.conf.ci.js # Karma configuration file for Continuous Integration | karma.conf.js # Karma configuration file -| package.json # +| package.json # | protractor.conf.js # protractor configuration file | README.md # this document | tsconfig.app.json # typescript configuration for the application, extends tsconfig.json diff --git a/showcase/src/app/app.component.spec.ts b/showcase/src/app/app.component.spec.ts index 5fc56ff09b..67c76c4ec2 100644 --- a/showcase/src/app/app.component.spec.ts +++ b/showcase/src/app/app.component.spec.ts @@ -1,3 +1,4 @@ +/* tslint:disable:completed-docs*/ import { NO_ERRORS_SCHEMA } from "@angular/core"; import { async, TestBed, ComponentFixture } from "@angular/core/testing"; diff --git a/showcase/src/app/home/home.component.spec.ts b/showcase/src/app/home/home.component.spec.ts index 50d2c5e157..bbc7f276c4 100644 --- a/showcase/src/app/home/home.component.spec.ts +++ b/showcase/src/app/home/home.component.spec.ts @@ -1,3 +1,4 @@ +/* tslint:disable:completed-docs */ import { NO_ERRORS_SCHEMA } from "@angular/core"; import { async, ComponentFixture, TestBed } from "@angular/core/testing"; import { HttpClientTestingModule } from "@angular/common/http/testing"; diff --git a/starter/README.md b/starter/README.md index bd87723582..fdb2d10a08 100644 --- a/starter/README.md +++ b/starter/README.md @@ -60,8 +60,8 @@ This is the project template for Stark applications. | | | | en.json # English | | | | fr.json # French | | | \ nl.json # Dutch -| | | -| | \ README.md # +| | | +| | \ README.md # | | | +---assets-base # static assets that will be copied to the root of the application | | | # @@ -70,12 +70,12 @@ This is the project template for Stark applications. | | | favicon.ico # icon for bookmarks bar | | | humans.txt # contains information about the website (http://humanstxt.org/) | | | manifest.json # application icons for Android mobile devices -| | | README.md # +| | | README.md # | | | robots.txt # the robots exclusion protocol (http://www.robotstxt.org/) -| | \ service-worker.js # support for building Progressive Web Applications (PWA) with Service Workers +| | \ service-worker.js # support for building Progressive Web Applications (PWA) with Service Workers | | | +---environments # configuration variables for each environment -| | | # +| | | # | | | environment.e2e.prod.ts # e2e tests configuration | | | environment.hmr.ts # development with HMR (Hot Module Replacement) configuration | | | environment.prod.ts # production configuration @@ -92,7 +92,7 @@ This is the project template for Stark applications. | | polyfills.browser.ts # this file includes polyfills needed by Angular and should be loaded before the app | | stark-app-config.json # Stark configuration | \ stark-app-metadata.json # Application metadata like: name, description, version... -| +| | .dockerignore # files and directories to be excluded by the Docker build | .gitignore # files and directories to be excluded by git | .prettierignore # files and directories to be excluded by prettier @@ -104,7 +104,7 @@ This is the project template for Stark applications. | Dockerfile # the commands that will be executed by the Docker Build command | karma.conf.ci.js # Karma configuration file for Continuous Integration | karma.conf.js # Karma configuration file -| package.json # +| package.json # | protractor.conf.js # protractor configuration file | README.md # this document | tsconfig.app.json # typescript configuration for the application, extends tsconfig.json diff --git a/starter/package.json b/starter/package.json index 7dd87039b2..e67086e253 100644 --- a/starter/package.json +++ b/starter/package.json @@ -51,7 +51,7 @@ "docker": "docker", "docs": "npm run docs:clean && compodoc src --theme material --tsconfig ./tsconfig.json --output ./reports/api-docs", "docs:clean": "npx rimraf reports/api-docs", - "docs:coverage": "npm run docs -- --coverageTest --coverageThresholdFail true", + "docs:coverage": "npm run docs -- --coverageTest 85 --coverageThresholdFail true", "docs:serve": "npm run docs -- --watch --serve --port 4321", "e2e:live": "npm-run-all -p -r server:prod:ci protractor:live", "e2e:travis": "npm-run-all -p -r server:prod:ci protractor:delay", diff --git a/starter/src/app/about/about.component.spec.ts b/starter/src/app/about/about.component.spec.ts index ee9d647e5a..6cb337553a 100644 --- a/starter/src/app/about/about.component.spec.ts +++ b/starter/src/app/about/about.component.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { ActivatedRoute, Data } from "@angular/router"; import { inject, TestBed } from "@angular/core/testing"; import { StoreModule } from "@ngrx/store"; diff --git a/starter/src/app/about/about.component.ts b/starter/src/app/about/about.component.ts index c7e3377e59..114a6d1332 100644 --- a/starter/src/app/about/about.component.ts +++ b/starter/src/app/about/about.component.ts @@ -1,18 +1,35 @@ import { Component, Inject, Input, OnInit } from "@angular/core"; import { Observable } from "rxjs"; import { StarkLoggingService, STARK_LOGGING_SERVICE } from "@nationalbankbelgium/stark-core"; - +/** + * @ignore + */ @Component({ selector: "about", styles: [``], templateUrl: "./about.component.html" }) +/** + * @ignore + */ export class AboutComponent implements OnInit { + /** + * @ignore + */ @Input() public resolvedData: Observable; + /** + * @ignore + */ @Input() public paramData: any; + /** + * @ignore + */ public constructor(@Inject(STARK_LOGGING_SERVICE) public loggingService: StarkLoggingService) {} + /** + * Triggered on the component's initialization + */ public ngOnInit(): void { this.loggingService.debug("hello from the `About` component"); } diff --git a/starter/src/app/app.component.spec.ts b/starter/src/app/app.component.spec.ts index 95b7517b4b..47e3ced1d2 100644 --- a/starter/src/app/app.component.spec.ts +++ b/starter/src/app/app.component.spec.ts @@ -1,3 +1,4 @@ +/*tslint:disable:completed-docs*/ import { NO_ERRORS_SCHEMA } from "@angular/core"; import { async, ComponentFixture, TestBed } from "@angular/core/testing"; diff --git a/starter/src/app/app.component.ts b/starter/src/app/app.component.ts index d2e90e4699..b412078734 100644 --- a/starter/src/app/app.component.ts +++ b/starter/src/app/app.component.ts @@ -15,25 +15,32 @@ import { AppState } from "./app.service"; styleUrls: ["./app.component.css"], templateUrl: "./app.component.html" }) +/** + * AppComponent file + */ export class AppComponent implements OnInit { + /** + * Name of the project + */ public name: string = "Stark Starter"; + /** + * Url of the project + */ public url: string = "https://github.com/NationalBankBelgium/stark"; + /** + * The application state + */ public appState: AppState; public constructor(appState: AppState) { this.appState = appState; } + /** + * Triggered on the component's initialization + */ public ngOnInit(): void { console.log("Initial App State", this.appState.state); } } - -/** - * Please review the https://github.com/AngularClass/angular2-examples/ repo for - * more angular app examples that you may copy/paste - * (The examples may not be updated as quickly. Please open an issue on github for us to update it) - * For help or questions please contact us at @AngularClass on twitter - * or our chat on Slack at https://AngularClass.com/slack-join - */ diff --git a/starter/src/app/app.module.ts b/starter/src/app/app.module.ts index e035bad044..5d60dea875 100644 --- a/starter/src/app/app.module.ts +++ b/starter/src/app/app.module.ts @@ -57,13 +57,25 @@ import "../styles/styles.scss"; /* tslint:enable */ import "../styles/headings.css"; -// Application wide providers +/** + * Application wide providers + */ const APP_PROVIDERS: any[] = [AppState]; // TODO: where to put this factory function? +/** + * This method will create, configure and return a new StarkApplicationConfig instance + * @returns the Stark Application config + */ export function starkAppConfigFactory(): StarkApplicationConfig { + /** + * The needed configuration for the application config + */ const config: any = require("../stark-app-config.json"); + /** + * This instance will contain data added by the developer but also data retrieved from the configuration file + */ const applicationConfig: StarkApplicationConfig = Deserialize(config, StarkApplicationConfigImpl); applicationConfig.rootStateUrl = "home"; @@ -78,13 +90,24 @@ export function starkAppConfigFactory(): StarkApplicationConfig { } // TODO: where to put this factory function? +/** + * This method will create, configure and return a new StarkApplicationMetadata instance + * @returns the Stark Application Metadata + */ export function starkAppMetadataFactory(): StarkApplicationMetadata { + /** + * The needed configuration for the metadata + */ const metadata: any = require("../stark-app-metadata.json"); return Deserialize(metadata, StarkApplicationMetadataImpl); } // TODO: where to put this factory function? +/** + * This method can be used to create and retrieve mock data + * @returns StarkMockData + */ export function starkMockDataFactory(): StarkMockData { return { whatever: "dummy prop", @@ -92,20 +115,31 @@ export function starkMockDataFactory(): StarkMockData { }; } -// Application Redux State +/** + * Application Redux State + */ export interface State { // reducer interfaces } +/** + * Reducers configured for a Map of Actions + */ export const reducers: ActionReducerMap = { // reducers }; +/** + * Logging function from @ngrx/store applications + */ export function logger(reducer: ActionReducer): any { // default, no options return storeLogger()(reducer); } +/** + * Set of meta-reducer, higher order reducer (i.e., functions) + */ export const metaReducers: MetaReducer[] = !environment.production ? [logger, storeFreeze] : []; /** @@ -151,6 +185,9 @@ export const metaReducers: MetaReducer[] = !environment.production ? [log { provide: STARK_MOCK_DATA, useFactory: starkMockDataFactory } ] }) +/** + * @ignore + */ export class AppModule { public constructor( private translateService: TranslateService, diff --git a/starter/src/app/app.routes.ts b/starter/src/app/app.routes.ts index f259902498..170344feec 100644 --- a/starter/src/app/app.routes.ts +++ b/starter/src/app/app.routes.ts @@ -3,6 +3,9 @@ import { AboutComponent } from "./about"; import { NoContentComponent } from "./no-content"; import { Ng2StateDeclaration } from "@uirouter/angular"; +/** + * Definition of all states of an application. + */ export const APP_STATES: Ng2StateDeclaration[] = [ { name: "index", url: "/", component: HomeComponent }, { name: "home", url: "/home", component: HomeComponent }, diff --git a/starter/src/app/app.service.ts b/starter/src/app/app.service.ts index 3927d86410..598c7d0db0 100644 --- a/starter/src/app/app.service.ts +++ b/starter/src/app/app.service.ts @@ -1,11 +1,19 @@ import { Injectable } from "@angular/core"; - +/** + * @ignore + */ export interface InternalStateType { [key: string]: any; } @Injectable() +/** + * @ignore + */ export class AppState { + /** + * @ignore + */ public _state: InternalStateType = {}; /** @@ -21,6 +29,9 @@ export class AppState { throw new Error("do not mutate the `.state` directly" + value); } + /** + * @ignore + */ public get(prop?: any): any { /** * Use our state getter for the clone. @@ -29,6 +40,9 @@ export class AppState { return state.hasOwnProperty(prop) ? state[prop] : state; } + /** + * @ignore + */ public set(prop: string, value: any): any { /** * Internally mutate our state. @@ -36,6 +50,9 @@ export class AppState { return (this._state[prop] = value); } + /** + * @ignore + */ private _clone(object: InternalStateType): any { /** * Simple object clone. diff --git a/starter/src/app/home/home.component.ts b/starter/src/app/home/home.component.ts index e224ced74c..121fc01f6c 100644 --- a/starter/src/app/home/home.component.ts +++ b/starter/src/app/home/home.component.ts @@ -1,15 +1,26 @@ import { Component, Inject, OnInit } from "@angular/core"; import { STARK_LOGGING_SERVICE, StarkLoggingService } from "@nationalbankbelgium/stark-core"; - +/** + * @ignore + */ @Component({ selector: "home", // providers: [], styleUrls: ["./home.component.pcss"], templateUrl: "./home.component.html" }) +/** + * @ignore + */ export class HomeComponent implements OnInit { + /** + * @ignore + */ public constructor(@Inject(STARK_LOGGING_SERVICE) public loggingService: StarkLoggingService) {} + /** + * Triggered at home component's initialization + */ public ngOnInit(): void { this.loggingService.debug("Hello from the `Home` component"); } diff --git a/starter/src/app/no-content/no-content.component.ts b/starter/src/app/no-content/no-content.component.ts index d9a895a584..c0dc8bbe86 100644 --- a/starter/src/app/no-content/no-content.component.ts +++ b/starter/src/app/no-content/no-content.component.ts @@ -1,9 +1,14 @@ import { Component } from "@angular/core"; - +/** + * @ignore + */ @Component({ selector: "no-content", template: `

404: page missing

` }) +/** + * @ignore + */ export class NoContentComponent {} diff --git a/starter/src/app/router.config.ts b/starter/src/app/router.config.ts index 2563640c60..5dfd3f7dd1 100644 --- a/starter/src/app/router.config.ts +++ b/starter/src/app/router.config.ts @@ -1,6 +1,10 @@ import { UIRouter, Category, StateDeclaration } from "@uirouter/core"; import { Visualizer } from "@uirouter/visualizer"; +/** + * This method will log all registered states of the application + * @param registeredstates: a set of registered states + */ function logRegisteredStates(registeredstates: StateDeclaration[]): void { let message: string = "============= Registered Ui-Router states: ==============\n"; @@ -16,6 +20,10 @@ function logRegisteredStates(registeredstates: StateDeclaration[]): void { console.log(message); } +/** + * @ignore + * @param router - the router to configure + */ export function routerConfigFn(router: UIRouter): void { router.trace.enable(Category.TRANSITION); @@ -25,6 +33,9 @@ export function routerConfigFn(router: UIRouter): void { logRegisteredStates(router.stateService.get()); } +/** + * @ignore + */ export function routerChildConfigFn(router: UIRouter): void { logRegisteredStates(router.stateService.get()); } diff --git a/starter/src/app/translation.config.ts b/starter/src/app/translation.config.ts index 2672e9f998..49da533b7f 100644 --- a/starter/src/app/translation.config.ts +++ b/starter/src/app/translation.config.ts @@ -1,17 +1,42 @@ import { TranslateService } from "@ngx-translate/core"; import { mergeTranslations, StarkLocale } from "@nationalbankbelgium/stark-core"; +/** + * This object will contain all English translation for the application + */ const translationsEn: object = require("../assets/translations/en.json"); +/** + * This object will contain all French translation for the application + */ const translationsFr: object = require("../assets/translations/fr.json"); +/** + * This object will contain all Dutch translation for the application + */ const translationsNl: object = require("../assets/translations/nl.json"); +/** + * Method that will initialize the translation of the application + * @param translateService: the translation service is use + */ export function initializeTranslation(translateService: TranslateService): void { translateService.addLangs(["en", "fr", "nl"]); translateService.setDefaultLang("en"); translateService.use("nl"); + /** + * The English StarkLocale, composed of the "en" language code + * and an object that retrieves all the English translations for the application in a json file + */ const english: StarkLocale = { languageCode: "en", translations: translationsEn }; + /** + * The French StarkLocale, composed of the "fr" language code + * and an object that retrieves all the French translations for the application in a json file + */ const french: StarkLocale = { languageCode: "fr", translations: translationsFr }; + /** + * The Dutch StarkLocale, composed of the "nl" language code + * and an object that retrieves all the Dutch translations for the application in a json file + */ const dutch: StarkLocale = { languageCode: "nl", translations: translationsNl }; mergeTranslations(translateService, english, french, dutch); diff --git a/starter/src/environments/environment.e2e.prod.ts b/starter/src/environments/environment.e2e.prod.ts index 0f44c2b97e..29d63463c2 100644 --- a/starter/src/environments/environment.e2e.prod.ts +++ b/starter/src/environments/environment.e2e.prod.ts @@ -4,14 +4,17 @@ import { Environment } from "./model"; enableProdMode(); +/** + * @ignore + */ export const environment: Environment = { production: true, hmr: false, - /** Angular debug tools in the dev console + /** + * Angular debug tools in the dev console * https://github.com/angular/angular/blob/86405345b781a9dc2438c0fbe3e9409245647019/TOOLS_JS.md - * @param modRef - * + * @param modRef - the module ref to decorate */ decorateModuleRef(modRef: NgModuleRef): NgModuleRef { disableDebugTools(); diff --git a/starter/src/environments/environment.hmr.ts b/starter/src/environments/environment.hmr.ts index dceab97e76..90466af558 100644 --- a/starter/src/environments/environment.hmr.ts +++ b/starter/src/environments/environment.hmr.ts @@ -7,14 +7,17 @@ import { Environment } from "./model"; Error.stackTraceLimit = Infinity; require("zone.js/dist/long-stack-trace-zone"); +/** + * @ignore + */ export const environment: Environment = { production: false, hmr: true, - /** Angular debug tools in the dev console + /** + * Angular debug tools in the dev console * https://github.com/angular/angular/blob/86405345b781a9dc2438c0fbe3e9409245647019/TOOLS_JS.md - * @param modRef - * + * @param modRef - the module ref to decorate */ decorateModuleRef(modRef: NgModuleRef): NgModuleRef { const appRef: ApplicationRef = modRef.injector.get(ApplicationRef); diff --git a/starter/src/environments/environment.prod.ts b/starter/src/environments/environment.prod.ts index 0f44c2b97e..41e802c004 100644 --- a/starter/src/environments/environment.prod.ts +++ b/starter/src/environments/environment.prod.ts @@ -4,13 +4,17 @@ import { Environment } from "./model"; enableProdMode(); +/** + * @ignore + */ export const environment: Environment = { production: true, hmr: false, - /** Angular debug tools in the dev console + /** + * Angular debug tools in the dev console * https://github.com/angular/angular/blob/86405345b781a9dc2438c0fbe3e9409245647019/TOOLS_JS.md - * @param modRef + * @param modRef - the module ref to decorate * */ decorateModuleRef(modRef: NgModuleRef): NgModuleRef { diff --git a/starter/src/environments/environment.ts b/starter/src/environments/environment.ts index 54f289d904..e48643b0a5 100644 --- a/starter/src/environments/environment.ts +++ b/starter/src/environments/environment.ts @@ -7,13 +7,17 @@ import { Environment } from "./model"; Error.stackTraceLimit = Infinity; require("zone.js/dist/long-stack-trace-zone"); +/** + * @ignore + */ export const environment: Environment = { production: false, hmr: false, - /** Angular debug tools in the dev console + /** + * Angular debug tools in the dev console * https://github.com/angular/angular/blob/86405345b781a9dc2438c0fbe3e9409245647019/TOOLS_JS.md - * @param modRef + * @param modRef - the module ref to decorate */ decorateModuleRef(modRef: NgModuleRef): NgModuleRef { const appRef: ApplicationRef = modRef.injector.get(ApplicationRef); diff --git a/starter/src/environments/model.ts b/starter/src/environments/model.ts index 547fb293c7..c998b81e7d 100644 --- a/starter/src/environments/model.ts +++ b/starter/src/environments/model.ts @@ -1,8 +1,23 @@ import { NgModuleRef } from "@angular/core"; +/** + * Interface implemented by all environments + */ export interface Environment { + /** + * @ignore + */ production: boolean; + /** + * @ignore + */ hmr: boolean; + /** + * @ignore + */ ENV_PROVIDERS: any; + /** + * @ignore + */ decorateModuleRef(modRef: NgModuleRef): NgModuleRef; } diff --git a/starter/src/hmr.ts b/starter/src/hmr.ts index b36d9f86bb..193884bbd3 100644 --- a/starter/src/hmr.ts +++ b/starter/src/hmr.ts @@ -4,6 +4,9 @@ import { NgModuleRef, ApplicationRef, ComponentRef } from "@angular/core"; import { createNewHosts } from "@angularclass/hmr"; +/** + * @ignore + */ export const hmrBootstrap: any = (module: any, bootstrap: () => Promise>) => { let ngModule: NgModuleRef; module.hot.accept(); diff --git a/starter/src/main.browser.ts b/starter/src/main.browser.ts index 29ad703ba9..0347178f45 100644 --- a/starter/src/main.browser.ts +++ b/starter/src/main.browser.ts @@ -43,6 +43,9 @@ switch (document.readyState) { } } +/** + * @ignore + */ function _domReadyHandler(): void { document.removeEventListener("DOMContentLoaded", _domReadyHandler, false); if (environment.hmr) { diff --git a/starter/tslint.json b/starter/tslint.json index 8198deafd1..cdd1a8e9e2 100644 --- a/starter/tslint.json +++ b/starter/tslint.json @@ -8,6 +8,8 @@ ], "rules": { "component-selector": false, - "no-unused-variable": false // FIXME: disabled due to false positives in imports. Re-enable once these are solved in a newer version of TSLint + "no-unused-variable": false, // FIXME: disabled due to false positives in imports. Re-enable once these are solved in a newer version of TSLint + "jsdoc-format": [true, "check-multiline-start"], + "no-redundant-jsdoc": true } } diff --git a/tslint.json b/tslint.json index a6413d40d9..38a180d7b0 100644 --- a/tslint.json +++ b/tslint.json @@ -1,6 +1,31 @@ { "extends": ["tslint:latest", "tslint-sonarts", "codelyzer", "tslint-config-prettier", "./packages/stark-build/config/tslint.json"], "rules": { - "component-selector": false + "component-selector": false, + "completed-docs": [ + true, + { + "enums": true, + "variables": { + "tags": { "existence": ["ignore", "link", "param", "returns"] } + }, + "functions": { + "tags": { "existence": ["ignore", "link", "param", "returns"] } + }, + "interfaces": { + "tags": { "existence": ["ignore", "link", "param", "returns"] }, + "visibilities": ["exported", "internal"] + }, + "classes": { + "tags": { "existence": ["ignore", "link", "param", "returns"] }, + "visibilities": ["internal"] + }, + "methods": { + "tags": { "existence": ["ignore", "link", "param", "returns"] } + } + } + ], + "jsdoc-format": [true, "check-multiline-start"], + "no-redundant-jsdoc": true } }