UMajs

https://umajs.github.io
Admin
UMajs is a simple, extensible, TypeScript-based Node.js web framework. It features powerful...
Tokens:10,825
Snippets:81
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Uma.js Instance Method: start

Source: https://umajs.github.io/development/Uma

Starts the Uma.js application. This method must be called during initialization. The default port is 8058.

```APIDOC
uma.start(port: number = 8058)
```

```JavaScript
// app.ts
// ===> Call the start method to launch the project
uma.start(8058)
```

--------------------------------

### Example Console Output for Parameter Extraction

Source: https://umajs.github.io/development/Router

This snippet shows the expected console output when accessing the `/page/test?name=uma` URL, demonstrating the successful extraction of 'test' from the path parameter and 'uma' from the query parameter.

```text
name: test
title: uma
```

--------------------------------

### Umajs Pure Middleware Plugin Example (koa-views)

Source: https://umajs.github.io/%E6%8F%92%E4%BB%B6/dev

This TypeScript example demonstrates how to create a pure middleware plugin for Umajs. It integrates `koa-views` by exporting a function that accepts the Uma instance and plugin options, returning a Koa middleware function. The options are combined from the plugin's configuration.

```TypeScript
import * as Koa from 'koa';
import * as views from 'koa-views';

import { Uma } from '@umajs/core;

type TView = {
    root: string
    opts: {
        // views options
    }
};

// options 是插件的配置及 [pluginName].config.ts 的配置结合配置
export default (uma: Uma, options: TView = {}): Koa.Middleware => {
    // uma 实例化对象；options 插件配置的 options，等同于 uma.plugin['error-handler'].options
    return views(options.root, options.opts);
};
```

--------------------------------

### Uma.js Static Property: pluginConfig

Source: https://umajs.github.io/development/Uma

Retrieves the configuration settings for all installed plugins, indexed by plugin name.

```APIDOC
static get pluginConfig(): {
        [pluginName: string]: boolean | import("../types/TPluginConfig").TPluginConfig;
    };
```

--------------------------------

### Initialize Uma Instance and Set Environment

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Demonstrates how to initialize the Uma instance using `Uma.instance()` and set the runtime environment (`env`) based on command-line arguments. It also shows starting the Uma application on port 8058.

```TypeScript
// app.ts
import Uma from '@umajs/core'
import { Router } from '@umajs/router'

const uma = Uma.instance({
  Router,
  ROOT: __dirname,
  env: process.argv.indexOf('production') > -1 ? 'production' : 'development',
})

uma.start(8058)
```

--------------------------------

### Use UmaLogger via singleton pattern

Source: https://umajs.github.io/%E6%8F%92%E4%BB%B6/Logger

Illustrates how to get and use the `UmaLogger` instance via its singleton pattern (`UmaLogger.instance()`) after initial configuration, supported from v0.0.5.

```TypeScript
import { UmaLogger } from '@umajs/logger'
import * as path from 'path'

const logger = UmaLogger.instance({
  level: 'ALL',
  consoleLevel: 'ALL',
  encoding: 'utf-8',
  file: path.resolve(__dirname, '../log/logger.log')
})
logger.debug('debug')
logger.info('info GET')
logger.warn('warn')
logger.error('error')
```

--------------------------------

### Uma Configuration Object Structure

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Illustrates the structure of the `uma.config` object, which contains processed configuration information from the `config` directory. It shows examples of plugin and status configurations.

```JSON
{
  "plugin": {
    "logger": true,
    "model": true
  },
  "status": {
    "_404": "[object, function]"
  }
}
```

--------------------------------

### Configure Uma.js plugin-logger

Source: https://umajs.github.io/%E6%8F%92%E4%BB%B6/Logger

Example configuration for the `@umajs/plugin-logger` in `plugin.config.ts`, setting the log level, file path, and whether to allow debug logs in production.

```TypeScript
import * as path from 'path'

const { ROOT } = Uma.options

export default {
  logger: {
    enable: true,
    options: {
      level: 'DEBUG', 
      file: path.resolve(ROOT, '../log/logger.log'),
      allowDebugAtProd: false 
    }
  }
}
```

--------------------------------

### Start Uma Application on a Specific Port

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Shows how to call the `uma.start()` method to launch the Uma application. The default port is 8058.

```TypeScript
// app.ts
// ===> 调用start方法启动项目
uma.start(8058)
```

--------------------------------

### Configure separate log files by level in Uma.js

Source: https://umajs.github.io/%E6%8F%92%E4%BB%B6/Logger

Example of configuring separate log files for error, info, and warn levels by specifying a directory and specific file names.

```JavaScript
exports.logger = {
  dir: '/path/to/your/custom/log', 
  errorLogName: 'errorlogger.log', 
  infoLogName: 'infologger.log', 
  warnLogName: 'warnlogger.log' 
}
```

--------------------------------

### Uma Static Method: get app()

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Documents the static getter `app` for retrieving the Koa Application instance.

```TypeScript
static get app(): Koa<Koa.DefaultState, IContext>;
```

--------------------------------

### Uma Static Method: get options()

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Documents the static getter `options` for retrieving the parameters used to run Uma.

```TypeScript
static get options(): TUmaOption;
```

--------------------------------

### Uma Lifecycle Hooks: beforeLoad and afterLoad

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Demonstrates the usage of `beforeLoad` and `afterLoad` lifecycle hooks, which are executed before and after the service starts, respectively. Both hooks receive the current Uma instance as an argument.

```TypeScript
const uma = Uma.instance({
  ROOT: __dirname,
  beforeLoad(uma: Uma) {
    // 服务开始启动
  },
  afterLoad(uma: Uma) {
    // 服务启动完成
  },
})
```

--------------------------------

### Create independent UmaLogger instance

Source: https://umajs.github.io/%E6%8F%92%E4%BB%B6/Logger

Example of creating a new, independent `UmaLogger` instance with custom configuration for log level, console level, encoding, and file path.

```TypeScript
import { UmaLogger } from '@umajs/logger'
import * as path from 'path'

const logger = new UmaLogger({
  level: 'ALL',
  consoleLevel: 'ALL',
  encoding: 'utf-8',
  file: path.resolve(__dirname, '../log/logger.log')
})
logger.debug('debug')
logger.info('info GET')
logger.warn('warn')
logger.error('error')
```

--------------------------------

### Uma Static Method: get server()

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Documents the static getter `server` for retrieving the HTTP or HTTPS server instance.

```TypeScript
static get server(): http.Server | https.Server;
```

--------------------------------

### Uma Static Method: get config()

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Documents the static getter `config` for retrieving all Uma configurations.

```TypeScript
static get config(): TConfig;
```

--------------------------------

### Uma.js Lifecycle Hooks: beforeLoad, afterLoad

Source: https://umajs.github.io/development/Uma

These are hook functions executed before and after the Uma.js service starts, respectively. Both functions receive the current Uma instance as an argument, allowing for custom logic during application startup and shutdown phases.

```JavaScript
const uma = Uma.instance({
  ROOT: __dirname,
  beforeLoad(uma: Uma) {
    // Service starting
  },
  afterLoad(uma: Uma) {
    // Service started
  }
})
```

--------------------------------

### Parameter Order Flexibility with @Param and @Query

Source: https://umajs.github.io/development/Router

This example highlights that the order of `@Param` and `@Query` decorators in the function signature does not impact their ability to correctly retrieve the corresponding parameters. Both original and reordered signatures work identically.

```TypeScript
- index(@Param('name') name: string, @Query('name') title: string)
// 参数顺序变化也可以正确获取
+ index(@Query('name') title: string, @Param('name') name: string)
```

--------------------------------

### Configure single custom log file path in Uma.js

Source: https://umajs.github.io/%E6%8F%92%E4%BB%B6/Logger

Example of configuring a single custom file path for all log levels in Uma.js logger settings.

```JavaScript
exports.logger = {
  file: '/path/to/your/custom/log/logger.log' 
}
```

--------------------------------

### Inject and Use UMA.js Service in Controller

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Service

This example illustrates how to integrate and use a UMA.js service within a controller. It showcases the use of the `@Service` decorator for automatic dependency injection, allowing direct access to service methods without manual instantiation. The second part provides a basic service definition for context.

```typescript
// controller
import DemoService from '../service/demo.service'

export default class Index extends BaseController {
  @Service(DemoService)
  demoService: DemoService

  @Path('/demo')
  demoService() {
    // return this.demoService.loadAll();
  }
}
```

```typescript
// service
import { BaseService } from '@umajs/core'

export default class Demp extends BaseService {
  loadAll() {
    // return
  }
}
```

--------------------------------

### Implement All Uma.js Aspect Advice Types

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/AOP

This example illustrates a complete implementation of the IAspect interface in Uma.js, showcasing all five types of advice: before, after, around, afterThrowing, and afterReturning. It demonstrates how each advice method interacts with the join point and handles method execution flow.

```TypeScript
import { IAspect, IJoinPoint, IProceedJoinPoint } from '@umajs/core'

export default class Method implements IAspect {
  before(point: IJoinPoint) {
    // Before advice
  }
  after(point: IJoinPoint) {
    // After advice
  }
  async around(proceedPoint: IProceedJoinPoint) {
    const { proceed, args } = proceedPoint
    // Around advice before
    return await proceed(...args)
    // Around advice after
  }
  afterThrowing(e: Error) {
    // AfterThrowing advice
  }
  afterReturning(point: IJoinPoint, result: any) {
    // AfterReturning advice
  }
}
```

--------------------------------

### Uma Static Method: get pluginConfig()

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Documents the static getter `pluginConfig` for retrieving the plugin configuration object.

```TypeScript
static get pluginConfig(): {
        [pluginName: string]: boolean | import("../types/TPluginConfig").TPluginConfig;
    };
```

--------------------------------

### Uma Static Method: get controllersInfo()

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Documents the static getter `controllersInfo` for retrieving information about instantiated controllers, including controller and route details.

```TypeScript
static get controllersInfo(): IterableIterator<import("..").TControllerInfo>;
```

--------------------------------

### Uma Static Method: instance()

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Documents the static `instance()` method of the Uma class, used to get or instantiate the Uma object. Parameters are required for instantiation but optional for retrieving an existing instance.

```TypeScript
static instance(options?: TUmaOption): Uma;
```

--------------------------------

### Uma Static Method: get env()

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Documents the static getter `env` for retrieving the current runtime environment of the Uma application.

```TypeScript
static get env(): string;
```

--------------------------------

### Uma Static Method: get pluginKeys()

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Documents the static getter `pluginKeys` for retrieving an array of active plugin keys.

```TypeScript
static get pluginKeys(): any[];
```

--------------------------------

### Uma.js Aspect with Combined Before and Around Advice

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/AOP

This example extends the initial test.aspect.ts by adding an async around advice method alongside the existing before advice. The around method demonstrates how to intercept method execution, perform logic (like a login check), modify arguments, and process the result, showcasing a common use case for AOP.

```TypeScript
// ${URSA_ROOT}/aspect/test.aspect.ts

import { IAspect, IJoinPoint, IProceedJoinPoint, Result } from '@umajs/core'

export default class Test implements IAspect {
  before(point: IJoinPoint) {
    console.log('index: this is before:', point.target)
  }
  // ====> Create around advice
  async around(proceedPoint: IProceedJoinPoint) {
    const { proceed, args } = proceedPoint
    console.log('index: this is around before')

    // Check login, and other conditional logic
    if (!isLogin) return Result.redirect('/login')

    // args are parameters, can be checked, modified, etc.
    const result = await proceed(...args)
    console.log('index: this is around after')
    return result
  }
}
```

--------------------------------

### Node.js Interval-Based Scheduling with node-schedule

Source: https://umajs.github.io/%E6%8F%92%E4%BB%B6/schedule

Demonstrates how to configure interval-based scheduled tasks using the `node-schedule` library in Node.js. Examples show setting rules for specific seconds or minutes within an hour.

```TypeScript
import * as schedule from 'node-schedule';
let rule = new schedule.RecurrenceRule();
rule.second =[0,1,2,3......59] // 每秒执行
rule.second =0 // 每分钟0秒执行
rule.minute =0 // 每小时30分执行

this.scheduleInfo = {
    rule, // 每1分鐘更新一次
}
```

--------------------------------

### Instantiate UMA.js Service in an Aspect

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Service

This example illustrates how to manually instantiate and use a UMA.js service within an Aspect. Similar to plugins, services used in Aspects need to be explicitly instantiated, typically by accessing the `ctx` object from the `proceedPoint.target` property.

```typescript
// Aspect
import DemoService from '../service/demo.service'

export default class Method implements IAspect {
  async around(proceedPoint: IProceedJoinPoint) {
    const { target, proceed, args } = proceedPoint

    const demoService: DemoService = new DemoService(target.ctx)

    const result = await proceed(...args)

    return result
  }
}
```

--------------------------------

### Uma Static Method: get context()

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Documents the static getter `context` for retrieving the Koa context, which can be extended. After instantiation, it becomes the `ctx` object.

```TypeScript
static get context(): Koa.BaseContext & IContext;
```

--------------------------------

### Uma.js: Defining a Resource with @Resource Decorator

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/IOC

Example of defining a `UserModel` class and decorating it with `@Resource` to make it available for dependency injection within the Uma.js IOC container. This class will be instantiated and managed by the container.

```TypeScript
import { Resource } from '@umajs/core'

// ===> @Resource修饰器
@Resource()
export default class UserModel {
  findAll() {
    // ...
    return []
  }
}
```

--------------------------------

### Uma.js: Defining a BaseService Class

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/IOC

Example of a basic service class extending `BaseService` in Uma.js. Services defined this way can be injected into controllers using the `@Service` decorator.

```TypeScript
import { BaseService } from '@umajs/core'

export default class Demp extends BaseService {
  loadAll() {
    // return
  }
}
```

--------------------------------

### Umajs plugin-status: Configure 404 Status Handler

Source: https://umajs.github.io/%E6%8F%92%E4%BB%B6/Status

Example configuration for the plugin-status plugin, demonstrating how to define a custom handler for the 404 HTTP status code. The handler function, named '_404' (using the default prefix), receives the context (ctx) and can render a specific HTML page, such as '404.html', providing a unified response for 404 requests.

```TypeScript
// status.config.ts
export default <statusOptions>{
    // ===> 404状态码处理方法
    _404(ctx) {
        return ctx.render('404.html');
    }
}
```

--------------------------------

### Uma.js: Using @Resource and @Inject in a Service (Non-Strict Dir)

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/IOC

Example of a service class using `@Resource` to make itself available in the IOC container and `@Inject` to inject another resource (`User`). This demonstrates how to manage dependencies within a service, especially when `strictDir` is enabled.

```TypeScript
// service
import { Inject, Resource } from '@umajs/core'
import User from '../model/User'
@Resource()
export default class {
  @Inject(User) // or @Inject('User')
  user: User

  getDefaultUserAge() {
    return this.user.getAge()
  }
}
```

--------------------------------

### Apply Uma.js @Aspect Decorator to Class and Method

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/AOP

This example demonstrates the flexibility of the @Aspect decorator in Uma.js, showing how it can be applied to an entire controller class (affecting all its methods) or to specific individual methods, allowing granular control over aspect application.

```TypeScript
// Apply to class
@Aspect('test1')
export default class Index extends BaseController {
  // Apply to method
  @Aspect('test2')
  index() {
    return this.send('这里是首页') // This is the homepage
  }
}
```

--------------------------------

### Manage Session Data in Umajs Controller

Source: https://umajs.github.io/%E6%8F%92%E4%BB%B6/Session

This JavaScript code defines an `Index` controller extending `BaseController` to handle session operations. It provides three methods: `setss` to store a key-value pair ('haha', 'Hello World') in the session, `getss` to retrieve the value associated with 'haha' from the session, and `rmss` to remove the 'haha' key from the session. All methods return a `Result.send` response indicating the operation status.

```JavaScript
export default class Index extends BaseController {
  setss() {
    this.ctx.session.set('haha', 'Hello World')
    return Result.send('set session done.')
  }

  getss() {
    return Result.send(this.ctx.session.get('haha'))
  }

  rmss() {
    this.ctx.session.remove('haha')
    return Result.send('remove session done.')
  }
}
```

--------------------------------

### Uma.js AOP Decorator for Middleware Conversion

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Middleware

This example illustrates how to integrate middleware into Uma.js as an Aspect-Oriented Programming (AOP) decorator. It shows a controller method (`page`) decorated with `@Aspect.around('mw')` to apply the 'mw' aspect. The aspect itself is defined in `mw.aspect.ts`, demonstrating the conversion of a standard middleware function (`mwFn`) into an AOP aspect using `middlewareToAround` for both direct assignment and explicit `around` method implementation.

```typescript
// app/src/controller/index.controller.ts AOP形式使用中间件
import * as path from 'path';
import { BaseController, Path, Aspect, Result } from '@umajs/core';

export default class Index extends BaseController {
    @Aspect.around('mw')
    @Path('/page')
    page() {
       console.log(this.userService.getDefaultUserAge());
       return Result.view('index.html', { test: 3 })
    }
}

// app/src/aspect/mw.aspect.ts 定义AOP
import { IAspect, middlewareToAround } from '@umajs/core';

const mwFn = function() { // 定义中间件
  return async (ctx, next) => {
    console.log("****** mw before ******");
    await next();
    console.log("****** mw after *******");
  }
}

// 将中间件转换为切面方法
export default class implements IAspect {
    // 第一种方法
    // async around({ target, proceed, args }) {
    //     return await middlewareToAround(mwFn())({target, proceed, args});
    // }

    // 第二种方法
    around = middlewareToAround(mwFn());
}
```

--------------------------------

### Initialize UMajs Instance and Set Environment

Source: https://umajs.github.io/development/Uma

This TypeScript code demonstrates how to create a new UMajs application instance using Uma.instance(). It shows how to configure essential parameters like the router, root directory, and explicitly set the application's runtime environment (e.g., 'production' or 'development') via the env property. Finally, it initiates the application server on a specified port.

```TypeScript
// app.ts
import Uma from '@umajs/core'
import { Router } from '@umajs/router'

const uma = Uma.instance({
  Router,
  ROOT: __dirname,
  env: process.argv.indexOf('production') > -1 ? 'production' : 'development',
})

uma.start(8058)
```

--------------------------------

### Initialize Umajs Plugin via CLI

Source: https://umajs.github.io/%E6%8F%92%E4%BB%B6/dev

Use this command to quickly initialize a new plugin project or add a plugin to an existing Umajs application. Replace `[pluginName]` with your desired plugin name.

```Shell
uma plugin init [pluginName]
```

--------------------------------

### UMajs Core Object (Uma) API Reference

Source: https://umajs.github.io/development/Uma

Comprehensive API documentation for the `Uma` object, the central component of the UMajs framework. This section details its instance properties for accessing environment and configuration, instance methods for application lifecycle management, and static methods for global framework utilities, plugin interaction, and context retrieval.

```APIDOC
Uma Object:
  Description: The core object exposed by the framework, providing access to application context, configuration, and lifecycle methods.

  Instance Properties:
    uma.env: string
      Description: The current running environment of the application (e.g., 'development', 'production'). Can be defined during instance creation.
    uma.config: object
      Description: The consolidated configuration object for the current project, derived from files in the 'config' directory.
    uma.options: object
      Description: Options passed during the Uma instance initialization.
    uma.app: object
      Description: The underlying Koa application instance.

  Instance Methods:
    uma.start(port: number = 8058): void
      Description: Starts the UMajs application server on the specified port.
    uma.beforeLoad(): Function
      Description: A hook executed before the application fully loads.
    uma.afterLoad(): Function
      Description: A hook executed after the application has fully loaded.

  Static Methods:
    Uma.instance(options: object): Uma
      Description: Creates and returns a new UMajs framework instance.
      Parameters:
        options: object - Configuration options for the new instance, e.g., Router, ROOT, env.
      Returns: Uma - The new UMajs application instance.
    Uma.getEnv(): string
      Description: Retrieves the current running environment of the application.
      Returns: string - The environment string.
    Uma.getApp(): object
      Description: Retrieves the underlying Koa application instance.
      Returns: object - The Koa app instance.
    Uma.getServer(): object
      Description: Retrieves the HTTP server instance.
      Returns: object - The server instance.
    Uma.getOptions(): object
      Description: Retrieves the framework options.
      Returns: object - The options object.
    Uma.getConfig(): object
      Description: Retrieves the framework's consolidated configuration.
      Returns: object - The configuration object.
    Uma.getPluginConfig(): object
      Description: Retrieves the configuration for all registered plugins.
      Returns: object - An object containing plugin configurations.
    Uma.getEffectivePluginKeys(): string[]
      Description: Retrieves the keys of all currently active plugins.
      Returns: string[] - An array of active plugin keys.
    Uma.getPluginParams(pluginKey: string): object
      Description: Retrieves the parameters for a specific plugin by its key.
      Parameters:
        pluginKey: string - The key of the plugin.
      Returns: object - The parameters for the specified plugin.
    Uma.getContext(): object
      Description: Retrieves the application context object.
      Returns: object - The context object.
    Uma.getControllersInfo(): object
      Description: Retrieves information about all registered controllers.
      Returns: object - An object containing controller metadata.
```

--------------------------------

### Uma Initialization Options Interface (TUmaOption)

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Defines the `TUmaOption` type, which specifies the parameters accepted when initializing the Uma instance. It includes options for routing, root directory, environment, strict directory mode, configuration path, proxy, body parser, server creation, and lifecycle hooks.

```TypeScript
type TUmaOption = {
  // 路由
  Router: Function
  // 代码根路径，用于加载代码
  ROOT: string
  // 运行环境
  env?: 'development' | 'production' | string
  // 严格目录，非严格目录只有 'plugins' 是保留目录，严格目录还有 'controller'、'service'
  strictDir?: boolean
  // 配置文件夹路径
  configPath?: string
  proxy?: boolean
  subdomainOffset?: number
  jsonpBody?: TJsonpBody
  // 自带 koa-body 时的配置，不配置时 koa-body 中间件不生效
  bodyParser?: bodyParser.IKoaBodyOptions
  createServer?: (
    cb: (
      req: IncomingMessage | Http2ServerRequest,
      res: ServerResponse | Http2ServerResponse
    ) => void
  ) => Server
  beforeLoad?: (uma: Uma) => void
  afterLoaded?: (uma: Uma) => void
}
```

--------------------------------

### Uma Application Instance (uma.app)

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Describes `uma.app` as an instance of the Koa Application object, generated during Uma initialization.

```APIDOC
uma.app: Koa Application instance
```

--------------------------------

### Uma.js Static Property: options

Source: https://umajs.github.io/development/Uma

Retrieves the `TUmaOption` object containing all the initialization parameters used to configure the current Uma.js instance.

```APIDOC
static get options(): TUmaOption;
```

--------------------------------

### Define UMA.js Service by Extending BaseService

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Service

This snippet demonstrates the fundamental way to define a service in UMA.js. Services must extend `BaseService` from `@umajs/core` to enable proper mounting to the application's context (`ctx`), making them accessible for dependency injection and manual instantiation.

```typescript
import { BaseService } from '@umajs/core'

export default class demo extends BaseService {
  demoService() {
    return 'this is demo service'
  }
}
```

--------------------------------

### Uma.js Static Method: instance

Source: https://umajs.github.io/development/Uma

Retrieves or instantiates the Uma.js singleton. Parameters are required for the initial instantiation but optional when retrieving an already instantiated Uma object.

```APIDOC
static instance(options?: TUmaOption): Uma;
```

--------------------------------

### Uma.js Initialization Options (TUmaOption Type)

Source: https://umajs.github.io/development/Uma

Defines the type for the configuration object passed during Uma.js initialization. It includes properties for routing, application root path, environment settings, configuration directory, proxy settings, JSONP body configuration, Koa-body parser options, and custom server creation. It also defines `beforeLoad` and `afterLoad` lifecycle hooks.

```APIDOC
type TUmaOption = {
  // Router
  Router: Function
  // Code root path, used to load code
  ROOT: string
  // Running environment
  env?: 'development' | 'production' | string
  // Configuration folder path
  configPath?: string
  // Set to true when you need to get the real user IP
  proxy?: boolean
  subdomainOffset?: number
  jsonpBody?: TJsonpBody
  // Configuration for built-in koa-body; if not configured, koa-body middleware will not take effect
  bodyParser?: bodyParser.IKoaBodyOptions
  createServer?: (
    cb: (
      req: IncomingMessage | Http2ServerRequest,
      res: ServerResponse | Http2ServerResponse
    ) => void
  ) => Server
  beforeLoad?: (uma: Uma) => void
  afterLoaded?: (uma: Uma) => void
}
```

--------------------------------

### Instantiate Uma Service in a Plugin

Source: https://umajs.github.io/development/Service

Demonstrates how to instantiate a Uma Service, such as `DemoService`, within a plugin's middleware. The `ctx` (Koa context) is passed to the Service constructor for proper initialization and access to request-specific data.

```TypeScript
// plugin
import DemoService from '../service/demo.service';

export default (uma: Uma, options: any = {}): Koa.Middleware => {
    return (ctx, next) = > {
        const demoService: DemoService = new DemoService(ctx);
        // ...
    };
};
```

--------------------------------

### Comprehensive Uma.js logger configuration options

Source: https://umajs.github.io/%E6%8F%92%E4%BB%B6/Logger

Detailed configuration options for the Uma.js logger, including log levels, directory, specific log file names for different levels, encoding, output format, console level, debug allowance, buffer settings, and a custom formatter.

```JavaScript
exports.logger = {
  level: 'DEBUG', 
  dir: '/path/to/your/custom/log', 
  errorLogName: 'errorlogger.log', 
  infoLogName: 'infologger.log', 
  warnLogName: 'warnlogger.log', 
  file: '/path/to/your/custom/log/logger.log', 
  encoding: 'utf-8', 
  outputJSON: true, 
  consoleLevel: 'debug', 
  allowDebugAtProd: true, 
  flushInterval: 1000, 
  maxBufferLength: 1000, 
  formatter: function (meta) {
    return `[${meta.level} ${meta.pid}] ${meta.date} ${meta.hostname} ${meta.paddingMessage}: ${meta.message}`
  }, 
  splitTime: '00 00 * * * *' 
}
```

--------------------------------

### Define Controller with @Param and @Query Decorators

Source: https://umajs.github.io/development/Router

This TypeScript code snippet demonstrates how to define a controller in UMA.js using `@Param` and `@Query` decorators to extract values from the URL path and query string respectively. It shows a basic `index` method that logs the extracted `name` and `title`.

```TypeScript
import { BaseController, Path } from '@umajs/core'
import { Param, Query } from '@umajs/arg-decorator'
@Path('/page')
export default class Test extends BaseController {
  @Path('/:name')
  index(@Param('name') name: string, @Query('name') title: string) {
    console.log(`name: ${name}`)
    console.log(`title: ${title}`)
    return this.send('this is test/index router')
  }
}
```

--------------------------------

### Configure and use default UmaLogger instance

Source: https://umajs.github.io/%E6%8F%92%E4%BB%B6/Logger

Demonstrates initializing and using the default exported `UmaLogger` instance from `@umajs/logger` module, supported from v0.0.5.

```JavaScript
const logger = require('@umajs/logger')
logger.init({
  level: 'ALL',
  consoleLevel: 'ALL',
  encoding: 'utf-8',
  file: path.resolve(__dirname, '../log/logger.log')
})
logger.debug('debug')
logger.info('info GET')
logger.warn('warn')
logger.error('error')
```

--------------------------------

### Uma.js: Configuring Strict Directory Mode for IOC

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/IOC

Configuration snippet for Uma.js instance initialization, demonstrating how to enable `strictDir: true`. This setting is necessary to allow `@Resource` decorator usage within the `service` directory when not inheriting `BaseService`.

```TypeScript
const options: TUmaOption = {
  Router,
  bodyParser: { multipart: true },
  strictDir: true, // 启用非严格模式
  ROOT: __dirname,
  env: process.argv.indexOf('production') > -1 ? 'production' : 'development',
}
const uma = Uma.instance(options)
uma.start(8058)
```

--------------------------------

### UMajs Framework Configuration Structure

Source: https://umajs.github.io/development/Uma

This JSON snippet illustrates the typical structure of the uma.config object within the UMajs framework. It showcases how various configurations, including plugin settings (like 'logger' and 'model') and framework-level options (such as custom 404 error handling), are organized and accessed.

```JSON
{
  "plugin": {
    "logger": true,
    "model": true
  },
  "status": {
    "_404": "[object, function]"
  }
}
```

--------------------------------

### Uma.js Built-in Logger Categories

Source: https://umajs.github.io/%E6%8F%92%E4%BB%B6/Logger

Description of the different logger categories available in Uma.js, including `ContextLogger` (default), `errorLogger`, `infoLogger`, and `warnLogger`, and how to enable them.

```APIDOC
ContextLogger:
  Description: Default logger, enabled by default.
  Usage: this.ctx.logger.info()
  Context: Can obtain context.

errorLogger:
  Description: Logs for any .error() calls.
  Default: Disabled.
  Enable: Requires configuring 'dir' and 'errorLogName'.

infoLogger:
  Description: Logs for any .info() calls.
  Default: Disabled.
  Enable: Requires configuring 'dir' and 'infoLogName'.

warnLogger:
  Description: Logs for any .warn() calls.
  Default: Disabled.
  Enable: Requires configuring 'dir' and 'warnLogName'.
```

--------------------------------

### Accessing Parameters via Koa Context (ctx)

Source: https://umajs.github.io/development/Router

This TypeScript code snippet illustrates an alternative method for accessing path and query parameters in UMA.js. Instead of using decorators, parameters can be retrieved directly from the `this.ctx.param` and `this.ctx.query` objects, leveraging Koa's context capabilities.

```TypeScript
import { BaseController, Path } from '@umajs/core'
import { Param, Query } from '@umajs/arg-decorator'

@Path('/page')
export default class Test extends BaseController {
  @Path('/:name')
  index(@Param('name') name: string, @Query('name') title: string) {
    // ====> 从ctx中获取参数
    console.log(this.ctx.param.name)
    console.log(this.ctx.query.title)
    return this.send('this is test/index router')
  }
}
```

--------------------------------

### Uma.js: Using @Resource Decorator with Constructor Parameters

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/IOC

Demonstrates how to use the `@Resource` decorator with a parameter, which will be passed as a constructor argument when the class is instantiated and added to the IOC container.

```TypeScript
@Resource('user')
class Test {
    constructor(readonly tablename) {
    }
}
```

--------------------------------

### Umajs Plugin Configuration with Detailed Options

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Plugin

This JavaScript/TypeScript snippet demonstrates how to configure an Umajs plugin, specifically 'error-handler', by enabling it and providing a detailed `options` object. It includes specifying the plugin's name and package name within the `config/plugin.config.ts` file.

```TypeScript
// config/plugin.config.ts

export default {
  'error-handler': {
    enable: true,
    name: 'error-handler',
    packageName: '@umajs/plugin-error-handler',
    options: {
      foo: '1'
    }
  }
}
```

--------------------------------

### Uma.js Static Property: server

Source: https://umajs.github.io/development/Uma

Retrieves the Node.js HTTP or HTTPS server instance created by Uma.js, providing access to server-level operations.

```APIDOC
static get server(): http.Server | https.Server;
```

--------------------------------

### Instantiate UMA.js Service in a Plugin

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Service

This snippet demonstrates how to manually instantiate and utilize a UMA.js service within a plugin. Unlike controllers that use dependency injection, services in plugins require explicit instantiation by passing the `ctx` (context) object to their constructor.

```typescript
// plugin
import DemoService from '../service/demo.service';

export default (uma: Uma, options: any = {}): Koa.Middleware => {
    return (ctx, next) = > {
        const demoService: DemoService = new DemoService(ctx);
        // ...
    };
};
```

--------------------------------

### Uma.js Static Method: pluginOptions

Source: https://umajs.github.io/development/Uma

Retrieves the specific configuration parameters for a designated plugin by its name.

```APIDOC
static pluginOptions(pluginName: string): object;
```

--------------------------------

### Uma.js Static Property: config

Source: https://umajs.github.io/development/Uma

Retrieves the complete configuration object (`TConfig`) for the Uma.js application, encompassing all loaded settings.

```APIDOC
static get config(): TConfig;
```

--------------------------------

### Uma.js Static Property: pluginKeys

Source: https://umajs.github.io/development/Uma

Retrieves an array of keys (names) for all currently active and enabled plugins within the Uma.js application.

```APIDOC
static get pluginKeys(): any[];
```

--------------------------------

### Uma.js Static Property: app

Source: https://umajs.github.io/development/Uma

Retrieves the Koa Application instance that Uma.js uses internally. This allows direct interaction with the underlying Koa application.

```APIDOC
static get app(): Koa<Koa.DefaultState, IContext>;
```

--------------------------------

### Use plugin-logger in Uma.js Controller

Source: https://umajs.github.io/%E6%8F%92%E4%BB%B6/Logger

Demonstrates how to access and use the `ctx.logger` instance within an Uma.js controller to log messages at different levels (info, debug, warn, error).

```TypeScript
export default class Index extends BaseController {
  @Path('/index')
  @RequestMethod('GET')
  index() {
    this.ctx.logger.info(this.testService.return1())
    this.ctx.logger.debug('debug')
    this.ctx.logger.warn('warn')
    this.ctx.logger.error('error')
    return this.send('这里是首页')
  }
}
```

--------------------------------

### Uma Static Method: pluginOptions(pluginName: string)

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Uma

Documents the static method `pluginOptions` for retrieving parameters of a specific plugin by its name.

```TypeScript
static pluginOptions(pluginName: string): object;
```

--------------------------------

### Uma.js Static Property: env

Source: https://umajs.github.io/development/Uma

Retrieves the current running environment of the Uma.js application, such as 'development' or 'production'.

```APIDOC
static get env(): string;
```

--------------------------------

### Define a Basic Uma.js Aspect with Before Advice

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/AOP

This snippet demonstrates the fundamental structure for defining an Aspect in Uma.js. It shows how to implement the IAspect interface and define a 'before' advice method, which executes before the target method.

```TypeScript
// app/aspect/test.aspect.ts

import { IAspect, IJoinPoint } from '@umajs/core'

export default class Test implements IAspect {
  before(point: IJoinPoint) {
    console.log('index: this is before:', point.target)
  }
}
```

--------------------------------

### Uma.js: Consuming an Injected Service in a Controller

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/IOC

Shows a controller consuming a service that was previously defined and made available through `@Resource` and `@Inject`. This demonstrates the end-to-end flow of dependency injection, where the controller accesses methods from the injected service.

```TypeScript
// controller
import { BaseController, Path, Result, Inject } from '@umajs/core'
import UserService from '../service/user.service'

export default class Index extends BaseController {
  @Path('/user')
  test() {
    console.log(this.userService.getDefaultUserAge())
    return Result.send('get defaultUserAge')
  }
}
```

--------------------------------

### Cron Style Scheduler Syntax Reference

Source: https://umajs.github.io/%E6%8F%92%E4%BB%B6/schedule

This section explains the standard Cron syntax used for scheduling tasks. It details the six placeholders representing second, minute, hour, day of month, month, and day of week, emphasizing its recommendation for time consistency.

```Cron Syntax
*  *  *  *  *  *
┬ ┬ ┬ ┬ ┬ ┬
│ │ │ │ │  |
│ │ │ │ │ └ day of week (0 - 7) (0 or 7 is Sun)
│ │ │ │ └───── month (1 - 12)
│ │ │ └────────── day of month (1 - 31)
│ │ └─────────────── hour (0 - 23)
│ └──────────────────── minute (0 - 59)
└───────────────────────── second (0 - 59, OPTIONAL)
```

--------------------------------

### Uma.js Static Property: controllersInfo

Source: https://umajs.github.io/development/Uma

Retrieves an iterable iterator containing information about all instantiated controllers, including their associated routes and metadata.

```APIDOC
static get controllersInfo(): IterableIterator<import("..").TControllerInfo>;
```

--------------------------------

### Use UmaLogger instance in Uma.js Service

Source: https://umajs.github.io/%E6%8F%92%E4%BB%B6/Logger

Shows how to obtain and use the `UmaLogger.instance()` within an Uma.js service for logging, supported from v0.0.5.

```TypeScript
import { BaseService } from '@umajs/core'
import { UmaLogger } from '@umajs/logger'

export default class test extends BaseService {
  return1() {
    UmaLogger.instance().info('service test')
    return 1
  }
}
```

--------------------------------

### Uma.js @Aspect Decorator for Specific Advice Application

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/AOP

This snippet illustrates the different syntaxes for applying aspects in Uma.js. It shows how to apply all advice methods of an aspect using @Aspect('name') or selectively apply specific advice types (e.g., before, around) using Aspect.before('name') or Aspect.around('name').

```TypeScript
export default class Index extends BaseController {
  // All advice
  @Aspect('test1')
  // Specify only before advice to take effect
  @Aspect.before('test2')
  // Specify only around advice to take effect
  @Aspect.around('test2')
  index() {
    return this.send('这里是首页') // This is the homepage
  }
}
```

--------------------------------

### Instantiate Uma Service in Aspect-Oriented Programming (AOP)

Source: https://umajs.github.io/development/Service

Illustrates how to instantiate a Uma Service within an 'around' aspect function. The `target.ctx` from the `proceedPoint` is used to provide the necessary context to the Service, allowing it to interact with the current request's state during AOP execution.

```TypeScript
// src/aspect/demo.aspect.ts
import DemoService from '../service/demo.service'

export default async around(proceedPoint: IProceedJoinPoint) {
    const { target, proceed, args } = proceedPoint

    const demoService: DemoService = new DemoService(target.ctx)

    const result = await proceed(...args)

    return result
  }
```

--------------------------------

### Simplified Umajs Plugin Enable/Disable Configuration

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/Plugin

This JavaScript/TypeScript snippet shows a simplified approach to enable or disable an Umajs plugin, such as 'error-handler', by setting its value directly to `true` or `false` in the `config/plugin.config.ts` file, without requiring a full options object.

```TypeScript
// config/plugin.config.ts

export default {
  'error-handler': true
}
```

--------------------------------

### Uma.js: Injecting a Resource into a Controller

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/IOC

Illustrates how to inject a previously defined `@Resource`-decorated class instance (e.g., `UserModel`) into a controller using the `@Inject` decorator. The injected instance can then be used to access its methods without manual instantiation.

```TypeScript
import {
  BaseController,
  Path,
  Private,
  Param,
  Query,
  RequestMethod,
  Inject,
  Aspect,
} from '@umajs/core'
import UserModel from '../model/user.model'

export default class Index extends BaseController {
  // ===> 获取实例，实例的名称为@Resource修饰的class所在的文件名
  @Inject('user')
  user: UserModel

  async testModel() {
    // ===> 这里不需要创建user实例，@Resource已经将userModel实例化保存在容器中
    const userList = await this.user.findAll()
    return this.json(userList)
  }
}
```

--------------------------------

### Uma.js Aspect Join Point Interface Definitions

Source: https://umajs.github.io/%E5%9F%BA%E7%A1%80%E5%8A%9F%E8%83%BD/AOP

This section defines the core interfaces IJoinPoint and IProceedJoinPoint used within Uma.js AOP. IJoinPoint provides access to the target object and method arguments, while IProceedJoinPoint extends it with a 'proceed' function, essential for 'around' advice.

```APIDOC
export interface IJoinPoint {
  target: Object; // controller instance
  args: Array<any>; // method parameters
}

export interface IProceedJoinPoint extends IJoinPoint {
  proceed: Function; // method, Around exclusive
}
```
Tokens:
Raw