wok-server 0.5.0 → 0.7.0

package/dist/validation/validator/min-length.js

@@ -1,33 +1,33 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.minLength = void 0;
-const i18n_1 = require("../../i18n");
-/**
- * 最小长度校验，可用于字符串或数组.
- * @returns
- */
-function minLength(minLength, message) {
-    const validator = 'minLength';
-    return val => {
-        // 不校验空
-        if (!val) {
-            return { ok: true };
-        }
-        if (typeof val.length !== 'number') {
-            return { ok: false, validator, message: (0, i18n_1.getI18n)().buildMsg('validate-err-no-length') };
-        }
-        const { length } = val;
-        if (typeof length !== 'number') {
-            return { ok: false, validator, message: (0, i18n_1.getI18n)().buildMsg('validate-err-length-not-number') };
-        }
-        if (length < minLength) {
-            return {
-                ok: false,
-                validator,
-                message: message || (0, i18n_1.getI18n)().buildMsg('validate-err-min-length', `${minLength}`)
-            };
-        }
-        return { ok: true };
-    };
-}
-exports.minLength = minLength;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.minLength = void 0;
+const i18n_1 = require("../../i18n");
+/**
+ * 最小长度校验，可用于字符串或数组.
+ * @returns
+ */
+function minLength(minLength, message) {
+    const validator = 'minLength';
+    return val => {
+        // 不校验空
+        if (!val) {
+            return { ok: true };
+        }
+        if (typeof val.length !== 'number') {
+            return { ok: false, validator, message: (0, i18n_1.getI18n)().buildMsg('validate-err-no-length') };
+        }
+        const { length } = val;
+        if (typeof length !== 'number') {
+            return { ok: false, validator, message: (0, i18n_1.getI18n)().buildMsg('validate-err-length-not-number') };
+        }
+        if (length < minLength) {
+            return {
+                ok: false,
+                validator,
+                message: message || (0, i18n_1.getI18n)().buildMsg('validate-err-min-length', `${minLength}`)
+            };
+        }
+        return { ok: true };
+    };
+}
+exports.minLength = minLength;

package/dist/validation/validator/min.js

@@ -1,29 +1,29 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.min = void 0;
-const i18n_1 = require("../../i18n");
-/**
- * 最小值校验.
- * @param min 最小值
- * @param msg 错误消息
- */
-function min(min, msg) {
-    const validator = 'min';
-    return val => {
-        if (val == undefined || val === null) {
-            return { ok: true };
-        }
-        if (typeof val !== 'number') {
-            return { ok: false, validator, message: (0, i18n_1.getI18n)().buildMsg('validate-err-numer') };
-        }
-        if (val < min) {
-            return {
-                ok: false,
-                validator,
-                message: msg || (0, i18n_1.getI18n)().buildMsg('validate-err-min', `${min}`)
-            };
-        }
-        return { ok: true };
-    };
-}
-exports.min = min;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.min = void 0;
+const i18n_1 = require("../../i18n");
+/**
+ * 最小值校验.
+ * @param min 最小值
+ * @param msg 错误消息
+ */
+function min(min, msg) {
+    const validator = 'min';
+    return val => {
+        if (val == undefined || val === null) {
+            return { ok: true };
+        }
+        if (typeof val !== 'number') {
+            return { ok: false, validator, message: (0, i18n_1.getI18n)().buildMsg('validate-err-numer') };
+        }
+        if (val < min) {
+            return {
+                ok: false,
+                validator,
+                message: msg || (0, i18n_1.getI18n)().buildMsg('validate-err-min', `${min}`)
+            };
+        }
+        return { ok: true };
+    };
+}
+exports.min = min;

package/dist/validation/validator/not-blank.js

@@ -1,33 +1,33 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.notBlank = void 0;
-const i18n_1 = require("../../i18n");
-/**
- * 字符串非空校验，以下的情况不会通过校验：undefined，null，非 string 类型，空白字符串.
- * @param message
- * @returns
- */
-function notBlank(message) {
-    const validator = 'notBlank';
-    return val => {
-        if (val === undefined || val === null) {
-            return {
-                ok: false,
-                validator,
-                message: message || (0, i18n_1.getI18n)().buildMsg('validate-err-empty')
-            };
-        }
-        if (typeof val !== 'string') {
-            return { ok: false, validator, message: (0, i18n_1.getI18n)().buildMsg('validate-err-string') };
-        }
-        if (!val.trim()) {
-            return {
-                ok: false,
-                validator,
-                message: message || (0, i18n_1.getI18n)().buildMsg('validate-err-empty')
-            };
-        }
-        return { ok: true };
-    };
-}
-exports.notBlank = notBlank;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.notBlank = void 0;
+const i18n_1 = require("../../i18n");
+/**
+ * 字符串非空校验，以下的情况不会通过校验：undefined，null，非 string 类型，空白字符串.
+ * @param message
+ * @returns
+ */
+function notBlank(message) {
+    const validator = 'notBlank';
+    return val => {
+        if (val === undefined || val === null) {
+            return {
+                ok: false,
+                validator,
+                message: message || (0, i18n_1.getI18n)().buildMsg('validate-err-empty')
+            };
+        }
+        if (typeof val !== 'string') {
+            return { ok: false, validator, message: (0, i18n_1.getI18n)().buildMsg('validate-err-string') };
+        }
+        if (!val.trim()) {
+            return {
+                ok: false,
+                validator,
+                message: message || (0, i18n_1.getI18n)().buildMsg('validate-err-empty')
+            };
+        }
+        return { ok: true };
+    };
+}
+exports.notBlank = notBlank;

package/dist/validation/validator/not-null.js

@@ -1,21 +1,21 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.notNull = void 0;
-const i18n_1 = require("../../i18n");
-/**
- * 非空校验.
- * @param message
- */
-function notNull(message) {
-    return val => {
-        if (val === null || val === undefined) {
-            return {
-                ok: false,
-                message: message || (0, i18n_1.getI18n)().buildMsg('validate-err-empty'),
-                validator: 'notNull'
-            };
-        }
-        return { ok: true };
-    };
-}
-exports.notNull = notNull;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.notNull = void 0;
+const i18n_1 = require("../../i18n");
+/**
+ * 非空校验.
+ * @param message
+ */
+function notNull(message) {
+    return val => {
+        if (val === null || val === undefined) {
+            return {
+                ok: false,
+                message: message || (0, i18n_1.getI18n)().buildMsg('validate-err-empty'),
+                validator: 'notNull'
+            };
+        }
+        return { ok: true };
+    };
+}
+exports.notNull = notNull;

package/dist/validation/validator/plain-obj.js

@@ -1,32 +1,32 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.plainObject = void 0;
-/**
- * 普通对象校验.
- * @param opts
- * @returns
- */
-function plainObject(opts) {
-    const validator = 'plainObject';
-    return val => {
-        if (!val) {
-            return { ok: true };
-        }
-        for (const entry of Object.entries(opts)) {
-            const [prop, validators] = entry;
-            const v = val[prop];
-            for (const validate of validators) {
-                const result = validate(v);
-                if (!result.ok) {
-                    const propPath = [prop];
-                    if (result.propPath) {
-                        propPath.push(...result.propPath);
-                    }
-                    return { ok: false, validator, message: result.message, propPath };
-                }
-            }
-        }
-        return { ok: true };
-    };
-}
-exports.plainObject = plainObject;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.plainObject = void 0;
+/**
+ * 普通对象校验.
+ * @param opts
+ * @returns
+ */
+function plainObject(opts) {
+    const validator = 'plainObject';
+    return val => {
+        if (!val) {
+            return { ok: true };
+        }
+        for (const entry of Object.entries(opts)) {
+            const [prop, validators] = entry;
+            const v = val[prop];
+            for (const validate of validators) {
+                const result = validate(v);
+                if (!result.ok) {
+                    const propPath = [prop];
+                    if (result.propPath) {
+                        propPath.push(...result.propPath);
+                    }
+                    return { ok: false, validator, message: result.message, propPath };
+                }
+            }
+        }
+        return { ok: true };
+    };
+}
+exports.plainObject = plainObject;

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.