@visulima/pail 4.0.0-alpha.1 → 4.0.0-alpha.11

package/dist/processor/environment-processor.d.ts

@@ -0,0 +1,124 @@
+import type { Meta, Processor } from "../types.d.ts";
+/**
+ * Detected environment information.
+ *
+ * Contains runtime environment details that are automatically detected
+ * from environment variables and process information.
+ */
+interface EnvironmentInfo {
+    /** Git commit hash or short SHA */
+    commit?: string;
+    /** Runtime environment (e.g., "production", "development", "test") */
+    environment?: string;
+    /** Hostname of the machine */
+    hostname?: string;
+    /** Process ID */
+    pid?: number;
+    /** Cloud region (e.g., "us-east-1") */
+    region?: string;
+    /** Application/service name */
+    service?: string;
+    /** Application version */
+    version?: string;
+}
+/**
+ * Environment processor configuration options.
+ */
+interface EnvironmentProcessorOptions {
+    /**
+     * Whether to include the hostname. Defaults to false.
+     */
+    includeHostname?: boolean;
+    /**
+     * Whether to include the process ID. Defaults to false.
+     */
+    includePid?: boolean;
+    /**
+     * Static environment info to use instead of or in addition to auto-detection.
+     * Values provided here take precedence over auto-detected values.
+     */
+    overrides?: Partial<EnvironmentInfo>;
+}
+/**
+ * Detects the runtime environment from environment variables.
+ *
+ * Checks common environment variable patterns used by various hosting
+ * platforms (Vercel, AWS, GCP, Heroku, Railway, Fly.io, Render, etc.)
+ * to automatically determine service name, version, environment, region,
+ * and commit hash.
+ * @returns Detected environment information
+ */
+declare const detectEnvironment: () => EnvironmentInfo;
+/**
+ * Environment Enrichment Processor.
+ *
+ * Inspired by evlog's automatic environment detection, this processor
+ * enriches log metadata with runtime environment information. It auto-detects
+ * details like service name, version, environment, region, and commit hash
+ * from common environment variables used by popular hosting platforms.
+ *
+ * The detected info is added to the log's context, making it easier to
+ * correlate logs across services and deployments in production.
+ * @template L - The log level type
+ * @example
+ * ```typescript
+ * import { createPail } from "@visulima/pail";
+ * import EnvironmentProcessor from "@visulima/pail/processor/environment";
+ *
+ * const logger = createPail({
+ *   processors: [
+ *     new EnvironmentProcessor({
+ *       overrides: { service: "my-api" },
+ *       includePid: true,
+ *     }),
+ *   ],
+ * });
+ *
+ * logger.info("Server started");
+ * // Log metadata will include: { __env: { service: "my-api", environment: "production", ... } }
+ * ```
+ * @example
+ * ```typescript
+ * // With static configuration only (no auto-detection)
+ * new EnvironmentProcessor({
+ *   overrides: {
+ *     service: "payment-service",
+ *     version: "2.1.0",
+ *     environment: "staging",
+ *   },
+ * });
+ * ```
+ */
+declare class EnvironmentProcessor<L extends string = string> implements Processor<L> {
+    #private;
+    /**
+     * Creates a new EnvironmentProcessor instance.
+     *
+     * Auto-detects environment information on construction and merges
+     * with any provided overrides. Undefined values in overrides are
+     * filtered out so they don't overwrite detected values.
+     * @param options Processor configuration options
+     */
+    constructor(options?: EnvironmentProcessorOptions);
+    /**
+     * Processes log metadata to add environment information.
+     *
+     * Adds a `__env` property to the meta containing detected and
+     * configured environment details. Each call receives a shallow
+     * clone of the environment info to prevent cross-record mutation.
+     * @param meta The log metadata to process
+     * @returns The processed metadata with environment info added
+     */
+    process(meta: Meta<L>): Meta<L>;
+    /**
+     * Returns the detected environment information.
+     *
+     * Useful for inspecting what environment details were auto-detected.
+     * Returns a shallow clone to prevent external mutation.
+     * @returns The environment information object
+     */
+    getEnvironmentInfo(): Readonly<EnvironmentInfo>;
+}
+export { detectEnvironment };
+export default EnvironmentProcessor;
+export type { EnvironmentInfo, EnvironmentProcessorOptions };

package/dist/processor/environment-processor.js

@@ -0,0 +1,89 @@
+const detectEnvironment = () => {
+  if (!process.env) {
+    return {};
+  }
+  const { env } = process;
+  const info = {
+    /* eslint-disable @typescript-eslint/no-unnecessary-condition, @typescript-eslint/prefer-nullish-coalescing -- env vars may be undefined or empty at runtime */
+    // Commit hash
+    commit: env.COMMIT_SHA || env.GIT_COMMIT || env.VERCEL_GIT_COMMIT_SHA?.slice(0, 7) || env.RAILWAY_GIT_COMMIT_SHA?.slice(0, 7) || env.RENDER_GIT_COMMIT?.slice(0, 7) || env.HEROKU_SLUG_COMMIT?.slice(0, 7) || env.CF_PAGES_COMMIT_SHA?.slice(0, 7) || void 0,
+    // Environment / Node env
+    environment: env.NODE_ENV || env.ENVIRONMENT || env.APP_ENV || void 0,
+    // Hostname
+    hostname: env.HOSTNAME || env.HOST || void 0,
+    // PID
+    pid: process.pid,
+    // Region (including GCP Cloud Functions FUNCTION_REGION and GOOGLE_CLOUD_REGION)
+    region: env.AWS_REGION || env.VERCEL_REGION || env.FLY_REGION || env.RENDER_REGION || env.CF_REGION || env.GOOGLE_CLOUD_REGION || // GCP general
+    env.FUNCTION_REGION || // GCP Cloud Functions
+    void 0,
+    // Service name - check common platform variables (including GCP Cloud Run / App Engine)
+    service: env.SERVICE_NAME || env.APP_NAME || env.K_SERVICE || // GCP Cloud Run
+    env.GAE_SERVICE || // GCP App Engine
+    env.FUNCTION_TARGET || // GCP Cloud Functions
+    env.VERCEL_PROJECT_PRODUCTION_URL || env.FLY_APP_NAME || env.RAILWAY_SERVICE_NAME || env.RENDER_SERVICE_NAME || env.HEROKU_APP_NAME || void 0,
+    // Version (including GCP Cloud Run K_REVISION and App Engine GAE_VERSION)
+    version: env.APP_VERSION || env.npm_package_version || env.K_REVISION || // GCP Cloud Run revision
+    env.GAE_VERSION || // GCP App Engine version
+    env.RAILWAY_GIT_COMMIT_SHA?.slice(0, 7) || env.RENDER_GIT_COMMIT?.slice(0, 7) || void 0
+    /* eslint-enable @typescript-eslint/no-unnecessary-condition, @typescript-eslint/prefer-nullish-coalescing */
+  };
+  return Object.fromEntries(Object.entries(info).filter(([, v]) => v !== void 0));
+};
+class EnvironmentProcessor {
+  #envInfo;
+  /**
+   * Creates a new EnvironmentProcessor instance.
+   *
+   * Auto-detects environment information on construction and merges
+   * with any provided overrides. Undefined values in overrides are
+   * filtered out so they don't overwrite detected values.
+   * @param options Processor configuration options
+   */
+  constructor(options = {}) {
+    const detected = detectEnvironment();
+    const cleanOverrides = {};
+    if (options.overrides) {
+      const overrideEntries = Object.entries(options.overrides);
+      for (let i = 0; i < overrideEntries.length; i += 1) {
+        const [key, value] = overrideEntries[i];
+        if (value !== void 0) {
+          cleanOverrides[key] = value;
+        }
+      }
+    }
+    const merged = { ...detected, ...cleanOverrides };
+    if (!options.includePid && cleanOverrides.pid === void 0) {
+      delete merged.pid;
+    }
+    if (!options.includeHostname && cleanOverrides.hostname === void 0) {
+      delete merged.hostname;
+    }
+    this.#envInfo = merged;
+  }
+  /**
+   * Processes log metadata to add environment information.
+   *
+   * Adds a `__env` property to the meta containing detected and
+   * configured environment details. Each call receives a shallow
+   * clone of the environment info to prevent cross-record mutation.
+   * @param meta The log metadata to process
+   * @returns The processed metadata with environment info added
+   */
+  process(meta) {
+    const enriched = { ...meta, envStorage: { ...this.#envInfo } };
+    return enriched;
+  }
+  /**
+   * Returns the detected environment information.
+   *
+   * Useful for inspecting what environment details were auto-detected.
+   * Returns a shallow clone to prevent external mutation.
+   * @returns The environment information object
+   */
+  getEnvironmentInfo() {
+    return { ...this.#envInfo };
+  }
+}
+
+export { EnvironmentProcessor as default, detectEnvironment };

package/dist/processor/message-formatter-processor.d.ts

@@ -1,10 +1,9 @@
 import type { FormatterFunction } from "@visulima/fmt";
-import type { stringify } from "safe-stable-stringify";
 import type { Meta, StringifyAwareProcessor } from "../types.d.ts";
 /**
  * Message Formatter Processor.
  *
- * A processor that formats log messages using the {@link https://www.visulima.com/docs/package/fmt|@visulima/fmt} library.
+ * A processor that formats log messages using the {@link https://visulima.com/packages/fmt/|@visulima/fmt} library.
  * Supports custom formatters, string interpolation, and complex object formatting.
  * Processes both the main message and contextual data.
  * @template L - The log level type
@@ -39,7 +38,7 @@ declare class MessageFormatterProcessor<L extends string = string> implements St
      * Sets the stringify function for object serialization.
      * @param function_ The stringify function to use for serializing objects
      */
-    setStringify(function_: typeof stringify): void;
+    setStringify(function_: typeof JSON.stringify): void;
     /**
      * Processes log metadata to format messages.
      *