nesoi 3.0.6 → 3.0.9

package/lib/engine/space.js

@@ -39,7 +39,7 @@ const path = __importStar(require("path"));
 // import { MachineBuilder } from "~/plugins/machine";
 const machine_builder_1 = require("../elements/blocks/machine/machine.builder");
 const constants_builder_1 = require("../elements/entities/constants/constants.builder");
-const externals_builder_1 = require("../elements/blocks/externals/externals.builder");
+const externals_builder_1 = require("../elements/edge/externals/externals.builder");
 const job_builder_1 = require("../elements/blocks/job/job.builder");
 const message_builder_1 = require("../elements/entities/message/message.builder");
 const resource_builder_1 = require("../elements/blocks/resource/resource.builder");
@@ -49,21 +49,48 @@ const bucket_model_builder_1 = require("../elements/entities/bucket/model/bucket
 const bucket_model_field_builder_1 = require("../elements/entities/bucket/model/bucket_model_field.builder");
 const error_1 = require("../compiler/error");
 const queue_builder_1 = require("../elements/blocks/queue/queue.builder");
+/**
+ * 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
+ */
 class Space {
-    constructor(dirname) {
-        this.dirname = dirname;
+    /**
+     * @param dirpath The path for the Space root directory
+     */
+    constructor(dirpath) {
+        this.dirpath = dirpath;
         this._authn = {};
-        this._name = 'App';
+        this._name = 'Space';
     }
+    /*
+     *  ROOT
+     */
     /**
-     * Space Settings
-     * - Name
-     * - Authentication
+     * 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) {
         this._name = name;
         return this;
     }
+    /**
+     * 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, $) {
         const fieldBuilder = new bucket_model_field_builder_1.BucketModelFieldFactory('*');
         const fields = $(fieldBuilder);
@@ -71,64 +98,199 @@ class Space {
         this._authn[name] = bucket_model_builder_1.BucketModelBuilder.build(builder);
         return this;
     }
-    // Statics
-    externals(module) {
-        return new externals_builder_1.ExternalsBuilder(module);
-    }
+    /*
+     *  ELEMENTS
+     */
+    // Entities
+    /**
+     * > 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(module) {
         return new constants_builder_1.ConstantsBuilder(module);
     }
-    // Entities
+    /**
+     * > 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(globalName) {
         const [module, name] = globalName.split('::');
         // TODO: review why this was not "$Bucket & {...}"
         // type Bucket = Module['buckets'][K] & { name: K }
         return new bucket_builder_1.BucketBuilder(module, name);
     }
+    /**
+     * > 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(globalName) {
         const [module, name] = globalName.split('::');
         return new message_builder_1.MessageBuilder(module, name);
     }
     // Blocks
+    /**
+     * > 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(globalName) {
         const [module, name] = globalName.split('::');
         return new job_builder_1.JobBuilder(module, name);
     }
+    /**
+     * > 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(globalName) {
         const [module, name] = globalName.split('::');
         return new resource_builder_1.ResourceBuilder(module, name);
     }
+    /**
+     * > 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(globalName) {
         const [module, name] = globalName.split('::');
         return new machine_builder_1.MachineBuilder(module, name);
     }
+    /**
+     * > 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(globalName) {
+        const [module, name] = globalName.split('::');
+        return new queue_builder_1.QueueBuilder(module, name);
+    }
     // Edge
+    /**
+     * > 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(module) {
+        return new externals_builder_1.ExternalsBuilder(module);
+    }
+    /**
+     * > 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(globalName) {
         const [module, name] = globalName.split('::');
         return new controller_builder_1.ControllerBuilder(module, name);
     }
-    queue(globalName) {
-        const [module, name] = globalName.split('::');
-        return new queue_builder_1.QueueBuilder(module, name);
-    }
+    /*
+     *  RUN / COMPILE
+     */
     /**
+     * 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, ...relPath) {
-        if (!space.dirname) {
+        if (!space.dirpath) {
             throw new Error('Cant use .path() on virtual space');
         }
-        return path.resolve(space.dirname, ...relPath);
+        return path.resolve(space.dirpath, ...relPath);
     }
+    /**
+     * 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, absPath) {
-        if (!space.dirname) {
+        if (!space.dirpath) {
             throw new Error('Cant use .path() on virtual space');
         }
-        return path.relative(space.dirname, absPath);
+        return path.relative(space.dirpath, absPath);
     }
+    /**
+     * 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, buildFn) {
-        if (!fs.existsSync(space.dirname)) {
-            throw error_1.CompilerError.DirectoryDoesntExists(space.dirname);
+        if (!fs.existsSync(space.dirpath)) {
+            throw error_1.CompilerError.DirectoryDoesntExists(space.dirpath);
         }
         const modulesPath = this.path(space, './modules');
         if (!fs.existsSync(modulesPath)) {

package/lib/engine/transaction/nodes/bucket.trx_node.d.ts

@@ -6,6 +6,10 @@ import { Bucket } from "../../../elements/entities/bucket/bucket";
 import { CreateObj, PatchObj, PutObj } from "../../../elements/entities/bucket/bucket.types";
 import { NQL_Query } from "../../../elements/entities/bucket/query/nql.schema";
 import { NesoiFile } from "../../data/file";
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 export declare class BucketTrxNode<M extends $Module, $ extends $Bucket> {
     private parentTrx;
     private bucket;
@@ -147,6 +151,10 @@ export declare class BucketTrxNode<M extends $Module, $ extends $Bucket> {
      */
     get unsafe(): BucketUnsafeTrxNode<M, $>;
 }
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 export declare class BucketUnsafeTrxNode<M extends $Module, $ extends $Bucket> {
     private bucketTrx;
     private bucket;
@@ -188,6 +196,10 @@ export declare class BucketUnsafeTrxNode<M extends $Module, $ extends $Bucket> {
      */
     deleteMany(ids: $['#data']['id'][]): Promise<void>;
 }
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 export declare class BucketDriveTrxNode<M extends $Module, $ extends $Bucket> {
     private bucketTrx;
     private bucket;

package/lib/engine/transaction/nodes/bucket.trx_node.js

@@ -4,6 +4,10 @@ exports.BucketDriveTrxNode = exports.BucketUnsafeTrxNode = exports.BucketTrxNode
 const trx_node_1 = require("../trx_node");
 const bucket_query_trx_node_1 = require("./bucket_query.trx_node");
 const error_1 = require("../../data/error");
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 class BucketTrxNode {
     constructor(parentTrx, bucket) {
         this.parentTrx = parentTrx;
@@ -283,6 +287,10 @@ class BucketTrxNode {
     }
 }
 exports.BucketTrxNode = BucketTrxNode;
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 class BucketUnsafeTrxNode {
     constructor(bucketTrx, bucket, enableTenancy) {
         this.bucketTrx = bucketTrx;
@@ -360,6 +368,10 @@ class BucketUnsafeTrxNode {
     }
 }
 exports.BucketUnsafeTrxNode = BucketUnsafeTrxNode;
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 class BucketDriveTrxNode {
     constructor(bucketTrx, bucket) {
         this.bucketTrx = bucketTrx;

package/lib/engine/transaction/nodes/bucket_query.trx_node.d.ts

@@ -4,6 +4,10 @@ import { $Bucket } from "../../../elements/entities/bucket/bucket.schema";
 import { Bucket } from "../../../elements/entities/bucket/bucket";
 import { NQL_AnyQuery, NQL_Pagination, NQL_Query } from "../../../elements/entities/bucket/query/nql.schema";
 import { NQL_Result } from "../../../elements/entities/bucket/query/nql_engine";
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 export declare class BucketQueryTrxNode<M extends $Module, B extends $Bucket, V extends ViewName<B>, Obj = ViewObj<B, V>> {
     private trx;
     private bucket;

package/lib/engine/transaction/nodes/bucket_query.trx_node.js

@@ -3,6 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BucketQueryTrxNode = void 0;
 const trx_node_1 = require("../trx_node");
 const error_1 = require("../../data/error");
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 class BucketQueryTrxNode {
     constructor(trx, bucket, query, view, enableTenancy) {
         this.trx = trx;

package/lib/engine/transaction/nodes/job.trx_node.d.ts

@@ -4,6 +4,10 @@ import { $Job } from "../../../elements/blocks/job/job.schema";
 import { Job } from "../../../elements/blocks/job/job";
 import { Message } from "../../../elements/entities/message/message";
 import { JobInput } from "../../../elements/blocks/job/job.types";
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 export declare class JobTrxNode<M extends $Module, $ extends $Job> {
     private trx;
     private job;

package/lib/engine/transaction/nodes/job.trx_node.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JobTrxNode = void 0;
 const trx_node_1 = require("../trx_node");
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 class JobTrxNode {
     constructor(trx, job, ctx) {
         this.trx = trx;

package/lib/engine/transaction/nodes/machine.trx_node.d.ts

@@ -3,6 +3,10 @@ import { TrxNode } from '../trx_node';
 import { $Machine } from "../../../elements/blocks/machine/machine.schema";
 import { Machine, MachineOutput } from "../../../elements/blocks/machine/machine";
 import { Message } from "../../../elements/entities/message/message";
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 export declare class MachineTrxNode<M extends $Module, $ extends $Machine> {
     private trx;
     private machine;

package/lib/engine/transaction/nodes/machine.trx_node.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MachineTrxNode = void 0;
 const trx_node_1 = require("../trx_node");
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 class MachineTrxNode {
     constructor(trx, machine) {
         this.trx = trx;

package/lib/engine/transaction/nodes/queue.trx_node.d.ts

@@ -2,6 +2,10 @@ import { $Module, RawMessageInput } from "../../../schema";
 import { TrxNode } from '../trx_node';
 import { $Queue } from "../../../elements/blocks/queue/queue.schema";
 import { Queue } from "../../../elements/blocks/queue/queue";
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 export declare class QueueTrxNode<M extends $Module, $ extends $Queue> {
     private trx;
     private queue;

package/lib/engine/transaction/nodes/queue.trx_node.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueueTrxNode = void 0;
 const trx_node_1 = require("../trx_node");
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 class QueueTrxNode {
     constructor(trx, queue) {
         this.trx = trx;

package/lib/engine/transaction/nodes/resource.trx_node.d.ts

@@ -8,6 +8,10 @@ type QueryRaw<$ extends $Resource> = $['#input.query']['#raw'];
 type CreateRaw<$ extends $Resource> = $['#input.create']['#raw'];
 type UpdateRaw<$ extends $Resource> = $['#input.update']['#raw'];
 type DeleteRaw<$ extends $Resource> = $['#input.delete']['#raw'];
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 export declare class ResourceTrxNode<M extends $Module, $ extends $Resource> {
     private trx;
     private resource;

package/lib/engine/transaction/nodes/resource.trx_node.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ResourceTrxNode = void 0;
 const trx_node_1 = require("../trx_node");
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 class ResourceTrxNode {
     constructor(trx, resource) {
         this.trx = trx;

package/lib/engine/transaction/trx.d.ts

@@ -6,6 +6,10 @@ import { AnyUsers, AuthnRequest } from '../auth/authn';
 import { NesoiDatetime } from '../data/datetime';
 type TrxOrigin = TrxEngineOrigin | `trx:${string}`;
 type TrxState = 'open' | 'ok' | 'error';
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 export declare class TrxStatus<Output> {
     id: string;
     origin: TrxOrigin;
@@ -18,6 +22,10 @@ export declare class TrxStatus<Output> {
     constructor(id: string, origin: TrxOrigin, start: NesoiDatetime, end?: NesoiDatetime | undefined, state?: TrxState | undefined, output?: Output | undefined, error?: string | undefined, nodes?: TrxNodeStatus[]);
     summary(): string;
 }
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 export declare class Trx<S extends $Space, M extends $Module, Authn extends AnyUsers> {
     private module;
     id: string;

package/lib/engine/transaction/trx.js

@@ -8,6 +8,10 @@ const datetime_1 = require("../data/datetime");
 /*
     Transaction Status
 */
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 class TrxStatus {
     constructor(id, origin, start, end, state, output, error, nodes = []) {
         this.id = id;
@@ -45,6 +49,10 @@ class TrxStatus {
     }
 }
 exports.TrxStatus = TrxStatus;
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 class Trx {
     constructor(module, origin, authn, id, root, nodes) {
         this.start = datetime_1.NesoiDatetime.now();

package/lib/engine/transaction/trx_engine.d.ts

@@ -5,6 +5,10 @@ import { TrxNode, TrxNodeStatus } from './trx_node';
 import { AnyAuthnProviders, AuthnRequest } from '../auth/authn';
 import { TrxEngineConfig } from './trx_engine.config';
 export type TrxEngineOrigin = `app:${string}`;
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 export declare class TrxEngine<S extends $Space, M extends $Module, Authn extends AnyAuthnProviders> {
     private origin;
     private module;

package/lib/engine/transaction/trx_engine.js

@@ -6,9 +6,10 @@ const trx_1 = require("./trx");
 const trx_node_1 = require("./trx_node");
 const error_1 = require("../data/error");
 const memory_bucket_adapter_1 = require("../../elements/entities/bucket/adapters/memory.bucket_adapter");
-/*
-    Transaction Engine
-*/
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 class TrxEngine {
     constructor(origin, module, authnProviders, config, providers = {}) {
         this.origin = origin;

package/lib/engine/transaction/trx_node.d.ts

@@ -22,6 +22,10 @@ export type TrxNodeStatus = {
     nodes: TrxNodeStatus[];
     app: number;
 };
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 export declare class TrxNode<Space extends $Space, M extends $Module, Authn extends AnyUsers> {
     private scope;
     private trx;

package/lib/engine/transaction/trx_node.js

@@ -15,6 +15,10 @@ const datetime_1 = require("../data/datetime");
 /*
     Transaction Node
 */
+/**
+ * @category Engine
+ * @subcategory Transaction
+ */
 class TrxNode {
     constructor(scope, trx, parent, module, authn, id) {
         this.scope = scope;

package/lib/engine/tree.d.ts

@@ -3,32 +3,84 @@ import { ResolvedBuilderNode } from './dependency';
 import { AnyModule } from './module';
 import { TreeshakeConfig } from "../compiler/treeshake";
 type TraverseCallback = (node: ResolvedBuilderNode) => Promise<void>;
+/**
+ * A tree of module elements which allows building in the correct order.
+ *
+ * @category Engine
+ */
 export declare class ModuleTree {
     modules: Record<string, AnyModule>;
     config?: TreeshakeConfig | undefined;
     private layers;
+    /**
+     * @param modules A dictionary of modules by name
+     * @param config Optional configuration for the treeshaking process
+     */
     constructor(modules: Record<string, AnyModule>, config?: TreeshakeConfig | undefined);
+    /**
+     * Build the tree from existing modules on the Space.
+     * - Treeshakes each element to identify it's dependencies
+     * - Resolves each found dependency forming a tree
+     * - Groups tree into layers which can be built in isolation
+     */
     resolve(): Promise<void>;
+    /**
+     * Read the module elements from files and identify
+     * all related nodes.
+     *
+     * @returns A dictionary of nodes by module name
+     */
     private treeshake;
     /**
-     * Each node declares it's dependencies as a `$Dependency`.
+     * Each element declares it's dependencies as a `$Dependency`.
      * In order to assemble the build layers, it's necessary to
      * resolve them into a graph of `ResolvedBuilderNode`s.
      * This also resolves the inline nodes, to allow merging the schemas
      * of inline nodes on build.
+     *
+     * @param nodesByModule A dictionary of builder nodes by module name
+     * @returns A dictionary of resolved builder nodes
      */
     private resolveDependencies;
+    /**
+     * Recursively extract all inline nodes from a resolved builder node.
+     *
+     * @param node A resolved builder node
+     * @returns A list of resolved builder nodes
+     */
     private getAllInlineNodes;
     /**
-     * In order to build nodes on the proper order, a set of layers must be stablished
+     * Build a list of layers (a _layer_ is a list of resolved builder nodes),
+     * each of which can be separately built, in a specific order, so all
+     * the dependencies of a node are built before the node itself.
+     *
+     * @param nodes A list of resolved builder nodes
+     * @returns A list of module tree layers
      */
     private resolveLayers;
+    /**
+     * Traverse tree layers and run the callback `fn` for each node of each layer.
+     *
+     * @param actionAlias Action alias to be logged
+     * @param fn Callback to be run for each node
+     */
     traverse(actionAlias: string, fn: TraverseCallback): Promise<void>;
+    /**
+     * Get schema of a dependency-like object.
+     *
+     * @param node A dependency-like object
+     * @return An element schema
+     */
     getSchema(node: {
         module: string;
         type: BuilderType;
         name: string;
     }): import("../elements").$Message | import("../elements").$Machine | import("../elements").$Bucket | import("../elements").$Constants | import("../elements").$Job | import("../elements").$Externals | import("../elements").$Resource | import("../elements").$Controller;
+    /**
+     * Return a list of all nodes of all modules on the tree.
+     *
+     * @returns A list of resolved builder nodes
+     */
     allNodes(): ResolvedBuilderNode[];
 }
 export {};