From 13f0a24336403b0f2c4fe4b721989e4e16d9c181 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 20:39:24 +0800 Subject: [PATCH] :memo: document async library facade composition apis --- docs/api/index.md | 5 + docs/api/library-async-logger-bind.md | 82 +++++++++++++++++ docs/api/library-async-logger-child.md | 82 +++++++++++++++++ docs/api/library-async-logger-new.md | 91 +++++++++++++++++++ ...ibrary-async-logger-with-context-fields.md | 85 +++++++++++++++++ docs/api/library-async-logger-with-target.md | 84 +++++++++++++++++ 6 files changed, 429 insertions(+) create mode 100644 docs/api/library-async-logger-bind.md create mode 100644 docs/api/library-async-logger-child.md create mode 100644 docs/api/library-async-logger-new.md create mode 100644 docs/api/library-async-logger-with-context-fields.md create mode 100644 docs/api/library-async-logger-with-target.md diff --git a/docs/api/index.md b/docs/api/index.md index 3fb54c0..8cc808c 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -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) diff --git a/docs/api/library-async-logger-bind.md b/docs/api/library-async-logger-bind.md new file mode 100644 index 0000000..a25e6d0 --- /dev/null +++ b/docs/api/library-async-logger-bind.md @@ -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. diff --git a/docs/api/library-async-logger-child.md b/docs/api/library-async-logger-child.md new file mode 100644 index 0000000..f66be87 --- /dev/null +++ b/docs/api/library-async-logger-child.md @@ -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. diff --git a/docs/api/library-async-logger-new.md b/docs/api/library-async-logger-new.md new file mode 100644 index 0000000..0d238da --- /dev/null +++ b/docs/api/library-async-logger-new.md @@ -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]`. diff --git a/docs/api/library-async-logger-with-context-fields.md b/docs/api/library-async-logger-with-context-fields.md new file mode 100644 index 0000000..c004a0a --- /dev/null +++ b/docs/api/library-async-logger-with-context-fields.md @@ -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. diff --git a/docs/api/library-async-logger-with-target.md b/docs/api/library-async-logger-with-target.md new file mode 100644 index 0000000..4d50eaf --- /dev/null +++ b/docs/api/library-async-logger-with-target.md @@ -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.