@twin.org/logging-models 0.0.1-next.2

package/dist/types/models/ILogEntry.d.ts

@@ -0,0 +1,33 @@
+import type { IError } from "@twin.org/core";
+import type { LogLevel } from "./logLevel";
+/**
+ * Interface describing a log entry.
+ */
+export interface ILogEntry {
+    /**
+     * The level of the error being logged.
+     */
+    level: LogLevel;
+    /**
+     * The source of the log entry.
+     */
+    source: string;
+    /**
+     * The timestamp of the log entry, if left blank will be populated by the connector.
+     */
+    ts?: number;
+    /**
+     * The message.
+     */
+    message: string;
+    /**
+     * Optional error details.
+     */
+    error?: IError;
+    /**
+     * Optional data for the message.
+     */
+    data?: {
+        [key: string]: unknown;
+    };
+}

package/dist/types/models/ILoggingComponent.d.ts

@@ -0,0 +1,36 @@
+import type { IComponent } from "@twin.org/core";
+import type { ILogEntry } from "./ILogEntry";
+import type { LogLevel } from "./logLevel";
+/**
+ * Interface describing a logging contract.
+ */
+export interface ILoggingComponent extends IComponent {
+    /**
+     * Log an entry to the component.
+     * @param logEntry The entry to log.
+     * @returns Nothing.
+     */
+    log(logEntry: ILogEntry): Promise<void>;
+    /**
+     * Query the log entries.
+     * @param level The level of the log entries.
+     * @param source The source of the log entries.
+     * @param timeStart The inclusive time as the start of the log entries.
+     * @param timeEnd The inclusive time as the end of the log entries.
+     * @param cursor The cursor to request the next page of entities.
+     * @param pageSize The maximum number of entities in a page.
+     * @returns All the entities for the storage matching the conditions,
+     * and a cursor which can be used to request more entities.
+     * @throws NotImplementedError if the implementation does not support retrieval.
+     */
+    query(level?: LogLevel, source?: string, timeStart?: number, timeEnd?: number, cursor?: string, pageSize?: number): Promise<{
+        /**
+         * The entities, which can be partial if a limited keys list was provided.
+         */
+        entities: ILogEntry[];
+        /**
+         * An optional cursor, when defined can be used to call find to get more entities.
+         */
+        cursor?: string;
+    }>;
+}

package/dist/types/models/ILoggingConnector.d.ts

@@ -0,0 +1,38 @@
+import type { IComponent } from "@twin.org/core";
+import type { EntityCondition, SortDirection } from "@twin.org/entity";
+import type { ILogEntry } from "./ILogEntry";
+/**
+ * Interface describing a logging connector.
+ */
+export interface ILoggingConnector extends IComponent {
+    /**
+     * Log an entry to the connector.
+     * @param logEntry The entry to log.
+     * @returns Nothing.
+     */
+    log(logEntry: ILogEntry): Promise<void>;
+    /**
+     * Query the log entries.
+     * @param conditions The conditions to match for the entities.
+     * @param sortProperties The optional sort order.
+     * @param properties The optional keys to return, defaults to all.
+     * @param cursor The cursor to request the next page of entities.
+     * @param pageSize The maximum number of entities in a page.
+     * @returns All the entities for the storage matching the conditions,
+     * and a cursor which can be used to request more entities.
+     * @throws NotImplementedError if the implementation does not support retrieval.
+     */
+    query(conditions?: EntityCondition<ILogEntry>, sortProperties?: {
+        property: keyof Omit<ILogEntry, "error" | "data">;
+        sortDirection: SortDirection;
+    }[], properties?: (keyof ILogEntry)[], cursor?: string, pageSize?: number): Promise<{
+        /**
+         * The entities, which can be partial if a limited keys list was provided.
+         */
+        entities: Partial<ILogEntry>[];
+        /**
+         * An optional cursor, when defined can be used to call find to get more entities.
+         */
+        cursor?: string;
+    }>;
+}

package/dist/types/models/ILoggingLevelsConfig.d.ts

@@ -0,0 +1,10 @@
+import type { LogLevel } from "./logLevel";
+/**
+ * Configuration for the logging connectors to specify the levels to display.
+ */
+export interface ILoggingLevelsConfig {
+    /**
+     * The log levels to display, will default to all.
+     */
+    levels?: LogLevel[];
+}

package/dist/types/models/api/ILoggingCreateRequest.d.ts

@@ -0,0 +1,10 @@
+import type { ILogEntry } from "../ILogEntry";
+/**
+ * Create a new log entry.
+ */
+export interface ILoggingCreateRequest {
+    /**
+     * The data to be used in the create.
+     */
+    body: ILogEntry;
+}

package/dist/types/models/api/ILoggingListRequest.d.ts

@@ -0,0 +1,35 @@
+import type { LogLevel } from "../logLevel";
+/**
+ * Get the a list of the log entries.
+ */
+export interface ILoggingListRequest {
+    /**
+     * The query parameters.
+     */
+    query: {
+        /**
+         * The level of the log entries to retrieve.
+         */
+        level?: LogLevel;
+        /**
+         * The source of the log entries to retrieve.
+         */
+        source?: string;
+        /**
+         * The start time of the metrics to retrieve as a timestamp in ms.
+         */
+        timeStart?: number;
+        /**
+         * The end time of the metrics to retrieve as a timestamp in ms.
+         */
+        timeEnd?: number;
+        /**
+         * The optional cursor to get next chunk.
+         */
+        cursor?: string;
+        /**
+         * The maximum number of entities in a page.
+         */
+        pageSize?: number;
+    };
+}

package/dist/types/models/api/ILoggingListResponse.d.ts

@@ -0,0 +1,19 @@
+import type { ILogEntry } from "../ILogEntry";
+/**
+ * Response for log entry list request.
+ */
+export interface ILoggingListResponse {
+    /**
+     * The response payload.
+     */
+    body: {
+        /**
+         * The entities, which can be partial if a limited keys list was provided.
+         */
+        entities: ILogEntry[];
+        /**
+         * An optional cursor, when defined can be used to call find to get more entities.
+         */
+        cursor?: string;
+    };
+}

package/dist/types/models/logLevel.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Log level.
+ */
+export type LogLevel = "info" | "error" | "warn" | "trace" | "debug";

package/docs/changelog.md

@@ -0,0 +1,5 @@
+# @twin.org/logging-models - Changelog
+
+## v0.0.1-next.2
+
+- Initial Release

package/docs/examples.md

@@ -0,0 +1 @@
+# @twin.org/logging-models - Examples

package/docs/reference/classes/LogEntryHelper.md

@@ -0,0 +1,33 @@
+# Class: LogEntryHelper
+
+Helper class for log entry operations.
+
+## Constructors
+
+### new LogEntryHelper()
+
+> **new LogEntryHelper**(): [`LogEntryHelper`](LogEntryHelper.md)
+
+#### Returns
+
+[`LogEntryHelper`](LogEntryHelper.md)
+
+## Methods
+
+### translate()
+
+> `static` **translate**(`logEntry`): `undefined` \| `string`
+
+Translate the log entry.
+
+#### Parameters
+
+• **logEntry**: [`ILogEntry`](../interfaces/ILogEntry.md)
+
+The log entry.
+
+#### Returns
+
+`undefined` \| `string`
+
+The translated log entry if a translation can be found.

package/docs/reference/classes/MultiLoggingConnector.md

@@ -0,0 +1,134 @@
+# Class: MultiLoggingConnector
+
+Class for performing logging operations on multiple connectors.
+
+## Implements
+
+- [`ILoggingConnector`](../interfaces/ILoggingConnector.md)
+
+## Constructors
+
+### new MultiLoggingConnector()
+
+> **new MultiLoggingConnector**(`options`): [`MultiLoggingConnector`](MultiLoggingConnector.md)
+
+Create a new instance of MultiLoggingConnector.
+
+#### Parameters
+
+• **options**
+
+The options for the connector.
+
+• **options.loggingConnectorTypes**: `string`[]
+
+The logging connectors to multiplex.
+
+• **options.config?**: [`ILoggingLevelsConfig`](../interfaces/ILoggingLevelsConfig.md)
+
+The configuration for the logging connector.
+
+#### Returns
+
+[`MultiLoggingConnector`](MultiLoggingConnector.md)
+
+## Properties
+
+### NAMESPACE
+
+> `readonly` `static` **NAMESPACE**: `string` = `"multi"`
+
+The namespace for the logging connector.
+
+***
+
+### CLASS\_NAME
+
+> `readonly` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+#### Implementation of
+
+`ILoggingConnector.CLASS_NAME`
+
+## Methods
+
+### log()
+
+> **log**(`logEntry`): `Promise`\<`void`\>
+
+Log an entry to the connector.
+
+#### Parameters
+
+• **logEntry**: [`ILogEntry`](../interfaces/ILogEntry.md)
+
+The entry to log.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+[`ILoggingConnector`](../interfaces/ILoggingConnector.md).[`log`](../interfaces/ILoggingConnector.md#log)
+
+***
+
+### query()
+
+> **query**(`conditions`?, `sortProperties`?, `properties`?, `cursor`?, `pageSize`?): `Promise`\<`object`\>
+
+Query the log entries.
+
+#### Parameters
+
+• **conditions?**: `EntityCondition`\<[`ILogEntry`](../interfaces/ILogEntry.md)\>
+
+The conditions to match for the entities.
+
+• **sortProperties?**: `object`[]
+
+The optional sort order.
+
+• **properties?**: keyof [`ILogEntry`](../interfaces/ILogEntry.md)[]
+
+The optional keys to return, defaults to all.
+
+• **cursor?**: `string`
+
+The cursor to request the next page of entities.
+
+• **pageSize?**: `number`
+
+The maximum number of entities in a page.
+
+#### Returns
+
+`Promise`\<`object`\>
+
+All the entities for the storage matching the conditions,
+and a cursor which can be used to request more entities.
+
+##### entities
+
+> **entities**: `Partial`\<[`ILogEntry`](../interfaces/ILogEntry.md)\>[]
+
+The entities, which can be partial if a limited keys list was provided.
+
+##### cursor?
+
+> `optional` **cursor**: `string`
+
+An optional cursor, when defined can be used to call find to get more entities.
+
+#### Throws
+
+NotImplementedError if the implementation does not support retrieval.
+
+#### Implementation of
+
+[`ILoggingConnector`](../interfaces/ILoggingConnector.md).[`query`](../interfaces/ILoggingConnector.md#query)

package/docs/reference/classes/SilentLoggingConnector.md

@@ -0,0 +1,118 @@
+# Class: SilentLoggingConnector
+
+Class for performing logging operations to nowhere.
+
+## Implements
+
+- [`ILoggingConnector`](../interfaces/ILoggingConnector.md)
+
+## Constructors
+
+### new SilentLoggingConnector()
+
+> **new SilentLoggingConnector**(): [`SilentLoggingConnector`](SilentLoggingConnector.md)
+
+#### Returns
+
+[`SilentLoggingConnector`](SilentLoggingConnector.md)
+
+## Properties
+
+### NAMESPACE
+
+> `readonly` `static` **NAMESPACE**: `string` = `"silent"`
+
+The namespace for the logging connector.
+
+***
+
+### CLASS\_NAME
+
+> `readonly` **CLASS\_NAME**: `string`
+
+Runtime name for the class.
+
+#### Implementation of
+
+`ILoggingConnector.CLASS_NAME`
+
+## Methods
+
+### log()
+
+> **log**(`logEntry`): `Promise`\<`void`\>
+
+Log an entry to the connector.
+
+#### Parameters
+
+• **logEntry**: [`ILogEntry`](../interfaces/ILogEntry.md)
+
+The entry to log.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+#### Implementation of
+
+[`ILoggingConnector`](../interfaces/ILoggingConnector.md).[`log`](../interfaces/ILoggingConnector.md#log)
+
+***
+
+### query()
+
+> **query**(`conditions`?, `sortProperties`?, `properties`?, `cursor`?, `pageSize`?): `Promise`\<`object`\>
+
+Query the log entries.
+
+#### Parameters
+
+• **conditions?**: `EntityCondition`\<[`ILogEntry`](../interfaces/ILogEntry.md)\>
+
+The conditions to match for the entities.
+
+• **sortProperties?**: `object`[]
+
+The optional sort order.
+
+• **properties?**: keyof [`ILogEntry`](../interfaces/ILogEntry.md)[]
+
+The optional keys to return, defaults to all.
+
+• **cursor?**: `string`
+
+The cursor to request the next page of entities.
+
+• **pageSize?**: `number`
+
+The maximum number of entities in a page.
+
+#### Returns
+
+`Promise`\<`object`\>
+
+All the entities for the storage matching the conditions,
+and a cursor which can be used to request more entities.
+
+##### entities
+
+> **entities**: `Partial`\<[`ILogEntry`](../interfaces/ILogEntry.md)\>[]
+
+The entities, which can be partial if a limited keys list was provided.
+
+##### cursor?
+
+> `optional` **cursor**: `string`
+
+An optional cursor, when defined can be used to call find to get more entities.
+
+#### Throws
+
+NotImplementedError if the implementation does not support retrieval.
+
+#### Implementation of
+
+[`ILoggingConnector`](../interfaces/ILoggingConnector.md).[`query`](../interfaces/ILoggingConnector.md#query)

package/docs/reference/index.md

@@ -0,0 +1,25 @@
+# @twin.org/logging-models
+
+## Classes
+
+- [MultiLoggingConnector](classes/MultiLoggingConnector.md)
+- [SilentLoggingConnector](classes/SilentLoggingConnector.md)
+- [LogEntryHelper](classes/LogEntryHelper.md)
+
+## Interfaces
+
+- [ILogEntry](interfaces/ILogEntry.md)
+- [ILoggingComponent](interfaces/ILoggingComponent.md)
+- [ILoggingConnector](interfaces/ILoggingConnector.md)
+- [ILoggingLevelsConfig](interfaces/ILoggingLevelsConfig.md)
+- [ILoggingCreateRequest](interfaces/ILoggingCreateRequest.md)
+- [ILoggingListRequest](interfaces/ILoggingListRequest.md)
+- [ILoggingListResponse](interfaces/ILoggingListResponse.md)
+
+## Type Aliases
+
+- [LogLevel](type-aliases/LogLevel.md)
+
+## Variables
+
+- [LoggingConnectorFactory](variables/LoggingConnectorFactory.md)

package/docs/reference/interfaces/ILogEntry.md

@@ -0,0 +1,55 @@
+# Interface: ILogEntry
+
+Interface describing a log entry.
+
+## Properties
+
+### level
+
+> **level**: [`LogLevel`](../type-aliases/LogLevel.md)
+
+The level of the error being logged.
+
+***
+
+### source
+
+> **source**: `string`
+
+The source of the log entry.
+
+***
+
+### ts?
+
+> `optional` **ts**: `number`
+
+The timestamp of the log entry, if left blank will be populated by the connector.
+
+***
+
+### message
+
+> **message**: `string`
+
+The message.
+
+***
+
+### error?
+
+> `optional` **error**: `IError`
+
+Optional error details.
+
+***
+
+### data?
+
+> `optional` **data**: `object`
+
+Optional data for the message.
+
+#### Index Signature
+
+ \[`key`: `string`\]: `unknown`

package/docs/reference/interfaces/ILoggingComponent.md

@@ -0,0 +1,84 @@
+# Interface: ILoggingComponent
+
+Interface describing a logging contract.
+
+## Extends
+
+- `IComponent`
+
+## Methods
+
+### log()
+
+> **log**(`logEntry`): `Promise`\<`void`\>
+
+Log an entry to the component.
+
+#### Parameters
+
+• **logEntry**: [`ILogEntry`](ILogEntry.md)
+
+The entry to log.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+Nothing.
+
+***
+
+### query()
+
+> **query**(`level`?, `source`?, `timeStart`?, `timeEnd`?, `cursor`?, `pageSize`?): `Promise`\<`object`\>
+
+Query the log entries.
+
+#### Parameters
+
+• **level?**: [`LogLevel`](../type-aliases/LogLevel.md)
+
+The level of the log entries.
+
+• **source?**: `string`
+
+The source of the log entries.
+
+• **timeStart?**: `number`
+
+The inclusive time as the start of the log entries.
+
+• **timeEnd?**: `number`
+
+The inclusive time as the end of the log entries.
+
+• **cursor?**: `string`
+
+The cursor to request the next page of entities.
+
+• **pageSize?**: `number`
+
+The maximum number of entities in a page.
+
+#### Returns
+
+`Promise`\<`object`\>
+
+All the entities for the storage matching the conditions,
+and a cursor which can be used to request more entities.
+
+##### entities
+
+> **entities**: [`ILogEntry`](ILogEntry.md)[]
+
+The entities, which can be partial if a limited keys list was provided.
+
+##### cursor?
+
+> `optional` **cursor**: `string`
+
+An optional cursor, when defined can be used to call find to get more entities.
+
+#### Throws
+
+NotImplementedError if the implementation does not support retrieval.