From 4a941f046725ae49f95a04914b6d80b4b77ae640 Mon Sep 17 00:00:00 2001 From: lxsang Date: Thu, 18 Jun 2020 17:09:00 +0200 Subject: [PATCH] add more docs --- src/bootstrap.ts | 8 +- src/core/BaseDialog.ts | 16 +- src/core/BaseService.ts | 3 + src/core/gui.ts | 317 +++++++++++---- src/core/handles/RemoteHandle.ts | 2 +- src/core/pm.ts | 43 ++- src/core/settings.ts | 295 ++++++++++++-- src/core/vfs.ts | 639 +++++++++++++++++++++++-------- 8 files changed, 1024 insertions(+), 299 deletions(-) diff --git a/src/bootstrap.ts b/src/bootstrap.ts index c9e90c5..ef8204d 100644 --- a/src/bootstrap.ts +++ b/src/bootstrap.ts @@ -1,9 +1,3 @@ -/* - * decaffeinate suggestions: - * DS102: Remove unnecessary code created because of implicit returns - * DS208: Avoid top-level this - * 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 @@ -22,7 +16,7 @@ // You should have received a copy of the GNU General Public License //along with this program. If not, see https://www.gnu.org/licenses/. -this.onload = function () { +Ant.onload = function () { $(document).on( "webkitfullscreenchange mozfullscreenchange fullscreenchange MSFullscreenChange", () => (Ant.OS.GUI.fullscreen = !Ant.OS.GUI.fullscreen) diff --git a/src/core/BaseDialog.ts b/src/core/BaseDialog.ts index 89cd7a6..cffe28b 100644 --- a/src/core/BaseDialog.ts +++ b/src/core/BaseDialog.ts @@ -448,6 +448,14 @@ namespace OS { /** * A Calendar dialog allows user to select a date * + * Input data: + * + * ```typescript + * { + * title: string // window title + * } + * ``` + * * @export * @class CalendarDialog * @extends {BasicDialog} @@ -456,14 +464,6 @@ namespace OS { /** * Creates an instance of CalendarDialog. * - * Input data: - * - * ```typescript - * { - * title: string // window title - * } - * ``` - * * Callback data: a Date object represent the selected date * * diff --git a/src/core/BaseService.ts b/src/core/BaseService.ts index bee6ac3..3ebf230 100644 --- a/src/core/BaseService.ts +++ b/src/core/BaseService.ts @@ -27,6 +27,9 @@ namespace OS { * to access to service visual contents such as: options, * task performing based on user interaction, etc. * + * Services are singleton processes, there is only + * one process of a service at a time + * * @export * @abstract * @class BaseService diff --git a/src/core/gui.ts b/src/core/gui.ts index f8b1687..890f6ee 100644 --- a/src/core/gui.ts +++ b/src/core/gui.ts @@ -17,41 +17,118 @@ // along with this program. If not, see https://www.gnu.org/licenses/. namespace OS { /** - * + * This namespace is dedicated to all APIs related to AntOS UI system, + * these API are called AFX APIs which handle: + * - The mouse and keyboard interaction with the UI system + * - UI rendering + * - Custom tags definition + * - Load/unload system, applications and services UI + * - System dialogs definition */ export namespace GUI { /** - * + * AntOS keyboard shortcut type definition * * @export * @interface ShortcutType */ export interface ShortcutType { + /** + * Placeholder for all shortcut callbacks attached to `ALT` key, eg. + * ```typescript + * ALT.c = function() {..} + * // this function will be called when the hotkey `ALT-C` is triggered + * ``` + * + * @memberof ShortcutType + */ ALT: GenericObject<(e: JQuery.MouseDownEvent) => void>; + + /** + * Placeholder for all shortcut callbacks attached to `CTRL` key, eg. + * ```typescript + * CTRL.c = function() {..} + * // this function will be called when the hotkey `CTRL-C` is triggered + * ``` + * + * @memberof ShortcutType + */ CTRL: GenericObject<(e: JQuery.MouseDownEvent) => void>; + + /** + * Placeholder for all shortcut callbacks attached to `SHIFT` key, eg. + * ```typescript + * SHIFT.c = function() {..} + * // this function will be called when the hotkey `SHIFT-C` is triggered + * ``` + * + * @memberof ShortcutType + */ SHIFT: GenericObject<(e: JQuery.MouseDownEvent) => void>; + /** + * Placeholder for all shortcut callbacks attached to `META` key, eg. + * ```typescript + * META[" "] = function() {..} + * // this function will be called when the hotkey `META-[space]` is triggered + * ``` + * + * @memberof ShortcutType + */ META: GenericObject<(e: JQuery.MouseDownEvent) => void>; } /** + * Basic item type definition which is usually used by some UI element + * such as list view, tree view, menu and grid view * * * @export * @interface BasicItemType */ export interface BasicItemType { + /** + * Item text + * + * @type {(string | FormattedString)} + * @memberof BasicItemType + */ text: string | FormattedString; + + /** + * Item children, usually used by tree view or menu item + * This property is keep for compatibility purposes only. + * Otherwise, the [[nodes]] property should be used + * + * @type {BasicItemType[]} + * @memberof BasicItemType + */ children?: BasicItemType[]; + /** + * Item children, usually used by tree view or menu item + * + * @type {BasicItemType[]} + * @memberof BasicItemType + */ nodes?: BasicItemType[]; [propName: string]: any; } - + /** + * Element id of the virtual desktop, used by JQuery + */ export var workspace: string = "#desktop"; - + /** + * Indicate whether the system is in fullscreen mode + */ export var fullscreen = false; - + /** + * Reference to the current system dialog, only one dialog + * is allowed at a time. A dialog may have sub dialog + */ export var dialog: BaseDialog; + /** + * Placeholder for system shortcuts + */ var shortcut: ShortcutType = { ALT: {}, CTRL: {}, @@ -60,12 +137,18 @@ namespace OS { }; /** + * Convert an application html scheme to + * UI elements, then insert this UI scheme to the DOM tree. * + * This function renders the UI of the application before calling the + * application's [[main]] function * * @export - * @param {string} html - * @param {BaseModel} app + * @param {string} html html scheme string + * @param {BaseModel} app reference to the target application * @param {(Element | string)} parent + * The parent HTML element where the application is rendered. + * This is usually the reference to the virtual desktop element. */ export function htmlToScheme( html: string, @@ -85,12 +168,13 @@ namespace OS { } /** - * + * Load an application scheme file then render + * it with [[htmlToScheme]] * * @export - * @param {string} path - * @param {BaseModel} app - * @param {(HTMLElement | string)} parent + * @param {string} path VFS path to the scheme file + * @param {BaseModel} app the target application + * @param {(HTMLElement | string)} parent The parent HTML element where the application is rendered. */ export function loadScheme( path: string, @@ -111,7 +195,7 @@ namespace OS { } /** - * + * Clear the current system theme * * @export */ @@ -120,11 +204,12 @@ namespace OS { } /** - * + * Load a theme based on its name, then refresh the + * system UI theme * * @export - * @param {string} name - * @param {boolean} force + * @param {string} name name of the theme e.g. `antos_dark` + * @param {boolean} force force to clear the system theme before applying the new one */ export function loadTheme(name: string, force: boolean): void { if (force) { @@ -135,11 +220,14 @@ namespace OS { } /** - * + * Open a system dialog. * * @export - * @param {(string | BaseDialog)} d - * @param {GenericObject} data + * @param {(BaseDialog | string)} d a dialog object or a dialog class name + * @param {GenericObject} [data] input data of the dialog, refer to each + * dialog definition for the format of the input data + * @returns {Promise} A promise on the callback data of the dialog, refer + * to each dialog definition for the format of the callback data * @returns {Promise} */ export function openDialog( @@ -170,10 +258,11 @@ namespace OS { } /** - * + * Find a list of applications that support a specific mime + * type in the system packages meta-data * * @export - * @param {string} mime + * @param {string} mime the mime type * @returns {API.PackageMetaType[]} */ export function appsByMime(mime: string): API.PackageMetaType[] { @@ -223,17 +312,16 @@ namespace OS { } /** - * + * Find all applications that have services attached to it. + * This function allows to collect all the services available + * on the system. These services may or may not be running. * * @export - * @returns {{ - * [index: string]: API.PackageMetaType; - * }} + * @returns {GenericObject} result in forme of: + * `service_name:service-meta-data` key-value pairs */ - export function appsWithServices(): { - [index: string]: API.PackageMetaType; - } { - const o: { [index: string]: API.PackageMetaType } = {}; + export function appsWithServices(): GenericObject { + const o: GenericObject = {}; for (let k in setting.system.packages) { const v = setting.system.packages[k]; if (v && v.services && v.services.length > 0) { @@ -244,10 +332,21 @@ namespace OS { } /** + * Find an launch an application using input application argument + * such as VFS file meta-data. * + * Based on the input application argument, the function will try + * to find all applications that is compatible with that argument. + * Three cases possible: + * - There is no application that can handle the argument, a message will + * be notified to user. + * - There is one application that can handle the argument, the application + * will be launched with the argument + * - There are many applications that can handle the arguments, a selection + * dialog will be popped up and allows user to select an application to launch. * * @export - * @param {AppArgumentsType} it + * @param {AppArgumentsType} it application argument * @returns {void} */ export function openWith(it: AppArgumentsType): void { @@ -283,11 +382,15 @@ namespace OS { } /** + * Kil all processes related to an application, reload the application + * prototype definition and launch a new process of this application. * + * This function is used only for debug purpose or used by + * AntOSDK during in-browser application development * * @export - * @param {string} app - * @param {AppArgumentsType[]} args + * @param {string} app the application class name + * @param {AppArgumentsType[]} args application arguments * @returns {void} */ export function forceLaunch( @@ -301,9 +404,13 @@ namespace OS { return launch(app, args); } - /** + * Kill an running processes of an application, then + * unregister the application prototype definition + * from the [[application]] namespace. * + * This process is similar to uninstall the application + * from the current system state * * @export * @param {string} app @@ -317,9 +424,14 @@ namespace OS { } /** + * Load an application if the application is not registered yet + * in the system. * + * This function fist loads and registers the application prototype + * definition in the [[application]] namespace, then update + * the system packages meta-data * - * @param {string} app + * @param {string} app application class name * @returns {Promise} */ function loadApp(app: string): Promise { @@ -371,7 +483,10 @@ namespace OS { } /** + * Create a service process. * + * Services are singleton processes, there is only + * one process of a service at a time * * @export * @param {string} ph @@ -417,10 +532,10 @@ namespace OS { } /** - * + * Synchronously start a list of services * * @export - * @param {string[]} srvs + * @param {string[]} srvs list of service class names * @returns {Promise} */ export function pushServices(srvs: string[]): Promise { @@ -445,19 +560,22 @@ namespace OS { } /** - * + * Launch an application with arguments * * @export - * @param {string} app - * @param {AppArgumentsType[]} args + * @param {string} app application class name + * @param {AppArgumentsType[]} args application arguments */ export function launch(app: string, args: AppArgumentsType[]): void { if (!application[app]) { // first load it loadApp(app) .then((a) => - PM.createProcess(app, application[app], args) - .catch((e) => + PM.createProcess( + app, + application[app], + args + ).catch((e) => announcer.osfail( __("Unable to launch: {0}", app), e @@ -487,11 +605,11 @@ namespace OS { } /** - * + * Dock an application to the system application dock * * @export - * @param {BaseApplication} app - * @param {API.PackageMetaType} meta + * @param {BaseApplication} app reference to the application process + * @param {API.PackageMetaType} meta Application meta-data * @returns {void} */ export function dock( @@ -525,12 +643,12 @@ namespace OS { "[data-id = 'appmenu']", "#syspanel" )[0] as tag.MenuTag; - dock.newapp(data); + dock.newapp(data); }); } /** - * + * Toggle system fullscreen * * @export */ @@ -566,7 +684,8 @@ namespace OS { } /** - * + * Remove an application process from the system application + * dock. This action will also exit the process * * @export * @param {BaseApplication} app @@ -577,10 +696,10 @@ namespace OS { } /** - * + * Attach a running service process to the system tray * * @export - * @param {BaseService} srv + * @param {BaseService} srv reference to the running service process * @returns {void} */ export function attachservice(srv: application.BaseService): void { @@ -589,10 +708,10 @@ namespace OS { } /** - * + * Detach a running process from the system tray * * @export - * @param {BaseService} srv + * @param {BaseService} srv reference to the running service process * @returns {void} */ export function detachservice(srv: application.BaseService): void { @@ -600,20 +719,21 @@ namespace OS { } /** + * Bind a context menu event to an AntOS element. * + * This will find the fist element which defines a handle + * named [[contextMenuHandle]] and bind the context menu + * event to it. * - * @param {JQuery.MouseEventBase} event + * @param {JQuery.MouseEventBase} event mouse event * @returns {void} */ function bindContextMenu(event: JQuery.MouseEventBase): void { var handle = function (e: HTMLElement) { if (e.contextmenuHandle) { const m = $("#contextmenu")[0] as tag.MenuTag; - m.onmenuselect = () => {} - return e.contextmenuHandle( - event, - m - ); + m.onmenuselect = () => {}; + return e.contextmenuHandle(event, m); } else { const p = $(e).parent().get(0); if (p !== $("#workspace").get(0)) { @@ -626,11 +746,12 @@ namespace OS { } /** - * + * Register a hot key and its handle in the + * system shortcut * * @export - * @param {string} k - * @param {(e: JQuery.MouseDownEvent) => void} f + * @param {string} k the hotkey e.g. `ALT-C` + * @param {(e: JQuery.MouseDownEvent) => void} f handle function * @returns {void} */ export function bindKey( @@ -650,10 +771,10 @@ namespace OS { } /** - * + * Load and apply system wallpaper from the setting object * * @export - * @param {setting.WPSettingType} obj + * @param {setting.WPSettingType} obj wallpaper setting object */ export function wallpaper(obj?: setting.WPSettingType): void { if (obj) { @@ -667,11 +788,11 @@ namespace OS { } /** + * Show tooltip at the current mouse position * - * - * @param {JQuery} el - * @param {string} text - * @param {JQuery.MouseEventBase} e + * @param {JQuery} el The target element that has the tooltip attribute + * @param {string} text The text to be displayed + * @param {JQuery.MouseEventBase} e mouse event * @returns {void} */ function showTooltip( @@ -720,7 +841,7 @@ namespace OS { } /** - * + * Refresh the content of the virtual desktop * * @param {tag.FloatListTag} desktop */ @@ -764,8 +885,12 @@ namespace OS { } /** + * Init the virtual desktop on boot: * - * + * - Register listener for system hotkey + * - Bind the system context menu handle + * - Init and load the content of the virtual desktop + * - Init the system tooltip event handle */ function initDM(): void { const scheme = $.parseHTML(schemes.ws); @@ -806,9 +931,8 @@ namespace OS { } shortcut[fnk][c](event); return event.preventDefault(); - }) - } - ); + }); + }); // system menu and dock $("#syspanel")[0].uify(undefined); $("#sysdock")[0].uify(undefined); @@ -840,11 +964,15 @@ namespace OS { return e.calibrate(); }; - desktop.onlistselect = function (d: TagEventType) { + desktop.onlistselect = function ( + d: TagEventType + ) { ($("#sysdock")[0] as tag.AppDockTag).selectedApp = null; }; - desktop.onlistdbclick = function (d: TagEventType) { + desktop.onlistdbclick = function ( + d: TagEventType + ) { ($("#sysdock")[0] as tag.AppDockTag).selectedApp = null; const it = desktop.selectedItem; return openWith(it.data as AppArgumentsType); @@ -889,8 +1017,10 @@ namespace OS { })() ); m.items = menu; - m.onmenuselect = function (evt: TagEventType) { - if(!evt.data || !evt.data.item) return; + m.onmenuselect = function ( + evt: TagEventType + ) { + if (!evt.data || !evt.data.item) return; const item = evt.data.item.data; switch (item.dataid) { case "desktop-open": @@ -934,7 +1064,7 @@ namespace OS { } /** - * + * Refresh the virtual desktop * * @export */ @@ -943,7 +1073,9 @@ namespace OS { } /** + * Show the login screen and perform the login operation. * + * Once login successfully, the [[startAntOS]] will be called * * @export */ @@ -978,6 +1110,15 @@ namespace OS { } /** + * Start AntOS after a successful login. + * + * This function performs the following operations: + * + * - System cleanup + * - Apply system setting + * - Load desktop wallpaper and the current theme from the system setting + * - Load system package meta-data + * - Load and apply system locale and language * * * @export @@ -1029,32 +1170,38 @@ namespace OS { pushServices( (() => { const result = []; - for (let v of - setting.system.startup.services - ) { + for (let v of setting.system.startup.services) { result.push(v); } return result; })() - ).then(function(){ + ).then(function () { setting.system.startup.apps.map((a) => { launch(a, []); }); - }) + }); }); } }); //GUI.launch "DummyApp" // initDM API.setLocale(setting.system.locale).then(() => initDM()); - Ant.OS.announcer.observable.on("error", function(d) { - console.log(d.data.e) + Ant.OS.announcer.observable.on("error", function (d) { + console.log(d.data.e); }); - Ant.OS.announcer.observable.on("fail", function(d) { - console.log(d.data.e) + Ant.OS.announcer.observable.on("fail", function (d) { + console.log(d.data.e); }); } - + /** + * HTML schemes used by the system: + * - The login screen scheme + * - The workspace including: + * - System panel + * - Virtual desktop + * - Context menu + * - System tooltip + */ export const schemes: GenericObject = {}; schemes.ws = `\ diff --git a/src/core/handles/RemoteHandle.ts b/src/core/handles/RemoteHandle.ts index 8b3e5ab..0702df8 100644 --- a/src/core/handles/RemoteHandle.ts +++ b/src/core/handles/RemoteHandle.ts @@ -217,7 +217,7 @@ namespace OS { * @param {string} t return data type: * - jsonp: the response is an json object * - script: the response is a javascript code - * - xm, html: the response is a XML/HTML object + * - xml, html: the response is a XML/HTML object * - text: plain text * * @returns {Promise} A promise on a [[RequestResult]] diff --git a/src/core/pm.ts b/src/core/pm.ts index 67f10f7..f8dce1f 100644 --- a/src/core/pm.ts +++ b/src/core/pm.ts @@ -1,19 +1,38 @@ namespace OS { + /** + * This namespace dedicated to all operations related to system + * process management + */ export namespace PM { - export type ProcessType = application.BaseApplication | application.BaseService; + /** + * A process is either an instance of an application or a service + */ + export type ProcessType = + | application.BaseApplication + | application.BaseService; + /** + * Alias to all classes that extends [[BaseModel]] + */ export type ModelTypeClass = { new (args: AppArgumentsType[]): T; }; + /** + * Process id allocator, when a new process is created, the value of + * this variable is increased + */ export var pidalloc: number = 0; + /** + * All running processes is stored in this variables + */ export var processes: GenericObject = {}; /** - * + * Create a new process of application or service * * @export - * @param {string} app - * @param {ProcessTypeClass} cls - * @param {GUI.AppArgumentsType[]} [args] - * @returns {Promise} + * @param {string} app class name string + * @param {ProcessTypeClass} cls prototype class + * @param {GUI.AppArgumentsType[]} [args] process arguments + * @returns {Promise} a promise on the created process */ export function createProcess( app: string, @@ -68,7 +87,7 @@ namespace OS { } /** - * + * Get the reference to a process using its id * * @export * @param {number} pid @@ -94,10 +113,10 @@ namespace OS { } /** - * + * Kill a process * * @export - * @param {OS.GUI.BaseModel} app + * @param {OS.GUI.BaseModel} app reference to the process * @returns {void} */ export function kill(app: BaseModel): void { @@ -119,11 +138,11 @@ namespace OS { } /** - * + * Kill all process of an application or service * * @export - * @param {string} app - * @param {boolean} force + * @param {string} app process class name + * @param {boolean} force force exit all process * @returns {void} */ export function killAll(app: string, force: boolean): void { diff --git a/src/core/settings.ts b/src/core/settings.ts index acec9af..d87819a 100644 --- a/src/core/settings.ts +++ b/src/core/settings.ts @@ -1,9 +1,3 @@ -/* - * decaffeinate suggestions: - * DS101: Remove unnecessary use of Array.from - * 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 @@ -23,134 +17,375 @@ //along with this program. If not, see https://www.gnu.org/licenses/. namespace OS { + /** + * This namespace is dedicated to everything related to the + * global system settings + */ export namespace setting { - /** - * + * User setting type definition * * @export * @interface UserSettingType */ export interface UserSettingType { + /** + * User full name + * + * @type {string} + * @memberof UserSettingType + */ name: string; + + /** + * User name + * + * @type {string} + * @memberof UserSettingType + */ username: string; + + /** + * User id + * + * @type {number} + * @memberof UserSettingType + */ id: number; + + /** + * User groups + * + * @type {{ [index: number]: string }} + * @memberof UserSettingType + */ group?: { [index: number]: string }; [propName: string]: any; } /** - * + * Virtual desktop setting data type * * @export * @interface DesktopSettingType */ export interface DesktopSettingType { + /** + * Desktop VFS path + * + * @type {string} + * @memberof DesktopSettingType + */ path: string; - menu: any[]; + + /** + * Desktop menu, can be added automatically by applications + * + * @type {GUI.BasicItemType[]} + * @memberof DesktopSettingType + */ + menu: GUI.BasicItemType[]; + + /** + * Show desktop hidden files + * + * @type {boolean} + * @memberof DesktopSettingType + */ showhidden: boolean; [propName: string]: any; } /** - * + * Wallpaper setting data type * * @export * @interface WPSettingType */ export interface WPSettingType { + /** + * Repeat wallpaper: + * - `repeat` + * - `repeat-x` + * - `repeat-y` + * - `no-repeat` + * + * @type {string} + * @memberof WPSettingType + */ repeat: string; + + /** + * Wallpaper size + * - `contain` + * - `cover` + * - `auto` + * + * @type {string} + * @memberof WPSettingType + */ size: string; + + /** + * VFS path to the wallpaper image + * + * @type {string} + * @memberof WPSettingType + */ url: string; } /** - * + * Theme setting data type * * @export * @interface ThemeSettingType */ export interface ThemeSettingType { + /** + * Theme name, this value is used for looking + * theme file in system asset + * + * @type {string} + * @memberof ThemeSettingType + */ name: string; + + /** + * Theme user-friendly text + * + * @type {string} + * @memberof ThemeSettingType + */ text: string; } /** - * + * Appearance setting data type * * @export * @interface AppearanceSettingType */ export interface AppearanceSettingType { + /** + * Current theme name + * + * @type {string} + * @memberof AppearanceSettingType + */ theme: string; + + /** + * All themes available in the system + * + * @type {ThemeSettingType[]} + * @memberof AppearanceSettingType + */ themes: ThemeSettingType[]; + + /** + * Current wallpaper setting + * + * @type {WPSettingType} + * @memberof AppearanceSettingType + */ wp: WPSettingType; + + /** + * All wallpapers available in the system + * + * @type {string[]} + * @memberof AppearanceSettingType + */ wps: string[]; } /** - * + * VFS Mount points setting data type * * @export * @interface VFSMountPointSettingType */ export interface VFSMountPointSettingType { + /** + * Path to the mount point + * + * @type {string} + * @memberof VFSMountPointSettingType + */ path: string; + + /** + * User friendly mount point name + * + * @type {string} + * @memberof VFSMountPointSettingType + */ text: string; [propName: string]: any; } /** - * + * VFS setting data type * * @export * @interface VFSSettingType */ export interface VFSSettingType { + /** + * mount points setting + * + * @type {VFSMountPointSettingType[]} + * @memberof VFSSettingType + */ mountpoints: VFSMountPointSettingType[]; [propName: string]: any; } /** - * + * Global system setting data type * * @export * @interface SystemSettingType */ export interface SystemSettingType { + /** + * System error report URL + * + * @type {string} + * @memberof SystemSettingType + */ error_report: string; + + /** + * Current system locale e.g. `en_GB` + * + * @type {string} + * @memberof SystemSettingType + */ locale: string; - menu: any[]; + + /** + * System menus + * + * @type {API.PackageMetaType[]} + * @memberof API.PackageMetaType + */ + menu: API.PackageMetaType[]; + + /** + * Packages meta-data + * + * @type {{ [index: string]: API.PackageMetaType }} + * @memberof SystemSettingType + */ packages: { [index: string]: API.PackageMetaType }; + + /** + * Path to the installed packages + * + * @type {{ + * user: string; + * system: string; + * }} + * @memberof SystemSettingType + */ pkgpaths: { + /** + * User specific packages install location + * + * @type {string} + */ user: string; + + /** + * System packages install location + * + * @type {string} + */ system: string; }; + + /** + * Package repositories setting. + * This configuration is used by [[MarketPlace]] + * for package management + * + * @type {{ + * text: string; + * url: string; + * }[]} + * @memberof SystemSettingType + */ repositories: { + /** + * Repository name + * + * @type {string} + */ text: string; + + /** + * Repository uri + * + * @type {string} + */ url: string; }[]; + + /** + * Startup applications and services + * + * @type {{ + * apps: string[]; + * services: string[]; + * }} + * @memberof SystemSettingType + */ startup: { + /** + * List of application names + * + * @type {string[]} + */ apps: string[]; + + /** + * List of service names + * + * @type {string[]} + */ services: string[]; }; } - + /** + * User settings + */ export var user: UserSettingType; - + /** + * Application settings + */ export var applications: GenericObject = {}; - + /** + * Desktop settings + */ export var desktop: DesktopSettingType; - + /** + * Appearance settings + */ export var appearance: AppearanceSettingType; - + /** + * VFS settings + */ export var VFS: VFSSettingType; - + /** + * System settings + */ export var system: SystemSettingType; } /** - * + * Reset the system settings to default values * * @export */ @@ -158,7 +393,7 @@ namespace OS { setting.desktop = { path: "home://.desktop", menu: [], - showhidden: false + showhidden: false, }; setting.user = { name: undefined, @@ -240,15 +475,15 @@ namespace OS { repositories: [], startup: { apps: [], - services: [ - "Syslog/PushNotification", "Syslog/Calendar" - ], + services: ["Syslog/PushNotification", "Syslog/Calendar"], }, }; } /** - * + * Apply the input parameter object to system settings. + * This object could be an object loaded from + * setting JSON file saved on the server. * * @export * @param {*} conf @@ -288,7 +523,7 @@ namespace OS { } } - //search for app + // Register handle for application search API.onsearch("__(Applications)", function (t) { const ar = []; const term = new RegExp(t, "i"); diff --git a/src/core/vfs.ts b/src/core/vfs.ts index 1bd2b5e..7f2473c 100644 --- a/src/core/vfs.ts +++ b/src/core/vfs.ts @@ -17,13 +17,21 @@ //along with this program. If not, see https://www.gnu.org/licenses/. type VFSFileHandleClass = { new (...args: any[]): OS.API.VFS.BaseFileHandle }; interface String { + /** + * Convert a string to VFS file handle. + * + * This function will create a file handle object from the string + * with the help of [[VFS.findHandles]] + * + * @returns {OS.API.VFS.BaseFileHandle} + * @memberof String + */ asFileHandle(): OS.API.VFS.BaseFileHandle; } namespace OS { export namespace API { - /** - * + * User permission data type * * @export * @interface UserPermissionType @@ -35,31 +43,127 @@ namespace OS { } /** - * + * VFS file meta-data data type * * @export * @interface FileInfoType */ export interface FileInfoType { + /** + * File mime type + * + * @type {string} + * @memberof FileInfoType + */ mime: string; + + /** + * File size + * + * @type {number} + * @memberof FileInfoType + */ size: number; + + /** + * File name + * + * @type {string} + * @memberof FileInfoType + */ name: string; + + /** + * File path + * + * @type {string} + * @memberof FileInfoType + */ path: string; + + /** + * File type: + * - `file` + * - `dir` + * - `app` + * + * @type {string} + * @memberof FileInfoType + */ type: string; + + /** + * File permission + * + * @type {{ + * group: UserPermissionType; + * owner: UserPermissionType; + * other: UserPermissionType; + * }} + * @memberof FileInfoType + */ perm?: { + /** + * Group permission + * + * @type {UserPermissionType} + */ group: UserPermissionType; + + /** + * Owner permission + * + * @type {UserPermissionType} + */ owner: UserPermissionType; + + /** + * Other permission + * + * @type {UserPermissionType} + */ other: UserPermissionType; }; + + /** + * Creation time + * + * @type {string} + * @memberof FileInfoType + */ ctime?: string; + + /** + * Modification time + * + * @type {string} + * @memberof FileInfoType + */ mtime?: string; + + /** + * Group id + * + * @type {number} + * @memberof FileInfoType + */ gid?: number; + + /** + * User id + * + * @type {number} + * @memberof FileInfoType + */ uid?: number; [propName: string]: any; } + /** + * This namespace is dedicated to all APIs related to + * AntOS Virtual File System (VFS) + */ export namespace VFS { - String.prototype.asFileHandle = function (): BaseFileHandle { const list = this.split("://"); const handles = API.VFS.findHandles(list[0]); @@ -73,14 +177,18 @@ namespace OS { return new handles[0](this); }; + /** + * Placeholder stores VFS file protocol patterns and its attached file handle class. + * + */ export const handles: GenericObject = {}; /** - * + * Register a protocol to a handle class * * @export - * @param {string} protos - * @param {VFSFileHandleClass} cls + * @param {string} protos VFS protocol pattern + * @param {VFSFileHandleClass} cls handle class */ export function register( protos: string, @@ -90,10 +198,18 @@ namespace OS { } /** + * Looking for a attached file handle class of a string protocol * + * When converting a string to file handle, the system will look + * for a protocol pattern in the string, if the protocol found, + * its attached handle class (found in [[VFS.handles]]) will be + * used to initialize a file handle object from the string * + * ```typescript + * "home://data/test.txt".asFileHandle() // -> an instance of RemoteFileHandle + * ``` * @export - * @param {string} proto + * @param {string} proto protocol string * @returns {VFSFileHandleClass[]} */ export function findHandles(proto: string): VFSFileHandleClass[] { @@ -111,26 +227,102 @@ namespace OS { } /** + * Abstract prototype of all all VFS file handle definition. * + * This prototype provides a standardized interface to access + * to different underlay file systems such as remote file, + * cloud file (Dropbox, Google drive, etc.), URL or memory-based file * * @export * @abstract * @class BaseFileHandle */ export abstract class BaseFileHandle { + /** + * Flag indicates whether the file is dirty + * + * @type {boolean} + * @memberof BaseFileHandle + */ dirty: boolean; + + /** + * Once read, file content will be cached in this placeholder + * + * @type {*} + * @memberof BaseFileHandle + */ cache: any; + + /** + * Flag indicated whether the file meta-data is loaded + * + * @type {boolean} + * @memberof BaseFileHandle + */ ready: boolean; + + /** + * File path + * + * @type {string} + * @memberof BaseFileHandle + */ path: string; + + /** + * File protocol e.g: + * - `os://` + * - `home://` + * + * @type {string} + * @memberof BaseFileHandle + */ protocol: string; + + /** + * List of path segments + * + * @type {string[]} + * @memberof BaseFileHandle + */ genealogy: string[]; + + /** + * File base name + * + * @type {string} + * @memberof BaseFileHandle + */ basename: string; + + /** + * Once loaded, [[ready]] will be set to true and + * file meta-data will be stored in this place holder + * + * @type {FileInfoType} + * @memberof BaseFileHandle + */ info: FileInfoType; + + /** + * File extension + * + * @type {string} + * @memberof BaseFileHandle + */ ext: string; + + /** + * + * File type + * @type {string} + * @memberof BaseFileHandle + */ type: string; /** *Creates an instance of BaseFileHandle. - * @param {string} path + * @param {string} path file path * @memberof BaseFileHandle */ constructor(path: string) { @@ -140,7 +332,7 @@ namespace OS { } /** - * + * Set a file path to the current file handle * * @param {string} p * @returns {void} @@ -176,7 +368,8 @@ namespace OS { } /** - * + * Getter: Get the file basename + * Setter: set the file name * * @returns {string} * @memberof BaseFileHandle @@ -187,20 +380,13 @@ namespace OS { } return this.basename; } - - /** - * - * - * @memberof BaseFileHandle - */ - set filename(v: string) - { + set filename(v: string) { this.basename = v; } /** + * Set data to the file cache * - * - * @param {*} v + * @param {*} v data object * @returns {BaseFileHandle} * @memberof BaseFileHandle */ @@ -210,7 +396,7 @@ namespace OS { } /** - * + * Return the object itself * * @returns {BaseFileHandle} * @memberof BaseFileHandle @@ -220,7 +406,7 @@ namespace OS { } /** - * + * Check whether the current file is the root of the file tree * * @returns {boolean} * @memberof BaseFileHandle @@ -230,22 +416,7 @@ namespace OS { } /** - * - * - * @param {string} name - * @returns {string} - * @memberof BaseFileHandle - */ - child(name: string): string { - if (this.isRoot()) { - return this.path + name; - } else { - return this.path + "/" + name; - } - } - - /** - * + * Check whether the current file is a hidden file * * @returns {boolean} * @memberof BaseFileHandle @@ -258,7 +429,7 @@ namespace OS { } /** - * + * Get hash number of the current file path * * @returns {number} * @memberof BaseFileHandle @@ -271,13 +442,16 @@ namespace OS { } /** + * Convert the current file cache to Base64 * - * - * @param {string} t - * @returns {(Promise)} + * @protected + * @param {string} t type of the file cache: + * - `object` + * - `mime type` + * @returns {(Promise)} promise on the converted data * @memberof BaseFileHandle */ - b64(t: string): Promise { + protected b64(t: string): Promise { // t is object or mime type return new Promise((resolve, reject) => { const m = t === "object" ? "text/plain" : t; @@ -307,7 +481,7 @@ namespace OS { } /** - * + * Get the parent file handle of the current file * * @returns {BaseFileHandle} * @memberof BaseFileHandle @@ -326,9 +500,10 @@ namespace OS { } /** + * Load the file meta-data before performing + * any task * - * - * @returns {Promise} + * @returns {Promise} a promise on file meta-data * @memberof BaseFileHandle */ onready(): Promise { @@ -348,10 +523,22 @@ namespace OS { } /** + * Public read operation * + * This function calls the [[_rd]] function to perform the operation. * - * @param {string} [t] - * @returns {Promise} + * If the current file is a directory, then the operation + * will return the meta-data of all files inside of the directory. + * Otherwise, file content will be returned + * + * @param {string} t data type + * - jsonp: the response is an json object + * - script: the response is a javascript code + * - xml, html: the response is a XML/HTML object + * - text: plain text + * - binary + * + * @returns {Promise} a promise on the file content * @memberof BaseFileHandle */ read(t?: string): Promise { @@ -371,10 +558,16 @@ namespace OS { } /** + * Write the file cache to the actual file * - * - * @param {string} t - * @returns {Promise} + * This function calls the [[_wr]] function to perform the operation + * + * @param {string} t data type + * - `base64` + * - `object` + * - `mime type` + * + * @returns {Promise} promise on the operation result * @memberof BaseFileHandle */ write(t: string): Promise { @@ -393,10 +586,12 @@ namespace OS { } /** + * Sub-directory creation * + * This function calls the [[_mk]] function to perform the operation * - * @param {string} d - * @returns {Promise} + * @param {string} d sub directory name + * @returns {Promise} promise on the operation result * @memberof BaseFileHandle */ mk(d: string): Promise { @@ -420,9 +615,11 @@ namespace OS { } /** + * Delete the file * + * This function calls the [[_rm]] function to perform the operation * - * @returns {Promise} + * @returns {Promise} promise on the operation result * @memberof BaseFileHandle */ remove(): Promise { @@ -446,9 +643,13 @@ namespace OS { } /** + * Upload a file to the current directory * + * Only work when the current file is a directory * - * @returns {Promise} + * This function calls the [[_up]] function to perform the operation + * + * @returns {Promise} promise on the operation result * @memberof BaseFileHandle */ upload(): Promise { @@ -472,9 +673,13 @@ namespace OS { } /** + * Share the file by publish it. * + * Only work with file * - * @returns {Promise} + * This function calls the [[_pub]] function to perform the operation + * + * @returns {Promise} promise on operation result * @memberof BaseFileHandle */ publish(): Promise { @@ -498,9 +703,13 @@ namespace OS { } /** + * Download the file. * + * Only work with file * - * @returns {Promise} + * This function calls the [[_down]] function to perform the operation + * + * @returns {Promise} Promise on the operation result * @memberof BaseFileHandle */ download(): Promise { @@ -524,10 +733,12 @@ namespace OS { } /** + * Move the current file to another location * + * This function calls the [[_mv]] function to perform the operation * - * @param {string} d - * @returns {Promise} + * @param {string} d destination location + * @returns {Promise} promise on the operation result * @memberof BaseFileHandle */ move(d: string): Promise { @@ -551,7 +762,11 @@ namespace OS { } /** + * Execute the current file. * + * This action depends on each file protocol + * + * This function calls the [[_exec]] function to perform the operation * * @returns {Promise} * @memberof BaseFileHandle @@ -577,7 +792,8 @@ namespace OS { } /** - * + * Get an accessible link to the file + * that can be accessed from the browser * * @returns {string} * @memberof BaseFileHandle @@ -587,13 +803,13 @@ namespace OS { } /** + * Helper function returns a promise on unsupported action * - * - * @param {string} t + * @param {string} t action name * @returns {Promise} * @memberof BaseFileHandle */ - unsupported(t: string): Promise { + protected unsupported(t: string): Promise { return new Promise((resolve, reject) => { return reject( API.throwe( @@ -606,117 +822,168 @@ namespace OS { ); }); } - // actions must be implemented by subclasses /** + * Low level protocol-specific read operation * + * This function should be overridden on the file handle class + * that supports the operation * - * @param {string} t + * @protected + * @param {string} t data type, see [[read]] * @returns {Promise} * @memberof BaseFileHandle */ - _rd(t: string): Promise { + protected _rd(t: string): Promise { return this.unsupported("read"); } /** + * Low level protocol-specific write operation * + * This function should be overridden by the file handle class + * that supports the operation * - * @param {string} t + * @protected + * @param {string} t data type, see [[write]] * @param {*} [d] * @returns {Promise} * @memberof BaseFileHandle */ - _wr(t: string, d?: any): Promise { + protected _wr(t: string, d?: any): Promise { return this.unsupported("write"); } + /** + * Low level protocol-specific sub-directory creation * + * This function should be overridden by the file handle class + * that supports the operation * - * @param {string} d + * @protected + * @param {string} d sub directory name * @returns {Promise} * @memberof BaseFileHandle */ - _mk(d: string): Promise { + protected _mk(d: string): Promise { return this.unsupported("mk"); } /** + * Low level protocol-specific delete operation * + * This function should be overridden by the file handle class + * that supports the operation * * @returns {Promise} * @memberof BaseFileHandle */ - _rm(): Promise { + protected _rm(): Promise { return this.unsupported("remove"); } /** + * Low level protocol-specific move operation * + * This function should be overridden by the file handle class + * that supports the operation * + * @protected * @param {string} d * @returns {Promise} * @memberof BaseFileHandle */ - _mv(d: string): Promise { + protected _mv(d: string): Promise { return this.unsupported("move"); } /** + * Low level protocol-specific upload operation * + * This function should be overridden by the file handle class + * that supports the operation * * @returns {Promise} * @memberof BaseFileHandle */ - _up(): Promise { + protected _up(): Promise { return this.unsupported("upload"); } /** + * Low level protocol-specific download operation * + * This function should be overridden by the file handle class + * that supports the operation * * @returns {Promise} * @memberof BaseFileHandle */ - _down(): Promise { + protected _down(): Promise { return this.unsupported("download"); } /** + * Low level protocol-specific execute operation * + * This function should be overridden by the file handle class + * that supports the operation * * @returns {Promise} * @memberof BaseFileHandle */ - _exec(): Promise { + protected _exec(): Promise { return this.unsupported("execute"); } /** + * Low level protocol-specific share operation * + * This function should be overridden by the file handle class + * that supports the operation * * @returns {Promise} * @memberof BaseFileHandle */ - _pub(): Promise { + protected _pub(): Promise { return this.unsupported("publish"); } + + /** + * Read the current file meta-data + * + * should be implemented by subclasses + * + * @abstract + * @returns {Promise} + * @memberof BaseFileHandle + */ abstract meta(): Promise; } - // Remote file handle /** + * Remote file handle allows to perform file operation + * on AntOS remote server files. Its protocol is defined + * by the following pattern: * + * ``` + * ^(home|desktop|os|Untitled)$ + * ``` * * @class RemoteFileHandle * @extends {BaseFileHandle} */ export class RemoteFileHandle extends BaseFileHandle { + /** + *Creates an instance of RemoteFileHandle. + * @param {string} path file path + * @memberof RemoteFileHandle + */ constructor(path: string) { super(path); } /** - * + * Read remote file meta-data * * @returns {Promise} * @memberof RemoteFileHandle @@ -724,9 +991,7 @@ namespace OS { meta(): Promise { return new Promise(async (resolve, reject) => { try { - const d = await API.handle.fileinfo( - this.path - ); + const d = await API.handle.fileinfo(this.path); if (d.error) { return reject( API.throwe( @@ -742,7 +1007,7 @@ namespace OS { } /** - * + * Remote file access link * * @returns {string} * @memberof RemoteFileHandle @@ -751,7 +1016,19 @@ namespace OS { return API.handle.get + "/" + this.path; } - _rd(t: string): Promise { + /** + * Read remote file content. + * + * If the current file is a directory, then the operation + * will return the meta-data of all files inside of the directory. + * Otherwise, file content will be returned + * + * @protected + * @param {string} t data type see [[read]] + * @returns {Promise} + * @memberof RemoteFileHandle + */ + protected _rd(t: string): Promise { // t: binary, text, any type if (!this.info) { return new Promise((resolve, reject) => { @@ -772,20 +1049,18 @@ namespace OS { if (t === "binary") { return API.handle.fileblob(this.path); } - return API.handle.readfile( - this.path, - t ? t : "text" - ); + return API.handle.readfile(this.path, t ? t : "text"); } /** + * Write file cache to the remote file * - * - * @param {string} t + * @protected + * @param {string} t data type see [[write]] * @returns {Promise} * @memberof RemoteFileHandle */ - _wr(t: string): Promise { + protected _wr(t: string): Promise { // t is base64 or undefined return new Promise(async (resolve, reject) => { if (t === "base64") { @@ -836,13 +1111,16 @@ namespace OS { } /** + * Create sub directory * + * Only work on directory file handle * - * @param {string} d + * @protected + * @param {string} d sub directory name * @returns {Promise} * @memberof RemoteFileHandle */ - _mk(d: string): Promise { + protected _mk(d: string): Promise { return new Promise((resolve, reject) => { if (!this.info) { return reject( @@ -878,12 +1156,13 @@ namespace OS { } /** + * Delete file/folder * - * + * @protected * @returns {Promise} * @memberof RemoteFileHandle */ - _rm(): Promise { + protected _rm(): Promise { return new Promise(async (resolve, reject) => { try { const d = await API.handle.remove(this.path); @@ -902,19 +1181,17 @@ namespace OS { } /** + * Move file/folder * - * + * @protected * @param {string} d * @returns {Promise} * @memberof RemoteFileHandle */ - _mv(d: string): Promise { + protected _mv(d: string): Promise { return new Promise(async (resolve, reject) => { try { - const r = await API.handle.move( - this.path, - d - ); + const r = await API.handle.move(this.path, d); if (r.error) { return reject( API.throwe( @@ -930,18 +1207,19 @@ namespace OS { } /** + * Upload a file * + * Only work with directory file handle * + * @protected * @returns {Promise} * @memberof RemoteFileHandle */ - _up(): Promise { + protected _up(): Promise { return new Promise((resolve, reject) => { if (this.info.type !== "dir") { return reject( - API.throwe( - __("{0} is not a file", this.path) - ) + API.throwe(__("{0} is not a file", this.path)) ); } return API.handle @@ -961,12 +1239,15 @@ namespace OS { } /** + * Download a file * + * only work with file * + * @protected * @returns {Promise} * @memberof RemoteFileHandle */ - _down(): Promise { + protected _down(): Promise { return new Promise((resolve, reject) => { if (this.info.type === "dir") { return API.throwe( @@ -987,12 +1268,13 @@ namespace OS { } /** + * Publish a file * - * + * @protected * @returns {Promise} * @memberof RemoteFileHandle */ - _pub(): Promise { + protected _pub(): Promise { return new Promise(async (resolve, reject) => { try { const d = await API.handle.sharefile( @@ -1016,25 +1298,28 @@ namespace OS { register("^(home|desktop|os|Untitled)$", RemoteFileHandle); - // Application Handle /** + * Application file is an AntOS special file allowing to + * refer to an application as a regular file. Its protocol + * pattern is defined as: * + * ```typescript + * "^app$" // e.g. app://Setting + * ``` * * @class ApplicationHandle * @extends {BaseFileHandle} */ export class ApplicationHandle extends BaseFileHandle { - /** *Creates an instance of ApplicationHandle. - * @param {string} path + * @param {string} path file path * @memberof ApplicationHandle */ constructor(path: string) { super(path); if (this.basename) { - let v: any = - OS.setting.system.packages[this.basename]; + let v: any = OS.setting.system.packages[this.basename]; v.type = "app"; v.mime = "antos/app"; v.size = 0; @@ -1044,7 +1329,7 @@ namespace OS { } /** - * + * Read application meta-data * * @returns {Promise} * @memberof ApplicationHandle @@ -1059,13 +1344,17 @@ namespace OS { } /** + * If the current file is root (e.g. `app://`), the operation + * will return all system packages meta-data. * + * Otherwise, an error will be thrown * + * @protected * @param {string} t * @returns {Promise} * @memberof ApplicationHandle */ - _rd(t: string): Promise { + protected _rd(t: string): Promise { return new Promise((resolve, reject) => { if (this.info) { return resolve({ @@ -1096,12 +1385,24 @@ namespace OS { register("^app$", ApplicationHandle); /** + * A buffer file handle represents a virtual file that is stored + * on the system memory. Its protocol pattern is defined as: * + * ```typescript + * "^mem$" // e.g. mem://test.txt + * ``` * * @class BufferFileHandle * @extends {BaseFileHandle} */ export class BufferFileHandle extends BaseFileHandle { + /** + *Creates an instance of BufferFileHandle. + * @param {string} path file path + * @param {string} mime file mime-type + * @param {*} data file data + * @memberof BufferFileHandle + */ constructor(path: string, mime: string, data: any) { super(path); if (data) { @@ -1117,7 +1418,7 @@ namespace OS { } /** - * + * Read the file meta-data * * @returns {Promise} * @memberof BufferFileHandle @@ -1132,27 +1433,29 @@ namespace OS { } /** + * Read file content stored in the file cached * - * - * @param {string} t + * @protected + * @param {string} t data type see [[read]] * @returns {Promise} * @memberof BufferFileHandle */ - _rd(t: string): Promise { + protected _rd(t: string): Promise { return new Promise((resolve, reject) => { return resolve(this.cache); }); } /** + * Write data to the file cache * - * - * @param {string} t - * @param {*} d + * @protected + * @param {string} t data type, see [[write]] + * @param {*} d data * @returns {Promise} * @memberof BufferFileHandle */ - _wr(t: string, d: any): Promise { + protected _wr(t: string, d: any): Promise { this.cache = d; return new Promise((resolve, reject) => resolve({ @@ -1163,12 +1466,13 @@ namespace OS { } /** + * Download the buffer file * - * + * @protected * @returns {Promise} * @memberof BufferFileHandle */ - _down(): Promise { + protected _down(): Promise { return new Promise((resolve, reject) => { const blob = new Blob([this.cache], { type: "octet/stream", @@ -1182,12 +1486,22 @@ namespace OS { API.VFS.register("^mem$", BufferFileHandle); /** + * URL file handle represents a HTTP/HTTPs link url + * as an AntOS VFS file handle. Its protocol is defined as * + * ``` + * ^(http|https|ftp)$ + * ``` * * @class URLFileHandle * @extends {BaseFileHandle} */ export class URLFileHandle extends BaseFileHandle { + /** + *Creates an instance of URLFileHandle. + * @param {string} path + * @memberof URLFileHandle + */ constructor(path: string) { super(path); this.ready = true; @@ -1201,7 +1515,7 @@ namespace OS { } /** - * + * Read file meta-data * * @returns {Promise} * @memberof URLFileHandle @@ -1214,7 +1528,16 @@ namespace OS { }) ); } - _rd(t: string): Promise { + + /** + * Read URL content + * + * @protected + * @param {string} t data type see [[read]] + * @returns {Promise} + * @memberof URLFileHandle + */ + protected _rd(t: string): Promise { return API.get(this.path, t ? t : "text"); } } @@ -1222,12 +1545,22 @@ namespace OS { API.VFS.register("^(http|https|ftp)$", URLFileHandle); /** + * Shared file handle represents all AntOS shared file. + * Its protocol is defined as: * + * ``` + * ^shared$ + * ``` * * @class SharedFileHandle * @extends {API.VFS.BaseFileHandle} */ export class SharedFileHandle extends API.VFS.BaseFileHandle { + /** + *Creates an instance of SharedFileHandle. + * @param {string} path file path + * @memberof SharedFileHandle + */ constructor(path: string) { super(path); if (this.isRoot()) { @@ -1236,7 +1569,7 @@ namespace OS { } /** - * + * Read file meta-data * * @returns {Promise} * @memberof SharedFileHandle @@ -1246,44 +1579,37 @@ namespace OS { } /** + * Read file content * - * - * @param {string} t + * @protected + * @param {string} t data type, see [[read]] * @returns {Promise} * @memberof SharedFileHandle */ - _rd(t: string): Promise { + protected _rd(t: string): Promise { if (this.isRoot()) { - return API.get( - `${API.handle.shared}/all`, - t - ); + return API.get(`${API.handle.shared}/all`, t); } //read the file if (t === "binary") { return API.handle.fileblob(this.path); } - return API.handle.readfile( - this.path, - t ? t : "text" - ); + return API.handle.readfile(this.path, t ? t : "text"); } /** + * write data to shared file * - * - * @param {string} t - * @param {string} d + * @protected + * @param {string} t data type, see [[write]] + * @param {string} d file data * @returns {Promise} * @memberof SharedFileHandle */ - _wr(t: string, d: string): Promise { + protected _wr(t: string, d: string): Promise { return new Promise(async (resolve, reject) => { try { - const r = await API.handle.write( - this.path, - d - ); + const r = await API.handle.write(this.path, d); if (r.error) { return reject( API.throwe( @@ -1299,12 +1625,13 @@ namespace OS { } /** + * Un-publish the file * - * + * @protected * @returns {Promise} * @memberof SharedFileHandle */ - _rm(): Promise { + protected _rm(): Promise { return new Promise(async (resolve, reject) => { try { const d = await API.handle.sharefile( @@ -1326,18 +1653,17 @@ namespace OS { } /** + * Download shared file * - * + * @protected * @returns {Promise} * @memberof SharedFileHandle */ - _down(): Promise { + protected _down(): Promise { return new Promise((resolve, reject) => { if (this.info.type === "dir") { return reject( - API.throwe( - __("{0} is not a file", this.path) - ) + API.throwe(__("{0} is not a file", this.path)) ); } return API.handle @@ -1354,12 +1680,13 @@ namespace OS { } /** + * Un publish the file * - * + * @protected * @returns {Promise} * @memberof SharedFileHandle */ - _pub(): Promise { + protected _pub(): Promise { return new Promise((resolve, reject) => resolve({ result: this.basename,