wok-server 0.4.13 → 0.6.0

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.

package/documentation/en/mongodb.md

@@ -0,0 +1,256 @@
+# MongoDB
+
+The MongoDB component is built on top of the [official MongoDB driver](https://www.npmjs.com/package/mongodb), providing simple entity mapping and CRUD operations for ease of use.
+
+## Environment Variables
+
+The MongoDB component supports multiple instances. By default, it uses MONGO as the prefix.
+
+| Variable Name               | Description                                                                 |
+| :-------------------------- | :-------------------------------------------------------------------------- |
+| MONGO_URI                   | MongoDB connection string. Example: mongodb+srv://<user>:<password>@<cluster-url> |
+| MONGO_MAX_POOL_SIZE         | Maximum connection pool size, default 10                                    |
+| MONGO_MIN_POOL_SIZE         | Minimum connection pool size, default 1                                     |
+| MONGO_MAX_CONNECTING        | Maximum concurrent connections in pool, default 10                          |
+| MONGO_MAX_IDLE_TIME_MS      | Maximum idle time for connections in milliseconds, default 60000            |
+| MONGO_WAIT_QUEUE_TIMEOUT_MS | Maximum wait time for connections in milliseconds, default 60000            |
+| MONGO_SLOW_QUERY_WARN       | Slow query warning. When enabled, warning logs are output for slow queries. Default enabled |
+| MONGO_SLOW_QUERY_MS         | Slow query threshold in milliseconds, default 200                           |
+| MONGO_TRANSACTION_TIMEOUT   | Transaction timeout in milliseconds, default 5000                           |
+| MONGO_TRANSACTION_STRICT    | Transaction strict mode, default true. Set to false to disable             |
+
+## Usage
+
+### Initialization
+
+First use the enableMongoDB function to enable MongoDB, then use related features.
+
+```ts
+await enableMongoDB()
+```
+
+The component supports multiple instances. If multiple databases need to be connected, you can specify a new name.
+
+```ts
+// Enable implementation with name md2
+await enableMongoDB('md2')
+```
+
+By default, environment variables use MONGO as the prefix. For named instances, the uppercase name is used as the prefix. In the example above, the instance named md2 uses the MD2 prefix.
+
+```
+# Configure default connection
+MONGO_URI=mongodb://test1:t1abcd@localhost/t1
+MONGO_MAXPOOLSIZE=10
+# Configure connection for md2 instance
+MD2_URI=mongodb://test2:t2abcd@localhost/t2
+MD2_MAXPOOLSIZE=10
+```
+
+Use the getMongoDBManager function to get a manager instance for operating MongoDB, with optional name parameter to get the corresponding instance.
+
+```ts
+// Default instance
+const manager = getMongoDBManager()
+// md2 instance
+const md2 = getMongoDBManager('md2')
+```
+
+### Entity Mapping
+
+Basic CRUD operations can be performed through the manager object's methods, but configuration is required before operation.
+
+Configuration consists of two parts: collection data format definition and collection information settings. Here is an example:
+
+```ts
+/**
+ * User collection data definition.
+ * Primary key name is fixed as _id, mapping configuration not supported. Entity class should not have _id field.
+ */
+export interface User {
+  nickname: string
+  skills: string[]
+  // Create and update fields can be set to be automatically managed by the component
+  // Due to type constraints, set as optional for insertion and update without filling
+  createAt?: Date
+  updateAt?: Date
+}
+/**
+ * User collection information. Type is MongoCollection with generic type as entity type.
+ * Primary key name is fixed as _id, mapping configuration not supported.
+ */
+export const collUser: MongoCollection<User> = {
+  /**
+   * Collection name
+   */
+  collectionName: 'user',
+  /**
+   * Configure creation time field, automatically managed by component
+   */
+  createdDate: {
+    type: 'date',
+    field: 'createAt'
+  },
+  /**
+   * Configure update time field, automatically managed by component
+   */
+  updatedDate: {
+    type: 'date',
+    field: 'updateAt'
+  }
+}
+```
+
+### CRUD Operations
+
+Now you can perform CRUD operations. All manager operations take the collection information as the first parameter, which is the collUser configured earlier.
+
+```ts
+const manager = getMongoDBManager()
+// Insert record. If _id has no value, database generates ObjectId as primary key
+await manager.insert(collUser, { _id: '007', nickname: 'Spark', skills: [] })
+// Find by id
+const user1 = await manager.findById(collUser, '007')
+// Update nickname
+user1.nickname = 'ryan'
+await manager.update(collUser, user1)
+// Check if id exists
+const exist = await manager.existsById(collUser, 'xyz')
+// Check if record exists by condition
+const exist2 = await manager.existsBy(collUser, { nickname: 'acute' })
+// Delete by id
+await manager.deleteById(collUser, '007')
+// Delete by condition. Use with caution, deleting large amounts of data at once may cause high database load and online incidents
+await manager.deleteMany(collUser, { nickname: 'smith' })
+// Find first matching record
+const jack = await manager.findFirst(collUser, { nickname: 'jack' })
+// Find all records. Use with caution, querying large amounts of data at once may cause memory issues and take a long time to transfer
+await manager.findAll(collUser)
+// Count. Use with caution, count operation may have performance issues even with indexes for large data sets
+const count = await manager.count(collUser, { nickname: 'Steve' })
+// Find users with skills, return at most 2 results
+const list = await manager.find(
+  collUser,
+  {
+    skills: { $exists: true }
+  },
+  { offset: 0, limit: 2 }
+)
+// Pagination, sort by id, 20 items per page, query page 2
+const page = await manager.paginate(
+  collUser,
+  {
+    skills: { $exists: true }
+  },
+  { pn: 2, pz: 20, orderBy: ['_id', 'asc'] }
+)
+```
+
+### Update Methods Description
+
+The manager provides four update methods: update, partialUpdate, updateMany, updateOne.
+
+| Method Name    | Description                                                                 |
+| :------------- | :-------------------------------------------------------------------------- |
+| update         | Full document update, requires complete document information, returns updated document, throws exception on failure |
+| partialUpdate  | Partial update, only needs id and fields to update, returns whether update succeeded |
+| updateMany     | Update all matching records, returns number of updated documents             |
+| updateOne      | Update only one matching record, only supports equality conditions, does not support range conditions |
+
+```ts
+// update requires complete document, usually need to query first
+const user = await manager.findById(collUser, '007')
+user.nickname = 'ryan'
+await manager.update(collUser, user)
+// partialUpdate does not require querying first
+// Update nickname of document with id 001 to lily
+await manager.partialUpdate(collUser, '001', { $set: { nickname: 'lily' } })
+// updateMany differs from partialUpdate only in that id parameter becomes condition
+// Increment credit by 1 for all users with credit <= 10
+await manager.updateMany(collUser, { credit: { $lte: 10 } }, { $inc: { credit: 1 } })
+```
+
+## Version Management
+
+The enableMongoDB function supports a migration parameter for version management and automatic migration.
+
+```ts
+await enableMongoDB({
+  migration: {
+    versionList: versionList
+  }
+})
+```
+
+versionList is an array of MongoMigrationVersion (`(db: Db) => Promise<void>`) type elements. Db is the database provided by the MongoDB driver, which can perform various operations such as creating collections and indexes.
+
+The version number is the index of the element, meaning each program update should add elements. Existing elements cannot be modified, and the program does not perform any validation. During startup, the program checks the already updated version number (index of version list), then finds subsequent versions from the version list, updates them one by one, and marks the completed version numbers.
+
+Here is an example of the versionList parameter:
+
+```ts
+const versionList: MongoMigrationVersion[] = [
+  // Version 1
+  async db => {
+    // Create a collection, insert some data, then create indexes
+    await db.createCollection('user')
+    await db
+      .collection<User>('user')
+      .createIndex({ nickname: 1 }, { unique: true, name: 'uk_nickname' })
+    await db
+      .collection<User>('user')
+      .createIndex({ skills: 1 }, { unique: false, name: 'idx_skills' })
+    // Preset data
+    await db.collection<User>('user').insertOne({
+      nickname: 'jack',
+      skills: ['java'],
+      createAt: new Date(),
+      updateAt: new Date()
+    })
+  },
+  // Version 2
+  async db => {
+    // Delete an index
+    await db.collection<User>('user').dropIndex('idx_skills')
+    // Preset data
+    await db.collection<User>('user').insertOne({
+      nickname: 'tom',
+      skills: ['golang', 'rust'],
+      createAt: new Date(),
+      updateAt: new Date()
+    })
+  }
+]
+```
+
+## Transactions
+
+Use the manager object's tx method to execute transaction operations. The method accepts a function parameter whose parameter is a session object. **All operations in the transaction must call session methods, which are the same as manager methods**.
+
+```ts
+await manager.tx(
+  async session => {
+    // Update order and account balance in transaction
+    // orderId Order ID
+    // accountId Account ID
+    // amount Order amount
+    await session.partialUpdate(collOrder, orderId, { $set: { status: 'finished' } })
+    await session.partialUpdate(collAccount, accountId, { $inc: { balance: -amount } })
+  },
+  // Additional options, can set timeout per transaction
+  { timeout: 1000 }
+)
+```
+
+### Strict Mode
+
+Transactions have strict mode enabled by default. Many operations are prohibited in strict mode. Set the environment variable MONGO_TRANSACTION_STRICT (default variable name, use corresponding name for multiple instances) to false to disable it.
+
+In strict mode, the following operations are prohibited in transactions:
+
+1. Bulk insert insertMany
+2. Bulk update updateMany
+3. Bulk delete deleteMany
+4. Bulk query and count find, count, paginate
+5. findByIdIn with more than 100 parameters
+6. Any operation called via session exceeding 10 times