@nestia/benchmark 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jeongho Nam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/DynamicBenchmarker.d.ts

@@ -0,0 +1,176 @@
+import { IConnection } from "@nestia/fetcher";
+import { WorkerServer } from "tgrid";
+import { IBenchmarkMaster } from "./internal/IBenchmarkMaster";
+import { IBenchmarkServant } from "./internal/IBenchmarkServant";
+/**
+ * Dynamic benchmark executor running prefixed functions.
+ *
+ * `DynamicBenchmarker` is composed with two programs,
+ * {@link DynamicBenchmarker.master} and
+ * {@link DynamicBenchmarker.servant servants}. The master program creates
+ * multiple servant programs, and the servant programs execute the prefixed
+ * functions in parallel. When the pre-congirued count of requests are all
+ * completed, the master program collects the results and returns them.
+ *
+ * Therefore, when you want to benchmark the performance of a backend server,
+ * you have to make two programs; one for calling the
+ * {@link DynamicBenchmarker.master} function, and the other for calling the
+ * {@link DynamicBenchmarker.servant} function. Also, never forget to write
+ * the path of the servant program to the
+ * {@link DynamicBenchmarker.IMasterProps.servant} property.
+ *
+ * Also, you when you complete the benchmark execution through the
+ * {@link DynamicBenchmarker.master} and {@link DynamicBenchmarker.servant}
+ * functions, you can convert the result to markdown content by using the
+ * {@link DynamicBenchmarker.markdown} function.
+ *
+ * Additionally, if you hope to see some utilization cases,
+ * see the below example tagged links.
+ *
+ * @example https://github.com/samchon/nestia-start/blob/master/test/benchmaark/index.ts
+ * @example https://github.com/samchon/backend/blob/master/test/benchmark/index.ts
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export declare namespace DynamicBenchmarker {
+    /**
+     * Properties of the master program.
+     */
+    interface IMasterProps {
+        /**
+         * Total count of the requests.
+         */
+        count: number;
+        /**
+         * Number of threads.
+         *
+         * The number of threads to be executed as parallel servant.
+         */
+        threads: number;
+        /**
+         * Number of simultaneous requests.
+         *
+         * The number of requests to be executed simultaneously.
+         *
+         * This property value would be divided by the {@link threads} in the servants.
+         */
+        simultaneous: number;
+        /**
+         * Path of the servant program.
+         *
+         * The path of the servant program executing the
+         * {@link DynamicBenchmarker.servant} function.
+         */
+        servant: string;
+        /**
+         * Filter function.
+         *
+         * The filter function to determine whether to execute the function in
+         * the servant or not.
+         *
+         * @param name Function name
+         * @returns Whether to execute the function or not.
+         */
+        filter?: (name: string) => boolean;
+        /**
+         * Progress callback function.
+         *
+         * @param complete The number of completed requests.
+         */
+        progress?: (complete: number) => void;
+        /**
+         * Standard I/O option.
+         *
+         * The standard I/O option for the servant programs.
+         */
+        stdio?: undefined | "overlapped" | "pipe" | "ignore" | "inherit";
+    }
+    /**
+     * Properties of the servant progrma.
+     */
+    interface IServantProps<Parameters extends any[]> {
+        /**
+         * Default connection.
+         *
+         * Default connection to be used in the servant.
+         */
+        connection: IConnection;
+        /**
+         * Location of the benchmark functions.
+         */
+        location: string;
+        /**
+         * Prefix of the benchmark functions.
+         *
+         * Every prefixed function will be executed in the servant.
+         *
+         * In other words, if a function name doesn't start with the prefix,
+         * then it would never be executed.
+         */
+        prefix: string;
+        /**
+         * Get parameters of a function.
+         *
+         * When composing the parameters, never forget to copy the
+         * {@link IConnection.logger} property of default connection to the
+         * returning parameters.
+         *
+         * @param connection Default connection instance
+         * @param name Function name
+         */
+        parameters: (connection: IConnection, name: string) => Parameters;
+    }
+    /**
+     * Benchmark report.
+     */
+    interface IReport {
+        count: number;
+        threads: number;
+        simultaneous: number;
+        started_at: string;
+        completed_at: string;
+        statistics: IReport.IStatistics;
+        endpoints: Array<IReport.IEndpoint & IReport.IStatistics>;
+    }
+    namespace IReport {
+        interface IEndpoint {
+            method: string;
+            path: string;
+        }
+        interface IStatistics {
+            count: number;
+            success: number;
+            mean: number | null;
+            stdev: number | null;
+            minimum: number | null;
+            maximum: number | null;
+        }
+    }
+    /**
+     * Master program.
+     *
+     * Creates a master program that executing the servant programs in parallel.
+     *
+     * Note that, {@link IMasterProps.servant} property must be the path of
+     * the servant program executing the {@link servant} function.
+     *
+     * @param props Properties of the master program
+     * @returns Benchmark report
+     */
+    const master: (props: IMasterProps) => Promise<IReport>;
+    /**
+     * Create a servant program.
+     *
+     * Creates a servant program executing the prefixed functions in parallel.
+     *
+     * @param props Properties of the servant program
+     * @returns Servant program as a worker server
+     */
+    const servant: <Parameters extends any[]>(props: IServantProps<Parameters>) => Promise<WorkerServer<null, IBenchmarkServant, IBenchmarkMaster>>;
+    /**
+     * Convert the benchmark report to markdown content.
+     *
+     * @param report Benchmark report
+     * @returns Markdown content
+     */
+    const markdown: (report: DynamicBenchmarker.IReport) => string;
+}