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

package/dist/middleware/shared/create-middleware-logger.d.ts

@@ -0,0 +1,82 @@
+import type { PailBrowserImpl } from "../../pail.d.ts";
+import type { DefaultLogTypes, LoggerFunction } from "../../types.d.ts";
+import type { WideEventFinishOptions } from "../../wide-event.d.ts";
+import { WideEvent } from "../../wide-event.d.ts";
+import type { RouteConfig } from "./routes.d.ts";
+/**
+ * A pail instance with dynamically generated log methods.
+ */
+type PailLike<T extends string = string> = PailBrowserImpl<T> & Record<DefaultLogTypes | T, LoggerFunction>;
+/**
+ * Base options shared by all framework middleware adapters.
+ * @template T - Custom logger type names from the pail instance
+ */
+export interface PailMiddlewareOptions<T extends string = string> {
+    /**
+     * Glob patterns for paths to exclude from logging.
+     * Exclusions take precedence over inclusions.
+     * @example ["/health", "/api/_internal/**"]
+     */
+    exclude?: string[];
+    /**
+     * Glob patterns for paths to include in logging.
+     * If not set, all non-excluded paths are logged.
+     * @example ["/api/**"]
+     */
+    include?: string[];
+    /**
+     * The pail logger instance to use for wide event emission.
+     */
+    pail: PailLike<T>;
+    /**
+     * Route-specific configuration. Maps glob patterns to config.
+     * First matching route wins.
+     * @example { "/api/auth/**": { service: "auth-service" } }
+     */
+    routes?: Record<string, RouteConfig>;
+    /**
+     * Default service name for all wide events.
+     * Can be overridden per-route via `routes`.
+     */
+    service?: string;
+}
+/**
+ * Result of creating a middleware logger for a request.
+ */
+export interface MiddlewareLoggerResult {
+    /**
+     * Finalize and emit the wide event. Sets status/error before emitting.
+     * Safe to call multiple times — only the first call emits.
+     */
+    finish: (options?: WideEventFinishOptions) => void;
+    /**
+     * The request-scoped WideEvent logger.
+     * Use `set()`, `info()`, `warn()`, `error()`, `debug()` to accumulate context.
+     */
+    logger: WideEvent;
+    /**
+     * Whether this request was skipped (excluded from logging).
+     * When true, `logger` and `finish` should not be used.
+     */
+    skipped: boolean;
+}
+/**
+ * Core factory function used by all framework middleware adapters.
+ *
+ * Creates a WideEvent for the given request, checks route inclusion/exclusion,
+ * resolves the service name, and returns a logger + finish callback.
+ * @param options Middleware options including pail instance and route config
+ * @param request Request metadata for the current HTTP request
+ * @param request.headers Safe headers extracted from the request
+ * @param request.method The HTTP method (GET, POST, etc.)
+ * @param request.path The URL path of the request
+ * @param request.requestId A unique identifier for this request
+ * @returns A result object with logger, finish callback, and skipped flag
+ */
+export declare const createMiddlewareLogger: <T extends string = string>(options: PailMiddlewareOptions<T>, request: {
+    headers?: Record<string, string>;
+    method: string;
+    path: string;
+    requestId: string;
+}) => MiddlewareLoggerResult;
+export {};

package/dist/middleware/shared/headers.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Extract safe headers from a Web API Headers object, filtering out
+ * sensitive headers like Authorization, Cookie, and API keys.
+ * @param headers Web API Headers object
+ * @returns Plain object of safe header key-value pairs
+ */
+export declare const extractSafeHeaders: (headers: Headers) => Record<string, string>;
+/**
+ * Extract safe headers from a Node.js IncomingHttpHeaders object,
+ * filtering out sensitive headers.
+ * @param headers Node.js IncomingHttpHeaders-like object
+ * @returns Plain object of safe header key-value pairs
+ */
+export declare const extractSafeNodeHeaders: (headers: Record<string, string | string[] | undefined>) => Record<string, string>;

package/dist/middleware/shared/routes.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Check if a path matches a glob pattern.
+ */
+export declare const matchesPattern: (path: string, pattern: string) => boolean;
+/**
+ * Route configuration for a specific path pattern.
+ */
+export interface RouteConfig {
+    /** Override the service name for requests matching this route. */
+    service?: string;
+}
+/**
+ * Determine whether a request path should be logged based on include/exclude patterns.
+ *
+ * - Exclusions take precedence over inclusions.
+ * - If no include patterns are provided, all non-excluded paths are logged.
+ * @param path The request path
+ * @param include Glob patterns of paths to include
+ * @param exclude Glob patterns of paths to exclude
+ * @returns Whether the path should be logged
+ */
+export declare const shouldLog: (path: string, include?: string[], exclude?: string[]) => boolean;
+/**
+ * Get the service name override for a given path based on route configuration.
+ * Returns the first matching route's service name, or undefined if no match.
+ * @param path The request path
+ * @param routes Route configuration map (pattern → config)
+ * @returns The service name override, or undefined
+ */
+export declare const getServiceForPath: (path: string, routes?: Record<string, RouteConfig>) => string | undefined;

package/dist/middleware/shared/storage.d.ts

@@ -0,0 +1,29 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { WideEvent } from "../../wide-event.d.ts";
+/**
+ * Create an isolated AsyncLocalStorage instance and a `useLogger` accessor
+ * for retrieving the request-scoped WideEvent from anywhere in the call stack.
+ *
+ * Each framework adapter should call this once at module level to get its own
+ * isolated storage instance.
+ * @param contextHint A description of the expected context, used in the
+ * error message when `useLogger` is called outside of a request scope.
+ * @returns An object with `storage` and `useLogger`
+ * @example
+ * ```typescript
+ * const { storage, useLogger } = createLoggerStorage(
+ *   "Express middleware context. Make sure evlog middleware is registered."
+ * );
+ *
+ * // In middleware:
+ * storage.run(wideEvent, () => next());
+ *
+ * // In handler:
+ * const log = useLogger();
+ * log.set({ user: { id: 1 } });
+ * ```
+ */
+export declare const createLoggerStorage: (contextHint: string) => {
+    storage: AsyncLocalStorage<WideEvent>;
+    useLogger: () => WideEvent;
+};

package/dist/middleware/sveltekit.d.ts

@@ -0,0 +1,123 @@
+import type { WideEvent } from "../wide-event.d.ts";
+import type { PailMiddlewareOptions } from "./shared/create-middleware-logger.d.ts";
+/**
+ * A SvelteKit-like event object with access to the pail logger via `locals.log`.
+ * @example
+ * ```typescript
+ * // In a SvelteKit load function or action:
+ * import type { PailSvelteKitEvent } from "@visulima/pail/middleware/sveltekit";
+ *
+ * export const load = async (event: PailSvelteKitEvent) => {
+ *   event.locals.log?.set({ user: { id: 1 } });
+ * };
+ * ```
+ */
+interface PailSvelteKitEvent {
+    [key: string]: unknown;
+    locals: Record<string, unknown> & {
+        log?: WideEvent;
+    };
+    request: Request;
+    url: URL;
+}
+/**
+ * Options passed to SvelteKit's resolve function.
+ */
+interface PailSvelteKitResolveOptions {
+    filterSerializedResponseHeaders?: (name: string) => boolean;
+    preload?: (input: {
+        type: string;
+    }) => boolean;
+    transformPageChunk?: (input: {
+        html: string;
+    }) => string;
+}
+/**
+ * SvelteKit resolve function type.
+ */
+type PailSvelteKitResolve = (event: PailSvelteKitEvent, options?: PailSvelteKitResolveOptions) => Promise<Response>;
+/**
+ * Input for the SvelteKit handle hook.
+ */
+interface PailSvelteKitHandleInput {
+    event: PailSvelteKitEvent;
+    resolve: PailSvelteKitResolve;
+}
+/**
+ * SvelteKit handle hook function type returned by `pailHandle()`.
+ */
+type PailSvelteKitHandle = (input: PailSvelteKitHandleInput) => Promise<Response>;
+/**
+ * Input for the SvelteKit handleError hook.
+ */
+interface PailSvelteKitHandleErrorInput {
+    error: unknown;
+    event: PailSvelteKitEvent;
+    message: string;
+    status: number;
+}
+/**
+ * SvelteKit handleError hook function type returned by `pailHandleError()`.
+ */
+type PailSvelteKitHandleError = (input: PailSvelteKitHandleErrorInput) => void;
+/**
+ * Retrieve the request-scoped WideEvent logger from AsyncLocalStorage.
+ * Must be called within a request handled by the pail SvelteKit handle hook.
+ * @returns The request-scoped WideEvent logger
+ * @throws Error if called outside of the hook context
+ */
+declare const useLogger: () => WideEvent;
+type SvelteKitHandleOptions<T extends string = string> = PailMiddlewareOptions<T>;
+/**
+ * Create a SvelteKit `handle` hook that attaches a WideEvent logger to each request.
+ *
+ * The logger is available via:
+ * - `event.locals.log` in server load functions and actions
+ * - `useLogger()` from anywhere in the async call stack
+ *
+ * The wide event is automatically emitted when the response is sent or an error occurs.
+ * @param options Hook configuration
+ * @returns SvelteKit handle hook function
+ * @example
+ * ```typescript
+ * // src/hooks.server.ts
+ * import { createPail } from "@visulima/pail";
+ * import { pailHandle, pailHandleError } from "@visulima/pail/middleware/sveltekit";
+ *
+ * const logger = createPail();
+ *
+ * export const handle = pailHandle({ pail: logger });
+ * export const handleError = pailHandleError();
+ * ```
+ */
+export declare const pailHandle: <T extends string = string>(options: SvelteKitHandleOptions<T>) => PailSvelteKitHandle;
+/**
+ * Create a SvelteKit `handleError` hook that captures errors into the WideEvent logger.
+ *
+ * Should be used alongside `pailHandle` to ensure errors are recorded in the wide event.
+ * @returns SvelteKit handleError hook function
+ */
+export declare const pailHandleError: () => PailSvelteKitHandleError;
+/**
+ * Convenience function that returns both handle and handleError hooks.
+ * @param options Hook configuration
+ * @returns Object with `handle` and `handleError` hooks
+ * @example
+ * ```typescript
+ * // src/hooks.server.ts
+ * import { createPail } from "@visulima/pail";
+ * import { createPailHooks } from "@visulima/pail/middleware/sveltekit";
+ *
+ * const logger = createPail();
+ * const { handle, handleError } = createPailHooks({ pail: logger });
+ *
+ * export { handle, handleError };
+ * ```
+ */
+export declare const createPailHooks: <T extends string = string>(options: SvelteKitHandleOptions<T>) => {
+    handle: PailSvelteKitHandle;
+    handleError: PailSvelteKitHandleError;
+};
+export { useLogger };
+export type { PailSvelteKitEvent, PailSvelteKitHandle, PailSvelteKitHandleError, PailSvelteKitHandleErrorInput, PailSvelteKitHandleInput, PailSvelteKitResolve, PailSvelteKitResolveOptions, SvelteKitHandleOptions, };
+export type { WideEvent } from "../wide-event.d.ts";

package/dist/middleware/sveltekit.js

@@ -0,0 +1,43 @@
+import { a as extractSafeHeaders, c as createMiddlewareLogger } from '../packem_shared/headers-Cp4uLtr4.js';
+import { c as createLoggerStorage } from '../packem_shared/storage-D0vqz8OX.js';
+
+const loggerStorage = createLoggerStorage("SvelteKit handle hook context. Make sure pailHandle is added to your hooks.server.ts.");
+const useLogger = () => loggerStorage.useLogger();
+const pailHandle = (options) => async ({ event, resolve }) => {
+  const requestId = event.request.headers.get("x-request-id") ?? crypto.randomUUID();
+  const safeHeaders = extractSafeHeaders(event.request.headers);
+  const { finish, logger, skipped } = createMiddlewareLogger(options, {
+    headers: safeHeaders,
+    method: event.request.method,
+    path: event.url.pathname,
+    requestId
+  });
+  if (skipped) {
+    return resolve(event);
+  }
+  event.locals.log = logger;
+  return loggerStorage.storage.run(logger, async () => {
+    try {
+      const response = await resolve(event);
+      finish({ status: response.status });
+      return response;
+    } catch (error) {
+      finish({ error: error instanceof Error ? error : new Error(String(error)) });
+      throw error;
+    }
+  });
+};
+const pailHandleError = () => ({ error, event }) => {
+  const logger = event.locals.log;
+  if (logger && error instanceof Error) {
+    logger.error(error.message, error);
+  }
+};
+const createPailHooks = (options) => {
+  return {
+    handle: pailHandle(options),
+    handleError: pailHandleError()
+  };
+};
+
+export { createPailHooks, pailHandle, pailHandleError, useLogger };

package/dist/packem_shared/{AbstractJsonReporter-DWRpTtGw.js → AbstractJsonReporter-CGKHS8_M.js}

@@ -12,7 +12,7 @@ const ErrorProto = Object.create(
   {},
   {
     cause: {
-      enumerable: true,
+      enumerable: false,
       value: void 0,
       writable: true
     },
@@ -22,32 +22,55 @@ const ErrorProto = Object.create(
       writable: true
     },
     errors: {
-      enumerable: true,
+      enumerable: false,
       value: void 0,
       writable: true
     },
     message: {
-      enumerable: true,
+      enumerable: false,
       value: void 0,
       writable: true
     },
     name: {
-      enumerable: true,
+      enumerable: false,
       value: void 0,
       writable: true
     },
     stack: {
-      enumerable: true,
+      enumerable: false,
       value: void 0,
       writable: true
     }
   }
 );
 const toJsonWasCalled = /* @__PURE__ */ new WeakSet();
+const makePropertiesEnumerable = (object) => {
+  if (!object || typeof object !== "object") {
+    return;
+  }
+  const props = Object.getOwnPropertyNames(object);
+  for (const prop of props) {
+    const descriptor = Object.getOwnPropertyDescriptor(object, prop);
+    if (descriptor) {
+      if (!descriptor.enumerable) {
+        Object.defineProperty(object, prop, {
+          ...descriptor,
+          enumerable: true
+        });
+      }
+      if (descriptor.value && typeof descriptor.value === "object" && !Array.isArray(descriptor.value) && (Object.getPrototypeOf(descriptor.value) === Object.prototype || Object.getPrototypeOf(descriptor.value) === null)) {
+        makePropertiesEnumerable(descriptor.value);
+      }
+    }
+  }
+};
 const toJSON = (from) => {
   toJsonWasCalled.add(from);
   const json = from.toJSON();
   toJsonWasCalled.delete(from);
+  if (json && typeof json === "object" && Object.isExtensible(json)) {
+    makePropertiesEnumerable(json);
+  }
   return json;
 };
 const serializeValue = (value, seen, depth, options) => {
@@ -58,7 +81,7 @@ const serializeValue = (value, seen, depth, options) => {
     return "[object Stream]";
   }
   if (value instanceof Error) {
-    if (seen.includes(value)) {
+    if (seen.has(value)) {
       return "[Circular]";
     }
     depth += 1;
@@ -73,11 +96,14 @@ const serializeValue = (value, seen, depth, options) => {
   if (typeof value === "function") {
     return `[Function: ${value.name || "anonymous"}]`;
   }
+  if (typeof value === "bigint") {
+    return `${value}n`;
+  }
   if (isPlainObject(value)) {
-    depth += 1;
-    if (options.maxDepth && depth >= options.maxDepth) {
+    if (options.maxDepth !== void 0 && options.maxDepth !== Number.POSITIVE_INFINITY && depth + 1 >= options.maxDepth) {
       return {};
     }
+    depth += 1;
     const plainObject = {};
     for (const key in value) {
       plainObject[key] = serializeValue(value[key], seen, depth, options);
@@ -91,7 +117,7 @@ const serializeValue = (value, seen, depth, options) => {
   }
 };
 const _serialize = (error, options, seen, depth) => {
-  seen.push(error);
+  seen.add(error);
   if (options.maxDepth === 0) {
     return {};
   }
@@ -99,31 +125,87 @@ const _serialize = (error, options, seen, depth) => {
     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;
+  Object.defineProperty(protoError, "name", {
+    configurable: true,
+    enumerable: true,
+    value: Object.prototype.toString.call(error.constructor) === "[object Function]" ? error.constructor.name : error.name,
+    writable: true
+  });
+  Object.defineProperty(protoError, "message", {
+    configurable: true,
+    enumerable: true,
+    value: error.message,
+    writable: true
+  });
+  Object.defineProperty(protoError, "stack", {
+    configurable: true,
+    enumerable: true,
+    value: error.stack,
+    writable: true
+  });
   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 = [];
+      if (seen.has(aggregateError)) {
+        Object.defineProperty(protoError, "errors", {
+          configurable: true,
+          enumerable: true,
+          value: [],
+          writable: true
+        });
         return protoError;
       }
       aggregateErrors.push(_serialize(aggregateError, options, seen, depth));
     }
-    protoError.errors = aggregateErrors;
+    Object.defineProperty(protoError, "errors", {
+      configurable: true,
+      enumerable: true,
+      value: aggregateErrors,
+      writable: true
+    });
   }
-  if (error.cause instanceof Error && !seen.includes(error.cause)) {
-    protoError.cause = _serialize(error.cause, options, seen, depth);
+  if (error.cause !== void 0 && error.cause !== null) {
+    if (error.cause instanceof Error) {
+      if (seen.has(error.cause)) {
+        Object.defineProperty(protoError, "cause", {
+          configurable: true,
+          enumerable: true,
+          value: "[Circular]",
+          writable: true
+        });
+      } else {
+        Object.defineProperty(protoError, "cause", {
+          configurable: true,
+          enumerable: true,
+          value: _serialize(error.cause, options, seen, depth),
+          writable: true
+        });
+      }
+    } else {
+      const serializedCause = serializeValue(error.cause, seen, depth, options);
+      Object.defineProperty(protoError, "cause", {
+        configurable: true,
+        enumerable: true,
+        value: serializedCause,
+        writable: true
+      });
+    }
   }
   for (const key in error) {
-    if (protoError[key] === void 0) {
-      const value = error[key];
-      protoError[key] = serializeValue(value, seen, depth, options);
+    if (key === "name" || key === "message" || key === "stack" || key === "cause" || key === "errors") {
+      continue;
     }
+    const value = error[key];
+    const serializedValue = serializeValue(value, seen, depth, options);
+    Object.defineProperty(protoError, key, {
+      configurable: true,
+      enumerable: true,
+      value: serializedValue,
+      writable: true
+    });
   }
   if (Array.isArray(options.exclude) && options.exclude.length > 0) {
     for (const key of options.exclude) {
@@ -142,7 +224,7 @@ const serialize = (error, options = {}) => _serialize(
     maxDepth: options.maxDepth ?? Number.POSITIVE_INFINITY,
     useToJSON: options.useToJSON ?? false
   },
-  [],
+  /* @__PURE__ */ new Set(),
   0
 );