@ontrails/pino 1.0.0-beta.18

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# @ontrails/pino
+
+## 1.0.0-beta.18
+
+### Minor Changes
+
+- e504e67: Add the publishable `@ontrails/pino` package scaffold.
+- 1a65022: Implement the structural Pino log sink.
+
+### Patch Changes
+
+- 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
+
+- Initial publishable package scaffold.
+- Add structural Pino log sink.

package/README.md

@@ -0,0 +1,74 @@
+# @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.
+
+## 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();
+// trails is your application's array of Trail definitions.
+const graph = topo('app', trails, {
+  observe: {
+    log: createPinoSink(logger),
+  },
+});
+```
+
+## 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.
+
+## Publishing
+
+`@ontrails/pino` participates in the standard Trails package publish checks:
+
+```bash
+bun run publish:check
+bun run publish:registry-check
+```
+
+`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
+```
+
+Do not publish this package with `npm publish` or `changeset publish`.

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@ontrails/pino",
+  "version": "1.0.0-beta.18",
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "peerDependencies": {
+    "@ontrails/observe": "^1.0.0-beta.17"
+  }
+}

package/src/index.ts

@@ -0,0 +1,90 @@
+import type { LogLevel, LogRecord, LogSink } from '@ontrails/observe';
+
+/**
+ * Package identifier for the publishable Pino adapter package.
+ */
+export const pinoPackageName = '@ontrails/pino';
+
+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;
+}
+
+export interface PinoSinkOptions {
+  /** Sink name exposed to Trails observe configuration. Defaults to `pino`. */
+  readonly name?: string | undefined;
+}
+
+type ForwardMethod = Exclude<LogLevel, 'silent'>;
+
+const LEVEL_MAP: Record<LogLevel, ForwardMethod | undefined> = {
+  debug: 'debug',
+  error: 'error',
+  fatal: 'fatal',
+  info: 'info',
+  silent: undefined,
+  trace: 'trace',
+  warn: 'warn',
+};
+
+const buildPayload = (record: LogRecord): Record<string, unknown> => ({
+  ...record.metadata,
+  category: record.category,
+  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`);
+  }
+  return loggerMethod.bind(logger);
+};
+
+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.
+ */
+export const createPinoSink = (
+  logger: PinoLoggerLike,
+  options: PinoSinkOptions = {}
+): LogSink => {
+  const methods = resolveLoggerMethods(logger);
+
+  return {
+    name: options.name ?? 'pino',
+    write(record: LogRecord): void {
+      const method = LEVEL_MAP[record.level];
+      if (method === undefined) {
+        return;
+      }
+
+      methods[method](buildPayload(record), record.message);
+    },
+  };
+};