@beignet/provider-logger-pino 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @beignet/provider-logger-pino
+
+## 0.0.1
+
+- Initial Beignet release under the `@beignet` npm scope.

package/README.md

@@ -0,0 +1,83 @@
+# @beignet/provider-logger-pino
+
+Pino-backed `LoggerPort` provider for Beignet.
+
+Use this package when you want `ctx.ports.logger` backed by Pino while keeping
+application code dependent on the stable `LoggerPort` interface from
+`@beignet/core/ports`.
+
+## Install
+
+```bash
+bun add @beignet/core @beignet/provider-logger-pino pino
+```
+
+Pretty development logs are optional:
+
+```bash
+bun add -d pino-pretty
+```
+
+## Setup
+
+```ts
+import { createNextServer } from "@beignet/next";
+import { loggerPinoProvider } from "@beignet/provider-logger-pino";
+import { appPorts } from "@/infra/app-ports";
+
+export const server = await createNextServer({
+  ports: appPorts,
+  providers: [loggerPinoProvider],
+  createContext: ({ ports }) => ({
+    requestId: crypto.randomUUID(),
+    ports,
+  }),
+});
+```
+
+The provider installs `ctx.ports.logger`.
+
+## Environment
+
+The provider reads `LOG_`-prefixed environment variables:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `LOG_LEVEL` | `info` | `trace`, `debug`, `info`, `warn`, `error`, or `fatal` |
+| `LOG_FORMAT` | `json` | `json` or `pretty` |
+| `LOG_SERVICE` | none | Optional service name added to log bindings |
+| `LOG_TIMESTAMP` | `true` | Include ISO timestamps |
+
+`LOG_FORMAT=pretty` requires `pino-pretty`. If it is unavailable, the provider
+falls back to JSON logging and emits a warning.
+
+## Usage
+
+```ts
+ctx.ports.logger.info("Post published", {
+  postId: post.id,
+  actorId: ctx.actor.type === "user" ? ctx.actor.id : undefined,
+});
+
+const log = ctx.ports.logger.child({ requestId: ctx.requestId });
+log.error("Failed to publish post", { error });
+```
+
+## Exports
+
+| Export | Purpose |
+| --- | --- |
+| `loggerPinoProvider` | Ready-to-install Beignet provider |
+| `LoggerPinoConfig` | Validated provider config type |
+| `LoggerPort` | Re-export from `@beignet/core/ports` |
+| `LogLevel` | Re-export from `@beignet/core/ports` |
+
+## Read next
+
+- Docs site logging guide: https://beignet.dev/logging
+- Providers: https://beignet.dev/providers
+- Pino documentation: https://getpino.io/
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @beignet/provider-logger-pino
+ *
+ * Pino logger provider that extends ports with structured logging capabilities using Pino.
+ *
+ * Configuration:
+ * - LOG_LEVEL: Minimum log level (trace/debug/info/warn/error/fatal, default: info)
+ * - LOG_FORMAT: Log format (json/pretty, default: json)
+ * - LOG_SERVICE: Optional service name for log enrichment
+ * - LOG_TIMESTAMP: Whether to include timestamps (true/false, default: true)
+ *
+ * @example
+ * ```ts
+ * import { createNextServer } from "@beignet/next";
+ * import { loggerPinoProvider } from "@beignet/provider-logger-pino";
+ *
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [loggerPinoProvider],
+ *   // ...
+ * });
+ *
+ * // In your use cases:
+ * ctx.ports.logger.info("User logged in", { userId: user.id });
+ *
+ * // Create child logger with request context:
+ * const log = ctx.ports.logger.child({ requestId: ctx.requestId });
+ * log.info("Processing request");
+ * ```
+ */
+import type { LoggerPort } from "@beignet/core/ports";
+import { z } from "zod";
+export type { LoggerPort, LogLevel } from "@beignet/core/ports";
+/**
+ * Configuration schema for the Pino logger provider.
+ * Validates environment variables with LOG_ prefix.
+ */
+declare const LoggerPinoConfigSchema: z.ZodObject<{
+    LEVEL: z.ZodDefault<z.ZodEnum<{
+        trace: "trace";
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+        error: "error";
+        fatal: "fatal";
+    }>>;
+    FORMAT: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        pretty: "pretty";
+    }>>;
+    SERVICE: z.ZodOptional<z.ZodString>;
+    TIMESTAMP: z.ZodDefault<z.ZodCoercedBoolean<unknown>>;
+}, z.core.$strip>;
+/**
+ * Inferred configuration type for Pino logger provider.
+ */
+export type LoggerPinoConfig = z.infer<typeof LoggerPinoConfigSchema>;
+/**
+ * Pino logger provider that extends ports with structured logging capabilities.
+ *
+ * Configuration via environment variables:
+ * - LOG_LEVEL: Minimum log level (trace/debug/info/warn/error/fatal, default: info)
+ * - LOG_FORMAT: Log format (json/pretty, default: json)
+ * - LOG_SERVICE: Optional service name for log enrichment
+ * - LOG_TIMESTAMP: Whether to include timestamps (true/false, default: true)
+ *
+ * @example
+ * ```ts
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [loggerPinoProvider],
+ *   // ...
+ * });
+ * ```
+ */
+export declare const loggerPinoProvider: import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
+    LEVEL: z.ZodDefault<z.ZodEnum<{
+        trace: "trace";
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+        error: "error";
+        fatal: "fatal";
+    }>>;
+    FORMAT: z.ZodDefault<z.ZodEnum<{
+        json: "json";
+        pretty: "pretty";
+    }>>;
+    SERVICE: z.ZodOptional<z.ZodString>;
+    TIMESTAMP: z.ZodDefault<z.ZodCoercedBoolean<unknown>>;
+}, z.core.$strip>, {
+    logger: LoggerPort;
+}>;
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEhE;;;GAGG;AACH,QAAA,MAAM,sBAAsB;;;;;;;;;;;;;;;iBA6B1B,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AA4EtE;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;EA8B7B,CAAC"}

package/dist/index.js

@@ -0,0 +1,166 @@
+/**
+ * @beignet/provider-logger-pino
+ *
+ * Pino logger provider that extends ports with structured logging capabilities using Pino.
+ *
+ * Configuration:
+ * - LOG_LEVEL: Minimum log level (trace/debug/info/warn/error/fatal, default: info)
+ * - LOG_FORMAT: Log format (json/pretty, default: json)
+ * - LOG_SERVICE: Optional service name for log enrichment
+ * - LOG_TIMESTAMP: Whether to include timestamps (true/false, default: true)
+ *
+ * @example
+ * ```ts
+ * import { createNextServer } from "@beignet/next";
+ * import { loggerPinoProvider } from "@beignet/provider-logger-pino";
+ *
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [loggerPinoProvider],
+ *   // ...
+ * });
+ *
+ * // In your use cases:
+ * ctx.ports.logger.info("User logged in", { userId: user.id });
+ *
+ * // Create child logger with request context:
+ * const log = ctx.ports.logger.child({ requestId: ctx.requestId });
+ * log.info("Processing request");
+ * ```
+ */
+import { createProvider } from "@beignet/core/providers";
+import pino from "pino";
+import { z } from "zod";
+/**
+ * Configuration schema for the Pino logger provider.
+ * Validates environment variables with LOG_ prefix.
+ */
+const LoggerPinoConfigSchema = z.object({
+    /**
+     * Minimum log level.
+     * Messages below this level will be ignored.
+     * Default: "info"
+     */
+    LEVEL: z
+        .enum(["trace", "debug", "info", "warn", "error", "fatal"])
+        .default("info"),
+    /**
+     * Log format.
+     * - "json": Newline-delimited JSON (production-friendly)
+     * - "pretty": Human-readable format (requires pino-pretty)
+     * Default: "json"
+     */
+    FORMAT: z.enum(["json", "pretty"]).default("json"),
+    /**
+     * Optional service name for log enrichment.
+     * Will be added to all log entries as { service: "your-service" }
+     */
+    SERVICE: z.string().optional(),
+    /**
+     * Whether to include timestamps in log entries.
+     * Default: true
+     */
+    TIMESTAMP: z.coerce.boolean().default(true),
+});
+/**
+ * Create a Pino logger instance with the given configuration.
+ *
+ * @param config - Validated logger configuration
+ * @param bindings - Optional base bindings to add to all log entries
+ * @returns Configured Pino logger instance
+ */
+function createPinoLogger(config, bindings = {}) {
+    const pinoOptions = {
+        level: config.LEVEL,
+        timestamp: config.TIMESTAMP ? pino.stdTimeFunctions.isoTime : false,
+        base: bindings,
+    };
+    // Handle pretty format
+    if (config.FORMAT === "pretty") {
+        try {
+            // Attempt to use pino-pretty transport
+            return pino({
+                ...pinoOptions,
+                transport: {
+                    target: "pino-pretty",
+                    options: {
+                        colorize: true,
+                        translateTime: "HH:MM:ss Z",
+                        ignore: "pid,hostname",
+                    },
+                },
+            });
+        }
+        catch (_error) {
+            // pino-pretty not available, fall back to JSON with warning
+            const jsonLogger = pino(pinoOptions);
+            jsonLogger.warn("LOG_FORMAT=pretty requested but pino-pretty is not installed. " +
+                "Falling back to JSON format. Install pino-pretty to enable pretty printing.");
+            return jsonLogger;
+        }
+    }
+    // Default to JSON format
+    return pino(pinoOptions);
+}
+/**
+ * Wrap a Pino logger instance to conform to the LoggerPort interface.
+ *
+ * Pino's API uses the signature: logger.level(obj, msg) or logger.level(msg)
+ * We adapt this to: logger.level(msg, meta?)
+ *
+ * @param logger - Pino logger instance to wrap
+ * @returns LoggerPort implementation
+ */
+function wrapPino(logger) {
+    return {
+        trace: (message, meta) => meta ? logger.trace(meta, message) : logger.trace(message),
+        debug: (message, meta) => meta ? logger.debug(meta, message) : logger.debug(message),
+        info: (message, meta) => meta ? logger.info(meta, message) : logger.info(message),
+        warn: (message, meta) => meta ? logger.warn(meta, message) : logger.warn(message),
+        error: (message, meta) => meta ? logger.error(meta, message) : logger.error(message),
+        fatal: (message, meta) => meta ? logger.fatal(meta, message) : logger.fatal(message),
+        child: (bindings) => wrapPino(logger.child(bindings)),
+    };
+}
+/**
+ * Pino logger provider that extends ports with structured logging capabilities.
+ *
+ * Configuration via environment variables:
+ * - LOG_LEVEL: Minimum log level (trace/debug/info/warn/error/fatal, default: info)
+ * - LOG_FORMAT: Log format (json/pretty, default: json)
+ * - LOG_SERVICE: Optional service name for log enrichment
+ * - LOG_TIMESTAMP: Whether to include timestamps (true/false, default: true)
+ *
+ * @example
+ * ```ts
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [loggerPinoProvider],
+ *   // ...
+ * });
+ * ```
+ */
+export const loggerPinoProvider = createProvider({
+    name: "logger-pino",
+    config: {
+        schema: LoggerPinoConfigSchema,
+        envPrefix: "LOG_",
+    },
+    async setup({ config }) {
+        if (!config) {
+            throw new Error("[loggerPinoProvider] Missing logger config. " +
+                "Please set LOG_LEVEL, LOG_FORMAT, etc. environment variables.");
+        }
+        // Prepare base bindings
+        const baseBindings = {};
+        if (config.SERVICE) {
+            baseBindings.service = config.SERVICE;
+        }
+        // Create and configure Pino logger
+        const logger = createPinoLogger(config, baseBindings);
+        // Wrap logger to match LoggerPort interface
+        const port = wrapPino(logger);
+        return { ports: { logger: port } };
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@beignet/provider-logger-pino",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Pino logger provider for Beignet - adds logger port using pino",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "beignet",
+    "logger",
+    "logging",
+    "provider",
+    "pino",
+    "structured-logging",
+    "ports"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/provider-logger-pino"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": "https://github.com/taylorbryant/beignet/issues",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "pino": "^9.0.0 || ^10.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.0.0",
+    "@beignet/core": "*"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "pino": "^10.0.0",
+    "typescript": "^5.3.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,201 @@
+/**
+ * @beignet/provider-logger-pino
+ *
+ * Pino logger provider that extends ports with structured logging capabilities using Pino.
+ *
+ * Configuration:
+ * - LOG_LEVEL: Minimum log level (trace/debug/info/warn/error/fatal, default: info)
+ * - LOG_FORMAT: Log format (json/pretty, default: json)
+ * - LOG_SERVICE: Optional service name for log enrichment
+ * - LOG_TIMESTAMP: Whether to include timestamps (true/false, default: true)
+ *
+ * @example
+ * ```ts
+ * import { createNextServer } from "@beignet/next";
+ * import { loggerPinoProvider } from "@beignet/provider-logger-pino";
+ *
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [loggerPinoProvider],
+ *   // ...
+ * });
+ *
+ * // In your use cases:
+ * ctx.ports.logger.info("User logged in", { userId: user.id });
+ *
+ * // Create child logger with request context:
+ * const log = ctx.ports.logger.child({ requestId: ctx.requestId });
+ * log.info("Processing request");
+ * ```
+ */
+
+import type { LoggerPort } from "@beignet/core/ports";
+import { createProvider } from "@beignet/core/providers";
+import pino, { type Logger as PinoLogger } from "pino";
+import { z } from "zod";
+
+export type { LoggerPort, LogLevel } from "@beignet/core/ports";
+
+/**
+ * Configuration schema for the Pino logger provider.
+ * Validates environment variables with LOG_ prefix.
+ */
+const LoggerPinoConfigSchema = z.object({
+  /**
+   * Minimum log level.
+   * Messages below this level will be ignored.
+   * Default: "info"
+   */
+  LEVEL: z
+    .enum(["trace", "debug", "info", "warn", "error", "fatal"])
+    .default("info"),
+
+  /**
+   * Log format.
+   * - "json": Newline-delimited JSON (production-friendly)
+   * - "pretty": Human-readable format (requires pino-pretty)
+   * Default: "json"
+   */
+  FORMAT: z.enum(["json", "pretty"]).default("json"),
+
+  /**
+   * Optional service name for log enrichment.
+   * Will be added to all log entries as { service: "your-service" }
+   */
+  SERVICE: z.string().optional(),
+
+  /**
+   * Whether to include timestamps in log entries.
+   * Default: true
+   */
+  TIMESTAMP: z.coerce.boolean().default(true),
+});
+
+/**
+ * Inferred configuration type for Pino logger provider.
+ */
+export type LoggerPinoConfig = z.infer<typeof LoggerPinoConfigSchema>;
+
+/**
+ * Create a Pino logger instance with the given configuration.
+ *
+ * @param config - Validated logger configuration
+ * @param bindings - Optional base bindings to add to all log entries
+ * @returns Configured Pino logger instance
+ */
+function createPinoLogger(
+  config: LoggerPinoConfig,
+  bindings: Record<string, unknown> = {},
+): PinoLogger {
+  const pinoOptions: pino.LoggerOptions = {
+    level: config.LEVEL,
+    timestamp: config.TIMESTAMP ? pino.stdTimeFunctions.isoTime : false,
+    base: bindings,
+  };
+
+  // Handle pretty format
+  if (config.FORMAT === "pretty") {
+    try {
+      // Attempt to use pino-pretty transport
+      return pino({
+        ...pinoOptions,
+        transport: {
+          target: "pino-pretty",
+          options: {
+            colorize: true,
+            translateTime: "HH:MM:ss Z",
+            ignore: "pid,hostname",
+          },
+        },
+      });
+    } catch (_error) {
+      // pino-pretty not available, fall back to JSON with warning
+      const jsonLogger = pino(pinoOptions);
+      jsonLogger.warn(
+        "LOG_FORMAT=pretty requested but pino-pretty is not installed. " +
+          "Falling back to JSON format. Install pino-pretty to enable pretty printing.",
+      );
+      return jsonLogger;
+    }
+  }
+
+  // Default to JSON format
+  return pino(pinoOptions);
+}
+
+/**
+ * Wrap a Pino logger instance to conform to the LoggerPort interface.
+ *
+ * Pino's API uses the signature: logger.level(obj, msg) or logger.level(msg)
+ * We adapt this to: logger.level(msg, meta?)
+ *
+ * @param logger - Pino logger instance to wrap
+ * @returns LoggerPort implementation
+ */
+function wrapPino(logger: PinoLogger): LoggerPort {
+  return {
+    trace: (message, meta) =>
+      meta ? logger.trace(meta, message) : logger.trace(message),
+    debug: (message, meta) =>
+      meta ? logger.debug(meta, message) : logger.debug(message),
+    info: (message, meta) =>
+      meta ? logger.info(meta, message) : logger.info(message),
+    warn: (message, meta) =>
+      meta ? logger.warn(meta, message) : logger.warn(message),
+    error: (message, meta) =>
+      meta ? logger.error(meta, message) : logger.error(message),
+    fatal: (message, meta) =>
+      meta ? logger.fatal(meta, message) : logger.fatal(message),
+    child: (bindings) => wrapPino(logger.child(bindings)),
+  };
+}
+
+/**
+ * Pino logger provider that extends ports with structured logging capabilities.
+ *
+ * Configuration via environment variables:
+ * - LOG_LEVEL: Minimum log level (trace/debug/info/warn/error/fatal, default: info)
+ * - LOG_FORMAT: Log format (json/pretty, default: json)
+ * - LOG_SERVICE: Optional service name for log enrichment
+ * - LOG_TIMESTAMP: Whether to include timestamps (true/false, default: true)
+ *
+ * @example
+ * ```ts
+ * const server = await createNextServer({
+ *   ports: basePorts,
+ *   providers: [loggerPinoProvider],
+ *   // ...
+ * });
+ * ```
+ */
+export const loggerPinoProvider = createProvider({
+  name: "logger-pino",
+
+  config: {
+    schema: LoggerPinoConfigSchema,
+    envPrefix: "LOG_",
+  },
+
+  async setup({ config }) {
+    if (!config) {
+      throw new Error(
+        "[loggerPinoProvider] Missing logger config. " +
+          "Please set LOG_LEVEL, LOG_FORMAT, etc. environment variables.",
+      );
+    }
+
+    // Prepare base bindings
+    const baseBindings: Record<string, unknown> = {};
+    if (config.SERVICE) {
+      baseBindings.service = config.SERVICE;
+    }
+
+    // Create and configure Pino logger
+    const logger = createPinoLogger(config, baseBindings);
+
+    // Wrap logger to match LoggerPort interface
+    const port = wrapPino(logger);
+
+    return { ports: { logger: port } };
+  },
+});