@plyaz/types 1.46.11 → 1.47.0

package/dist/core/index.d.ts

@@ -23,3 +23,4 @@ export type * from './frontend';
 export * from './frameworks';
 export type * from './hooks';
 export type * from './utils';
+export type * from './validation';

package/dist/core/init/index.d.ts

@@ -2,4 +2,4 @@
  * Core Init Types
  * Service registry and initialization type definitions
  */
-export type { CoreDomainServiceInstance, CoreServiceInitConfig, CoreServiceCreateOptions, CoreInitializableDomainService, CoreServiceEntry, CoreServiceRegistryConfig, CoreExtractServiceConfig, CoreExtractServiceInstance, CoreFeatureFlagInitConfig, CoreErrorHandlerInitConfig, CoreCacheConfig, CoreStorageConfig, CoreNotificationConfig, CoreObservabilityConfig, CoreStreamConfig, CoreInitOptionsBase, CoreServicesResultBase, CoreNestJsMiddlewareConfig, CoreNestJsRateLimitConfig, CoreNestJsValidationConfig, CoreNestJsSwaggerConfig, } from './types';
+export type { CoreDomainServiceInstance, CoreServiceInitConfig, CoreServiceCreateOptions, CoreInitializableDomainService, CoreServiceEntry, CoreServiceRegistryConfig, CoreExtractServiceConfig, CoreExtractServiceInstance, CoreFeatureFlagInitConfig, CoreErrorHandlerInitConfig, CoreCacheConfig, CoreStorageConfig, CoreNotificationConfig, CoreObservabilityConfig, CoreStreamConfig, CoreInitOptionsBase, CoreServicesResultBase, CoreMiddlewareConfig, CoreRateLimitConfig, CoreCorsConfig, ConfigureAppResult, CoreNestJsMiddlewareConfig, CoreNestJsRateLimitConfig, CoreNestJsValidationConfig, CoreNestJsSwaggerConfig, CoreNestJsVersioningConfig, CoreExpressMiddlewareConfig, CoreNextJsMiddlewareConfig, } from './types';

package/dist/core/init/types.d.ts

@@ -788,16 +788,115 @@ export interface CoreStreamConfig {
     };
 }
 /**
- * Rate limiting configuration for NestJS
+ * Common rate limiting configuration.
+ * Shared across all frameworks (NestJS, Express, Hono, etc.)
  */
-export interface CoreNestJsRateLimitConfig {
+export interface CoreRateLimitConfig {
     /** Time window in seconds (default: 60) */
     ttl?: number;
     /** Max requests per window (default: 100) */
     limit?: number;
-    /** Skip rate limiting for certain paths */
+    /** Skip rate limiting for certain requests */
     skipIf?: (request: unknown) => boolean;
 }
+/**
+ * Common CORS configuration.
+ * Shared across all frameworks.
+ */
+export interface CoreCorsConfig {
+    /** Allowed origins (default: true for all) */
+    origin?: string | string[] | boolean;
+    /** Allow credentials (default: true) */
+    credentials?: boolean;
+    /** Allowed methods */
+    methods?: string[];
+    /** Allowed headers */
+    allowedHeaders?: string[];
+}
+/**
+ * Base middleware configuration shared across all frameworks.
+ * NestJS, Express, Next.js, Hono, etc. all extend this interface.
+ *
+ * @example
+ * ```typescript
+ * const config: CoreMiddlewareConfig = {
+ *   compression: true,
+ *   helmet: true,
+ *   rateLimit: { ttl: 60, limit: 100 },
+ *   bodyLimit: '10mb',
+ *   timeout: 30000,
+ *   cors: { origin: ['http://localhost:3000'] },
+ *   gracefulShutdown: true,
+ * };
+ * ```
+ */
+export interface CoreMiddlewareConfig {
+    /**
+     * Enable response compression (default: true in production).
+     * Uses compression middleware for gzip/brotli.
+     */
+    compression?: boolean;
+    /**
+     * Enable Helmet security headers (default: true).
+     * Adds XSS protection, content security policy, etc.
+     */
+    helmet?: boolean | Record<string, unknown>;
+    /**
+     * Rate limiting configuration.
+     * Set to false to disable, true for defaults, or object for custom config.
+     */
+    rateLimit?: boolean | CoreRateLimitConfig;
+    /**
+     * Maximum request body size (default: '10mb').
+     * Accepts string like '1mb', '10kb', or number in bytes.
+     */
+    bodyLimit?: string | number;
+    /**
+     * Request timeout in milliseconds (default: 30000).
+     * Set to 0 to disable timeout.
+     */
+    timeout?: number;
+    /**
+     * CORS configuration.
+     * Set to false to disable, true for defaults, or object for custom config.
+     */
+    cors?: boolean | CoreCorsConfig;
+    /**
+     * Enable graceful shutdown handling (default: true).
+     * Registers SIGTERM/SIGINT handlers for clean shutdown.
+     */
+    gracefulShutdown?: boolean;
+    /**
+     * Shutdown timeout in milliseconds (default: 10000).
+     * Time to wait for graceful shutdown before force exit.
+     */
+    shutdownTimeout?: number;
+}
+/**
+ * Result of configuring an app (framework-agnostic).
+ * Returned by configureNestApp, configureExpressApp, etc.
+ */
+export interface ConfigureAppResult {
+    /** Features that were enabled */
+    enabled: string[];
+    /** Features that were skipped (not configured or dependencies missing) */
+    skipped: string[];
+    /** Any warnings during configuration */
+    warnings: string[];
+    /** Configured paths */
+    paths: {
+        /** API prefix (e.g., 'api') */
+        prefix?: string;
+        /** Documentation path (e.g., 'api/docs') */
+        docs?: string;
+    };
+}
+/**
+ * Rate limiting configuration for NestJS.
+ * @deprecated Use CoreRateLimitConfig instead
+ */
+export interface CoreNestJsRateLimitConfig extends CoreRateLimitConfig {
+}
 /**
  * Validation pipe configuration for NestJS
  */
@@ -828,8 +927,48 @@ export interface CoreNestJsSwaggerConfig {
     /** Bearer auth enabled */
     bearerAuth?: boolean;
 }
+/**
+ * API versioning configuration for NestJS.
+ * Enables per-controller versioning via @Version() decorator.
+ */
+export interface CoreNestJsVersioningConfig {
+    /**
+     * Versioning type.
+     * - 'uri': Version in URL path (e.g., /v1/users) - default
+     * - 'header': Version in request header
+     * - 'media-type': Version in Accept header media type
+     * - 'custom': Custom version extractor
+     */
+    type?: 'uri' | 'header' | 'media-type' | 'custom';
+    /**
+     * Default version when none specified.
+     * Can be a single version or array of versions.
+     * @example '1' or ['1', '2']
+     */
+    defaultVersion?: string | string[];
+    /**
+     * URI prefix for URI versioning (default: 'v').
+     * @example prefix: 'v' results in /v1/users
+     */
+    prefix?: string;
+    /**
+     * Header name for header versioning (default: 'X-API-Version').
+     */
+    header?: string;
+    /**
+     * Media type key for media-type versioning (default: 'v').
+     * @example Accept: application/json;v=1
+     */
+    key?: string;
+    /**
+     * Custom version extractor function.
+     * Only used when type is 'custom'.
+     */
+    extractor?: (request: unknown) => string | string[];
+}
 /**
  * NestJS middleware and configuration options.
+ * Extends CoreMiddlewareConfig with NestJS-specific features.
  * Applied during app bootstrap via configureNestApp().
  *
  * @example
@@ -848,37 +987,77 @@ export interface CoreNestJsSwaggerConfig {
  * });
  * ```
  */
-export interface CoreNestJsMiddlewareConfig {
+export interface CoreNestJsMiddlewareConfig extends CoreMiddlewareConfig {
     /**
-     * Enable response compression (default: true in production).
-     * Uses compression middleware for gzip/brotli.
+     * Global validation pipe configuration.
+     * Enables class-validator for DTO validation.
+     * NestJS-specific feature.
      */
-    compression?: boolean;
+    validation?: boolean | CoreNestJsValidationConfig;
     /**
-     * Enable Helmet security headers (default: true).
-     * Adds XSS protection, content security policy, etc.
+     * Enable raw body parsing for webhooks (default: false).
+     * Required for signature verification (Stripe, GitHub, etc.).
+     * When enabled, raw body is available on request.rawBody.
      */
-    helmet?: boolean | Record<string, unknown>;
+    rawBody?: boolean | {
+        paths?: string[];
+    };
     /**
-     * Rate limiting configuration.
+     * Swagger/OpenAPI documentation configuration.
      * Set to false to disable, true for defaults, or object for custom config.
+     * NestJS-specific feature.
      */
-    rateLimit?: boolean | CoreNestJsRateLimitConfig;
+    swagger?: boolean | CoreNestJsSwaggerConfig;
     /**
-     * Global validation pipe configuration.
-     * Enables class-validator for DTO validation.
+     * Global prefix for all routes (default: 'api').
+     * Set to false to disable prefix.
      */
-    validation?: boolean | CoreNestJsValidationConfig;
+    globalPrefix?: string | false;
     /**
-     * Maximum request body size (default: '10mb').
-     * Accepts string like '1mb', '10kb', or number in bytes.
+     * Routes to exclude from global prefix.
+     * @example ['health', 'metrics', 'webhooks/*']
      */
-    bodyLimit?: string | number;
+    excludeFromPrefix?: string[];
     /**
-     * Request timeout in milliseconds (default: 30000).
-     * Set to 0 to disable timeout.
+     * API versioning configuration.
+     * Enables per-controller versioning via @Version() decorator.
+     * NestJS-specific feature.
+     *
+     * @example URI versioning (default)
+     * ```typescript
+     * versioning: { type: 'uri', defaultVersion: '1' }
+     * // Routes: /v1/users, /v2/users
+     * ```
+     *
+     * @example Header versioning
+     * ```typescript
+     * versioning: { type: 'header', header: 'X-API-Version' }
+     * // Use header: X-API-Version: 1
+     * ```
      */
-    timeout?: number;
+    versioning?: CoreNestJsVersioningConfig;
+}
+/**
+ * Express middleware and configuration options.
+ * Extends CoreMiddlewareConfig with Express-specific features.
+ * Applied during app bootstrap via configureExpressApp().
+ *
+ * @example
+ * ```typescript
+ * const app = express();
+ * await configureExpressApp(app, {
+ *   express: {
+ *     compression: true,
+ *     helmet: true,
+ *     rateLimit: { ttl: 60, limit: 100 },
+ *     bodyLimit: '10mb',
+ *     trustProxy: true,
+ *     rawBody: { paths: ['/webhooks'] },
+ *   },
+ * });
+ * ```
+ */
+export interface CoreExpressMiddlewareConfig extends CoreMiddlewareConfig {
     /**
      * Enable raw body parsing for webhooks (default: false).
      * Required for signature verification (Stripe, GitHub, etc.).
@@ -888,40 +1067,76 @@ export interface CoreNestJsMiddlewareConfig {
         paths?: string[];
     };
     /**
-     * Swagger/OpenAPI documentation configuration.
-     * Set to false to disable, true for defaults, or object for custom config.
+     * Trust proxy setting for Express.
+     * Required when behind a reverse proxy (nginx, load balancer).
+     * @see https://expressjs.com/en/guide/behind-proxies.html
      */
-    swagger?: boolean | CoreNestJsSwaggerConfig;
+    trustProxy?: boolean | string | number;
     /**
-     * CORS configuration override.
-     * By default, uses app-level CORS. Set here to override.
+     * Mount path for the Express app.
+     * @example '/api' mounts all routes under /api/*
      */
-    cors?: boolean | {
-        origin?: string | string[] | boolean;
-        credentials?: boolean;
-        methods?: string[];
-        allowedHeaders?: string[];
-    };
+    mountPath?: string;
     /**
-     * Global prefix for all routes (default: 'api').
-     * Set to false to disable prefix.
+     * Extended URL encoding for body parser.
+     * @default true
      */
-    globalPrefix?: string | false;
+    extendedUrlEncoded?: boolean;
+}
+/**
+ * Next.js middleware and configuration options.
+ * Extends CoreMiddlewareConfig with Next.js-specific features.
+ * Applied via middleware.ts or API route wrappers.
+ *
+ * @example App Router API
+ * ```typescript
+ * // app/api/users/route.ts
+ * import { withCoreMiddleware } from '@plyaz/core/nextjs';
+ *
+ * export const GET = withCoreMiddleware(async (req) => {
+ *   return Response.json({ users: [] });
+ * }, {
+ *   rateLimit: { ttl: 60, limit: 100 },
+ * });
+ * ```
+ *
+ * @example Pages Router API
+ * ```typescript
+ * // pages/api/users.ts
+ * import { withCoreApiHandler } from '@plyaz/core/nextjs';
+ *
+ * export default withCoreApiHandler(async (req, res) => {
+ *   res.json({ users: [] });
+ * }, {
+ *   rateLimit: { ttl: 60, limit: 100 },
+ * });
+ * ```
+ */
+export interface CoreNextJsMiddlewareConfig extends CoreMiddlewareConfig {
     /**
-     * Routes to exclude from global prefix.
-     * @example ['health', 'metrics', 'webhooks/*']
+     * Enable raw body parsing for webhooks (default: false).
+     * Required for signature verification (Stripe, GitHub, etc.).
+     * Note: Next.js App Router requires config.api.bodyParser = false
      */
-    excludeFromPrefix?: string[];
+    rawBody?: boolean | {
+        paths?: string[];
+    };
     /**
-     * Enable graceful shutdown handling (default: true).
-     * Registers SIGTERM/SIGINT handlers for clean shutdown.
+     * API base path for Next.js routes.
+     * @default '/api'
      */
-    gracefulShutdown?: boolean;
+    apiBasePath?: string;
     /**
-     * Shutdown timeout in milliseconds (default: 10000).
-     * Time to wait for graceful shutdown before force exit.
+     * Enable Edge runtime compatibility mode.
+     * Some middleware (compression, helmet) may not work on Edge.
+     * @default false
      */
-    shutdownTimeout?: number;
+    edgeCompatible?: boolean;
+    /**
+     * Skip middleware for certain paths (regex patterns).
+     * @example ['^/api/health$', '^/_next/.*']
+     */
+    skipPaths?: string[];
 }
 /**
  * Base core initialization options
@@ -990,6 +1205,18 @@ export interface CoreInitOptionsBase<TDb = unknown, TApi = unknown, TStorage = u
      * Only used when runtime is 'nestjs'.
      */
     nestjs?: CoreNestJsMiddlewareConfig;
+    /**
+     * Express-specific middleware and configuration.
+     * Applied during app bootstrap via configureExpressApp().
+     * Only used when runtime is 'express'.
+     */
+    express?: CoreExpressMiddlewareConfig;
+    /**
+     * Next.js-specific middleware and configuration.
+     * Applied via middleware.ts or API route wrappers.
+     * Only used when runtime is 'nextjs'.
+     */
+    nextjs?: CoreNextJsMiddlewareConfig;
 }
 /**
  * Core services result from initialization

package/dist/core/validation.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Validation Types
+ *
+ * Types for schema validation across the Plyaz ecosystem.
+ * Compatible with Zod schemas without complex type inference issues.
+ */
+/**
+ * Minimal schema interface for validation pipes.
+ * Compatible with Zod schemas without complex type inference issues.
+ *
+ * Use this type instead of ZodSchema<T> to avoid TypeScript
+ * "type instantiation excessively deep" errors with complex schemas.
+ *
+ * Note: This uses Zod's actual API structure where error is an object
+ * with an `issues` array, not the abstracted `ValidationSchema` from
+ * errors/validation.ts which uses a flat `errors` array.
+ *
+ * @example
+ * ```typescript
+ * import type { ValidatableSchema } from '@plyaz/types/core';
+ *
+ * class ValidationPipe<T> {
+ *   constructor(private schema: ValidatableSchema<T>) {}
+ *
+ *   transform(value: unknown): T {
+ *     const result = this.schema.safeParse(value);
+ *     if (!result.success) throw result.error;
+ *     return result.data;
+ *   }
+ * }
+ * ```
+ */
+export interface ValidatableSchema<T = unknown> {
+    safeParse(value: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues: ReadonlyArray<{
+                path: PropertyKey[];
+                message: string;
+                code: string;
+            }>;
+        };
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.46.11",
+  "version": "1.47.0",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",