diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..b50dc041 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,45 @@ +# Contributing to `@openstapps/core` + +Please see the appropriate general group contributing guides in [project-management](https://gitlab.com/openstapps/projectmanagement/tree/master/project-docs/workflow). + +## Additional coding style + +### Extract inline type definitions + +For consistency and correct functionality of `core-tools` we need well-defined type assignments. + +Type assignments shall always be primitive types, classes, interfaces, enums or unions. Not allowed are inline type-definitions. Those shall be refactored accordingly: + +```typescript +export interface SCPlaceWithoutReferences extends SCThing { + ... + // Use this: + geo: SCGeoInformation; + + // Instead of: + geo: { + point: Point, + polygon?: Polygon, + }; +} +``` + +### Reuse the map structure + +If you come around a map-like-type use `SCMap`. + +```typescript +// Use this: +interface AnyClass{ + inventory: SCMap; +} + +// Instead of: +interface AnyClass{ + inventory?: Array<{ key: string, value: number }>; +} +// or instead of +interface AnyClass{ + inventory?: { [key: string]: number }; +} +``` diff --git a/src/core/Route.ts b/src/core/Route.ts index eed4550c..cf182737 100644 --- a/src/core/Route.ts +++ b/src/core/Route.ts @@ -33,6 +33,7 @@ import {SCSearchRequest} from './protocol/routes/search/SearchRequest'; import {SCSearchResponse} from './protocol/routes/search/SearchResponse'; import {SCThingUpdateRequest} from './protocol/routes/TYPE/UID/ThingUpdateRequest'; import {SCThingUpdateResponse} from './protocol/routes/TYPE/UID/ThingUpdateResponse'; +import {SCMap} from './types/Map'; export type SCRouteHttpVerbs = 'GET' | 'POST' | 'PUT'; @@ -53,7 +54,7 @@ export interface SCRoute { /** * Map of obligatory parameters and their type that have to be set via the requested path */ - obligatoryParameters?: { [k: string]: string }; + obligatoryParameters?: SCMap; /** * Name of the type of the request body @@ -84,13 +85,13 @@ export abstract class SCAbstractRoute implements SCRoute { 'SCErrorResponse', ]; method: SCRouteHttpVerbs = 'GET'; - obligatoryParameters?: { [k: string]: string }; + obligatoryParameters?: SCMap; requestBodyName = 'any'; responseBodyName = 'any'; statusCodeSuccess = 200; urlFragment = '/'; - public getUrlFragment(parameters?: { [k: string]: string }): string { + public getUrlFragment(parameters?: SCMap): string { if (typeof parameters === 'undefined') { parameters = {}; } diff --git a/src/core/Thing.ts b/src/core/Thing.ts index 8a204dce..4b393bee 100644 --- a/src/core/Thing.ts +++ b/src/core/Thing.ts @@ -315,10 +315,15 @@ export interface SCThingTranslatableProperties { /** * Origin of the thing */ - origin?: { - /** - * Translation of the name of the origin of the thing - */ - name: string; - }; + origin?: SCThingTranslatablePropertyOrigin; +} + +/** + * Translatable property of an origin + */ +export interface SCThingTranslatablePropertyOrigin { + /** + * Translation of the name of the origin + */ + name: string; } diff --git a/src/core/base/Place.ts b/src/core/base/Place.ts index 85cb17a8..db747759 100644 --- a/src/core/base/Place.ts +++ b/src/core/base/Place.ts @@ -12,8 +12,8 @@ * You should have received a copy of the GNU General Public License along with * this program. If not, see . */ -import {Point, Polygon} from 'geojson'; import {SCThing} from '../Thing'; +import {SCGeoInformation} from '../types/GeoInformation'; import {SCPostalAddress} from '../types/PostalAddress'; /** @@ -26,15 +26,12 @@ export interface SCPlaceWithoutReferences extends SCThing { address?: SCPostalAddress; /** - * Position/shape of the place + * Positional information of the place * * !!! BEWARE !!! * Can not be a GeometryCollection because ElasticSearch does not allow distance filtering/sorting on other types */ - geo: { - point: Point, - polygon?: Polygon, - }; + geo: SCGeoInformation; /** * Opening hours of the place diff --git a/src/core/base/ThingWithCategories.ts b/src/core/base/ThingWithCategories.ts index d20f0590..f356e181 100644 --- a/src/core/base/ThingWithCategories.ts +++ b/src/core/base/ThingWithCategories.ts @@ -14,6 +14,7 @@ */ import {SCThing, SCThingTranslatableProperties} from '../Thing'; import {SCTranslations} from '../types/i18n'; +import {SCMap} from '../types/Map'; /** * A thing without references with categories @@ -33,13 +34,8 @@ export interface SCThingWithCategoriesWithoutReferences; /** * Translated fields of a thing with categories diff --git a/src/core/protocol/routes/feedback/FeedbackRequest.ts b/src/core/protocol/routes/feedback/FeedbackRequest.ts index f9b7196d..238833ad 100644 --- a/src/core/protocol/routes/feedback/FeedbackRequest.ts +++ b/src/core/protocol/routes/feedback/FeedbackRequest.ts @@ -24,42 +24,7 @@ export interface SCFeedbackRequest extends SCMessage { /** * Meta data that helps to understand the feedback */ - metaData: { - /** - * Whether or not the user enabled the debug mode - */ - debug?: boolean; - - /** - * Platform identifier - */ - platform: string; - - /** - * Scope/app state at feedback invocation - */ - scope: any; - - /** - * Whether or not the feedback is sendable - */ - sendable?: boolean; - - /** - * App state that feedback was invoked from - */ - state: any; - - /** - * User agent - */ - userAgent: string; - - /** - * StApps version string - */ - version: string; - }; + metaData: SCFeedbackRequestMetaData; } /** @@ -82,3 +47,43 @@ export class SCFeedbackRoute extends SCAbstractRoute { this.urlFragment = '/feedback'; } } + +/** + * Request Meta Data + */ +export interface SCFeedbackRequestMetaData { + /** + * Whether or not the user enabled the debug mode + */ + debug?: boolean; + + /** + * Platform identifier + */ + platform: string; + + /** + * Scope/app state at feedback invocation + */ + scope: any; + + /** + * Whether or not the feedback is sendable + */ + sendable?: boolean; + + /** + * App state that feedback was invoked from + */ + state: any; + + /** + * User agent + */ + userAgent: string; + + /** + * StApps version string + */ + version: string; +} diff --git a/src/core/protocol/routes/search/SearchResponse.ts b/src/core/protocol/routes/search/SearchResponse.ts index 2717996a..93f48b21 100644 --- a/src/core/protocol/routes/search/SearchResponse.ts +++ b/src/core/protocol/routes/search/SearchResponse.ts @@ -13,6 +13,7 @@ * this program. If not, see . */ import {SCThings, SCThingsField} from '../../../Classes'; +import {SCMap} from '../../../types/Map'; /** * A search response @@ -39,32 +40,12 @@ export interface SCSearchResult { /** * Pagination information */ - pagination: { - /** - * Count of given data. Same as data.length - */ - count: number; - - /** - * Offset of data on all matching data. Given by [[SCSearchQuery.from]] - */ - offset: number; - - /** - * Number of total matching data - */ - total: number - }; + pagination: SCSearchResponsePagination; /** * Stats of the search engine */ - stats: { - /** - * Response time of the search engine in ms - */ - time: number; - }; + stats: SCSearchResponseSearchEngineStats; } /** @@ -74,15 +55,40 @@ export interface SCFacet { /** * Values for the aggregation */ - buckets: Array<{ - /** - * One value with its number of occurrences - */ - [key: string]: number; - }>; + buckets: Array>; /** * Field of the aggregation */ field: SCThingsField; } + +/** + * Stores information about Pagination + */ +export interface SCSearchResponsePagination { + /** + * Count of given data. Same as data.length + */ + count: number; + + /** + * Offset of data on all matching data. Given by [[SCSearchQuery.from]] + */ + offset: number; + + /** + * Number of total matching data + */ + total: number; +} + +/** + * Statistics of search engine + */ +export interface SCSearchResponseSearchEngineStats { + /** + * Response time of the search engine in ms + */ + time: number; +} diff --git a/src/core/things/Room.ts b/src/core/things/Room.ts index 6cbe26f3..498ca740 100644 --- a/src/core/things/Room.ts +++ b/src/core/things/Room.ts @@ -22,6 +22,7 @@ import { } from '../base/ThingWithCategories'; import {SCThingMeta, SCThingType} from '../Thing'; import {SCTranslations} from '../types/i18n'; +import {SCMap} from '../types/Map'; /** * Categories of a room @@ -53,7 +54,7 @@ export interface SCRoomWithoutReferences /** * The inventory of the place/room as a list of items and their quantity. */ - inventory?: Array<{ key: string, value: number }>; + inventory?: SCMap; /** * Translations of specific values of the object diff --git a/src/core/things/Tour.ts b/src/core/things/Tour.ts index 992a3650..3d57ef40 100644 --- a/src/core/things/Tour.ts +++ b/src/core/things/Tour.ts @@ -97,11 +97,7 @@ export interface SCTourStepTooltip { /** * How the step shall be resolved */ - resolved?: { element: string } | { event: string } | { location: { is: string } | { match: string } } | { - menu: - 'open-left' - | 'open-right'; - }; + resolved?: SCTourResolvedElement | SCTourResolvedEvent | SCTourResolvedLocation | SCTourResolvedMenu; /** * Text that the tooltip shall contain @@ -138,3 +134,63 @@ export interface SCTourStepMenu { */ type: 'menu'; } + +/** + * Tour step resolved by an element + */ +export interface SCTourResolvedElement { + /** + * Element name + */ + element: string; +} + +/** + * Tour step resolved by an event + */ +export interface SCTourResolvedEvent { + /** + * Event name + */ + event: string; +} + +/** + * Tour step resolved by a location + */ +export interface SCTourResolvedLocation { + /** + * Matching location + */ + location: SCTourResolvedLocationTypeIs | SCTourResolvedLocationTypeMatch; +} + +/** + * Tour step resolved by a location for a specific location + */ +export interface SCTourResolvedLocationTypeIs { + /** + * Specific location name + */ + is: string; +} + +/** + * Tour step resolved by a location for a specific location + */ +export interface SCTourResolvedLocationTypeMatch { + /** + * Regex location name + */ + match: string; +} + +/** + * Tour step resolved by interacting with a menu + */ +export interface SCTourResolvedMenu { + /** + * Menu location + */ + menu: 'open-left' | 'open-right'; +} diff --git a/src/core/types/GeoInformation.ts b/src/core/types/GeoInformation.ts new file mode 100644 index 00000000..98f2876f --- /dev/null +++ b/src/core/types/GeoInformation.ts @@ -0,0 +1,29 @@ +/* + * Copyright (C) 2018-2019 StApps + * This program is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, version 3. + * + * This program is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this program. If not, see . + */ +import {Point, Polygon} from 'geojson'; + +/** + * Positional information + */ +export interface SCGeoInformation { + /** + * Center point of a place + */ + point: Point; + /** + * Shape of a place + */ + polygon?: Polygon; +} diff --git a/src/core/types/Map.ts b/src/core/types/Map.ts new file mode 100644 index 00000000..62220b8a --- /dev/null +++ b/src/core/types/Map.ts @@ -0,0 +1,29 @@ +/* + * Copyright (C) 2018-2019 StApps + * This program is free software: you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by the Free + * Software Foundation, version 3. + * + * This program is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for + * more details. + * + * You should have received a copy of the GNU General Public License along with + * this program. If not, see . + */ + +/** + * Capsulation for a map with a string as key with values of type `T` + * + * !!! BEWARE !!! + * Can't be refactored to a `Map`, because it can't be serialized via JSON.stringify(map) + * + * @typeparam T Can be any type. + */ +export interface SCMap { + /** + * One value for each key + */ + [key: string]: T; +} diff --git a/src/core/types/config/App.ts b/src/core/types/config/App.ts index e0856e2d..85bf4cac 100644 --- a/src/core/types/config/App.ts +++ b/src/core/types/config/App.ts @@ -38,7 +38,7 @@ export interface SCAppConfigurationMenuItem { /** * Translations for the menu item */ - translations: SCTranslations<{ title: string }>; + translations: SCTranslations; } /** @@ -72,7 +72,7 @@ export interface SCAppConfigurationMenuCategory { /** * Translations for the menu category */ - translations: SCTranslations<{ name: string }>; + translations: SCTranslations; } /** @@ -87,9 +87,7 @@ export interface SCAppConfiguration { /** * A list of features to en- or disable */ - features: { - widgets: boolean; - }; + features: SCAppConfigurationFeature; /** * A URL where images are available @@ -119,14 +117,58 @@ export interface SCAppConfiguration { /** * Map of store URLs */ - storeUrl?: { - android?: string; - ios?: string; - uwp?: string; - }; + storeUrl?: SCAppConfigurationStoreUrl; /** * URL where a web instance of the app is available */ url?: string; } + +/** + * + */ +export interface SCAppConfigurationFeature { + /** + * + */ + widgets: boolean; +} + +/** + * URLs of published apps + */ +export interface SCAppConfigurationStoreUrl { + /** + * Google Play Store URL + */ + android?: string; + /** + * Apple App Store URL + */ + ios?: string; + /** + * Microsoft Store URL + */ + uwp?: string; +} + +/** + * Translatable property of a menu item + */ +export interface SCAppConfigurationMenuItemTranslationTitle { + /** + * Translation of the title of a menu item + */ + title: string; +} + +/** + * Translatable property of a menu category + */ +export interface SCAppConfigurationMenuCategoryTranslationName { + /** + * Translation of the name of a menu category + */ + name: string; +} diff --git a/src/core/types/config/Backend.ts b/src/core/types/config/Backend.ts index 0373e2fd..1ff9fd15 100644 --- a/src/core/types/config/Backend.ts +++ b/src/core/types/config/Backend.ts @@ -15,6 +15,7 @@ import {SCThingType} from '../../Thing'; import {SCSearchSortType} from '../sorts/Abstract'; import {SCUuid} from '../UUID'; +import {SCMap} from './../Map'; import {SCMonitoringConfiguration} from './Monitoring'; /** @@ -25,7 +26,7 @@ export interface SCBackendConfiguration { * A list of hidden SC types * * If a type is hidden it won't show in any result unless the type is filtered for - * + * */ hiddenTypes: SCThingType[]; @@ -61,7 +62,7 @@ export interface SCBackendConfigurationSortableField { /** * A list of SC types on which this field exists - * + * * If no type is given it is assumed it exists on every type */ onlyOnTypes?: SCThingType[]; @@ -98,15 +99,10 @@ export interface SCBackendConfigurationSearchBoosting { /** * Fields of this type that should be boosted if they match a given value + * + * For nest fields you can use the `.` as a separator. For example `academicTerms.acronym` */ - fields?: { - /** - * Field name which has to match a given value - * - * For nest fields you can use the `.` as a separator. For example `academicTerms.acronym` - */ - [fieldName: string]: SCBackendConfigurationSearchBoostingValues; - }; + fields?: SCMap; /** * Type of things the factor should be applied to @@ -151,20 +147,25 @@ export interface SCBackendInternalConfiguration { /** * Configuration of the database */ - database?: { - /** - * A name of the database to select which one is used by the backend - */ - name: string; - - /** - * Allow additional configuration for the database - */ - [key: string]: any; - }; + database?: SCBackendConfigurationDatabaseConfiguration; /** * Configuration for monitoring */ monitoring?: SCMonitoringConfiguration; } + +/** + * Configuration of the database + */ +export interface SCBackendConfigurationDatabaseConfiguration { + /** + * Name of the database used by the backend + */ + name: string; + + /** + * Allow additional configuration for the database + */ + [key: string]: any; +}