From ca06e5c827e34561b2de625c94daed179b49f106 Mon Sep 17 00:00:00 2001 From: Norman Breau Date: Sun, 4 Feb 2024 20:44:41 -0400 Subject: [PATCH] docs: TSDocs --- src/AbstractFuseAPIFactory.ts | 6 +++ src/AbstractFuseLoggerFactory.ts | 6 +++ src/FuseError.ts | 63 +++++++++++++++++++++++++++++++- src/FuseLoggerFactory.ts | 12 ++++++ src/FuseLoggerLevel.ts | 3 ++ src/FusePermissionState.ts | 3 ++ src/FusePlugin.ts | 32 +++++++++++++++- src/FuseResponseReader.ts | 19 ++++++++++ src/FuseSerializer.ts | 11 ++++++ src/TSerializable.ts | 17 ++++++++- src/Version.ts | 47 +++++++++++++++++++++++- 11 files changed, 213 insertions(+), 6 deletions(-) diff --git a/src/AbstractFuseAPIFactory.ts b/src/AbstractFuseAPIFactory.ts index bfe7455..9736f59 100644 --- a/src/AbstractFuseAPIFactory.ts +++ b/src/AbstractFuseAPIFactory.ts @@ -22,5 +22,11 @@ import { Platform } from './Platform'; * An factory class that defines the base signature for creating a FuseAPI bridge object. */ export abstract class AbstractFuseAPIFactory { + + /** + * Implement a create API that returns a FuseAPI for the given Platform + * + * @param platform + */ public abstract create(platform: Platform): FuseAPI; } diff --git a/src/AbstractFuseLoggerFactory.ts b/src/AbstractFuseLoggerFactory.ts index 17f7688..cb8ed87 100644 --- a/src/AbstractFuseLoggerFactory.ts +++ b/src/AbstractFuseLoggerFactory.ts @@ -17,8 +17,14 @@ limitations under the License. import { IFuseLogger } from "./IFuseLogger"; +/** + * An FuseLogger factory for creating logging instances. + */ export abstract class AbstractFuseLoggerFactory { public constructor() {} + /** + * Implement to create a FuseLogger + */ public abstract create(): IFuseLogger; } diff --git a/src/FuseError.ts b/src/FuseError.ts index ae5deab..38d4f96 100644 --- a/src/FuseError.ts +++ b/src/FuseError.ts @@ -15,10 +15,12 @@ See the License for the specific language governing permissions and limitations under the License. */ -import { FuseSerializer } from "./FuseSerializer"; import { ISerializable } from "./ISerializable"; -import { TFuseSerializable, TSerializable } from "./TSerializable"; +import { TFuseSerializable } from "./TSerializable"; +/** + * A union of acceptable type for error causes. + */ export type TFuseErrorCause = string | Error | FuseError | null; interface _IFuseErrorSerialized { @@ -28,14 +30,26 @@ interface _IFuseErrorSerialized { stack?: string; } +/** + * A type that represents a fuse error in a serialized state. + */ export type IFuseErrorSerialized = TFuseSerializable<_IFuseErrorSerialized>; +/** + * A structured error object. + */ export class FuseError extends Error implements ISerializable { private $domain: string; private $message: string; private $cause: TFuseErrorCause; private $code: number; + /** + * @param domain The error domain, usually represents a library, class, or plugin. + * @param message The error message + * @param cause The underlying cause of the error. May be null. + * @param code An error code. May be null. + */ public constructor(domain: string, message: string, cause?: TFuseErrorCause, code?: number) { super(message); this.name = this.constructor.name; @@ -45,22 +59,37 @@ export class FuseError extends Error implements ISerializable { this.$cause = cause || null; } + /** + * @returns The error message + */ public getMessage(): string { return this.$message; } + /** + * @returns The error domain, usually representing a library, class, or plugin. + */ public getDomain(): string { return this.$domain; } + /** + * @returns The error code + */ public getCode(): number { return this.$code; } + /** + * @returns The underlying cause of the error, if known. May be null. + */ public getCause(): TFuseErrorCause | null { return this.$cause; } + /** + * @returns A serialized object representing an error. + */ public serialize(): IFuseErrorSerialized { return { domain: this.getDomain(), @@ -70,6 +99,30 @@ export class FuseError extends Error implements ISerializable { }; } + /** + * Wraps the given object into a FuseError object. Accepts several different + * formats, which influences the behaviour of this method. + * + * If the input is a string, a FuseError object is created with the string as + * the error message of an unknown domain. + * + * If the input is a FuseError, then this method does nothing but passes through + * the FuseError. The returned FuseError is the input FuseError, a copy is not made. + * + * If the input is an Error, then a FuseError is created using the name as the + * domain, and it's message as the error message. The error object is also used + * as the FuseError's cause parameter. + * + * If the input is of the shape of IFuseErrorSerialized, then the object is + * deserialized into a FuseError instance. + * + * If any other type of object is given, an console error message will be + * printed and a "FuseError" domain error will be returned stating the error + * is not wrappable. + * + * @param error A value that can represent an error + * @returns A FuseError instance + */ public static wrap(error: string | Error | FuseError | IFuseErrorSerialized | unknown): FuseError { let ferr: FuseError = null; if (typeof error === 'string') { @@ -92,6 +145,12 @@ export class FuseError extends Error implements ISerializable { return ferr; } + /** + * Deserializes and creates a new FuseError instance + * + * @param error The serialized error object + * @returns A FuseError instance + */ public static fromSerialized(error: IFuseErrorSerialized): FuseError { return new FuseError(error.domain, error.message, null, error.code); } diff --git a/src/FuseLoggerFactory.ts b/src/FuseLoggerFactory.ts index fb3aad3..4f05cdd 100644 --- a/src/FuseLoggerFactory.ts +++ b/src/FuseLoggerFactory.ts @@ -21,13 +21,25 @@ import { Platform } from "./Platform"; import {IOSFuseLogger} from './ios/IOSFuseLogger'; import {AndroidFuseLogger} from './android/AndroidFuseLogger'; +/** + * A default logger factory for creating loggers for the given platform. + */ export class FuseLoggerFactory { private $platform: Platform; + /** + * + * @param platform The current Platform in this runtime environment + */ public constructor(platform: Platform) { this.$platform = platform; } + /** + * Creates a FuseLogger for the current Platform. + * + * @returns {IFuseLogger} + */ public create(): IFuseLogger { switch (this.$platform) { case Platform.IOS: diff --git a/src/FuseLoggerLevel.ts b/src/FuseLoggerLevel.ts index cb721e7..16d44b9 100644 --- a/src/FuseLoggerLevel.ts +++ b/src/FuseLoggerLevel.ts @@ -15,6 +15,9 @@ See the License for the specific language governing permissions and limitations under the License. */ +/** + * A bitmask option of logger levels + */ export enum FuseLoggerLevel { SILENT = 0, DEBUG = 1, diff --git a/src/FusePermissionState.ts b/src/FusePermissionState.ts index efadaf4..1a82789 100644 --- a/src/FusePermissionState.ts +++ b/src/FusePermissionState.ts @@ -15,6 +15,9 @@ See the License for the specific language governing permissions and limitations under the License. */ +/** + * A set of constants representing permission states. + */ export enum FusePermissionState { GRANTED, REQUIRES_JUSTIFICATION, diff --git a/src/FusePlugin.ts b/src/FusePlugin.ts index 23d750f..dff297f 100644 --- a/src/FusePlugin.ts +++ b/src/FusePlugin.ts @@ -41,17 +41,31 @@ export abstract class FusePlugin { /** * Creates the API bridge - * @param platform + * @param platform * @returns */ protected _createAPI(platform: Platform): FuseAPI { return this._getAPIFactory().create(platform); } + /** + * @virtual + * + * @remarks + * + * Create a concrete {@link FuseAPI} factory capable of creating FuseAPI + * instance for the current runtime. + * + * @returns A concrete {@link FuseAPI} Factory + */ protected _createAPIFactory(): AbstractFuseAPIFactory { return null; } + /** + * + * @returns The concrete API factory + */ protected _getAPIFactory(): AbstractFuseAPIFactory { return this.$apiFactory; } @@ -111,13 +125,14 @@ export abstract class FusePlugin { /** * Returns the FuseContext * - * @returns + * @returns The current context */ public getContext(): FuseContext { return this.$context; } /** + * @remarks * * Concrete classes should implement and return a string that uniquely represents this plugin. * The string must conform to URL fragment rules. It shall only contain the following characters: @@ -126,6 +141,7 @@ export abstract class FusePlugin { * - dots and hyphens * * @abstract + * @virtual */ protected abstract _getID(): string; @@ -150,6 +166,18 @@ export abstract class FusePlugin { return await this._getAPI(apiOpts).execute(this.getID(), method, contentType, data); } + /** + * @remarks + * This is useful when you want to use an API as a callback, without exposing + * the plugin implementation. The returned function is a bounded function. + * When invoked, it will call on the API endpoint and returns a {@link FuseAPIResponse} + * asynchronously. + * + * @sealed + * @param route The API end point + * @param serializer The serializer to use. Defaults to {@link FuseSerializer} which is a sensible serializer. + * @returns A context-binding function that can be given to another object. + */ protected _createAPIBridge(route: string, serializer?: FuseSerializer): TAPIBridgeFunction { if (!serializer) { serializer = new FuseSerializer(); diff --git a/src/FuseResponseReader.ts b/src/FuseResponseReader.ts index 04f118a..e4df508 100644 --- a/src/FuseResponseReader.ts +++ b/src/FuseResponseReader.ts @@ -22,6 +22,13 @@ limitations under the License. export class FuseResponseReader { private constructor() {} + /** + * @remarks + * Reads the data buffer as a string + * + * @param data input data + * @returns The buffer contents as a string + */ public static async readAsText(data: ArrayBuffer): Promise { return await new Promise((resolve, reject) => { let reader: FileReader = new FileReader(); @@ -35,6 +42,18 @@ export class FuseResponseReader { }); } + /** + * @remarks + * Reads the given data buffer as a JSON object. The JSON object + * can be typed as T generic. No validations occurs on whether the given + * data is actually a type of T. + * + * @throws {SyntaxError} + * If data is not parseable as JSON. + * + * @param data input data + * @returns The buffer contents as a JSON object. + */ public static async readAsJSON(data: ArrayBuffer): Promise { let str: string = await this.readAsText(data); return JSON.parse(str); diff --git a/src/FuseSerializer.ts b/src/FuseSerializer.ts index cdb494b..ef655b0 100644 --- a/src/FuseSerializer.ts +++ b/src/FuseSerializer.ts @@ -18,6 +18,10 @@ limitations under the License. import { ISerializable } from "./ISerializable"; import { TSerializable } from "./TSerializable"; +/** + * A class to serialize several different types of objects into a data structure + * that can be reconstructed across the Fuse API bridge. + */ export class FuseSerializer { public constructor() {} @@ -57,6 +61,13 @@ export class FuseSerializer { return obj.toISOString(); } + /** + * Serializes the given object into a blob. + * + * @param obj A supported serializable object. See {@link TSerializable} for + * a list of currently supported types + * @returns A serialized blob + */ public serialize(obj: TSerializable): Blob { if (obj === null || obj === undefined) { return null; diff --git a/src/TSerializable.ts b/src/TSerializable.ts index f66bb3e..33febb8 100644 --- a/src/TSerializable.ts +++ b/src/TSerializable.ts @@ -19,8 +19,23 @@ import {ISerializable} from './ISerializable'; /** * Type of supported serializable obejcts that can go over the Fuse API bridge. + * + * Currently the supported types are: + * - Error + * - Blob + * - ArrayBuffer + * - Primitives (string, number, boolean) + * - Date + * - Any object or array consisting exclusively of the above types */ -export type TSerializable = Error | string | Blob | ArrayBuffer| ISerializable | number | boolean | Date | TSerializable[] | {[key: string]: TSerializable }; +export type TSerializable = Error | + string | + Blob | + ArrayBuffer | + ISerializable | + number | + boolean | + Date | TSerializable[] | {[key: string]: TSerializable }; /** * Utility type wrap, useful if you have a concrete interface of TSerializable properties. diff --git a/src/Version.ts b/src/Version.ts index dea793d..a24012a 100644 --- a/src/Version.ts +++ b/src/Version.ts @@ -15,6 +15,9 @@ See the License for the specific language governing permissions and limitations under the License. */ +/** + * A class that represents a {@link https://semver.org/} versioning. + */ export class Version { private $major: number; private $minor: number; @@ -30,6 +33,16 @@ export class Version { this.$patch = patch || 0; } + /** + * @remarks + * Parses a semver-formatted version string and creates a Version object. + * Does not support pre-release labels, which will be chopped off. + * If any dot notation segment is missing or is not parseable as an integer, + * it will default to 0. + * + * @param version Semver formatted version string + * @returns A version object + */ public static parseVersionString(version: string): Version { let parts: string[] = version.split('.'); @@ -52,27 +65,59 @@ export class Version { return new Version(major, minor, patch); } + /** + * @sealed + * @returns The major component of this version + */ public getMajor(): number { return this.$major; } + /** + * @sealed + * @returns The minor component of this version + */ public getMinor(): number { return this.$minor; } + /** + * @sealed + * @returns The patch component of this version + */ public getPatch(): number { return this.$patch; } + /** + * @sealed + * @returns A semver-formatted string + */ public toString(): string { return `${this.$major}.${this.$minor}.${this.$patch}`; } - + /** + * @sealed + * @param b The right side version + * @remarks + * This is the equivilant in using `Version.compare(this, b)`. + * See {@link copmare} for more details. + */ public compare(b: Version): number { return Version.compare(this, b); } + /** + * @remarks + * Compares this version with another. If left side is greater than right side, + * {@link GREATER_THAN} is returned. If they are equal, {@link EQUAL} is returned. + * Otherwise, {@link LESS_THAN} is returned. + * + * @param lhs The left side version + * @param rhs The right side version + * @returns + */ public static compare(lhs: Version, rhs: Version): number { if (lhs.$major === rhs.$major && lhs.$minor === rhs.$minor && lhs.$patch === rhs.$patch) { return Version.EQUAL;