nesoi 3.0.8 → 3.0.10

package/lib/engine/dependency.d.ts

@@ -1,4 +1,4 @@
-import { BuilderType } from "../schema";
+import { $Module, BuilderType } from "../schema";
 import { AnyBuilder, AnyElementSchema } from './module';
 import { Overlay } from './util/type';
 import { JobBuilderNode } from "../elements/blocks/job/job.builder";
@@ -6,28 +6,87 @@ 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;
+    static resolve(module: $Module, dep: $Dependency): import("../elements").$Message | import("../elements").$Machine | import("../elements").$Bucket | import("../elements").$Constants | import("../elements").$Job | import("../elements").$Externals | import("../elements").$Resource | import("../elements").$Controller | undefined;
 }
+/**
+ * A element builder, along with metadata required for building it.
+ *
+ * @category Engine
+ */
 export declare class BuilderNode {
     module: string;
     type: BuilderType;
@@ -47,6 +106,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);
@@ -74,8 +121,31 @@ class $Dependency {
                 .type;
         }
     }
+    static resolve(module, dep) {
+        if (dep.type === 'constants')
+            return module.constants;
+        if (dep.type === 'externals')
+            return module.externals;
+        if (dep.type === 'bucket')
+            return module.buckets[dep.name];
+        if (dep.type === 'message')
+            return module.messages[dep.name];
+        if (dep.type === 'job')
+            return module.jobs[dep.name];
+        if (dep.type === 'resource')
+            return module.resources[dep.name];
+        if (dep.type === 'machine')
+            return module.machines[dep.name];
+        if (dep.type === 'controller')
+            return module.controllers[dep.name];
+    }
 }
 exports.$Dependency = $Dependency;
+/**
+ * A element builder, along with metadata required for building it.
+ *
+ * @category Engine
+ */
 class BuilderNode {
     constructor($) {
         this.module = $.module;

package/lib/engine/module.d.ts

@@ -15,8 +15,8 @@ import { Bucket } from "../elements/entities/bucket/bucket";
 import { $Constants } from "../elements/entities/constants/constants.schema";
 import { ConstantsBuilder } from "../elements/entities/constants/constants.builder";
 import { AnyControllerBuilder } from "../elements/edge/controller/controller.builder";
-import { AnyExternalsBuilder } from "../elements/blocks/externals/externals.builder";
-import { $Externals } from "../elements/blocks/externals/externals.schema";
+import { AnyExternalsBuilder } from "../elements/edge/externals/externals.builder";
+import { $Externals } from "../elements/edge/externals/externals.schema";
 import { $Dependency, ResolvedBuilderNode } from './dependency';
 import { $Bucket } from "../elements/entities/bucket/bucket.schema";
 import { $Resource } from "../elements/blocks/resource/resource.schema";
@@ -26,6 +26,7 @@ import { $Job } from "../elements/blocks/job/job.schema";
 import { ModuleTree } from './tree';
 import { AnyResourceJobBuilder } from "../elements/blocks/job/internal/resource_job.builder";
 import { AnyApp } from './apps/app';
+import { AnyService } from './apps/service';
 import { AnyMachineJobBuilder } from "../elements/blocks/job/internal/machine_job.builder";
 import { AnyQueueBuilder } from "../elements/blocks/queue/queue.builder";
 import { $Queue } from "../elements/blocks/queue/queue.schema";
@@ -46,6 +47,20 @@ export type VirtualModuleDef = {
         jobs?: $Dependency[];
     };
 };
+/**
+ * A `Module` is an isolated named collection of _Elements_.
+ *
+ * Modules should be designed to work in isolation as much as possible.
+ * When declaring external dependencies, these can be injected into the
+ * module or linked externally through REST or other means.
+ *
+ * Each `Module` has a _Transaction Engine_, which keeps track of
+ * transactions performed with the Module elements.
+ * Transactions can be shared between engines, to allow for a tracking
+ * of distributed applications.
+ *
+ * @category Engine
+ */
 export declare class Module<S extends $Space, $ extends $Module> {
     name: string;
     schema: $;
@@ -56,19 +71,48 @@ export declare class Module<S extends $Space, $ extends $Module> {
     machines: { [B in keyof $["machines"]]: Machine<S, $, $["machines"][B]>; };
     queues: { [B in keyof $["queues"]]: Queue<$, $["queues"][B]>; };
     controllers: { [B in keyof $["controllers"]]: Controller<S, $, $["controllers"][B]>; };
+    /**
+     * Daemon which is running the current module.
+     * This is `undefined` when the _Module_ is created for compiling.
+     */
     daemon?: AnyDaemon;
+    /**
+     * NQL (Nesoi Query Language) Engine for this module.
+     */
     nql: NQL_Engine;
+    /**
+     * The boot source for this module:
+     * - `dirpath`: This module is being run from a Space (Framework mode), so
+     * source is the module directory, from which builders will be read
+     * - `builders`: This module is being run in Library mode, so source is
+     * a list of builders
+     */
     boot?: {
-        path: string;
+        dirpath: string;
     } | {
         builders: AnyBuilder[];
     };
+    /**
+     * @param name A module name
+     * @param boot The boot source for this module
+     */
     constructor(name: string, boot?: {
-        path: string;
+        dirpath: string;
     } | {
         builders: AnyBuilder[];
     });
+    /**
+     * Log the module elements
+     */
     info(): void;
+    /**
+     * Inject element schemas into the module.
+     * This is used on the compiled version of the `App`, which has
+     * the schemas pre-built, so it directly injects them.
+     *
+     * @param schemas A dictionary of schema(s) by element type
+     * @returns The `Module`, for call-chaining
+     */
     inject(schemas: {
         externals?: $Externals;
         constants?: $Constants;
@@ -80,19 +124,77 @@ export declare class Module<S extends $Space, $ extends $Module> {
         queues?: $Queue[];
         controllers?: $Controller[];
     }): this;
-    injectDependencies(daemon: AnyDaemon, dependencies: {
+    /**
+     * Include references for external elements on the module.
+     * This allows a module to use elements from other modules directly,
+     * on single-threaded `Apps`.
+     * This implementation also includes transitive dependencies.
+     *
+     * @param daemon A `Daemon` instance
+     * @param dependencies: A dictionary of dependencies by element type
+     * @returns The `Module`, for call-chaining
+     */
+    injectDependencies(modules: Record<string, AnyModule>, dependencies: {
         buckets?: $Dependency[];
         jobs?: $Dependency[];
         messages?: $Dependency[];
         machines?: $Dependency[];
     }): this;
-    scanFiles(dir: string, exclude?: string[]): string[];
+    /**
+     * Recursively find all files inside the module dir.
+     *
+     * @param dirpath A directory to scan
+     * @param exclude: A list of patterns to ignore
+     * @returns A list of file paths
+     */
+    scanFiles(dirpath: string, exclude?: string[]): string[];
+    /**
+     * Build a resolved builder node, then merge the
+     * resulting schema(s) to the module.
+     * This also merges the resulting inline nodes of building a node.
+     *
+     * @param node A resolved builder node
+     * @param tree A module tree
+     */
     buildNode(node: ResolvedBuilderNode, tree: ModuleTree): Promise<void>;
+    /**
+     * Merge inline message schemas into the module.
+     *
+     * @param node A resolved builder node
+     * @param schemas A dictionary of Message schemas by name
+     */
     private mergeInlineMessages;
+    /**
+     * Merge inline job schemas into the module.
+     *
+     * @param node A resolved builder node
+     * @param schemas A dictionary of job schemas by name
+     */
     private mergeInlineJobs;
-    start(app: AnyApp, providers: Record<string, any>): void;
+    /**
+     * Create elements from schemas, and the NQL engine for this module.
+     *
+     * @param app A `App` instance
+     * @param services A dictionary of services by name
+     */
+    start(app: AnyApp, services: Record<string, AnyService>): void;
+    /**
+     * Destroy all elements from module.
+     */
     destroy(): void;
-    private destroyBlock;
+    /**
+     * Destroy one element from module.
+     */
+    private destroyElement;
+    /**
+     * Create a virtual module from a definition.
+     * A virtual module can be used to dynamically create
+     * and use schemas with limited access to the application elements.
+     *
+     * @param daemon A `Daemon` instance
+     * @param def A definition for a Virtual Module
+     * @returns A `Module` instance
+     */
     static virtual(daemon: AnyDaemon, def: VirtualModuleDef): Promise<Module<$Space, $Module>>;
 }
 export type AnyModule = Module<any, any>;