appos 0.3.5-0 → 0.3.7-0

package/dist/exports/tests/api/openapi.d.mts

@@ -1,271 +0,0 @@
-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
-
-/**
- * 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, defineOpenAPI, defineOpenAPIConfig, defineOpenAPIEndpoint, defineTypedResponses, generateOpenAPIDocument, loadAndRegisterAPIRoutes, registerRoutes, scanAPIRoutes, writeOpenAPISpecs };

package/dist/exports/tests/api/openapi.mjs

@@ -1 +0,0 @@
-import{APPOS_DIR as e,FILE_EXT as t,PUBLIC_DIR as n,ROUTES_DIR as r}from"../constants.mjs";import"./app-context.mjs";import{access as i,mkdir as a,writeFile as o}from"node:fs/promises";import{join as s,resolve as c}from"node:path";import{remixRoutesOptionAdapter as l}from"@react-router/remix-routes-option-adapter";import{isEmpty as u}from"es-toolkit/compat";import{flatRoutes as d}from"remix-flat-routes";import{z as f}from"zod";import{createDocument as p}from"zod-openapi";const m=c(n,`openapi`);function h(e){return e.match(/^\/(v\d+)/)?.[1]}function g(e){return e.replace(/:(\w+)/g,`{$1}`)}function _(e,t){let n=g(e),r={summary:t.summary,description:t.description};(t.request?.params||t.request?.query||t.request?.headers)&&(r.requestParams={},t.request.params&&(r.requestParams.path=t.request.params),t.request.query&&(r.requestParams.query=t.request.query),t.request.headers&&(r.requestParams.header=t.request.headers)),t.request?.body&&(r.requestBody={content:{"application/json":{schema:t.request.body}}}),r.responses={};for(let[e,n]of Object.entries(t.responses))r.responses[e]={description:n.description,content:{"application/json":{schema:n.content[`application/json`].schema}}};return{path:n,config:r}}function v(e,t,n){let r={};for(let n of e){if(n.version!==t)continue;let e=n.path.replace(`/${t}`,``)||`/`;for(let t of n.openAPISpec){let{path:n,config:i}=_(e,t);r[n]||(r[n]={}),r[n][t.method]=i}}return p({openapi:`3.1.0`,info:n?.info||{title:`API ${t.toUpperCase()}`,version:t.replace(`v`,``),description:`OpenAPI specification for ${t} API`},servers:n?.servers||[{url:`http://localhost:8000/${t}`,description:process.env.NODE_ENV===`production`?`Production server`:`Development server`}],paths:r})}async function y(n){let a=c(e,r);try{await i(a)}catch(e){return n.logger.error({error:e},`OpenAPI routes directory not found`),[]}let o=await l(t=>d(r,t,{appDir:e,ignoredRouteFiles:[`**/.*`,`**/*.{spec,test}.{ts,tsx}`,`**/*-????????.{js,ts}`]})),s=[];for(let[r,i]of Object.entries(o)){let r=c(e,i.file).replace(/\.ts$/,`.${t}`);try{let t=(await import(r)).default;if(!t||u(t)||/\/openapi.(j|t)s$/.test(r))continue;if(!t?.handlers&&!t?.openAPISpec){n.logger.warn(`Missing default export with 'defineOpenAPI' for '${e}/${i.file}'`);continue}let a=`/${i.path}`;s.push({path:a,filePath:r,handlers:t.handlers,openAPISpec:t.openAPISpec,version:h(a)})}catch(e){n.logger.error(e,`Error loading route ${i.file}:`)}}return s}function b(e,t){for(let n of t)for(let[t,r]of Object.entries(n.handlers))e[t.toLowerCase()](n.path,r)}async function x(n,i){let a=c(e,r,`${i}+/openapi.${t}`);try{let e=(await import(a)).default;return e?e(n):void 0}catch{return}}async function S(e,t){let n=[...new Set(t.map(e=>e.version).filter(Boolean))];n.length>0&&await a(m,{recursive:!0});for(let r of n){let n=v(t,r,await x(e,r));await o(s(m,`${r}.json`),JSON.stringify(n,null,2),`utf-8`)}}async function C(e){let t=await y(e.locals.container);b(e,t),process.env.NODE_ENV!==`production`&&await S(e.locals.container,t)}export{C as loadAndRegisterAPIRoutes};

package/dist/exports/tests/api/orm.d.mts

@@ -1,13 +0,0 @@
-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/api/otel.d.mts

@@ -1,40 +0,0 @@
-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/api/redis.d.mts

@@ -1,34 +0,0 @@
-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/api/redis.mjs

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

package/dist/exports/tests/api/server.mjs

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