wok-server 0.5.0 → 0.7.0

package/documentation/en/engineering.md

@@ -0,0 +1,256 @@
+# Engineering Practices
+
+As the program grows in size, we need to split and better organize code files to manage large projects conveniently.
+
+The following are recommended practices.
+
+## Directory Structure
+
+The recommended approach is to organize by feature rather than by traditional layers (service layer, controller layer). This keeps highly related files together, making them easier to find and better for encapsulation.
+
+Suppose there are two business functions: user and tag. Here is the project structure:
+
+```
+Root Directory
+  ├── db-migration  Database migration files, only needed when using MySQL
+  ├── src Source directory
+  │   ├── auth Authorization
+  │   │   ├── auth.ts Authorization entity configuration
+  │   │   ├── auth-interceptor.ts Authorization interceptor
+  │   │   ├── create-auth.ts Create authorization endpoint (/auth/create)
+  │   │   ├── ccu-task.ts Online user count task
+  │   │   └── index.ts Package entry file, exports needed modules
+  │   ├── user User business function directory
+  │   │   ├── user.ts User entity configuration
+  │   │   ├── create-user.ts Create user endpoint (/user/create)
+  │   │   ├── delete-user.ts Delete user endpoint (/user/delete)
+  │   │   ├── update-user.ts Update user endpoint (/user/update)
+  │   │   └── index.ts Package entry file, exports needed modules
+  │   ├── tag Tag business function directory
+  │   │   ├── tag.ts Tag entity configuration
+  │   │   ├── create-tag.ts Create tag endpoint (/tag/create)
+  │   │   ├── delete-tag.ts Delete tag endpoint (/tag/delete)
+  │   │   └── index.ts Package entry file, exports needed modules
+  │   ├── exception.ts Global exceptions
+  │   └── main.ts Entry file, starts server, configures routes
+  ├── .env Development environment variable configuration
+  ├── package.json
+  ├── tsconfig.json
+  └── .gitignore
+```
+
+## File Description
+
+The exception.ts file contains custom business exceptions and exception handling interceptors.
+
+```ts
+/**
+ * Custom business exception.
+ */
+export class BusinessException {
+  constructor(
+    /**
+     * Message.
+     */
+    readonly message: string,
+    /**
+     * Custom status code, default 400
+     */
+    readonly status?: number
+  ) {}
+}
+
+/**
+ * Global exception interceptor that handles specific exceptions and provides appropriate response messages.
+ * @param exchange
+ * @param next
+ */
+export async function globalErrorInterceptor(
+  exchange: ServerExchange,
+  next: () => Promise<void>
+): Promise<void> {
+  try {
+    await next()
+  } catch (e) {
+    // Handle custom business exceptions
+    if (e instanceof BusinessException) {
+      const status = typeof e.status === 'number' ? e.status : 400
+      const message = e.message || ''
+      exchange.respondErrMsg(message, status)
+      return
+    }
+    // Handle validation exceptions
+    if (e instanceof ValidationException) {
+      exchange.respondErrMsg(`${e.propertyPath}: ${e.errMsg}`, 400)
+      return
+    }
+    // Other exceptions are thrown directly, framework responds with 500 status code by default
+    throw e
+  }
+}
+```
+
+Using custom business exceptions to abort request processing when business logic cannot proceed. Transactions will also rollback when exceptions occur during processing. This is the recommended approach.
+
+main.ts example:
+
+```ts
+import { createAuth, authInterceptor, ccuTask } from './auth'
+import { createUser, updateUser, deleteUser } from './user'
+import { createTag, deleteTag } from './tag'
+import { globalErrorInterceptor } from './exception'
+
+async function main() {
+  // Override Date prototype to serialize dates as numbers
+  // Optional, typically done for internationalization
+  Date.prototype.toJSON = function () {
+    return this.getTime() as any
+  }
+  // Activate MySQL
+  await enableMysql()
+  // Start server
+  await startWebServer({
+    // Static file configuration
+    static: {
+      // Frontend files
+      '/': { dir: 'fe', cacheAge: 600 }
+    },
+    // If there are many endpoints, it's recommended to write this configuration separately
+    // or split further into a separate router directory
+    // However, route configuration must be centralized and cannot be placed in individual business function directories
+    // Centralization makes it easier to find
+    routers: {
+      '/auth/create': createAuth,
+      '/user/create': createUser,
+      '/user/update': updateUser,
+      '/user/delete': deleteUser,
+      '/tag/create': createTag,
+      '/tag/delete': deleteTag
+    },
+    // Interceptors
+    interceptors: [globalErrorInterceptor, authInterceptor]
+  })
+  // Periodic task
+  // Count online users every 60 seconds
+  scheduleWithFixedDelay(60, 60, ccuTask)
+}
+
+main().catch(console.error)
+```
+
+Taking the user function as an example, let's explain entity configuration and endpoint writing.
+
+user/user.ts file example:
+
+```ts
+import { Table } from 'wok-server'
+
+/**
+ * User
+ */
+export interface User {
+  id: string
+  /**
+   * Code.
+   */
+  code: string
+  /**
+   * Nickname
+   */
+  nickname: string
+  /**
+   * Password
+   */
+  pwd: string
+  /**
+   * Status.
+   */
+  status: 'ACTIVATED' | 'DISABLED'
+  /**
+   * Create time.
+   */
+  create_at?: Date
+  /**
+   * Update time.
+   */
+  update_at?: Date
+}
+
+/**
+ * User table
+ */
+export const tableUser: Table<User> = {
+  tableName: 'user',
+  id: 'id',
+  columns: ['code', 'nickname', 'pwd', 'status'],
+  createdDate: {
+    type: 'date',
+    column: 'create_at'
+  },
+  updatedDate: {
+    type: 'date',
+    column: 'update_at'
+  }
+}
+```
+
+The user.ts file contains the entity type declaration and table configuration information. The example above is for MySQL; MongoDB is slightly different.
+
+Our recommendation is to write each endpoint in a separate file, putting all request and response information related to the endpoint in the file, and only exporting the endpoint handler function.
+
+user/create-user.ts example:
+
+```ts
+import { createJsonHandler, getMysqlManager, notBlank, length } from 'wok-server'
+import { User, tableUser } from './user'
+
+/**
+ * Request form information
+ */
+interface Form {
+  /**
+   * Code.
+   */
+  code: string
+  /**
+   * Nickname
+   */
+  nickname: string
+  /**
+   * Password
+   */
+  pwd: string
+}
+/**
+ * Response information
+ */
+interface Resp {
+  /**
+   * User id
+   */
+  id: string
+}
+
+/**
+ * Create user endpoint /user/create
+ */
+export const createUser = createJsonHandler<Form, Resp>({
+  // Validation
+  validation: {
+    code: [notBlank(), length({ max: 64 })],
+    nickname: [notBlank(), length({ max: 64 })],
+    pwd: [notBlank(), length({ max: 20 })]
+  },
+  // Business handling
+  async handle(body, exchange) {
+    const manager = getMysqlManager()
+    if (await manager.existsBy(tableUser, { code: body.code })) {
+      // Throw exception to abort processing
+      // Exception will be handled by interceptor and responded
+      throw new BusinessException('Code already exists')
+    }
+    const newUser = await manager.insert(tableUser, body)
+    return { id: newUser.id }
+  }
+})
+```

package/documentation/en/http-client.md

@@ -0,0 +1,32 @@
+# HTTP Client
+
+The HTTP client is an HTTP request tool built on top of Node.js's built-in http and https modules, providing three functions.
+
+| Function   | Description                                     |
+| :--------- | :---------------------------------------------- |
+| doRequest  | Generic HTTP request with customizable options |
+| postJson   | Send POST request and get JSON response         |
+| getJson    | Send GET request and get JSON response          |
+
+## Usage Examples
+
+```ts
+// GET request for JSON
+const list = await getJson<User[]>({
+  url: '/users'
+})
+
+// POST request for JSON
+const res = await postJson<Result>({
+  url: '/data/save',
+  body: { name: 'jack', age: 33 }
+})
+
+// Use doRequest with more custom options
+await doRequest({
+  url: '/users/001',
+  method: 'DELETE',
+  timeout: 5000,
+  followRedirect: true
+})
+```

package/documentation/en/i18n.md

@@ -0,0 +1,143 @@
+# Internationalization
+
+The internationalization component provides support for multilingual environments, allows extending new internationalization content, and automatically maintains language consistency.
+
+The i18n object is global. During request processing with asynchronous operations, you can use binding to maintain consistent language throughout a single request.
+
+## No Internationalization Handling
+
+By default, the internationalization component automatically updates the language based on the environment. However, when using containers or virtual machines, the image may default to English.
+
+If the project doesn't need internationalization and must ensure the framework's prompt messages are in Chinese, you can set the environment variable LANG in the program.
+
+```ts
+// Change environment variable LANG via process to specify Simplified Chinese
+// Must be written before framework import
+process.env.LANG = 'zh-CN'
+// After changing the variable, then import
+import {...} from 'wok-server'
+```
+
+If using containers, you can directly set the environment variable for the container, eliminating the need to modify code.
+
+## Usage Examples
+
+```ts
+// Get i18n object through getI18n function
+const i18n = getI18n()
+// getLang method gets current language
+const currentLang = i18n.getLang()
+// setLang method switches language, returns boolean indicating success
+// Only supported language tags can be switched successfully
+i18n.setLang('en')
+// buildMsg method builds message based on current language
+// First parameter is key (with type constraints), followed by 0 to multiple template parameters
+// More details in the configuration section below
+const msg = i18n.buildMsg('validate-err-max', '7')
+```
+
+## Language Tags and Matching Rules
+
+Currently only language + region format is supported, e.g., en-US, where en represents English and US represents the United States. The region is optional, and you can configure just the language, such as en. Matching is case-insensitive.
+
+If only "en-US" is configured but the language is set to "en-GB", it will still succeed. This is because during matching, if no exact language and region match is found, it looks for the language default (i.e., "en"). If the default is also not found, it finds the first configuration from the same language, ultimately using "en-US".
+
+If matching fails when switching languages, the switch is not performed and the language remains unchanged. **The default language is not used**. The default language is always en, and any extended i18n object must have English as the default for consistency and to ensure proper program operation.
+
+However, during program initialization, the language is automatically switched based on the current environment variables. If LANG or LC_CTYPE variables are set, the switch is performed accordingly. Extended internationalization content needs to be handled separately. See the extension section below for details.
+
+## Configure New Languages
+
+The following languages are built into the framework:
+
+| Language Tag | Language         |
+| :----------- | :--------------- |
+| en           | English (default)|
+| zh-CN        | Simplified Chinese|
+| zh-TW        | Traditional Chinese (Taiwan)|
+| zh-HK        | Traditional Chinese (Hong Kong)|
+| ja           | Japanese         |
+| ko           | Korean           |
+| ru           | Russian          |
+| es           | Spanish          |
+| de           | German           |
+| fr           | French           |
+| ar           | Arabic           |
+| pt           | Portuguese       |
+
+If the language you need is not built-in, you need to configure it yourself. Here is example code:
+
+```ts
+const i18n = getI18n()
+// Call setMsgs to configure language. First parameter is language tag, second is message templates
+i18n.setMsgs('ja', {
+  'validate-err-array': '値が配列ではありません',
+  'validate-err-enum': '値は {} の中のいずれかでなければなりません',
+  'validate-err-numer': '値が数字ではありません',
+  'validate-err-max': '{} 以下である必要があります',
+  'validate-err-min': '{} 以上である必要があります',
+  'validate-err-empty': '空であってはいけません',
+  'validate-err-string': '値が文字列のタイプではありません',
+  'validate-err-incorrect-format': '形式が正しくありません',
+  'validate-err-no-length': 'length属性が見当たりません',
+  'validate-err-length-not-number': 'lengthプロパティは数値ではありません',
+  'validate-err-min-length': '長さは {} 以上でなければりません',
+  'validate-err-max-length': '長さは {} 以下でなければなりません'
+})
+// After setting, you can successfully switch to the custom language
+i18n.setLang('ja')
+```
+
+## Extend New Content
+
+The above are the framework's built-in internationalization contents. In actual project development, there are many business-related internationalization requirements. You can extend new content based on the framework's i18n object. The extended object will maintain the same language as the global i18n object. When you need to change the language, simply call the global i18n object's setLang method.
+
+```ts
+// Get i18n object
+const i18n = getI18n()
+// New language template definition
+interface ExtMsgs {
+  hello: string
+  world: string
+}
+// Extend new content. Parameter is English template, always use English as default (explained earlier)
+// Returns an I18n type object with methods basically the same as the global i18n object, except without the extend method
+const extI18n = i18n.extend<ExtMsgs>({ hello: 'hello', world: 'world' })
+// Add Chinese to extended content
+extI18n.setMsgs('zh-cn', { hello: '你好', world: '世界' })
+
+// When the global i18n object changes language, extI18n also changes
+// In actual development, you can switch to the appropriate language after extension
+i18n.setLang('zh')
+
+i18n.getLang() // zh
+extI18n.getLang() // zh
+```
+
+In actual development, you can export the extI18n object for use by other modules.
+
+Note that for new language templates, values must all be string type, otherwise an error will be thrown. Template content supports 0 to multiple placeholders. For example, `{accountNotExist:"Account {} does not exist"}`, calling `buildMsg('accountNotExist','jack')` returns `"Account jack does not exist"`.
+
+## Bind Language
+
+Since the i18n object is global and shared, during request processing with asynchronous operations, it's possible that one request changes the language, executes an async operation, then another request changes the language again. When the async operation completes, the language may be incorrect.
+
+You can use the language binding feature in this case.
+
+```ts
+// Handle request, simplified demonstration, see MVC chapter for details
+async function handleReq(exchange: RouterExchange): Promise<void> {
+  // Headers, type is IncomingHttpHeaders, native type from Node.js http module
+  const headers = exchange.headers
+  // Bind to get a language-fixed i18n object. extI18n is the business internationalization object extended in the above demonstration
+  // bindByRequest generates a fixed-language i18n object based on the 'accept-language' header value
+  const boundI18n = extI18n.bindByRequest(headers)
+  await query1()
+  await query2()
+  await query3()
+  // Built messages are always related to the request's accepted language
+  const hello = boundI18n.buildMsg('hello')
+}
+```
+
+In addition, the i18n object has a switchByRequest method, which also takes IncomingHttpHeaders as a parameter and switches the language based on the headers.

package/documentation/en/index.md

@@ -1 +1,25 @@
 # node-server
+
+A Node.js backend development framework that is simple, easy to use, and has sufficient functionality. Developed with TypeScript, it has complete type definitions and high development efficiency.
+
+## Documentation Conventions
+
+All demonstration code in the documentation uses TypeScript. It is also recommended to use the framework only in TypeScript projects, as many features depend on type inference.
+
+The documentation does not list every option's details, as this would be too much work. However, it will provide as many usage examples as possible. For specific parameters, you can use your editor's documentation preview and jump functions to view the definition files.
+
+## Features
+
+- [Internationalization](./i18n.md)
+- [Validation](./validate.md)
+- [Configuration](./config.md)
+- [Logging](./log.md)
+- [Cache](./cache.md)
+- [MySQL](./mysql.md)
+- [MongoDB](./mongodb.md)
+- [MVC](./mvc.md)
+- [Task Scheduling](./task.md)
+- [Lock](./lock.md)
+- [HTTP Client](./http-client.md)
+- [Unit Testing](./test.md)
+- [Engineering Practices](./engineering.md)

package/documentation/en/lock.md

@@ -0,0 +1,51 @@
+# Lock
+
+Locks coordinate multiple asynchronous operation flows, allowing these flows to execute sequentially. This is very useful in concurrent request scenarios. A request may have many asynchronous operations during processing. Under concurrent conditions, operations from different requests may interleave. If there are modification operations, errors may occur, such as inventory reduction and lottery draws.
+
+## Usage
+
+Use the getLockManager function to get the lock manager object, and call the tryLock method to attempt to acquire a lock and execute logic upon successful acquisition.
+
+Simple scenario example code:
+
+```ts
+import { getLockManager } from 'wok-server'
+
+interface Form {
+  id: string
+  quantity: number
+}
+// Create JSON handler, simulate inventory reduction request
+createJsonHandler<Form>({
+  validation: {
+    id: [notBlank()],
+    quantity: [notNull(), min(1), max(10)]
+  },
+  async handle(body, exchange) {
+    const lock = getLockManager()
+    const res = lock.tryLock({
+      // Lock identifier, same identifiers create competition
+      key: `reduce-quantity-${body.id}`,
+      // Maximum wait time in seconds, tryLock returns false if lock not acquired within 2 seconds
+      waitSeconds: 2,
+      // Lock expiration time, set to hold lock for maximum 600 seconds to prevent deadlock
+      // If timeout occurs, other processes can acquire the lock regardless of whether run function completes
+      expiresInSeconds: 600,
+      // Execution function, executed if lock acquired successfully
+      // In concurrent request scenarios, requests that don't acquire the lock wait and execute in queue
+      async run() {
+        const product = await findProductById(body.id)
+        if (product.quantity < body.quantity) {
+          throw new BusinessException('Insufficient inventory')
+        }
+        await reduceQuantity(body.id, body.quantity)
+      }
+    })
+    // tryLock returns boolean indicating whether lock was acquired successfully
+    // If lock not acquired, provide business prompt
+    if (!res) {
+      throw new BusinessException('System busy, please try again later')
+    }
+  }
+})
+```

package/documentation/en/log.md

@@ -0,0 +1,109 @@
+# Logging
+
+Logging is used to record information, supporting simple level control and file writing functionality.
+
+## Environment Variables
+
+| Environment Variable   | Default | Description                                                                 |
+| :--------------------- | :------ | :-------------------------------------------------------------------------- |
+| LOG_LEVEL              | info    | Log level. Logs below the set level will not be output. Values: DEBUG, INFO, WARN, ERROR |
+| LOG_FILE               | false   | true or false, indicating whether to enable file logging                     |
+| LOG_FILE_MAX_DAYS      | 30      | Number of days to keep log files                                            |
+| LOG_FILE_DIR           | logs    | Log file storage path, supports relative and absolute paths. Relative paths are relative to the process execution directory |
+| LOG_CONSOLE            | true    | Whether to output logs to console, added in version 0.5                     |
+| LOG_FORMAT             | text    | Output log format, can be set to json or text, added in version 0.5. Note: console always outputs text |
+
+## Usage
+
+Get the logger object through getLogger() function, then call its methods to output logs.
+
+```ts
+const logger = getLogger()
+
+logger.info('Normal log message')
+
+const err = new Error('Error message test')
+logger.error('Error log output', err)
+
+if (logger.isDebugEnabled()) {
+  logger.debug(`Debug log output, args: ${JSON.stringify(args)}`)
+}
+```
+
+## Check if a Log Level is Supported
+
+The logger object provides isDebugEnabled, isInfoEnabled, isWarnEnabled, and isErrorEnabled methods to check if a log level is supported.
+
+```ts
+if (logger.isDebugEnabled()) {
+  logger.debug('Debug log output')
+}
+```
+
+These methods determine whether the current level is supported before processing. If not supported, the log content is not built. In some cases, this avoids unnecessary overhead of building log messages.
+
+## Add Prefix to Logs
+
+Starting from version 0.5, the getLogger function supports adding a prefix. For example:
+
+```ts
+const logger = getLogger('my-module')
+```
+
+This adds the prefix `[my-module]` to output logs, making it easier to distinguish logs from different modules.
+
+For example, the default log without prefix is:
+
+```
+[2024/08/19 16:27:18.214][INFO]Mysql migration
+```
+
+With prefix added:
+
+```
+[2024/08/19 16:27:18.214][INFO][my-module]Mysql migration
+```
+
+## Custom Log Storage
+
+The setLogStore function allows customizing log storage. Once set, it overrides file storage. Even if file logging is enabled, logs will not be output to files.
+
+Starting from version 0.5, logs are structured. The storage function parameters are log objects and configuration information, rather than a string.
+
+```ts
+setLogStore((log: Log, config: LogConfig) => {
+  // log type is Log
+  // config type is LogConfig
+  // You can store log content in message queues or independent file storage systems as needed
+  messageQueue.push(log)
+})
+```
+
+Log definition:
+
+```ts
+export interface Log {
+  /**
+   * Log time
+   */
+  time: Date
+  /**
+   * Log level
+   */
+  level: LogLevel
+  /**
+   * Log content
+   */
+  content: string
+  /**
+   * Error information
+   */
+  error?: any
+  /**
+   * Prefix information
+   */
+  prefix?: string
+}
+```
+
+LogConfig type contains the environment variable configuration information mentioned earlier, used to determine how to handle logs.