appos 0.2.1 → 0.2.3-0

package/dist/exports/tests/packages/appos/src/api/openapi.d.mts

@@ -0,0 +1,271 @@
+import { Container } from "./container.mjs";
+import { AppContext } from "./app-context.mjs";
+import { Express, Request, RequestHandler } from "ultimate-express";
+import { z } from "zod";
+import * as _node_modules_zod_openapi_dist_components_B1DX_zYv_mjs0 from "#node_modules/zod-openapi/dist/components-B1DX_zYv.mjs";
+
+//#region src/api/openapi.d.ts
+declare const appDir: string;
+/**
+ * Utility type to enforce exact type matching (no extra properties).
+ * This uses a tuple check to prevent objects with extra keys from being assigned.
+ * Arrays are handled specially to avoid treating numeric indices as object keys.
+ */
+type Exact<T, Expected> = [T] extends [Expected] ? [Expected] extends [T] ? T : T extends readonly unknown[] ? Expected extends readonly unknown[] ? T extends readonly (infer TItem)[] ? Expected extends readonly (infer ExpectedItem)[] ? readonly Exact<TItem, ExpectedItem>[] : T : T : { [K in keyof T]: K extends keyof Expected ? Exact<T[K], Expected[K]> : ["Error: unexpected key", K] } : { [K in keyof T]: K extends keyof Expected ? Exact<T[K], Expected[K]> : ["Error: unexpected key", K] } : T;
+/**
+ * Response marker type for Express compatibility.
+ */
+type ResponseMarker<T = unknown> = {
+  __response: true;
+  status: number;
+  data: T;
+};
+/**
+ * Define typed response builders based on defined response schemas.
+ */
+declare function defineTypedResponses<TResponses extends Record<number, {
+  description: string;
+  schema: z.ZodSchema;
+}>>(responses: TResponses): { [K in keyof TResponses as GetMethodName<K>]: K extends number ? TResponses[K]["schema"] extends z.ZodNull ? () => ResponseMarker<null> : <T extends z.infer<TResponses[K]["schema"]>>(data: Exact<T, z.infer<TResponses[K]["schema"]>>) => ResponseMarker<z.infer<TResponses[K]["schema"]>> : never } & {
+  status: <S extends keyof TResponses & number>(statusCode: S, data: TResponses[S]["schema"] extends z.ZodNull ? undefined : Exact<z.infer<TResponses[S]["schema"]>, z.infer<TResponses[S]["schema"]>>) => ResponseMarker;
+};
+type GetMethodName<K$1> = K$1 extends 200 ? "ok" : K$1 extends 201 ? "created" : K$1 extends 202 ? "accepted" : K$1 extends 204 ? "noContent" : K$1 extends 400 ? "badRequest" : K$1 extends 401 ? "unauthorized" : K$1 extends 403 ? "forbidden" : K$1 extends 404 ? "notFound" : K$1 extends 409 ? "conflict" : K$1 extends 422 ? "unprocessableEntity" : K$1 extends 500 ? "internalServerError" : never;
+/**
+ * Handler parameters with full type safety for request inputs.
+ */
+type HandlerParams<TParams extends z.ZodSchema | undefined = undefined, TQuery extends z.ZodSchema | undefined = undefined, TBody extends z.ZodSchema | undefined = undefined, THeaders extends z.ZodSchema | undefined = undefined, TResponses extends Record<number, {
+  description: string;
+  schema: z.ZodSchema;
+}> = Record<number, {
+  description: string;
+  schema: z.ZodSchema;
+}>> = {
+  ctx: AppContext;
+  body: TBody extends z.ZodSchema ? z.infer<TBody> : unknown;
+  headers: THeaders extends z.ZodSchema ? z.infer<THeaders> : Record<string, string>;
+  params: TParams extends z.ZodSchema ? z.infer<TParams> : Record<string, unknown>;
+  query: TQuery extends z.ZodSchema ? z.infer<TQuery> : Record<string, unknown>;
+  request: Request;
+  response: ReturnType<typeof defineTypedResponses<TResponses>>;
+};
+/**
+ * Helper function to define an OpenAPI endpoint with full type safety.
+ */
+declare function defineOpenAPIEndpoint<TParams extends z.ZodSchema | undefined = undefined, TQuery extends z.ZodSchema | undefined = undefined, TBody extends z.ZodSchema | undefined = undefined, THeaders extends z.ZodSchema | undefined = undefined, TResponses extends Record<number, {
+  description: string;
+  schema: z.ZodSchema;
+}> = Record<number, {
+  description: string;
+  schema: z.ZodSchema;
+}>>(spec: {
+  summary?: string;
+  description?: string;
+  params?: TParams;
+  query?: TQuery;
+  requestBody?: TBody;
+  headers?: THeaders;
+  responses: TResponses;
+  handler: (params: HandlerParams<TParams, TQuery, TBody, THeaders, TResponses>) => Promise<ResponseMarker>;
+}): {
+  summary?: string;
+  description?: string;
+  params?: TParams;
+  query?: TQuery;
+  requestBody?: TBody;
+  headers?: THeaders;
+  responses: TResponses;
+  handler: (params: HandlerParams<TParams, TQuery, TBody, THeaders, TResponses>) => Promise<ResponseMarker>;
+};
+/**
+ * OpenAPI method specification type (for internal use).
+ */
+type OpenAPIMethodSpec = {
+  summary?: string;
+  description?: string;
+  params?: z.ZodSchema;
+  query?: z.ZodSchema;
+  requestBody?: z.ZodSchema;
+  headers?: z.ZodSchema;
+  responses: Record<number, {
+    description: string;
+    schema: z.ZodSchema;
+  }>;
+  handler: (params: HandlerParams<any, any, any, any, any>) => Promise<ResponseMarker>;
+};
+/**
+ * Configuration object for defineOpenApi.
+ */
+type DefineOpenAPIConfig = { [K in "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE"]?: OpenAPIMethodSpec };
+/**
+ * OpenAPI configuration for document-level settings
+ */
+type OpenAPIObjectConfigV31 = {
+  info: {
+    title: string;
+    version: string;
+    description?: string;
+    contact?: {
+      name?: string;
+      email?: string;
+      url?: string;
+    };
+    license?: {
+      name: string;
+      url?: string;
+    };
+  };
+  servers?: Array<{
+    url: string;
+    description?: string;
+  }>;
+  openapi: "3.1.0";
+};
+/**
+ * Simplified config input for defineOpenAPIConfig
+ */
+type DefineOpenAPIConfigInput = {
+  info: OpenAPIObjectConfigV31["info"];
+  servers?: OpenAPIObjectConfigV31["servers"];
+};
+/**
+ * OpenAPI registration format (without path - CLI will add it)
+ */
+type OpenAPIRegistration = {
+  method: "get" | "post" | "put" | "patch" | "delete" | "head";
+  summary?: string;
+  description?: string;
+  request?: {
+    params?: z.ZodSchema;
+    query?: z.ZodSchema;
+    body?: z.ZodSchema;
+    headers?: z.ZodSchema;
+  };
+  responses: Record<number, {
+    description: string;
+    content: {
+      "application/json": {
+        schema: z.ZodSchema;
+      };
+    };
+  }>;
+};
+/**
+ * Return type for defineOpenAPI function
+ */
+type DefineOpenAPIReturn = {
+  handlers: Record<string, RequestHandler>;
+  openAPISpec: OpenAPIRegistration[];
+};
+/**
+ * RFC 9457 compliant validation error response
+ */
+type ValidationErrorResponse = {
+  error: "validation_error";
+  status: number;
+  detail: string;
+  errors: Array<{
+    field: string;
+    message: string;
+    received: unknown;
+  }>;
+};
+/**
+ * Define OpenAPI-based route handlers with full type safety.
+ *
+ * @param config Configuration object with HTTP method specifications
+ * @returns Object containing Express handlers and openAPISpec
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * export default defineOpenAPI({
+ *   GET: {
+ *     summary: "Get user by ID",
+ *     params: z.object({ id: z.uuid() }),
+ *     responses: {
+ *       200: { description: "User data", schema: UserSchema }
+ *     },
+ *     handler: async ({ params, response }) => {
+ *       const user = await getUser(params.id);
+ *       return response.ok(user); // Fully typed!
+ *     }
+ *   },
+ *   POST: {
+ *     summary: "Create user",
+ *     requestBody: CreateUserSchema,
+ *     responses: {
+ *       201: { description: "User created", schema: UserSchema }
+ *     },
+ *     handler: async ({ body, response }) => {
+ *       const user = await createUser(body);
+ *       return response.created(user); // Fully typed!
+ *     }
+ *   }
+ * });
+ * ```
+ */
+declare function defineOpenAPI(config: DefineOpenAPIConfig): DefineOpenAPIReturn;
+/**
+ * Define OpenAPI document configuration with improved DX.
+ *
+ * Only allows specifying info and servers objects, ensuring a consistent
+ * OpenAPI v3.1.0 structure while preventing configuration of other fields.
+ *
+ * @param config Configuration object with info and optional servers
+ * @returns Complete OpenAPI configuration object
+ *
+ * @example
+ * ```typescript
+ * export const openAPIConfig = defineOpenAPIConfig({
+ *   info: {
+ *     title: "My API",
+ *     version: "1.0.0",
+ *     description: "API v1 - Authentication and core features",
+ *     contact: {
+ *       name: "API Support",
+ *       email: "support@example.com",
+ *     },
+ *   },
+ *   servers: [
+ *     {
+ *       url: process.env.API_URL || "http://localhost:8000",
+ *       description: "API Server",
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+declare function defineOpenAPIConfig<TContainer extends Container = Container>(config: (container: TContainer) => DefineOpenAPIConfigInput): (container: TContainer) => OpenAPIObjectConfigV31;
+/**
+ * Route module type for scanned API routes
+ */
+type RouteModule = {
+  path: string;
+  filePath: string;
+  handlers: Record<string, RequestHandler>;
+  openAPISpec: OpenAPIRegistration[];
+  version?: string;
+};
+/**
+ * Generate complete OpenAPI 3.1.0 document from routes using zod-openapi
+ */
+declare function generateOpenAPIDocument(routes: RouteModule[], version: string, config?: DefineOpenAPIConfigInput): _node_modules_zod_openapi_dist_components_B1DX_zYv_mjs0.it;
+/**
+ * Scan routes directory and convert to Express route paths using remix-flat-routes.
+ */
+declare function scanAPIRoutes(container: Container): Promise<RouteModule[]>;
+/**
+ * Register scanned routes with Express app.
+ */
+declare function registerRoutes(app: Express, routes: RouteModule[]): void;
+/**
+ * Write OpenAPI specs to api/public/openapi directory.
+ */
+declare function writeOpenAPISpecs<TContainer extends Container>(container: TContainer, routes: RouteModule[]): Promise<void>;
+/**
+ * Load and register API routes with Express (convenience function).
+ * Also auto-generates OpenAPI specs in development mode.
+ */
+declare function loadAndRegisterAPIRoutes<TContainer extends Container>(app: Express): Promise<void>;
+//#endregion
+export { DefineOpenAPIConfig, DefineOpenAPIConfigInput, DefineOpenAPIReturn, HandlerParams, OpenAPIMethodSpec, OpenAPIObjectConfigV31, OpenAPIRegistration, RouteModule, ValidationErrorResponse, appDir, defineOpenAPI, defineOpenAPIConfig, defineOpenAPIEndpoint, defineTypedResponses, generateOpenAPIDocument, loadAndRegisterAPIRoutes, registerRoutes, scanAPIRoutes, writeOpenAPISpecs };

package/dist/exports/tests/packages/appos/src/api/orm.d.mts

@@ -0,0 +1,13 @@
+import { __export, __reExport } from "../../../../_virtual/rolldown_runtime.mjs";
+import { index, isPgEnum, isPgMaterializedView, isPgSchema, isPgSequence, isPgView, numeric, parsePgArray, parsePgNestedArray, pgEnum, pgMaterializedView, pgPolicy, pgRole, pgSchema, pgSequence, pgTable as pgTable$1, pgTableCreator, pgView, serial, smallint, smallserial, sparsevec, unique, uniqueIndex, uniqueKeyName, withReplicas } from "drizzle-orm/pg-core";
+export * from "drizzle-orm";
+export * from "drizzle-seed";
+
+//#region src/api/orm.d.ts
+declare namespace orm_d_exports {
+  export { index, isPgEnum, isPgMaterializedView, isPgSchema, isPgSequence, isPgView, numeric, parsePgArray, parsePgNestedArray, pgEnum, pgMaterializedView, pgPolicy, pgRole, pgSchema, pgSequence, pgTable$1 as pgTable, pgTableCreator, pgView, serial, smallint, smallserial, sparsevec, unique, uniqueIndex, uniqueKeyName, withReplicas };
+}
+import * as import_drizzle_orm from "drizzle-orm";
+import * as import_drizzle_seed from "drizzle-seed";
+//#endregion
+export { import_drizzle_seed as orm_d_exports };

package/dist/exports/tests/packages/appos/src/api/otel.d.mts

@@ -0,0 +1,40 @@
+import { instrumentation_d_exports } from "../instrumentation.mjs";
+
+//#region src/api/otel.d.ts
+
+/**
+ * Wraps an async function with an OpenTelemetry span for distributed tracing.
+ *
+ * Automatically handles span lifecycle (start/end), error recording, and context propagation.
+ * The span will appear as a child of the currently active span (if any).
+ *
+ * @param tracerName - Fully qualified module path (e.g., "api/routes/payouts", "packages/primitives/mailer")
+ * @param spanName - Operation name following {verb} {object} pattern (e.g., "fetch payouts", "send email")
+ * @param fn - The async function to execute within the span context. Receives span for custom attributes.
+ * @param attributes - Optional span attributes for high-cardinality data (IDs, counts, etc.).
+ *                     Use semantic conventions: https://opentelemetry.io/docs/specs/semconv/
+ * @returns Promise resolving to the function's return value.
+ *
+ * @example
+ * // Basic usage - simple business operation
+ * await withOtelSpan("api/routes/payouts", "fetch payouts", async () => {
+ *   return await db.query.payouts.findMany();
+ * });
+ *
+ * @example
+ * // With attributes and custom span data
+ * const payouts = await withOtelSpan(
+ *   "api/routes/payouts",
+ *   "fetch payouts",
+ *   async (span) => {
+ *     const results = await db.query.payouts.findMany();
+ *     span.setAttribute("payouts.count", results.length);
+ *     span.addEvent("cache.miss");
+ *     return results;
+ *   },
+ *   { "payouts.limit": 100, "payouts.offset": 0 }
+ * );
+ */
+declare function withOtelSpan<T>(fn: (span: instrumentation_d_exports.Span) => Promise<T>, attributes?: Record<string, string | number | boolean>): Promise<T>;
+//#endregion
+export { withOtelSpan };

package/dist/exports/tests/packages/appos/src/api/redis.d.mts

@@ -0,0 +1,34 @@
+import { Logger } from "./logger.mjs";
+import { createClient, createCluster } from "redis";
+
+//#region src/api/redis.d.ts
+type RedisClient = ReturnType<typeof createClient> | ReturnType<typeof createCluster>;
+/**
+ * Options for defining a Redis client.
+ */
+interface DefineRedisClientOptions {
+  /**
+   * Logger instance for error reporting.
+   */
+  logger: Logger;
+  /**
+   * Redis URL(s). Single: "redis://localhost:6379", Cluster: comma-separated URLs
+   */
+  url: string;
+}
+/**
+ * Defines Redis client based on URL format with lazy connection.
+ * Single URL → createClient(), comma-separated URLs → createCluster()
+ *
+ * Algorithm:
+ * 1. Split URL by comma to detect cluster vs single
+ * 2. Create appropriate client type
+ * 3. Attach error handler with label for debugging
+ * 4. Wrap in proxy that auto-connects on first use
+ *
+ * @param opts Options for defining the Redis client.
+ * @returns Redis client that auto-connects on first operation.
+ */
+declare function defineRedisClient(opts: DefineRedisClientOptions): RedisClient;
+//#endregion
+export { DefineRedisClientOptions, RedisClient, defineRedisClient };

package/dist/exports/tests/packages/appos/src/api/redis.mjs

@@ -0,0 +1 @@
+import{createClient as e,createCluster as t}from"redis";export{};

package/dist/exports/tests/packages/appos/src/api/server.mjs

@@ -0,0 +1 @@
+import{RedisStore as e}from"../../../../node_modules/.bun/rate-limit-redis@4.3.1_f1fa5524233c9c60/node_modules/rate-limit-redis/dist/index.mjs";import{defineErrorHandlerMiddleware as t}from"./middleware/error-handler.mjs";import{defineHealthMiddleware as n}from"./middleware/health.mjs";import{defineI18nMiddleware as r}from"./middleware/i18n.mjs";import{defineRequestLoggerMiddleware as i}from"./middleware/request-logger.mjs";import{defineShutdownMiddleware as a}from"./middleware/shutdown.mjs";import{defineTimeoutMiddleware as o}from"./middleware/timeout.mjs";import{loadMiddleware as s}from"./middleware.mjs";import{join as c}from"node:path";import l from"cors";import{rateLimit as u}from"express-rate-limit";import d from"helmet";import{createClient as f}from"redis";import p from"ultimate-express";async function m({container:m}){let h=!1,{host:g=`0.0.0.0`,port:_,timeout:v=3e4,bodyLimit:y=`1mb`,healthPath:b=`/health`,cors:x,helmet:S,rateLimit:C,redisUrl:w}=m.server,T=p();T.locals.container=m;let E=null;if(w&&C)try{E=f({url:w}),E.on(`error`,e=>{m.logger.error({error:e.message},`Redis client error`)}),await E.connect(),m.logger.info(`Connected to Redis for rate limiting`)}catch(e){m.logger.error({error:e instanceof Error?e.message:e},`Failed to connect to Redis, falling back to in-memory rate limiting`),E=null}if(T.use(a(m.logger,()=>h),o(m.logger,v),i(m.logger),n(b)),S!==void 0&&T.use(d(S)),x!==void 0&&T.use(l(x)),C)for(let[t,n]of C.entries()){let r=u({windowMs:n.windowMs??60*1e3,limit:n.limit??100,standardHeaders:n.standardHeaders??`draft-8`,legacyHeaders:n.legacyHeaders??!1,skip:n.skip,keyGenerator:n.keyGenerator,handler:n.handler,message:n.message,statusCode:n.statusCode,requestPropertyName:n.requestPropertyName,skipFailedRequests:n.skipFailedRequests,skipSuccessfulRequests:n.skipSuccessfulRequests,requestWasSuccessful:n.requestWasSuccessful,validate:n.validate,store:E?new e({sendCommand:(...e)=>E.sendCommand(e),prefix:`rl:${t}:`}):n.store});T.use(r)}if(T.use(r(m.i18n),p.json({limit:y}),p.urlencoded({extended:!0,limit:y})),await s(c(process.cwd(),`api`,`middleware`),m,T),T.get(`/`,(e,t)=>{t.json({message:`${m.config.APP_NAME} server is running.`})}),process.env.NODE_ENV!==`production`){let{defineYouchErrorHandler:e}=await import(`./middleware/youch-handler.mjs`);T.use(e(m.logger))}else T.use(t(m.logger));return{app:T,host:g,port:_,async start(){await new Promise((e,t)=>{try{T.listen(_,g,()=>{e()})}catch(e){t(e)}})},async close(){if(h=!0,T.uwsApp.close(),E)try{await E.destroy()}catch(e){m.logger.warn({error:e instanceof Error?e.message:e},`Error disconnecting from Redis`)}}}}export{m as defineServer};