refactor: extract inline type definitions

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<T>`.
+
+```typescript
+// Use this:
+interface AnyClass{
+    inventory: SCMap<number>;
+}
+
+// Instead of:
+interface AnyClass{
+    inventory?: Array<{ key: string, value: number }>;
+}
+// or instead of
+interface AnyClass{
+    inventory?: { [key: string]: number };
+}
+```	  

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<string>;
 
   /**
    * 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<string>;
   requestBodyName = 'any';
   responseBodyName = 'any';
   statusCodeSuccess = 200;
   urlFragment = '/';
 
-  public getUrlFragment(parameters?: { [k: string]: string }): string {
+  public getUrlFragment(parameters?: SCMap<string>): string {
     if (typeof parameters === 'undefined') {
       parameters = {};
     }

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;
 }

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 <https://www.gnu.org/licenses/>.
  */
-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

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<T,
    * Use this to explicitly override general opening hours brought in scope by openingHoursSpecification or openingHours
    *
    * A map from categories to their specific values.
-   *
-   * !!! BEWARE !!!
-   * TypeScript does not allow generics as index signatures. The properties of the map should exist in `T`.
    */
-  categorySpecificValues?: {
-    [s: string]: U,
-  };
+  categorySpecificValues?: SCMap<U>;
 
   /**
    * Translated fields of a thing with categories

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;
+}

src/core/protocol/routes/search/SearchResponse.ts

@@ -13,6 +13,7 @@
  * this program. If not, see <https://www.gnu.org/licenses/>.
  */
 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<SCMap<number>>;
 
   /**
    * 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;
+}

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<number>;
 
   /**
    * Translations of specific values of the object

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';
+}

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 <https://www.gnu.org/licenses/>.
+ */
+import {Point, Polygon} from 'geojson';
+
+/**
+ * Positional information
+ */
+export interface SCGeoInformation {
+  /**
+   * Center point of a place
+   */
+  point: Point;
+  /**
+   * Shape of a place
+   */
+  polygon?: Polygon;
+}

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 <https://www.gnu.org/licenses/>.
+ */
+
+/**
+ * Capsulation for a map with a string as key with values of type `T`
+ * 
+ * !!! BEWARE !!!
+ * Can't be refactored to a `Map<K, V>`, because it can't be serialized via JSON.stringify(map)
+ * 
+ * @typeparam T Can be any type.
+ */
+export interface SCMap<T> {
+  /**
+   * One value for each key
+   */
+  [key: string]: T;
+}

src/core/types/config/App.ts

@@ -38,7 +38,7 @@ export interface SCAppConfigurationMenuItem {
   /**
    * Translations for the menu item
    */
-  translations: SCTranslations<{ title: string }>;
+  translations: SCTranslations<SCAppConfigurationMenuItemTranslationTitle>;
 }
 
 /**
@@ -72,7 +72,7 @@ export interface SCAppConfigurationMenuCategory {
   /**
    * Translations for the menu category
    */
-  translations: SCTranslations<{ name: string }>;
+  translations: SCTranslations<SCAppConfigurationMenuCategoryTranslationName>;
 }
 
 /**
@@ -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;
+}

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<SCBackendConfigurationSearchBoostingValues>;
 
   /**
    * 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;
+}