@better-logger/core 0.7.0 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
-# @better-logger/core
+# better-logger
 
-> Track what your app *did*, not what it *said*.
+**Track what your app *did*, not what it *said*.**
 
 Execution flow debugger for modern apps. Zero deps. Works everywhere. <10KB.
 
@@ -8,11 +8,9 @@ Execution flow debugger for modern apps. Zero deps. Works everywhere. <10KB.
 npm install @better-logger/core
 ```
 
----
+## Stop debugging like this:
 
-Stop debugging like this:
-
-```ts
+```typescript
 console.log('start')
 console.log('user', user)
 console.log('after db')
@@ -21,273 +19,229 @@ console.log('done')
 
 And trying to mentally reconstruct what happened, in what order, and how long each thing took.
 
-Your app is not a list of messages.
+## Your app is not a list of messages. It's a flow.
 
-It's a **flow**.
+```typescript
+import { better } from '@better-logger/core'
 
----
+// Replace console.log — zero learning curve
+better.log('User created', { email: 'test@example.com' })
+better.log.warn('Slow query detected', { duration: 250 })
+better.log.error('Payment failed', error)
 
-## What you actually get
+// When you need structure
+const flow = better.flow('user-onboarding', { tags: ['auth'] })
+const step = flow.step('create-user', { email })
+await createUser(email)
+step.success()
+flow.success()
+```
+
+**What you get:**
 
 ```
 🚀 [flow:user-onboarding] [auth] (tid: a1b2c3d4)
   → create-user
     data: { email: "test@example.com" }
   ✓ create-user (45ms)
-  → generate-ai-profile
-  ✓ generate-ai-profile (410ms)
-  → save-db
-  ✗ save-db (error: timeout)
-🏁 [flow:user-onboarding] failed (532ms)
-```
-
-```ts
-import { createFlow } from '@better-logger/core'
-
-const flow = createFlow('user-onboarding', { tags: ['auth'] })
-
-const s1 = flow.step('create-user', { email })
-await createUser(email)
-s1.success()
-
-const s2 = flow.step('save-db')
-await saveUser()
-s2.fail(new Error('timeout'))
-
-flow.fail(new Error('save-db failed'))
+🏁 [flow:user-onboarding] success (45ms)
 ```
 
-You didn't write logs.
-
-You defined the **execution**.
-
-better-logger turns your code into a timeline of what actually happened.
-
-Output is deferred until `flow.success()` / `flow.fail()` — one atomic write, zero interleaving, even in async chaos.
-
----
-
 ## Why this exists
 
 Debugging today is broken:
 
-- `console.log` → flat noise, no structure
-- No automatic timing
-- No context propagation
-- Async flows become impossible to follow
+| Problem | better-logger solution |
+|---------|----------------------|
+| `console.log` → flat noise, no structure | Hierarchical flows with automatic timing |
+| No automatic timing | Every step and flow tracks duration |
+| No context propagation | `flow.setContext()` shares metadata across all steps |
+| Async flows become impossible to follow | Deferred atomic rendering — one output per flow |
+| Need to learn new API | `better.log()` is `console.log()` — just add `.log` |
 
-You don't debug code.
+## Quick Start
 
-You debug **guesses about what happened**.
+### 1. Drop-in replacement
 
-better-logger removes the guesswork. Instead of scattering `console.log` across your code and reconstructing timelines mentally, you define the flow upfront and get a structured narrative back — with timing, context, and clear failure markers.
+Replace `console.log` with `better.log`:
 
----
+```typescript
+// Before
+console.log('Server started on port 3000')
+console.error('Database connection failed', error)
 
-## What changes
+// After
+import { better } from '@better-logger/core'
 
-Instead of guessing:
-- "did this run?"
-- "what ran first?"
-- "where did it fail?"
-- "why is it slow?"
-
-You **see**:
-
-- 🧠 A full execution narrative
-- ⏱ Exact timing for every step
-- 🌳 Nested flows (real hierarchy, not flat logs)
-- 🧾 Data at the moment it mattered
-- 🧵 Shared context across the entire flow
-- 🏷 Tags to group and filter
-- 🧱 Guaranteed consistency — no race-condition bugs
-- 🔒 Immutable render snapshots — output can't be corrupted
-
-This replaces `console.log` for anything non-trivial.
-
----
-
-## Why not just use something else?
-
-| Tool | Reality |
-|------|--------|
-| `console.log` | You reconstruct flows manually like it's 2005 |
-| `pino` / `winston` | Built for shipping logs, not understanding execution |
-| `debug` | Namespaces ≠ structure |
-| OpenTelemetry | Powerful, but heavy and not built for everyday debugging |
-
-**@better-logger/core** sits in the missing gap:
+better.log('Server started on port 3000')
+better.log.error('Database connection failed', error)
+```
 
-→ instant, local, zero-config execution tracing
+That's it. You now get structured, timed output for free.
 
----
+### 2. When you need structure
 
-## Usage
+For important operations, use explicit flows:
 
-```ts
-const flow = createFlow('request', { tags: ['api'] })
+```typescript
+const flow = better.flow('process-payment', { tags: ['billing'] })
+flow.setContext({ orderId: 'ord-123', userId: 'user-456' })
 
-const step = flow.step('db')
-await db.query()
-step.success()
+const step = flow.step('charge-card', { amount: 99.99 })
+const result = await paymentGateway.charge({ amount: 99.99 })
+step.success(result)
 
 flow.success()
+better.log(`Payment processed: ${result.transactionId}`)
 ```
 
-That's it.
-
----
-
-## How it works
-
-```mermaid
-graph TD
-  Start[createFlow] --> Step[step]
-  Step --> Complete[success / fail]
-  Complete --> FlowEnd[flow.success / flow.fail]
-  FlowEnd --> Render[Atomic Render]
-```
-
----
-
-## When should you use this
-
-Use it when:
-
-- your flow has more than 2 steps
-- async logic gets confusing
-- debugging requires more than one `console.log`
-- timing matters
-- you need to know "what ran" and "what didn't"
+### 3. Async made easy
 
-If a single `console.log` feels enough, you don't need this.
+```typescript
+const flow = better.flow('data-export')
 
-If it doesn't… this replaces it.
-
----
-
-## Advanced
-
-### Child Flows
-
-```ts
-const flow = createFlow('request')
+const data = await flow.run('fetch-data', async () => {
+  return await db.users.find({})
+})
 
-const ai = flow.child('ai-call')
-const s = ai.step('generate')
-await generate()
-s.success()
-ai.success()
+const file = await flow.run('generate-file', async () => {
+  return await exportToCSV(data)
+})
 
 flow.success()
 ```
 
-```
-🚀 [flow:request] (tid: a1b2c3d4)
-  └─ 🚀 [flow:ai-call] (tid: x9y8z7w6)
-       → generate
-       ✓ generate (210ms)
-     🏁 [flow:ai-call] success (215ms)
-🏁 [flow:request] success (340ms)
-```
-
-### Context Propagation
+## API Reference
 
-```ts
-flow.setContext({ userId: 'abc', requestId: 'xyz' })
-// Available across all steps and child flows
-```
-
-### Silent Mode
-
-```ts
-const flow = createFlow('task', { enabled: false })
-// Near-zero overhead. All operations are no-ops.
-```
-
-### Max Steps Guard
+### `better.log()` — The simple way
 
-```ts
-const flow = createFlow('batch', { maxSteps: 1000 })
-// Prevents memory blowups from runaway loops
+```typescript
+better.log('message')                           // Simple message
+better.log('message', data)                     // Message with data
+better.log.info('message', data)                // Info (same as log)
+better.log.warn('message', data)                // Warning (auto-tags flow)
+better.log.error('message', error)              // Error (fails flow)
 ```
 
-### Subscribe (DevTools / Testing)
+### `better.flow()` — The structured way
 
-```ts
-import { subscribe, toJSON } from '@better-logger/core'
-
-subscribe((trace) => {
-  // Frozen snapshot of every completed flow
-  console.log(toJSON(trace))
+```typescript
+const flow = better.flow('name', {
+  tags: ['tag1', 'tag2'],           // Indexing labels
+  maxSteps: 100,                     // Safety limit
+  initialContext: { key: 'value' }   // Shared metadata
 })
-```
 
-### JSON Output
+flow.setContext({ userId: 'abc' })   // Add context
+flow.getContext()                    // Get context copy
 
-```ts
-import { toJSON } from '@better-logger/core'
+flow.step('step-name', data)         // Create step
+  .success()                         // Mark success
+  .fail(error)                       // Mark failure
 
-const json = toJSON(flow)
-// { version: 1, flow: { id, name, state, status, tags, steps, context, ... } }
+flow.success()                       // Complete flow
+flow.fail(error)                     // Fail flow
 ```
 
-Portable, structured trace for tooling, testing, and future integrations.
+### `better.flow.run()` — Async helper
 
----
-
-## Features
-
-### Core
-`createFlow` · `step` · `success/fail` · `child` · `toJSON`
-
-### Advanced
-Context propagation · Tags · Inline data snapshots · Subscribe event tap · Deferred atomic rendering · Immutable snapshots
-
-### Safety
-Guarded finalization · `maxSteps` overflow protection · Lifecycle states (`running` → `completed`) · Safe data serializer (circular refs, deep nesting) · NoOp singletons (zero-allocation silent mode)
-
----
-
-## What's not included
-
-- ❌ Log levels (debug, info, warn)
-- ❌ Transports (file, HTTP, Elasticsearch)
-- ❌ SaaS dashboards
-- ❌ Auto-instrumentation
-
-This is a developer debugging tool, not observability infrastructure.
-
----
-
-## Roadmap
-
-| Version | Focus |
-|---------|-------|
-| **V1** | Core flow debugger — this release |
-| **V2** | Custom renderers, `flow.run()` async helper, flow sampling |
-| **V3** | Browser DevTools timeline panel |
-| **V4+** | Python / Go / Rust ports, shared tracing schema |
-
----
-
-## Organization
+```typescript
+const result = await flow.run('async-step', async () => {
+  return await fetchData()  // Auto-completes step on success/fail
+})
+```
 
-Published under the **@better-logger** org, owned by [0xmilord](https://github.com/0xmilord).
+### Configuration
 
-```bash
-npm install @better-logger/core
+```typescript
+better.log.setIdleTimeout(200)           // Auto-complete timeout (ms)
+better.log.setFlowName('my-app')         // Default flow name
+better.log.setDefaultTags(['app', 'v3']) // Tags on all flows
+better.log.flush()                       // Force complete current flow
+better.setEnabled(false)                 // Disable all logging
+better.isEnabled()                       // Check if enabled
 ```
 
-All packages in this org share the same execution tracing schema.
+## Real-World Examples
 
----
+We've included 10 comprehensive examples showing better-logger in real applications:
 
-## Test Coverage
+| Example | What it shows |
+|---------|--------------|
+| `01-express-rest-api.js` | Express middleware, CRUD endpoints, error handling |
+| `02-background-job-processor.js` | Job queue, retry logic, nested flows |
+| `03-authentication-flow.js` | Login, token refresh, password reset, security logging |
+| `04-ecommerce-order-processing.js` | Multi-step checkout, inventory, payment, shipping |
+| `05-cli-tool.js` | CLI commands, progress tracking, file processing |
+| `06-api-integration-client.js` | HTTP client, retry logic, rate limiting, batch ops |
+| `07-microservice-distributed-tracing.js` | Trace context, downstream calls, health checks |
+| `08-testing-utilities.js` | Test runner, assertions, performance testing |
+| `09-data-pipeline.js` | ETL pipelines, transforms, validation, aggregation |
+| `10-full-application.js` | Complete Node.js app with all patterns combined |
 
-**100%** across all metrics — statements, branches, functions, lines.
+## Features
 
-[View detailed coverage report](./COVERAGE.md) | [Testing Strategy](./docs/TESTING-STRATEGY.md)
+### Zero Friction
+- `better.log()` is a drop-in for `console.log()`
+- No configuration needed — import and use immediately
+- Auto-flow management groups rapid calls together
+- Idle timeout auto-completes flows (100ms default)
+
+### Structured Output
+- Hierarchical flows with visual nesting
+- Automatic timing for every step and flow
+- Context propagation across all steps
+- Tags for filtering and grouping
+- JSON export for downstream systems
+
+### Production-Grade
+- Zero dependencies — nothing to break
+- <10KB bundle — won't bloat your app
+- Works in Node.js 18+, browsers, Edge runtimes
+- Full TypeScript support
+- 100% test coverage
+
+### Forgiving
+- Call methods after completion — silent no-ops
+- Pass any data type — handled gracefully
+- Circular references — won't crash
+- Concurrent flows — no interleaving
+- Error anywhere — won't break your app
+
+## Migration from console.log
+
+```typescript
+// Before
+console.log('User created:', user)
+console.warn('Slow query', { duration: 250 })
+console.error('Payment failed:', error)
+
+// After (literally just add "better.")
+import { better } from '@better-logger/core'
+
+better.log('User created:', user)
+better.log.warn('Slow query', { duration: 250 })
+better.log.error('Payment failed:', error)
+```
+
+**Migration effort:** 10 minutes to replace all console.log. Hours to days to adopt flows strategically where they add value.
+
+## What's NOT included
+
+- ❌ Log levels (debug, info, warn, error) — execution tracing ≠ log routing
+- ❌ Transport layers (file, HTTP, Elasticsearch) — zero-config philosophy
+- ❌ SaaS dashboards — we emit data, we don't host it
+- ❌ Auto-instrumentation — devs control what they trace
+
+## Package Health
+
+| Metric | Value |
+|--------|-------|
+| Bundle size | <10KB minified |
+| Dependencies | 0 |
+| Test coverage | 100% |
+| TypeScript | Full support |
+| Runtimes | Node 18+, Browser, Edge |
 
 ## License
 

package/package.json

@@ -52,5 +52,5 @@
     "@typescript-eslint/eslint-plugin": "8.58.0",
     "@types/node": "20.11.0"
   },
-  "version": "0.7.0"
+  "version": "0.8.0"
 }