widelogger 0.2.1 → 0.4.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,15 +49,23 @@ 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
 // src/logger.ts
 import { widelogger } from "widelogger";
 
-export const { widelog, destroy } = widelogger({
+export const { context, destroy } = widelogger({
   service: "checkout-api",
   defaultEventName: "http_request",
 });
@@ -65,10 +73,11 @@ export const { widelog, destroy } = widelogger({
 
 ```ts
 // src/middleware/logging.ts
-import { widelog } from "../logger";
+import { widelog } from "widelogger";
+import { context } from "../logger";
 
 export const logging = (request, response, next) => {
-  widelog.context(
+  context(
     () =>
       new Promise((resolve) => {
         widelog.set("method", request.method);
@@ -90,17 +99,16 @@ export const logging = (request, response, next) => {
 
 ```ts
 // src/routes/checkout.ts
-import { widelog } from "../logger";
+import { widelog } from "widelogger";
 
-export const checkout = (request, response) => {
+export const checkout = async (request, response) => {
   const { userId } = request.body;
 
-  widelog.set("user.id", userId);
-  widelog.set("user.plan", "premium");
+  widelog.setFields({ user: { id: userId, plan: "premium" } });
 
-  widelog.time.start("db_ms");
-  const order = await processOrder(userId);
-  widelog.time.stop("db_ms");
+  const order = await widelog.time.measure("db_ms", () =>
+    processOrder(userId),
+  );
 
   widelog.set("order.total_cents", order.totalCents);
   widelog.count("order.items", order.itemCount);
@@ -109,7 +117,7 @@ export const checkout = (request, response) => {
 };
 ```
 
-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
 
@@ -119,7 +127,7 @@ The same pattern works with Bun's built-in server.
 // src/logger.ts
 import { widelogger } from "widelogger";
 
-export const { widelog, destroy } = widelogger({
+export const { context, destroy } = widelogger({
   service: "checkout-api",
   defaultEventName: "http_request",
 });
@@ -127,17 +135,16 @@ export const { widelog, destroy } = widelogger({
 
 ```ts
 // src/routes/checkout.ts
-import { widelog } from "../logger";
+import { widelog } from "widelogger";
 
 export const checkout = async (request: Request) => {
   const { userId } = await request.json();
 
-  widelog.set("user.id", userId);
-  widelog.set("user.plan", "premium");
+  widelog.setFields({ user: { id: userId, plan: "premium" } });
 
-  widelog.time.start("db_ms");
-  const order = await processOrder(userId);
-  widelog.time.stop("db_ms");
+  const order = await widelog.time.measure("db_ms", () =>
+    processOrder(userId),
+  );
 
   widelog.set("order.total_cents", order.totalCents);
   widelog.count("order.items", order.itemCount);
@@ -149,12 +156,13 @@ export const checkout = async (request: Request) => {
 ```ts
 // src/server.ts
 import { serve } from "bun";
-import { widelog } from "./logger";
+import { widelog } from "widelogger";
+import { context } from "./logger";
 import { checkout } from "./routes/checkout";
 
 serve({
   fetch: (request) =>
-    widelog.context(async () => {
+    context(async () => {
       const url = new URL(request.url);
       widelog.set("method", request.method);
       widelog.set("path", url.pathname);
@@ -192,6 +200,31 @@ widelog.set("user.plan", "premium");
 // Output: { user: { id: "usr_123", plan: "premium" } }
 ```
 
+### Bulk Fields
+
+`setFields` accepts a nested object and recursively flattens it into individual `set` calls. Non-primitive values (other than plain objects) are silently ignored.
+
+```ts
+widelog.setFields({
+  user: { id: "usr_123", plan: "premium" },
+  status_code: 200,
+});
+// Equivalent to:
+// widelog.set("user.id", "usr_123");
+// widelog.set("user.plan", "premium");
+// widelog.set("status_code", 200);
+```
+
+### Measured Timing
+
+`time.measure` wraps a sync or async callback, automatically recording start and stop times. It returns the callback's result and still records timing even if the callback throws.
+
+```ts
+const order = await widelog.time.measure("db_ms", () =>
+  processOrder(userId),
+);
+```
+
 ### Log Routing
 
 Events with `status_code >= 500` or `outcome === "error"` are emitted at `error` level. Everything else is `info`. In development, logs are pretty-printed; in production, they're structured JSON.
@@ -200,7 +233,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 |
 |--------|------|-------------|
@@ -212,18 +245,25 @@ 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) |
+| `setFields(fields)` | Recursively flatten a nested object into dotted-key `set` calls |
 | `count(key, amount?)` | Increment a counter (default +1) |
 | `append(key, value)` | Append a value to an array |
 | `max(key, value)` | Track the maximum value for a key |
 | `min(key, value)` | Track the minimum value for a key |
 | `time.start(key)` | Start a timer |
 | `time.stop(key)` | Stop a timer and record elapsed ms |
+| `time.measure(key, fn)` | Time a sync or async callback, returns the callback's result |
 | `errorFields(error, opts?)` | Extract error name, message, and stack |
 | `flush()` | Aggregate all operations and emit the event |
 

package/dist/index.d.ts

@@ -12,24 +12,29 @@ export interface ErrorFieldsOptions {
     prefix?: string;
     includeStack?: boolean;
 }
+declare function measure<K extends string, T>(key: DottedKey<K>, callback: () => Promise<T>): Promise<T>;
+declare function measure<K extends string, T>(key: DottedKey<K>, callback: () => T): T;
+export declare const widelog: {
+    set: <K extends string>(key: DottedKey<K>, value: FieldValue) => void;
+    setFields: (fields: Record<string, unknown>) => 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;
+        measure: typeof measure;
+    };
+    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;
+export {};

package/dist/index.js

@@ -115,6 +115,8 @@ var flush = (context) => {
 };
 
 // src/index.ts
+var isFieldValue = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 function getErrorFields(error, includeStack = true) {
   if (error instanceof Error) {
     return {
@@ -134,8 +136,112 @@ function getErrorFields(error, includeStack = true) {
     error_message: "Unknown error"
   };
 }
+var storage = new AsyncLocalStorage;
+function pushOp(operation) {
+  storage.getStore()?.operations.push(operation);
+}
+function applyFields(operations, fields, parentKey) {
+  for (const key of Object.keys(fields)) {
+    const value = fields[key];
+    const fullKey = parentKey ? `${parentKey}.${key}` : key;
+    if (isFieldValue(value)) {
+      operations.push({ operation: "set", key: fullKey, value });
+      continue;
+    }
+    if (isRecord2(value)) {
+      applyFields(operations, value, fullKey);
+    }
+  }
+}
+function measure(key, callback) {
+  const operations = storage.getStore()?.operations;
+  operations?.push({ operation: "time.start", key, time: performance.now() });
+  let result;
+  try {
+    result = callback();
+  } catch (error) {
+    operations?.push({ operation: "time.stop", key, time: performance.now() });
+    throw error;
+  }
+  if (result instanceof Promise) {
+    return result.finally(() => {
+      operations?.push({
+        operation: "time.stop",
+        key,
+        time: performance.now()
+      });
+    });
+  }
+  operations?.push({ operation: "time.stop", key, time: performance.now() });
+  return result;
+}
+var widelog = {
+  set: (key, value) => {
+    pushOp({ operation: "set", key, value });
+  },
+  setFields: (fields) => {
+    const operations = storage.getStore()?.operations;
+    if (operations) {
+      applyFields(operations, fields);
+    }
+  },
+  count: (key, amount = 1) => {
+    pushOp({ operation: "count", key, amount });
+  },
+  append: (key, value) => {
+    pushOp({ operation: "append", key, value });
+  },
+  max: (key, value) => {
+    pushOp({ operation: "max", key, value });
+  },
+  min: (key, value) => {
+    pushOp({ operation: "min", key, value });
+  },
+  time: {
+    start: (key) => {
+      pushOp({ operation: "time.start", key, time: performance.now() });
+    },
+    stop: (key) => {
+      pushOp({ operation: "time.stop", key, time: performance.now() });
+    },
+    measure
+  },
+  errorFields: (error, options = {}) => {
+    const context = storage.getStore();
+    if (!context) {
+      return;
+    }
+    const prefix = options.prefix ?? "error";
+    const fields = getErrorFields(error, options.includeStack ?? true);
+    context.operations.push({
+      operation: "set",
+      key: `${prefix}.error_name`,
+      value: fields.error_name
+    }, {
+      operation: "set",
+      key: `${prefix}.error_message`,
+      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 || store.operations.length === 0) {
+      return;
+    }
+    const event = flush(store);
+    store.transport(event);
+  }
+};
 var widelogger = (options) => {
-  const environment = options.environment ?? "development" ?? "development";
+  const nodeEnvironment = typeof process.env === "object" ? "development" : undefined;
+  const environment = options.environment ?? nodeEnvironment ?? "development";
   const isDevelopment = environment !== "production";
   const pinoTransport = isDevelopment ? pino.transport({
     target: "pino-pretty",
@@ -157,28 +263,25 @@ var widelogger = (options) => {
       environment
     }
   }, pinoTransport);
-  const storage = new AsyncLocalStorage;
+  const defaultEventName = options.defaultEventName;
   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 };
+    event.event_name = defaultEventName;
     if (isError) {
-      logger.error(payload);
+      logger.error(event);
       return;
     }
-    logger.info(payload);
+    logger.info(event);
   };
   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 +296,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 +304,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.1",
+  "version": "0.4.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": {