update Mokapi typings to v0.20.0

Author: marle3003

types/mokapi/encoding.d.ts

@@ -0,0 +1,28 @@
+export interface Base64Encoding {
+    /**
+     * Encodes a string value to its equivalent string representation that is encoded with base-64.
+     * https://mokapi.io/docs/javascript-api/mokapi-encoding/base64-encode
+     * @param input input - The input string to base64 encode.
+     * @returns The base64 encoding of the input string.
+     * @example
+     * export default function() {
+     *   console.log(`The base64 encoding of 'hello world' is: ${base.encode('hello world')}`)
+     * }
+     */
+    encode(input: string | ArrayBuffer): string;
+
+    /**
+     * Decodes a string value that is encoded with base-64 to its equivalent unencoded string representation.
+     * @param input input - The base64 input string to decode.
+     * @returns  The base64 decoded version of the input string.
+     * @example
+     * export default function() {
+     *   console.log(`The base64 decoded string of 'aGVsbG8gd29ybGQ=' is: ${base.decode('aGVsbG8gd29ybGQ=')}`)
+     * }
+     */
+    decode(input: string): string;
+}
+
+export const base64: Base64Encoding;
+
+

types/mokapi/faker.d.ts

@@ -13,116 +13,160 @@
 export function fake(schema: Schema | JSONSchema): any;
 
 /**
- * Gets the tree node with the given name
- * @param name name - tree node's name
+ * Retrieves a node from the faker tree by its name.
+ *
+ * @param name name - The name of the node to find.
+ * @returns The matching {@link Node} from the faker tree.
+ *
  * @example
  * export default function() {
  *   const root = findByName(RootName)
- *   root.insert(0, { name: 'foo', test: () => { return true }, fake: () => { return 'foobar' } })
+ *   root.children.unshift({
+ *      name: 'foo',
+ *      fake: () => {
+ *          return 'foobar'
+ *      }
+ *   })
  *   console.log(fake({type: 'string'}))
+ *   // Expected output: foobar
  * }
  */
-export function findByName(name: string): Tree;
+export function findByName(name: string): Node;
 
 /**
- * The name of the root faker tree
+ * The name of the root node in the faker tree.
  */
-export const RootName = "Faker";
+export const ROOT_NAME = "root";
 
 /**
- * The Tree object represents a node in the faker tree
+ * Represents a node in the faker tree.
+ * Nodes can have children and can generate fake values based on a request.
  */
-export interface Tree {
+export interface Node {
     /**
-     * Gets the name of the tree node
+     * The unique name of the node.
      */
     name: string;
 
     /**
-     * Inserts a Tree objects after the last child of this tree.
-     * @param node node - A Tree node to insert after the last child.
+     * Attributes associated with this node.
+     * These will be used for matching path or schema properties.
      */
-    append: (node: Tree | CustomTree) => void;
+    attributes: string[];
 
     /**
-     * Inserts a Tree objects at a specified index position
-     * @param index index - The zero-based index position of the insertion.
-     * @param node node - The tree node to insert
+     * A weight that determines how likely this node is to be selected,
+     * if multiple nodes match.
      */
-    insert: (index: number, node: Tree | CustomTree) => void;
+    weight: number;
 
     /**
-     * Removes a Tree node at the specific index position
-     * @param index index - The zero-based index position to remove.
+     * The child nodes of this node.
      */
-    removeAt: (index: number) => void;
+    children: Array<Node | AddNode>;
 
     /**
-     * Removes a Tree node with the given name
-     * @param name name - The name of a node to remove
-     */
-    remove: (name: string) => void;
-}
-
-/**
- * The CustomTree object represents a custom node in the faker tree
- */
-export interface CustomTree {
-    /**
-     * Gets the name of the custom tree node
-     */
-    name: string;
-
-    /**
-     * Tests whether the tree node supports the request.
-     * @param request request - Request for a new fake value
+     * Generates a fake value based on the given request.
+     *
+     * @param r r - The request describing the value to generate.
+     * @returns A generated fake value.
+     *
      * @example
      * export default function() {
      *   const frequencyItems = ['never', 'daily', 'weekly', 'monthly', 'yearly']
-     *   const node = findByName('Strings')
-     *   node.append({
+     *   const node = findByName(ROOT_NAME)
+     *   node.children.unshift({
      *     name: 'Frequency',
-     *     test: (r) => { return r.lastName() === 'frequency' },
+     *     attributes: [ 'frequency' ]
      *     fake: (r) => {
      *       return frequencyItems[Math.floor(Math.random()*frequencyItems.length)]
      *     }
      *   })
-     *   return fake({ type: 'string' })
+     *   console.log(fake({ properties: { frequency } }))
+     *   // Expected output: an object with a frequency attribute containing a random value of frequency
      * }
      */
-    test: (r: Request) => boolean;
+    fake: (r: Request) => any;
+}
+
+export interface AddNode {
+    /**
+     * The unique name of the node.
+     */
+    name: string;
+
+    /**
+     * Attributes associated with this node.
+     * These will be used for matching path or schema properties.
+     */
+    attributes?: string[];
+
+    /**
+     * A weight that determines how likely this node is to be selected,
+     * if multiple nodes match.
+     */
+    weight?: number;
+
+    /**
+     * The child nodes of this node.
+     */
+    children?: Array<Node | AddNode>;
 
     /**
-     * Gets a new fake value
-     * @param request request - Request for a new fake value
+     * Generates a fake value based on the given request.
+     *
+     * @param r r - The request describing the value to generate.
+     * @returns A generated fake value.
+     *
      * @example
      * export default function() {
      *   const frequencyItems = ['never', 'daily', 'weekly', 'monthly', 'yearly']
-     *   const node = findByName('Strings')
-     *   node.append({
+     *   const node = findByName(ROOT_NAME)
+     *   node.children.unshift({
      *     name: 'Frequency',
-     *     test: (r) => { return r.lastName() === 'frequency' },
+     *     attributes: [ 'frequency' ]
      *     fake: (r) => {
      *       return frequencyItems[Math.floor(Math.random()*frequencyItems.length)]
      *     }
      *   })
-     *   return fake({ type: 'string' })
+     *   console.log(fake({ properties: { frequency } }))
+     *   // Expected output: an object with a frequency attribute containing a random value of frequency
      * }
      */
     fake: (r: Request) => any;
 }
 
+/**
+ * Represents the input provided to the `fake` function of a {@link Node}.
+ */
 export interface Request {
-    path: PathElement[];
+    /**
+     * The path to the value to generate.
+     * This may include paths from an API endpoint or the structure of a nested object.
+     */
+    path: string[];
 
-    last: () => PathElement;
-    lastName: () => string;
-    lastSchema: () => JSONSchema;
+    /**
+     * The {@link JSONSchema} definition that describes the value to generate.
+     */
+    schema: JSONSchema;
+
+    /**
+     * A shared context holding values generated by other nodes.
+     * This allows for interdependent data generation — for example, creating an email
+     * address using a previously generated first and last name.
+     */
+    context: Context
 }
 
-export interface PathElement {
-    name: string;
-    schema: JSONSchema;
+/**
+ * A context map holding values generated during the faker tree evaluation.
+ */
+export interface Context {
+    /**
+     * A map of names to previously generated values.
+     */
+    values: { [name: string]: any }
 }
 
 /**
@@ -171,7 +215,7 @@ export interface JSONSchema {
     maximum?: number;
 
     /**
-     * Restricts the number to a exclusive maximum number
+     * Restricts the number to an exclusive maximum number
      */
     exclusiveMaximum?: number;
 
@@ -181,7 +225,7 @@ export interface JSONSchema {
     minimum?: number;
 
     /**
-     * Restricts the number to a exclusive minimum number
+     * Restricts the number to an exclusive minimum number
      */
     exclusiveMinimum?: number;
 
@@ -348,4 +392,4 @@ export interface Schema {
 
     /** Specifies whether all items in an array must be unique. */
     uniqueItems?: boolean;
-}
+}

types/mokapi/global.d.ts

@@ -16,12 +16,12 @@ declare global {
      *   });
      * }
      */
-    function open(filePath: string, args?: Args): string;
+    function open(filePath: string, args?: Args): any;
 
     interface Args {
         /**
-         * By default contents of the file are read as string, but with binary the file will be read as binary.
+         * By default, contents of the file are read as string, but with binary the file will be read as binary.
          */
-        as: "binary" | "string";
+        as: "binary" | "string" | "resolved";
     }
-}
+}

types/mokapi/http.d.ts

@@ -117,4 +117,4 @@ export interface Response {
      * res.json()
      */
     json(): JSONValue;
-}
+}

types/mokapi/index.d.ts

@@ -1,13 +1,15 @@
 /**
  * Mokapi JavaScript API
- * https://mokapi.io/docs/guides/get-started/welcome
+ * https://mokapi.io/docs/guides/welcome
  */
 
 import "./faker";
 import "./global";
 import "./http";
 import "./mustache";
 import "./yaml";
+import "./encoding";
+import "./mail";
 
 /**
  * Attaches an event handler for the given event.
@@ -93,7 +95,7 @@ export function sleep(time: number | string): void;
 
 /**
  * Specifies the interval of a periodic job.
- * Interval string is a possibly signed sequence of decimal numbers, each with optional
+ * Interval string is a possibly signed sequence of decimal numbers, each with an optional
  * fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m".
  * Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
  */
@@ -120,7 +122,7 @@ export interface EventHandler {
  *   })
  * }
  */
-export type HttpEventHandler = (request: HttpRequest, response: HttpResponse) => boolean;
+export type HttpEventHandler = (request: HttpRequest, response: HttpResponse) => void | Promise<void>;
 
 /**
  * HttpRequest is an object used by HttpEventHandler that contains request-specific
@@ -134,7 +136,7 @@ export interface HttpRequest {
     /** Represents a parsed URL. */
     readonly url: Url;
 
-    /** Body contains request body specified by OpenAPI request body. */
+    /** Body contains the request body specified by OpenAPI request body. */
     readonly body: any;
 
     /** Object contains path parameters specified by OpenAPI path parameters. */
@@ -202,7 +204,7 @@ export interface Url {
  *   })
  * }
  */
-export type KafkaEventHandler = (message: KafkaEventMessage) => boolean;
+export type KafkaEventHandler = (message: KafkaEventMessage) => void | Promise<void>;
 
 /**
  * KafkaEventMessage is an object used by KafkaEventHandler that contains Kafka-specific message data.
@@ -241,7 +243,7 @@ export interface KafkaEventMessage {
  *   })
  * }
  */
-export type LdapEventHandler = (request: LdapSearchRequest, response: LdapSearchResponse) => boolean;
+export type LdapEventHandler = (request: LdapSearchRequest, response: LdapSearchResponse) => void | Promise<void>;
 
 /**
  * LdapSearchRequest is an object used by LdapEventHandler that contains request-specific data.
@@ -341,7 +343,7 @@ export enum LdapResultStatus {
     SizeLimitExceeded = 4,
 }
 
-export type SmtpEventHandler = (record: SmtpEventMessage) => boolean;
+export type SmtpEventHandler = (record: SmtpEventMessage) => void | Promise<void>;
 
 export interface SmtpEventMessage {
     server: string;
@@ -379,7 +381,7 @@ export interface DateArgs {
     /**
      * The format of the textual representation, default is RFC3339
      */
-    layout?: DateLayout;
+    layout?: DateLayout | string;
 
     /**
      * The timestamp of the date, default is current UTC time
@@ -455,3 +457,7 @@ export interface JSONObject {
 }
 
 export const RFC3339 = "RFC3339";
+
+export function patch(target: any, patch: any): any;
+
+export const Delete: unique symbol;

types/mokapi/kafka.d.ts

@@ -243,4 +243,4 @@ export interface ProduceRetry {
      * @default 5
      */
     retries: number;
-}
+}