npm - @alt-stack/server-bun - Versions diffs - 0.4.5 - Mend

@alt-stack/server-bun 0.4.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025 Anthony Altieri
+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/package.json ADDED Viewed

@@ -0,0 +1,33 @@
+{
+  "name": "@alt-stack/server-bun",
+  "version": "0.4.5",
+  "description": "Type-safe server framework built on Bun with Zod validation",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@alt-stack/server-core": "0.4.4"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "bun-types": "^1.2.5",
+    "oxlint": "^1.24.0",
+    "typescript": "^5.9.2",
+    "zod": "^4.0.0"
+  },
+  "scripts": {
+    "test": "bun test",
+    "check-types": "tsc --noEmit"
+  }
+}

package/src/docs.ts ADDED Viewed

@@ -0,0 +1,115 @@
+import { z } from "zod";
+import {
+  router,
+  publicProcedure,
+  generateOpenAPISpec,
+  ok,
+} from "@alt-stack/server-core";
+import type { Router, GenerateOpenAPISpecOptions } from "@alt-stack/server-core";
+export interface CreateDocsRouterOptions extends GenerateOpenAPISpecOptions {
+  openapiPath?: string;
+  enableDocs?: boolean;
+}
+const SWAGGER_UI_HTML = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>API Documentation</title>
+  <link rel="stylesheet" type="text/css" href="https://unpkg.com/swagger-ui-dist@5.10.5/swagger-ui.css" />
+  <style>
+    html {
+      box-sizing: border-box;
+      overflow: -moz-scrollbars-vertical;
+      overflow-y: scroll;
+    }
+    *, *:before, *:after {
+      box-sizing: inherit;
+    }
+    body {
+      margin:0;
+      background: #fafafa;
+    }
+  </style>
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist@5.10.5/swagger-ui-bundle.js"></script>
+  <script src="https://unpkg.com/swagger-ui-dist@5.10.5/swagger-ui-standalone-preset.js"></script>
+  <script>
+    window.onload = function() {
+      const ui = SwaggerUIBundle({
+        url: '{{OPENAPI_URL}}',
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIStandalonePreset
+        ],
+        plugins: [
+          SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: "StandaloneLayout"
+      });
+    };
+  </script>
+</body>
+</html>`;
+export function createDocsRouter<
+  TCustomContext extends object = Record<string, never>,
+>(
+  config: Record<string, Router<TCustomContext> | Router<TCustomContext>[]>,
+  options: CreateDocsRouterOptions = {},
+): Router<TCustomContext> {
+  const spec = generateOpenAPISpec(config, options);
+  // openapiPath should be relative (without leading slash) so it works correctly when mounted
+  const openapiPathOption = options.openapiPath || "openapi.json";
+  const openapiPath = openapiPathOption.startsWith("/")
+    ? openapiPathOption.slice(1)
+    : openapiPathOption;
+  const enableDocs = options.enableDocs !== false; // Default to true
+  // Use router() function to create a router with tRPC-style API
+  const docsRouterConfig: Record<string, any> = {};
+  // Serve OpenAPI spec as JSON
+  const openapiSpecPath = `/${openapiPath}`;
+  docsRouterConfig[openapiSpecPath] = publicProcedure
+    .input({})
+    .output(z.any())
+    .get(() => {
+      return ok(spec);
+    });
+  // Serve interactive documentation (Swagger UI)
+  if (enableDocs) {
+    docsRouterConfig["/"] = publicProcedure
+      .input({})
+      .get(async (opts) => {
+        // Access Bun context via ctx.bun
+        const bunCtx = (opts.ctx as any).bun;
+        const requestUrl = new URL(bunCtx.req.url);
+        const baseUrl = requestUrl.origin;
+        // Get the pathname of the current request
+        const currentPath = requestUrl.pathname;
+        // Remove trailing slash if present
+        const basePath =
+          currentPath.endsWith("/") && currentPath !== "/"
+            ? currentPath.slice(0, -1)
+            : currentPath;
+        // Construct openapi URL at the same mount level
+        const openapiUrl = `${baseUrl}${basePath}/${openapiPath}`;
+        const html = SWAGGER_UI_HTML.replace("{{OPENAPI_URL}}", openapiUrl);
+        // Return HTML response with correct content type
+        return ok(
+          new Response(html, {
+            headers: { "Content-Type": "text/html" },
+          }),
+        );
+      });
+  }
+  return router<TCustomContext>(docsRouterConfig);
+}

package/src/index.ts ADDED Viewed

@@ -0,0 +1,142 @@
+import {
+  Router as BaseRouter,
+  router as baseRouter,
+  createRouter as baseCreateRouter,
+  mergeRouters as baseMergeRouters,
+} from "@alt-stack/server-core";
+import type { BunBaseContext } from "./types.ts";
+// Re-export everything from server-core except Router and router utilities (which we override)
+export {
+  // Init
+  init,
+  publicProcedure,
+  default400ErrorSchema,
+  default500ErrorSchema,
+  // Result utilities
+  ok,
+  err,
+  isOk,
+  isErr,
+  map,
+  flatMap,
+  mapError,
+  catchError,
+  unwrap,
+  unwrapOr,
+  unwrapOrElse,
+  match,
+  fold,
+  tryCatch,
+  tryCatchAsync,
+  isResultError,
+  assertResultError,
+  ResultAggregateError,
+  TaggedError,
+  // Middleware
+  createMiddleware,
+  createMiddlewareWithErrors,
+  middlewareMarker,
+  middlewareOk,
+  // Procedure builders
+  BaseProcedureBuilder,
+  ProcedureBuilder,
+  // OpenAPI
+  generateOpenAPISpec,
+  // Validation
+  validateInput,
+  parseSchema,
+  mergeInputs,
+  // Telemetry
+  resolveTelemetryConfig,
+  shouldIgnoreRoute,
+  initTelemetry,
+  createRequestSpan,
+  endSpanWithError,
+  setSpanOk,
+  // Error extraction
+  extractTagsFromSchema,
+  findHttpStatusForError,
+} from "@alt-stack/server-core";
+// Re-export all types from server-core
+export type {
+  Result,
+  Ok,
+  Err,
+  ResultError,
+  InferErrorTag,
+  InferErrorTags,
+  NarrowError,
+  InitOptions,
+  InitResult,
+  MiddlewareFunction,
+  MiddlewareBuilder,
+  MiddlewareResult,
+  MiddlewareResultSuccess,
+  MiddlewareFunctionWithErrors,
+  MiddlewareBuilderWithErrors,
+  MiddlewareBuilderWithErrorsStaged,
+  AnyMiddlewareBuilderWithErrors,
+  AnyMiddlewareFunctionWithErrors,
+  Overwrite,
+  OpenAPISpec,
+  GenerateOpenAPISpecOptions,
+  OpenAPIPathItem,
+  OpenAPIOperation,
+  OpenAPIParameter,
+  OpenAPIRequestBody,
+  OpenAPIResponse,
+  ParseResult,
+  StructuredInput,
+  TelemetryConfig,
+  TelemetryOption,
+  ResolvedTelemetryConfig,
+  Span,
+  InputConfig,
+  TypedContext,
+  BaseContext,
+  InferInput,
+  Procedure,
+  ReadyProcedure,
+  PendingProcedure,
+} from "@alt-stack/server-core";
+// Pre-typed Router with Bun context baked in
+export class Router<
+  TCustomContext extends BunBaseContext = BunBaseContext,
+> extends BaseRouter<TCustomContext> {}
+/**
+ * Pre-typed router function with Bun context as default.
+ * Routes defined with this function will have `ctx.bun` properly typed.
+ */
+export function router<TCustomContext extends BunBaseContext = BunBaseContext>(
+  config: Parameters<typeof baseRouter<TCustomContext>>[0],
+): Router<TCustomContext> {
+  return baseRouter<TCustomContext>(config) as Router<TCustomContext>;
+}
+/**
+ * Pre-typed createRouter function with Bun context as default.
+ */
+export function createRouter<TCustomContext extends BunBaseContext = BunBaseContext>(
+  config?: Record<string, Router<TCustomContext> | Router<TCustomContext>[]>,
+): Router<TCustomContext> {
+  return baseCreateRouter<TCustomContext>(config) as Router<TCustomContext>;
+}
+/**
+ * Pre-typed mergeRouters function with Bun context as default.
+ */
+export function mergeRouters<TCustomContext extends BunBaseContext = BunBaseContext>(
+  ...routers: Router<TCustomContext>[]
+): Router<TCustomContext> {
+  return baseMergeRouters<TCustomContext>(...routers) as Router<TCustomContext>;
+}
+// Export Bun-specific functionality
+export { createServer } from "./server.ts";
+export { createDocsRouter } from "./docs.ts";
+export type { CreateDocsRouterOptions } from "./docs.ts";
+export type { BunBaseContext, BunServer } from "./types.ts";

package/src/router.ts ADDED Viewed

@@ -0,0 +1,100 @@
+import type { BunServer } from "./types.ts";
+/**
+ * Route definition for internal routing
+ */
+interface RouteDefinition {
+  method: string;
+  path: string;
+  pattern: RegExp;
+  paramNames: string[];
+  handler: (
+    req: Request,
+    params: Record<string, string>,
+    server: BunServer,
+  ) => Promise<Response>;
+}
+/**
+ * Simple router for Bun that handles path matching and parameter extraction.
+ * Converts OpenAPI-style paths ({param}) to regex patterns for matching.
+ */
+export class BunRouter {
+  private routes: RouteDefinition[] = [];
+  /**
+   * Register a route handler
+   * @param method HTTP method (GET, POST, PUT, PATCH, DELETE)
+   * @param path OpenAPI-style path (e.g., /users/{id})
+   * @param handler Request handler function
+   */
+  register(
+    method: string,
+    path: string,
+    handler: (
+      req: Request,
+      params: Record<string, string>,
+      server: BunServer,
+    ) => Promise<Response>,
+  ): void {
+    const { pattern, paramNames } = this.compilePath(path);
+    this.routes.push({ method, path, pattern, paramNames, handler });
+  }
+  /**
+   * Match a request to a registered route and execute its handler
+   * @param req The incoming Request
+   * @param server The Bun server instance
+   * @returns Response if a route matches, null otherwise
+   */
+  async handle(req: Request, server: BunServer): Promise<Response | null> {
+    const url = new URL(req.url);
+    const method = req.method;
+    const pathname = url.pathname;
+    for (const route of this.routes) {
+      if (route.method !== method) continue;
+      const match = pathname.match(route.pattern);
+      if (!match) continue;
+      // Extract parameters from the match
+      const params: Record<string, string> = {};
+      route.paramNames.forEach((name, index) => {
+        params[name] = decodeURIComponent(match[index + 1] ?? "");
+      });
+      return route.handler(req, params, server);
+    }
+    return null; // No matching route
+  }
+  /**
+   * Compile an OpenAPI-style path to a regex pattern
+   * Examples:
+   * - /users -> /^\/users$/
+   * - /users/{id} -> /^\/users\/([^\/]+)$/
+   * - /items/{category}/{id} -> /^\/items\/([^\/]+)\/([^\/]+)$/
+   */
+  private compilePath(path: string): {
+    pattern: RegExp;
+    paramNames: string[];
+  } {
+    const paramNames: string[] = [];
+    // Escape special regex characters except { and }
+    let regexStr = path.replace(/[.+?^$|()[\]\\]/g, "\\$&");
+    // Replace {param} with capture groups
+    regexStr = regexStr.replace(/\{([^}]+)\}/g, (_, paramName) => {
+      paramNames.push(paramName);
+      return "([^/]+)";
+    });
+    // Anchor the pattern
+    const pattern = new RegExp(`^${regexStr}$`);
+    return { pattern, paramNames };
+  }
+}