📝 document async config model aliases

docs/api/async-logger-build-config-type.md

@@ -0,0 +1,74 @@
+---
+name: async-logger-build-config-type
+group: api
+category: async
+update-time: 20260613
+description: Public async build config alias combining the base logger config and async runtime config.
+key-word:
+    - async
+    - build
+    - config
+    - public
+---
+
+## Async-logger-build-config-type
+
+`AsyncLoggerBuildConfig` is the public config object that combines the base synchronous `LoggerConfig` with the async runtime `AsyncLoggerConfig`. It is a direct alias to the build-config model used by async builder APIs, parsers, and serializers.
+
+### Interface
+
+```moonbit
+pub type AsyncLoggerBuildConfig = @utils.AsyncLoggerBuildConfig
+```
+
+#### output
+
+- `AsyncLoggerBuildConfig` - Public async build config object containing `logger` and `async_config`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a built logger instance.
+- The current fields are `logger : LoggerConfig` and `async_config : AsyncLoggerConfig`.
+- `AsyncLoggerBuildConfig::new(...)` constructs this type as the main handoff object for async build flows.
+- `build_async_logger(...)`, `build_async_text_logger(...)`, `parse_async_logger_build_config_text(...)`, `async_logger_build_config_to_json(...)`, and `stringify_async_logger_build_config(...)` all consume or produce this same public shape.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need One Typed Object For Full Async Logger Setup
+
+When sync sink setup and async runtime policy should move together through application boot code:
+```moonbit
+let config : AsyncLoggerBuildConfig = AsyncLoggerBuildConfig::new(
+  logger=@bitlogger.LoggerConfig::new(target="svc"),
+  async_config=AsyncLoggerConfig::new(max_pending=64),
+)
+```
+
+In this example, both layers of logger setup are kept in one typed value.
+
+#### When Need To Export Or Inspect The Full Build Shape
+
+When application code should inspect the combined async build configuration before constructing the logger:
+```moonbit
+let config = AsyncLoggerBuildConfig::new(async_config=AsyncLoggerConfig::new(max_batch=4))
+println(stringify_async_logger_build_config(config, pretty=true))
+```
+
+In this example, the same public config object supports both review and later build steps.
+
+### Error Case
+
+e.g.:
+- `AsyncLoggerBuildConfig` itself does not have a runtime failure mode.
+
+- If only async runtime policy is needed and the base sync logger config is irrelevant, this type may be broader than necessary and `AsyncLoggerConfig` is the smaller fit.
+
+### Notes
+
+1. Use `AsyncLoggerBuildConfig::new(...)` when one object should carry both sync and async logger setup.
+
+2. Use `parse_async_logger_build_config_text(...)` when the same shape should come from JSON text instead of handwritten code.

docs/api/async-logger-config-type.md

@@ -0,0 +1,74 @@
+---
+name: async-logger-config-type
+group: api
+category: async
+update-time: 20260613
+description: Public async logger config alias used for queue, batching, linger, and flush settings.
+key-word:
+    - async
+    - config
+    - alias
+    - public
+---
+
+## Async-logger-config-type
+
+`AsyncLoggerConfig` is the public config object used to describe async queue capacity, overflow behavior, batching, linger timing, and flush policy. It is a direct alias to the async config model used by `async_logger(...)`, config parsers, and async config serializers.
+
+### Interface
+
+```moonbit
+pub type AsyncLoggerConfig = @utils.AsyncLoggerConfig
+```
+
+#### output
+
+- `AsyncLoggerConfig` - Public async config object containing `max_pending`, `overflow`, `max_batch`, `linger_ms`, and `flush`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a runtime logger handle.
+- The current fields are `max_pending : Int`, `overflow : AsyncOverflowPolicy`, `max_batch : Int`, `linger_ms : Int`, and `flush : AsyncFlushPolicy`.
+- `AsyncLoggerConfig::new(...)` constructs this type with the same normalization rules used by the runtime.
+- `parse_async_logger_config_text(...)`, `async_logger_config_to_json(...)`, and `stringify_async_logger_config(...)` all operate on this same public config shape.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Async Runtime Policy Value
+
+When async queue and flush behavior should be passed around as structured config:
+```moonbit
+let config : AsyncLoggerConfig = AsyncLoggerConfig::new(
+  max_pending=64,
+  overflow=AsyncOverflowPolicy::DropOldest,
+)
+```
+
+In this example, async policy remains a typed object instead of immediately becoming JSON text or a logger instance.
+
+#### When Need To Inspect The Config Before Building
+
+When one layer should read or adjust async policy before logger construction:
+```moonbit
+let config = AsyncLoggerConfig::new(max_batch=4, linger_ms=20)
+println(stringify_async_logger_config(config, pretty=true))
+```
+
+In this example, the same public config object supports both inspection and later build steps.
+
+### Error Case
+
+e.g.:
+- `AsyncLoggerConfig` itself does not have a runtime failure mode.
+
+- Constructor normalization still applies when the value is created through `AsyncLoggerConfig::new(...)`, so very small or negative timing and batch inputs may be adjusted before later serialization or use.
+
+### Notes
+
+1. Use `AsyncLoggerConfig::new(...)` when you need a value of this type in code.
+
+2. Use `AsyncLoggerBuildConfig` when the async config should travel together with the base synchronous `LoggerConfig`.

docs/api/index.md

@@ -216,10 +216,12 @@ BitLogger API navigation.
 - [async-runtime-state.md](./async-runtime-state.md)
 - [async-runtime-state-to-json.md](./async-runtime-state-to-json.md)
 - [stringify-async-runtime-state.md](./stringify-async-runtime-state.md)
+- [async-logger-config-type.md](./async-logger-config-type.md)
 - [async-logger-config.md](./async-logger-config.md)
 - [parse-async-logger-config-text.md](./parse-async-logger-config-text.md)
 - [async-logger-config-to-json.md](./async-logger-config-to-json.md)
 - [stringify-async-logger-config.md](./stringify-async-logger-config.md)
+- [async-logger-build-config-type.md](./async-logger-build-config-type.md)
 - [parse-async-logger-build-config-text.md](./parse-async-logger-build-config-text.md)
 - [build-async-logger.md](./build-async-logger.md)
 - [build-async-text-logger.md](./build-async-text-logger.md)