@avtechno/sfr 1.0.0

package/src/types/index.d.ts

@@ -0,0 +1,395 @@
+/// <reference types="typescript" />
+
+
+
+declare type ServiceTypes = ("core" | "application" | "adapter" | "ai-agent");
+
+declare type Multer = import("multer").Multer;
+
+declare type OAPI_Document = import("openapi-types").OpenAPIV3_1.Document;
+declare type InfoObject = import("openapi-types").OpenAPIV3_1.InfoObject;
+declare type Express = import("express").Express;
+declare type Server = import("socket.io").Server;
+declare type NextFunction = import("express").NextFunction;
+declare type RequestHandler = import("express").RequestHandler;
+declare type ExpressRequest = import("express").Request;
+declare type ExpressResponse = import("express").Response;
+declare type ChannelModel = import("amqplib").Channel;
+declare type Socket = import("socket.io").Socket;
+
+declare type BroadcastMQ = import("../mq.mts").BroadcastMQ;
+declare type TargetedMQ = import("../mq.mts").TargetedMQ;
+
+declare enum PROTOCOLS {
+  REST = "REST",
+  WS = "WS",
+  MQ = "MQ"
+}
+
+
+declare type RESTHandlerDescriptor<V, H, C> = {
+  meta?: SFRMetadata;
+  cfg?: SFRConfig;
+  validators: RequestValidators & V;
+  handlers: RESTRequestHandlers & H & ThisType<HandlerFacilities & C>;
+  controllers?: RequestControllers & C & ThisType<ControllerFacilities>;
+};
+
+declare type WSHandlerDescriptor<V, H, C> = {
+  cfg?: SFRConfig;
+  validators: RequestValidators & V;
+  handlers: WSRequestHandlers & H & ThisType<HandlerFacilities & C>;
+  controllers?: RequestControllers & C & ThisType<ControllerFacilities & C>;
+};
+
+declare interface HandlerFacilities { }
+
+declare interface ControllerFacilities { }
+
+declare type InjectedFacilities = {
+  handlers?: HandlerFacilities;
+  controllers?: ControllerFacilities;
+}
+
+/**
+ * Main Configuration object used by the bundler to apply for a given API Declaration
+ *
+ *
+ */
+declare type SFRConfig = {
+  /**
+     * Configuration used to explicitly set the API Declaration's root directory upon binding.
+  
+     * **Example**
+     * ```
+     * //The given REST Declaration will be bound to
+     * //"/space/*" instead of /*
+     *
+     * REST({
+     *  cfg : {
+     *    base_dir : "space"
+     *  },
+     *
+     *  validators : {
+     *  },
+     *
+     *  handlers : {
+     *  }
+     * })
+     * ```
+     */
+  base_dir?: string;
+  /**
+   * Directive used to evaluate an API Declaration's public accessibility.
+   *
+   * setting this to **true (false by default)** will cause the heading middleware to skip certain checks, namely the ff.
+   *
+   * * Session Validity
+   * * Access Authorization
+   */
+  public?: boolean;
+};
+
+declare type OASConfig = Omit<ServiceManifest, "documents"> & InfoObject
+
+/**
+ * UAC Policy Type Definitions
+ * 
+ * @author Emmanuel Abellana
+ * @description Type definitions for service-manifest, the main interchange document for service-coupling functions.
+ */
+declare type ServiceManifest = {
+  title: string;
+  description: string;
+  tags?: string[];
+  meta: {
+    //Specifies the domain of the service
+    domain: string;
+    service: string;
+    /**
+     * Specifies the type of service
+     * 
+     * **core** - Specialized services, meant to be used by other types of services.
+     * 
+     * **application** - Standard 1st party services.
+     * 
+     * **adapter** - Services meant to couple with 3rd party services.
+     * 
+     * **ai-agent** - AI-enabled service-agent.
+     */
+    //"x-service-type": ServiceTypes
+
+    /**
+     * Specifies the port of the service
+     */
+    port: number;
+
+    /**
+     * Optional: Specifies the framework used by the service
+     */
+    framework?: string[];
+
+    /**
+     * Optional: Specifies the language used by the service
+     */
+    language: string;
+
+    /**
+     * Optional: Specifies the type of the service
+     */
+    type: ("backend" | "frontend");
+  };
+  documents: ServiceDocuments
+}
+declare type ServiceDocuments = {
+  REST?: OAPI_Document;
+  MQ?: AsyncAPIDocument;
+  WS?: AsyncAPIDocument;
+}
+
+declare type RequestValidators = {
+  [name: string]: object | RequestHandler;
+};
+declare type RequestControllers = {
+  [name: string]: RequestController;
+};
+declare type RequestController = (...args: any[]) => Promise<any>;
+declare type RESTRequestHandlers = {
+  GET?: RESTHandlerMap;
+  POST?: RESTHandlerMap;
+  PUT?: RESTHandlerMap;
+  PATCH?: RESTHandlerMap;
+  DELETE?: RESTHandlerMap;
+  COPY?: RESTHandlerMap;
+  HEAD?: RESTHandlerMap;
+  OPTIONS?: RESTHandlerMap;
+  PROPFIND?: RESTHandlerMap;
+};
+/**
+ * Mapping of endpoints and their respective metadata according to OpenAPI standards
+ *
+ * Note: Some fields are automatically inferred from the SFR build phase and as such, only a subset of the official parameters are exposed.
+ *
+ * Link: https://spec.openapis.org/oas/v3.1.0#operation-object
+ */
+declare type SFRMetadata = {
+  tags?: string[];
+  summary?: string;
+  description?: string;
+  deprecated?: boolean;
+};
+declare type RESTRequestType =
+  "get" |
+  "post" |
+  "put" |
+  "patch" |
+  "delete" |
+  "copy" |
+  "head" |
+  "options" |
+  "propfind";
+declare type RESTHandlerMap = {
+  [key: string]: SFRMetadata & {
+    fn: CustomRequestHandler
+  }
+};
+type CustomRequestHandler= (
+  req: ExpressRequest,
+  res: ExpressResponse,
+  next: NextFunction
+) => any;
+declare type WSRequestHandler = (
+  ctx: WSRequestCtx,
+  args?: object
+) => Promise<object>;
+declare type WSRequestHandlers = {
+  [event: string]: WSRequestHandler;
+};
+declare type WSRequestCtx = {
+  io: Server;
+  socket: Socket;
+  args: string[];
+};
+declare type RequestResponse =
+  | {
+    error: object;
+  }
+  | {
+    data: object;
+  };
+declare type RESTNamespaceDeclaration = {
+  [namespace: string]: DeclarationArtifact & {
+    content: {
+      handlers: RESTRequestHandlers
+    }
+  }
+};
+declare type WSNamespaceDeclaration = {
+  [namespace: string]: DeclarationArtifact & {
+    content: {
+      handlers: WSRequestHandlers
+    }
+  }
+};
+declare type MQNamespaceDeclaration = {
+  [namespace: string]: DeclarationArtifact & {
+    content: {
+      handlers: MQRequestHandlers<any>
+    }
+  }
+}
+declare type DeclarationArtifact = {
+  name: string;
+  path: string;
+  desc?: string;
+  dir?: string[];
+  content: {
+    cfg: SFRConfig;
+    validators: RequestValidators;
+    controllers: RequestControllers;
+  }
+}
+
+declare type NamespaceDeclaration = {
+  REST: RESTNamespaceDeclaration;
+  WS: WSNamespaceDeclaration;
+  MQ: MQNamespaceDeclaration;
+}
+declare type SFRProtocols = {
+  REST?: Express;
+  WS?: Server;
+  MQ?: Connection;
+}
+
+declare type Operation = "Read" | "Write";
+declare type Protocol = "REST" | "WS";
+declare type LogFragment = {
+  domain: string;
+  user_id: string;
+  stamp: number;
+  host: string;
+  type: "in" | "out" | "req";
+};
+
+declare type ParserCFG = {
+  root: string; //Root directory of the project's source files.
+  path: string; //Directory of SFRs.
+  out?: string; //Directory for the oas output documents.
+};
+
+declare type Channel = import("amqplib").Channel;
+declare type Connection = import("amqplib").Connection;
+declare type ConsumeMessage = import("amqplib").ConsumeMessage;
+declare type ConsumeOptions = import("amqplib").Options.Consume;
+
+declare type ConsumerConfig = {
+  options?: ConsumeOptions;
+  fn: ((msg: ConsumeMessage) => void);
+} & ThisType<ConsumerContext>;
+declare type ConsumerContext = {
+  name: string;
+  type: string;
+  channel: Channel;
+}
+
+
+/* Commons */
+type CommunicationPattern = (
+  "Point-to-Point" |
+  "Publish-Subscribe" |
+  "Request-Reply" |
+  "Routing" |
+  "Topic"
+  /* "Scatter-Gather" */
+)
+
+declare type PatternMQSet = {
+  "Point-to-Point": TargetedMQ;
+  "Publish-Subscribe": BroadcastMQ;
+  "Request-Reply": TargetedMQ;
+  "Routing": TargetedMQ;
+  "Topic": TargetedMQ;
+}
+
+declare type MQHandlerDescriptor<V, H, C> = {
+  cfg?: SFRConfig;
+  validators: RequestValidators & V;
+  handlers: MQRequestHandlers<C> & H & ThisType<HandlerFacilities & C>;
+  controllers?: RequestControllers & C & ThisType<ControllerFacilities & C>;
+};
+
+declare type MQRequestHandlers<C> = {
+  "Point-to-Point"?: MQRequestHandlerMap & ThisType<{ mq: Omit<TargetedMQ, "type" | "reply"> } & C>;
+  "Publish-Subscribe"?: MQRequestHandlerMap & ThisType<{ mq: Omit<BroadcastMQ, "type"> } & C>;
+  "Request-Reply"?: MQRequestHandlerMap & ThisType<{ mq: Omit<TargetedMQ, "type"> } & C>;
+  "Routing"?: RoutingHandlerMap & ThisType<{ mq: Omit<BroadcastMQ, "type"> } & C>;
+  "Topic"?: TopicHandlerMap & ThisType<{ mq: Omit<BroadcastMQ, "type"> } & C>;
+};
+
+declare type MQRequestHandlerMap = {
+  [name: string]: SFRMetadata & MQConsumeOptions;
+}
+
+declare type RoutingHandlerMap = {
+  [name: string]: SFRMetadata & RoutingOptions;
+}
+
+declare type TopicHandlerMap = {
+  [name: string]: SFRMetadata & TopicOptions;
+}
+
+declare type MQConsumeOptions = {
+  options?: ConsumeOptions;
+  queue?: string[];
+  fn: MQRequestHandler;
+}
+
+declare type RoutingOptions = MQConsumeOptions & {
+  routing_key: string;
+}
+
+declare type TopicOptions = MQConsumeOptions & {
+  binding_key: string;
+}
+
+
+declare type MQRequestHandler = (msg: (ConsumeMessage & { content: any }) | null) => void;
+
+
+declare type MQRequestCtx = {
+  channel: Channel;
+  connection: Connection;
+};
+
+type AsyncAPIDocument = {
+  asyncapi: string;
+  info: {
+    title: string;
+    version: string;
+    description?: string;
+  };
+  channels: {
+    [channelName: string]: {
+      description?: string;
+      subscribe?: AsyncAPIMessage;
+      publish?: AsyncAPIMessage;
+    };
+  };
+  components?: {
+    messages: {
+      [messageName: string]: {
+        contentType: string;
+        payload: any;
+      };
+    };
+  };
+};
+
+type AsyncAPIMessage = {
+  summary?: string;
+  description?: string;
+  message: {
+    contentType: string;
+    payload: any;
+  };
+};

package/src/util.mts

@@ -0,0 +1,32 @@
+import fs from "fs/promises";
+import { Response } from "express";
+import path from "path";
+import Joi from "joi";
+
+export async function get_stats(dirs : string[], base_dir : string) {
+  let temp = await Promise.all(dirs.map((v)=> fs.lstat(path.join(base_dir, v)).then((stats)=> ({ stats, dir : v }))));
+  const result = temp.filter(({ stats })=> stats.isFile()).map((v)=> v.dir);
+  return result;
+}
+
+export async function assess_namespace(stats : string[], dir : string){
+  let dirs = stats.map((v)=> `file:///${dir.replaceAll("\\", "/")}/${v}`);
+  const result = await Promise.all(dirs.map((d)=> import(d).then((v)=> [d.replace(".mjs", "").substring(d.lastIndexOf("/")+1), v.default]))).then(Object.fromEntries);
+  return result;
+}
+
+export const template = (rule : object, v : object)=> _validate(Joi.object(rule).validate(v));
+function _validate(expression : Joi.ValidationResult){
+  let result = expression.error;
+  return result ? result.details[0].message : false;
+}
+
+export const object_id = Joi.string().hex().length(24).required();
+
+/* QoLs */
+
+export const handle_res = (controller : Promise<any>, res : Response) =>{
+  controller
+  .then((data)=> res.json({data}))
+  .catch((error)=> res.status(400).json({error}));
+}