@orpc/experimental-pino 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 oRPC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+<div align="center">
+  <image align="center" src="https://orpc.unnoq.com/logo.webp" width=280 alt="oRPC logo" />
+</div>
+
+<h1></h1>
+
+<div align="center">
+  <a href="https://codecov.io/gh/unnoq/orpc">
+    <img alt="codecov" src="https://codecov.io/gh/unnoq/orpc/branch/main/graph/badge.svg">
+  </a>
+  <a href="https://www.npmjs.com/package/@orpc/experimental-pino">
+    <img alt="weekly downloads" src="https://img.shields.io/npm/dw/%40orpc%2Fexperimental-pino?logo=npm" />
+  </a>
+  <a href="https://github.com/unnoq/orpc/blob/main/LICENSE">
+    <img alt="MIT License" src="https://img.shields.io/github/license/unnoq/orpc?logo=open-source-initiative" />
+  </a>
+  <a href="https://discord.gg/TXEbwRBvQn">
+    <img alt="Discord" src="https://img.shields.io/discord/1308966753044398161?color=7389D8&label&logo=discord&logoColor=ffffff" />
+  </a>
+  <a href="https://deepwiki.com/unnoq/orpc">
+    <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
+  </a>
+</div>
+
+<h3 align="center">Typesafe APIs Made Simple 🪄</h3>
+
+**oRPC is a powerful combination of RPC and OpenAPI**, makes it easy to build APIs that are end-to-end type-safe and adhere to OpenAPI standards
+
+---
+
+## Highlights
+
+- **🔗 End-to-End Type Safety**: Ensure type-safe inputs, outputs, and errors from client to server.
+- **📘 First-Class OpenAPI**: Built-in support that fully adheres to the OpenAPI standard.
+- **📝 Contract-First Development**: Optionally define your API contract before implementation.
+- **🔍 First-Class OpenTelemetry**: Seamlessly integrate with OpenTelemetry for observability.
+- **⚙️ Framework Integrations**: Seamlessly integrate with TanStack Query (React, Vue, Solid, Svelte, Angular), SWR, Pinia Colada, and more.
+- **🚀 Server Actions**: Fully compatible with React Server Actions on Next.js, TanStack Start, and other platforms.
+- **🔠 Standard Schema Support**: Works out of the box with Zod, Valibot, ArkType, and other schema validators.
+- **🗃️ Native Types**: Supports native types like Date, File, Blob, BigInt, URL, and more.
+- **⏱️ Lazy Router**: Enhance cold start times with our lazy routing feature.
+- **📡 SSE & Streaming**: Enjoy full type-safe support for SSE and streaming.
+- **🌍 Multi-Runtime Support**: Fast and lightweight on Cloudflare, Deno, Bun, Node.js, and beyond.
+- **🔌 Extendability**: Easily extend functionality with plugins, middleware, and interceptors.
+
+## Documentation
+
+You can find the full documentation [here](https://orpc.unnoq.com).
+
+## Packages
+
+- [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
+- [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
+- [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
+- [@orpc/openapi](https://www.npmjs.com/package/@orpc/openapi): Generate OpenAPI specs and handle OpenAPI requests.
+- [@orpc/otel](https://www.npmjs.com/package/@orpc/otel): [OpenTelemetry](https://opentelemetry.io/) integration for observability.
+- [@orpc/nest](https://www.npmjs.com/package/@orpc/nest): Deeply integrate oRPC with [NestJS](https://nestjs.com/).
+- [@orpc/react](https://www.npmjs.com/package/@orpc/react): Utilities for integrating oRPC with React and React Server Actions.
+- [@orpc/tanstack-query](https://www.npmjs.com/package/@orpc/tanstack-query): [TanStack Query](https://tanstack.com/query/latest) integration.
+- [@orpc/experimental-react-swr](https://www.npmjs.com/package/@orpc/experimental-react-swr): [SWR](https://swr.vercel.app/) integration.
+- [@orpc/vue-colada](https://www.npmjs.com/package/@orpc/vue-colada): Integration with [Pinia Colada](https://pinia-colada.esm.dev/).
+- [@orpc/hey-api](https://www.npmjs.com/package/@orpc/hey-api): [Hey API](https://heyapi.dev/) integration.
+- [@orpc/zod](https://www.npmjs.com/package/@orpc/zod): More schemas that [Zod](https://zod.dev/) doesn't support yet.
+- [@orpc/valibot](https://www.npmjs.com/package/@orpc/valibot): OpenAPI spec generation from [Valibot](https://valibot.dev/).
+- [@orpc/arktype](https://www.npmjs.com/package/@orpc/arktype): OpenAPI spec generation from [ArkType](https://arktype.io/).
+
+## `@orpc/experimental-pino`
+
+Integration with [Pino](https://getpino.io/) for structured logging.
+
+## Sponsors
+
+<p align="center">
+  <a href="https://cdn.jsdelivr.net/gh/unnoq/unnoq/sponsors.svg">
+    <img src='https://cdn.jsdelivr.net/gh/unnoq/unnoq/sponsors.svg'/>
+  </a>
+</p>
+
+## License
+
+Distributed under the MIT License. See [LICENSE](https://github.com/unnoq/orpc/blob/main/LICENSE) for more information.

package/dist/index.d.mts

@@ -0,0 +1,56 @@
+import { Logger } from 'pino';
+import { Context } from '@orpc/server';
+import { StandardHandlerInterceptorOptions, StandardHandlerPlugin, StandardHandlerOptions } from '@orpc/server/standard';
+
+declare const CONTEXT_LOGGER_SYMBOL: unique symbol;
+interface LoggerContext {
+    [CONTEXT_LOGGER_SYMBOL]?: Logger;
+}
+declare function getLogger(context: object): Logger | undefined;
+
+interface LoggingHandlerPluginOptions<T extends Context> {
+    /**
+     * Logger instance to use for logging.
+     *
+     * @default pino()
+     */
+    logger?: Logger;
+    /**
+     * Function to generate a unique ID for each request.
+     *
+     * @default () => crypto.randomUUID()
+     */
+    generateId?: (logger: Logger, options: StandardHandlerInterceptorOptions<T>) => string;
+    /**
+     * Enables info-level lifecycle logging for each request.
+     *
+     * @example
+     * - request received
+     * - request handled
+     *
+     * @default undefined (disabled)
+     */
+    logRequestLifecycle?: boolean;
+    /**
+     * Enables logging when requests are aborted.
+     *
+     * @example
+     * - request is aborted (reason)
+     *
+     * @remarks If a signal is used for multiple requests, this may lead to un-efficient memory usage (listeners never removed).
+     *
+     * @default undefined (disabled)
+     */
+    logAbort?: boolean;
+}
+declare class LoggingHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+    private readonly logger;
+    private readonly generateId;
+    private readonly logRequestLifecycle;
+    private readonly logAbort;
+    constructor(options?: LoggingHandlerPluginOptions<T>);
+    init(options: StandardHandlerOptions<T>): void;
+}
+
+export { CONTEXT_LOGGER_SYMBOL, LoggingHandlerPlugin, getLogger };
+export type { LoggerContext, LoggingHandlerPluginOptions };

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { Logger } from 'pino';
+import { Context } from '@orpc/server';
+import { StandardHandlerInterceptorOptions, StandardHandlerPlugin, StandardHandlerOptions } from '@orpc/server/standard';
+
+declare const CONTEXT_LOGGER_SYMBOL: unique symbol;
+interface LoggerContext {
+    [CONTEXT_LOGGER_SYMBOL]?: Logger;
+}
+declare function getLogger(context: object): Logger | undefined;
+
+interface LoggingHandlerPluginOptions<T extends Context> {
+    /**
+     * Logger instance to use for logging.
+     *
+     * @default pino()
+     */
+    logger?: Logger;
+    /**
+     * Function to generate a unique ID for each request.
+     *
+     * @default () => crypto.randomUUID()
+     */
+    generateId?: (logger: Logger, options: StandardHandlerInterceptorOptions<T>) => string;
+    /**
+     * Enables info-level lifecycle logging for each request.
+     *
+     * @example
+     * - request received
+     * - request handled
+     *
+     * @default undefined (disabled)
+     */
+    logRequestLifecycle?: boolean;
+    /**
+     * Enables logging when requests are aborted.
+     *
+     * @example
+     * - request is aborted (reason)
+     *
+     * @remarks If a signal is used for multiple requests, this may lead to un-efficient memory usage (listeners never removed).
+     *
+     * @default undefined (disabled)
+     */
+    logAbort?: boolean;
+}
+declare class LoggingHandlerPlugin<T extends Context> implements StandardHandlerPlugin<T> {
+    private readonly logger;
+    private readonly generateId;
+    private readonly logRequestLifecycle;
+    private readonly logAbort;
+    constructor(options?: LoggingHandlerPluginOptions<T>);
+    init(options: StandardHandlerOptions<T>): void;
+}
+
+export { CONTEXT_LOGGER_SYMBOL, LoggingHandlerPlugin, getLogger };
+export type { LoggerContext, LoggingHandlerPluginOptions };

package/dist/index.mjs

@@ -0,0 +1,98 @@
+import { get, isAsyncIteratorObject, overlayProxy } from '@orpc/shared';
+import { mapEventIterator } from '@orpc/client';
+import pino from 'pino';
+
+const CONTEXT_LOGGER_SYMBOL = Symbol("ORPC_PINO_CONTEXT_LOGGER_SYMBOL");
+function getLogger(context) {
+  return get(context, [CONTEXT_LOGGER_SYMBOL]);
+}
+
+class LoggingHandlerPlugin {
+  logger;
+  generateId;
+  logRequestLifecycle;
+  logAbort;
+  constructor(options = {}) {
+    this.logger = options.logger ?? pino();
+    this.generateId = options.generateId ?? (() => crypto.randomUUID());
+    this.logRequestLifecycle = options.logRequestLifecycle;
+    this.logAbort = options.logAbort;
+  }
+  init(options) {
+    options.rootInterceptors ??= [];
+    options.interceptors ??= [];
+    options.clientInterceptors ??= [];
+    options.rootInterceptors.unshift(async (interceptorOptions) => {
+      const logger = (interceptorOptions.context[CONTEXT_LOGGER_SYMBOL] ?? this.logger).child({});
+      const currentBindings = logger.bindings();
+      const extraBindings = {
+        orpc: { ...currentBindings.orpc, id: this.generateId(logger, interceptorOptions) }
+      };
+      if (!currentBindings.req) {
+        extraBindings.req = { url: interceptorOptions.request.url, method: interceptorOptions.request.method };
+      }
+      logger.setBindings(extraBindings);
+      try {
+        return await interceptorOptions.next({
+          ...interceptorOptions,
+          context: {
+            ...interceptorOptions.context,
+            [CONTEXT_LOGGER_SYMBOL]: logger
+          }
+        });
+      } catch (error) {
+        this.logger.error(error);
+        throw error;
+      }
+    });
+    options.interceptors.unshift(async ({ next, context, request }) => {
+      const logger = getLogger(context);
+      if (this.logAbort) {
+        request.signal?.addEventListener("abort", () => {
+          logger?.info(`request is aborted (${String(request.signal?.reason)})`);
+        }, { once: true });
+      }
+      try {
+        if (this.logRequestLifecycle) {
+          logger?.info("request received");
+        }
+        const result = await next();
+        if (this.logRequestLifecycle) {
+          logger?.info(result.matched ? "request handled" : "no matching procedure found");
+        }
+        return result;
+      } catch (error) {
+        if (request.signal?.aborted && request.signal.reason === error) {
+          logger?.info(error);
+        } else {
+          logger?.error(error);
+        }
+        throw error;
+      }
+    });
+    options.clientInterceptors.unshift(async ({ next, path, context, signal }) => {
+      const logger = getLogger(context);
+      logger?.setBindings({ orpc: { ...logger.bindings().orpc, path } });
+      const output = await next();
+      if (isAsyncIteratorObject(output)) {
+        return overlayProxy(output, mapEventIterator(
+          output,
+          {
+            value: (v) => v,
+            error: async (error) => {
+              if (signal?.aborted && signal.reason === error) {
+                logger?.info(error);
+              } else {
+                logger?.error(error);
+              }
+              return error;
+            }
+          }
+        ));
+      }
+      return output;
+    });
+  }
+}
+
+export { CONTEXT_LOGGER_SYMBOL, LoggingHandlerPlugin, getLogger };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@orpc/experimental-pino",
+  "type": "module",
+  "version": "0.0.0",
+  "license": "MIT",
+  "homepage": "https://orpc.unnoq.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unnoq/orpc.git",
+    "directory": "packages/pino"
+  },
+  "keywords": [
+    "orpc",
+    "pino"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "pino": ">=10.1.0"
+  },
+  "dependencies": {
+    "@orpc/client": "1.10.4",
+    "@orpc/shared": "1.10.4",
+    "@orpc/server": "1.10.4"
+  },
+  "devDependencies": {
+    "pino": "^10.1.0"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "build:watch": "pnpm run build --watch",
+    "type:check": "tsc -b"
+  }
+}