nesoi 3.0.8 → 3.0.10

package/lib/engine/module.js

@@ -52,17 +52,34 @@ const bucket_1 = require("../elements/entities/bucket/bucket");
 const constants_schema_1 = require("../elements/entities/constants/constants.schema");
 const constants_builder_1 = require("../elements/entities/constants/constants.builder");
 const controller_builder_1 = require("../elements/edge/controller/controller.builder");
-const externals_builder_1 = require("../elements/blocks/externals/externals.builder");
+const externals_builder_1 = require("../elements/edge/externals/externals.builder");
 const error_1 = require("./data/error");
-const externals_schema_1 = require("../elements/blocks/externals/externals.schema");
+const externals_schema_1 = require("../elements/edge/externals/externals.schema");
 const app_1 = require("./apps/app");
 const queue_builder_1 = require("../elements/blocks/queue/queue.builder");
 const nql_engine_1 = require("../elements/entities/bucket/query/nql_engine");
 const daemon_1 = require("./daemon");
+/**
+ * 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
+ */
 class Module {
+    /**
+     * @param name A module name
+     * @param boot The boot source for this module
+     */
     constructor(name, boot) {
         this.name = name;
-        // Schemas built by this module
         this.schema = {
             constants: new constants_schema_1.$Constants(this.name),
             externals: new externals_schema_1.$Externals(this.name),
@@ -87,6 +104,9 @@ class Module {
         this.schema.name = name;
         this.boot = boot;
     }
+    /**
+     * Log the module elements
+     */
     info() {
         log_1.Log.info('module', this.name, 'Loaded', {
             values: Object.keys(this.schema.constants.values),
@@ -101,6 +121,14 @@ class Module {
         });
     }
     // Manual injection
+    /**
+     * 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) {
         if (schemas.externals) {
             externals_schema_1.$Externals.merge(this.schema.externals, schemas.externals);
@@ -131,9 +159,19 @@ class Module {
         });
         return this;
     }
-    injectDependencies(daemon, 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, dependencies) {
         dependencies.buckets?.forEach(dep => {
-            const bucketModule = daemon_1.Daemon.getModule(daemon, dep.module);
+            const bucketModule = modules[dep.module];
             const bucket = bucketModule.buckets[dep.name];
             if (!bucket) {
                 throw new Error(`Internal Error: unable to find bucket '${dep.tag}' during injection to module '${this.name}'`);
@@ -141,15 +179,19 @@ class Module {
             this.buckets[dep.refName] = bucket;
         });
         dependencies.jobs?.forEach(dep => {
-            const jobModule = daemon_1.Daemon.getModule(daemon, dep.module);
+            const jobModule = modules[dep.module];
             const job = jobModule.jobs[dep.name];
             if (!job) {
                 throw new Error(`Internal Error: unable to find job '${dep.tag}' during injection to module '${this.name}'`);
             }
             this.jobs[dep.refName] = job;
+            const schema = job.schema;
+            this.injectDependencies(modules, {
+                messages: schema.input
+            });
         });
         dependencies.messages?.forEach(dep => {
-            const messageModule = daemon_1.Daemon.getModule(daemon, dep.module);
+            const messageModule = modules[dep.module];
             const message = messageModule.messages[dep.name];
             if (!message) {
                 throw new Error(`Internal Error: unable to find message '${dep.tag}' during injection to module '${this.name}'`);
@@ -157,21 +199,34 @@ class Module {
             this.messages[dep.refName] = message;
         });
         dependencies.machines?.forEach(dep => {
-            const machineModule = daemon_1.Daemon.getModule(daemon, dep.module);
+            const machineModule = modules[dep.module];
             const machine = machineModule.machines[dep.name];
             if (!machine) {
                 throw new Error(`Internal Error: unable to find machine '${dep.tag}' during injection to module '${this.name}'`);
             }
             this.machines[dep.refName] = machine;
+            const schema = machine.schema;
+            this.injectDependencies(modules, {
+                messages: schema.input,
+                buckets: schema.buckets,
+                jobs: schema.jobs
+            });
         });
         return this;
     }
     // Treeshaking
-    scanFiles(dir, exclude = []) {
+    /**
+     * 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, exclude = []) {
         const files = [];
-        fs.readdirSync(dir, { withFileTypes: true })
+        fs.readdirSync(dirpath, { withFileTypes: true })
             .forEach(node => {
-            const nodePath = path.resolve(dir, node.name);
+            const nodePath = path.resolve(dirpath, node.name);
             // TODO: Wildcards, this is just ugly
             for (const path of exclude) {
                 if (nodePath.endsWith(path.slice(1))) {
@@ -192,6 +247,14 @@ class Module {
         return files;
     }
     // Build Nodes
+    /**
+     * 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
+     */
     async buildNode(node, tree) {
         log_1.Log.trace('compiler', 'module', `Building ${this.name}::${(0, log_1.scopeTag)(node.builder.$b, node.builder.name)}`);
         if (node.builder.$b === 'constants') {
@@ -209,19 +272,19 @@ class Module {
         else if (node.builder.$b === 'job') {
             const { schema, inlineMessages } = job_builder_1.JobBuilder.build(node, tree, this.schema);
             this.schema.jobs[node.name] = schema;
-            this.mergeInlineMessages(node, inlineMessages);
+            this.mergeInlineMessages(inlineMessages);
         }
         else if (node.builder.$b === 'resource') {
             const { schema, inlineMessages, inlineJobs } = resource_builder_1.ResourceBuilder.build(node, tree, this.schema);
             this.schema.resources[schema.name] = schema;
-            this.mergeInlineMessages(node, inlineMessages);
-            this.mergeInlineJobs(node, inlineJobs);
+            this.mergeInlineMessages(inlineMessages);
+            this.mergeInlineJobs(inlineJobs);
         }
         else if (node.builder.$b === 'machine') {
             const { schema, inlineMessages, inlineJobs } = machine_builder_1.MachineBuilder.build(node, tree, this.schema);
             this.schema.machines[schema.name] = schema;
-            this.mergeInlineMessages(node, inlineMessages);
-            this.mergeInlineJobs(node, inlineJobs);
+            this.mergeInlineMessages(inlineMessages);
+            this.mergeInlineJobs(inlineJobs);
         }
         else if (node.builder.$b === 'controller') {
             this.schema.controllers[node.name] = controller_builder_1.ControllerBuilder.build(node);
@@ -229,31 +292,49 @@ class Module {
         else if (node.builder.$b === 'queue') {
             const { schema, inlineMessages } = queue_builder_1.QueueBuilder.build(node, tree, this.schema);
             this.schema.queues[node.name] = schema;
-            this.mergeInlineMessages(node, inlineMessages);
+            this.mergeInlineMessages(inlineMessages);
         }
         else {
             throw error_1.NesoiError.Module.UnknownBuilderType(this, node.filepath.toString(), node.name, node.builder.$b);
         }
     }
-    mergeInlineMessages(node, schemas) {
+    /**
+     * Merge inline message schemas into the module.
+     *
+     * @param node A resolved builder node
+     * @param schemas A dictionary of Message schemas by name
+     */
+    mergeInlineMessages(schemas) {
         for (const name in schemas) {
             const $msg = schemas[name];
             this.schema.messages[name] = $msg;
         }
     }
-    mergeInlineJobs(node, schemas) {
+    /**
+     * Merge inline job schemas into the module.
+     *
+     * @param node A resolved builder node
+     * @param schemas A dictionary of job schemas by name
+     */
+    mergeInlineJobs(schemas) {
         for (const name in schemas) {
             const $job = schemas[name];
             this.schema.jobs[name] = $job;
         }
     }
     // Start
-    start(app, providers) {
+    /**
+     * 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, services) {
         const info = app_1.App.getInfo(app);
         const config = info.config;
         Object.entries(this.schema.buckets).forEach(([name, schema]) => {
             const bucketConfig = config.buckets?.[this.name]?.[name];
-            this.buckets[name] = new bucket_1.Bucket(schema, bucketConfig, providers);
+            this.buckets[name] = new bucket_1.Bucket(schema, bucketConfig, services);
         });
         Object.entries(this.schema.messages).forEach(([name, schema]) => {
             this.messages[name] = new message_parser_1.MessageParser(schema);
@@ -269,7 +350,7 @@ class Module {
         });
         Object.entries(this.schema.controllers).forEach(([name, schema]) => {
             const controllerConfig = config.controllers?.[this.name]?.[name];
-            this.controllers[name] = new controller_1.Controller(this, schema, controllerConfig, providers);
+            this.controllers[name] = new controller_1.Controller(this, schema, controllerConfig, services);
         });
         Object.entries(this.schema.queues).forEach(([name, schema]) => {
             this.queues[name] = new queue_1.Queue(this, schema);
@@ -277,43 +358,58 @@ class Module {
         this.nql = new nql_engine_1.NQL_Engine(this);
     }
     // Destroy
+    /**
+     * Destroy all elements from module.
+     */
     destroy() {
         // Destroy messages
         for (const name in this.messages || []) {
-            this.destroyBlock('message', name);
+            this.destroyElement('message', name);
         }
         // Destroy buckets
         for (const name in this.buckets || {}) {
-            this.destroyBlock('bucket', name);
+            this.destroyElement('bucket', name);
         }
         // Destroy jobs
         for (const name in this.jobs || []) {
-            this.destroyBlock('job', name);
+            this.destroyElement('job', name);
         }
         // Destroy resources
         for (const name in this.resources || []) {
-            this.destroyBlock('resource', name);
+            this.destroyElement('resource', name);
         }
         // Destroy machines
         for (const name in this.machines || []) {
-            this.destroyBlock('machine', name);
+            this.destroyElement('machine', name);
         }
         // Destroy queues
         for (const name in this.queues || []) {
-            this.destroyBlock('queue', name);
+            this.destroyElement('queue', name);
         }
         // Destroy controllers
         for (const name in this.controllers || []) {
-            this.destroyBlock('controller', name);
+            this.destroyElement('controller', name);
         }
     }
-    async destroyBlock(type, name) {
+    /**
+     * Destroy one element from module.
+     */
+    async destroyElement(type, name) {
         const t = type + 's';
         log_1.Log.info('module', this.name, 'Destroying');
         delete this.schema[t][name];
         delete this[t][name];
     }
     // Virtual
+    /**
+     * 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 async virtual(daemon, def) {
         const virtualModule = new Module(def.name, { builders: [] });
         // Inject schemas
@@ -324,7 +420,11 @@ class Module {
         await virtualModule.start({ config: {} }, {});
         // Inject externals
         if (def.externals) {
-            virtualModule.injectDependencies(daemon, def.externals);
+            const modules = {};
+            daemon_1.Daemon.getModules(daemon).forEach(module => {
+                modules[module.name] = module;
+            });
+            virtualModule.injectDependencies(modules, def.externals);
         }
         return virtualModule;
     }

package/lib/engine/space.d.ts

@@ -1,7 +1,7 @@
 import { $Module, $Space } from "../schema";
 import { MachineBuilder } from "../elements/blocks/machine/machine.builder";
 import { ConstantsBuilder } from "../elements/entities/constants/constants.builder";
-import { ExternalsBuilder } from "../elements/blocks/externals/externals.builder";
+import { ExternalsBuilder } from "../elements/edge/externals/externals.builder";
 import { JobBuilder } from "../elements/blocks/job/job.builder";
 import { MessageBuilder } from "../elements/entities/message/message.builder";
 import { ResourceBuilder } from "../elements/blocks/resource/resource.builder";
@@ -9,47 +9,200 @@ import { ControllerBuilder } from "../elements/edge/controller/controller.builde
 import { BucketBuilder } from "../elements/entities/bucket/bucket.builder";
 import { $Message } from "../elements/entities/message/message.schema";
 import { BucketModelDef } from "../elements/entities/bucket/model/bucket_model.builder";
-import { BucketModelInfer } from "../elements/entities/bucket/model/bucket_model.infer";
 import { QueueBuilder } from "../elements/blocks/queue/queue.builder";
 import { $Bucket, $Job, $Resource } from "../elements";
+/**
+ * When using Nesoi as a framework (not a library), the `Space`
+ * is a collection of all modules.
+ * The name comes from the linear algebra notion of 'vector space'.
+ * It's the 'module space', where all past and future modules exist.
+ *
+ * The `Space` is mainly used to:
+ * - Declare builders which reference the compiled schemas with a minimal syntax
+ * - Read modules from the directory structure to compile schemas and apps
+ *
+ * @category Engine
+ */
 export declare class Space<$ extends $Space> {
-    private dirname;
+    private dirpath;
     private _authn;
     private _name;
-    constructor(dirname: string);
     /**
-     * Space Settings
-     * - Name
-     * - Authentication
+     * @param dirpath The path for the Space root directory
+     */
+    constructor(dirpath: string);
+    /**
+     * Set a custom Space name. The default is 'Space'.
+     * > This method MUST be called on the root `nesoi.ts` file.
+     * @param name A new Space name
+     * @returns The current Space, for call-chaining
      */
     name(name: string): this;
-    authn<Name extends string, Def extends BucketModelDef<$, never>, Obj = BucketModelInfer<Def>>(name: Name, $: Def): this;
-    externals<M extends keyof $['modules']>(module: M): ExternalsBuilder<$, M>;
+    /**
+     * Set one authentication model.
+     * This model MUST be yielded by the `AuthnProvider` assigned
+     * to the same name.
+     * > This method MUST be called on the root `nesoi.ts` file.
+     * @param name A name for the authentication
+     * @returns The current Space, for call-chaining
+     */
+    authn<Name extends string, Def extends BucketModelDef<$, never>>(name: Name, $: Def): this;
+    /**
+     * > Elements / Entities / Constants
+     *
+     * `Constants` represent statically-known data, namely `values` and `enums`,
+     * which can be referenced from any `Module`.
+     *
+     * @param module A module name
+     * @returns A `Constants` builder
+     */
     constants<M extends keyof $['modules']>(module: M): ConstantsBuilder;
+    /**
+     * > Elements / Entities / Bucket
+     *
+     * A `Bucket` represents stored data, on any kind of storage.
+     * It contains a definition of the type of data (_model_),
+     * the relations between this data and other (_graph_),
+     * and different ways to present this data (_view_).
+     *
+     * The actual storage is linked through a `BucketAdapter`, on the
+     * `App` definition. Which means you build a _Bucket_ without
+     * knowing how it's data will be stored, and then later plug
+     * any adapter (like Memory, or PostgreSQL, etc) into it.
+     *
+     * @param globalName A _Bucket_ name in the format `module::name`
+     * @returns A `Bucket` builder
+     */
     bucket<M extends keyof $['modules'], K extends string, Module extends $Module = $['modules'][M]>(globalName: `${M & string}::${K}`): BucketBuilder<$, Module, $Bucket & {
         name: K;
     }>;
+    /**
+     * > Elements / Entities / Message
+     *
+     * A `Message` represents data in transit (generally incoming).
+     * It contains a definition of the data format (_template_),
+     * which includes possibly complex validation rules.
+     *
+     * This _template_ is used to _parse_ an object into the message format,
+     * so a _Message_ has two states: `raw` and `parsed`.
+     * - `raw`: A JS object containing a `$` with the message name plus some other properties
+     * - `parsed`: A `Message` object containing the parsed data plus some metadata (signature, etc)
+     *
+     * @param globalName A message name in the format `module::name`
+     * @returns A `Constants` builder
+     */
     message<M extends keyof $['modules'], K extends string, Module extends $Module = $['modules'][M]>(globalName: `${M & string}::${K}`): MessageBuilder<$, Module, $Message & {
         name: K;
     }>;
+    /**
+     * > Elements / Blocks / Job
+     *
+     * A `Job` is a method which accepts one or more _Messages_ as input.
+     *
+     * It might declare _extra_ data to include on the job input, and
+     * conditions which must be met before the method is executed.
+     * These can be pre-validate a Job before queuing it, or for
+     * organizing the job flow in a more declarative way.
+     *
+     * This method has access to all elements within it's module.
+     *
+     * @param globalName A _Job_ name in the format `module::name`
+     * @returns A `Job` builder
+     */
     job<M extends keyof $['modules'], K extends string, Module extends $Module = $['modules'][M]>(globalName: `${M & string}::${K}`): JobBuilder<$, Module, $Job & {
         name: K;
     }, {}>;
+    /**
+     * > Elements / Blocks / Resource
+     *
+     * A `Resource` is a fast way to declare simple CRUD _Jobs_ and _Messages_ for a `Bucket`.
+     *
+     * It offers 5 types of jobs:
+     * - `view`: Read one or all bucket object(s) through a specific view
+     * - `query`: Query bucket object(s)
+     * - `create`: Create one object on the bucket
+     * - `update`: Modify (patch) one object of the bucket
+     * - `delete`: Delete one object of the bucket
+     *
+     * @param globalName A _Resource_ name in the format `module::name`
+     * @returns A `Resource` builder
+     */
     resource<M extends keyof $['modules'], K extends string, Module extends $Module = $['modules'][M]>(globalName: `${M & string}::${K}`): ResourceBuilder<$, Module, $Resource & {
         name: K;
     }>;
+    /**
+     * > Elements / Blocks / Machine
+     *
+     * A `Machine` is a _Statechart_ which reads it's context from a _Bucket_,
+     * and uses a specific property to store a discrete state.
+     * When this machine receives _Messages_, it follows the definition to possibly
+     * advance the state and run _Jobs_.
+     *
+     * @param globalName A _Machine_ name in the format `module::name`
+     * @returns A `Machine` builder
+     */
     machine<M extends keyof $['modules'], K extends string, Module extends $Module = $['modules'][M]>(globalName: `${M & string}::${K}`): MachineBuilder<$, Module, K, Module["machines"][K] & {
         name: K;
     }>;
-    controller<M extends keyof $['modules'], K extends string, Module extends $Module = $['modules'][M]>(globalName: `${M & string}::${K}`): ControllerBuilder<$, Module>;
+    /**
+     * > Elements / Blocks / Queue
+     *
+     * A `Queue` stores _Messages_ to be consumed later in order.
+     *
+     * @param globalName A _Queue_ name in the format `module::name`
+     * @returns A `Queue` builder
+     */
     queue<M extends keyof $['modules'], K extends string, Module extends $Module = $['modules'][M]>(globalName: `${M & string}::${K}`): QueueBuilder<$, Module, Module["queues"][K] & {
         name: K;
     }>;
     /**
+     * > Elements / Edge / Externals
+     *
+     * `Externals` references elements from other modules, allowing
+     * them to be used by Jobs and other elements from this module.
+     *
+     * @param module A module name
+     * @returns A `Externals` builder
+     */
+    externals<M extends keyof $['modules']>(module: M): ExternalsBuilder<$, M>;
+    /**
+     * > Elements / Edge / Controller
+     *
+     * A `Controller` allows an external application to send
+     * and receive messages /from the Nesoi Engine.
+     *
+     * The controller declares endpoints which accept specific messages
+     * and route them to specific elements.
+     * On the `App`, each controller is assigned a `ControllerAdapter`, which
+     * is responsible for creating the raw _Messages_ and sending them to the Engine.
+     *
+     * @param globalName A _Controller_ name in the format `module::name`
+     * @returns A `Controller` builder
+     */
+    controller<M extends keyof $['modules'], K extends string, Module extends $Module = $['modules'][M]>(globalName: `${M & string}::${K}`): ControllerBuilder<$, Module>;
+    /**
+     * Resolve a path relative to the Space root.
      *
+     * @param space A `Space` instance
+     * @param relPath One or many path terms
+     * @returns A resolved path
      */
     static path(space: Space<any>, ...relPath: string[]): string;
+    /**
+     * Return a path relative to the Space root given an absolute path.
+     *
+     * @param space A `Space` instance
+     * @param relPath One or many path terms
+     * @returns A resolved path
+     */
     static relPath(space: Space<any>, absPath: string): string;
+    /**
+     * Read all module directories from the Space root, then
+     * run a callback for each.
+     *
+     * @param space A `Space` instance
+     * @param buildFn A callback to run for each module directory
+     */
     static scan(space: Space<any>, buildFn: (name: string, path: string) => void): void;
 }
 export type AnySpace = Space<$Space>;