nesoi 3.0.8 → 3.0.10

package/lib/engine/daemon.d.ts

@@ -6,31 +6,118 @@ import { AnyUsers, AuthnRequest } from './auth/authn';
 import { TrxNode } from './transaction/trx_node';
 import { TrxStatus } from './transaction/trx';
 import { AnyModule } from './module';
+import { IService } from './apps/service';
+/**
+ * A background process running one or more modules,
+ * which runs _Transactions_ for the available elements.
+ *
+ * A `Daemon` is spawn by an `App`.
+ *
+ * @category Engine
+ */
 export declare abstract class Daemon<S extends $Space, Modules extends ModuleName<S>> {
     protected name: string;
     protected trxEngines: Record<Modules, AnyTrxEngine>;
-    protected providers: Record<string, any>;
-    protected app?: AnyAppConfig | undefined;
-    private _cli?;
-    constructor(name: string, trxEngines: Record<Modules, AnyTrxEngine>, providers: Record<string, any>, app?: AnyAppConfig | undefined);
+    protected services: Record<string, IService>;
+    protected config?: AnyAppConfig | undefined;
+    /**
+     * @param name Name of the daemon (taken from App)
+     * @param trxEngines A dictionary of Transaction Engine by module name
+     * @param services A dictionary of Service by name
+     * @param config Optional `AppConfig`
+     */
+    constructor(name: string, trxEngines: Record<Modules, AnyTrxEngine>, services: Record<string, IService>, config?: AnyAppConfig | undefined);
+    /**
+     * Prepare a transaction to be run by the Daemon.
+     *
+     * @param moduleName Name of the module where to run the transactoin
+     * @returns A `DaemonTrx` instance, which can be run
+     */
     trx<K extends Modules & keyof S['modules']>(moduleName: K): DaemonTrx<S, S["modules"][K], {}>;
+    /**
+     * Run the Nesoi CLI for this Daemon.
+     */
     cli(cmd?: string): Promise<void>;
+    /**
+     * Bind the controller of each module to this Daemon.
+     * This allows the registered `Controller Adapters` to run
+     * transactions on the daemon.
+     */
     private bindControllers;
-    static destroy(daemon: AnyDaemon): Promise<void>;
-    static reload(daemon: AnyDaemon, trxEngines: Record<string, AnyTrxEngine>, providers: Record<string, any>): void;
+    /**
+     * Destroy the services and transaction engines of this daemon
+     *
+     * @param A `Daemon` instance
+     */
+    destroy(): Promise<void>;
+    /**
+     * Replace the services and transaction engines of this daemon
+     * and rebind the controllers
+     *
+     * @param daemon A `Daemon` instance
+     * @param trxEngines A dictionary of Transaction Engine by module name
+     * @param services A dictionary of Service by name
+     */
+    reload(trxEngines: Record<Modules, AnyTrxEngine>, services: Record<string, any>): void;
+    /**
+     * Return a `Daemon` property.
+     * This is used to read private properties.
+     *
+     * @param daemon A `Daemon` instance
+     * @param key A `Daemon` property `'name'|'services'|'app'`
+     * @returns The selected property
+     */
     static get<T extends {
         name: string;
-        providers: Record<string, any>;
+        services: Record<string, any>;
         app: AnyAppConfig;
     }, K extends keyof T>(daemon: AnyDaemon | undefined, key: K): T[K];
-    static getModule<Modules extends ModuleName<any>, D extends Daemon<any, Modules>>(daemon: D, module: Modules): import("./module").Module<any, any>;
+    /**
+     * Return one module of the `Daemon` by name.
+     *
+     * @param daemon A `Daemon` instance
+     * @param module A module name
+     * @returns The `Module` instance
+     */
+    static getModule<Module extends ModuleName<any>, D extends Daemon<any, Module>>(daemon: D, module: Module): import("./module").Module<any, any>;
+    /**
+     * Return all modules of the `Daemon`.
+     *
+     * @param daemon A `Daemon` instance
+     * @returns The `Module` instances
+     */
     static getModules(daemon: AnyDaemon): AnyModule[];
 }
+/**
+ * A helper class for preparing a transaction to be run.
+ * It allows declaring authentication data before running
+ * the transaction.
+ *
+ * @category Engine
+ */
 export declare class DaemonTrx<S extends $Space, M extends $Module, Authn extends AnyUsers = {}> {
     private trxEngine;
-    private _authn?;
+    /**
+     * The authentication request which will be used to
+     * authenticate this transaction prior to running.
+     */
+    private authnRequest?;
+    /**
+     * @param trxEngine The transaction engine where to run the transaction.
+     */
     constructor(trxEngine: AnyTrxEngine);
+    /**
+     * Authenticate the transaction with the given credentials.
+     * You can specify one or more credentials, so the transaction
+     * is able to access elements with different authn providers.
+     */
     authn<Authn extends AuthnRequest<keyof S['authnUsers']>>(authn?: Authn): DaemonTrx<S, M, { [K in keyof Authn]: S["authnUsers"][K & keyof S["authnUsers"]]; }>;
+    /**
+     * Run a method inside the transaction.
+     *
+     * @param fn A function to execute inside the transaction
+     * @returns A `TrxStatus` containing metadata about the transaction and the function response
+     */
     run<Output>(fn: (trx: TrxNode<S, M, Authn>) => Promise<Output>): Promise<TrxStatus<Output>>;
 }
 export type AnyDaemon = Daemon<any, any>;

package/lib/engine/daemon.js

@@ -4,15 +4,35 @@ exports.DaemonTrx = exports.Daemon = void 0;
 const log_1 = require("./util/log");
 const error_1 = require("./data/error");
 const cli_1 = require("./cli/cli");
+/**
+ * A background process running one or more modules,
+ * which runs _Transactions_ for the available elements.
+ *
+ * A `Daemon` is spawn by an `App`.
+ *
+ * @category Engine
+ */
 class Daemon {
-    constructor(name, trxEngines, providers, app) {
+    /**
+     * @param name Name of the daemon (taken from App)
+     * @param trxEngines A dictionary of Transaction Engine by module name
+     * @param services A dictionary of Service by name
+     * @param config Optional `AppConfig`
+     */
+    constructor(name, trxEngines, services, config) {
         this.name = name;
         this.trxEngines = trxEngines;
-        this.providers = providers;
-        this.app = app;
+        this.services = services;
+        this.config = config;
         this.bindControllers();
         log_1.Log.info('daemon', name, 'Woo-ha!');
     }
+    /**
+     * Prepare a transaction to be run by the Daemon.
+     *
+     * @param moduleName Name of the module where to run the transactoin
+     * @returns A `DaemonTrx` instance, which can be run
+     */
     trx(moduleName) {
         const trxEngine = this.trxEngines[moduleName];
         if (!trxEngine) {
@@ -20,10 +40,18 @@ class Daemon {
         }
         return new DaemonTrx(trxEngine);
     }
+    /**
+     * Run the Nesoi CLI for this Daemon.
+     */
     async cli(cmd) {
-        this._cli = new cli_1.CLI(this, this.app?.cli);
-        await this._cli.run(cmd);
+        const cli = new cli_1.CLI(this, this.config?.cli);
+        await cli.run(cmd);
     }
+    /**
+     * Bind the controller of each module to this Daemon.
+     * This allows the registered `Controller Adapters` to run
+     * transactions on the daemon.
+     */
     bindControllers() {
         log_1.Log.info('daemon', this.name, 'Binding controllers');
         for (const t in this.trxEngines) {
@@ -34,45 +62,100 @@ class Daemon {
             }
         }
     }
-    static async destroy(daemon) {
+    /**
+     * Destroy the services and transaction engines of this daemon
+     *
+     * @param A `Daemon` instance
+     */
+    async destroy() {
         log_1.Log.info('daemon', this.name, 'Stop');
-        for (const key in daemon.providers) {
-            const provider = daemon.providers[key];
-            await provider.__down(provider);
-            delete daemon.providers[key];
+        for (const key in this.services) {
+            const service = this.services[key];
+            await service.down();
+            delete this.services[key];
         }
-        for (const key in daemon.trxEngines) {
-            delete daemon.trxEngines[key];
+        for (const key in this.trxEngines) {
+            delete this.trxEngines[key];
         }
     }
-    static reload(daemon, trxEngines, providers) {
+    /**
+     * Replace the services and transaction engines of this daemon
+     * and rebind the controllers
+     *
+     * @param daemon A `Daemon` instance
+     * @param trxEngines A dictionary of Transaction Engine by module name
+     * @param services A dictionary of Service by name
+     */
+    reload(trxEngines, services) {
         log_1.Log.info('daemon', this.name, 'Reloaded');
-        daemon.trxEngines = trxEngines;
-        daemon.providers = providers;
-        daemon.bindControllers();
+        this.trxEngines = trxEngines;
+        this.services = services;
+        this.bindControllers();
     }
+    /**
+     * Return a `Daemon` property.
+     * This is used to read private properties.
+     *
+     * @param daemon A `Daemon` instance
+     * @param key A `Daemon` property `'name'|'services'|'app'`
+     * @returns The selected property
+     */
     static get(daemon, key) {
         return daemon?.[key];
     }
+    /**
+     * Return one module of the `Daemon` by name.
+     *
+     * @param daemon A `Daemon` instance
+     * @param module A module name
+     * @returns The `Module` instance
+     */
     static getModule(daemon, module) {
         return daemon.trxEngines[module].getModule();
     }
+    /**
+     * Return all modules of the `Daemon`.
+     *
+     * @param daemon A `Daemon` instance
+     * @returns The `Module` instances
+     */
     static getModules(daemon) {
         return Object.values(daemon.trxEngines)
             .map((trx) => trx.getModule());
     }
 }
 exports.Daemon = Daemon;
+/**
+ * A helper class for preparing a transaction to be run.
+ * It allows declaring authentication data before running
+ * the transaction.
+ *
+ * @category Engine
+ */
 class DaemonTrx {
+    /**
+     * @param trxEngine The transaction engine where to run the transaction.
+     */
     constructor(trxEngine) {
         this.trxEngine = trxEngine;
     }
+    /**
+     * Authenticate the transaction with the given credentials.
+     * You can specify one or more credentials, so the transaction
+     * is able to access elements with different authn providers.
+     */
     authn(authn) {
-        this._authn = authn;
+        this.authnRequest = authn;
         return this;
     }
+    /**
+     * Run a method inside the transaction.
+     *
+     * @param fn A function to execute inside the transaction
+     * @returns A `TrxStatus` containing metadata about the transaction and the function response
+     */
     async run(fn) {
-        return this.trxEngine.trx(fn, this._authn);
+        return this.trxEngine.trx(fn, this.authnRequest);
     }
 }
 exports.DaemonTrx = DaemonTrx;

package/lib/engine/data/date.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @category Engine
+ * @subcategory Data
+ */
 export declare class NesoiDate {
     day: number;
     month: number;

package/lib/engine/data/date.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NesoiDate = void 0;
 const error_1 = require("./error");
+/**
+ * @category Engine
+ * @subcategory Data
+ */
 class NesoiDate {
     constructor(day, month, year) {
         this.day = day;

package/lib/engine/data/datetime.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @category Engine
+ * @subcategory Data
+ */
 export declare class NesoiDatetime {
     static tz: {
         '-12:00': string;

package/lib/engine/data/datetime.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NesoiDatetime = void 0;
 const error_1 = require("./error");
+/**
+ * @category Engine
+ * @subcategory Data
+ */
 class NesoiDatetime {
     constructor(epoch, tz = 'Z') {
         this.epoch = epoch || new Date().getTime();

package/lib/engine/data/decimal.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @category Engine
+ * @subcategory Data
+ */
 export declare class NesoiDecimal {
     private neg;
     private left;

package/lib/engine/data/decimal.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NesoiDecimal = void 0;
 const error_1 = require("./error");
+/**
+ * @category Engine
+ * @subcategory Data
+ */
 class NesoiDecimal {
     constructor(value, pLeft = 12, pRight = 12) {
         this.neg = false;

package/lib/engine/data/file.d.ts

@@ -1,5 +1,22 @@
-import { TrxNode } from '../transaction/trx_node';
-import { $Module } from "../../elements";
+/**
+ * @category Engine
+ * @subcategory Data
+ */
+export declare class LocalNesoiFile {
+    /**
+     * - If not overriden, `extname` is derived from `filepath`
+     *   - If `overrides.originalFilename` is passed, `extname` is derived from it (this allows saving the file without extension, but keeping the information on NesoiFile).
+     * - If not overriden, `mimetype` is derived from the resolved `extname`
+     */
+    static from(filepath: string, overrides?: Partial<NesoiFile>): NesoiFile;
+    static delete(file: NesoiFile): void;
+    static move(file: NesoiFile, to: string): void;
+    static read(file: NesoiFile): string;
+}
+/**
+ * @category Engine
+ * @subcategory Data
+ */
 export declare class NesoiFile {
     __nesoi_file: boolean;
     filepath: string;
@@ -8,31 +25,14 @@ export declare class NesoiFile {
     mimetype: string | null;
     size: number;
     originalFilename: string | null;
-    newFilename: string;
     mtime: Date | null;
     hashAlgorithm: false | 'sha1' | 'md5' | 'sha256';
-    private _hash;
-    constructor(filepath: string, extra?: {
-        originalFilename?: string | null;
-        newFilename?: string | null;
-    });
+    private hash;
+    constructor(filepath: string, filename: string, extname: string, mimetype: string | null, size: number, originalFilename: string | null, mtime: Date | null);
+    static from(file: NesoiFile, overrides: Partial<NesoiFile>): NesoiFile;
     static hash(file: NesoiFile, hashAlgorithm: 'sha1' | 'md5' | 'sha256'): Promise<{
         algorithm: "sha1" | "sha256" | "md5";
         hash: string | object;
     }>;
-    static delete<M extends $Module>($: {
-        trx: TrxNode<any, M, any>;
-    }, bucket: keyof M['buckets'], file: NesoiFile, options?: {
-        silent?: boolean;
-    }): Promise<void> | undefined;
-    static move<M extends $Module>($: {
-        trx: TrxNode<any, M, any>;
-    }, bucket: keyof M['buckets'], file: NesoiFile, to: string, options?: {
-        silent?: boolean;
-    }): Promise<void>;
-    static read<M extends $Module>($: {
-        trx: TrxNode<any, M, any>;
-    }, bucket: keyof M['buckets'], file: NesoiFile, options?: {
-        silent?: boolean;
-    }): Promise<void>;
+    static local: typeof LocalNesoiFile;
 }

package/lib/engine/data/file.js

@@ -3,52 +3,89 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NesoiFile = void 0;
+exports.NesoiFile = exports.LocalNesoiFile = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const hash_1 = require("../util/hash");
 const mime_1 = require("../util/mime");
-// Based on [formidable](https://github.com/node-formidable/formidable)
+/**
+ * @category Engine
+ * @subcategory Data
+ */
+class LocalNesoiFile {
+    /**
+     * - If not overriden, `extname` is derived from `filepath`
+     *   - If `overrides.originalFilename` is passed, `extname` is derived from it (this allows saving the file without extension, but keeping the information on NesoiFile).
+     * - If not overriden, `mimetype` is derived from the resolved `extname`
+     */
+    static from(filepath, overrides) {
+        const filename = overrides?.filename || path_1.default.basename(filepath);
+        let extname;
+        if (overrides?.extname) {
+            extname = overrides.extname;
+        }
+        else {
+            if (overrides?.originalFilename) {
+                extname = path_1.default.extname(overrides?.originalFilename).slice(1);
+            }
+            else {
+                extname = path_1.default.extname(filepath).slice(1);
+            }
+        }
+        const mimetype = overrides?.mimetype || mime_1.Mime.ofExtname(extname);
+        const stat = fs_1.default.statSync(filepath);
+        const mtime = stat.mtime;
+        const size = stat.size;
+        const originalFilename = overrides?.originalFilename || null;
+        return new NesoiFile(filepath, filename, extname, mimetype, size, originalFilename, mtime);
+    }
+    static delete(file) {
+        fs_1.default.rmSync(file.filepath);
+    }
+    static move(file, to) {
+        fs_1.default.renameSync(file.filepath, to);
+        file.filepath = to;
+        file.filename = path_1.default.basename(to);
+    }
+    static read(file) {
+        return fs_1.default.readFileSync(file.filepath).toString();
+    }
+}
+exports.LocalNesoiFile = LocalNesoiFile;
+/**
+ * @category Engine
+ * @subcategory Data
+ */
 class NesoiFile {
-    constructor(filepath, extra) {
+    constructor(filepath, filename, extname, mimetype, size, originalFilename, mtime) {
         this.__nesoi_file = true;
+        // Algorithm used to generate the hash
         this.hashAlgorithm = false;
         // Only available after `.hash` is called
-        this._hash = null;
+        this.hash = null;
         this.filepath = filepath;
-        this.filename = path_1.default.basename(filepath);
-        const mime = mime_1.Mime.ofFilepath(filepath);
-        this.extname = extra?.originalFilename
-            ? path_1.default.extname(extra.originalFilename).slice(1)
-            : mime.extname;
-        this.mimetype = mime.mimetype;
-        const stat = fs_1.default.statSync(filepath);
-        this.size = stat.size;
-        this.originalFilename = extra?.originalFilename || null;
-        this.newFilename = extra?.newFilename || this.filename;
-        this.mtime = stat.mtime;
+        this.filename = filename;
+        this.extname = extname;
+        this.mimetype = mimetype;
+        this.size = size;
+        this.originalFilename = originalFilename;
+        this.mtime = mtime;
+    }
+    static from(file, overrides) {
+        return new NesoiFile(overrides.filepath || file.filepath, overrides.filename || file.filename, overrides.extname || file.extname, overrides.mimetype || file.mimetype, overrides.size || file.size, overrides.originalFilename || file.originalFilename, overrides.mtime || file.mtime);
     }
     static async hash(file, hashAlgorithm) {
-        if (!file._hash) {
+        if (!file.hash) {
             file.hashAlgorithm = hashAlgorithm;
-            file._hash = hash_1.Hash.file(file.filepath, file.hashAlgorithm).then(hash => {
-                file._hash = hash;
+            file.hash = hash_1.Hash.file(file.filepath, file.hashAlgorithm).then(hash => {
+                file.hash = hash;
             });
         }
         return {
             algorithm: hashAlgorithm,
-            hash: file._hash
+            hash: file.hash
         };
     }
-    static delete($, bucket, file, options) {
-        return $.trx.bucket(bucket).drive.delete(file, options);
-    }
-    static async move($, bucket, file, to, options) {
-        await $.trx.bucket(bucket).drive.move(file, to, options);
-        file.filepath = to;
-    }
-    static async read($, bucket, file, options) {
-        await $.trx.bucket(bucket).drive.read(file, options);
-    }
 }
 exports.NesoiFile = NesoiFile;
+NesoiFile.local = LocalNesoiFile;

package/lib/engine/data/json.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @category Engine
+ * @subcategory Data
+ */
 export declare class NesoiJSON {
     /**
      * Dumps an object to

package/lib/engine/data/json.js

@@ -4,6 +4,10 @@ exports.NesoiJSON = void 0;
 const date_1 = require("./date");
 const datetime_1 = require("./datetime");
 const decimal_1 = require("./decimal");
+/**
+ * @category Engine
+ * @subcategory Data
+ */
 class NesoiJSON {
     /**
      * Dumps an object to

package/lib/engine/data/tree.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @category Engine
+ * @subcategory Data
+ */
 export declare class Tree {
     /**
      * Read one or more values from the object, from a _fieldpath_.

package/lib/engine/data/tree.js

@@ -5,6 +5,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Tree = void 0;
 const error_1 = require("./error");
+/**
+ * @category Engine
+ * @subcategory Data
+ */
 class Tree {
     /**
      * Read one or more values from the object, from a _fieldpath_.