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 sync library facade composition apis

Browse Source
This commit is contained in:
Nanaloveyuki
2026-06-13 20:36:45 +08:00
parent 76dbc421eb
commit 4e32a7350a
6 changed files with 407 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/index.md
+5
View File
@@ -205,8 +205,13 @@ BitLogger API navigation.
## Application and library facades
- [library-logger-new.md](./library-logger-new.md)
- [logger-to-library-logger.md](./logger-to-library-logger.md)
- [library-logger-to-logger.md](./library-logger-to-logger.md)
- [library-logger-with-target.md](./library-logger-with-target.md)
- [library-logger-child.md](./library-logger-child.md)
- [library-logger-with-context-fields.md](./library-logger-with-context-fields.md)
- [library-logger-bind.md](./library-logger-bind.md)
- [build-application-logger.md](./build-application-logger.md)
- [parse-and-build-application-logger.md](./parse-and-build-application-logger.md)
- [build-library-logger.md](./build-library-logger.md)
docs/api/library-logger-bind.md
+82
View File
@@ -0,0 +1,82 @@
---
name: library-logger-bind
group: api
category: facade
update-time: 20260613
description: Attach reusable structured fields to a LibraryLogger facade through the bind alias.
key-word:
- library
- facade
- bind
- public
---
## Library-logger-bind
Attach shared structured fields to a `LibraryLogger[S]` through the `bind(...)` alias. This is behaviorally identical to `with_context_fields(...)` and exists as a shorter name for common library-facing context binding.
### Interface
```moonbit
pub fn[S] LibraryLogger::bind(
self : LibraryLogger[S],
fields : Array[Field],
) -> LibraryLogger[ContextSink[S]] {
```
#### input
- `self : LibraryLogger[S]` - Base facade that should gain shared fields.
- `fields : Array[Field]` - Structured fields attached to every emitted record.
#### output
- `LibraryLogger[ContextSink[S]]` - New library-facing wrapper that prepends shared fields at write time.
### 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 code.
### How to Use
Here are some specific examples provided.
#### When Bind Shared Package Context
When a library logger should carry stable metadata through a flow:
```moonbit
let request_logger = default_library_logger()
.with_target("sdk")
.bind([field("request_id", "req-42")])
```
In this example, subsequent writes automatically include `request_id`.
#### When Prefer Shorter Chaining Syntax
When a context-bound child facade should stay readable:
```moonbit
let worker = LibraryLogger::new(console_sink(), target="app")
.child("worker")
.bind([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-logger-child.md
+79
View File
@@ -0,0 +1,79 @@
---
name: library-logger-child
group: api
category: facade
update-time: 20260613
description: Derive a child LibraryLogger facade by composing the current target with a child segment.
key-word:
- library
- facade
- child
- public
---
## Library-logger-child
Create a child `LibraryLogger[S]` by composing the current target with another target segment. This is the library-facing hierarchical naming helper for targets such as `sdk.cache` or `plugin.worker.io`.
### Interface
```moonbit
pub fn[S] LibraryLogger::child(self : LibraryLogger[S], target : String) -> LibraryLogger[S] {
```
#### input
- `self : LibraryLogger[S]` - Parent facade whose target should be extended.
- `target : String` - Child target segment or suffix.
#### output
- `LibraryLogger[S]` - New library-facing facade whose target is the composed child path.
### Explanation
Detailed rules explaining key parameters and behaviors
- This API delegates to the wrapped 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 Target Naming In A Library API
When a package wants stable namespace composition without exposing `Logger[S]`:
```moonbit
let worker = default_library_logger()
.with_target("plugin")
.child("worker")
```
In this example, the final target becomes `plugin.worker`.
#### When Build Scoped Facades Step By Step
When deeper target composition should stay readable:
```moonbit
let client = LibraryLogger::new(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 target naming.
2. Composition uses `.` as the separator between parent and child segments.
docs/api/library-logger-new.md
+81
View File
@@ -0,0 +1,81 @@
---
name: library-logger-new
group: api
category: facade
update-time: 20260613
description: Create a narrower sync library logger facade from any sink implementation.
key-word:
- library
- facade
- logger
- public
---
## Library-logger-new
Create a `LibraryLogger[S]` from any sink implementation. This is the library-facing sync constructor when you want standard logging behavior but do not want to expose the full `Logger[S]` surface.
### Interface
```moonbit
pub fn[S] LibraryLogger::new(
sink : S,
min_level~ : Level = Level::Info,
target~ : String = "",
) -> LibraryLogger[S] {
```
#### input
- `sink : S` - Any sink value implementing `Sink`, such as `console_sink()` or a composed sink.
- `min_level : Level` - Minimum enabled level. Messages below this threshold are ignored.
- `target : String` - Default target attached to emitted records unless later overridden.
#### output
- `LibraryLogger[S]` - Narrow library-facing wrapper over a newly created sync logger.
### Explanation
Detailed rules explaining key parameters and behaviors
- This API builds a regular `Logger::new(...)` internally and then wraps it as `LibraryLogger`.
- The returned facade intentionally exposes a smaller method set than the full `Logger[S]` type.
- The original sink type is still preserved in `LibraryLogger[S]`.
- Call `to_logger()` if later code must recover the full sync logger surface.
### How to Use
Here are some specific examples provided.
#### When Need A Narrower Library-facing Constructor
When a package should create a logger without exposing the full logger API:
```moonbit
let logger = LibraryLogger::new(console_sink(), min_level=Level::Info, target="plugin")
logger.info("loaded")
```
In this example, the package creates a normal sync logger pipeline but publishes only the smaller facade type.
#### When Accept A Generic Sink But Keep Library Boundaries Small
When a library API wants typed sinks without exposing extra composition helpers:
```moonbit
let logger = LibraryLogger::new(text_console_sink(text_formatter()), target="worker")
```
In this example, sink typing remains explicit while the consumer only sees the library facade.
### 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_logger()`.
### Notes
1. This is the direct constructor counterpart to `Logger::new(...)` for library-oriented APIs.
2. Prefer this when public package boundaries should stay narrower than `Logger[S]`.
docs/api/library-logger-with-context-fields.md
+82
View File
@@ -0,0 +1,82 @@
---
name: library-logger-with-context-fields
group: api
category: facade
update-time: 20260613
description: Attach reusable structured fields to a LibraryLogger facade.
key-word:
- library
- facade
- fields
- public
---
## Library-logger-with-context-fields
Bind shared structured fields to a `LibraryLogger[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 log call.
### Interface
```moonbit
pub fn[S] LibraryLogger::with_context_fields(
self : LibraryLogger[S],
fields : Array[Field],
) -> LibraryLogger[ContextSink[S]] {
```
#### input
- `self : LibraryLogger[S]` - Base facade that should gain shared fields.
- `fields : Array[Field]` - Structured fields that will be prepended to each emitted record.
#### output
- `LibraryLogger[ContextSink[S]]` - New library-facing facade wrapping the original sink with context-field merging behavior.
### Explanation
Detailed rules explaining key parameters and behaviors
- This API delegates to the wrapped logger's `with_context_fields(...)` behavior and then narrows the result back to `LibraryLogger`.
- Context fields are merged at write time rather than by mutating previously created records.
- The returned facade carries `ContextSink[S]` because the sink pipeline has been extended.
- `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 Record
When a package should attach fixed metadata to all emitted records:
```moonbit
let logger = default_library_logger()
.with_target("plugin")
.with_context_fields([field("plugin", "alpha"), field("region", "cn")])
```
In this example, both fields are automatically included on every later write.
#### When Combine Target Scoping And Shared Fields
When a subsystem facade should carry both a target and stable context:
```moonbit
let worker = LibraryLogger::new(console_sink(), target="sdk")
.child("worker")
.with_context_fields([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 `LibraryLogger` surface is preserved after context binding.
docs/api/library-logger-with-target.md
+78
View File
@@ -0,0 +1,78 @@
---
name: library-logger-with-target
group: api
category: facade
update-time: 20260613
description: Replace the default target carried by a LibraryLogger facade.
key-word:
- library
- facade
- target
- public
---
## Library-logger-with-target
Replace the default target on a `LibraryLogger[S]`. This is the library-facing counterpart to `Logger::with_target(...)` when a package wants to retarget a logger without exposing the full sync logger API.
### Interface
```moonbit
pub fn[S] LibraryLogger::with_target(self : LibraryLogger[S], target : String) -> LibraryLogger[S] {
```
#### input
- `self : LibraryLogger[S]` - Base facade whose default target should be replaced.
- `target : String` - New default target namespace.
#### output
- `LibraryLogger[S]` - New library-facing logger facade carrying the updated target.
### Explanation
Detailed rules explaining key parameters and behaviors
- This API delegates to the wrapped logger's `with_target(...)` behavior and then re-wraps the result.
- The returned value keeps the same sink type and minimum level settings.
- 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 Namespace Inside Library Code
When one facade should emit under a different target namespace:
```moonbit
let logger = default_library_logger().with_target("sdk.http")
logger.info("request prepared")
```
In this example, later writes inherit `sdk.http` unless a call overrides the target directly.
#### When Reuse The Same Sink Across Several Library Subsystems
When multiple library-facing loggers should share one base pipeline:
```moonbit
let base = LibraryLogger::new(console_sink())
let cache = base.with_target("cache")
let io = base.with_target("io")
```
In this example, one base facade becomes several target-specific 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 `LibraryLogger` boundary intact.