@polygonlabs/logger 0.0.0-0 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createLogger } from './logger.ts';
+export type { AppLogger, CreateLoggerOptions, SentryAdapter } from './logger.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,SAAS,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createLogger } from "./logger.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,74 @@
+import type { Bindings, ChildLoggerOptions, DestinationStream, Logger } from 'pino';
+/**
+ * Duck-typed interface for Sentry error capturing. Matches the surface of
+ * @sentry/node used by logError. Pass an initialised Sentry client to
+ * createLogger to activate automatic error capture alongside pino logging.
+ */
+export interface SentryAdapter {
+    captureException(err: unknown): void;
+    captureMessage(msg: string, level: string): void;
+}
+/**
+ * pino Logger extended with logError and a narrowed child() return type.
+ *
+ * logError is a VError/WError-aware error logging helper: use it in preference
+ * to logger.error() for caught exceptions so that VError info fields are emitted
+ * as discrete structured fields and WError cause chains are fully unwound into
+ * separate log entries.
+ *
+ * child() is overridden to return AppLogger so child loggers inherit logError
+ * and the override is preserved at any depth.
+ *
+ * Inject this type throughout your service rather than importing a module-level
+ * singleton. Construct once at the entry point and pass down via constructor
+ * arguments or function parameters.
+ */
+export type AppLogger = Omit<Logger, 'child'> & {
+    /**
+     * Log an error at `error` level. Mirrors pino's merge-object signature with
+     * `err` as a required key:
+     *
+     *   logger.logError({ err })
+     *   logger.logError({ err, requestId, userId }, 'optional message override')
+     *
+     * VError `info` fields from the full cause chain are spread into the log entry
+     * alongside any call-site context. Call-site context wins on key collision.
+     * WError wrappers are skipped — only the cause is logged.
+     */
+    /**
+     * Log an error at `error` level. Mirrors pino's merge-object signature with
+     * `err` as a required key:
+     *
+     *   logger.logError({ err })
+     *   logger.logError({ err, requestId, userId }, 'optional message override')
+     *
+     * VError `info` from the full cause chain is always emitted under the `error_info`
+     * key — never spread at the top level. This means `error_info` is a reserved key:
+     * passing it in the context object is a TypeScript error.
+     *
+     * `err` must be an `Error` instance. For non-Error caught values, narrow first or
+     * use `logger.error()` directly.
+     */
+    logError(obj: {
+        err: Error;
+        error_info?: never;
+    } & Record<string, unknown>, message?: string): void;
+    child(bindings: Bindings, options?: ChildLoggerOptions): AppLogger;
+};
+export interface CreateLoggerOptions {
+    /** Enable pino-pretty output for development. Requires pino-pretty to be installed. */
+    pretty?: boolean;
+    /**
+     * Custom pino destination stream. When provided, takes precedence over `pretty`.
+     * Intended for use in tests to capture log output.
+     */
+    destination?: DestinationStream;
+    /**
+     * Optional Sentry adapter for automatic error capturing in logError.
+     * Pass your initialised @sentry/node instance (or any object satisfying
+     * SentryAdapter). Propagated automatically to all child loggers.
+     */
+    sentry?: SentryAdapter;
+}
+export declare function createLogger(options?: CreateLoggerOptions): Promise<AppLogger>;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAMnG;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IACrC,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAClD;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC9C;;;;;;;;;;OAUG;IACH;;;;;;;;;;;;;OAaG;IACH,QAAQ,CACN,GAAG,EAAE;QAAE,GAAG,EAAE,KAAK,CAAC;QAAC,UAAU,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,OAAO,CAAC,EAAE,MAAM,GACf,IAAI,CAAC;IACR,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;CACpE,CAAC;AAEF,MAAM,WAAW,mBAAmB;IAClC,uFAAuF;IACvF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAmCD,wBAAsB,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,SAAS,CAAC,CA2FpF"}

package/dist/logger.js

@@ -0,0 +1,98 @@
+import { pino, stdSerializers } from 'pino';
+import { VError, WError } from '@polygonlabs/verror';
+function logError(logger, obj, message, sentry) {
+    const { err, ...context } = obj;
+    // WError is a wrapper whose own message is intentionally not the useful signal —
+    // the cause is. Skip the WError itself and recurse directly into its cause.
+    // Carry call-site context through; discard the developer's message override since
+    // it described the wrapper, not the cause.
+    if (err instanceof WError) {
+        const cause = VError.cause(err);
+        // The spread of context (Record<string, unknown>) widens err back to unknown;
+        // cast is safe because cause is narrowed to Error by the if-guard above.
+        if (cause)
+            logError(logger, { err: cause, ...context }, undefined, sentry);
+        return;
+    }
+    // info from the full cause chain is spread first so call-site context wins on collision.
+    const info = err instanceof VError ? VError.info(err) : {};
+    const infoEntry = Object.keys(info).length > 0 ? { error_info: info } : {};
+    logger.error({ err, ...context, ...infoEntry }, message ?? err.message);
+    sentry?.captureException(err);
+}
+export async function createLogger(options) {
+    // ref.self is assigned immediately after pino() returns. The formatters.log
+    // closure only fires when a log method is called — never during construction —
+    // so ref.self is always defined by the time the closure executes.
+    const ref = { self: undefined };
+    const pinoOptions = {
+        level: 'debug',
+        // Rename pino's default "msg" key to "message" for Datadog ingestion.
+        messageKey: 'message',
+        // Suppress pino's default pid and hostname fields.
+        base: undefined,
+        // Write ISO 8601 as "timestamp" — Datadog's expected field name.
+        // pino's default is Unix epoch under "time". The leading comma is required
+        // because pino appends this fragment directly onto the partially-constructed
+        // JSON string.
+        timestamp: () => `,"timestamp":"${new Date().toISOString()}"`,
+        formatters: {
+            // Emit string level labels ("info") instead of numeric values (30).
+            level(label) {
+                return { level: label };
+            },
+            // Detect a caller-supplied "timestamp" key and rename it so it cannot
+            // shadow the authoritative timestamp written by the timestamp function.
+            log(object) {
+                if ('timestamp' in object) {
+                    const { timestamp, ...rest } = object;
+                    ref.self?.warn({ callerTimestamp: timestamp }, 'Log call included "timestamp" in merge object — reserved key renamed to callerTimestamp. Fix the call site.');
+                    return { callerTimestamp: timestamp, ...rest };
+                }
+                return object;
+            }
+        },
+        serializers: {
+            err: stdSerializers.err
+        }
+    };
+    let destination = options?.destination;
+    if (!destination && options?.pretty) {
+        destination = (await import('pino-pretty')).default({
+            colorize: true,
+            timestampKey: 'timestamp',
+            translateTime: 'SYS:standard',
+            ignore: 'pid,hostname',
+            sync: true
+        });
+    }
+    const base = destination ? pino(pinoOptions, destination) : pino(pinoOptions);
+    // Capture child from Logger.prototype directly rather than from the instance, so we
+    // hold a reference to the prototype method that cannot be shadowed by an own property.
+    // We call it with .call(target) where target is the raw pino instance (never the Proxy),
+    // so pino's child creation runs with a clean `this` and produces a raw child whose
+    // prototype chain is pure pino. We then wrap that child in a new Proxy via enrichLogger.
+    const pinoProtoChild = Object.getPrototypeOf(base).child;
+    function enrichLogger(instance) {
+        // Wrap in a Proxy rather than mutating the pino logger instance. Mutation would
+        // make logError and child OWN properties on the pino object, which become visible
+        // in descendant loggers via their prototype chain (pino creates children with
+        // Object.create(parent)). A Proxy intercepts only the two properties we care about
+        // and passes everything else through to the original logger untouched.
+        return new Proxy(instance, {
+            get(target, prop, receiver) {
+                if (prop === 'logError') {
+                    return (obj, message) => logError(target, obj, message, options?.sentry);
+                }
+                if (prop === 'child') {
+                    return (bindings, childOptions) => enrichLogger(pinoProtoChild.call(target, bindings, childOptions));
+                }
+                return Reflect.get(target, prop, receiver);
+            }
+        });
+    }
+    const logger = enrichLogger(base);
+    ref.self = logger;
+    return logger;
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@polygonlabs/logger",
-  "version": "0.0.0-0",
+  "version": "0.2.0",
   "description": "Pino-based logger with Sentry integration, configured for Datadog ingestion and prettified output capable.",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/0xPolygon/apps-team-packages.git",
+    "directory": "packages/logger"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -12,10 +17,12 @@
       "import": "./dist/index.js"
     }
   },
-  "files": [],
+  "files": [
+    "dist"
+  ],
   "dependencies": {
     "pino": "^10.3.1",
-    "@polygonlabs/verror": "0.0.0-0"
+    "@polygonlabs/verror": "0.2.0"
   },
   "devDependencies": {
     "@tsconfig/node-ts": "^23.0.0",