docs: clarify logger documentation

Author: khmm12

README.md

@@ -1,9 +1,9 @@
 # knex-tiny-logger
 
-> Zero-config query logging for Knex. Tiny by default, flexible when needed.
-
 [![](https://img.shields.io/npm/v/knex-tiny-logger.svg?style=flat-square)](https://npmjs.com/package/knex-tiny-logger)
 
+> Zero-config query logging for Knex. Tiny by default, flexible when needed.
+
 ## Install
 
 ```bash
@@ -39,9 +39,14 @@ const knex = knexTinyLogger(
 )
 ```
 
-That is the default path: plain output, no extra runtime dependencies.
+By default, `knexTinyLogger` uses `defaultLogger`: plain string logs, no extra runtime dependencies.
 
-## String Logs
+```text
+SQL (3.421 ms) select 1 as id
+SQL ERROR (2.104 ms) select * from missing_table
+```
+
+## Default Logger
 
 ```ts
 import knexTinyLogger, { defaultLogger } from 'knex-tiny-logger'
@@ -51,7 +56,9 @@ knexTinyLogger(knex, {
 })
 ```
 
-String loggers format SQL before writing it. Use `bindings` for the built-in formatter, or replace formatting completely:
+The default logger formats SQL before writing it. By default, it asks Knex to interpolate bindings into the logged SQL.
+
+Set `bindings: false` to write the original SQL with placeholders, or replace formatting completely:
 
 ```ts
 knexTinyLogger(knex, {
@@ -73,7 +80,10 @@ knexTinyLogger(knex, {
 
 ## Colorful Logs
 
-The colorful logger lives in a separate entrypoint.
+The colorful logger is the same string logger experience, with output colored by query state.
+It supports the same `bindings`, `formatter`, and `write` options as `defaultLogger`.
+
+Successful SQL is cyan; failed SQL is red. The message shape otherwise matches `defaultLogger`.
 
 ```ts
 import knexTinyLogger from 'knex-tiny-logger'
@@ -93,13 +103,12 @@ import knexTinyLogger from 'knex-tiny-logger'
 import { pinoLogger } from 'knex-tiny-logger/pino'
 
 knexTinyLogger(knex, {
-  logger: pinoLogger(pino, {
-    bindings: true,
-  }),
+  logger: pinoLogger(pino),
 })
 ```
 
 The pino adapter logs `sql`, `bindings`, and `durationMs`; errors also include `err`.
+Bindings are included by default. Set `bindings: false` to omit them from the structured payload.
 
 ## Custom Logger
 
@@ -118,6 +127,21 @@ const logger: Logger = {
 knexTinyLogger(knex, { logger })
 ```
 
+Passing a function uses the default string formatting and writes each log message to that function:
+
+```ts
+import { defaultLogger } from 'knex-tiny-logger'
+
+knexTinyLogger(knex, { logger: console.log })
+
+// same as
+knexTinyLogger(knex, {
+  logger: defaultLogger({ write: console.log }),
+})
+```
+
+## Logger Errors
+
 Logger errors are caught so logging does not break queries. By default they are reported with `console.error`.
 
 ```ts
@@ -129,35 +153,36 @@ knexTinyLogger(knex, {
 })
 ```
 
-Simple function loggers also work:
-
-```ts
-knexTinyLogger(knex, { logger: console.log })
-```
-
 ## Tracing
 
-Use the tracer directly for lower-level integrations.
+For lower-level integrations:
 
 ```ts
 import { createTracer } from 'knex-tiny-logger/tracer'
 
+const spans = new Map()
+
 const tracer = createTracer(knex, {
   onStart(query) {
-    span.start(query.sql)
+    spans.set(query.queryId, tracerProvider.startSpan('sql', {
+      sql: query.sql,
+      bindings: query.bindings,
+    }))
   },
   onEnd(query) {
-    span.end({ durationMs: query.durationMs })
+    spans.get(query.queryId)?.end({ durationMs: query.durationMs })
+    spans.delete(query.queryId)
   },
   onError(query) {
-    span.fail(query.error)
+    spans.get(query.queryId)?.fail(query.error)
+    spans.delete(query.queryId)
   },
 })
 
 tracer.dispose()
 ```
 
-The tracer is raw on purpose: lifecycle, duration, SQL, bindings, errors. Formatting belongs to loggers.
+The tracer exposes query lifecycle events with duration, SQL, bindings, and errors.
 
 ## License
 

src/colorful-logger.ts

@@ -12,15 +12,23 @@ const COLORIZE = {
 /**
  * Create the built-in ANSI-colored string logger.
  *
- * It writes to `console.log` by default. `bindings` configures the built-in
- * formatter; `formatter` lets you provide custom SQL formatting.
+ * It behaves like `defaultLogger`, but colors output by query state.
+ *
+ * It writes to `console.log` by default.
+ *
+ * By default, it asks Knex to interpolate bindings into the logged SQL.
+ * `bindings: false` writes the original SQL with placeholders.
+ *
+ * `formatter` lets you replace SQL formatting completely.
  *
  * @example
  * ```ts
  * import knexTinyLogger from 'knex-tiny-logger'
  * import { colorfulLogger } from 'knex-tiny-logger/colorful'
  *
- * knexTinyLogger(knex, { logger: colorfulLogger() })
+ * knexTinyLogger(knex, {
+ *   logger: colorfulLogger(),
+ * })
  * ```
  */
 export function colorfulLogger(options: ColorfulLoggerOptions = {}): Logger {

src/default-logger.ts

@@ -5,14 +5,20 @@ import type { DefaultLoggerOptions, Logger, QueryFormatter } from './types.ts'
 /**
  * Create the built-in dependency-free string logger.
  *
- * It writes to `console.log` by default. `bindings` configures the built-in
- * formatter; `formatter` lets you provide custom SQL formatting.
+ * It writes to `console.log` by default.
+ *
+ * By default, it asks Knex to interpolate bindings into the logged SQL.
+ * `bindings: false` writes the original SQL with placeholders.
+ *
+ * `formatter` lets you replace SQL formatting completely.
  *
  * @example
  * ```ts
  * import knexTinyLogger, { defaultLogger } from 'knex-tiny-logger'
  *
- * knexTinyLogger(knex, { logger: defaultLogger({ bindings: false }) })
+ * knexTinyLogger(knex, {
+ *   logger: defaultLogger({ bindings: false }),
+ * })
  * ```
  */
 export function defaultLogger(options: DefaultLoggerOptions = {}): Logger {

src/index.ts

@@ -28,8 +28,10 @@ export type {
  * Attach query logging to a Knex instance and return the same instance.
  *
  * With no options, queries are logged through the built-in dependency-free
- * logger. Logger errors are caught and reported through `onLoggerError` so
- * logging does not break database queries.
+ * `defaultLogger()`.
+ *
+ * Logger errors are caught and reported through `onLoggerError` so logging does
+ * not break database queries.
  *
  * @example
  * ```ts

src/pino-logger.ts

@@ -32,7 +32,7 @@ export interface PinoLoggerOptions {
  * import { pinoLogger } from 'knex-tiny-logger/pino'
  *
  * knexTinyLogger(knex, {
- *   logger: pinoLogger(pino, { bindings: true }),
+ *   logger: pinoLogger(pino),
  * })
  * ```
  */

src/tracer.ts

@@ -25,16 +25,32 @@ type KnexWithEvents = Knex & {
 /**
  * Attach low-level query tracing hooks to a Knex instance.
  *
- * The tracer reports raw query lifecycle data and never formats SQL. Hook
- * errors are caught and passed to `onTracerError`, which is a no-op by default.
+ * The tracer exposes query lifecycle events with duration, SQL, bindings, and
+ * errors.
+ *
+ * Hook errors are caught and passed to `onTracerError`, which is a no-op by
+ * default.
  *
  * @example
  * ```ts
  * import { createTracer } from 'knex-tiny-logger/tracer'
  *
+ * const spans = new Map()
+ *
  * const tracer = createTracer(knex, {
+ *   onStart(event) {
+ *     spans.set(event.queryId, tracerProvider.startSpan('sql', {
+ *       sql: event.sql,
+ *       bindings: event.bindings,
+ *     }))
+ *   },
  *   onEnd(event) {
- *     console.log(event.sql, event.durationMs)
+ *     spans.get(event.queryId)?.end({ durationMs: event.durationMs })
+ *     spans.delete(event.queryId)
+ *   },
+ *   onError(event) {
+ *     spans.get(event.queryId)?.fail(event.error)
+ *     spans.delete(event.queryId)
  *   },
  * })
  *

src/types.ts

@@ -1,6 +1,10 @@
 import type { Knex } from 'knex'
 
-/** Function logger adapter, for example `console.log`. */
+/**
+ * Function logger adapter, for example `console.log`.
+ *
+ * Receives default string log messages.
+ */
 export type SimpleLogger = (message?: unknown, ...optionalParams: unknown[]) => void
 
 /** Receives one complete message from a string logger. */
@@ -23,7 +27,11 @@ export interface QueryFormatterInput {
 
 /** Options for `defaultQueryFormatter`. */
 export interface DefaultQueryFormatterOptions {
-  /** Include bindings in formatted SQL when Knex can interpolate them. Defaults to `true`. */
+  /**
+   * Ask Knex to interpolate bindings into the logged SQL.
+   *
+   * Defaults to `true`.
+   */
   bindings?: boolean
 }
 
@@ -110,13 +118,15 @@ interface StringLoggerBaseOptions {
 /**
  * Options shared by string loggers.
  *
- * `bindings` configures the built-in formatter. `formatter` provides custom
- * SQL formatting, so `bindings` only applies when `formatter` is not provided.
+ * Bindings are interpolated into the logged SQL by default through Knex.
+ *
+ * `formatter` provides custom SQL formatting, so `bindings` only applies when
+ * `formatter` is not provided.
  */
 export type StringLoggerOptions = StringLoggerBaseOptions &
   (
     | {
-        /** Include bindings in SQL formatted by the built-in formatter. Defaults to `true`. */
+        /** Ask Knex to interpolate bindings into the logged SQL. Defaults to `true`. */
         bindings?: boolean
         formatter?: undefined
       }
@@ -129,7 +139,7 @@ export type StringLoggerOptions = StringLoggerBaseOptions &
 
 /** Options accepted by `defaultLogger`. */
 export type DefaultLoggerOptions = StringLoggerOptions
-/** Options accepted by `colorfulLogger`. */
+/** Options accepted by `colorfulLogger`; same formatting options as `defaultLogger`. */
 export type ColorfulLoggerOptions = StringLoggerOptions
 
 /** Options for `createTracer`. */
@@ -140,8 +150,16 @@ export interface CreateTracerOptions extends TracerHooks {
 
 /** Options for `knexTinyLogger`. */
 export interface KnexTinyLoggerOptions {
-  /** Logger implementation or simple log function. Defaults to `defaultLogger()`. */
+  /**
+   * Logger implementation or simple log function.
+   *
+   * Defaults to String Logs through `defaultLogger()`.
+   */
   logger?: Logger | SimpleLogger
-  /** Called when a logger hook, writer, or formatter throws. Defaults to `console.error`. */
+  /**
+   * Called when a logger hook, writer, or formatter throws.
+   *
+   * Defaults to `console.error`.
+   */
   onLoggerError?: (event: LoggerErrorEvent) => void
 }