@weconjs/core 1.2.15 → 1.3.0

package/README.md

@@ -12,12 +12,14 @@
 - [Configuration](#configuration)
 - [Modules](#modules)
 - [Routing & RBAC](#routing--rbac)
+- [Postman Generation](#postman-generation)
 - [Database](#database)
 - [Logging](#logging)
 - [i18n](#i18n)
 - [Socket.IO](#socketio)
 - [Context & Services](#context--services)
 - [Authentication](#authentication)
+- [DevTools](#devtools)
 - [API Reference](#api-reference)
 - [Testing](#testing)
 - [Requirements](#requirements)
@@ -87,7 +89,6 @@ export default defineConfig({
       logging: { level: 'info', enableFile: true },
     },
   },
-  modules: ['./src/modules/auth', './src/modules/users'],
 });
 ```
 
@@ -95,9 +96,14 @@ export default defineConfig({
 
 ```typescript
 // src/modules/users/users.module.ts
+import { z } from 'zod';
 import { defineModule, Routes, Route } from '@weconjs/core';
 import { userController } from './controllers/user.controller.js';
 
+const UsersConfigSchema = z.object({
+  maxPerPage: z.coerce.number().default(50),
+});
+
 const usersRoutes = new Routes({
   prefix: '/users',
   routes: [
@@ -108,13 +114,6 @@ const usersRoutes = new Routes({
       roles: ['admin', 'user'],
       middlewares: [userController.findAll],
     }),
-    new Route({
-      method: 'GET',
-      path: '/:id',
-      rai: 'users:read',
-      roles: ['admin', 'user'],
-      middlewares: [userController.findById],
-    }),
     new Route({
       method: 'POST',
       path: '/',
@@ -128,8 +127,14 @@ const usersRoutes = new Routes({
 export default defineModule({
   name: 'users',
   description: 'User management module',
+  config: {
+    schema: UsersConfigSchema,
+    load: () => ({
+      maxPerPage: Number(process.env.USERS_MAX_PER_PAGE) || 50,
+    }),
+  },
   routes: usersRoutes,
-  imports: ['auth'],
+  priority: 0,
   onInit: async (ctx) => {
     ctx.logger.info('Users module initialized');
   },
@@ -155,7 +160,17 @@ export const wecon = new Wecon()
       routes: [authModule.routes!, usersModule.routes!],
     })
   )
-  .dev({ helpfulErrors: true, logRoutes: true })
+  .postman({
+    name: 'My API',
+    baseUrl: 'http://localhost:3000',
+    apiPrefix: '/api',
+    autoGenerate: true,
+    output: {
+      collection: './postman/collection.json',
+      environment: './postman/environment.json',
+    },
+  })
+  .dev({ helpfulErrors: true })
   .build();
 
 export const modules = [authModule, usersModule];
@@ -165,12 +180,21 @@ export const modules = [authModule, usersModule];
 
 ```typescript
 // src/main.ts
-import { createWecon, loadConfig, buildUriFromConfig } from '@weconjs/core';
+import {
+  createWecon,
+  loadConfig,
+  buildUriFromConfig,
+  resolveModuleConfigs,
+} from '@weconjs/core';
 import { wecon, modules } from './bootstrap.js';
 
 async function main() {
   const config = await loadConfig('./wecon.config.ts', process.env.NODE_ENV);
 
+  // Resolve module configs (calls load() + validates with Zod schema)
+  const moduleConfigs = await resolveModuleConfigs(modules);
+  config.moduleConfigs = moduleConfigs;
+
   const app = await createWecon({
     config,
     modules,
@@ -179,6 +203,7 @@ async function main() {
       enabled: true,
       uri: buildUriFromConfig(config.database),
     },
+    i18n: { enabled: true, modulesDir: './src/modules' },
     logger: { useWinston: true, enableFile: false },
     hooks: {
       onBoot: (ctx) => ctx.logger.info('Server ready'),
@@ -244,38 +269,42 @@ const resolved = resolveConfig(rawConfig, 'production');
 
 ### Per-module configuration
 
-Modules can declare a Zod schema for their configuration. Values are validated at startup and accessible at runtime through the context:
+Modules declare a Zod schema and a `load()` function to read environment variables. Config is validated at startup and accessible at runtime:
 
 ```typescript
 import { z } from 'zod';
 import { defineModule } from '@weconjs/core';
 
+const MailConfigSchema = z.object({
+  from: z.string().email().default('noreply@example.com'),
+  host: z.string().default('smtp.gmail.com'),
+  port: z.coerce.number().default(587),
+});
+
 export default defineModule({
   name: 'mail',
   config: {
-    schema: z.object({
-      from: z.string().email(),
-      provider: z.enum(['ses', 'sendgrid']),
+    schema: MailConfigSchema,
+    load: () => ({
+      from: process.env.MAIL_FROM || 'noreply@example.com',
+      host: process.env.MAIL_HOST || 'smtp.gmail.com',
+      port: Number(process.env.MAIL_PORT) || 587,
     }),
-    defaults: { provider: 'ses' },
   },
   onInit: async (ctx) => {
-    const mailConfig = ctx.getModuleConfig<{ from: string; provider: string }>('mail');
-    ctx.logger.info(`Mail provider: ${mailConfig.provider}`);
+    const mailConfig = ctx.getModuleConfig<z.infer<typeof MailConfigSchema>>('mail');
+    ctx.logger.info(`Mail host: ${mailConfig.host}`);
   },
 });
 ```
 
-Provide values in your config file:
+Resolve all module configs before creating the application:
 
 ```typescript
-export default defineConfig({
-  app: { name: 'my-api' },
-  moduleConfigs: {
-    mail: { from: 'hello@example.com' },
-  },
-  // ...
-});
+import { resolveModuleConfigs } from '@weconjs/core';
+
+const moduleConfigs = await resolveModuleConfigs(modules);
+config.moduleConfigs = moduleConfigs;
 ```
 
 ## Modules
@@ -286,15 +315,16 @@ export default defineConfig({
 import { defineModule } from '@weconjs/core';
 
 export default defineModule({
-  name: 'auth',
-  description: 'Authentication and authorization',
-  routes: authRoutes,          // Routes instance
-  imports: ['database-seeds'], // Dependencies (loaded first)
-  exports: ['authService'],    // Exported services
-  path: __dirname,             // Enables per-module package.json
+  name: 'auth',                          // Unique identifier (lowercase, hyphens allowed)
+  description: 'Authentication module',
+  config: { schema, load: () => ({}) },  // Zod schema + env loader
+  routes: authRoutes,                    // Routes instance (optional)
+  priority: 1,                           // Load order (lower = first, default: 0)
+  path: __dirname,                       // Enables per-module package.json discovery
 
   onInit: async (ctx) => {
-    // Called when the module is initialized
+    // Called during initialization — register services here
+    ctx.registerService('auth', new AuthService(config));
   },
   onDestroy: async (ctx) => {
     // Called on graceful shutdown
@@ -302,21 +332,21 @@ export default defineModule({
 });
 ```
 
-### Dependency resolution
+### Priority-based load order
 
-Modules are sorted using topological sort, with circular dependency detection:
+Modules are sorted by `priority` ascending — lower numbers initialize first:
 
 ```typescript
-import { loadModule, resolveModuleDependencies } from '@weconjs/core';
+import { resolveModuleDependencies } from '@weconjs/core';
 
-const modules = await Promise.all([
-  loadModule('./src/modules/users'),
-  loadModule('./src/modules/auth'),
-  loadModule('./src/modules/orders'),
+const modulesMap = new Map([
+  ['core', coreModule],      // priority: 0
+  ['users', usersModule],    // priority: 0
+  ['auth', authModule],      // priority: 1
 ]);
 
-// Returns modules in correct initialization order
-const sorted = resolveModuleDependencies(modules);
+// Returns: [coreModule, usersModule, authModule]
+const sorted = resolveModuleDependencies(modulesMap);
 ```
 
 ### Per-module dependencies
@@ -352,11 +382,12 @@ Every route has a unique RAI string (e.g. `users:list`, `orders:create`). The RA
 ### Defining routes
 
 ```typescript
-import { Route, Routes, RoutesParam } from '@weconjs/core';
+import { Route, Routes, PostmanGroup, PostmanRoute } from '@weconjs/core';
 
 const routes = new Routes({
   prefix: '/api/orders',
   middlewares: [authMiddleware],
+  postman: new PostmanGroup({ folderName: 'Orders' }),
   routes: [
     new Route({
       method: 'GET',
@@ -364,6 +395,7 @@ const routes = new Routes({
       rai: 'orders:list',
       roles: ['admin', 'user'],
       middlewares: [orderController.list],
+      postman: new PostmanRoute({ name: 'List Orders' }),
     }),
     new Route({
       method: 'POST',
@@ -371,6 +403,14 @@ const routes = new Routes({
       rai: 'orders:create',
       roles: ['admin', 'user'],
       middlewares: [validateOrder, orderController.create],
+      postman: new PostmanRoute({
+        name: 'Create Order',
+        body: {
+          mode: 'raw',
+          raw: JSON.stringify({ item: 'Widget', qty: 1 }, null, 2),
+          options: { raw: { language: 'json' } },
+        },
+      }),
     }),
     new Route({
       method: 'DELETE',
@@ -404,12 +444,7 @@ const wecon = new Wecon()
   .guestRole('guest')
   .routes(apiRoutes)
   .dev({
-    debugMode: true,
     helpfulErrors: true,  // Detailed 401/404 messages in development
-    logRoutes: true,
-  })
-  .onRoutesPrepared((routes) => {
-    console.log(`Registered ${routes.length} routes`);
   })
   .build();
 
@@ -438,6 +473,31 @@ const allRoutes = wecon.getRoutes();
 const route = wecon.getRoute('users:read');
 ```
 
+## Postman Generation
+
+Auto-generate Postman Collection v2.1.0 and Environment files from your route tree:
+
+```typescript
+const wecon = new Wecon()
+  .routes(apiRoutes)
+  .postman({
+    name: 'My API',
+    description: 'API documentation',
+    baseUrl: 'http://localhost:3000',
+    apiPrefix: '/api/v1',
+    autoGenerate: true,
+    output: {
+      collection: './postman/collection.json',
+      environment: './postman/environment.json',
+    },
+  })
+  .build();
+```
+
+- URLs use `{{APP_PUBLIC_ADDRESS}}{{API_PREFIX}}` variables in the generated collection
+- Variables are placed in the environment file (not the collection)
+- `PostmanGroup` creates folders, `PostmanRoute` adds request metadata (body, description)
+
 ## Database
 
 ### URI builder
@@ -467,7 +527,6 @@ const db = await createDatabaseConnection({
   uri: 'mongodb://localhost/myapp',
   plugins: [timestampPlugin],
   debug: process.env.NODE_ENV === 'development',
-  fieldShield: { enabled: true, strict: true },
 });
 
 await db.connect();
@@ -504,11 +563,11 @@ When creating an app with `createWecon`, the framework tries Winston first and f
 
 ## i18n
 
-Translation files are auto-discovered from module directories. Each module can have a `locales/` folder with JSON files:
+Translation files are auto-discovered from module directories. Each module has an `i18n/` folder with locale JSON files:
 
 ```
-src/modules/users/locales/en.json
-src/modules/users/locales/es.json
+src/modules/users/i18n/en.translation.json
+src/modules/users/i18n/fr.translation.json
 ```
 
 Enable i18n in your config:
@@ -521,12 +580,11 @@ const app = await createWecon({
 });
 ```
 
-Use translations in handlers via `req.t()`:
+Use translations in handlers via `req.t()`. Keys are namespaced by module:
 
 ```typescript
-app.get('/greeting', (req, res) => {
-  res.json({ message: req.t('users:welcome', { name: 'Alice' }) });
-});
+// Format: {module}:{section}.{KEY}
+res.json({ message: req.t('users:welcome', { name: 'Alice' }) });
 ```
 
 Interpolation uses `{{key}}` syntax in translation files:
@@ -535,40 +593,78 @@ Interpolation uses `{{key}}` syntax in translation files:
 { "welcome": "Welcome, {{name}}!" }
 ```
 
+The `i18nNamespaceMiddleware` automatically sets the translation namespace based on the route's module, so `RequestError` codes are automatically mapped to `{namespace}:errors.{CODE}`.
+
 ## Socket.IO
 
 Socket handlers and middleware are auto-discovered from module directories:
 
+```
+src/modules/chat/socket/chat.socket.ts        # Handler
+src/modules/chat/socket/socket.middleware.ts   # Middleware (optional)
+```
+
+### Handler
+
 ```typescript
-import { setupSocketIO, createSocketServer } from '@weconjs/core';
+// src/modules/chat/socket/chat.socket.ts
+import type { SocketHandlerFn } from '@weconjs/core';
 
-// Attach to existing HTTP server
-const io = createSocketServer(httpServer, {
-  cors: { origin: 'http://localhost:3000' },
-});
+const chatHandler: SocketHandlerFn = (io, socket) => {
+  socket.on('message', (data) => {
+    io.emit('message', data);
+  });
+};
 
-// Auto-discover handlers from modules
-await setupSocketIO(io, './src/modules');
+export default chatHandler;
 ```
 
-Convention: place socket handlers in `src/modules/<name>/sockets/` and middleware in `src/modules/<name>/sockets/middleware/`.
+### Middleware
+
+```typescript
+// src/modules/chat/socket/socket.middleware.ts
+import type { SocketMiddlewareFn } from '@weconjs/core';
+
+const authMiddleware: SocketMiddlewareFn = (socket, next) => {
+  const token = socket.handshake.auth?.token;
+  if (!token) return next(new Error('Authentication required'));
+  next();
+};
+
+export default authMiddleware;
+```
+
+### Setup
+
+```typescript
+import { setupSocketIO } from '@weconjs/core';
+
+// Full auto-discovery setup
+const io = await setupSocketIO(httpServer, './src/modules', {
+  enabled: true,
+  path: '/ws',
+  cors: { origin: '*' },
+});
+```
+
+When socket is enabled, the `io` instance is available on `ctx.io`.
 
 ## Context & Services
 
 The `WeconContext` is passed to all module hooks, handlers, and middleware. It provides access to configuration, logging, and a service registry.
 
 ```typescript
-// Register a service
-ctx.registerService('mailer', new MailerService());
+// Register a service (in onInit)
+ctx.registerService('mailer', new MailerService(config));
 
-// Retrieve a service
-const mailer = ctx.getService<MailerService>('mailer');
+// Retrieve a service (in controllers via req.ctx)
+const mailer = req.ctx!.getService<MailerService>('mailer');
 
 // Access module config (validated at startup)
 const mailConfig = ctx.getModuleConfig<MailConfig>('mail');
 
 // Update module config at runtime (re-validates against Zod schema)
-ctx.setModuleConfig('mail', { from: 'new@example.com', provider: 'sendgrid' });
+ctx.setModuleConfig('mail', { from: 'new@example.com' });
 ```
 
 ## Authentication
@@ -605,6 +701,33 @@ res.status(404).respond({
 // → { success: false, data: null, errors: [...], meta: null }
 ```
 
+### RequestError
+
+Throw structured errors that integrate with i18n:
+
+```typescript
+import { RequestError } from '@weconjs/core';
+
+throw new RequestError('User not found', {
+  code: 'USER_NOT_FOUND',  // Maps to i18n key: {namespace}:errors.USER_NOT_FOUND
+  status: 404,
+  details: { id: userId },
+});
+```
+
+## DevTools
+
+Built-in development tools for module and route introspection:
+
+```typescript
+import { createDevToolsRouter } from '@weconjs/core';
+
+const devRouter = createDevToolsRouter({ modules, wecon });
+app.use('/_dev', devRouter);
+```
+
+Provides endpoints for listing modules (with priority, config) and inspecting routes.
+
 ## Server Factory
 
 `createWecon` is the main entry point. It wires together all framework features and returns a `WeconApp` instance:
@@ -616,16 +739,14 @@ const app = await createWecon({
   config,
   modules,
   wecon,                          // Wecon routing instance (optional)
-  middleware: [cors(), helmet()],  // Custom Express middleware
+  apiPrefix: '/api/v1',           // API prefix for middleware/routing
+  middlewares: [cors(), helmet()], // Custom Express middleware
   database: { enabled: true, uri: '...' },
-  plugins: { fieldShield: { strict: true } },
   i18n: { enabled: true, modulesDir: './src/modules' },
   logger: { useWinston: true, enableFile: true, logDir: './logs' },
-  moduleDeps: { autoInstall: true, paths: { auth: './src/modules/auth' } },
   hooks: {
     onBoot: async (ctx) => { /* before server starts */ },
     onShutdown: async (ctx) => { /* cleanup */ },
-    onModuleInit: async (module, ctx) => { /* after each module init */ },
   },
 });
 
@@ -654,9 +775,10 @@ Features included automatically:
 
 | Export | Description |
 |--------|-------------|
-| `defineModule(definition)` | Define a module with routes and lifecycle hooks |
-| `loadModule(path)` | Load a module from file path |
-| `resolveModuleDependencies(modules)` | Sort modules by dependencies (topological sort) |
+| `defineModule(definition)` | Define a module with routes, config, and lifecycle hooks |
+| `loadModule(path, baseDir)` | Load a module from file path with socket discovery |
+| `resolveModuleDependencies(modules)` | Sort modules by priority (lower first) |
+| `resolveModuleConfigs(modules)` | Call each module's `load()` and validate with Zod schema |
 | `readModulePackageJson(path)` | Read a module's package.json |
 | `checkModuleDeps(path, rootDir)` | Check if module dependencies are installed |
 | `installModuleDeps(path, rootDir)` | Install missing module dependencies |
@@ -677,8 +799,11 @@ Features included automatically:
 | `Route` | Single endpoint definition (method, path, RAI, roles, middlewares) |
 | `Routes` | Hierarchical route group with prefix, middleware, and params |
 | `RoutesParam` | Route parameter definition with validation |
+| `PostmanRoute` | Postman request metadata (name, description, body) |
+| `PostmanGroup` | Postman folder grouping |
 | `RaiMatcher` | RAI resolution engine (maps request path + method to a RAI) |
 | `ErrorCatcher` | Base class for configuration error reporting |
+| `PostmanGenerator` | Generates Postman Collection v2.1.0 + Environment files |
 
 ### Database
 
@@ -699,19 +824,23 @@ Features included automatically:
 
 | Export | Description |
 |--------|-------------|
+| `initializeI18n(options)` | Initialize i18n system |
 | `initI18n(modulesDir, defaultLocale)` | Initialize i18n and return Express middleware |
-| `loadI18nResources(modulesDir)` | Load translation files from module directories |
-| `createI18nMiddleware(resources, defaultLocale)` | Create the Express middleware |
+| `i18nNamespaceMiddleware` | Middleware that sets i18n namespace from route module |
+| `getI18n()` | Get the i18next instance |
+| `translate(key, options?)` | Translate a key programmatically |
 
 ### Socket.IO
 
 | Export | Description |
 |--------|-------------|
 | `createSocketServer(httpServer, options)` | Create Socket.IO server |
-| `setupSocketIO(io, modulesDir)` | Auto-discover and register handlers |
-| `initializeSocket(server, modulesDir, options)` | Combined setup helper |
-| `discoverSocketHandlers(modulesDir)` | Find socket handler files in modules |
-| `discoverSocketMiddleware(modulesDir)` | Find socket middleware files in modules |
+| `setupSocketIO(httpServer, modulesDir, options)` | Full auto-discovery setup |
+| `initializeSocket(io, handlers, middleware)` | Wire handlers and middleware to io |
+| `discoverSocketHandlersFromModules(modulesDir)` | Find all socket handler files |
+| `discoverSocketMiddlewareFromModules(modulesDir)` | Find all socket middleware files |
+| `discoverSocketHandlers(modulePath)` | Find handlers in a single module |
+| `discoverSocketMiddleware(modulePath)` | Find middleware in a single module |
 
 ### Context
 
@@ -720,12 +849,52 @@ Features included automatically:
 | `createContext(options)` | Create application context with service registry |
 | `createLogger(options)` | Create a logger instance |
 
+### DevTools
+
+| Export | Description |
+|--------|-------------|
+| `createDevToolsRouter(options)` | Create Express router for module/route introspection |
+
 ### Errors
 
 | Export | Description |
 |--------|-------------|
 | `ConfigError` | Configuration error with code and metadata |
-| `RequestError` | Request error with code and metadata |
+| `RequestError` | Request error with code, status, and metadata |
+
+### Types
+
+Key TypeScript types available for import:
+
+```typescript
+import type {
+  // Config
+  WeconConfig, ResolvedConfig, AppConfig, DatabaseConfig,
+  LoggingConfig, HttpsConfig, SocketConfig, FeaturesConfig,
+
+  // Modules
+  ModuleDefinition, ModuleConfigDefinition, WeconModule,
+
+  // Routing
+  RouteConfig, RoutesConfig, RAI, WeconDevConfig, WeconPostmanConfig,
+
+  // Context
+  WeconContext, WeconLogger, WeconServices,
+
+  // Socket
+  SocketHandler, SocketMiddleware, SocketHandlerFn, SocketMiddlewareFn,
+  SocketServer, SocketInstance, DiscoveredSocketHandler, SocketOptions,
+
+  // Auth & Request
+  Authenticable, WeconRequest, WeconResponse, RouteHandler, WeconMiddleware,
+
+  // Server
+  CreateWeconOptions, WeconApp, ApiError, ApiResponse, RespondOptions,
+
+  // Postman
+  PostmanGeneratorConfig, PostmanCollectionConfig,
+} from '@weconjs/core';
+```
 
 ## Testing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weconjs/core",
-  "version": "1.2.15",
+  "version": "1.3.0",
   "description": "Wecon Framework Core - defineConfig, defineModule, and runtime utilities",
   "type": "module",
   "main": "./dist/index.js",