naloveyuki/BitLogger
1
0
Fork 0
mirror of https://github.com/Nanaloveyuki/BitLogger.git synced 2026-07-24 00:42:18 +00:00
Code Issues Packages Projects Releases Wiki Activity

📝 document async library facade composition apis

Browse Source
This commit is contained in:
Nanaloveyuki
2026-06-13 20:39:24 +08:00
parent 4e32a7350a
commit 13f0a24336
6 changed files with 429 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/index.md
+5
View File
@@ -219,6 +219,11 @@ BitLogger API navigation.
- [default-library-logger.md](./default-library-logger.md)
- [async-logger-to-library-async-logger.md](./async-logger-to-library-async-logger.md)
- [library-async-logger-to-async-logger.md](./library-async-logger-to-async-logger.md)
- [library-async-logger-new.md](./library-async-logger-new.md)
- [library-async-logger-with-target.md](./library-async-logger-with-target.md)
- [library-async-logger-child.md](./library-async-logger-child.md)
- [library-async-logger-with-context-fields.md](./library-async-logger-with-context-fields.md)
- [library-async-logger-bind.md](./library-async-logger-bind.md)
- [build-application-async-logger.md](./build-application-async-logger.md)
- [build-application-text-async-logger.md](./build-application-text-async-logger.md)
- [parse-and-build-application-async-logger.md](./parse-and-build-application-async-logger.md)
docs/api/library-async-logger-bind.md
+82
View File
@@ -0,0 +1,82 @@
---
name: library-async-logger-bind
group: api
category: facade
update-time: 20260613
description: Attach reusable structured fields to a LibraryAsyncLogger facade through the bind alias.
key-word:
- async
- library
- bind
- public
---
## Library-async-logger-bind
Attach shared structured fields to a `LibraryAsyncLogger[S]` through the `bind(...)` alias. This is behaviorally identical to `with_context_fields(...)` and exists as a shorter name for common library-facing async context binding.
### Interface
```moonbit
pub fn[S] LibraryAsyncLogger::bind(
self : LibraryAsyncLogger[S],
fields : Array[@bitlogger.Field],
) -> LibraryAsyncLogger[S] {
```
#### input
- `self : LibraryAsyncLogger[S]` - Base facade that should gain shared fields.
- `fields : Array[@bitlogger.Field]` - Structured fields attached to every emitted record.
#### output
- `LibraryAsyncLogger[S]` - New library-facing async wrapper that carries the shared field set.
### Explanation
Detailed rules explaining key parameters and behaviors
- `bind(...)` delegates directly to `with_context_fields(...)`.
- The original facade value is not mutated; a wrapped facade is returned.
- Shared fields are applied to every later log call emitted through the returned facade.
- This alias is useful when you prefer shorter chaining syntax in library async code.
### How to Use
Here are some specific examples provided.
#### When Bind Shared Package Context For Async Writes
When a library async logger should carry stable metadata through a flow:
```moonbit
let request_logger = LibraryAsyncLogger::new(@bitlogger.console_sink())
.with_target("sdk")
.bind([@bitlogger.field("request_id", "req-42")])
```
In this example, subsequent async writes automatically include `request_id`.
#### When Prefer Shorter Async Chaining Syntax
When a context-bound child async facade should stay readable:
```moonbit
let worker = LibraryAsyncLogger::new(@bitlogger.console_sink(), target="app")
.child("worker")
.bind([@bitlogger.field("component", "worker")])
```
In this example, `bind(...)` communicates intent without changing underlying behavior.
### Error Case
e.g.:
- If `fields` is empty, the returned facade remains valid and simply adds no extra metadata.
- If duplicate field keys are bound, all copies are preserved for downstream formatting or inspection.
### Notes
1. Use `bind(...)` and `with_context_fields(...)` interchangeably; choose the one that reads better in context.
2. This alias exists for ergonomics, not for different semantics.
docs/api/library-async-logger-child.md
+82
View File
@@ -0,0 +1,82 @@
---
name: library-async-logger-child
group: api
category: facade
update-time: 20260613
description: Derive a child LibraryAsyncLogger facade by composing the current target with a child segment.
key-word:
- async
- library
- child
- public
---
## Library-async-logger-child
Create a child `LibraryAsyncLogger[S]` by composing the current target with another target segment. This is the library-facing hierarchical naming helper for async targets such as `sdk.cache` or `plugin.worker.io`.
### Interface
```moonbit
pub fn[S] LibraryAsyncLogger::child(
self : LibraryAsyncLogger[S],
target : String,
) -> LibraryAsyncLogger[S] {
```
#### input
- `self : LibraryAsyncLogger[S]` - Parent facade whose target should be extended.
- `target : String` - Child target segment or suffix.
#### output
- `LibraryAsyncLogger[S]` - New library-facing async facade whose target is the composed child path.
### Explanation
Detailed rules explaining key parameters and behaviors
- This API delegates to the wrapped async logger's `child(...)` behavior and then re-wraps the result.
- If the parent target is empty, the child target becomes the full target.
- If the child target is empty, the parent target is preserved.
- If both are non-empty, they are joined with `.`.
### How to Use
Here are some specific examples provided.
#### When Need Hierarchical Async Naming In A Library API
When a package wants stable namespace composition without exposing `AsyncLogger[S]`:
```moonbit
let worker = LibraryAsyncLogger::new(@bitlogger.console_sink())
.with_target("plugin")
.child("worker")
```
In this example, the final target becomes `plugin.worker`.
#### When Build Scoped Async Facades Step By Step
When deeper target composition should stay readable:
```moonbit
let client = LibraryAsyncLogger::new(@bitlogger.console_sink(), target="sdk")
.child("http")
.child("client")
```
In this example, the final facade emits under `sdk.http.client`.
### Error Case
e.g.:
- If `target` is empty, the returned facade keeps the original parent target.
- If callers need complete replacement instead of composition, `with_target(...)` should be used instead.
### Notes
1. This is the preferred library-facing API for hierarchical async target naming.
2. Composition changes the target only and does not rebuild the queue or sink.
docs/api/library-async-logger-new.md
+91
View File
@@ -0,0 +1,91 @@
---
name: library-async-logger-new
group: api
category: facade
update-time: 20260613
description: Create a narrower library-facing async logger facade from any sink implementation.
key-word:
- async
- library
- facade
- public
---
## Library-async-logger-new
Create a `LibraryAsyncLogger[S]` from any sink implementation. This is the library-facing async constructor when you want queue-backed async logging behavior without exposing the full `AsyncLogger[S]` surface.
### Interface
```moonbit
pub fn[S] LibraryAsyncLogger::new(
sink : S,
config~ : AsyncLoggerConfig = AsyncLoggerConfig::new(),
min_level~ : @bitlogger.Level = @bitlogger.Level::Info,
target~ : String = "",
flush~ : (S) -> Int raise = fn(_) { 0 },
) -> LibraryAsyncLogger[S] {
```
#### input
- `sink : S` - Any sink value implementing `@bitlogger.Sink`, such as `@bitlogger.console_sink()` or a composed sink.
- `config : AsyncLoggerConfig` - Queue size, overflow behavior, batching, linger, and flush policy.
- `min_level : Level` - Minimum enabled level. Messages below this threshold are ignored before enqueue.
- `target : String` - Default target attached to emitted records unless later overridden.
- `flush : (S) -> Int raise` - Flush callback used when async batch or shutdown policy needs explicit flushing.
#### output
- `LibraryAsyncLogger[S]` - Narrow library-facing wrapper over a newly created async logger.
### Explanation
Detailed rules explaining key parameters and behaviors
- This API builds a regular `async_logger(...)` internally and then wraps it as `LibraryAsyncLogger`.
- The returned facade intentionally exposes a smaller method set than the full `AsyncLogger[S]` type.
- Queue settings, flush policy, and runtime state are preserved inside the wrapped async logger.
- Call `to_async_logger()` if later code must recover the full async logger surface.
### How to Use
Here are some specific examples provided.
#### When Need A Narrower Library-facing Async Constructor
When a package should create an async logger without exposing the full async logger API:
```moonbit
let logger = LibraryAsyncLogger::new(
@bitlogger.console_sink(),
config=AsyncLoggerConfig::new(max_pending=32),
target="plugin.async",
)
```
In this example, the package creates a normal async logging pipeline but publishes only the smaller facade type.
#### When Need Explicit Flush Behavior In A Library Boundary
When the sink requires a flush callback for batch or shutdown policy:
```moonbit
let logger = LibraryAsyncLogger::new(
@bitlogger.console_sink(),
flush=fn(sink) { 0 },
)
```
In this example, the facade still keeps the queue-backed async behavior while hiding the full async logger type.
### Error Case
e.g.:
- If `target` is empty, the returned logger remains valid and later records simply use an empty default target.
- If later code needs methods outside the facade, it must unwrap with `to_async_logger()`.
### Notes
1. This is the direct constructor counterpart to `async_logger(...)` for library-oriented async APIs.
2. Prefer this when public package boundaries should stay narrower than `AsyncLogger[S]`.
docs/api/library-async-logger-with-context-fields.md
+85
View File
@@ -0,0 +1,85 @@
---
name: library-async-logger-with-context-fields
group: api
category: facade
update-time: 20260613
description: Attach reusable structured fields to a LibraryAsyncLogger facade.
key-word:
- async
- library
- fields
- public
---
## Library-async-logger-with-context-fields
Bind shared structured fields to a `LibraryAsyncLogger[S]`. This is the library-facing API for attaching stable metadata such as component name, plugin id, or request scope without repeating those fields on every async log call.
### Interface
```moonbit
pub fn[S] LibraryAsyncLogger::with_context_fields(
self : LibraryAsyncLogger[S],
fields : Array[@bitlogger.Field],
) -> LibraryAsyncLogger[S] {
```
#### input
- `self : LibraryAsyncLogger[S]` - Base facade that should gain shared fields.
- `fields : Array[@bitlogger.Field]` - Structured fields that will be prepended to each emitted record.
#### output
- `LibraryAsyncLogger[S]` - New library-facing async facade carrying the shared field set.
### Explanation
Detailed rules explaining key parameters and behaviors
- This API delegates to the wrapped async logger's `with_context_fields(...)` behavior and then narrows the result back to `LibraryAsyncLogger`.
- Context fields are merged during `log(...)` before enqueue.
- Unlike synchronous `LibraryLogger::with_context_fields(...)`, this async variant preserves the visible `LibraryAsyncLogger[S]` type instead of changing the visible sink type.
- `bind(...)` is an ergonomic alias for this same behavior.
### How to Use
Here are some specific examples provided.
#### When Need Stable Library Metadata On Every Async Record
When a package should attach fixed metadata to all queued records:
```moonbit
let logger = LibraryAsyncLogger::new(@bitlogger.console_sink())
.with_target("plugin")
.with_context_fields([
@bitlogger.field("plugin", "alpha"),
@bitlogger.field("region", "cn"),
])
```
In this example, both fields are automatically attached before every record enters the queue.
#### When Combine Async Target Scoping And Shared Fields
When a subsystem facade should carry both a target and stable context:
```moonbit
let worker = LibraryAsyncLogger::new(@bitlogger.console_sink(), target="sdk")
.child("worker")
.with_context_fields([@bitlogger.field("component", "worker")])
```
In this example, target composition and field binding stay separate but compose cleanly.
### Error Case
e.g.:
- If `fields` is empty, the returned facade remains valid and simply adds no extra metadata.
- If duplicate field keys are provided, all fields are still emitted for downstream formatting or inspection.
### Notes
1. Use this for stable shared metadata, not highly dynamic event-specific values.
2. The narrower `LibraryAsyncLogger` surface is preserved after field binding.
docs/api/library-async-logger-with-target.md
+84
View File
@@ -0,0 +1,84 @@
---
name: library-async-logger-with-target
group: api
category: facade
update-time: 20260613
description: Replace the default target carried by a LibraryAsyncLogger facade.
key-word:
- async
- library
- facade
- public
---
## Library-async-logger-with-target
Replace the default target on a `LibraryAsyncLogger[S]`. This is the library-facing counterpart to `AsyncLogger::with_target(...)` when package code wants to retarget an async logger without exposing the full async logger API.
### Interface
```moonbit
pub fn[S] LibraryAsyncLogger::with_target(
self : LibraryAsyncLogger[S],
target : String,
) -> LibraryAsyncLogger[S] {
```
#### input
- `self : LibraryAsyncLogger[S]` - Base facade whose default target should be replaced.
- `target : String` - New default target namespace.
#### output
- `LibraryAsyncLogger[S]` - New library-facing async facade carrying the updated target.
### Explanation
Detailed rules explaining key parameters and behaviors
- This API delegates to the wrapped async logger's `with_target(...)` behavior and then re-wraps the result.
- The returned value keeps the same queue state, sink type, and async config.
- This replaces the default target instead of composing it.
- The original facade value is not mutated.
### How to Use
Here are some specific examples provided.
#### When Need A New Fixed Async Namespace Inside Library Code
When one facade should emit under a different async target namespace:
```moonbit
let logger = LibraryAsyncLogger::new(@bitlogger.console_sink())
.with_target("sdk.http")
```
In this example, later async writes inherit `sdk.http` unless a call overrides the target directly.
#### When Reuse One Async Setup Across Library Subsystems
When multiple library-facing async loggers should share one queue policy:
```moonbit
let base = LibraryAsyncLogger::new(
@bitlogger.console_sink(),
config=AsyncLoggerConfig::new(max_pending=64),
)
let cache = base.with_target("cache")
let io = base.with_target("io")
```
In this example, one base facade becomes several target-specific async facades.
### Error Case
e.g.:
- If `target` is empty, the returned logger remains valid and later records simply use an empty default target.
- If callers need hierarchical target composition rather than replacement, `child(...)` is the better API.
### Notes
1. Use this API for replacement, not target-path composition.
2. It keeps the narrower `LibraryAsyncLogger` boundary intact.