@visulima/pail 4.0.0-alpha.6 → 4.0.0-alpha.7

package/dist/wide-event.js

@@ -0,0 +1,281 @@
+const LEVEL_PRIORITY = {
+  debug: 0,
+  error: 3,
+  info: 1,
+  warn: 2
+};
+const LEVEL_TO_LOG_TYPE = {
+  debug: "debug",
+  error: "error",
+  info: "info",
+  warn: "warn"
+};
+const deepMerge = (target, source) => {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    const sourceValue = source[key];
+    const targetValue = result[key];
+    if (sourceValue !== null && typeof sourceValue === "object" && !Array.isArray(sourceValue) && targetValue !== null && typeof targetValue === "object" && !Array.isArray(targetValue)) {
+      result[key] = deepMerge(targetValue, sourceValue);
+    } else {
+      result[key] = sourceValue;
+    }
+  }
+  return result;
+};
+const formatDuration = (ms) => {
+  if (ms < 1e3) {
+    return `${ms}ms`;
+  }
+  return `${(ms / 1e3).toFixed(2)}s`;
+};
+const serializeError = (error) => {
+  const serialized = {
+    message: error.message,
+    name: error.name
+  };
+  if (error.stack) {
+    serialized.stack = error.stack;
+  }
+  const errorWithStatus = error;
+  if (errorWithStatus.status !== void 0) {
+    serialized.status = errorWithStatus.status;
+  } else if (errorWithStatus.statusCode !== void 0) {
+    serialized.status = errorWithStatus.statusCode;
+  }
+  if (errorWithStatus.data !== void 0) {
+    serialized.data = errorWithStatus.data;
+  }
+  if (error.cause instanceof Error) {
+    serialized.cause = serializeError(error.cause);
+  }
+  return serialized;
+};
+class WideEvent {
+  name;
+  autoEmit;
+  data;
+  emitted;
+  attachedError;
+  level;
+  pail;
+  requestLogs;
+  service;
+  startTime;
+  status;
+  timestamp;
+  type;
+  constructor(options) {
+    this.name = options.name;
+    this.pail = options.pail;
+    this.data = {};
+    this.startTime = performance.now();
+    this.timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    this.emitted = false;
+    this.autoEmit = options.autoEmit ?? true;
+    this.type = options.type ?? "info";
+    this.level = "info";
+    this.requestLogs = [];
+    this.service = options.service;
+  }
+  /**
+   * Record a debug-level lifecycle log entry.
+   * Does not escalate the event level.
+   * @param message Description of what happened
+   * @param context Optional structured context
+   * @returns `this` for chaining
+   */
+  debug(message, context) {
+    return this.addLogEntry("debug", message, context);
+  }
+  /**
+   * Emit the wide event through the pail logger. Can only be called once;
+   * subsequent calls are no-ops.
+   *
+   * Automatically calculates duration, determines the log type based on
+   * the highest severity level reached, and serializes any attached error.
+   *
+   * Prefer `finish()` for HTTP request contexts where you have a status code.
+   * @param typeOverride Override the log type for this emission
+   */
+  emit(typeOverride) {
+    if (this.emitted) {
+      return;
+    }
+    this.emitted = true;
+    const durationMs = Math.round(performance.now() - this.startTime);
+    const resolvedLevel = this.attachedError ? "error" : this.level;
+    const type = typeOverride ?? LEVEL_TO_LOG_TYPE[resolvedLevel] ?? this.type;
+    const payload = {
+      duration: formatDuration(durationMs),
+      duration_ms: durationMs,
+      event: this.name,
+      timestamp: this.timestamp,
+      ...this.data
+    };
+    if (this.service) {
+      payload.service = this.service;
+    }
+    if (this.status !== void 0) {
+      payload.status = this.status;
+    }
+    if (this.attachedError) {
+      payload.error = serializeError(this.attachedError);
+    }
+    if (this.requestLogs.length > 0) {
+      payload.requestLogs = this.requestLogs;
+    }
+    const logFunction = this.pail[type];
+    logFunction({ message: payload });
+  }
+  /**
+   * Record an error-level lifecycle log entry and attach the error.
+   * Escalates the event level to "error".
+   * @param message Description of what went wrong
+   * @param error The error that occurred
+   * @param context Optional structured context
+   * @returns `this` for chaining
+   */
+  error(message, error, context) {
+    if (error) {
+      this.attachedError = error;
+    }
+    return this.addLogEntry("error", message, context);
+  }
+  /**
+   * Finish and emit the wide event with HTTP context.
+   * Sets the response status and optional error before emitting.
+   * @example
+   * ```typescript
+   * ev.finish({ status: 200 });
+   * ev.finish({ status: 500, error: new Error("DB timeout") });
+   * ```
+   * @param options Status code and/or error
+   */
+  finish(options) {
+    if (options?.status !== void 0) {
+      this.status = options.status;
+    }
+    if (options?.error) {
+      this.attachedError = options.error;
+    }
+    this.emit();
+  }
+  /**
+   * Get a read-only snapshot of the accumulated data.
+   */
+  getData() {
+    return this.data;
+  }
+  /**
+   * Get the current severity level of the event.
+   * The level auto-escalates as `warn()` or `error()` entries are added.
+   */
+  getLevel() {
+    return this.attachedError ? "error" : this.level;
+  }
+  /**
+   * Get a read-only copy of the request lifecycle log entries.
+   */
+  getRequestLogs() {
+    return this.requestLogs;
+  }
+  /**
+   * Record an info-level lifecycle log entry.
+   * Does not escalate the event level.
+   * @param message Description of what happened
+   * @param context Optional structured context
+   * @returns `this` for chaining
+   */
+  info(message, context) {
+    return this.addLogEntry("info", message, context);
+  }
+  /**
+   * Accumulate context into the wide event via deep merge.
+   * Call as many times as needed throughout the operation.
+   * @example
+   * ```typescript
+   * ev.set({ user: { id: 1 } });
+   * ev.set({ user: { plan: "pro" } });
+   * // data = { user: { id: 1, plan: "pro" } }
+   * ```
+   * @param data Partial data to merge into the event
+   * @returns `this` for chaining
+   */
+  set(data) {
+    this.data = deepMerge(this.data, data);
+    return this;
+  }
+  /**
+   * Attach an error to the event. Automatically escalates the event
+   * level to "error".
+   * @param error The error to attach
+   * @returns `this` for chaining
+   */
+  setError(error) {
+    this.attachedError = error;
+    return this;
+  }
+  /**
+   * Set the HTTP response status code.
+   * @param status HTTP status code
+   * @returns `this` for chaining
+   */
+  setStatus(status) {
+    this.status = status;
+    return this;
+  }
+  /**
+   * Record a warn-level lifecycle log entry.
+   * Escalates the event level to "warn" (unless already "error").
+   * @param message Description of the warning
+   * @param context Optional structured context
+   * @returns `this` for chaining
+   */
+  warn(message, context) {
+    return this.addLogEntry("warn", message, context);
+  }
+  /**
+   * Disposable implementation. Auto-emits the event if `autoEmit` is true
+   * and the event hasn't been manually emitted yet.
+   *
+   * Enables usage with TC39 Explicit Resource Management:
+   * ```typescript
+   * using ev = createWideEvent({ pail: logger, name: "api.checkout" });
+   * ev.set({ user: { id: 1 } });
+   * // auto-emits here when scope exits
+   * ```
+   */
+  [Symbol.dispose]() {
+    if (this.autoEmit && !this.emitted) {
+      this.emit();
+    }
+  }
+  /**
+   * Add an entry to the request lifecycle log and escalate level if needed.
+   */
+  addLogEntry(level, message, context) {
+    const entry = {
+      level,
+      message,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if (context) {
+      entry.context = context;
+    }
+    this.requestLogs.push(entry);
+    this.escalateLevel(level);
+    return this;
+  }
+  /**
+   * Escalate the event level if the new level has higher severity.
+   */
+  escalateLevel(level) {
+    if ((LEVEL_PRIORITY[level] ?? 0) > (LEVEL_PRIORITY[this.level] ?? 0)) {
+      this.level = level;
+    }
+  }
+}
+const createWideEvent = (options) => new WideEvent(options);
+
+export { WideEvent, createWideEvent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visulima/pail",
-  "version": "4.0.0-alpha.6",
+  "version": "4.0.0-alpha.7",
   "description": "Highly configurable Logger for Node.js, Edge and Browser.",
   "keywords": [
     "ansi",
@@ -114,6 +114,18 @@
       "types": "./dist/processor/opentelemetry-processor.d.ts",
       "default": "./dist/processor/opentelemetry-processor.js"
     },
+    "./processor/sampling": {
+      "types": "./dist/processor/sampling-processor.d.ts",
+      "default": "./dist/processor/sampling-processor.js"
+    },
+    "./processor/environment": {
+      "types": "./dist/processor/environment-processor.d.ts",
+      "default": "./dist/processor/environment-processor.js"
+    },
+    "./error": {
+      "types": "./dist/error.d.ts",
+      "default": "./dist/error.js"
+    },
     "./reporter/file": {
       "types": "./dist/reporter/file/json-file-reporter.d.ts",
       "default": "./dist/reporter/file/json-file-reporter.js"
@@ -194,6 +206,34 @@
       "types": "./dist/object-tree.d.ts",
       "default": "./dist/object-tree.js"
     },
+    "./wide-event": {
+      "types": "./dist/wide-event.d.ts",
+      "default": "./dist/wide-event.js"
+    },
+    "./middleware/express": {
+      "types": "./dist/middleware/express.d.ts",
+      "default": "./dist/middleware/express.js"
+    },
+    "./middleware/fastify": {
+      "types": "./dist/middleware/fastify.d.ts",
+      "default": "./dist/middleware/fastify.js"
+    },
+    "./middleware/hono": {
+      "types": "./dist/middleware/hono.d.ts",
+      "default": "./dist/middleware/hono.js"
+    },
+    "./middleware/elysia": {
+      "types": "./dist/middleware/elysia.d.ts",
+      "default": "./dist/middleware/elysia.js"
+    },
+    "./middleware/sveltekit": {
+      "types": "./dist/middleware/sveltekit.d.ts",
+      "default": "./dist/middleware/sveltekit.js"
+    },
+    "./middleware/next": {
+      "types": "./dist/middleware/next/handler.d.ts",
+      "default": "./dist/middleware/next/handler.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -208,16 +248,40 @@
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9",
+    "@sveltejs/kit": ">=2.0",
     "@visulima/redact": "3.0.0-alpha.5",
+    "elysia": ">=1.0",
+    "express": ">=4.0",
+    "fastify": ">=4.0",
+    "hono": ">=4.0",
+    "next": ">=14.0",
     "rotating-file-stream": "^3.2.7"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {
       "optional": true
     },
+    "@sveltejs/kit": {
+      "optional": true
+    },
     "@visulima/redact": {
       "optional": true
     },
+    "elysia": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    },
     "rotating-file-stream": {
       "optional": true
     }