@bajustone/fortress 1.0.0-rc.1

package/src/express/validated.test.ts

@@ -0,0 +1,86 @@
+import type { ExpressRequestLike, InferOutput } from './validated';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { obj, str } from '../core/schema-builder';
+import { vBody, vParam, vQuery } from './validated';
+
+const CreateUserBody = obj({ name: str(), email: str() }, 'name', 'email');
+const IdParam = obj({ id: str('User ID') }, 'id');
+const SearchQuery = obj({ q: str('Search query'), page: str() }, 'q');
+
+describe('vBody', () => {
+  it('returns parsed body when valid', async () => {
+    const req: ExpressRequestLike = { body: { name: 'Alice', email: 'alice@test.com' } };
+    const data = await vBody(req, CreateUserBody);
+    expect(data).toEqual({ name: 'Alice', email: 'alice@test.com' });
+  });
+
+  it('throws VALIDATION_ERROR when body is missing required fields', async () => {
+    const req: ExpressRequestLike = { body: { name: 'Alice' } };
+    await expect(vBody(req, CreateUserBody)).rejects.toMatchObject({
+      code: 'VALIDATION_ERROR',
+      statusCode: 422,
+    });
+  });
+
+  it('throws VALIDATION_ERROR when body is undefined', async () => {
+    const req: ExpressRequestLike = {};
+    await expect(vBody(req, CreateUserBody)).rejects.toMatchObject({
+      code: 'VALIDATION_ERROR',
+      statusCode: 422,
+    });
+  });
+});
+
+describe('vParam', () => {
+  it('returns route params when valid', async () => {
+    const req: ExpressRequestLike = { params: { id: '42' } };
+    const data = await vParam(req, IdParam);
+    expect(data.id).toBe('42');
+  });
+
+  it('throws VALIDATION_ERROR when required param missing', async () => {
+    const req: ExpressRequestLike = { params: {} };
+    await expect(vParam(req, IdParam)).rejects.toMatchObject({
+      code: 'VALIDATION_ERROR',
+      statusCode: 422,
+    });
+  });
+});
+
+describe('vQuery', () => {
+  it('returns query parameters when valid', async () => {
+    const req: ExpressRequestLike = { query: { q: 'hello' } };
+    const data = await vQuery(req, SearchQuery);
+    expect(data.q).toBe('hello');
+  });
+
+  it('throws VALIDATION_ERROR when required query field missing', async () => {
+    const req: ExpressRequestLike = { query: {} };
+    await expect(vQuery(req, SearchQuery)).rejects.toMatchObject({
+      code: 'VALIDATION_ERROR',
+      statusCode: 422,
+    });
+  });
+});
+
+describe('type inference', () => {
+  it('infers vBody return type from schema', () => {
+    const fn = (r: ExpressRequestLike) => vBody(r, CreateUserBody);
+    expectTypeOf(fn).returns.resolves.toEqualTypeOf<{ name: string; email: string }>();
+  });
+
+  it('infers vParam return type from schema', () => {
+    const fn = (r: ExpressRequestLike) => vParam(r, IdParam);
+    expectTypeOf(fn).returns.resolves.toEqualTypeOf<{ id: string }>();
+  });
+
+  it('infers vQuery return type from schema', () => {
+    const fn = (r: ExpressRequestLike) => vQuery(r, SearchQuery);
+    expectTypeOf(fn).returns.resolves.toEqualTypeOf<{ q: string; page?: string }>();
+  });
+
+  it('exports InferOutput utility type', () => {
+    type Expected = InferOutput<typeof CreateUserBody>;
+    expectTypeOf<Expected>().toEqualTypeOf<{ name: string; email: string }>();
+  });
+});

package/src/express/validated.ts

@@ -0,0 +1,99 @@
+/**
+ * Typed extraction-and-validation helpers for Express handlers.
+ *
+ * These helpers extract request data (body, params, query) **and validate
+ * it at runtime** against the supplied Standard Schema. On success they
+ * return the parsed value with full TypeScript inference; on failure they
+ * throw `FortressError('VALIDATION_ERROR', 422)` — the same shape every
+ * fortress-managed endpoint produces — so the existing Express error
+ * handler (`createErrorHandler`) formats it identically.
+ *
+ * Works with any Standard Schema V1 library: Zod, Valibot, ArkType, or
+ * fortress's built-in schema builders.
+ *
+ * Assumes body-parsing middleware (e.g. `app.use(express.json())`) has
+ * already populated `req.body` for `vBody` to read.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { vBody, vParam, vQuery, createErrorHandler } from '@bajustone/fortress/express';
+ * import { obj, str } from '@bajustone/fortress';
+ *
+ * const app = express();
+ * app.use(express.json());
+ *
+ * const Body  = obj({ name: str() }, 'name');
+ * const Param = obj({ id: str() }, 'id');
+ *
+ * app.patch('/users/:id', async (req, res, next) => {
+ *   try {
+ *     const { id }   = await vParam(req, Param);
+ *     const { name } = await vBody(req, Body);
+ *     res.json({ id, name });
+ *   }
+ *   catch (err) { next(err); }
+ * });
+ *
+ * app.use(createErrorHandler());
+ * ```
+ *
+ * Validation runs per call, so the first failing helper throws and any
+ * downstream helpers in the same handler do not run. If you need to
+ * aggregate body+query+params issues into a single response, use the
+ * framework-agnostic `validateRequest` from `@bajustone/fortress` instead.
+ */
+
+import type { StandardSchemaV1 } from '../core/standard-schema';
+import { validateValue } from '../core/validation';
+
+/** Infer the output type of a Standard Schema V1 schema. */
+export type InferOutput<T extends StandardSchemaV1> = StandardSchemaV1.InferOutput<T>;
+
+/**
+ * Structural shape of an Express `Request` accepted by these helpers.
+ * Defined locally instead of importing from `express` so fortress can ship
+ * without a hard `express` dependency. Compatible by structural typing with
+ * the real `express.Request` — consumers pass their `req` directly.
+ */
+export interface ExpressRequestLike {
+  body?: unknown;
+  params?: unknown;
+  query?: unknown;
+}
+
+/**
+ * Extract and validate the request body. Assumes body-parsing middleware
+ * (e.g. `express.json()`) populated `req.body`. Returns the parsed value
+ * typed as `InferOutput<T>`, or throws `FortressError('VALIDATION_ERROR', 422)`.
+ */
+export async function vBody<T extends StandardSchemaV1>(
+  req: ExpressRequestLike,
+  schema: T,
+): Promise<InferOutput<T>> {
+  return validateValue(schema, req.body, 'body');
+}
+
+/**
+ * Extract and validate route parameters from `req.params`. Returns the
+ * parsed value typed as `InferOutput<T>`, or throws
+ * `FortressError('VALIDATION_ERROR', 422)`.
+ */
+export async function vParam<T extends StandardSchemaV1>(
+  req: ExpressRequestLike,
+  schema: T,
+): Promise<InferOutput<T>> {
+  return validateValue(schema, req.params, 'params');
+}
+
+/**
+ * Extract and validate query parameters from `req.query`. Returns the
+ * parsed value typed as `InferOutput<T>`, or throws
+ * `FortressError('VALIDATION_ERROR', 422)`.
+ */
+export async function vQuery<T extends StandardSchemaV1>(
+  req: ExpressRequestLike,
+  schema: T,
+): Promise<InferOutput<T>> {
+  return validateValue(schema, req.query, 'query');
+}

package/src/fetcher/index.ts

@@ -0,0 +1,81 @@
+/**
+ * Re-export of `@bajustone/fetcher` — the schema-validated fetch client and
+ * schema builder that power fortress's own request validation (and, in later
+ * phases, its outbound HTTP).
+ *
+ * Surfaced here so consumers can use the exact same toolkit fortress uses
+ * internally — authoring endpoint schemas with the same builder, building
+ * their own validated outbound clients — without installing
+ * `@bajustone/fetcher` as a separate dependency.
+ *
+ * - Flat root re-export: `createFetch`, middleware (`retry`, `timeout`,
+ *   `authBearer`, …), error classes, and types.
+ * - `schema` namespace: the schema builder (`object`, `string`, `integer`,
+ *   `optional`, `email`, `uuid`, `discriminatedUnion`, `ref`, `compile`, …).
+ * - `openapi` namespace: `fromOpenAPI`, `fromJSONSchema`, `extractRouteSchemas`, …
+ * - `specTools` namespace: `coverage`, `lintSpec`.
+ *
+ * @example
+ * ```ts
+ * import { createFetch, schema } from '@bajustone/fortress/fetcher';
+ *
+ * const Login = schema.object({ email: schema.email(), password: schema.string() });
+ * const api = createFetch({ baseUrl: 'https://api.example.com' });
+ * ```
+ *
+ * @module
+ */
+
+export {
+  authBearer,
+  bearerWithRefresh,
+  cookieAuth,
+  createFetch,
+  extractErrorMessage,
+  FetcherAbortError,
+  FetcherHTTPError,
+  FetcherNetworkError,
+  FetcherRequestError,
+  FetcherTimeoutError,
+  FetcherValidationError,
+  parseSetCookie,
+  retry,
+  timeout,
+  withInputType,
+} from '@bajustone/fetcher';
+export type {
+  BearerWithRefreshOptions,
+  CookieAuthOptions,
+  ExcludeMatcher,
+  ExtractPathParams,
+  FetchConfig,
+  FetcherError,
+  FetcherErrorLocation,
+  FetchFn,
+  HttpMethod,
+  InferOutput,
+  InferRoutesFromSpec,
+  InferSchema,
+  JSONSchemaToType,
+  MethodShortcutFn,
+  Middleware,
+  PathsToRoutes,
+  QueryDescriptor,
+  QuerySerializer,
+  ResultData,
+  RetryOptions,
+  RouteDefinition,
+  Routes,
+  Schema,
+  SchemaOf,
+  StandardSchemaV1,
+  StandardSchemaV1Issue,
+  StandardSchemaV1PathSegment,
+  StandardSchemaV1Result,
+  TypedFetchFn,
+  TypedFetchPromise,
+  TypedResponse,
+} from '@bajustone/fetcher';
+export * as openapi from '@bajustone/fetcher/openapi';
+export * as schema from '@bajustone/fetcher/schema';
+export * as specTools from '@bajustone/fetcher/spec-tools';

package/src/hono/convert-routes.test.ts

@@ -0,0 +1,220 @@
+import type { JSONSchema } from '../core/json-schema';
+import type { ExternalRoute } from './convert-routes';
+import { describe, expect, it } from 'vitest';
+import { convertRoutes } from './convert-routes';
+
+/** Passthrough converter — returns whatever it receives as JSONSchema. */
+const identity = (schema: unknown): JSONSchema => schema as JSONSchema;
+
+/** Tracking converter — records calls and returns the input. */
+function trackingConverter(): { converter: (s: unknown) => JSONSchema; calls: unknown[] } {
+  const calls: unknown[] = [];
+  return {
+    converter: (s: unknown) => {
+      calls.push(s);
+      return s as JSONSchema;
+    },
+    calls,
+  };
+}
+
+const GET_HEALTH: ExternalRoute = {
+  method: 'get',
+  path: '/health',
+  tags: ['Health'],
+  summary: 'Health check',
+  responses: {
+    200: {
+      description: 'OK',
+      content: { 'application/json': { schema: { type: 'object', properties: { status: { type: 'string' } } } } },
+    },
+  },
+};
+
+const POST_LOGIN: ExternalRoute = {
+  method: 'post',
+  path: '/login',
+  tags: ['Auth'],
+  summary: 'Login',
+  security: [{ Bearer: [] }],
+  request: {
+    body: {
+      content: {
+        'application/json': {
+          schema: { type: 'object', properties: { email: { type: 'string' }, password: { type: 'string' } } },
+        },
+      },
+    },
+  },
+  responses: {
+    200: { description: 'Login successful', content: { 'application/json': { schema: { type: 'object' } } } },
+    401: { description: 'Invalid credentials' },
+  },
+};
+
+const GET_USER: ExternalRoute = {
+  method: 'get',
+  path: '/users/{id}',
+  tags: ['Users'],
+  summary: 'Get user by ID',
+  security: [{ Bearer: [] }],
+  request: {
+    params: { type: 'object', properties: { id: { type: 'integer' } }, required: ['id'] },
+  },
+  responses: {
+    200: { description: 'User found', content: { 'application/json': { schema: { type: 'object' } } } },
+  },
+};
+
+const LIST_ITEMS: ExternalRoute = {
+  method: 'get',
+  path: '/items',
+  summary: 'List items',
+  request: {
+    query: { type: 'object', properties: { page: { type: 'integer' }, limit: { type: 'integer' } } },
+  },
+  responses: {
+    200: { description: 'Items list' },
+  },
+};
+
+describe('convertRoutes', () => {
+  it('converts a simple GET route', () => {
+    const [ep] = convertRoutes([GET_HEALTH], { schemaConverter: identity });
+
+    expect(ep.method).toBe('GET');
+    expect(ep.path).toBe('/health');
+    expect(ep.handler).toBe('get_health');
+    expect(ep.meta?.tags).toEqual(['Health']);
+    expect(ep.meta?.summary).toBe('Health check');
+    expect(ep.responses?.[200]?.description).toBe('OK');
+    expect(ep.responses?.[200]?.schema).toEqual({ type: 'object', properties: { status: { type: 'string' } } });
+    expect(ep.input).toBeUndefined();
+  });
+
+  it('converts a POST route with body and security', () => {
+    const [ep] = convertRoutes([POST_LOGIN], { schemaConverter: identity });
+
+    expect(ep.method).toBe('POST');
+    expect(ep.path).toBe('/login');
+    expect(ep.meta?.security).toEqual(['bearer']);
+    expect(ep.input?.body).toEqual({
+      type: 'object',
+      properties: { email: { type: 'string' }, password: { type: 'string' } },
+    });
+    expect(ep.responses?.[200]?.description).toBe('Login successful');
+    expect(ep.responses?.[401]?.description).toBe('Invalid credentials');
+    expect(ep.responses?.[401]?.schema).toBeUndefined();
+  });
+
+  it('converts {param} to :param in paths', () => {
+    const [ep] = convertRoutes([GET_USER], { schemaConverter: identity });
+
+    expect(ep.path).toBe('/users/:id');
+    expect(ep.input?.params).toEqual({
+      type: 'object',
+      properties: { id: { type: 'integer' } },
+      required: ['id'],
+    });
+  });
+
+  it('converts query parameters', () => {
+    const [ep] = convertRoutes([LIST_ITEMS], { schemaConverter: identity });
+
+    expect(ep.input?.query).toEqual({
+      type: 'object',
+      properties: { page: { type: 'integer' }, limit: { type: 'integer' } },
+    });
+  });
+
+  it('applies prefix to paths', () => {
+    const endpoints = convertRoutes([GET_HEALTH, GET_USER], {
+      schemaConverter: identity,
+      prefix: '/api/v1',
+    });
+
+    expect(endpoints[0].path).toBe('/api/v1/health');
+    expect(endpoints[0].handler).toBe('get_api_v1_health');
+    expect(endpoints[1].path).toBe('/api/v1/users/:id');
+  });
+
+  it('strips trailing slash from prefix', () => {
+    const [ep] = convertRoutes([GET_HEALTH], {
+      schemaConverter: identity,
+      prefix: '/api/v1/',
+    });
+
+    expect(ep.path).toBe('/api/v1/health');
+  });
+
+  it('calls schemaConverter for every schema', () => {
+    const { converter, calls } = trackingConverter();
+
+    convertRoutes([POST_LOGIN], { schemaConverter: converter });
+
+    // body schema + 200 response schema (401 has no schema)
+    expect(calls).toHaveLength(2);
+  });
+
+  it('calls schemaConverter for params and query', () => {
+    const route: ExternalRoute = {
+      method: 'get',
+      path: '/items/{id}',
+      request: {
+        params: { type: 'object', properties: { id: { type: 'string' } } },
+        query: { type: 'object', properties: { expand: { type: 'boolean' } } },
+      },
+      responses: { 200: { description: 'OK' } },
+    };
+
+    const { converter, calls } = trackingConverter();
+    convertRoutes([route], { schemaConverter: converter });
+
+    // params + query (no body, no response schema)
+    expect(calls).toHaveLength(2);
+  });
+
+  it('maps security schemes correctly', () => {
+    const routes: ExternalRoute[] = [
+      { ...GET_HEALTH, security: [{ Bearer: [] }] },
+      { ...GET_HEALTH, path: '/basic', security: [{ BasicAuth: [] }] },
+      { ...GET_HEALTH, path: '/apikey', security: [{ ApiKeyAuth: [] }] },
+      { ...GET_HEALTH, path: '/public', security: [{}] },
+    ];
+
+    const endpoints = convertRoutes(routes, { schemaConverter: identity });
+
+    expect(endpoints[0].meta?.security).toEqual(['bearer']);
+    expect(endpoints[1].meta?.security).toEqual(['basic']);
+    expect(endpoints[2].meta?.security).toEqual(['apiKey']);
+    expect(endpoints[3].meta?.security).toEqual(['none']);
+  });
+
+  it('handles deprecated routes', () => {
+    const route: ExternalRoute = { ...GET_HEALTH, deprecated: true };
+    const [ep] = convertRoutes([route], { schemaConverter: identity });
+
+    expect(ep.meta?.deprecated).toBe(true);
+  });
+
+  it('converts multiple routes at once', () => {
+    const endpoints = convertRoutes(
+      [GET_HEALTH, POST_LOGIN, GET_USER, LIST_ITEMS],
+      { schemaConverter: identity },
+    );
+
+    expect(endpoints).toHaveLength(4);
+    expect(endpoints.map(e => e.method)).toEqual(['GET', 'POST', 'GET', 'GET']);
+  });
+
+  it('skips invalid HTTP methods', () => {
+    const route: ExternalRoute = { ...GET_HEALTH, method: 'OPTIONS' };
+    const endpoints = convertRoutes([route], { schemaConverter: identity });
+
+    expect(endpoints).toHaveLength(0);
+  });
+
+  it('returns empty array for empty input', () => {
+    expect(convertRoutes([], { schemaConverter: identity })).toEqual([]);
+  });
+});

package/src/hono/convert-routes.ts

@@ -0,0 +1,196 @@
+/**
+ * Convert external route definitions (e.g., from @hono/zod-openapi createRoute)
+ * into Fortress EndpointDefinitions.
+ *
+ * Schema-library agnostic — the user provides a converter function
+ * that turns their schema objects into JSON Schema.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { convertRoutes } from '@bajustone/fortress/hono';
+ * import { loginRoute, listUsersRoute } from './modules/auth/routes';
+ *
+ * const endpoints = convertRoutes(
+ *   [loginRoute, listUsersRoute],
+ *   { prefix: '/api/v1/auth', schemaConverter: z.toJSONSchema },
+ * );
+ * ```
+ */
+
+import type { EndpointDefinition, EndpointInput, EndpointResponse, HttpMethod, SecurityRequirement } from '../core/endpoint';
+import type { JSONSchema } from '../core/json-schema';
+
+const TRAILING_SLASH_REGEX = /\/$/;
+
+/** A function that converts a schema object (Zod, Valibot, etc.) to JSON Schema. */
+export type ToJSONSchemaConverter = (schema: unknown) => JSONSchema;
+
+/**
+ * Generic route shape matching what `createRoute` from `@hono/zod-openapi` returns.
+ * No dependency on any specific framework or schema library.
+ */
+export interface ExternalRoute {
+  method: string;
+  path: string;
+  tags?: string[];
+  summary?: string;
+  description?: string;
+  deprecated?: boolean;
+  security?: Array<Record<string, string[]>>;
+  request?: {
+    body?: { content: { 'application/json': { schema: unknown } } };
+    params?: unknown;
+    query?: unknown;
+  };
+  responses: Record<number | string, {
+    description: string;
+    content?: { 'application/json': { schema: unknown } };
+  }>;
+}
+
+/** Options accepted by {@link convertRoutes}. */
+export interface ConvertRoutesOptions {
+  /** Convert your schema objects to JSON Schema (e.g., `z.toJSONSchema` for Zod v4). */
+  schemaConverter: ToJSONSchemaConverter;
+  /** Path prefix to prepend (e.g., '/api/v1/auth'). */
+  prefix?: string;
+}
+
+const RE_LEADING_SLASH = /^\//;
+const RE_PARAM_BRACE = /\{(\w+)\}/g;
+const RE_SLASH = /\//g;
+const RE_NON_WORD = /\W/g;
+
+/** Convert OpenAPI `{param}` path to Express-style `:param`. */
+function fromOpenAPIPath(path: string): string {
+  return path.replace(RE_PARAM_BRACE, ':$1');
+}
+
+/** Generate a handler/operationId from method + path. */
+function toOperationId(method: string, path: string): string {
+  const normalized = path
+    .replace(RE_LEADING_SLASH, '')
+    .replace(RE_PARAM_BRACE, '$1')
+    .replace(RE_SLASH, '_')
+    .replace(RE_NON_WORD, '_');
+  return `${method.toLowerCase()}_${normalized}`;
+}
+
+const VALID_METHODS = new Set<HttpMethod>(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']);
+
+/** Reverse map from security scheme names to SecurityRequirement. */
+const SECURITY_REVERSE: Record<string, SecurityRequirement> = {
+  bearer: 'bearer',
+  bearerauth: 'bearer',
+  basic: 'basic',
+  basicauth: 'basic',
+  apikey: 'apiKey',
+  apikeyauth: 'apiKey',
+};
+
+function mapSecurity(security: Array<Record<string, string[]>>): SecurityRequirement[] {
+  const result: SecurityRequirement[] = [];
+  for (const entry of security) {
+    const keys = Object.keys(entry);
+    if (keys.length === 0) {
+      result.push('none');
+      continue;
+    }
+    for (const key of keys) {
+      const mapped = SECURITY_REVERSE[key.toLowerCase()];
+      if (mapped && !result.includes(mapped)) {
+        result.push(mapped);
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Convert an array of external route definitions into Fortress EndpointDefinitions.
+ *
+ * The `schemaConverter` is called for every schema object encountered in request/response
+ * definitions. Fortress never imports or depends on your schema library.
+ */
+export function convertRoutes(
+  routes: ExternalRoute[],
+  options: ConvertRoutesOptions,
+): EndpointDefinition[] {
+  const { schemaConverter, prefix } = options;
+  const result: EndpointDefinition[] = [];
+
+  for (const route of routes) {
+    const method = route.method.toUpperCase() as HttpMethod;
+    if (!VALID_METHODS.has(method))
+      continue;
+
+    const rawPath = prefix ? `${prefix.replace(TRAILING_SLASH_REGEX, '')}${route.path}` : route.path;
+    const path = fromOpenAPIPath(rawPath);
+    const handler = toOperationId(method, rawPath);
+
+    // Meta
+    const meta: EndpointDefinition['meta'] = {
+      summary: route.summary ?? '',
+    };
+    if (route.tags)
+      meta.tags = route.tags;
+    if (route.description)
+      meta.description = route.description;
+    if (route.deprecated)
+      meta.deprecated = true;
+    if (route.security) {
+      const mapped = mapSecurity(route.security);
+      if (mapped.length > 0)
+        meta.security = mapped;
+    }
+
+    // Input
+    const input: EndpointInput = {};
+    let hasInput = false;
+
+    if (route.request?.body?.content?.['application/json']?.schema) {
+      input.body = schemaConverter(route.request.body.content['application/json'].schema);
+      hasInput = true;
+    }
+
+    if (route.request?.params) {
+      input.params = schemaConverter(route.request.params);
+      hasInput = true;
+    }
+
+    if (route.request?.query) {
+      input.query = schemaConverter(route.request.query);
+      hasInput = true;
+    }
+
+    // Responses
+    const responses: Record<number, EndpointResponse> = {};
+    let hasResponses = false;
+
+    for (const [status, resp] of Object.entries(route.responses)) {
+      const entry: EndpointResponse = { description: resp.description };
+      if (resp.content?.['application/json']?.schema) {
+        entry.schema = schemaConverter(resp.content['application/json'].schema);
+      }
+      responses[Number(status)] = entry;
+      hasResponses = true;
+    }
+
+    const endpoint: EndpointDefinition = {
+      method,
+      path,
+      handler,
+      meta,
+    };
+
+    if (hasInput)
+      endpoint.input = input;
+    if (hasResponses)
+      endpoint.responses = responses;
+
+    result.push(endpoint);
+  }
+
+  return result;
+}