@rapidrest/core 1.0.1

package/docs/reference/classes/ClassLoader.md

@@ -0,0 +1,224 @@
+[**@rapidrest/core**](../README.md)
+
+***
+
+[@rapidrest/core](../README.md) / ClassLoader
+
+# Class: ClassLoader
+
+Defined in: src/ClassLoader.ts:48
+
+The *ClassLoader* provides a container for dynamically loading classes at runtime using C#/Java style namespaces.
+Namespaces are determined from the folder structure relative to the root.
+
+Class names are derived either directly from the modules export name or inferred from the module's file path when
+the `default` export is used.
+
+For example, given the following example TypeScript module at relative path `com/company/MyClass.ts` would register
+a class with fully qualified name `com.company.MyClass`.
+
+```javascript
+export default class MyClass {
+    // ...
+}
+```
+
+In the event that multiple exports are defined, the fully qualified name will take on the export name instead of the
+module name. Thus, the following example module at relative path `com/company/MyClasses.ts` would register the following
+classes.
+- `com.company.MyClass`
+- `com.company.MyEnum`
+
+```javascript
+export class MyClass {
+    // ...
+}
+
+export enum MyEnum {
+    // ...
+}
+```
+
+**IMPORTANT**: If you use *ClassLoader* to dynamically load TypeScript files (.ts, .cts, .mts, etc.) at runtime using
+an ESM-only project you must use the `ts-node/esm` module loader. This can be specified by passing the `--loader` to
+node at runtime.
+
+```
+node --loader ts-node/esm <module>
+```
+
+## Author
+
+Jean-Philippe Steinmetz
+
+## Constructors
+
+### Constructor
+
+> **new ClassLoader**(`rootDir`, `includeJavaScript`, `includeTypeScript`, `ignore`): `ClassLoader`
+
+Defined in: src/ClassLoader.ts:67
+
+Creates a new instance of `ClassLoader` with the specified defaults.
+
+#### Parameters
+
+##### rootDir
+
+`string`
+
+The root directory to load all classes from.
+
+##### includeJavaScript
+
+`boolean` = `true`
+
+Set to `true` to load all TypeScript classes from the given `rootDir`, otherwise set to `false.
+@param includeTypeScript Set to `true` to load all JavaScript classes from the given `rootDir`, otherwise set to `false.
+
+##### includeTypeScript
+
+`boolean` = `true`
+
+##### ignore
+
+(`string` \| `RegExp`)[] = `[]`
+
+A list of regex pattern of file paths to ignore.
+
+#### Returns
+
+`ClassLoader`
+
+## Properties
+
+### classes
+
+> `protected` **classes**: `Map`\<`string`, `any`\>
+
+Defined in: src/ClassLoader.ts:50
+
+The map containnig all loaded classes.
+
+***
+
+### ignore
+
+> `protected` **ignore**: (`string` \| `RegExp`)[] = `[]`
+
+Defined in: src/ClassLoader.ts:51
+
+***
+
+### includeJavaScript
+
+> `protected` **includeJavaScript**: `boolean` = `true`
+
+Defined in: src/ClassLoader.ts:55
+
+Indicates if JavaScript classes should be loaded.
+
+***
+
+### includeTypeScript
+
+> `protected` **includeTypeScript**: `boolean` = `true`
+
+Defined in: src/ClassLoader.ts:53
+
+Indicates if TypeScript classes should be loaded.
+
+***
+
+### rootDir
+
+> `protected` **rootDir**: `string` = `"."`
+
+Defined in: src/ClassLoader.ts:57
+
+The path to the root directory containing all classes on disk.
+
+## Methods
+
+### getClass()
+
+> **getClass**(`fqn`): `any`
+
+Defined in: src/ClassLoader.ts:80
+
+Returns the class with the specified fully qualified name.
+
+#### Parameters
+
+##### fqn
+
+`string`
+
+The fully qualified name of the class to return.
+
+#### Returns
+
+`any`
+
+The class definition for the given fully qualified name if found, otherwise `undefined`.
+
+***
+
+### getClasses()
+
+> **getClasses**(): `Map`\<`string`, `any`\>
+
+Defined in: src/ClassLoader.ts:87
+
+Returns the map containing all classes that have been loaded.
+
+#### Returns
+
+`Map`\<`string`, `any`\>
+
+***
+
+### hasClass()
+
+> **hasClass**(`fqn`): `any`
+
+Defined in: src/ClassLoader.ts:97
+
+Returns `true` if a class exists with the specified fully qualified name.
+
+#### Parameters
+
+##### fqn
+
+`string`
+
+The fully qualified name of the class to search.
+
+#### Returns
+
+`any`
+
+`true` if a class definition exists for the given fully qualified name, otherwise `false`.
+
+***
+
+### load()
+
+> **load**(`dir`): `Promise`\<`void`\>
+
+Defined in: src/ClassLoader.ts:107
+
+Loads all modules exports contained in the directory specified. The folder must be a child
+directory to the `rootDir` parameter passed in to the constructor.
+
+#### Parameters
+
+##### dir
+
+`string` = `""`
+
+The directory, relative to `rootDir`, containing modules to load.
+
+#### Returns
+
+`Promise`\<`void`\>

package/docs/reference/classes/Event.md

@@ -0,0 +1,109 @@
+[**@rapidrest/core**](../README.md)
+
+***
+
+[@rapidrest/core](../README.md) / Event
+
+# Class: Event
+
+Defined in: src/TelemetryUtils.ts:23
+
+Describes a single telemetry event. A telemetry event is when something occurs in the system.
+
+## Author
+
+Jean-Philippe Steinmetz <rapidrests@gmail.com>
+
+## Implements
+
+- [`NewEvent`](../interfaces/NewEvent.md)
+
+## Constructors
+
+### Constructor
+
+> **new Event**(`config`, `userId`, `data`): `Event`
+
+Defined in: src/TelemetryUtils.ts:54
+
+#### Parameters
+
+##### config
+
+`any`
+
+##### userId
+
+`string`
+
+##### data
+
+[`NewEvent`](../interfaces/NewEvent.md)
+
+#### Returns
+
+`Event`
+
+## Properties
+
+### environment
+
+> `readonly` **environment**: `string`
+
+Defined in: src/TelemetryUtils.ts:32
+
+The name of the environment that the event originated from. This is typically `dev` or `prod`.
+
+***
+
+### origin
+
+> `readonly` **origin**: `string`
+
+Defined in: src/TelemetryUtils.ts:37
+
+The unique name of the service or client that the event originated from.
+
+***
+
+### timestamp
+
+> `readonly` **timestamp**: `Date`
+
+Defined in: src/TelemetryUtils.ts:42
+
+The date and time that the event occured.
+
+***
+
+### type
+
+> `readonly` **type**: `string`
+
+Defined in: src/TelemetryUtils.ts:47
+
+The type of event being recorded.
+
+#### Implementation of
+
+[`NewEvent`](../interfaces/NewEvent.md).[`type`](../interfaces/NewEvent.md#type)
+
+***
+
+### uid
+
+> `readonly` **uid**: `string`
+
+Defined in: src/TelemetryUtils.ts:27
+
+The universally unique identifier of the event.
+
+***
+
+### userId
+
+> `readonly` **userId**: `string`
+
+Defined in: src/TelemetryUtils.ts:52
+
+The universally unique identifer of the user that sent the event.

package/docs/reference/classes/EventUtils.md

@@ -0,0 +1,123 @@
+[**@rapidrest/core**](../README.md)
+
+***
+
+[@rapidrest/core](../README.md) / EventUtils
+
+# Class: EventUtils
+
+Defined in: src/TelemetryUtils.ts:84
+
+Provides a common set of static functions for recording and working with telemetry `Event` instances.
+
+The `init` function must be called before any other function can be called.
+
+The `record` function is used to send an event to a configured `telemetry_services` service for permanent storage.
+
+The `on` function allows code within the same application or service to listen for outgoing events that have been
+sent via the `record` function.
+
+## Author
+
+Jean-Philippe Steinmetz <rapidrests@gmail.com>
+
+## Constructors
+
+### Constructor
+
+> **new EventUtils**(): `EventUtils`
+
+#### Returns
+
+`EventUtils`
+
+## Methods
+
+### init()
+
+> `static` **init**(`config`, `logger`, `jwtToken`): `void`
+
+Defined in: src/TelemetryUtils.ts:99
+
+Initializes `EventUtils` with the provided defaults.
+
+#### Parameters
+
+##### config
+
+`any`
+
+The application configuration to use.
+
+##### logger
+
+`any`
+
+The logging utility to use.
+
+##### jwtToken
+
+`string`
+
+The user's JWT token to send telemetry events on behalf of.
+
+#### Returns
+
+`void`
+
+***
+
+### on()
+
+> `static` **on**(`type`, `callback`): `void`
+
+Defined in: src/TelemetryUtils.ts:173
+
+Registers a `callback` function to receive notifications of recorded events of the given `type`. Note that only
+events originating from the same application or service will be notified.
+
+#### Parameters
+
+##### type
+
+`string`
+
+The type of event to be notified of.
+
+##### callback
+
+`Function`
+
+The function to call when an event is recorded.
+
+#### Returns
+
+`void`
+
+***
+
+### record()
+
+> `static` **record**(`evt`, `type?`): `Promise`\<`void`\>
+
+Defined in: src/TelemetryUtils.ts:118
+
+Sends the given event to the telemetry service for permanent recording.
+
+#### Parameters
+
+##### evt
+
+`any`
+
+The event to send and record.
+
+##### type?
+
+`string`
+
+The type of event to record. Overrides any `type` value set in `evt`.
+
+#### Returns
+
+`Promise`\<`void`\>

package/docs/reference/classes/FileUtils.md

@@ -0,0 +1,193 @@
+[**@rapidrest/core**](../README.md)
+
+***
+
+[@rapidrest/core](../README.md) / FileUtils
+
+# Class: FileUtils
+
+Defined in: src/FileUtils.ts:18
+
+Utility functions for working with files.
+
+## Author
+
+Jean-Philippe Steinmetz
+
+## Constructors
+
+### Constructor
+
+> **new FileUtils**(): `FileUtils`
+
+#### Returns
+
+`FileUtils`
+
+## Methods
+
+### copyBinaryFile()
+
+> `static` **copyBinaryFile**(`srcPath`, `outPath`, `variables`): `Promise`\<`void`\>
+
+Defined in: src/FileUtils.ts:160
+
+Generates a copy of the source file at the desired output destination using binary copy mode.
+
+#### Parameters
+
+##### srcPath
+
+`string`
+
+The source file to copy.
+
+##### outPath
+
+`string`
+
+The destination file to generate.
+
+##### variables
+
+`any` = `{}`
+
+The map of variable names to values to swap. Applies to outPath only.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### copyDirectory()
+
+> `static` **copyDirectory**(`srcPath`, `outPath`, `vars`, `excludeFilters`, `binaryFilters`, `force`): `Promise`\<`void`\>
+
+Defined in: src/FileUtils.ts:188
+
+Performs a deep copy of a directory tree at the given srcPath to the specified output directory. Performs
+template replacement for all variables given and skips any files in the specified filter.
+
+#### Parameters
+
+##### srcPath
+
+`string`
+
+The path to the source directory to copy files from.
+
+##### outPath
+
+`string`
+
+The path to the destination directory to copy files to.
+
+##### vars
+
+`any` = `{}`
+
+The map of template variables to perform replacement on.
+
+##### excludeFilters
+
+`string`[] = `[]`
+
+The list of file extension filters to exclude during the copy process.
+
+##### binaryFilters
+
+`string`[] = `[]`
+
+The list of file extension filters to copy as binary only.
+
+##### force
+
+`boolean` = `false`
+
+Set to `true` to force writing over any existing files.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### copyFile()
+
+> `static` **copyFile**(`srcPath`, `outPath`, `variables`, `overwrite`): `Promise`\<`void`\>
+
+Defined in: src/FileUtils.ts:124
+
+Generates a copy of the source file at the desired output destination and performs a swap of all values of the
+variables specified.
+
+#### Parameters
+
+##### srcPath
+
+`string`
+
+The source file to copy.
+
+##### outPath
+
+`string`
+
+The destination file to generate.
+
+##### variables
+
+`any` = `{}`
+
+The map of variable names to values to swap.
+
+##### overwrite
+
+`boolean` = `false`
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### writeFile()
+
+> `static` **writeFile**(`srcPath`, `outPath`, `contents`, `overwrite`): `Promise`\<`void`\>
+
+Defined in: src/FileUtils.ts:29
+
+Attempts to write the provided contents to the file path given. If a file already exists the user is prompted to
+allow the file to be overwritten or merged. In the case of a merge, srcPath is used as a baseline in order to
+perform a 3-way merge.
+
+#### Parameters
+
+##### srcPath
+
+`string`
+
+The baseline template file to use during a merge.
+
+##### outPath
+
+`string`
+
+The destination file path to be written.
+
+##### contents
+
+`any`
+
+The contents of the file to write.
+
+##### overwrite
+
+`boolean` = `false`
+
+Set to `true` to overwite the file and not perform a merge.
+
+#### Returns
+
+`Promise`\<`void`\>

package/docs/reference/classes/JWTUtils.md

@@ -0,0 +1,91 @@
+[**@rapidrest/core**](../README.md)
+
+***
+
+[@rapidrest/core](../README.md) / JWTUtils
+
+# Class: JWTUtils
+
+Defined in: src/JWTUtils.ts:145
+
+Utility class for working with Json Web Token (JWT) authentication tokens.
+
+## Author
+
+Jean-Philippe Steinmetz <rapidrests@gmail.com>
+
+## Constructors
+
+### Constructor
+
+> **new JWTUtils**(): `JWTUtils`
+
+#### Returns
+
+`JWTUtils`
+
+## Methods
+
+### createToken()
+
+> `static` **createToken**(`config`, `user`, `data?`): `string`
+
+Defined in: src/JWTUtils.ts:154
+
+Generates a new JWT token for the given config and user object. The user object must be a valid RapidREST
+user.
+
+#### Parameters
+
+##### config
+
+[`JWTUtilsConfig`](../interfaces/JWTUtilsConfig.md)
+
+The JWT configuration to use when generating the token.
+
+##### user
+
+[`JWTUser`](../interfaces/JWTUser.md)
+
+The user to encode into the token's payload.
+
+##### data?
+
+`any`
+
+Additional data to include the token's payload.
+
+#### Returns
+
+`string`
+
+***
+
+### decodeToken()
+
+> `static` **decodeToken**(`config`, `token`): [`JWTPayload`](../interfaces/JWTPayload.md)
+
+Defined in: src/JWTUtils.ts:207
+
+Decodes the given JWT authentication token using the provided configuration. If the token is not valid an
+error is thrown with the reason. Returns the encoded user object payload upon success.
+
+#### Parameters
+
+##### config
+
+[`JWTUtilsConfig`](../interfaces/JWTUtilsConfig.md)
+
+The JWT configuration to use when validating the token.
+
+##### token
+
+`string`
+
+The JWT token to validate.
+
+#### Returns
+
+[`JWTPayload`](../interfaces/JWTPayload.md)
+
+The data encoded in the token's payload.