feat: add core tools

src/common.ts

@@ -0,0 +1,152 @@
+/*
+ * Copyright (C) 2018 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 {Logger} from '@openstapps/logger';
+import {mkdir, PathLike, readFile, writeFile} from 'fs';
+import * as glob from 'glob';
+import {Schema as JSONSchema, ValidationError} from 'jsonschema';
+import {Definition} from 'ts-json-schema-generator';
+import {Application, ProjectReflection} from 'typedoc';
+import {promisify} from 'util';
+
+/**
+ * Initialized logger
+ */
+export const logger = new Logger();
+
+export const globPromisfied = promisify(glob);
+export const mkdirPromisified = promisify(mkdir);
+export const readFilePromisifed = promisify(readFile);
+export const writeFilePromisified = promisify(writeFile);
+
+/**
+ * A route instance with its relevant meta information
+ */
+export interface RouteWithMetaInformation {
+  /**
+   * Description of the route
+   */
+  description: {
+    /**
+     * Short text of the description - title
+     */
+    shortText?: string;
+    /**
+     * Text of the description
+     */
+    text?: string;
+  };
+  /**
+   * Name of the route
+   */
+  name: string;
+  /**
+   * Instance of the route
+   */
+  route: {
+    errorNames: string[];
+    method: string;
+    obligatoryParameters: {
+      [k: string]: string;
+    }
+    requestBodyName: string;
+    responseBodyName: string;
+    statusCodeSuccess: number;
+    urlFragment: string;
+  };
+}
+
+/**
+ * A node with its relevant meta information
+ */
+export interface NodeWithMetaInformation {
+  /**
+   * Module the node belongs to
+   */
+  module: string;
+  /**
+   * Type of the node
+   */
+  type: string;
+}
+
+/**
+ * A map of nodes indexed by their name
+ */
+export interface NodesWithMetaInformation {
+  /**
+   * Index signature
+   */
+  [k: string]: NodeWithMetaInformation;
+}
+
+/**
+ * A schema with definitions
+ */
+interface SchemaWithDefinitions extends JSONSchema {
+  definitions: { [name: string]: Definition };
+}
+
+/**
+ * An expectable error
+ */
+export type ExpectableValidationError = ValidationError & { expected: boolean };
+
+/**
+ * A map of files and their expectable validation errors
+ */
+export interface ExpectableValidationErrors {
+  [fileName: string]: ExpectableValidationError[];
+}
+
+/**
+ * Get a project reflection from a path
+ *
+ * @param srcPath Path to get reflection from
+ */
+export function getProjectReflection(srcPath: PathLike): ProjectReflection {
+  logger.info(`Generating project reflection for ${srcPath.toString()}.`);
+
+  // initialize new Typedoc application
+  const app = new Application({
+    excludeExternals: true,
+    includeDeclarations: true,
+    module: 'commonjs',
+  });
+
+  // get input files
+  const inputFiles = app.expandInputFiles([srcPath.toString()]);
+
+  // get project reflection from input files
+  return app.convert(inputFiles);
+}
+
+/**
+ * Check if a schema has definitions
+ *
+ * @param schema Schema to check
+ */
+export function isSchemaWithDefinitions(schema: JSONSchema): schema is SchemaWithDefinitions {
+  return typeof schema.definitions !== 'undefined';
+}
+
+/**
+ * Guard method for determining if an object (a thing) has a type property with a type of string
+ *
+ * @param thing {any} Any object (thing)
+ * @returns {boolean} Is an object (a thing) with a type property with type of string
+ */
+export function isThingWithType(thing: any): thing is { type: string } {
+  return typeof thing.type === 'string';
+}