nesoi 3.0.8 → 3.0.9

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 providers A dictionary of App Provider by name
+     * @param config Optional `AppConfig`
+     */
+    constructor(name, trxEngines, providers, config) {
         this.name = name;
         this.trxEngines = trxEngines;
         this.providers = providers;
-        this.app = app;
+        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 {
             }
         }
     }
+    /**
+     * Destroy the providers and transaction engines of this daemon
+     *
+     * @param A `Daemon` instance
+     */
     static async destroy(daemon) {
         log_1.Log.info('daemon', this.name, 'Stop');
         for (const key in daemon.providers) {
             const provider = daemon.providers[key];
-            await provider.__down(provider);
+            await provider.down(provider);
             delete daemon.providers[key];
         }
         for (const key in daemon.trxEngines) {
             delete daemon.trxEngines[key];
         }
     }
+    /**
+     * Replace the providers 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 providers A dictionary of App Provider by name
+     */
     static reload(daemon, trxEngines, providers) {
         log_1.Log.info('daemon', this.name, 'Reloaded');
         daemon.trxEngines = trxEngines;
         daemon.providers = providers;
         daemon.bindControllers();
     }
+    /**
+     * Return a `Daemon` property.
+     * This is used to read private properties.
+     *
+     * @param daemon A `Daemon` instance
+     * @param key A `Daemon` property `'name'|'providers'|'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_.

package/lib/engine/dependency.d.ts

@@ -6,28 +6,86 @@ import { MessageBuilderNode } from "../elements/entities/message/message.builder
 import { ResourceJobBuilderNode } from "../elements/blocks/job/internal/resource_job.builder";
 import { BucketFnExtract, JobFnExtract, MachineFnExtract, MessageFnExtract } from "../compiler/typescript/bridge/organize";
 import { MachineJobBuilderNode } from "../elements/blocks/job/internal/machine_job.builder";
+/**
+ * Utility class for parsing element `tags`.
+ *
+ * A `tag` is a string which references an element
+ * on the `Space`, following one of the formats below:
+ * ```
+ * module::type:name
+ * module::name
+ * type:name
+ * name
+ * ```
+ *
+ * @category Engine
+ */
 export declare class $Tag {
+    /**
+     * Parse `module?`, `type?` and `name` from a tag string.
+     *
+     * @param tag A tag string
+     * @returns An object containing the parsed tag info or `undefined`
+     * if it's an invalid tag.
+     */
     static parse(tag: string): {
         module: string | undefined;
         type: string | undefined;
         name: string;
     } | undefined;
+    /**
+     * Parse `module?`, `type?` and `name` from a tag string.
+     *
+     * @param tag A tag string
+     * @returns An object containing the parsed tag info
+     * @throws If it's an invalid tag
+     */
     static parseOrFail(tag: string): {
-        module: string;
-        type: string;
+        module: string | undefined;
+        type: string | undefined;
         name: string;
     };
 }
+/**
+ * A reference for an element, declared from another element.
+ *
+ * @category Engine
+ */
 export declare class $Dependency {
+    /** Low name of the module*/
     module: string;
+    /** Type of node */
     type: BuilderType;
+    /** Low name of the node */
     name: string;
+    /** `module::type:name` */
     tag: string;
+    /** `name` if dependency is local, `module::name` if is external */
     refName: string;
+    /** If true, this dependency doesn't affect build order */
     soft: boolean;
+    /**
+     * @param fromModule Name of module which uses this dependency
+     * @param type Type of referenced element
+     * @param name Name of referenced element
+     * @param soft True if this doesn't affect build order
+     */
     constructor(fromModule: string, type: BuilderType, name: string, soft?: boolean);
+    /**
+     * Return the type name (UpperCamel) of the element
+     * referenced by a dependency.
+     *
+     * @param dep A `$Dependency` instance
+     * @param fromModule Name of dependant module
+     * @returns The type name of the dependency
+     */
     static typeName(dep: $Dependency, fromModule: string): string;
 }
+/**
+ * A element builder, along with metadata required for building it.
+ *
+ * @category Engine
+ */
 export declare class BuilderNode {
     module: string;
     type: BuilderType;
@@ -47,6 +105,9 @@ export declare class BuilderNode {
         builder: AnyBuilder;
     });
 }
+/**
+ * A builder node with the dependencies resolved to references to other nodes.
+ */
 export type ResolvedBuilderNode = Overlay<BuilderNode, {
     _dependencies?: ResolvedBuilderNode[];
     dependencies: {

package/lib/engine/dependency.js

@@ -2,7 +2,28 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BuilderNode = exports.$Dependency = exports.$Tag = void 0;
 const name_helpers_1 = require("../compiler/helpers/name_helpers");
+/**
+ * Utility class for parsing element `tags`.
+ *
+ * A `tag` is a string which references an element
+ * on the `Space`, following one of the formats below:
+ * ```
+ * module::type:name
+ * module::name
+ * type:name
+ * name
+ * ```
+ *
+ * @category Engine
+ */
 class $Tag {
+    /**
+     * Parse `module?`, `type?` and `name` from a tag string.
+     *
+     * @param tag A tag string
+     * @returns An object containing the parsed tag info or `undefined`
+     * if it's an invalid tag.
+     */
     static parse(tag) {
         const match = tag.match(/(.\w*?::)?(\w*?:)?(.*)/);
         const module = match?.[1]?.slice(0, -2);
@@ -17,6 +38,13 @@ class $Tag {
         }
         return { module, type, name };
     }
+    /**
+     * Parse `module?`, `type?` and `name` from a tag string.
+     *
+     * @param tag A tag string
+     * @returns An object containing the parsed tag info
+     * @throws If it's an invalid tag
+     */
     static parseOrFail(tag) {
         const match = tag.match(/(.\w*?::)?(\w*?:)?(.*)/);
         if (!match) {
@@ -41,7 +69,18 @@ class $Tag {
     }
 }
 exports.$Tag = $Tag;
+/**
+ * A reference for an element, declared from another element.
+ *
+ * @category Engine
+ */
 class $Dependency {
+    /**
+     * @param fromModule Name of module which uses this dependency
+     * @param type Type of referenced element
+     * @param name Name of referenced element
+     * @param soft True if this doesn't affect build order
+     */
     constructor(fromModule, type, name, soft = false) {
         this.type = type;
         this.soft = soft;
@@ -61,6 +100,14 @@ class $Dependency {
             this.refName = `${this.module}::${this.name}`;
         }
     }
+    /**
+     * Return the type name (UpperCamel) of the element
+     * referenced by a dependency.
+     *
+     * @param dep A `$Dependency` instance
+     * @param fromModule Name of dependant module
+     * @returns The type name of the dependency
+     */
     static typeName(dep, fromModule) {
         if (dep.module !== fromModule) {
             const moduleHigh = name_helpers_1.NameHelpers.nameLowToHigh(dep.module);
@@ -76,6 +123,11 @@ class $Dependency {
     }
 }
 exports.$Dependency = $Dependency;
+/**
+ * A element builder, along with metadata required for building it.
+ *
+ * @category Engine
+ */
 class BuilderNode {
     constructor($) {
         this.module = $.module;