@faasjs/node-utils 8.0.0-beta.10

package/dist/index.d.ts

@@ -0,0 +1,347 @@
+//#region src/deep_merge.d.ts
+/**
+ * Deep merge two objects or arrays.
+ *
+ * Features:
+ * * All objects will be cloned before merging.
+ * * Merging order is from right to left.
+ * * If an array include same objects, it will be unique to one.
+ *
+ * ```ts
+ * deepMerge({ a: 1 }, { a: 2 }) // { a: 2 }
+ * deepMerge([1, 2], [2, 3]) // [1, 2, 3]
+ * ```
+ */
+declare function deepMerge(...sources: any[]): any;
+//#endregion
+//#region src/logger.d.ts
+/** Logger Level */
+type Level = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Formats the provided arguments into a string, filtering out any objects
+ * with a `__hidden__` property set to `true`. If formatting fails, it attempts
+ * to stringify each argument individually.
+ *
+ * @param {...any[]} args - The arguments to format.
+ * @returns {string} The formatted string.
+ */
+declare function formatLogger(fmt: any, ...args: any[]): string;
+/**
+ * Logger Class
+ *
+ * @example
+ * ```ts
+ * const logger = new Logger()
+ *
+ * logger.debug('debug message')
+ * logger.info('info message')
+ * logger.warn('warn message')
+ * logger.error('error message')
+ *
+ * logger.time('timer name')
+ * logger.timeEnd('timer name', 'message') // => 'message +1ms'
+ * ```
+ */
+declare class Logger {
+  silent: boolean;
+  level: Level;
+  colorfyOutput: boolean;
+  label?: string;
+  size: number;
+  disableTransport: boolean;
+  stdout: (text: string) => void;
+  stderr: (text: string) => void;
+  private cachedTimers;
+  /**
+   * @param label {string} Prefix label
+   */
+  constructor(label?: string);
+  /**
+   * @param message {string} message
+   * @param args {...any=} arguments
+   */
+  debug(message: string, ...args: any[]): Logger;
+  /**
+   * @param message {string} message
+   * @param args {...any=} arguments
+   */
+  info(message: string, ...args: any[]): Logger;
+  /**
+   * @param message {string} message
+   * @param args {...any=} arguments
+   */
+  warn(message: string, ...args: any[]): Logger;
+  /**
+   * @param message {any} message or Error object
+   * @param args {...any=} arguments
+   */
+  error(message: string | Error | unknown, ...args: any[]): Logger;
+  /**
+   * Start a timer with a specific key and log level.
+   *
+   * @param key - The unique identifier for the timer.
+   * @param level - The log level for the timer. Defaults to 'debug'.
+   * @returns The Logger instance for chaining.
+   */
+  time(key: string, level?: Level): Logger;
+  /**
+   * End a timer with a specific key and log the elapsed time.
+   *
+   * @param key - The unique identifier for the timer.
+   * @param message - The message to log with the elapsed time.
+   * @param args - Additional arguments to log with the message.
+   * @returns The Logger instance for chaining.
+   */
+  timeEnd(key: string, message: string, ...args: any[]): Logger;
+  /**
+   * @param message {string} message
+   * @param args {...any=} arguments
+   */
+  raw(message: string, ...args: any[]): Logger;
+  private log;
+}
+//#endregion
+//#region src/color.d.ts
+declare const Color: {
+  DEFAULT: number;
+  BLACK: number;
+  RED: number;
+  GREEN: number;
+  ORANGE: number;
+  BLUE: number;
+  MAGENTA: number;
+  CYAN: number;
+  GRAY: number;
+};
+declare const LevelColor: {
+  debug: number;
+  info: number;
+  warn: number;
+  error: number;
+};
+/**
+ * Apply ANSI color codes to a message based on the log level.
+ *
+ * @param level - The log level to determine the color.
+ * @param message - The message to be colorized.
+ * @returns The colorized message string.
+ */
+declare function colorfy(level: Level, message: string): string;
+//#endregion
+//#region src/load_config.d.ts
+type FuncPluginConfig = {
+  [key: string]: any;
+  type?: string;
+  config?: {
+    [key: string]: any;
+  };
+  name?: string;
+};
+type FuncConfig = {
+  [key: string]: any;
+  plugins?: {
+    [key: string]: FuncPluginConfig;
+  };
+};
+/**
+ * Load configuration from faas.yaml
+ */
+declare function loadConfig(root: string, filename: string, staging: string, logger?: Logger): FuncConfig;
+//#endregion
+//#region src/load_env.d.ts
+type LoadEnvFileIfExistsOptions = {
+  cwd?: string;
+  filename?: string;
+};
+/**
+ * Load a dotenv file if it exists.
+ *
+ * - Defaults to `${process.cwd()}/.env`.
+ * - Existing environment variables are preserved (Node.js behavior).
+ */
+declare function loadEnvFileIfExists(options?: LoadEnvFileIfExistsOptions): string | null;
+//#endregion
+//#region src/load_func.d.ts
+type ExportedHandler<TEvent = any, TContext = any, TResult = any> = (event?: TEvent, context?: TContext, callback?: (...args: any) => any) => Promise<TResult>;
+/**
+ * Load a FaasJS function and its configuration, returning the handler.
+ *
+ * @param root Project root directory used to resolve configuration.
+ * @param filename Path to the packaged FaasJS function file to load.
+ * @param staging Staging directory name (used when locating config).
+ * @returns A promise that resolves to the function handler.
+ *
+ * @example
+ * ```ts
+ * import { loadFunc } from '@faasjs/node-utils'
+ *
+ * const handler = await loadFunc(
+ *   process.cwd(),
+ *   __dirname + '/example.func.ts',
+ *   'development'
+ * )
+ *
+ * const result = await handler(event, context)
+ * console.log(result)
+ * ```
+ */
+declare function loadFunc<TEvent = any, TContext = any, TResult = any>(root: string, filename: string, staging: string): Promise<ExportedHandler<TEvent, TContext, TResult>>;
+//#endregion
+//#region src/load_package.d.ts
+type NodeRuntime = 'commonjs' | 'module';
+declare function resetRuntime(): void;
+/**
+ * Detect current JavaScript runtime environment.
+ *
+ * This function checks for presence of `require` first, then falls back to
+ * Node.js ESM detection via `process.versions.node`.
+ *
+ * @returns {NodeRuntime} Returns `module` for ESM and `commonjs` for CJS.
+ * @throws {Error} Throws an error if runtime cannot be determined.
+ */
+declare function detectNodeRuntime(): NodeRuntime;
+/**
+ * Asynchronously loads a package by its name, supporting both ESM and CJS.
+ *
+ * @template T The type of module to be loaded.
+ * @param name The package name to load.
+ * @param defaultNames Preferred export keys used to resolve default values.
+ * @returns Loaded module or resolved default export.
+ */
+declare function loadPackage<T = unknown>(name: string, defaultNames?: string | string[]): Promise<T>;
+//#endregion
+//#region src/stream.d.ts
+/**
+ * Convert ReadableStream to text.
+ *
+ * @throws {TypeError} If stream is not a ReadableStream instance.
+ */
+declare function streamToText(stream: ReadableStream<Uint8Array>): Promise<string>;
+/**
+ * Convert ReadableStream to object.
+ *
+ * @throws {TypeError} If stream is not a ReadableStream instance.
+ */
+declare function streamToObject<T = any>(stream: ReadableStream<Uint8Array>): Promise<T>;
+declare const streamToString: typeof streamToText;
+//#endregion
+//#region src/transport.d.ts
+type LoggerMessage = {
+  level: Level;
+  labels: string[];
+  message: string;
+  timestamp: number;
+  extra?: any[];
+};
+type TransportHandler = (messages: LoggerMessage[]) => Promise<void>;
+type TransportOptions = {
+  /** @default 'LoggerTransport' */label?: string; /** @default 5000 */
+  interval?: number; /** @default false */
+  debug?: boolean;
+};
+/**
+ * The transport class that manages the transport handlers and log messages.
+ *
+ * **Note: This class is not meant to be used directly. Use the {@link getTransport} instead.**
+ *
+ * @example
+ * ```typescript
+ * import { getTransport } from '@faasjs/node-utils'
+ *
+ * const transport = getTransport()
+ *
+ * transport.register('test', async (messages) => {
+ *  for (const { level, message } of messages)
+ *    console.log(level, message)
+ * })
+ *
+ * transport.config({ label: 'test', debug: true })
+ *
+ * // If you using Logger, it will automatically insert messages to the transport.
+ * // Otherwise, you can insert messages manually.
+ * transport.insert({
+ *   level: 'info',
+ *   labels: ['server'],
+ *   message: 'test message',
+ *   timestamp: Date.now()
+ * })
+ *
+ * process.on('SIGINT', async () => {
+ *   await transport.stop()
+ *   process.exit(0)
+ * })
+ * ```
+ */
+declare class Transport {
+  private enabled;
+  handlers: Map<string, TransportHandler>;
+  private logger;
+  messages: LoggerMessage[];
+  private flushing;
+  private interval;
+  private intervalTime;
+  constructor();
+  /**
+   * Registers a new transport handler.
+   *
+   * @param name - The name of the transport handler.
+   * @param handler - The transport handler function to be registered.
+   */
+  register(name: string, handler: TransportHandler): void;
+  /**
+   * Unregister a handler by its name.
+   *
+   * This method logs the unregistration process, removes the handler from the internal collection,
+   * and disables the logger if no handlers remain.
+   *
+   * @param name - The name of the handler to unregister.
+   */
+  unregister(name: string): void;
+  /**
+   * Inserts a log message into the transport if it is enabled.
+   *
+   * @param message - The log message to be inserted.
+   */
+  insert(message: LoggerMessage): void;
+  /**
+   * Flushes the current messages by processing them with the registered handlers.
+   *
+   * If the transport is already flushing, it will wait until the current flush is complete.
+   * If the transport is disabled or there are no messages to flush, it will return immediately.
+   * If there are no handlers registered, it will log a warning, clear the messages, disable the transport, and stop the interval.
+   *
+   * The method processes all messages with each handler and logs any errors encountered during the process.
+   *
+   * @returns {Promise<void>} A promise that resolves when the flush operation is complete.
+   */
+  flush(): Promise<void>;
+  /**
+   * Stops the logger transport.
+   *
+   * This method performs the following actions:
+   * 1. Logs a 'stopping' message.
+   * 2. Clears the interval if it is set.
+   * 3. Flushes any remaining logs.
+   * 4. Disables the transport.
+   *
+   * @returns {Promise<void>} A promise that resolves when the transport has been stopped.
+   */
+  stop(): Promise<void>;
+  /**
+   * Resets the transport by clearing handlers, emptying messages, and re-enabling the transport.
+   * If an interval is set, it will be cleared.
+   */
+  reset(): void;
+  /**
+   * Configure the transport options for the logger.
+   *
+   * @param {TransportOptions} options - The configuration options for the transport.
+   * @param {string} [options.label] - The label to be used by the logger.
+   * @param {boolean} [options.debug] - If true, sets the logger level to 'debug', otherwise sets it to 'info'.
+   * @param {number} [options.interval] - The interval time in milliseconds for flushing the logs. If different from the current interval, it updates the interval and resets the timer.
+   */
+  config(options: TransportOptions): void;
+}
+declare function getTransport(): Transport;
+//#endregion
+export { Color, type ExportedHandler, type FuncConfig, type FuncPluginConfig, type Level, LevelColor, type LoadEnvFileIfExistsOptions, Logger, type LoggerMessage, type NodeRuntime, Transport, type TransportHandler, type TransportOptions, colorfy, deepMerge, detectNodeRuntime, formatLogger, getTransport, loadConfig, loadEnvFileIfExists, loadFunc, loadPackage, resetRuntime, streamToObject, streamToString, streamToText };