wok-server 0.5.0 → 0.6.0

package/dist/validation/validator/regexp.js

@@ -1,34 +1,34 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.regexp = void 0;
-const i18n_1 = require("../../i18n");
-/**
- * 正则校验
- * @param pattern 正则表达式
- * @param msg 错误消息
- * @returns
- */
-function regexp(pattern, msg) {
-    const validator = 'regexp';
-    return val => {
-        if (val === undefined || val === null) {
-            return { ok: true };
-        }
-        if (typeof val !== 'string') {
-            return { ok: false, validator, message: (0, i18n_1.getI18n)().buildMsg('validate-err-string') };
-        }
-        // 跳过空串
-        if (!val) {
-            return { ok: true };
-        }
-        if (!pattern.test(val)) {
-            return {
-                ok: false,
-                validator,
-                message: msg || (0, i18n_1.getI18n)().buildMsg('validate-err-incorrect-format')
-            };
-        }
-        return { ok: true };
-    };
-}
-exports.regexp = regexp;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.regexp = void 0;
+const i18n_1 = require("../../i18n");
+/**
+ * 正则校验
+ * @param pattern 正则表达式
+ * @param msg 错误消息
+ * @returns
+ */
+function regexp(pattern, msg) {
+    const validator = 'regexp';
+    return val => {
+        if (val === undefined || val === null) {
+            return { ok: true };
+        }
+        if (typeof val !== 'string') {
+            return { ok: false, validator, message: (0, i18n_1.getI18n)().buildMsg('validate-err-string') };
+        }
+        // 跳过空串
+        if (!val) {
+            return { ok: true };
+        }
+        if (!pattern.test(val)) {
+            return {
+                ok: false,
+                validator,
+                message: msg || (0, i18n_1.getI18n)().buildMsg('validate-err-incorrect-format')
+            };
+        }
+        return { ok: true };
+    };
+}
+exports.regexp = regexp;

package/documentation/en/cache.md

@@ -0,0 +1,56 @@
+# Cache
+
+The cache component provides simple in-memory caching with a random eviction strategy and support for expiration times.
+
+## Environment Variables
+
+| Environment Variable          | Description                                                                 |
+| :---------------------------- | :-------------------------------------------------------------------------- |
+| CACHE_DEFAULT_EXPIRE_IN_SECONDS | Default expiration time in seconds. Value: 1-3600, default 60             |
+| CACHE_STAT_TASK_ENABLED         | Whether to enable statistics task. When enabled, cache statistics are printed at specified intervals for observation |
+| CACHE_STAT_INTERVAL             | Statistics task execution interval in seconds. Value: 1-86400              |
+| CACHE_CLEANING_INTERVAL         | Expired data cleaning interval in seconds. Value: 1-3600, default 60      |
+| CACHE_MAX_ELEMENTS              | Maximum number of elements. Value: 1-NUM.MAX_VALUE, default 1024         |
+
+After enabling cache statistics, statistics will be output to the log at the specified interval.
+
+```
+[2023/09/27 11:31:35.690][INFO]Cache statistics,
+time window: 2023/09/27 11:31:35.442 - now, hit: 4/4, capacity: 120/100
+```
+
+The example above shows statistics including hit rate and capacity usage. In the example, capacity is exceeded, which is normal because the cleaning task hasn't run yet. Statistics are time-windowed and only count within the current cycle.
+
+## Performance Considerations
+
+CACHE_CLEANING_INTERVAL controls the cache cleaning task cycle. If the project has a lot of cached content, this should be set smaller to clean up invalid data promptly.
+
+Excessive cached data affects GC because the garbage collector cannot reclaim cached objects, but the marking and memory compaction work is still costly. In addition to more frequent cleaning, cache records should also have shorter expiration times when possible.
+
+To reduce overhead, the cache component uses a random eviction strategy and does not support configurable eviction strategies.
+
+If large amounts of data need to be cached without affecting GC, consider alternative solutions such as off-heap memory (Buffer) or external cache services (Redis, etc.). In-memory caching is only suitable for caching small amounts of short-term data.
+
+## Examples
+
+You can get the global cache object through the getCache function and use its methods to work with the cache.
+
+```ts
+// Get cache object
+const cache = getCache()
+
+// Use default expiration time
+cache.put('abc', 123)
+let value = cache.get('abc') // 123
+
+// Specify expiration time (third parameter, in seconds)
+cache.put('d', 2233, 1)
+// Remove cache entry
+cache.remove('d')
+```
+
+The cache object has a computeIfAbsent method that allows you to specify a function to generate cache content. If no cached data exists, it generates and caches it; otherwise, it returns the cached data directly.
+
+```ts
+const user = await cache.computeIfAbsent(`get-user-${userId}`, findUserById(userId))
+```

package/documentation/en/config.md

@@ -0,0 +1,96 @@
+# Configuration
+
+The configuration module maps configuration objects to environment variables and provides them to other modules. It can be combined with the validation component to extend new features.
+
+Three functions are provided:
+
+| Function        | Description                                                                 |
+| :-------------- | :-------------------------------------------------------------------------- |
+| registerConfig  | Register configuration, which immediately matches environment variables and returns the mapped configuration object |
+| getConfig       | Get configuration                                                           |
+| generateConfig  | Generate configuration from environment variables without registering       |
+
+## Configuration Types and Instance Objects
+
+To perform configuration mapping, you must first define a configuration type. Here is an example:
+
+```ts
+/**
+ * Configuration definition
+ */
+interface CustomConfig {
+  appId: string
+  appSecret: string
+}
+```
+
+**All properties of the configuration type must be non-nullable and must have values for mapping to work.**
+
+You can also skip defining a type and directly declare an object, then call registerConfig to complete automatic type inference. See the registerConfig description below for details.
+
+Currently, configuration objects only support the following types: string, number, boolean.
+
+## registerConfig
+
+Environment variable mapping requires a prefix. The object's properties are concatenated with the prefix and then converted to match environment variables. For example, if the configuration object has a property `appId` and the prefix is `cus`, the matching environment variable would be `CUS_APP_ID`.
+
+Each call to registerConfig outputs logs showing the matching status for debugging purposes.
+
+Example usage of registerConfig:
+
+```ts
+/**
+ * Configuration definition
+ */
+interface CustomConfig {
+  appId: string
+  appSecret: string
+  ssl: boolean
+  timeout: number
+}
+
+// Call registerConfig to map with environment variables
+// Returns the mapped configuration object
+const config = registerConfig<CustomConfig>(
+  // First parameter: default configuration object, must have defaults for fallback
+  { appId: '', appSecret: '', ssl: true, timeout: 5000 },
+  // Second parameter: configuration prefix
+  'custom',
+  // Third parameter: validation rules, optional, see validation component for details
+  {
+    appId: [notBlank()],
+    appSecret: [notBlank()],
+    ssl: [notNull()],
+    timeout: [notNull(), min(1000), max(3600)]
+  }
+)
+```
+
+You can also skip defining the configuration object and directly write the default configuration object. Automatic type inference is done through the default configuration object in the first parameter, which is more concise.
+
+```ts
+const config2 = registerConfig(
+  {
+    url: 'http://localhost/api',
+    account: 'Jack'
+  },
+  'c2',
+  {
+    url: [notBlank()]
+  }
+)
+```
+
+## getConfig
+
+The getConfig function takes only one parameter, the prefix, and returns the configuration object.
+
+This is rarely needed. It is recommended to export the configuration object returned by registerConfig for use by other modules.
+
+```ts
+const config2 = getConfig('c2')
+```
+
+## generateConfig
+
+Generates a configuration object from environment variables with the same parameters as registerConfig. Unlike registerConfig, generateConfig can be called multiple times, making it convenient to regenerate configuration after changing environment variables at runtime. registerConfig locks the configuration once registered and cannot be changed. This design facilitates program testing, simulating program execution in different environments, and other special requirements.

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)