@extk/expressive 0.7.1 → 0.8.0

package/README.md

@@ -16,6 +16,29 @@
 
 ---
 
+## Table of Contents
+
+- [What is this?](#what-is-this)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [Error Handling](#error-handling)
+- [OpenAPI / Swagger](#openapi--swagger)
+  - [File uploads](#file-uploads)
+  - [Using Zod schemas for OpenAPI](#using-zod-schemas-for-openapi)
+- [Middleware](#middleware)
+  - [getApiErrorHandlerMiddleware](#getapierrorhandlermiddleware)
+  - [getApiNotFoundMiddleware](#getapinotfoundmiddleware)
+  - [getGlobalNotFoundMiddleware](#getglobalnotfoundmiddleware)
+  - [getGlobalErrorHandlerMiddleware](#getglobalerrorhandlermiddleware)
+  - [getBasicAuthMiddleware](#getbasicauthmiddleware)
+- [silently](#silently)
+- [Logging](#logging)
+- [Utilities](#utilities)
+- [API Response Format](#api-response-format)
+- [License](#license)
+
+---
+
 ## What is this?
 
 `@extk/expressive` is an opinionated toolkit for Express 5 that wires up the things every API needs but nobody wants to set up from scratch:
@@ -171,6 +194,38 @@ addRoute(
 );
 ```
 
+### File uploads
+
+Use `SWG.singleFileSchema` for a single file field, or `SWG.formDataSchema` for a custom multipart body:
+
+```ts
+// single file — field name defaults to 'file', required defaults to true
+addRoute({
+  method: 'post',
+  path: '/upload',
+  oapi: {
+    requestBody: SWG.singleFileSchema(),
+    // requestBody: SWG.singleFileSchema('avatar', true),
+  },
+}, handler);
+
+// custom multipart schema with multiple fields
+addRoute({
+  method: 'post',
+  path: '/upload/rich',
+  oapi: {
+    requestBody: SWG.formDataSchema({
+      type: 'object',
+      properties: {
+        file: { type: 'string', format: 'binary' },
+        title: { type: 'string' },
+      },
+      required: ['file'],
+    }),
+  },
+}, handler);
+```
+
 Configure security schemes via the swagger builder:
 
 ```ts
@@ -261,6 +316,55 @@ addRoute({
 
 This way your Zod schemas serve as the single source of truth for both runtime validation and API documentation.
 
+## Middleware
+
+All middleware factories are returned from `bootstrap()`.
+
+### `getApiErrorHandlerMiddleware(errorMapper?)`
+
+Express error handler for API routes. Catches `ApiError` subclasses, handles malformed JSON, and falls back to `InternalError` for unknown errors. Pass an optional `errorMapper` to map third-party errors (e.g. Zod, Multer) to typed `ApiError` instances.
+
+```ts
+app.use(getApiErrorHandlerMiddleware((err) => {
+  if (err.name === 'ZodError') return new SchemaValidationError('Validation failed').setData(err.issues);
+  return null;
+}));
+```
+
+### `getApiNotFoundMiddleware()`
+
+Returns a JSON `404` response for unmatched API routes.
+
+```ts
+app.use(getApiNotFoundMiddleware());
+// { status: 'error', message: 'GET /unknown not found', errorCode: 'NOT_FOUND' }
+```
+
+### `getGlobalNotFoundMiddleware(content?)`
+
+Returns a plain-text `404`. Useful as the last catch-all for non-API routes. Defaults to `¯\_(ツ)_/¯`.
+
+```ts
+app.use(getGlobalNotFoundMiddleware());
+app.use(getGlobalNotFoundMiddleware('Not found'));
+```
+
+### `getGlobalErrorHandlerMiddleware()`
+
+Minimal error handler that logs and responds with a plain-text `500`. Use this outside of API route groups where JSON responses aren't expected.
+
+### `getBasicAuthMiddleware(basicAuthBase64, realm?)`
+
+Protects a route or the Swagger UI with HTTP Basic auth. Accepts a pre-encoded base64 `user:password` string.
+
+```ts
+expressiveServer()
+  .withSwagger(
+    { config: swaggerDoc },
+    getBasicAuthMiddleware(process.env.SWAGGER_AUTH!, 'API Docs'),
+  )
+```
+
 ## silently
 
 `silently` runs a function — sync or async — and suppresses any errors it throws. Errors are forwarded to `alertHandler` (if configured) or logged via the container logger.

package/dist/index.d.mts

@@ -33,61 +33,85 @@ type Container = {
     alertHandler?: AlertHandler;
 };
 
+type Nullable<T extends string> = T | [T, 'null'] | ['null', T];
 type NumericConfigs = {
     minimum?: number;
     maximum?: number;
-    exclusiveMinimum?: boolean;
-    exclusiveMaximum?: boolean;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
     multipleOf?: number;
 };
 type NumberSchema = {
-    type: 'number';
+    type: Nullable<'number'>;
     format?: 'float' | 'double';
 } & NumericConfigs;
 type IntegerSchema = {
-    type: 'integer';
+    type: Nullable<'integer'>;
     format?: 'int32' | 'int64';
 } & NumericConfigs;
 type StringSchema = {
-    type: 'string';
+    type: Nullable<'string'>;
     minLength?: number;
     maxLength?: number;
     format?: 'date' | 'date-time' | 'password' | 'byte' | 'binary' | 'email' | 'uuid' | 'uri' | 'hostname' | 'ipv4' | 'ipv6' | OtherString;
     pattern?: string;
 };
 type BooleanSchema = {
-    type: 'boolean';
+    type: Nullable<'boolean'>;
+};
+type NullSchema = {
+    type: 'null';
 };
 type ArraySchema = {
-    type: 'array';
-    items: Partial<Schema>;
+    type: Nullable<'array'>;
+    items?: Schema;
     minItems?: number;
     maxItems?: number;
     uniqueItems?: boolean;
 };
 type ObjectSchema = {
-    type: 'object';
+    type: Nullable<'object'>;
     properties?: Record<string, Schema>;
     required?: string[];
     additionalProperties?: boolean | Schema;
     minProperties?: number;
     maxProperties?: number;
 };
-type BaseSchema = ({
-    nullable?: boolean;
-    enum?: unknown[];
+type Discriminator = {
+    propertyName: string;
+    mapping?: Record<string, string>;
+};
+type CommonSchemaProps = {
+    title?: string;
     description?: string;
+    example?: unknown;
     default?: unknown;
-} & (StringSchema | NumberSchema | IntegerSchema | BooleanSchema | ArraySchema | ObjectSchema)) | {
-    $ref: string;
+    enum?: unknown[];
+    const?: unknown;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    deprecated?: boolean;
 };
-type Schema = BaseSchema | {
+type BaseSchema = CommonSchemaProps & (StringSchema | NumberSchema | IntegerSchema | BooleanSchema | NullSchema | ArraySchema | ObjectSchema | {
+    $ref: string;
+});
+type Schema = // circular
+BaseSchema | (CommonSchemaProps & {
     allOf: Schema[];
-} | {
+    discriminator?: Discriminator;
+}) | (CommonSchemaProps & {
     anyOf: Schema[];
-} | {
+    discriminator?: Discriminator;
+}) | (CommonSchemaProps & {
     oneOf: Schema[];
-} | OtherUnknown;
+    discriminator?: Discriminator;
+}) | (CommonSchemaProps & {
+    not: Schema;
+}) | (CommonSchemaProps & {
+    if: Schema;
+    then?: Schema;
+    else?: Schema;
+}) | OtherUnknown;
 type Content = {
     description?: string;
     content?: Partial<Record<ContentType, {
@@ -95,7 +119,7 @@ type Content = {
     }>>;
 };
 type Param = {
-    in: 'path' | 'query' | 'headers';
+    in: 'path' | 'query' | 'header' | 'cookie';
     name: string;
     description: string;
     required: boolean;
@@ -107,6 +131,7 @@ type Servers = {
 }[];
 type PathItem = {
     summary?: string;
+    description?: string;
     requestBody?: Content;
     parameters?: Param[];
     servers?: Servers;
@@ -116,13 +141,14 @@ type PathItem = {
     deprecated?: boolean;
     security?: AuthMethod[];
 };
+/** { BearerAuth: [] } | { OAuth2: ['read', 'write'] } */
 type AuthMethod = Record<string, string[]>;
 type SecurityScheme = {
     type: 'http';
     scheme: 'basic' | 'bearer';
 } | {
     type: 'apiKey';
-    in: 'header';
+    in: 'header' | 'query' | 'cookie';
     name: string;
 } | {
     type: 'openIdConnect';
@@ -234,8 +260,9 @@ declare class SwaggerBuilder {
     withSecuritySchemes(schemes: Record<string, SecurityScheme>): this;
     withSchemas(schemas: Record<string, Schema>): this;
     withDefaultSecurity(globalAuthMethods: AuthMethod[]): this;
-    get(): SwaggerConfig;
+    build(): SwaggerConfig;
 }
+declare function singleFileSchema(field?: string, required?: boolean): Content;
 declare function formDataSchema(schema: Schema): Content;
 declare function jsonSchema(schema: Schema): Content;
 declare function jsonSchemaRef(name: string): Content;
@@ -251,6 +278,7 @@ declare const SWG: {
     formDataSchema: typeof formDataSchema;
     jsonSchema: typeof jsonSchema;
     jsonSchemaRef: typeof jsonSchemaRef;
+    singleFileSchema: typeof singleFileSchema;
     security: (name: string) => AuthMethod;
     securitySchemes: {
         readonly BasicAuth: () => SecurityScheme;

package/dist/index.d.ts

@@ -33,61 +33,85 @@ type Container = {
     alertHandler?: AlertHandler;
 };
 
+type Nullable<T extends string> = T | [T, 'null'] | ['null', T];
 type NumericConfigs = {
     minimum?: number;
     maximum?: number;
-    exclusiveMinimum?: boolean;
-    exclusiveMaximum?: boolean;
+    exclusiveMinimum?: number;
+    exclusiveMaximum?: number;
     multipleOf?: number;
 };
 type NumberSchema = {
-    type: 'number';
+    type: Nullable<'number'>;
     format?: 'float' | 'double';
 } & NumericConfigs;
 type IntegerSchema = {
-    type: 'integer';
+    type: Nullable<'integer'>;
     format?: 'int32' | 'int64';
 } & NumericConfigs;
 type StringSchema = {
-    type: 'string';
+    type: Nullable<'string'>;
     minLength?: number;
     maxLength?: number;
     format?: 'date' | 'date-time' | 'password' | 'byte' | 'binary' | 'email' | 'uuid' | 'uri' | 'hostname' | 'ipv4' | 'ipv6' | OtherString;
     pattern?: string;
 };
 type BooleanSchema = {
-    type: 'boolean';
+    type: Nullable<'boolean'>;
+};
+type NullSchema = {
+    type: 'null';
 };
 type ArraySchema = {
-    type: 'array';
-    items: Partial<Schema>;
+    type: Nullable<'array'>;
+    items?: Schema;
     minItems?: number;
     maxItems?: number;
     uniqueItems?: boolean;
 };
 type ObjectSchema = {
-    type: 'object';
+    type: Nullable<'object'>;
     properties?: Record<string, Schema>;
     required?: string[];
     additionalProperties?: boolean | Schema;
     minProperties?: number;
     maxProperties?: number;
 };
-type BaseSchema = ({
-    nullable?: boolean;
-    enum?: unknown[];
+type Discriminator = {
+    propertyName: string;
+    mapping?: Record<string, string>;
+};
+type CommonSchemaProps = {
+    title?: string;
     description?: string;
+    example?: unknown;
     default?: unknown;
-} & (StringSchema | NumberSchema | IntegerSchema | BooleanSchema | ArraySchema | ObjectSchema)) | {
-    $ref: string;
+    enum?: unknown[];
+    const?: unknown;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+    deprecated?: boolean;
 };
-type Schema = BaseSchema | {
+type BaseSchema = CommonSchemaProps & (StringSchema | NumberSchema | IntegerSchema | BooleanSchema | NullSchema | ArraySchema | ObjectSchema | {
+    $ref: string;
+});
+type Schema = // circular
+BaseSchema | (CommonSchemaProps & {
     allOf: Schema[];
-} | {
+    discriminator?: Discriminator;
+}) | (CommonSchemaProps & {
     anyOf: Schema[];
-} | {
+    discriminator?: Discriminator;
+}) | (CommonSchemaProps & {
     oneOf: Schema[];
-} | OtherUnknown;
+    discriminator?: Discriminator;
+}) | (CommonSchemaProps & {
+    not: Schema;
+}) | (CommonSchemaProps & {
+    if: Schema;
+    then?: Schema;
+    else?: Schema;
+}) | OtherUnknown;
 type Content = {
     description?: string;
     content?: Partial<Record<ContentType, {
@@ -95,7 +119,7 @@ type Content = {
     }>>;
 };
 type Param = {
-    in: 'path' | 'query' | 'headers';
+    in: 'path' | 'query' | 'header' | 'cookie';
     name: string;
     description: string;
     required: boolean;
@@ -107,6 +131,7 @@ type Servers = {
 }[];
 type PathItem = {
     summary?: string;
+    description?: string;
     requestBody?: Content;
     parameters?: Param[];
     servers?: Servers;
@@ -116,13 +141,14 @@ type PathItem = {
     deprecated?: boolean;
     security?: AuthMethod[];
 };
+/** { BearerAuth: [] } | { OAuth2: ['read', 'write'] } */
 type AuthMethod = Record<string, string[]>;
 type SecurityScheme = {
     type: 'http';
     scheme: 'basic' | 'bearer';
 } | {
     type: 'apiKey';
-    in: 'header';
+    in: 'header' | 'query' | 'cookie';
     name: string;
 } | {
     type: 'openIdConnect';
@@ -234,8 +260,9 @@ declare class SwaggerBuilder {
     withSecuritySchemes(schemes: Record<string, SecurityScheme>): this;
     withSchemas(schemas: Record<string, Schema>): this;
     withDefaultSecurity(globalAuthMethods: AuthMethod[]): this;
-    get(): SwaggerConfig;
+    build(): SwaggerConfig;
 }
+declare function singleFileSchema(field?: string, required?: boolean): Content;
 declare function formDataSchema(schema: Schema): Content;
 declare function jsonSchema(schema: Schema): Content;
 declare function jsonSchemaRef(name: string): Content;
@@ -251,6 +278,7 @@ declare const SWG: {
     formDataSchema: typeof formDataSchema;
     jsonSchema: typeof jsonSchema;
     jsonSchemaRef: typeof jsonSchemaRef;
+    singleFileSchema: typeof singleFileSchema;
     security: (name: string) => AuthMethod;
     securitySchemes: {
         readonly BasicAuth: () => SecurityScheme;

package/dist/index.js

@@ -91,7 +91,7 @@ var SwaggerBuilder = class {
     this.swaggerDoc.security = globalAuthMethods;
     return this;
   }
-  get() {
+  build() {
     return this.swaggerDoc;
   }
 };
@@ -131,6 +131,22 @@ var security = (name) => {
   }
   return securityRegistry[name];
 };
+function singleFileSchema(field = "file", required = true) {
+  const schema = {
+    type: "object",
+    properties: {
+      [field]: { type: "string", format: "binary" }
+    },
+    ...required && { required: [field] }
+  };
+  return {
+    content: {
+      "multipart/form-data": {
+        schema
+      }
+    }
+  };
+}
 function formDataSchema(schema) {
   return {
     content: {
@@ -168,7 +184,7 @@ function queryParam(id, schema, required = true, description = "", name) {
   return param("query", id, schema, required, description, name);
 }
 function headerParam(id, schema, required = true, description = "", name) {
-  return param("headers", id, schema, required, description, name);
+  return param("header", id, schema, required, description, name);
 }
 function convertExpressPath(path2) {
   return path2.replace(/:([a-zA-Z0-9_*]+)/g, "{$1}");
@@ -188,6 +204,7 @@ var SWG = {
   formDataSchema,
   jsonSchema,
   jsonSchemaRef,
+  singleFileSchema,
   security,
   securitySchemes
 };

package/dist/index.mjs

@@ -30,7 +30,7 @@ var SwaggerBuilder = class {
     this.swaggerDoc.security = globalAuthMethods;
     return this;
   }
-  get() {
+  build() {
     return this.swaggerDoc;
   }
 };
@@ -70,6 +70,22 @@ var security = (name) => {
   }
   return securityRegistry[name];
 };
+function singleFileSchema(field = "file", required = true) {
+  const schema = {
+    type: "object",
+    properties: {
+      [field]: { type: "string", format: "binary" }
+    },
+    ...required && { required: [field] }
+  };
+  return {
+    content: {
+      "multipart/form-data": {
+        schema
+      }
+    }
+  };
+}
 function formDataSchema(schema) {
   return {
     content: {
@@ -107,7 +123,7 @@ function queryParam(id, schema, required = true, description = "", name) {
   return param("query", id, schema, required, description, name);
 }
 function headerParam(id, schema, required = true, description = "", name) {
-  return param("headers", id, schema, required, description, name);
+  return param("header", id, schema, required, description, name);
 }
 function convertExpressPath(path2) {
   return path2.replace(/:([a-zA-Z0-9_*]+)/g, "{$1}");
@@ -127,6 +143,7 @@ var SWG = {
   formDataSchema,
   jsonSchema,
   jsonSchemaRef,
+  singleFileSchema,
   security,
   securitySchemes
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@extk/expressive",
-    "version": "0.7.1",
+    "version": "0.8.0",
     "type": "commonjs",
     "publishConfig": {
         "access": "public"