widelogger 0.2.0 → 0.3.0

package/README.md

@@ -41,7 +41,7 @@ npm install widelogger
 ```ts
 import { widelogger } from "widelogger";
 
-const { widelog, destroy } = widelogger({
+const { context, destroy } = widelogger({
   service: "checkout-api",
   defaultEventName: "http_request",
   version: "1.0.0",
@@ -49,116 +49,129 @@ const { widelog, destroy } = widelogger({
 });
 ```
 
+`widelogger()` returns a `context` function to wrap request lifecycles and a `destroy` function for graceful shutdown. To log fields, import `widelog` directly from the package — it works anywhere inside a `context()` call thanks to `AsyncLocalStorage`.
+
+```ts
+import { widelog } from "widelogger";
+
+widelog.set("user.id", userId);
+```
+
 ### Express
 
-Create a shared logger instance, use middleware to wrap requests in a context, and accumulate fields from anywhere in your codebase.
+Create a logger instance once, use middleware to wrap requests in a context, and accumulate fields from anywhere in your codebase by importing `widelog` directly.
 
 ```ts
-// lib/logger.ts
+// src/logger.ts
 import { widelogger } from "widelogger";
 
-const { widelog, destroy } = widelogger({
+export const { context, destroy } = widelogger({
   service: "checkout-api",
   defaultEventName: "http_request",
 });
-
-export { widelog, destroy };
 ```
 
 ```ts
-// middleware/logging.ts
-import { widelog } from "../lib/logger";
-
-export const loggingMiddleware = (req, res, next) => {
-  widelog.context(() => {
-    widelog.set("method", req.method);
-    widelog.set("path", req.path);
-    widelog.time.start("duration_ms");
-
-    res.on("finish", () => {
-      widelog.set("status_code", res.statusCode);
-      widelog.time.stop("duration_ms");
-      widelog.flush();
-    });
-
-    next();
-  });
+// src/middleware/logging.ts
+import { widelog } from "widelogger";
+import { context } from "../logger";
+
+export const logging = (request, response, next) => {
+  context(
+    () =>
+      new Promise((resolve) => {
+        widelog.set("method", request.method);
+        widelog.set("path", request.path);
+        widelog.time.start("duration_ms");
+
+        response.on("finish", () => {
+          widelog.set("status_code", response.statusCode);
+          widelog.time.stop("duration_ms");
+          widelog.flush();
+          resolve();
+        });
+
+        next();
+      }),
+  );
 };
 ```
 
 ```ts
-// routes/checkout.ts
-import { widelog } from "../lib/logger";
-
-export const checkout = async (req, res) => {
-  const user = await getUser(req.userId);
-  widelog.set("user.id", user.id);
-  widelog.set("user.plan", user.plan);
-
-  try {
-    const order = await processOrder(user);
-    widelog.set("order.total_cents", order.totalCents);
-    widelog.count("order.items", order.items.length);
-    widelog.set("outcome", "success");
-    res.json({ orderId: order.id });
-  } catch (error) {
-    widelog.set("outcome", "error");
-    widelog.errorFields(error);
-    res.status(500).json({ error: "checkout failed" });
-  }
+// src/routes/checkout.ts
+import { widelog } from "widelogger";
+
+export const checkout = async (request, response) => {
+  const { userId } = request.body;
+
+  widelog.set("user.id", userId);
+  widelog.set("user.plan", "premium");
+
+  widelog.time.start("db_ms");
+  const order = await processOrder(userId);
+  widelog.time.stop("db_ms");
+
+  widelog.set("order.total_cents", order.totalCents);
+  widelog.count("order.items", order.itemCount);
+
+  response.json({ orderId: order.id });
 };
 ```
 
-The handler doesn't need to know about context setup or flushing — it just imports `widelog` and adds fields. `AsyncLocalStorage` ensures concurrent requests never leak into each other.
+The handler doesn't need to know about context setup or flushing — it just imports `widelog` from the package and adds fields. `AsyncLocalStorage` ensures concurrent requests never leak into each other.
 
 ### Bun
 
 The same pattern works with Bun's built-in server.
 
 ```ts
-// lib/logger.ts
+// src/logger.ts
 import { widelogger } from "widelogger";
 
-const { widelog, destroy } = widelogger({
+export const { context, destroy } = widelogger({
   service: "checkout-api",
   defaultEventName: "http_request",
 });
-
-export { widelog, destroy };
 ```
 
 ```ts
-// routes/checkout.ts
-import { widelog } from "../lib/logger";
+// src/routes/checkout.ts
+import { widelog } from "widelogger";
+
+export const checkout = async (request: Request) => {
+  const { userId } = await request.json();
 
-export const checkout = async (req: Request) => {
-  const user = await getUser(req);
-  widelog.set("user.id", user.id);
-  widelog.set("user.plan", user.plan);
+  widelog.set("user.id", userId);
+  widelog.set("user.plan", "premium");
+
+  widelog.time.start("db_ms");
+  const order = await processOrder(userId);
+  widelog.time.stop("db_ms");
 
-  const order = await processOrder(user);
   widelog.set("order.total_cents", order.totalCents);
-  widelog.count("order.items", order.items.length);
+  widelog.count("order.items", order.itemCount);
 
   return Response.json({ orderId: order.id });
 };
 ```
 
 ```ts
-// server.ts
-import { widelog } from "./lib/logger";
+// src/server.ts
+import { serve } from "bun";
+import { widelog } from "widelogger";
+import { context } from "./logger";
 import { checkout } from "./routes/checkout";
 
-Bun.serve({
-  fetch: (req) =>
-    widelog.context(async () => {
-      const url = new URL(req.url);
-      widelog.set("method", req.method);
+serve({
+  fetch: (request) =>
+    context(async () => {
+      const url = new URL(request.url);
+      widelog.set("method", request.method);
       widelog.set("path", url.pathname);
       widelog.time.start("duration_ms");
 
       try {
-        const response = await checkout(req);
+        const response = await checkout(request);
         widelog.set("status_code", response.status);
         widelog.set("outcome", "success");
         return response;
@@ -197,7 +210,7 @@ Events with `status_code >= 500` or `outcome === "error"` are emitted at `error`
 
 ### `widelogger(options)`
 
-Creates a logger instance. Returns `{ widelog, destroy }`.
+Creates a logger instance. Returns `{ context, destroy }`.
 
 | Option | Type | Description |
 |--------|------|-------------|
@@ -209,11 +222,16 @@ Creates a logger instance. Returns `{ widelog, destroy }`.
 | `environment` | `string` | Environment name (defaults to `NODE_ENV`) |
 | `level` | `string` | Log level (defaults to `LOG_LEVEL` env or `"info"`) |
 
+### `context(fn)`
+
+Run a function inside an isolated async context. All `widelog` calls within this function (and any functions it calls) are scoped to this context. Supports both sync and async callbacks.
+
 ### `widelog`
 
+Imported directly from `"widelogger"`. All methods operate on the current async context established by `context()`.
+
 | Method | Description |
 |--------|-------------|
-| `context(fn)` | Run a function in an isolated async context |
 | `set(key, value)` | Set a field value (last write wins) |
 | `count(key, amount?)` | Increment a counter (default +1) |
 | `append(key, value)` | Append a value to an array |

package/dist/index.d.ts

@@ -12,24 +12,24 @@ export interface ErrorFieldsOptions {
     prefix?: string;
     includeStack?: boolean;
 }
+export declare const widelog: {
+    set: <K extends string>(key: DottedKey<K>, value: FieldValue) => void;
+    count: <K extends string>(key: DottedKey<K>, amount?: number) => void;
+    append: <K extends string>(key: DottedKey<K>, value: FieldValue) => void;
+    max: <K extends string>(key: DottedKey<K>, value: number) => void;
+    min: <K extends string>(key: DottedKey<K>, value: number) => void;
+    time: {
+        start: <K extends string>(key: DottedKey<K>) => void;
+        stop: <K extends string>(key: DottedKey<K>) => void;
+    };
+    errorFields: (error: unknown, options?: ErrorFieldsOptions) => void;
+    flush: () => void;
+};
 export declare const widelogger: (options: WideloggerOptions) => {
-    widelog: {
-        set: <K extends string>(key: DottedKey<K>, value: FieldValue) => void;
-        count: <K extends string>(key: DottedKey<K>, amount?: number) => void;
-        append: <K extends string>(key: DottedKey<K>, value: FieldValue) => void;
-        max: <K extends string>(key: DottedKey<K>, value: number) => void;
-        min: <K extends string>(key: DottedKey<K>, value: number) => void;
-        time: {
-            start: <K extends string>(key: DottedKey<K>) => void;
-            stop: <K extends string>(key: DottedKey<K>) => void;
-        };
-        errorFields: (error: unknown, options?: ErrorFieldsOptions) => void;
-        flush: () => void;
-        context: {
-            <T>(callback: () => Promise<T>): Promise<T>;
-            <T>(callback: () => T): T;
-        };
+    context: {
+        <T>(callback: () => Promise<T>): Promise<T>;
+        <T>(callback: () => T): T;
     };
     destroy: () => Promise<void>;
 };
-export type Widelog = ReturnType<typeof widelogger>["widelog"];
+export type Widelog = typeof widelog;

package/dist/index.js

@@ -134,6 +134,69 @@ function getErrorFields(error, includeStack = true) {
     error_message: "Unknown error"
   };
 }
+var storage = new AsyncLocalStorage;
+var widelog = {
+  set: (key, value) => {
+    storage.getStore()?.operations.push({ operation: "set", key, value });
+  },
+  count: (key, amount = 1) => {
+    storage.getStore()?.operations.push({ operation: "count", key, amount });
+  },
+  append: (key, value) => {
+    storage.getStore()?.operations.push({ operation: "append", key, value });
+  },
+  max: (key, value) => {
+    storage.getStore()?.operations.push({ operation: "max", key, value });
+  },
+  min: (key, value) => {
+    storage.getStore()?.operations.push({ operation: "min", key, value });
+  },
+  time: {
+    start: (key) => {
+      storage.getStore()?.operations.push({
+        operation: "time.start",
+        key,
+        time: performance.now()
+      });
+    },
+    stop: (key) => {
+      storage.getStore()?.operations.push({
+        operation: "time.stop",
+        key,
+        time: performance.now()
+      });
+    }
+  },
+  errorFields: (error, options = {}) => {
+    const context = storage.getStore();
+    if (!context) {
+      return;
+    }
+    const prefix = options.prefix ?? "error";
+    const fields = getErrorFields(error, options.includeStack ?? true);
+    const nameKey = `${prefix}.error_name`;
+    const messageKey = `${prefix}.error_message`;
+    context.operations.push({ operation: "set", key: nameKey, value: fields.error_name }, { operation: "set", key: messageKey, value: fields.error_message });
+    if (fields.error_stack !== undefined) {
+      context.operations.push({
+        operation: "set",
+        key: `${prefix}.error_stack`,
+        value: fields.error_stack
+      });
+    }
+  },
+  flush: () => {
+    const store = storage.getStore();
+    if (!store) {
+      return;
+    }
+    const event = flush(store);
+    if (Object.keys(event).length === 0) {
+      return;
+    }
+    store.transport(event);
+  }
+};
 var widelogger = (options) => {
   const environment = options.environment ?? "development" ?? "development";
   const isDevelopment = environment !== "production";
@@ -157,11 +220,7 @@ var widelogger = (options) => {
       environment
     }
   }, pinoTransport);
-  const storage = new AsyncLocalStorage;
   const transport = (event) => {
-    if (Object.keys(event).length === 0) {
-      return;
-    }
     const statusCode = typeof event.status_code === "number" ? event.status_code : undefined;
     const isError = statusCode !== undefined ? statusCode >= 500 : event.outcome === "error";
     const payload = { event_name: options.defaultEventName, ...event };
@@ -172,13 +231,13 @@ var widelogger = (options) => {
     logger.info(payload);
   };
   const clearContext = () => {
-    const context = storage.getStore();
-    if (context && context.operations.length > 0) {
-      context.operations = [];
+    const context2 = storage.getStore();
+    if (context2 && context2.operations.length > 0) {
+      context2.operations = [];
     }
   };
-  function runContext(callback) {
-    return storage.run({ operations: [] }, () => {
+  function context(callback) {
+    return storage.run({ operations: [], transport }, () => {
       let result;
       try {
         result = callback();
@@ -193,62 +252,6 @@ var widelogger = (options) => {
       return result;
     });
   }
-  const widelog = {
-    set: (key, value) => {
-      storage.getStore()?.operations.push({ operation: "set", key, value });
-    },
-    count: (key, amount = 1) => {
-      storage.getStore()?.operations.push({ operation: "count", key, amount });
-    },
-    append: (key, value) => {
-      storage.getStore()?.operations.push({ operation: "append", key, value });
-    },
-    max: (key, value) => {
-      storage.getStore()?.operations.push({ operation: "max", key, value });
-    },
-    min: (key, value) => {
-      storage.getStore()?.operations.push({ operation: "min", key, value });
-    },
-    time: {
-      start: (key) => {
-        storage.getStore()?.operations.push({
-          operation: "time.start",
-          key,
-          time: performance.now()
-        });
-      },
-      stop: (key) => {
-        storage.getStore()?.operations.push({
-          operation: "time.stop",
-          key,
-          time: performance.now()
-        });
-      }
-    },
-    errorFields: (error, options2 = {}) => {
-      const context = storage.getStore();
-      if (!context) {
-        return;
-      }
-      const prefix = options2.prefix ?? "error";
-      const fields = getErrorFields(error, options2.includeStack ?? true);
-      const nameKey = `${prefix}.error_name`;
-      const messageKey = `${prefix}.error_message`;
-      context.operations.push({ operation: "set", key: nameKey, value: fields.error_name }, { operation: "set", key: messageKey, value: fields.error_message });
-      if (fields.error_stack !== undefined) {
-        context.operations.push({
-          operation: "set",
-          key: `${prefix}.error_stack`,
-          value: fields.error_stack
-        });
-      }
-    },
-    flush: () => {
-      const event = flush(storage.getStore());
-      transport(event);
-    },
-    context: runContext
-  };
   const destroy = async () => {
     await new Promise((resolve) => {
       logger.flush(() => resolve());
@@ -257,8 +260,9 @@ var widelogger = (options) => {
       pinoTransport.end();
     }
   };
-  return { widelog, destroy };
+  return { context, destroy };
 };
 export {
-  widelogger
+  widelogger,
+  widelog
 };

package/dist/types.d.ts

@@ -36,5 +36,6 @@ export type Operation = {
 };
 export interface Context {
     operations: Operation[];
+    transport: (event: Record<string, unknown>) => void;
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "widelogger",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -9,7 +9,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
   "repository": {