From 1812f25d8ada0417063f4513e0f9c980b1978d63 Mon Sep 17 00:00:00 2001 From: lxsang Date: Tue, 16 Jun 2020 18:02:17 +0200 Subject: [PATCH] add docs on coreapi --- src/core/Announcerment.ts | 4 +- src/core/BaseModel.ts | 2 +- src/core/BaseService.ts | 8 +- src/core/core.ts | 360 ++++++++++++++++++++++++++----- src/core/db.ts | 7 +- src/core/handles/RemoteHandle.ts | 2 +- 6 files changed, 312 insertions(+), 71 deletions(-) diff --git a/src/core/Announcerment.ts b/src/core/Announcerment.ts index 83e3ec5..c613fed 100644 --- a/src/core/Announcerment.ts +++ b/src/core/Announcerment.ts @@ -231,12 +231,12 @@ namespace OS { */ export namespace announcer { /** - * The global announcer object tha manages global events + * The global announcer object that manages global events * and callbacks */ export var observable: API.Announcer = new API.Announcer(); /** - * This variable is used to allocate the `id` of message + * This variable is used to allocate the `id` of all messages * passing between publishers and subscribers in the * system announcement */ diff --git a/src/core/BaseModel.ts b/src/core/BaseModel.ts index 66b8c01..6aa52ef 100644 --- a/src/core/BaseModel.ts +++ b/src/core/BaseModel.ts @@ -252,7 +252,7 @@ namespace OS { static singleton: boolean; /** - * The javacript of css dependencies of the model. All dependencies + * The javascript or css files that the model depends on. All dependencies * will be loaded before the model is rendered * * @static diff --git a/src/core/BaseService.ts b/src/core/BaseService.ts index cf2b08e..bee6ac3 100644 --- a/src/core/BaseService.ts +++ b/src/core/BaseService.ts @@ -19,7 +19,7 @@ namespace OS { export namespace application { /** * Services are processes that run in the background and - * are waken up in certain circumstances such as global + * are waken up in certain circumstances such as by global * events or user interactions. * * Each service takes an entry in the system tray menu @@ -67,7 +67,7 @@ namespace OS { domel: HTMLElement; /** - * Reference to the timer that periodically execute the callback + * Reference to the timer that periodically executes the callback * defined in [[watch]]. * * @private @@ -77,7 +77,7 @@ namespace OS { private timer: number; /** - * Reference to th system tray menu + * Reference to the system tray menu * * @type {HTMLElement} * @memberof BaseService @@ -85,7 +85,7 @@ namespace OS { holder: HTMLElement; /** - * Place holder for service select callback + * Placeholder for service select callback * * @memberof BaseService */ diff --git a/src/core/core.ts b/src/core/core.ts index 93464c3..bdde58f 100644 --- a/src/core/core.ts +++ b/src/core/core.ts @@ -842,41 +842,210 @@ namespace OS { } } /** + * The namespace API is dedicated to the definition of the core system APIs + * used by AntOS and its applications. The following core APIs are defined: * + * - The AntOS announcement system + * - Virtual File system + * - Virtual Database + * - Low-level REST based client-server communication + * - Dependencies management + * - System utilities + * + * These APIs are considered as middle-ware that abstracts the client-server + * communication and provide the application layer with a standardized APIs + * for file/database access, system events handling (announcement), automatic + * dependencies resolving, etc. */ export namespace API { /** - * + * AntOS package meta-data type definition * * @export - * @interface PackageType + * @interface PackageMetaType */ export interface PackageMetaType { - app: string; + /** + * The application class name, if the package has only services + * this property is ignored and [[pkgname]] should be specified + * + * @type {string} + * @memberof PackageMetaType + */ + app?: string; + + /** + * Package name, in case of [[app]] being undefined, this property + * need to be specified + * + * @type {string} + * @memberof PackageMetaType + */ + pkgname?: string; + + /** + * Package category + * + * @type {string} + * @memberof PackageMetaType + */ category: string; + + /** + * Package description string + * + * @type {string} + * @memberof PackageMetaType + */ description: string; + + /** + * List of services that is attached to the + * package + * + * @type {string[]} + * @memberof PackageMetaType + */ services?: string[]; + + /** + * CSS icon class of the package + * + * @type {string} + * @memberof PackageMetaType + */ iconclass?: string; + + /** + * Package information + * + * @type {{ + * author: string; + * email: string; + * [propName: string]: any; + * }} + * @memberof PackageMetaType + */ info: { + /** + * Author of the package + * + * @type {string} + */ author: string; + + /** + * Author's email + * + * @type {string} + */ email: string; [propName: string]: any; }; + + /** + * Application-specific locale definition. When the system locale changes, + * translatable texts inside the application will be first translated using + * the locale dictionary defined in the package meta-data. If no translation + * found, the system locale dictionary is used instead. + * + * A local dictionary definition should be in the following format: + * + * ```typescript + * { + * [locale_name: string]: { + * [origin_string]: string // translation string + * } + * } + * ``` + * + * Example of locale dictionaries: + * + * ```typescript + * { + * "en_GB": { + * "Cancel": "Cancel", + * "Modify": "Modify" + * }, + * "fr_FR": { + * "Cancel": "Annuler", + * "Modify": "Modifier" + * } + * } + * ``` + * + * @type {{ [index: string]: GenericObject }} locale dictionaries + * @memberof PackageMetaType + */ locales: { [index: string]: GenericObject }; + + /** + * Mime types supported by the packages, regular expression can be used + * to specified a range of mimes in common + * + * @type {string[]} + * @memberof PackageMetaType + */ mimes: string[]; + + /** + * Package (application) name + * + * @type {string} + * @memberof PackageMetaType + */ name: string; + + /** + * VFS path to package installation location + * + * @type {string} + * @memberof PackageMetaType + */ path: string; + + /** + * Package version, should be in a format conforming + * to the version definition in [[Version]] class + * + * @type {string} + * @memberof PackageMetaType + */ version: string; [propName: string]: any; } + /** + * Placeholder to store all loaded shared libraries. Once + * a shared library is firstly loaded, its identity will be + * stored in this variable. Based on this information, in + * the next use of the library, the system knows that the + * library is already loaded and ready to use. + * + * A shared library can be a javascript or a CSS file. + */ export const shared: GenericObject = {}; + /** + * Placeholder for all global search handles registered to the system. + * These callbacks will be called when user performs the search operation + * in the spotlight UI. + * + * Applications can define their own search handle to provide the spotlight UI + * with additional search results + * + */ export const searchHandle: GenericObject<(text: string) => any[]> = {}; + /** + * Placeholder of the current system locale dictionary, the system uses + * this dictionary to translate all translatable texts to the current + * locale language + */ export var lang: GenericObject = {}; /** - * + * Re-export the system announcement [[getMID]] function to the + * core API * * @export * @returns {number} @@ -886,12 +1055,15 @@ namespace OS { } /** + * REST-based API. * + * Perform a POST request to the server. Data exchanged + * is in `application/json` * * @export - * @param {string} p - * @param {*} d - * @returns {Promise} + * @param {string} p the server URI + * @param {*} d data object that will be converted to JSON + * @returns {Promise} a promise on the result data */ export function post(p: string, d: any): Promise { return new Promise(function (resolve, reject) { @@ -926,11 +1098,15 @@ namespace OS { } /** + * REST-based API. * + * Perform a GET request and read back the data in + * `ArrayBuffer` (binary) format. This is useful for + * binary data reading * * @export - * @param {string} p - * @returns {Promise} + * @param {string} p resource URI + * @returns {Promise} a promise on the returned binary data */ export function blob(p: string): Promise { return new Promise(function (resolve, reject) { @@ -953,11 +1129,13 @@ namespace OS { } /** + * REST-based API. * + * Send file to server * * @export - * @param {string} p - * @param {string} d + * @param {string} p resource URI + * @param {string} d VFS path of the destination file * @returns {Promise} */ export function upload(p: string, d: string): Promise { @@ -997,11 +1175,13 @@ namespace OS { } /** + * REST-based API. * + * Download a file * * @export - * @param {string} name - * @param {*} b + * @param {string} name file name + * @param {*} b file content */ export function saveblob(name: string, b: any): void { const url = window.URL.createObjectURL(b); @@ -1016,11 +1196,13 @@ namespace OS { } /** - * + * Helper function to trigger the global `loading` + * event. This event should be triggered in the + * beginning of a heavy task * * @export - * @param {number} q - * @param {string} p + * @param {number} q message id, see [[mid]] + * @param {string} p message string */ export function loading(q: number, p: string): void { announcer.trigger("loading", { @@ -1031,12 +1213,15 @@ namespace OS { } /** - * + * Helper function to trigger the global `loaded` + * event: This event should be triggered in the + * end of a heavy task that has previously triggered + * the `loading` event * * @export - * @param {number} q - * @param {string} p - * @param {string} m + * @param {number} q the message id of the corresponding `loading` event + * @param {string} p the message string + * @param {string} m message status (`OK` of `FAIL`) */ export function loaded(q: number, p: string, m: string): void { announcer.trigger("loaded", { @@ -1054,7 +1239,7 @@ namespace OS { * @param {string} [t=undefined] the response data type: * - jsonp: the response is an json object * - script: the response is a javascript code - * - xm, html: the response is a XML/HTNL object + * - xm, html: the response is a XML/HTML object * - text: plain text * @returns {Promise} a Promise on the requested data */ @@ -1082,22 +1267,28 @@ namespace OS { } /** + * REST-based API * + * Perform a GET operation and executed the returned + * content as javascript * * @export - * @param {string} p - * @returns {Promise} + * @param {string} p URI resource + * @returns {Promise} promise on the executed content */ export function script(p: string): Promise { return API.get(p, "script"); } /** + * REST-based API * + * Get the content of a global asset resource stored + * in `os://resources/` * * @export - * @param {string} r - * @returns {Promise} + * @param {string} r relative path to the resource + * @returns {Promise} promise on the returned content */ export function resource(r: string): Promise { const path = `resources/${r}`; @@ -1105,10 +1296,11 @@ namespace OS { } /** - * + * Helper function to verify whether a shared library + * is loaded and ready to use * * @export - * @param {string} l + * @param {string} l path to the library * @returns {boolean} */ export function libready(l: string): boolean { @@ -1116,11 +1308,11 @@ namespace OS { } /** - * + * Load a shared library if not ready * * @export - * @param {string} l - * @returns {Promise} + * @param {string} l VFS path to the library + * @returns {Promise} a promise on the result data */ export function requires(l: string): Promise { return new Promise(function (resolve, reject) { @@ -1165,10 +1357,10 @@ namespace OS { } /** - * + * Synchronously load a list of shared libraries * * @export - * @param {string[]} libs + * @param {string[]} libs list of shared libraries * @returns {Promise} */ export function require(libs: string[]): Promise { @@ -1176,23 +1368,34 @@ namespace OS { if (!(libs.length > 0)) { return resolve(); } - announcer.observable.one("sharedlibraryloaded", function (l) { + announcer.observable.one("sharedlibraryloaded", async function ( + l + ) { libs.splice(0, 1); - return API.require(libs) - .catch((e: Error) => reject(__e(e))) - .then((r: any) => resolve(r)); + let r: void; + try { + r = await API.require(libs); + } catch (e) { + r = reject(__e(e)); + } + return resolve(r); }); return API.requires(libs[0]).catch((e: Error) => reject(__e(e)) ); }); } + /** + * The namespace packages is dedicated to all package management + * related APIs. + */ export namespace packages { /** - * + * Fetch the package meta-data from the server * * @export - * @returns {Promise} + * @returns {Promise} Promise on a [[RequestResult]]. + * A success request result should contain a list of [[PackageMetaType]] */ export function fetch(): Promise { return API.handle.packages({ @@ -1211,7 +1414,8 @@ namespace OS { } /** - * + * Request the server to regenerate the package + * caches * * @export * @returns {Promise} @@ -1234,22 +1438,42 @@ namespace OS { } /** - * + * Save the current user setting * * @export - * @returns {Promise} + * @returns {Promise} promise on a [[RequestResult]] */ export function setting(): Promise { return API.handle.setting(); } /** - * + * An apigateway allows client side to execute a custom server-side + * script and get back the result. This gateway is particularly + * useful in case of performing a task that is not provided by the core + * API * * @export - * @param {GenericObject} d - * @param {boolean} ws - * @returns {Promise} + * @param {GenericObject} d execution indication, provided only when ws is `false` + * otherwise, `d` should be written directly to the websocket stream as JSON object. + * Two possible formats of `d`: + * ```text + * execute an server-side script file: + * + * { + * path: [VFS path], + * parameters: [parameters of the server-side script] + * } + * + * or, execute directly a snippet of server-side script: + * + * { code: [server-side script code snippet as string] } + * + * ``` + * + * @param {boolean} ws flag indicate whether to use websocket for the connection + * to the gateway API. In case of streaming data, the websocket is preferred + * @returns {Promise} a promise on the result object (any) */ export function apigateway( d: GenericObject, @@ -1259,10 +1483,15 @@ namespace OS { } /** + * Perform the global search operation when user enter + * text in spotlight. * + * This function will call all the search handles stored + * in [[searchHandle]] and build the search result based + * on output of these handle * * @export - * @param {string} text + * @param {string} text text to search * @returns {any[]} */ export function search(text: string): any[] { @@ -1283,11 +1512,11 @@ namespace OS { } /** - * + * Register a search handle to the global [[searchHandle]] * * @export - * @param {string} name - * @param {(text: string) => any[]} fn + * @param {string} name handle name string + * @param {(text: string) => any[]} fn search handle */ export function onsearch( name: string, @@ -1299,10 +1528,14 @@ namespace OS { } /** - * + * Set the current system locale: This function will + * find and load the locale dictionary definition file in the + * system asset resource, then trigger the global event + * `systemlocalechange` to translated all translatable text + * to the target language * * @export - * @param {string} name + * @param {string} name locale name, e.g. `en_GB` * @returns {Promise} */ export function setLocale(name: string): Promise { @@ -1321,10 +1554,12 @@ namespace OS { } /** - * + * Return an error Object: AntOS use this function to + * collect information (stack trace) from user reported + * error. * * @export - * @param {(string | FormattedString)} n + * @param {(string | FormattedString)} n error string * @returns {Error} */ export function throwe(n: string | FormattedString): Error { @@ -1338,10 +1573,10 @@ namespace OS { } /** - * + * Set value to the system clipboard * * @export - * @param {string} v + * @param {string} v clipboard value * @returns {boolean} */ export function setClipboard(v: string): boolean { @@ -1353,10 +1588,10 @@ namespace OS { } /** - * + * Get the clipboard data * * @export - * @returns {Promise} + * @returns {Promise} Promise on the clipboard data */ export function getClipboard(): Promise { return new Promise(function (resolve, reject) { @@ -1372,7 +1607,18 @@ namespace OS { } /** + * A switcher object is a special object in which + * each object's property is a boolean option. All object's + * properties are mutual exclusive. It means that when a property + * is set to true, all other properties will be reset to false. * + * Example: + * + * ```typescript + * let view = API.switcher("tree", "list", "icon") + * view.tree = true // view.list = false and view.icon = false + * view.list = true // view.tree = false and view.icon = false + * ``` * * @export * @returns {*} diff --git a/src/core/db.ts b/src/core/db.ts index be61761..c0c065b 100644 --- a/src/core/db.ts +++ b/src/core/db.ts @@ -1,8 +1,3 @@ -/* - * decaffeinate suggestions: - * DS102: Remove unnecessary code created because of implicit returns - * Full docs: https://github.com/decaffeinate/decaffeinate/blob/master/docs/suggestions.md - */ // Copyright 2017-2018 Xuan Sang LE // AnTOS Web desktop is is licensed under the GNU General Public @@ -19,7 +14,7 @@ // 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/. +// along with this program. If not, see https://www.gnu.org/licenses/. namespace OS { export namespace API { diff --git a/src/core/handles/RemoteHandle.ts b/src/core/handles/RemoteHandle.ts index 75c70e6..8b3e5ab 100644 --- a/src/core/handles/RemoteHandle.ts +++ b/src/core/handles/RemoteHandle.ts @@ -152,7 +152,7 @@ namespace OS { * * @export * @param {string} p a VFS file path e.g. home://test/ - * @returns {Promise} A promise on a [[RequestResult + * @returns {Promise} A promise on a [[RequestResult]] * which contains an error or a list of FileInfoType */ export function scandir(p: string): Promise {