@stacksjs/logging 0.70.45 → 0.70.53

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -1,3 +1,32 @@
+/**
+ * Parse + validate `LOG_LEVEL` (stacksjs/stacks#1932). Previously the
+ * env value was cast `as any` straight into the logger, so a typo
+ * (`LOG_LEVEL=infoo`) silently produced undefined behavior. Now an
+ * unknown value warns once and falls back. Accepts `warn` as an alias
+ * for clarity's `warning`.
+ */
+export declare function parseLogLevel(raw: string | undefined, fallback?: LogLevel): LogLevel;
+/** Parse + validate `LOG_FORMAT`; defaults to json in prod, text in dev. */
+export declare function parseLogFormat(raw: string | undefined): LogFormat;
+/**
+ * Resolve the effective logger settings with precedence
+ * **env var > config file > default** (stacksjs/stacks#1935). Pure +
+ * exported so the precedence is unit-testable without booting the
+ * singleton logger.
+ */
+export declare function resolveLogSettings(input: {
+  envLevel?: string
+  envFormat?: string
+  cfgLevel?: string
+  cfgFormat?: string
+  cfgWriteToFile?: boolean
+  isProduction?: boolean
+}): ResolvedLogSettings;
+export declare function normalizeError(err: unknown, depth?: number): NormalizedError;
+/** Render a normalized error (+ its cause chain) to a printable string. */
+export declare function renderNormalizedError(n: NormalizedError): string;
+/** Apply {@link normalizeContextValue} to a structured log context. */
+export declare function normalizeContext(ctx: LogContext): LogContext;
 /**
  * Run a function with an attached log context (e.g., request ID).
  * Use in HTTP middleware to propagate context through the request lifecycle.
@@ -12,35 +41,87 @@ declare function getLogger(): Promise<Logger>;
 export declare function dump(...args: any[]): Promise<void>;
 export declare function dd(...args: any[]): Promise<never>;
 export declare function echo(...args: any[]): Promise<void>;
+/**
+ * Single error→log chokepoint (stacksjs/stacks#1933) — Laravel's
+ * `report()`. Every automatic error-logging path (router action catch,
+ * request catch, process-level handlers) funnels through here so the
+ * policy lives in one place:
+ *
+ *   - **4xx** (client errors — a thrown `HttpError(404)` / `422`) are
+ *     NOT reported at error level; they're expected control flow, not
+ *     server faults. Logged at debug so they stay traceable without
+ *     spamming the error stream.
+ *   - **5xx** and any non-HTTP throw are always reported at `error`
+ *     with the full normalized stack + cause chain + request context.
+ *
+ * Fire-and-forget by design (callers are on a response / exit path);
+ * the write is queued through the shared logger so a flush-on-exit
+ * (stacksjs/stacks#1934) drains it.
+ */
+export declare function report(error: unknown, options?: ReportOptions): void;
 export declare const log: Log;
 export declare const struct: unknown;
 // Request context propagation for structured logging
-declare interface LogContext {
+export declare interface LogContext {
   requestId?: string
   userId?: string | number
   [key: string]: unknown
 }
+export declare interface ResolvedLogSettings {
+  level: LogLevel
+  format: LogFormat
+  writeToFile: boolean
+}
+/**
+ * Normalize any thrown value into a stable, serializable shape
+ * (stacksjs/stacks#1932). `JSON.stringify(new Error())` yields `{}`,
+ * dropping the stack/message — so historically `log.error('x', err)`
+ * lost the error entirely. This walks `.cause` (bounded) and always
+ * captures name/message/stack.
+ */
+export declare interface NormalizedError {
+  name: string
+  message: string
+  stack?: string
+  cause?: NormalizedError
+}
 export declare interface Log {
-  info: (...args: any[]) => Promise<void>
+  info: (...args: unknown[]) => Promise<void>
   success: (msg: string) => Promise<void>
-  error: (err: string | Error | object | unknown, options?: LogErrorOptions) => Promise<void>
-  warn: (arg: string, options?: Record<string, any>) => Promise<void>
+  error: (message: string | Error | unknown, error?: unknown, context?: LogContext) => Promise<void>
+  warn: (arg: string, context?: LogContext) => Promise<void>
   warning: (arg: string) => Promise<void>
-  debug: (...args: any[]) => Promise<void>
-  dump: (...args: any[]) => Promise<void>
-  dd: (...args: any[]) => Promise<void>
-  echo: (...args: any[]) => Promise<void>
-  time: (label: string) => (metadata?: Record<string, any>) => Promise<void>
+  debug: (...args: unknown[]) => Promise<void>
+  dump: (...args: unknown[]) => Promise<void>
+  dd: (...args: unknown[]) => Promise<void>
+  echo: (...args: unknown[]) => Promise<void>
+  time: (label: string) => (metadata?: LogContext) => Promise<void>
   syncWarn: (msg: string) => void
   syncError: (msg: string) => void
   fatal: (msg: string, exitCode?: number) => never
   flush: () => Promise<void>
 }
-export type ErrorMessage = string;
-export type LogErrorOptions = {
+/**
+ * @deprecated stacksjs/stacks#1932 — the old union form
+ * (`{…} | any | Error`) included `| any`, which collapsed the whole
+ * union and let `log.error(msg, anything)` type-check while silently
+ * dropping the error. Prefer `log.error(message, error?, context?)`.
+ * This explicit object shape is retained only for the legacy
+ * `{ shouldExit }` fatal path.
+ */
+export declare interface LogErrorOptions {
   shouldExit: boolean
   silent?: boolean
   message?: ErrorMessage
-} | any | Error;
+}
+export declare interface ReportOptions {
+  status?: number
+  context?: LogContext
+  label?: string
+}
+/** Valid log levels — mirrors `@stacksjs/clarity`'s `LogLevel`. */
+export type LogLevel = 'debug' | 'info' | 'success' | 'warning' | 'error';
+export type LogFormat = 'json' | 'text';
+export type ErrorMessage = string;
 // Export logger getter for debugging
 export { getLogger as logger };

package/dist/index.js

@@ -1,5 +1,8 @@
 // @bun
-var Z=import.meta.require;import{AsyncLocalStorage as $}from"async_hooks";import K from"process";import{Logger as Y}from"@stacksjs/clarity";import{handleError as A}from"@stacksjs/error-handling";import{ExitCode as W}from"@stacksjs/types";var U=null,T=null,X=new $;function v(z,B){return X.run(z,B)}function w(){return X.getStore()}async function F(){if(U)return;if(T)return T;return T=(async()=>{let z=K.env.LOG_FORMAT||(K.env.NODE_ENV==="production"?"json":"text");try{let B=await import("@stacksjs/path");U=new Y("stacks",{level:K.env.LOG_LEVEL||"info",logDirectory:B.projectPath("storage/logs"),showTags:!1,fancy:z!=="json",format:z,writeToFile:!0})}catch{U=new Y("stacks",{level:K.env.LOG_LEVEL||"info",logDirectory:"storage/logs",showTags:!1,fancy:z!=="json",format:z,writeToFile:!0})}})(),T}async function J(){return await F(),U}function N(...z){let B=z.map((G)=>typeof G==="object"?JSON.stringify(G,null,2):String(G)).join(" "),D=X.getStore();if(D?.requestId)return`[${D.requestId}] ${B}`;return B}var V={info:async(...z)=>{let B=N(...z);await(await J()).info(B)},success:async(z)=>{await(await J()).success(z)},warn:async(z,B)=>{await(await J()).warn(z,B)},warning:async(z)=>{await(await J()).warn(z)},error:async(z,B)=>{let D=!!B&&typeof B==="object"&&!(B instanceof Error)&&(("shouldExit"in B)||("silent"in B)||("message"in B)),G;if(typeof z==="string")G=z;else if(z instanceof Error)G=z.stack||z.message;else G=JSON.stringify(z);let H="";if(B!==void 0&&!D)if(B instanceof Error)H=B.stack||B.message;else if(typeof B==="string")H=B;else try{H=JSON.stringify(B)}catch{H=String(B)}let Q=H?`${G} ${H}`:G;if(await(await J()).error(Q),D&&B.shouldExit)A(z,B)},debug:async(...z)=>{let B=N(...z);await(await J()).debug(B)},dump:async(...z)=>{let B=N(...z);await(await J()).debug(`DUMP: ${B}`)},dd:async(...z)=>{let B=N(...z);await(await J()).error(B),K.exit(W.FatalError)},echo:async(...z)=>{let B=N(...z);await(await J()).info(`ECHO: ${B}`)},time:(z)=>{let B=performance.now();return async(D)=>{let G=performance.now()-B,H=await J(),Q=D?` ${JSON.stringify(D)}`:"";await H.info(`${z}: ${G.toFixed(2)}ms${Q}`)}},syncWarn:(z)=>{K.stderr.write(`${z}
-`)},syncError:(z)=>{K.stderr.write(`${z}
-`)},fatal:(z,B=W.FatalError)=>{K.stderr.write(`${z}
-`),K.exit(B)},flush:async()=>{if(!U&&!T)return;try{let z=await J(),B=z.flush;if(typeof B==="function")await B.call(z)}catch{}}};async function C(...z){for(let B of z)await V.debug(B)}async function y(...z){let B=N(...z);console.log(B),K.exit(W.FatalError)}async function k(...z){await V.debug(...z)}function R(z,B,D){let G=w(),H={event:B,traceId:G?.requestId,...D};if(z==="warn")V.warn(`[${B}]`,H);else V[z](H)}var O={request(z,B,D,G,H={}){let Q=D>=500?"error":D>=400?"warn":"info";R(Q,"http.request",{method:z,path:B,status:D,durationMs:G,...H})},query(z,B,D={}){R("debug","db.query",{sql:z,durationMs:B,...D})},slowQuery(z,B,D={}){R("warn","db.slow_query",{sql:z,durationMs:B,...D})},job(z,B,D={}){R(B==="failed"?"error":"info",`job.${B}`,{jobName:z,...D})},cache(z,B,D={}){R("debug",`cache.${z}`,{key:B,...D})}};V.struct=O;export{v as withLogContext,O as struct,J as logger,V as log,w as getLogContext,k as echo,C as dump,y as dd};
+var A=import.meta.require;import{AsyncLocalStorage as w}from"async_hooks";import X from"process";import{Logger as k}from"@stacksjs/clarity";import{handleError as C}from"@stacksjs/error-handling";import{ExitCode as I}from"@stacksjs/types";var W=null,T=null,j=new Set;function O(B){return j.add(B),B.finally(()=>j.delete(B)).catch(()=>{}),B}var M=!1;function E(){if(M)return;M=!0,X.on("beforeExit",()=>{G.flush()})}var b=new Set(["debug","info","success","warning","error"]);function z(B,H="info"){if(!B)return H;let J=B.toLowerCase();if(J==="warn")return"warning";if(b.has(J))return J;return X.stderr.write(`[logging] Ignoring invalid LOG_LEVEL="${B}" (expected: ${[...b].join(", ")}); using "${H}".
+`),H}function h(B){if(B==="json"||B==="text")return B;if(B)X.stderr.write(`[logging] Ignoring invalid LOG_FORMAT="${B}" (expected "json" or "text").
+`);return X.env.NODE_ENV==="production"?"json":"text"}function L(B){let H=B.envLevel?z(B.envLevel):B.cfgLevel?z(B.cfgLevel):"info",J=B.envFormat?h(B.envFormat):B.cfgFormat==="json"||B.cfgFormat==="text"?B.cfgFormat:B.isProduction?"json":"text";return{level:H,format:J,writeToFile:B.cfgWriteToFile??!0}}function q(B,H=0){if(H>8)return{name:"Error",message:"[cause chain truncated]"};if(B instanceof Error)return{name:B.name,message:B.message,stack:B.stack,cause:B.cause!=null?q(B.cause,H+1):void 0};if(typeof B==="string")return{name:"Error",message:B};if(B==null)return{name:"Error",message:String(B)};try{return{name:"Error",message:JSON.stringify(R(B))}}catch{return{name:"Error",message:String(B)}}}function S(B){let H=B.stack||`${B.name}: ${B.message}`,J=B.cause;while(J)H+=`
+  caused by: ${J.stack||`${J.name}: ${J.message}`}`,J=J.cause;return H}function R(B,H=0){if(B instanceof Error)return q(B);if(H>=4||B===null||typeof B!=="object")return B;if(Array.isArray(B))return B.map((U)=>R(U,H+1));let J=Object.getPrototypeOf(B);if(J!==Object.prototype&&J!==null)return B;let Q={};for(let[U,Z]of Object.entries(B))Q[U]=R(Z,H+1);return Q}function D(B){return R(B)}var F=new w;function o(B,H){return F.run(B,H)}function _(){return F.getStore()}async function x(){if(W)return;if(T)return T;return E(),T=(async()=>{let B,H,J,Q;try{let K=(await import("@stacksjs/config")).logging;if(K){if(B=K.level,H=K.format,typeof K.writeToFile==="boolean")Q=K.writeToFile;if(K.logsPath)J=(await import("path")).dirname(K.logsPath)}}catch{}let{level:U,format:Z,writeToFile:V}=L({envLevel:X.env.LOG_LEVEL,envFormat:X.env.LOG_FORMAT,cfgLevel:B,cfgFormat:H,cfgWriteToFile:Q,isProduction:X.env.NODE_ENV==="production"}),P=J;if(!P)try{P=(await import("@stacksjs/path")).projectPath("storage/logs")}catch{P="storage/logs"}W=new k("stacks",{level:U,logDirectory:P,showTags:!1,fancy:Z!=="json",format:Z,writeToFile:V})})(),T}async function $(){return await x(),W}function Y(...B){let H=B.map((Q)=>{if(Q instanceof Error)return S(q(Q));if(typeof Q==="object"&&Q!==null)return JSON.stringify(R(Q),null,2);return String(Q)}).join(" "),J=F.getStore();if(J?.requestId)return`[${J.requestId}] ${H}`;return H}var f=new Set(["shouldExit","silent","message"]);function v(B){if(!B||typeof B!=="object"||B instanceof Error)return!1;if(!(("shouldExit"in B)||("silent"in B)))return!1;return Object.keys(B).every((H)=>f.has(H))}var G={info:async(...B)=>{let H=Y(...B);await(await $()).info(H)},success:async(B)=>{await(await $()).success(B)},warn:async(B,H)=>{await(await $()).warn(B,H?D(H):void 0)},warning:async(B)=>{await(await $()).warn(B)},error:async(B,H,J)=>{let Q=v(H)?H:void 0,U;if(typeof B==="string")U=B;else U=S(q(B));if(H!==void 0&&!Q)U=`${U} ${S(q(H))}`;let Z={..._(),...J};if(Object.keys(Z).length>0)try{U=`${U} ${JSON.stringify(D(Z))}`}catch{}if(await(await $()).error(U),Q?.shouldExit)C(B,Q)},debug:async(...B)=>{let H=(X.env.LOG_LEVEL||"info").toLowerCase();if(H==="info"||H==="warn"||H==="error")return;let J=Y(...B);await(await $()).debug(J)},dump:async(...B)=>{let H=Y(...B);await(await $()).debug(`DUMP: ${H}`)},dd:async(...B)=>{let H=Y(...B);await(await $()).error(H),X.exit(I.FatalError)},echo:async(...B)=>{let H=Y(...B);await(await $()).info(`ECHO: ${H}`)},time:(B)=>{let H=performance.now();return async(J)=>{let Q=performance.now()-H,U=await $(),Z=J?` ${JSON.stringify(D(J))}`:"";await U.info(`${B}: ${Q.toFixed(2)}ms${Z}`)}},syncWarn:(B)=>{X.stderr.write(`${B}
+`)},syncError:(B)=>{X.stderr.write(`${B}
+`)},fatal:(B,H=I.FatalError)=>{X.stderr.write(`${B}
+`),X.exit(H)},flush:async()=>{if(j.size>0)await Promise.allSettled([...j]);if(!W&&!T)return;try{let B=await $(),H=B.flush;if(typeof H==="function")await H.call(B)}catch{}}};async function a(...B){for(let H of B)await G.debug(H)}async function s(...B){let H=Y(...B);console.log(H),X.exit(I.FatalError)}async function t(...B){await G.debug(...B)}function d(B){if(B&&typeof B==="object"){let H=B;if(typeof H.status==="number")return H.status;if(typeof H.statusCode==="number")return H.statusCode}return}function r(B,H={}){let J=H.status??d(B),Q=typeof J==="number"&&J>=400&&J<500,U=H.label??"Unhandled error",Z={...H.context,...J!=null?{status:J}:{}};if(Q){G.debug(`${U} (client error ${J}): ${q(B).message}`);return}G.error(U,B,Z)}function N(B,H,J){let Q=_(),U={event:H,traceId:Q?.requestId,...J};if(B==="warn")O(G.warn(`[${H}]`,U));else O(G[B](U))}var c={request(B,H,J,Q,U={}){let Z=J>=500?"error":J>=400?"warn":"info";N(Z,"http.request",{method:B,path:H,status:J,durationMs:Q,...U})},query(B,H,J={}){N("debug","db.query",{sql:B,durationMs:H,...J})},slowQuery(B,H,J={}){N("warn","db.slow_query",{sql:B,durationMs:H,...J})},job(B,H,J={}){N(H==="failed"?"error":"info",`job.${H}`,{jobName:B,...J})},cache(B,H,J={}){N("debug",`cache.${B}`,{key:H,...J})}};G.struct=c;export{o as withLogContext,c as struct,L as resolveLogSettings,r as report,S as renderNormalizedError,z as parseLogLevel,h as parseLogFormat,q as normalizeError,D as normalizeContext,$ as logger,G as log,_ as getLogContext,t as echo,a as dump,s as dd};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/logging",
   "type": "module",
-  "version": "0.70.45",
+  "version": "0.70.53",
   "description": "The Stacks logging system.",
   "author": "Chris Breuer",
   "contributors": [
@@ -49,12 +49,12 @@
   },
   "devDependencies": {
     "@stacksjs/clarity": "^0.3.24",
-    "@stacksjs/cli": "^0.70.45",
-    "@stacksjs/config": "^0.70.45",
-    "@stacksjs/error-handling": "^0.70.45",
-    "@stacksjs/path": "^0.70.45",
-    "@stacksjs/storage": "^0.70.45",
-    "@stacksjs/validation": "^0.70.45",
+    "@stacksjs/cli": "0.70.53",
+    "@stacksjs/config": "0.70.53",
+    "@stacksjs/error-handling": "0.70.53",
+    "@stacksjs/path": "0.70.53",
+    "@stacksjs/storage": "0.70.53",
+    "@stacksjs/validation": "0.70.53",
     "typescript": "^6.0.2"
   }
 }