@ontrails/pino 1.0.0-beta.39 → 1.0.0-beta.43

package/CHANGELOG.md

@@ -1,122 +1,15 @@
-# @ontrails/pino
+# Changelog
 
-## 1.0.0-beta.39
-
-## 1.0.0-beta.38
-
-## 1.0.0-beta.37
-
-## 1.0.0-beta.36
-
-## 1.0.0-beta.35
-
-## 1.0.0-beta.34
-
-## 1.0.0-beta.33
-
-## 1.0.0-beta.32
-
-### Patch Changes
-
-- @ontrails/observe@1.0.0-beta.32
-
-## 1.0.0-beta.31
-
-### Patch Changes
-
-- @ontrails/observe@1.0.0-beta.31
-
-## 1.0.0-beta.30
-
-### Patch Changes
-
-- @ontrails/observe@1.0.0-beta.30
-
-## 1.0.0-beta.29
-
-### Patch Changes
-
-- @ontrails/observe@1.0.0-beta.29
-
-## 1.0.0-beta.28
-
-### Patch Changes
-
-- @ontrails/observe@1.0.0-beta.28
-
-## 1.0.0-beta.27
-
-### Patch Changes
-
-- @ontrails/observe@1.0.0-beta.27
-
-## 1.0.0-beta.26
-
-### Patch Changes
-
-- @ontrails/observe@1.0.0-beta.26
-
-## 1.0.0-beta.25
-
-### Patch Changes
-
-- @ontrails/observe@1.0.0-beta.25
-
-## 1.0.0-beta.24
-
-### Patch Changes
-
-- @ontrails/observe@1.0.0-beta.24
-
-## 1.0.0-beta.23
-
-### Patch Changes
-
-- @ontrails/observe@1.0.0-beta.23
-
-## 1.0.0-beta.22
-
-### Patch Changes
-
-- @ontrails/observe@1.0.0-beta.22
-
-## 1.0.0-beta.21
-
-### Patch Changes
-
-- @ontrails/observe@1.0.0-beta.21
-
-## 1.0.0-beta.20
-
-### Patch Changes
-
-- @ontrails/observe@1.0.0-beta.20
-
-## 1.0.0-beta.19
-
-### Patch Changes
-
-- ed5926b: Add missing TSDoc for public adapter and sink boundary types.
-- Updated dependencies [1eb5bdc]
-  - @ontrails/observe@1.0.0-beta.19
-
-## 1.0.0-beta.18
+## 1.0.0-beta.43
 
 ### Minor Changes
 
-- e504e67: Add the publishable `@ontrails/pino` package scaffold.
-- 1a65022: Implement the structural Pino log sink.
-
-### Patch Changes
+- [`50e2779`](https://github.com/outfitter-dev/trails/commit/50e27796d074851bccd57d7df009db749757b457): Extract the real `@ontrails/logtape` and `@ontrails/pino` adapters from the
+  temporary observability subpaths. The new packages own their namesake foreign
+  dependencies and preserve Trails record metadata, levels, redaction boundaries,
+  and lifecycle behavior; the old subpaths are removed in the pre-v1 hard cut.
 
-- bf44972: Document Pino sink usage and publish-readiness checks.
-- Updated dependencies [bf44972]
-- Updated dependencies [e0ae995]
-  - @ontrails/observe@1.0.0-beta.18
-
-## 1.0.0-beta.17
-
-### Minor Changes
+  Add governed Regrade transitions for both exact import replacements and expose
+  the observability adapter target through the shared adapter readiness check.
 
-- Initial publishable package scaffold.
-- Add structural Pino log sink.
+All notable changes to this package are documented through the Trails release process.

package/README.md

@@ -1,65 +1,35 @@
 # @ontrails/pino
 
-Pino adapter package for `@ontrails/observe`.
-
-## Installation
-
-```bash
-bun add @ontrails/observe @ontrails/pino pino
-```
-
-`pino` is supplied by your application. `@ontrails/pino` has no hard runtime dependency on it.
+Real Pino adapter for Trails observability. This extracted package owns the Pino dependency boundary, keeping `@ontrails/observability` limited to Trails-native records, sink contracts, redaction, formatters, and built-ins.
 
 ## Usage
 
-Use `createPinoSink(...)` when you already have a Pino-shaped logger and want Trails log records to flow into it:
-
 ```typescript
 import pino from 'pino';
 import { createPinoSink } from '@ontrails/pino';
 
-const sink = createPinoSink(pino());
-```
-
-The package does not depend on `pino`; it accepts any object shaped like a Pino logger through `PinoLoggerLike`. Records are forwarded in Pino's object-first style as `logger.info(payload, message)`, preserving the metadata already redacted by Trails.
-
-```typescript
-import pino from 'pino';
-import { topo } from '@ontrails/core';
-import { createPinoSink } from '@ontrails/pino';
+const logger = pino({ level: 'info' });
+const sink = createPinoSink({ logger });
 
-const logger = pino();
-// trails is your application's array of Trail definitions.
-const graph = topo('app', trails, {
-  observe: {
-    log: createPinoSink(logger),
-  },
+sink.write({
+  category: 'app.http',
+  level: 'info',
+  message: 'request received',
+  metadata: { requestId: 'req_123' },
+  timestamp: new Date(),
 });
-```
-
-## Structural Logger Shape
-
-`PinoLoggerLike` requires `trace`, `debug`, `info`, `warn`, `error`, and `fatal` methods that accept `(payload, message)`. The sink forwards:
-
-- `record.message` as the Pino message argument.
-- `record.category`, `record.timestamp`, and `record.metadata` in the payload.
-- `silent` records as no-ops.
 
-If a required method is missing at runtime, the sink throws instead of silently dropping the record.
+await sink.flush();
+```
 
-## Publishing
+Pass `pinoOptions` and an optional Pino destination when the adapter should construct the logger. For an asynchronously buffered destination, await `sink.flush()` before shutdown so accepted records reach Pino's destination. Trails records arrive after Trails-owned redaction, retain their category and timestamp as structured fields, and map `trace` through `fatal` directly to Pino levels. `silent` records do not reach Pino.
 
-`@ontrails/pino` participates in the standard Trails package publish checks:
+## Installation
 
 ```bash
-bun run publish:check
-bun run publish:registry-check
+bun add @ontrails/observability@beta @ontrails/pino@beta
 ```
 
-`publish:registry-check` is read-only. Before the first registry publication it may report `@ontrails/pino` as a first-time package candidate. Actual package publication still goes through the repo script:
-
-```bash
-bun run publish:packages
-```
+## Migration
 
-Do not publish this package with `npm publish` or `changeset publish`.
+This package is the final Pino adapter in the pre-v1 hard cut. No compatibility subpath remains; see the logging migration guide for the explicit historical import map.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/pino",
-  "version": "1.0.0-beta.39",
+  "version": "1.0.0-beta.43",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -21,7 +21,16 @@
     "lint": "oxlint ./src",
     "clean": "rm -rf dist *.tsbuildinfo"
   },
+  "dependencies": {
+    "pino": "^10.3.1"
+  },
   "peerDependencies": {
-    "@ontrails/observe": "^1.0.0-beta.39"
+    "@ontrails/observability": "^1.0.0-beta.43",
+    "zod": "^4.3.5"
+  },
+  "trails": {
+    "adapter": {
+      "target": "observability"
+    }
   }
 }

package/src/index.ts

@@ -1,35 +1,24 @@
-import type { LogLevel, LogRecord, LogSink } from '@ontrails/observe';
+import pino from 'pino';
+import type { DestinationStream, Logger, LoggerOptions } from 'pino';
 
-/**
- * Package identifier for the publishable Pino adapter package.
- */
-export const pinoPackageName = '@ontrails/pino';
-
-/**
- * Signature for a Pino-compatible logger method used when forwarding Trails records.
- */
-export type PinoLogMethod = (
-  payload: Record<string, unknown>,
-  message?: string
-) => void;
-
-/**
- * Structural subset of a Pino logger.
- */
-export interface PinoLoggerLike {
-  debug: PinoLogMethod;
-  error: PinoLogMethod;
-  fatal: PinoLogMethod;
-  info: PinoLogMethod;
-  trace: PinoLogMethod;
-  warn: PinoLogMethod;
-}
+import type { LogLevel, LogRecord, LogSink } from '@ontrails/observability';
 
 export interface PinoSinkOptions {
+  /** Destination used only when this adapter constructs the Pino logger itself. */
+  readonly destination?: DestinationStream | undefined;
+  /** Existing configured Pino logger to receive Trails records. */
+  readonly logger?: Logger | undefined;
+  /** Options used only when this adapter constructs the Pino logger itself. */
+  readonly pinoOptions?: LoggerOptions | undefined;
   /** Sink name exposed to Trails observe configuration. Defaults to `pino`. */
   readonly name?: string | undefined;
 }
 
+export interface PinoLogSink extends LogSink {
+  /** Flush an asynchronously buffered Pino destination, when one is present. */
+  flush(): Promise<void>;
+}
+
 type ForwardMethod = Exclude<LogLevel, 'silent'>;
 
 const LEVEL_MAP: Record<LogLevel, ForwardMethod | undefined> = {
@@ -48,46 +37,46 @@ const buildPayload = (record: LogRecord): Record<string, unknown> => ({
   timestamp: record.timestamp.toISOString(),
 });
 
-const resolveLoggerMethod = (
-  logger: PinoLoggerLike,
-  method: ForwardMethod
-): PinoLogMethod => {
-  const loggerMethod = logger[method];
-  if (typeof loggerMethod !== 'function') {
-    throw new TypeError(`Pino logger is missing "${method}" method`);
+/* oxlint-disable eslint-plugin-promise/avoid-new, eslint-plugin-promise/prefer-await-to-callbacks -- Pino exposes callback-only flush completion; the Trails sink contract is promise-based. */
+const flush = (logger: Logger): Promise<void> =>
+  new Promise((resolve, reject) => {
+    logger.flush((error) => {
+      if (error === undefined) {
+        resolve();
+        return;
+      }
+      reject(error);
+    });
+  });
+/* oxlint-enable eslint-plugin-promise/avoid-new, eslint-plugin-promise/prefer-await-to-callbacks */
+
+const resolveLogger = (options: PinoSinkOptions): Logger => {
+  if (options.logger !== undefined) {
+    return options.logger;
   }
-  return loggerMethod.bind(logger);
+  if (options.destination !== undefined) {
+    return pino(options.pinoOptions ?? {}, options.destination);
+  }
+  return options.pinoOptions === undefined ? pino() : pino(options.pinoOptions);
 };
 
-const resolveLoggerMethods = (
-  logger: PinoLoggerLike
-): Record<ForwardMethod, PinoLogMethod> => ({
-  debug: resolveLoggerMethod(logger, 'debug'),
-  error: resolveLoggerMethod(logger, 'error'),
-  fatal: resolveLoggerMethod(logger, 'fatal'),
-  info: resolveLoggerMethod(logger, 'info'),
-  trace: resolveLoggerMethod(logger, 'trace'),
-  warn: resolveLoggerMethod(logger, 'warn'),
-});
-
 /**
- * Create a Trails log sink that forwards records to a structural Pino logger.
+ * Create a Trails sink backed by a real Pino logger. If no logger is supplied,
+ * the adapter constructs one from `pinoOptions`; applications remain free to
+ * own destinations, transports, and richer Pino configuration directly.
  */
-export const createPinoSink = (
-  logger: PinoLoggerLike,
-  options: PinoSinkOptions = {}
-): LogSink => {
-  const methods = resolveLoggerMethods(logger);
+export const createPinoSink = (options: PinoSinkOptions = {}): PinoLogSink => {
+  const logger = resolveLogger(options);
 
   return {
+    flush: async (): Promise<void> => await flush(logger),
     name: options.name ?? 'pino',
     write(record: LogRecord): void {
       const method = LEVEL_MAP[record.level];
       if (method === undefined) {
         return;
       }
-
-      methods[method](buildPayload(record), record.message);
+      logger[method](buildPayload(record), record.message);
     },
   };
 };