@decohere/scribe-pino 0.0.1-dev.7 → 0.0.1-dev.71

package/types/src/scribe-pino.d.ts

@@ -1,24 +1,69 @@
 import { type Environment } from "@decohere/nexus/system";
 import { type DefaultLevels, type Logger, type ScribeOptions, scribe } from "@decohere/scribe";
-import type { TransportMultiOptions, TransportPipelineOptions, TransportSingleOptions } from "pino";
+import { type DestinationStream, type TransportMultiOptions, type TransportPipelineOptions, type TransportSingleOptions } from "pino";
+import { type PinoPrettyRecipeOptions, type PinoRollRecipeOptions } from "./pino.recipe.js";
+import { type GuardedTransport, guardTransport } from "./pino.transport-guard.js";
+export type { GuardedTransport } from "./pino.transport-guard.js";
+export { guardTransport } from "./pino.transport-guard.js";
+type TransportOptions = TransportSingleOptions | TransportMultiOptions | TransportPipelineOptions;
 type TransportConfig = {
     environment?: Environment;
-    transports: TransportSingleOptions | TransportMultiOptions | TransportPipelineOptions;
+    transports: TransportOptions;
 };
 type CustomLevelOptions<T extends string = never, CustomOnly extends true = undefined> = {
     scribe?: ScribeOptions<T, CustomOnly>;
     transports?: TransportConfig | TransportConfig[];
 };
+export type PinoLoggerFactory = (name?: string) => Logger;
+export type PinoRecipeChain = {
+    withPinoPretty(logLevelOrOptions?: DefaultLevels | string | PinoPrettyRecipeOptions): PinoRecipe;
+    withPinoRoll(options: PinoRollRecipeOptions): PinoRecipe;
+};
+export type PinoRecipe = PinoLoggerFactory & PinoRecipeChain & {
+    readonly and: PinoRecipeChain;
+};
 declare module "@decohere/scribe" {
     interface scribe {
-        withPino(transports: TransportConfig | TransportConfig[], loglevel?: DefaultLevels | string): (name?: string) => Logger;
-        withPinoPretty(logLevel?: DefaultLevels | string): (name?: string) => Logger;
-        withPinoCustom<T extends string = never, CustomOnly extends true = undefined>(options?: CustomLevelOptions<T, CustomOnly>): (name?: string) => Logger<T, CustomOnly>;
+        withPino(transports: TransportConfig | TransportConfig[], loglevel?: DefaultLevels | string): PinoLoggerFactory;
+        /**
+         * Colorized pretty transport. Development only unless `{ when: "always" }`.
+         * Chain with `.and.withPinoRoll({ file })`. Production writes JSON to stdout
+         * so log shipping stays outside the process.
+         */
+        withPinoPretty(logLevelOrOptions?: DefaultLevels | string | PinoPrettyRecipeOptions): PinoRecipe;
+        /**
+         * Rolling log files. Development only unless `{ when: "always" }`.
+         * Do not enable in production — ship stdout from a sidecar or platform agent.
+         * `symlink` defaults off; enabling it can race under multi-worker / HMR.
+         */
+        withPinoRoll(options: PinoRollRecipeOptions): PinoRecipe;
+        withPinoCustom<T extends string = never, CustomOnly extends true = undefined>(options?: CustomLevelOptions<T, CustomOnly>): PinoLoggerFactory;
+    }
+    namespace scribe {
+        function withPino(transports: TransportConfig | TransportConfig[], loglevel?: DefaultLevels | string): PinoLoggerFactory;
+        function withPinoPretty(logLevelOrOptions?: DefaultLevels | string | PinoPrettyRecipeOptions): PinoRecipe;
+        function withPinoRoll(options: PinoRollRecipeOptions): PinoRecipe;
+        function withPinoCustom<T extends string = never, CustomOnly extends true = undefined>(options?: CustomLevelOptions<T, CustomOnly>): PinoLoggerFactory;
     }
 }
 export declare class PinoExtensions {
-    static withPino(factory: scribe, config: TransportConfig | TransportConfig[], logLevel?: DefaultLevels | string): any;
-    static withPinoPretty(factory: scribe, logLevel?: DefaultLevels | string): any;
-    static withPinoCustom<T extends string = never, CustomOnly extends true = undefined>(factory: scribe, options?: CustomLevelOptions<T, CustomOnly>): any;
+    static withPino(factory: scribe, config: TransportConfig | TransportConfig[], logLevel?: DefaultLevels | string): (name?: string) => Logger<never, false>;
+    static withPinoPretty(factory: scribe, logLevelOrOptions?: DefaultLevels | string | PinoPrettyRecipeOptions): PinoRecipe;
+    static withPinoRoll(factory: scribe, options: PinoRollRecipeOptions): PinoRecipe;
+    static withPinoCustom<T extends string = never, CustomOnly extends true = undefined>(factory: scribe, options?: CustomLevelOptions<T, CustomOnly>): (name?: string) => Logger<T, CustomOnly>;
 }
-export {};
+/**
+ * Guard a worker transport so failures (roll EEXIST, worker exit) neither
+ * crash the process nor spam stderr on every subsequent log write.
+ */
+declare function createSafeTransport(options: TransportOptions): DestinationStream;
+/** @deprecated Use {@link guardTransport} — kept for callers/tests from the silence-only era. */
+declare function silenceErrors(transport: {
+    on(event: "error", listener: (err: Error) => void): unknown;
+    write?: (...args: never[]) => unknown;
+}): GuardedTransport;
+export declare const pinoTransport: {
+    createSafeTransport: typeof createSafeTransport;
+    guardTransport: typeof guardTransport;
+    silenceErrors: typeof silenceErrors;
+};