@visulima/pail 3.1.0 → 3.2.1

package/dist/reporter/http/http-reporter.edge-light.d.ts

@@ -0,0 +1,40 @@
+import type { AbstractHttpReporterOptions } from "./abstract-http-reporter.d.ts";
+import { AbstractHttpReporter } from "./abstract-http-reporter.d.ts";
+/**
+ * HTTP Reporter for Edge Runtime environments.
+ *
+ * A reporter optimized for Edge Runtime environments (Next.js Edge, Cloudflare Workers, etc.)
+ * that sends logs to HTTP endpoints. Edge compatibility mode is enabled by default.
+ * Supports batching, retries, and rate limiting. Compression is disabled for Edge compatibility.
+ * @template L - The log level type
+ * @example
+ * ```typescript
+ * import { createPail } from "@visulima/pail";
+ * import { HttpReporterEdgeLight } from "@visulima/pail/reporter/http/edge-light";
+ *
+ * const logger = createPail({
+ *   reporters: [
+ *     new HttpReporterEdgeLight({
+ *       url: "https://api.example.com/logs",
+ *       method: "POST",
+ *       headers: {
+ *         "Authorization": "Bearer token"
+ *       },
+ *       enableBatchSend: true,
+ *       batchSize: 50
+ *     })
+ *   ]
+ * });
+ *
+ * logger.info("Edge function started");
+ * ```
+ */
+declare class HttpReporterEdgeLight<L extends string = string> extends AbstractHttpReporter<L> {
+    /**
+     * Creates a new HTTP Reporter Edge Light instance.
+     * Edge compatibility mode is automatically enabled.
+     * @param options Configuration options for HTTP reporting
+     */
+    constructor(options: Omit<AbstractHttpReporterOptions, "edgeCompat">);
+}
+export default HttpReporterEdgeLight;

package/dist/reporter/http/http-reporter.edge-light.js

@@ -0,0 +1,651 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+const {
+  Buffer
+} = __cjs_getBuiltinModule("node:buffer");
+const {
+  gzipSync
+} = __cjs_getBuiltinModule("node:zlib");
+
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return (prototype === null || prototype === Object.prototype || Object.getPrototypeOf(prototype) === null) && !(Symbol.toStringTag in value) && !(Symbol.iterator in value);
+}
+
+const ErrorProto = Object.create(
+  {},
+  {
+    cause: {
+      enumerable: true,
+      value: void 0,
+      writable: true
+    },
+    code: {
+      enumerable: true,
+      value: void 0,
+      writable: true
+    },
+    errors: {
+      enumerable: true,
+      value: void 0,
+      writable: true
+    },
+    message: {
+      enumerable: true,
+      value: void 0,
+      writable: true
+    },
+    name: {
+      enumerable: true,
+      value: void 0,
+      writable: true
+    },
+    stack: {
+      enumerable: true,
+      value: void 0,
+      writable: true
+    }
+  }
+);
+const toJsonWasCalled = /* @__PURE__ */ new WeakSet();
+const toJSON = (from) => {
+  toJsonWasCalled.add(from);
+  const json = from.toJSON();
+  toJsonWasCalled.delete(from);
+  return json;
+};
+const serializeValue = (value, seen, depth, options) => {
+  if (value && value instanceof Uint8Array && value.constructor.name === "Buffer") {
+    return "[object Buffer]";
+  }
+  if (value !== null && typeof value === "object" && typeof value.pipe === "function") {
+    return "[object Stream]";
+  }
+  if (value instanceof Error) {
+    if (seen.includes(value)) {
+      return "[Circular]";
+    }
+    depth += 1;
+    return _serialize(value, options, seen, depth);
+  }
+  if (options.useToJSON && typeof value.toJSON === "function") {
+    return value.toJSON();
+  }
+  if (typeof value === "object" && value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === "function") {
+    return `[Function: ${value.name || "anonymous"}]`;
+  }
+  if (isPlainObject(value)) {
+    depth += 1;
+    if (options.maxDepth && depth >= options.maxDepth) {
+      return {};
+    }
+    const plainObject = {};
+    for (const key in value) {
+      plainObject[key] = serializeValue(value[key], seen, depth, options);
+    }
+    return plainObject;
+  }
+  try {
+    return value;
+  } catch {
+    return "[Not Available]";
+  }
+};
+const _serialize = (error, options, seen, depth) => {
+  seen.push(error);
+  if (options.maxDepth === 0) {
+    return {};
+  }
+  if (options.useToJSON && typeof error.toJSON === "function" && !toJsonWasCalled.has(error)) {
+    return toJSON(error);
+  }
+  const protoError = Object.create(ErrorProto);
+  protoError.name = Object.prototype.toString.call(error.constructor) === "[object Function]" ? error.constructor.name : error.name;
+  protoError.message = error.message;
+  protoError.stack = error.stack;
+  if (Array.isArray(error.errors)) {
+    const aggregateErrors = [];
+    for (const aggregateError of error.errors) {
+      if (!(aggregateError instanceof Error)) {
+        throw new TypeError("All errors in the 'errors' property must be instances of Error");
+      }
+      if (seen.includes(aggregateError)) {
+        protoError.errors = [];
+        return protoError;
+      }
+      aggregateErrors.push(_serialize(aggregateError, options, seen, depth));
+    }
+    protoError.errors = aggregateErrors;
+  }
+  if (error.cause instanceof Error && !seen.includes(error.cause)) {
+    protoError.cause = _serialize(error.cause, options, seen, depth);
+  }
+  for (const key in error) {
+    if (protoError[key] === void 0) {
+      const value = error[key];
+      protoError[key] = serializeValue(value, seen, depth, options);
+    }
+  }
+  if (Array.isArray(options.exclude) && options.exclude.length > 0) {
+    for (const key of options.exclude) {
+      try {
+        delete protoError[key];
+      } catch {
+      }
+    }
+  }
+  return protoError;
+};
+const serialize = (error, options = {}) => _serialize(
+  error,
+  {
+    exclude: options.exclude ?? [],
+    maxDepth: options.maxDepth ?? Number.POSITIVE_INFINITY,
+    useToJSON: options.useToJSON ?? false
+  },
+  [],
+  0
+);
+
+const EMPTY_SYMBOL = Symbol("EMPTY");
+
+class AbstractJsonReporter {
+  /** Custom stringify function for object serialization */
+  stringify;
+  /** Error serialization options */
+  errorOptions;
+  /**
+   * Creates a new AbstractJsonReporter instance.
+   * @param options Configuration options for JSON formatting and error handling
+   */
+  constructor(options = {}) {
+    this.errorOptions = options.error ?? {};
+  }
+  /**
+   * Sets a custom stringify function for object serialization.
+   * @param function_ The stringify function to use for serialization
+   */
+  // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any
+  setStringify(function_) {
+    this.stringify = function_;
+  }
+  // eslint-disable-next-line sonarjs/cognitive-complexity
+  log(meta) {
+    const { context, error, file, message, type, ...rest } = meta;
+    if (rest.label) {
+      rest.label = rest.label.trim();
+    }
+    if (file) {
+      rest.file = `${file.name}:${file.line}${file.column ? `:${file.column}` : ""}`;
+    }
+    if (message === EMPTY_SYMBOL) {
+      rest.message = void 0;
+    } else {
+      rest.message = message;
+    }
+    if (error) {
+      rest.error = serialize(error, this.errorOptions);
+    }
+    if (context) {
+      const newContext = [];
+      for (const item of context) {
+        if (item === EMPTY_SYMBOL) {
+          continue;
+        }
+        if (item instanceof Error) {
+          newContext.push(serialize(item, this.errorOptions));
+        } else {
+          newContext.push(item);
+        }
+      }
+      rest.context = newContext;
+    }
+    this._log(this.stringify(rest), type.level);
+  }
+}
+
+const compressData = async (data) => {
+  const CompressionStreamClass = globalThis.CompressionStream;
+  if (CompressionStreamClass) {
+    const stream = new CompressionStreamClass("gzip");
+    const writer = stream.writable.getWriter();
+    const reader = stream.readable.getReader();
+    const encoder = new TextEncoder();
+    const chunks = [];
+    writer.write(encoder.encode(data));
+    writer.close();
+    let done = false;
+    while (!done) {
+      const result2 = await reader.read();
+      done = result2.done ?? false;
+      if (result2.value) {
+        chunks.push(result2.value);
+      }
+    }
+    const totalLength = chunks.reduce((accumulator, chunk) => accumulator + chunk.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return result;
+  }
+  return gzipSync(data);
+};
+
+class LogSizeError extends Error {
+  /**
+   * The log entry data that caused the error
+   */
+  logData;
+  /**
+   * The actual size of the log entry in bytes
+   */
+  actualSize;
+  /**
+   * The maximum allowed size in bytes
+   */
+  maxSize;
+  /**
+   * Creates a new LogSizeError instance.
+   * @param message Descriptive error message explaining the size violation
+   * @param logData The log entry data that caused the error
+   * @param actualSize Size of the log entry in bytes
+   * @param maxSize Maximum allowed size in bytes
+   * @example
+   * ```typescript
+   * throw new LogSizeError("Log too large", logData, 2000000, 1000000);
+   * ```
+   */
+  constructor(message, logData, actualSize, maxSize) {
+    super(message);
+    this.name = "LogSizeError";
+    this.logData = logData;
+    this.actualSize = actualSize;
+    this.maxSize = maxSize;
+  }
+}
+
+const calculateBackoffDelay = (baseDelay, attempt) => baseDelay * 2 ** attempt;
+const sleep = (delay) => new Promise((resolve) => {
+  setTimeout(resolve, delay);
+});
+const prepareRequestBody = (body) => {
+  if (typeof body === "string") {
+    return body;
+  }
+  return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+};
+const processResponse = async (response, url, method, headers, body, onDebugRequestResponse, onError) => {
+  const responseHeaders = {};
+  response.headers.forEach((value, key) => {
+    responseHeaders[key] = value;
+  });
+  const responseBody = await response.text();
+  const requestResponse = {
+    req: {
+      body,
+      headers,
+      method,
+      url
+    },
+    res: {
+      body: responseBody,
+      headers: responseHeaders,
+      status: response.status,
+      statusText: response.statusText
+    }
+  };
+  if (onDebugRequestResponse) {
+    onDebugRequestResponse(requestResponse);
+  }
+  if (response.ok) {
+    return false;
+  }
+  if (response.status < 500 && response.status !== 429) {
+    const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
+    if (onError) {
+      onError(error);
+    }
+    throw error;
+  }
+  return true;
+};
+const handleRateLimit = (response, respectRateLimit, retryDelay, attempt, maxRetries) => {
+  if (response.status === 429 && respectRateLimit && attempt < maxRetries) {
+    const retryAfter = response.headers.get("retry-after");
+    return retryAfter ? Number.parseInt(retryAfter, 10) * 1e3 : calculateBackoffDelay(retryDelay, attempt);
+  }
+  return void 0;
+};
+const handleServerError = (response, retryDelay, attempt, maxRetries) => {
+  if (response.status >= 500 && attempt < maxRetries) {
+    return calculateBackoffDelay(retryDelay, attempt);
+  }
+  return void 0;
+};
+const calculateRetryDelay = (response, respectRateLimit, retryDelay, attempt, maxRetries) => {
+  const rateLimitDelay = handleRateLimit(response, respectRateLimit, retryDelay, attempt, maxRetries);
+  if (rateLimitDelay !== void 0) {
+    return rateLimitDelay;
+  }
+  return handleServerError(response, retryDelay, attempt, maxRetries);
+};
+const handleRetryError = async (error, attempt, maxRetries, retryDelay, onError) => {
+  if (attempt < maxRetries) {
+    const delay = calculateBackoffDelay(retryDelay, attempt);
+    await sleep(delay);
+    return true;
+  }
+  if (onError) {
+    onError(error);
+  }
+  return false;
+};
+const sendWithRetry = async (url, method, headers, body, maxRetries, retryDelay, respectRateLimit, onDebugRequestResponse, onError) => {
+  let attempt = 0;
+  while (attempt <= maxRetries) {
+    try {
+      const requestBody = prepareRequestBody(body);
+      const response = await fetch(url, {
+        body: requestBody,
+        headers,
+        method
+      });
+      const shouldRetry = await processResponse(response, url, method, headers, body, onDebugRequestResponse, onError);
+      if (!shouldRetry) {
+        return;
+      }
+      const retryDelayValue = calculateRetryDelay(response, respectRateLimit, retryDelay, attempt, maxRetries);
+      if (retryDelayValue !== void 0) {
+        await sleep(retryDelayValue);
+        attempt += 1;
+        continue;
+      }
+      if (!response.ok) {
+        const error = new Error(`HTTP ${response.status}: ${response.statusText}`);
+        if (onError) {
+          onError(error);
+        }
+        throw error;
+      }
+      return;
+    } catch (error) {
+      const shouldRetry = await handleRetryError(error, attempt, maxRetries, retryDelay, onError);
+      if (shouldRetry) {
+        attempt += 1;
+        continue;
+      }
+      throw error;
+    }
+  }
+};
+
+class AbstractHttpReporter extends AbstractJsonReporter {
+  url;
+  method;
+  headers;
+  contentType;
+  batchContentType;
+  onError;
+  onDebug;
+  onDebugRequestResponse;
+  payloadTemplate;
+  compression;
+  maxRetries;
+  retryDelay;
+  respectRateLimit;
+  enableBatchSend;
+  batchSize;
+  batchSendTimeout;
+  batchSendDelimiter;
+  batchMode;
+  batchFieldName;
+  maxLogSize;
+  maxPayloadSize;
+  edgeCompat;
+  // Batch management
+  batchQueue = [];
+  batchTimeout;
+  isProcessingBatch = false;
+  currentBatchSize = 0;
+  // Track uncompressed size of current batch
+  /**
+   * Creates a new instance of AbstractHttpReporter.
+   * @param config Configuration options for the reporter
+   */
+  constructor(config) {
+    super(config);
+    this.url = config.url;
+    this.method = config.method ?? "POST";
+    this.headers = config.headers ?? {};
+    this.contentType = config.contentType ?? "application/json";
+    this.batchContentType = config.batchContentType ?? "application/json";
+    this.onError = config.onError;
+    this.onDebug = config.onDebug;
+    this.onDebugRequestResponse = config.onDebugRequestResponse;
+    this.payloadTemplate = config.payloadTemplate ?? ((data) => JSON.stringify(data));
+    this.compression = config.compression ?? false;
+    this.maxRetries = config.maxRetries ?? 3;
+    this.retryDelay = config.retryDelay ?? 1e3;
+    this.respectRateLimit = config.respectRateLimit ?? true;
+    this.enableBatchSend = config.enableBatchSend ?? true;
+    this.batchSize = config.batchSize ?? 100;
+    this.batchSendTimeout = config.batchSendTimeout ?? 5e3;
+    this.batchSendDelimiter = config.batchSendDelimiter ?? "\n";
+    this.batchMode = config.batchMode ?? "delimiter";
+    this.batchFieldName = config.batchFieldName;
+    if (this.batchMode === "field" && !this.batchFieldName) {
+      throw new Error("batchFieldName is required when batchMode is 'field'");
+    }
+    this.maxLogSize = config.maxLogSize ?? 1048576;
+    this.maxPayloadSize = config.maxPayloadSize ?? 5242880;
+    this.edgeCompat = config.edgeCompat ?? false;
+  }
+  /**
+   * Processes and ships log entries to the HTTP endpoint.
+   * @param message The JSON-formatted log message
+   * @param logLevel The log level of the message
+   * @protected
+   */
+  // eslint-disable-next-line no-underscore-dangle
+  _log(message, logLevel) {
+    try {
+      const logData = JSON.parse(message);
+      const logLevelString = logLevel;
+      const messageString = logData.message;
+      const payloadTemplate = {
+        logLevel: logLevelString,
+        message: messageString ?? ""
+      };
+      if (logData.data) {
+        payloadTemplate["data"] = logData.data;
+      } else if (logData.context) {
+        payloadTemplate["data"] = logData.context;
+      } else {
+        const rest = { ...logData };
+        delete rest.message;
+        if (Object.keys(rest).length > 0) {
+          payloadTemplate["data"] = rest;
+        }
+      }
+      const payload = this.payloadTemplate(payloadTemplate);
+      if (this.onDebug) {
+        this.onDebug({ data: payloadTemplate.data, logLevel: logLevelString, message: messageString });
+      }
+      const logEntrySize = this.edgeCompat || typeof TextEncoder === "undefined" ? Buffer.byteLength(payload, "utf8") : new TextEncoder().encode(payload).length;
+      if (logEntrySize > this.maxLogSize) {
+        const error = new LogSizeError(
+          `Log entry exceeds maximum size of ${this.maxLogSize} bytes. Size: ${logEntrySize} bytes`,
+          { data: payloadTemplate.data, logLevel: logLevelString, message: messageString },
+          logEntrySize,
+          this.maxLogSize
+        );
+        if (this.onError) {
+          this.onError(error);
+        }
+        return;
+      }
+      if (this.enableBatchSend) {
+        this.addToBatch(payload, logEntrySize);
+      } else {
+        this.sendPayload(payload).catch((error) => {
+          if (this.onError) {
+            this.onError(error);
+          }
+        });
+      }
+    } catch (error) {
+      if (this.onError) {
+        this.onError(error);
+      }
+    }
+  }
+  /**
+   * Adds a payload to the batch queue and triggers sending if conditions are met.
+   */
+  addToBatch(payload, logEntrySize) {
+    const payloadSizeWithEntry = this.currentBatchSize + logEntrySize + this.batchSendDelimiter.length;
+    const payloadSizeThreshold = this.maxPayloadSize * 0.9;
+    if (payloadSizeWithEntry > payloadSizeThreshold && this.batchQueue.length > 0) {
+      this.processBatch();
+    }
+    this.batchQueue.push(payload);
+    this.currentBatchSize += logEntrySize + this.batchSendDelimiter.length;
+    if (!this.batchTimeout) {
+      this.batchTimeout = setTimeout(() => {
+        this.processBatch();
+      }, this.batchSendTimeout);
+    }
+    if (this.batchQueue.length >= this.batchSize) {
+      this.processBatch();
+    }
+  }
+  /**
+   * Processes the current batch and sends it to the HTTP endpoint.
+   */
+  async processBatch() {
+    if (this.isProcessingBatch || this.batchQueue.length === 0) {
+      return;
+    }
+    this.isProcessingBatch = true;
+    if (this.batchTimeout) {
+      clearTimeout(this.batchTimeout);
+      this.batchTimeout = void 0;
+    }
+    const batch = this.batchQueue.splice(0, this.batchSize);
+    this.currentBatchSize = 0;
+    for (let i = 0; i < this.batchQueue.length; i += 1) {
+      const payload = this.batchQueue[i];
+      const payloadSize = this.edgeCompat || typeof TextEncoder === "undefined" ? Buffer.byteLength(payload, "utf8") : new TextEncoder().encode(payload).length;
+      this.currentBatchSize += payloadSize + (i < this.batchQueue.length - 1 ? this.batchSendDelimiter.length : 0);
+    }
+    try {
+      await this.sendBatch(batch);
+    } catch (error) {
+      if (this.onError) {
+        this.onError(error);
+      }
+    } finally {
+      this.isProcessingBatch = false;
+      if (this.batchQueue.length > 0) {
+        this.processBatch();
+      }
+    }
+  }
+  /**
+   * Sends a batch of payloads to the HTTP endpoint.
+   */
+  async sendBatch(batch) {
+    let batchPayload;
+    switch (this.batchMode) {
+      case "array": {
+        const batchEntries = batch.map((payload) => JSON.parse(payload));
+        batchPayload = JSON.stringify(batchEntries);
+        break;
+      }
+      case "field": {
+        const fieldEntries = batch.map((payload) => JSON.parse(payload));
+        const batchObject = this.batchFieldName ? { [this.batchFieldName]: fieldEntries } : {};
+        batchPayload = JSON.stringify(batchObject);
+        break;
+      }
+      default: {
+        batchPayload = batch.join(this.batchSendDelimiter);
+        break;
+      }
+    }
+    await this.sendPayload(batchPayload, this.batchContentType);
+  }
+  /**
+   * Sends a single payload to the HTTP endpoint.
+   */
+  async sendPayload(payload, contentType) {
+    const headers = typeof this.headers === "function" ? this.headers() : { ...this.headers };
+    if (!headers["content-type"]) {
+      headers["content-type"] = contentType ?? this.contentType;
+    }
+    let finalPayload = payload;
+    if (this.compression && !this.edgeCompat) {
+      try {
+        finalPayload = await compressData(payload);
+        headers["content-encoding"] = "gzip";
+      } catch (error) {
+        if (this.onError) {
+          this.onError(new Error(`Compression failed: ${error}`));
+        }
+      }
+    }
+    await sendWithRetry(
+      this.url,
+      this.method,
+      headers,
+      finalPayload,
+      this.maxRetries,
+      this.retryDelay,
+      this.respectRateLimit,
+      this.onDebugRequestResponse,
+      this.onError
+    );
+  }
+}
+
+class HttpReporterEdgeLight extends AbstractHttpReporter {
+  /**
+   * Creates a new HTTP Reporter Edge Light instance.
+   * Edge compatibility mode is automatically enabled.
+   * @param options Configuration options for HTTP reporting
+   */
+  constructor(options) {
+    super({
+      ...options,
+      edgeCompat: true
+    });
+  }
+}
+
+export { HttpReporterEdgeLight as default };

package/dist/reporter/http/http-reporter.js

@@ -0,0 +1,13 @@
+import { AbstractHttpReporter } from './abstract-http-reporter.js';
+
+class HttpReporter extends AbstractHttpReporter {
+  /**
+   * Creates a new HTTP Reporter instance.
+   * @param options Configuration options for HTTP reporting
+   */
+  constructor(options) {
+    super(options);
+  }
+}
+
+export { HttpReporter as default };

package/dist/reporter/http/utils/compression.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Compresses data using gzip compression.
+ * @param data The data to compress as a string
+ * @returns A Promise that resolves to the compressed data as Uint8Array
+ */
+declare const compressData: (data: string) => Promise<Uint8Array>;
+export default compressData;