@rapidrest/core 1.0.1

package/dist/types/UserUtils.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Utilities for working with authenticated user objects. An user object is expected to have the following
+ * properties.
+ *
+ * * `uid` - Universally unique identifier for the user
+ * * `email` - Unique e-mail address for the user
+ * * `roles` - A list of unique names indicating the permissions of the user.
+ * * `verified` - Indicates if the user's e-mail address has been verified.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export declare class UserUtils {
+    /**
+     * Returns `true` if the given user object is a member of the organization with the specified uid, otherwise returns `false`.
+     * @param user The user object to inspect.
+     * @param organizationUid The universally unique identifier of the persona to search for.
+     */
+    static hasOrganization(user: any, organizationUid: string): boolean;
+    /**
+     * Returns `true` if the given user object contains is a member of an organization matching one of the uids in the specified list, otherwise returns `false`.
+     * @param user The user object to inspect.
+     * @param organizationUids The list of universally unique identifiers to search for.
+     */
+    static hasOrganizations(user: any, organizationUids?: string[]): boolean;
+    /**
+     * Returns `true` if the given user object contains a `Persona` object with the specified uid, otherwise returns `false`.
+     * @param user The user object to inspect.
+     * @param personaUid The universally unique identifier of the persona to search for.
+     */
+    static hasPersona(user: any, personaUid?: string): boolean;
+    /**
+     * Returns `true` if the given user object contains a `Persona` object matching one of the uids in the specified list, otherwise returns `false`.
+     * @param user The user object to inspect.
+     * @param personaUid The list of universally unique identifiers to search for.
+     */
+    static hasPersonas(user: any, personaUids?: string[]): boolean;
+    /**
+     * Returns the unique identifier of the specified type associated with the given user.
+     *
+     * @param user The user to retrieve the external id from.
+     * @param type The type of external provider to retrieve.
+     * @returns The unique id of the external provider for the given type if found, otherwise `undefined`.
+     */
+    static getExternalId(user: any, type: string): string | undefined;
+    /**
+     * Returns `true` if the given user object has a role with the specified name, otherwise returns `false`.
+     *
+     * @param user The user object to inspect.
+     * @param role The unique name of the role to search for.
+     * @param orgUid The unique identifier of an organization whose role will be verified.
+     */
+    static hasRole(user: any, role?: string, orgUid?: string): boolean;
+    /**
+     * Returns `true` if the given user object has at least one role from the specified list of names, otherwise returns `false`.
+     *
+     * @param user The user object to inspect.
+     * @param roles A list of unique names of the roles to search for.
+     * @param orgUid The unique identifier of an organization whose role will be verified.
+     */
+    static hasRoles(user: any, roles?: string[], orgUid?: string): boolean;
+}

package/dist/types/ValidationUtils.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A simple validation function that returns a boolean success or fail.
+ */
+export type BooleanFunc = (val: any) => boolean;
+/**
+ * A collection of validation functions to use with the `@Validator()` decorator.
+ */
+export declare class ValidationUtils {
+    /**
+     * A simple wrapper that calls the specified boolean validation function with the given value and returns the
+     * value as a result if the validation function passes. Otherwise throws an error.
+     *
+     * @param val The value to validate.
+     * @param func The boolean validation function to check the value.
+     * @throws Throws an error if the value fails the boolean validation test.
+     */
+    static check(val: any, func: BooleanFunc): any;
+    /**
+     * Validates that the provided string represents a ISO, RFC or UTC date or timestamp.
+     */
+    static checkDate(val: string): string;
+    /**
+     * Validates that the provided string represents a valid e-mail address.
+     */
+    static checkEmail(val: string): string;
+    /**
+     * Validates that the provided array is not empty.
+     */
+    static checkEmpty(val: Array<any>): Array<any>;
+    /**
+     * Validates that the provided string is a valid IP address.
+     */
+    static checkIP(val: string): string;
+    /**
+     * Validates that the provided string is valid JSON (note: uses `JSON.parse`).
+     */
+    static checkJSON(val: string): string;
+    /**
+     * Validates that the provided string matches the regexp pattern /[a-zA-Z0-9_\-\.@:\+]+/.
+     */
+    static checkName(val: string): string;
+    /**
+     * Validates that the provided object is not null or empty.
+     */
+    static checkNull(val: any): any;
+    /**
+     * Validates that the provided string represents a valid phone number.
+     */
+    static checkPhone(val: string): string;
+    /**
+     * Validates that the provided string represents a semantic version.
+     */
+    static checkSemVer(val: string): string;
+    /**
+     * Validates that the provided string is a valid URL.
+     */
+    static checkURL(val: string): string;
+    /**
+     * Validates that the provided string is a valid UUID.
+     */
+    static checkUUID(val: string): string;
+    /**
+     * Validates that the provided value is an entity `version` number (e.g. `value > 0`).
+     */
+    static checkVersion(val: any): number;
+}

package/dist/types/decorators/ObjectDecorators.d.ts

@@ -0,0 +1,55 @@
+import "reflect-metadata";
+import { InstanceOptions } from "../ObjectFactory.js";
+/**
+ * Apply this to a class function to mark it as a destructor to be called by the `ObjectFactory` during cleanup.
+ */
+export declare function Destroy(target: any, propertyKey: string): void;
+/**
+ * Injects an object instance to the decorated property of the given name and type using the provided arguments
+ * if no object has been created yet.
+ * @param type The fully qualified name or type of the class to instantiate. If a type is given it's class name will be inferred
+ * via the constructor name.
+ * @param name The unique name to give the class instance. Set to `undefined` if you wish to force a new object is created.
+ * @param initialize Set to `true` to initialize the object after creation, otherwise set to `false`. Default is `true`.
+ * @param args The set of constructor arguments to use during construction
+ */
+export declare function Inject(type: any, options?: InstanceOptions): (target: any, propertyKey: string | symbol) => void;
+/**
+ * Apply this to a function to be executed once a new object instance has been created and all dependencies injected.
+ * Note: If the decorated function returns a Promise it is not gauranteed to finish execution before the object is
+ * returned during the instantiation process.
+ */
+export declare function Init(target: any, propertyKey: string, descriptor: PropertyDescriptor): void;
+/**
+ * Apply this to a property to have a configuration variable be injected at instantiation. If no path is given, the
+ * global configuration object is injected.
+ *
+ * @param path The path to the configuration variable to inject.
+ * @param defaultValue Set to the desired default value. If `undefined` is specified then an error is thrown if
+ * no config variable is found at the given path.
+ */
+export declare function Config(path?: string, defaultValue?: any): (target: any, propertyKey: string | symbol) => void;
+/**
+ * Apply this to a property to have the logger utility injected at instantiation.
+ */
+export declare function Logger(target: any, propertyKey: string | symbol): void;
+/**
+ * Apply this to a property to indicate that the value can be `null` or `undefined.`
+ *
+ * @param nullable Set to `true` to indicate that the property value can be `null`, otherwise set to `false`. Default is `false`.
+ */
+export declare function Nullable(target: any, propertyKey: string | symbol): void;
+/**
+ * A function used to validate a property value.
+ *
+ * @param value The value to validate.
+ * @returns The validated value to assign to the property.
+ * @throws An exception if the value cannot be validated.
+ */
+export type ValidatorFunction = (value: any) => any;
+/**
+ * Apply this to a property to specify the function that will be used to perform validation of the value.
+ *
+ * @param func The validation function to use for the given property.
+ */
+export declare function Validator(func: ValidatorFunction): (target: any, propertyKey: string | symbol) => void;

package/dist/types/decorators/index.d.ts

@@ -0,0 +1 @@
+export * as ObjectDecorators from "./ObjectDecorators.js";

package/dist/types/index.d.ts

@@ -0,0 +1,17 @@
+export * from "./ApiError.js";
+export * from "./AlertUtils.js";
+export * from "./ClassLoader.js";
+export * from "./decorators/index.js";
+export * from "./FileUtils.js";
+export * from "./JWTUtils.js";
+export * from "./Logger.js";
+export * from "./MessagingUtils.js";
+export * from "./ObjectFactory.js";
+export * from "./ObjectUtils.js";
+export * from "./OASUtils.js";
+export * from "./StringUtils.js";
+export * from "./threads/index.js";
+export * from "./sleep.js";
+export * from "./TelemetryUtils.js";
+export * from "./UserUtils.js";
+export * from "./ValidationUtils.js";

package/dist/types/sleep.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Starts a timer to suspend execution for a given number of milliseconds.
+ * @param ms The number of milliseconds to suspend. Default is `1`.
+ */
+export declare function sleep(ms?: number): Promise<void>;

package/dist/types/threads/ThreadLogger.d.ts

@@ -0,0 +1,15 @@
+export = ThreadLogger;
+/**
+ * Provides a Winston transport for forwarding logs from this thread to the parent's logger instance.
+ *
+ * Constructor requires two properties to be set in the `opts` argument:
+ * - `parentPort`
+ * - `threadId`
+ */
+declare class ThreadLogger {
+    log(data: any): void;
+    debug(message: any): void;
+    error(message: any): void;
+    info(message: any): void;
+    warn(message: any): void;
+}

package/dist/types/threads/ThreadPool.d.ts

@@ -0,0 +1,115 @@
+import { Worker } from "worker_threads";
+/**
+ * Callback function for `ThreadPool` events.
+ *
+ * @param threadId The id of the thread that originated the event.
+ * @param msg The optional message data associated with the event.
+ */
+export type WorkerCallback = (threadId: number, msg?: any) => void;
+/**
+ * Describes the various options that can be used when creating worker threads.
+ */
+export interface WorkerOptions {
+    /** The list of initialization arguments to pass into the worker thread. */
+    args?: any;
+    /** The path to the entry file create a worker thread from. Default is `ThreadWorkerEntry.js`. */
+    entry?: string;
+    /** Indicates if a worker thread should automatically be restarted on exit. */
+    restartOnExit?: boolean;
+    /** Set to `true` to enable support for importing TypeScript modules in the worker. Default is `true`. */
+    allowTs?: boolean;
+    /** The path to the worker file. This must be set when using `ThreadWorkerEntry` as the default entry file. */
+    worker?: string;
+}
+/**
+ * The `ThreadPool` class provides an interface for managing a pool of execution threads that can be used for parallel
+ * code execution. `ThreadPool` is a wrapper to the `worker_threads` API to add support for multiple `Worker` instances.
+ * By default, the pool will create *n* workers corresponding to the number of CPUs (physical + virtual) on the system.
+ *
+ * There are two ways to start worker threads with the pool.
+ *
+ * The first way is to set the `entry` option when calling the `start()` function. This will create a instance of the
+ * `worker_threads` APIs `Worker` class with the specified file as the entry point. Note that this file must be of
+ * type JavaScript (`.js` extension) as the underlying system does not support loading TypeScript. If the `args` option
+ * is set, the value will be passed in as the `workerData` to the entry file.
+ *
+ * The second way to start a worker thread is by setting the `worker` argument when calling the `start()` function. The
+ * specified `worker` file must contain a `default` export. The `default` export must be a class definition which
+ * extends the `ThreadWorker` abstract class interface. The file can be either JavaScript or TypeScript. When using
+ * this method the `start()` function will return only when all worker instances in each thread of the pool has
+ * successfully returned from its `start()` function. When the `args` option is set, the value(s) will be passed in to
+ * the constructor on instantiation by the thread executor.
+ *
+ * When the `restartOnExit` option is specified, the pool will automatically recreate and start a worker thread on
+ * the `exit event`.
+ *
+ * This class exposes worker messages via the `on()` callback handler function. Registering a callback handler via
+ * `on()` will propogate all messages from all underlying threads in the pool.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class ThreadPool {
+    /** The map of event types to a list of callback functions. */
+    private callbacks;
+    /** The index of the last worker that was assigned work. */
+    private lastThread;
+    /** The instance of Winston logger to forward thread logs to. */
+    private logger?;
+    /** The maximum number of threads allowed. */
+    private maxThreads;
+    /** The list of active worker threads. */
+    readonly workers: Array<Worker>;
+    /** Used to indicate that the pool is shutting down. */
+    private shutdown;
+    /**
+     * The maximum number of threads that can be created by the pool.
+     */
+    get max(): number;
+    /**
+     * The number of active threads in the pool.
+     */
+    get size(): number;
+    /**
+     * Creates a new `ThreadPool` instance with the specified defaults.
+     *
+     * @param max The maximum number of threads to create. Default is `os.cpus().length`.
+     * @param logger The Winston logger instance to forward all worker thread logs to.
+     */
+    constructor(max?: number, logger?: any);
+    private createWorker;
+    /**
+     * Initializes the thread pool with the initial worker threads and begins execution.
+     *
+     * @param entry The path of the entry create a worker thread from. Default is `ThreadWorkerEntry.js`.
+     * @param options The options to use when creating the worker thread.
+     * @param num The number of initial threads to create, cannot be greater than max. Default is `max`.
+     */
+    start(options?: WorkerOptions, num?: number): Promise<void>;
+    /**
+     * Stops all running thread executions.
+     */
+    stop(): Promise<void>;
+    /**
+     * Registers a new callback function to be notified when the given event type is fired.
+     *
+     * @param type The event type to be notified of. Possible values are: `error`, `exit` and `message`.
+     * @param func The callback function to register.
+     */
+    on(type: string, func: WorkerCallback): void;
+    /**
+     * Sends the provided message to the next available worker thread. Messages are sent in a round-robin order.
+     * @param msg The message to send the next available worker thread.
+     */
+    send(msg: any): void;
+    /**
+     * Sends the provided message to all worker threads in the pool.
+     * @param msg The message to send to all workers.
+     */
+    sendAll(msg: any): void;
+    /**
+     * Sends the provided message to the worker thread with the specified id.
+     * @param id The id of the thread to send the message to.
+     * @param msg The message to send the next available worker thread.
+     */
+    sendTo(id: number, msg: any): void;
+}

package/dist/types/threads/ThreadWorker.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Describes the types of messages passed between the parent thread pool manager and a worker thread.
+ */
+export declare enum WorkerMessageType {
+    ERROR = "_WorkerError",
+    LOG = "_WorkerLog",
+    ONLINE = "_WorkerOnline",
+    STOP = "_StopWorker"
+}
+/**
+ * Describes a single message sent from the thread pool managger to a worker thread.
+ */
+export interface WorkerMessage {
+    /** The data associated with the message. */
+    data?: any;
+    /** The type of message sent. */
+    type: WorkerMessageType;
+}
+/**
+ * Provides a simple abstract interface for creating thread workers when using the `ThreadPool` system.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare abstract class ThreadWorker {
+    protected logger: any;
+    constructor(logger: any);
+    /**
+     * Callback function when a message is received from the thread pool manager.
+     *
+     * @param msg The message that was received.
+     */
+    abstract onMessage(msg: WorkerMessage): void | Promise<void>;
+    /**
+     * Starts execution of the thread worker.
+     */
+    abstract start(): void | Promise<void>;
+    /**
+     * Stops execution of all work and shuts down the thread worker.
+     */
+    abstract stop(): void | Promise<void>;
+}

package/dist/types/threads/ThreadWorkerEntry.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/threads/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./ThreadPool.js";
+export * from "./ThreadWorker.js";

package/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

package/docs/conf.py

@@ -0,0 +1,58 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+import recommonmark
+from recommonmark.transform import AutoStructify
+
+source_suffix = ['.rst', '.md']
+
+# -- Project information -----------------------------------------------------
+
+project = 'RapidREST: Core Library'
+copyright = 'Jean-Philippe Steinmetz. All rights reserved.'
+author = 'RapidREST <rapidrests@gmail.com>'
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'recommonmark',
+    'sphinx.ext.autodoc',
+]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+master_doc = 'index'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# app setup hook
+def setup(app):
+    app.add_config_value('recommonmark_config', {
+        'auto_toc_tree_section': 'Contents',
+        'enable_math': False,
+        'enable_inline_math': False,
+        'enable_eval_rst': True,
+        'enable_auto_doc_ref': True,
+    }, True)
+    app.add_transform(AutoStructify)

package/docs/index.rst

@@ -0,0 +1,17 @@
+===============================================================================
+RapidREST: Core Library
+===============================================================================
+
+Repository: ``git@github.com:rapidrest/core.git``
+
+A collection of common utilities and core functionality for rapidly building RESTful applications.
+
+.. toctree::
+   :caption: Project Info
+
+   ../README
+   
+.. toctree::
+   :caption: API Reference
+   
+   reference/globals

package/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

package/docs/reference/@rapidrest/namespaces/ObjectDecorators/README.md

@@ -0,0 +1,21 @@
+[**@rapidrest/core**](../../../README.md)
+
+***
+
+[@rapidrest/core](../../../README.md) / ObjectDecorators
+
+# ObjectDecorators
+
+## Type Aliases
+
+- [ValidatorFunction](type-aliases/ValidatorFunction.md)
+
+## Functions
+
+- [Config](functions/Config.md)
+- [Destroy](functions/Destroy.md)
+- [Init](functions/Init.md)
+- [Inject](functions/Inject.md)
+- [Logger](functions/Logger.md)
+- [Nullable](functions/Nullable.md)
+- [Validator](functions/Validator.md)

package/docs/reference/@rapidrest/namespaces/ObjectDecorators/functions/Config.md

@@ -0,0 +1,47 @@
+[**@rapidrest/core**](../../../../README.md)
+
+***
+
+[@rapidrest/core](../../../../README.md) / [ObjectDecorators](../README.md) / Config
+
+# Function: Config()
+
+> **Config**(`path?`, `defaultValue?`): (`target`, `propertyKey`) => `void`
+
+Defined in: src/decorators/ObjectDecorators.ts:63
+
+Apply this to a property to have a configuration variable be injected at instantiation. If no path is given, the
+global configuration object is injected.
+
+## Parameters
+
+### path?
+
+`string`
+
+The path to the configuration variable to inject.
+
+### defaultValue?
+
+`any` = `undefined`
+
+Set to the desired default value. If `undefined` is specified then an error is thrown if
+no config variable is found at the given path.
+
+## Returns
+
+> (`target`, `propertyKey`): `void`
+
+### Parameters
+
+#### target
+
+`any`
+
+#### propertyKey
+
+`string` | `symbol`
+
+### Returns
+
+`void`

package/docs/reference/@rapidrest/namespaces/ObjectDecorators/functions/Destroy.md

@@ -0,0 +1,27 @@
+[**@rapidrest/core**](../../../../README.md)
+
+***
+
+[@rapidrest/core](../../../../README.md) / [ObjectDecorators](../README.md) / Destroy
+
+# Function: Destroy()
+
+> **Destroy**(`target`, `propertyKey`): `void`
+
+Defined in: src/decorators/ObjectDecorators.ts:10
+
+Apply this to a class function to mark it as a destructor to be called by the `ObjectFactory` during cleanup.
+
+## Parameters
+
+### target
+
+`any`
+
+### propertyKey
+
+`string`
+
+## Returns
+
+`void`

package/docs/reference/@rapidrest/namespaces/ObjectDecorators/functions/Init.md

@@ -0,0 +1,33 @@
+[**@rapidrest/core**](../../../../README.md)
+
+***
+
+[@rapidrest/core](../../../../README.md) / [ObjectDecorators](../README.md) / Init
+
+# Function: Init()
+
+> **Init**(`target`, `propertyKey`, `descriptor`): `void`
+
+Defined in: src/decorators/ObjectDecorators.ts:51
+
+Apply this to a function to be executed once a new object instance has been created and all dependencies injected.
+Note: If the decorated function returns a Promise it is not gauranteed to finish execution before the object is
+returned during the instantiation process.
+
+## Parameters
+
+### target
+
+`any`
+
+### propertyKey
+
+`string`
+
+### descriptor
+
+`PropertyDescriptor`
+
+## Returns
+
+`void`