@better-logger/core 0.6.0 → 0.8.0

package/README.md

@@ -1,294 +1,248 @@
-# @better-logger/core
-
-> Track what your app *did*, not what it *said*.
-
-Execution flow debugger for modern apps. Zero deps. Works everywhere. <10KB.
-
-```bash
-npm install @better-logger/core
-```
-
----
-
-Stop debugging like this:
-
-```ts
-console.log('start')
-console.log('user', user)
-console.log('after db')
-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.
-
-It's a **flow**.
-
----
-
-## What you actually 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'))
-```
-
-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
-
-You don't debug code.
-
-You debug **guesses about what happened**.
-
-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.
-
----
-
-## What changes
-
-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:
-
-→ instant, local, zero-config execution tracing
-
----
-
-## Usage
-
-```ts
-const flow = createFlow('request', { tags: ['api'] })
-
-const step = flow.step('db')
-await db.query()
-step.success()
-
-flow.success()
-```
-
-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"
-
-If a single `console.log` feels enough, you don't need this.
-
-If it doesn't… this replaces it.
-
----
-
-## Advanced
-
-### Child Flows
-
-```ts
-const flow = createFlow('request')
-
-const ai = flow.child('ai-call')
-const s = ai.step('generate')
-await generate()
-s.success()
-ai.success()
-
-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
-
-```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
-
-```ts
-const flow = createFlow('batch', { maxSteps: 1000 })
-// Prevents memory blowups from runaway loops
-```
-
-### Subscribe (DevTools / Testing)
-
-```ts
-import { subscribe, toJSON } from '@better-logger/core'
-
-subscribe((trace) => {
-  // Frozen snapshot of every completed flow
-  console.log(toJSON(trace))
-})
-```
-
-### JSON Output
-
-```ts
-import { toJSON } from '@better-logger/core'
-
-const json = toJSON(flow)
-// { version: 1, flow: { id, name, state, status, tags, steps, context, ... } }
-```
-
-Portable, structured trace for tooling, testing, and future integrations.
-
----
-
-## 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
-
-Published under the **@better-logger** org, owned by [0xmilord](https://github.com/0xmilord).
-
-```bash
-npm install @better-logger/core
-```
-
-All packages in this org share the same execution tracing schema.
-
----
-
-## Test Coverage
-
-**100%** across all metrics — statements, branches, functions, lines.
-
-[View detailed coverage report](./COVERAGE.md) | [Testing Strategy](./docs/TESTING-STRATEGY.md)
-
-## License
-
-MIT
+# better-logger
+
+**Track what your app *did*, not what it *said*.**
+
+Execution flow debugger for modern apps. Zero deps. Works everywhere. <10KB.
+
+```bash
+npm install @better-logger/core
+```
+
+## Stop debugging like this:
+
+```typescript
+console.log('start')
+console.log('user', user)
+console.log('after db')
+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. 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)
+
+// 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)
+🏁 [flow:user-onboarding] success (45ms)
+```
+
+## Why this exists
+
+Debugging today is broken:
+
+| 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` |
+
+## Quick Start
+
+### 1. Drop-in replacement
+
+Replace `console.log` with `better.log`:
+
+```typescript
+// Before
+console.log('Server started on port 3000')
+console.error('Database connection failed', error)
+
+// After
+import { better } from '@better-logger/core'
+
+better.log('Server started on port 3000')
+better.log.error('Database connection failed', error)
+```
+
+That's it. You now get structured, timed output for free.
+
+### 2. When you need structure
+
+For important operations, use explicit flows:
+
+```typescript
+const flow = better.flow('process-payment', { tags: ['billing'] })
+flow.setContext({ orderId: 'ord-123', userId: 'user-456' })
+
+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}`)
+```
+
+### 3. Async made easy
+
+```typescript
+const flow = better.flow('data-export')
+
+const data = await flow.run('fetch-data', async () => {
+  return await db.users.find({})
+})
+
+const file = await flow.run('generate-file', async () => {
+  return await exportToCSV(data)
+})
+
+flow.success()
+```
+
+## API Reference
+
+### `better.log()` — The simple way
+
+```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)
+```
+
+### `better.flow()` — The structured way
+
+```typescript
+const flow = better.flow('name', {
+  tags: ['tag1', 'tag2'],           // Indexing labels
+  maxSteps: 100,                     // Safety limit
+  initialContext: { key: 'value' }   // Shared metadata
+})
+
+flow.setContext({ userId: 'abc' })   // Add context
+flow.getContext()                    // Get context copy
+
+flow.step('step-name', data)         // Create step
+  .success()                         // Mark success
+  .fail(error)                       // Mark failure
+
+flow.success()                       // Complete flow
+flow.fail(error)                     // Fail flow
+```
+
+### `better.flow.run()` — Async helper
+
+```typescript
+const result = await flow.run('async-step', async () => {
+  return await fetchData()  // Auto-completes step on success/fail
+})
+```
+
+### Configuration
+
+```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
+```
+
+## Real-World Examples
+
+We've included 10 comprehensive examples showing better-logger in real applications:
+
+| 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 |
+
+## Features
+
+### 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
+
+MIT

package/dist/index.cjs

@@ -1,3 +1,3 @@
-"use strict";var N=Object.defineProperty;var ee=Object.getOwnPropertyDescriptor;var te=Object.getOwnPropertyNames;var re=Object.prototype.hasOwnProperty;var ne=(e,t)=>{for(var r in t)N(e,r,{get:t[r],enumerable:!0})},oe=(e,t,r,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of te(t))!re.call(e,i)&&i!==r&&N(e,i,{get:()=>t[i],enumerable:!(n=ee(t,i))||n.enumerable});return e};var ie=e=>oe(N({},"__esModule",{value:!0}),e);var Oe={};ne(Oe,{NOOP_FLOW:()=>l,NOOP_STEP:()=>m,better:()=>d,createFlow:()=>v,getRenderer:()=>D,isEnabled:()=>C,normalizeError:()=>f,safeSerialize:()=>u,setClock:()=>X,setEnabled:()=>Q,setIdGenerator:()=>V,setRenderer:()=>P,subscribe:()=>L,toJSON:()=>W});module.exports=ie(Oe);function f(e){return e===void 0?{name:"Error",message:"Unknown error"}:e instanceof Error?{name:e.name,message:e.message,stack:e.stack}:typeof e=="string"?{name:"Error",message:e}:{name:"Error",message:String(e)}}var S=class{constructor(t,r){this._trace=t;this._clock=r;this._completed=!1}get isCompleted(){return this._completed}get trace(){return this._trace}success(){this._completed||(this._completed=!0,this._trace.end=this._clock.now(),this._trace.state="completed",this._trace.status="success")}fail(t){this._completed||(this._completed=!0,this._trace.end=this._clock.now(),this._trace.state="completed",this._trace.status="error",this._trace.error=f(t))}};var g=()=>{},m={success:g,fail:g},l={step:()=>m,child:()=>l,tag:g,tags:()=>[],setContext:g,getContext:()=>({}),success:g,fail:g,run:(e,t)=>{try{let r=t();return r instanceof Promise?r:Promise.resolve(r)}catch(r){return Promise.reject(r)}}};function J(e){let t=new WeakMap;function r(n){if(n===null||typeof n!="object")return n;if(n instanceof Date)return new Date(n.getTime());if(n instanceof RegExp)return new RegExp(n.source,n.flags);if(t.has(n))return t.get(n);if(Array.isArray(n)){let s=[];t.set(n,s);for(let o=0;o<n.length;o++)s.push(r(n[o]));return s}let i={};t.set(n,i);for(let s of Object.keys(n))i[s]=r(n[s]);return i}return r(e)}function k(e){if(e===null||typeof e!="object")return e;if(Object.freeze(e),Array.isArray(e))for(let t of e)k(t);else for(let t of Object.keys(e)){let r=e[t];r&&typeof r=="object"&&!Object.isFrozen(r)&&k(r)}return e}function b(e){let t=J(e);return k(t)}var T=new Set;function L(e){return T.add(e),()=>{T.delete(e)}}function se(e){if(T.size!==0)for(let t of T)try{t(e)}catch{}}var y=class e{constructor(t,r,n,i,s){this._trace=t;this._clock=r;this._idGen=n;this._renderer=i;this._options=s;this._completed=!1;this._sequence=0}get isCompleted(){return this._completed}get trace(){return this._trace}step(t,r){if(this._completed)return m;let n=this._options.maxSteps;if(n!==void 0&&this._trace.steps.length>=n)return this._trace.meta===void 0?this._trace.meta={maxStepsExceeded:!0}:this._trace.meta.maxStepsExceeded=!0,m;let i={id:this._idGen.generate(),name:t,sequence:this._sequence++,state:"running",status:"pending",start:this._clock.now(),data:r,children:[]};return this._trace.steps.push(i),new S(i,this._clock)}child(t){if(this._completed)return l;if(this._options.enabled===!1)return l;let r={id:this._idGen.generate(),name:t,parentId:this._trace.id,state:"running",status:void 0,tags:[],start:this._clock.now(),context:{...this._trace.context},steps:[]};return new e(r,this._clock,this._idGen,this._renderer,{...this._options})}tag(t){this._completed||this._trace.tags.includes(t)||this._trace.tags.push(t)}tags(){return[...this._trace.tags]}setContext(t){this._completed||Object.assign(this._trace.context,t)}getContext(){return{...this._trace.context}}success(){this._finalize("success")}fail(t){this._trace.error=f(t),this._finalize("error")}run(t,r){if(this._completed)return Promise.resolve(r());let n=this.step(t);return Promise.resolve(r()).then(i=>(n.success(),i),i=>{throw n.fail(i),i})}_finalize(t){if(this._completed)return;this._completed=!0,this._trace.end=this._clock.now(),this._trace.state="completed",this._trace.status=t;let r=b(this._trace);se(r),this._renderer.render(r)}};var x=class{generate(){return Math.random().toString(36).slice(2,10)}};var h=class{now(){return Date.now()}};function u(e,t){let r=t?.maxDepth??2,n=t?.maxLength??80,i=new WeakSet;function s(o,c){if(typeof o=="function")return`[Fn:${o.name||"?"}]`;if(typeof o=="symbol")return o.toString();if(c>r)return o&&typeof o=="object"?"[...]":o;if(o===null||typeof o!="object")return o;if(o instanceof Map)return`{Map(${o.size})}`;if(o instanceof Set)return`{Set(${o.size})}`;if(o instanceof Date)return o.toISOString();if(o instanceof RegExp)return o.toString();if(i.has(o))return"[Circular]";if(i.add(o),Array.isArray(o))return o.map(p=>s(p,c+1));let _={};for(let p of Object.keys(o)){let E=o[p];_[p]=s(E,c+1)}return _}try{let o=JSON.stringify(s(e,0));return o&&o.length>n?o.slice(0,n)+"\u2026":o}catch{return"[Unserializable]"}}var ae=()=>typeof process<"u"&&process.versions!==void 0&&process.versions.node!==void 0,le=()=>typeof EdgeRuntime<"u",ce=()=>typeof caches<"u"&&"default"in caches,de=()=>typeof window<"u"||typeof self<"u";function q(){return ae()?"node":le()||ce()?"edge":de()?"browser":"node"}var fe="\x1B[0m",ue="\x1B[32m",pe="\x1B[31m";var me="\x1B[36m";var ge="\x1B[2m";function we(){return!(q()==="browser"||typeof process<"u"&&process.env?.NO_COLOR)}var xe=we();function R(e,t){return xe?`${t}${e}${fe}`:e}function z(e){return R(e,ue)}function O(e){return R(e,pe)}function U(e){return R(e,me)}function I(e){return R(e,ge)}function B(e,t){if(t===void 0)return"\u2014";let r=Math.round(t-e);return r>=1e3?`${(r/1e3).toFixed(1)}s`:`${r}ms`}function Y(e,t,r){let n="  ".repeat(t);r.push(`${n}${U("\u2192")} ${e.name}`),e.data!==void 0&&r.push(`${n}  ${I("data:")} ${u(e.data,{maxLength:80})}`);let i=B(e.start,e.end);e.status==="success"?r.push(`${n}${z("\u2713")} ${e.name} (${i})`):e.status==="error"?r.push(`${n}${O("\u2717")} ${e.name} (error: ${e.error?.message??"Unknown error"})`):r.push(`${n}  ${e.name} (${i})`);for(let s of e.children)Y(s,t+1,r)}var F=class{constructor(){this.name="console"}render(t){let r=[],n=t.tags.length>0?` [${t.tags.join(", ")}]`:"",i=t.status==="error"?"\u{1F525}":"\u{1F680}";r.push(`${i} [flow:${t.name}]${n} (${I("tid:")} ${t.id})`);for(let c of t.steps)Y(c,1,r);let s=B(t.start,t.end),o=t.meta?.maxStepsExceeded?` ${O("\u26A0\uFE0F maxSteps exceeded")}`:"";t.status==="error"?(r.push(`\u{1F3C1} [flow:${t.name}] ${O("failed")} (${s}, error: ${t.error?.message??"Unknown error"})${o}`),console.error(r.join(`
-`))):(r.push(`\u{1F3C1} [flow:${t.name}] ${z("success")} (${s})${o}`),console.log(r.join(`
-`)))}};var H=null;function P(e){H=e}function D(){return H}function K(e){return H??e}var G=new x,A=new h,_e=new F,M=!0;function Q(e){M=e}function C(){return M}function V(e){G=e}function X(e){A=e}function v(e,t){if(!M)return l;let r=t?.sample??1;if(r<1&&Math.random()>r)return l;if(t?.enabled===!1)return l;let n=K(_e),i={id:G.generate(),name:e,state:"running",tags:t?.tags??[],start:A.now(),context:t?.initialContext?{...t.initialContext}:{},steps:[]};return new y(i,A,G,n,t??{})}var w={idleTimeout:100,flowName:"default",defaultTags:[]},a=null;function Se(e){if(a&&e===void 0&&!a.completed)return a.flow;let t=e??w.flowName,r=v(t,{tags:[...w.defaultTags]});return a={flow:r,timer:null,lastError:null,completed:!1},r}function ke(){a&&(a.timer&&clearTimeout(a.timer),a.timer=setTimeout(()=>{Z()},w.idleTimeout))}function Z(){!a||a.completed||(a.timer&&(clearTimeout(a.timer),a.timer=null),a.completed=!0,a.lastError?a.flow.fail(a.lastError):a.flow.success(),a=null)}function Te(e){return e!==null&&typeof e=="object"&&("flow"in e||"tags"in e)}function $(e,t,r,n){if(!C())return;let i,s;t===void 0?(i=void 0,s=void 0):Te(t)?r===void 0?(i=void 0,s=t):(i=void 0,s={...t,...r}):(i=t,s=r);let o=s?.flow,c=Se(o);if(s?.tags)for(let E of s.tags)c.tag(E);let _=n&&n!=="info"?`${e} [${n}]`:e,p=c.step(_,i);n==="error"?(p.fail(i),a.lastError=i,c.tag("error")):(p.success(),n&&n!=="info"&&c.tag(n)),ke()}var ye=(e,t,r)=>$(e,t,r),d=ye;d.info=(e,t,r)=>$(e,t,r,"info");d.warn=(e,t,r)=>$(e,t,r,"warn");d.error=(e,t,r)=>$(e,t,r,"error");d.setIdleTimeout=e=>{w.idleTimeout=e};d.setFlowName=e=>{w.flowName=e};d.setDefaultTags=e=>{w.defaultTags=e};d.activeFlow=()=>a?.flow??null;d.flush=()=>{Z()};function Re(e){return typeof e=="object"&&e!==null&&"trace"in e&&typeof e.trace=="object"&&e.trace!==null}function W(e){let t=Re(e)?e.trace:e;return JSON.stringify({version:1,flow:{id:t.id,name:t.name,...t.parentId!==void 0&&{parentId:t.parentId},state:t.state,...t.status!==void 0&&{status:t.status},tags:t.tags,start:t.start,...t.end!==void 0&&{end:t.end},...t.error!==void 0&&{error:t.error},context:t.context,steps:t.steps.map(j),...t.meta!==void 0&&{meta:t.meta}}},null,2)}function j(e){let t={id:e.id,name:e.name,sequence:e.sequence,state:e.state,status:e.status,start:e.start};if(e.end!==void 0&&(t.end=e.end),e.data!==void 0)try{t.data=JSON.parse(u(e.data))}catch{t.data="[Circular or unserializable]"}return e.error!==void 0&&(t.error=e.error),e.children.length>0&&(t.children=e.children.map(j)),t}0&&(module.exports={NOOP_FLOW,NOOP_STEP,better,createFlow,getRenderer,isEnabled,normalizeError,safeSerialize,setClock,setEnabled,setIdGenerator,setRenderer,subscribe,toJSON});
+"use strict";var I=Object.defineProperty;var ne=Object.getOwnPropertyDescriptor;var oe=Object.getOwnPropertyNames;var ie=Object.prototype.hasOwnProperty;var se=(e,r)=>{for(var t in r)I(e,t,{get:r[t],enumerable:!0})},ae=(e,r,t,n)=>{if(r&&typeof r=="object"||typeof r=="function")for(let i of oe(r))!ie.call(e,i)&&i!==t&&I(e,i,{get:()=>r[i],enumerable:!(n=ne(r,i))||n.enumerable});return e};var le=e=>ae(I({},"__esModule",{value:!0}),e);var ve={};se(ve,{NOOP_FLOW:()=>c,NOOP_STEP:()=>m,better:()=>d,createFlow:()=>k,getRenderer:()=>A,isEnabled:()=>x,normalizeError:()=>f,safeSerialize:()=>p,setClock:()=>j,setEnabled:()=>b,setIdGenerator:()=>Z,setRenderer:()=>G,subscribe:()=>H,toJSON:()=>J});module.exports=le(ve);function f(e){return e===void 0?{name:"Error",message:"Unknown error"}:e instanceof Error?{name:e.name,message:e.message,stack:e.stack}:typeof e=="string"?{name:"Error",message:e}:{name:"Error",message:String(e)}}var y=class{constructor(r,t){this._trace=r;this._clock=t;this._completed=!1}get isCompleted(){return this._completed}get trace(){return this._trace}success(){this._completed||(this._completed=!0,this._trace.end=this._clock.now(),this._trace.state="completed",this._trace.status="success")}fail(r){this._completed||(this._completed=!0,this._trace.end=this._clock.now(),this._trace.state="completed",this._trace.status="error",this._trace.error=f(r))}};var g=()=>{},m={success:g,fail:g},c={step:()=>m,child:()=>c,tag:g,tags:()=>[],setContext:g,getContext:()=>({}),success:g,fail:g,run:(e,r)=>{try{let t=r();return t instanceof Promise?t:Promise.resolve(t)}catch(t){return Promise.reject(t)}}};function U(e){let r=new WeakMap;function t(n){if(n===null||typeof n!="object")return n;if(n instanceof Date)return new Date(n.getTime());if(n instanceof RegExp)return new RegExp(n.source,n.flags);if(r.has(n))return r.get(n);if(Array.isArray(n)){let s=[];r.set(n,s);for(let o=0;o<n.length;o++)s.push(t(n[o]));return s}let i={};r.set(n,i);for(let s of Object.keys(n))i[s]=t(n[s]);return i}return t(e)}function R(e){if(e===null||typeof e!="object")return e;if(Object.freeze(e),Array.isArray(e))for(let r of e)R(r);else for(let r of Object.keys(e)){let t=e[r];t&&typeof t=="object"&&!Object.isFrozen(t)&&R(t)}return e}function z(e){let r=U(e);return R(r)}var O=new Set;function H(e){return O.add(e),()=>{O.delete(e)}}function ce(e){if(O.size!==0)for(let r of O)try{r(e)}catch{}}var C=class e{constructor(r,t,n,i,s){this._trace=r;this._clock=t;this._idGen=n;this._renderer=i;this._options=s;this._completed=!1;this._sequence=0}get isCompleted(){return this._completed}get trace(){return this._trace}step(r,t){if(this._completed)return m;let n=this._options.maxSteps;if(n!==void 0&&this._trace.steps.length>=n)return this._trace.meta===void 0?this._trace.meta={maxStepsExceeded:!0}:this._trace.meta.maxStepsExceeded=!0,m;let i={id:this._idGen.generate(),name:r,sequence:this._sequence++,state:"running",status:"pending",start:this._clock.now(),data:t,children:[]};return this._trace.steps.push(i),new y(i,this._clock)}child(r){if(this._completed)return c;if(this._options.enabled===!1)return c;let t={id:this._idGen.generate(),name:r,parentId:this._trace.id,state:"running",status:void 0,tags:[],start:this._clock.now(),context:{...this._trace.context},steps:[]};return new e(t,this._clock,this._idGen,this._renderer,{...this._options})}tag(r){this._completed||this._trace.tags.includes(r)||this._trace.tags.push(r)}tags(){return[...this._trace.tags]}setContext(r){this._completed||Object.assign(this._trace.context,r)}getContext(){return{...this._trace.context}}success(){this._finalize("success")}fail(r){this._trace.error=f(r),this._finalize("error")}run(r,t){if(this._completed)return Promise.resolve(t());let n=this.step(r);return Promise.resolve(t()).then(i=>(n.success(),i),i=>{throw n.fail(i),i})}_finalize(r){if(this._completed)return;this._completed=!0,this._trace.end=this._clock.now(),this._trace.state="completed",this._trace.status=r;let t=z(this._trace);ce(t),this._renderer.render(t)}};var h=class{generate(){return Math.random().toString(36).slice(2,10)}};var _=class{now(){return Date.now()}};function p(e,r){let t=r?.maxDepth??2,n=r?.maxLength??80,i=new WeakSet;function s(o,l){if(typeof o=="function")return`[Fn:${o.name||"?"}]`;if(typeof o=="symbol")return o.toString();if(l>t)return o&&typeof o=="object"?"[...]":o;if(o===null||typeof o!="object")return o;if(o instanceof Map)return`{Map(${o.size})}`;if(o instanceof Set)return`{Set(${o.size})}`;if(o instanceof Date)return o.toISOString();if(o instanceof RegExp)return o.toString();if(i.has(o))return"[Circular]";if(i.add(o),Array.isArray(o))return o.map(u=>s(u,l+1));let T={};for(let u of Object.keys(o)){let $=o[u];T[u]=s($,l+1)}return T}try{let o=JSON.stringify(s(e,0));return o&&o.length>n?o.slice(0,n)+"\u2026":o}catch{return"[Unserializable]"}}var de=()=>typeof process<"u"&&process.versions!==void 0&&process.versions.node!==void 0,ue=()=>typeof EdgeRuntime<"u",fe=()=>typeof caches<"u"&&"default"in caches,pe=()=>typeof window<"u"||typeof self<"u";function Y(){return de()?"node":ue()||fe()?"edge":pe()?"browser":"node"}var me="\x1B[0m",we="\x1B[32m",ge="\x1B[31m";var xe="\x1B[36m";var Fe="\x1B[2m";function he(){return!(Y()==="browser"||typeof process<"u"&&process.env?.NO_COLOR)}var _e=he();function v(e,r){return _e?`${r}${e}${me}`:e}function L(e){return v(e,we)}function E(e){return v(e,ge)}function K(e){return v(e,xe)}function P(e){return v(e,Fe)}function Q(e,r){if(r===void 0)return"\u2014";let t=Math.round(r-e);return t>=1e3?`${(t/1e3).toFixed(1)}s`:`${t}ms`}function V(e,r,t){let n="  ".repeat(r);t.push(`${n}${K("\u2192")} ${e.name}`),e.data!==void 0&&t.push(`${n}  ${P("data:")} ${p(e.data,{maxLength:80})}`);let i=Q(e.start,e.end);e.status==="success"?t.push(`${n}${L("\u2713")} ${e.name} (${i})`):e.status==="error"?t.push(`${n}${E("\u2717")} ${e.name} (error: ${e.error?.message??"Unknown error"})`):t.push(`${n}  ${e.name} (${i})`);for(let s of e.children)V(s,r+1,t)}var S=class{constructor(){this.name="console"}render(r){let t=[],n=r.tags.length>0?` [${r.tags.join(", ")}]`:"",i=r.status==="error"?"\u{1F525}":"\u{1F680}";t.push(`${i} [flow:${r.name}]${n} (${P("tid:")} ${r.id})`);for(let l of r.steps)V(l,1,t);let s=Q(r.start,r.end),o=r.meta?.maxStepsExceeded?` ${E("\u26A0\uFE0F maxSteps exceeded")}`:"";r.status==="error"?(t.push(`\u{1F3C1} [flow:${r.name}] ${E("failed")} (${s}, error: ${r.error?.message??"Unknown error"})${o}`),console.error(t.join(`
+`))):(t.push(`\u{1F3C1} [flow:${r.name}] ${L("success")} (${s})${o}`),console.log(t.join(`
+`)))}};var D=null;function G(e){D=e}function A(){return D}function X(e){return D??e}var B=new h,M=new _,Te=new S,W=!0;function b(e){W=e}function x(){return W}function Z(e){B=e}function j(e){M=e}function k(e,r){if(!W)return c;let t=r?.sample??1;if(t<1&&Math.random()>t)return c;if(r?.enabled===!1)return c;let n=X(Te),i={id:B.generate(),name:e,state:"running",tags:r?.tags??[],start:M.now(),context:r?.initialContext?{...r.initialContext}:{},steps:[]};return new C(i,M,B,n,r??{})}function ye(e){return e!==null&&typeof e=="object"&&("flow"in e||"tags"in e)}function Re(e,r,t){if(r.current&&t===void 0&&!r.current.completed)return r.current.flow;let n=t??e.flowName,i=k(n,{tags:[...e.defaultTags]});return r.current={flow:i,timer:null,lastError:null,completed:!1},i}function Oe(e,r){r.current&&(r.current.timer&&clearTimeout(r.current.timer),r.current.timer=setTimeout(()=>{ee(r)},e.idleTimeout))}function ee(e){!e.current||e.current.completed||(e.current.timer&&(clearTimeout(e.current.timer),e.current.timer=null),e.current.completed=!0,e.current.lastError?e.current.flow.fail(e.current.lastError):e.current.flow.success(),e.current=null)}function N(e,r,t,n,i,s){if(!x())return;let o,l;n===void 0?(o=void 0,l=void 0):ye(n)?i===void 0?(o=void 0,l=n):(o=void 0,l={...n,...i}):(o=n,l=i);let T=l?.flow,u=Re(e,r,T);if(l?.tags)for(let te of l.tags)u.tag(te);let $=s&&s!=="info"?`${t} [${s}]`:t,q=u.step($,o);s==="error"?(q.fail(o),r.current&&(r.current.lastError=o),u.tag("error")):(q.success(),s&&s!=="info"&&u.tag(s)),Oe(e,r)}var w={idleTimeout:100,flowName:"default",defaultTags:[]},F={current:null};function a(e,r,t){N(w,F,e,r,t)}a.info=(e,r,t)=>N(w,F,e,r,t,"info");a.warn=(e,r,t)=>N(w,F,e,r,t,"warn");a.error=(e,r,t)=>N(w,F,e,r,t,"error");a.setIdleTimeout=e=>{w.idleTimeout=e};a.setFlowName=e=>{w.flowName=e};a.setDefaultTags=e=>{w.defaultTags=e};a.activeFlow=()=>F.current?.flow??null;a.flush=()=>{ee(F)};var d=(e,r,t)=>{a(e,r,t)};d.log=a;d.flow=(e,r)=>k(e,r);d.setIdleTimeout=a.setIdleTimeout;d.setFlowName=a.setFlowName;d.setDefaultTags=a.setDefaultTags;d.activeFlow=a.activeFlow;d.flush=a.flush;d.setEnabled=b;d.isEnabled=x;function Ce(e){return typeof e=="object"&&e!==null&&"trace"in e&&typeof e.trace=="object"&&e.trace!==null}function J(e){let r=Ce(e)?e.trace:e;return JSON.stringify({version:1,flow:{id:r.id,name:r.name,...r.parentId!==void 0&&{parentId:r.parentId},state:r.state,...r.status!==void 0&&{status:r.status},tags:r.tags,start:r.start,...r.end!==void 0&&{end:r.end},...r.error!==void 0&&{error:r.error},context:r.context,steps:r.steps.map(re),...r.meta!==void 0&&{meta:r.meta}}},null,2)}function re(e){let r={id:e.id,name:e.name,sequence:e.sequence,state:e.state,status:e.status,start:e.start};if(e.end!==void 0&&(r.end=e.end),e.data!==void 0)try{r.data=JSON.parse(p(e.data))}catch{r.data="[Circular or unserializable]"}return e.error!==void 0&&(r.error=e.error),e.children.length>0&&(r.children=e.children.map(re)),r}0&&(module.exports={NOOP_FLOW,NOOP_STEP,better,createFlow,getRenderer,isEnabled,normalizeError,safeSerialize,setClock,setEnabled,setIdGenerator,setRenderer,subscribe,toJSON});

package/dist/index.d.cts

@@ -170,17 +170,16 @@ declare function setClock(clock: Clock): void;
 declare function createFlow<Data = unknown>(name: string, options?: FlowOptions): FlowHandle<Data>;
 
 /**
- * V3: Zero-Friction Log API
+ * V3: Zero-Friction better.log API
  *
  * Drop-in console.log replacement with auto-flow management.
  *
  * Usage:
- *   log('message')
- *   log('message', data)
- *   log('message', { tags: ['x'] })
- *   log('message', data, { tags: ['x'], flow: 'custom' })
- *   log.warn('warning', data)
- *   log.error('error', error)
+ *   better.log('message')
+ *   better.log('message', data)
+ *   better.log.warn('warning', data)
+ *   better.log.error('error', error)
+ *   better.flow('explicit-flow', { tags: ['auth'] })
  */
 
 /** Options for individual log calls */
@@ -190,22 +189,36 @@ interface LogCallOptions {
     /** Additional tags for this step */
     tags?: string[];
 }
-/** Public Log API */
-interface LogAPI {
-    (message: string, data?: unknown): void;
-    (message: string, options?: LogCallOptions): void;
-    (message: string, data?: unknown, options?: LogCallOptions): void;
-    info: LogFn;
-    warn: LogFn;
-    error: LogFn;
-    setIdleTimeout(ms: number): void;
-    setFlowName(name: string): void;
-    setDefaultTags(tags: string[]): void;
-    activeFlow(): FlowHandle | null;
-    flush(): void;
+/** Options for creating an explicit flow via better.flow() */
+interface BetterFlowOptions {
+    tags?: string[];
+    maxSteps?: number;
+    sample?: number;
+    initialContext?: Record<string, unknown>;
+}
+declare function logFn(message: string, dataOrOptions?: unknown, options?: LogCallOptions): void;
+declare namespace logFn {
+    var info: (message: string, dataOrOptions?: unknown, options?: LogCallOptions) => void;
+    var warn: (message: string, dataOrOptions?: unknown, options?: LogCallOptions) => void;
+    var error: (message: string, dataOrOptions?: unknown, options?: LogCallOptions) => void;
+    var setIdleTimeout: (ms: number) => void;
+    var setFlowName: (name: string) => void;
+    var setDefaultTags: (tags: string[]) => void;
+    var activeFlow: () => FlowHandle | null;
+    var flush: () => void;
 }
-type LogFn = (message: string, dataOrOptions?: unknown, options?: LogCallOptions) => void;
-declare const better: LogAPI;
+declare const betterBase: {
+    (message: string, dataOrOptions?: unknown, options?: LogCallOptions): void;
+    log: typeof logFn;
+    flow(name: string, options?: BetterFlowOptions): FlowHandle;
+    setIdleTimeout: (ms: number) => void;
+    setFlowName: (name: string) => void;
+    setDefaultTags: (tags: string[]) => void;
+    activeFlow: () => FlowHandle | null;
+    flush: () => void;
+    setEnabled: typeof setEnabled;
+    isEnabled: typeof isEnabled;
+};
 
 /** Contract for all renderer implementations */
 interface FlowRenderer {
@@ -233,4 +246,4 @@ declare function toJSON(input: Readonly<FlowTrace> | {
     trace: Readonly<FlowTrace>;
 }): string;
 
-export { type LogAPI as BetterLogAPI, type Clock, type FlowListener, type FlowOptions, type FlowRenderer, type FlowState, type FlowStatus, type FlowTrace, type IdGenerator, type LogCallOptions, NOOP_FLOW, NOOP_STEP, type NoOpFlowHandle, type NoOpStepHandle, type NormalizedError, type SerializeOptions, type StepStatus, type StepTrace, better, createFlow, getRenderer, isEnabled, normalizeError, safeSerialize, setClock, setEnabled, setIdGenerator, setRenderer, subscribe, toJSON };
+export { type BetterFlowOptions, type Clock, type FlowListener, type FlowOptions, type FlowRenderer, type FlowState, type FlowStatus, type FlowTrace, type IdGenerator, type LogCallOptions, NOOP_FLOW, NOOP_STEP, type NoOpFlowHandle, type NoOpStepHandle, type NormalizedError, type SerializeOptions, type StepStatus, type StepTrace, betterBase as better, createFlow, getRenderer, isEnabled, normalizeError, safeSerialize, setClock, setEnabled, setIdGenerator, setRenderer, subscribe, toJSON };

package/dist/index.d.ts

@@ -170,17 +170,16 @@ declare function setClock(clock: Clock): void;
 declare function createFlow<Data = unknown>(name: string, options?: FlowOptions): FlowHandle<Data>;
 
 /**
- * V3: Zero-Friction Log API
+ * V3: Zero-Friction better.log API
  *
  * Drop-in console.log replacement with auto-flow management.
  *
  * Usage:
- *   log('message')
- *   log('message', data)
- *   log('message', { tags: ['x'] })
- *   log('message', data, { tags: ['x'], flow: 'custom' })
- *   log.warn('warning', data)
- *   log.error('error', error)
+ *   better.log('message')
+ *   better.log('message', data)
+ *   better.log.warn('warning', data)
+ *   better.log.error('error', error)
+ *   better.flow('explicit-flow', { tags: ['auth'] })
  */
 
 /** Options for individual log calls */
@@ -190,22 +189,36 @@ interface LogCallOptions {
     /** Additional tags for this step */
     tags?: string[];
 }
-/** Public Log API */
-interface LogAPI {
-    (message: string, data?: unknown): void;
-    (message: string, options?: LogCallOptions): void;
-    (message: string, data?: unknown, options?: LogCallOptions): void;
-    info: LogFn;
-    warn: LogFn;
-    error: LogFn;
-    setIdleTimeout(ms: number): void;
-    setFlowName(name: string): void;
-    setDefaultTags(tags: string[]): void;
-    activeFlow(): FlowHandle | null;
-    flush(): void;
+/** Options for creating an explicit flow via better.flow() */
+interface BetterFlowOptions {
+    tags?: string[];
+    maxSteps?: number;
+    sample?: number;
+    initialContext?: Record<string, unknown>;
+}
+declare function logFn(message: string, dataOrOptions?: unknown, options?: LogCallOptions): void;
+declare namespace logFn {
+    var info: (message: string, dataOrOptions?: unknown, options?: LogCallOptions) => void;
+    var warn: (message: string, dataOrOptions?: unknown, options?: LogCallOptions) => void;
+    var error: (message: string, dataOrOptions?: unknown, options?: LogCallOptions) => void;
+    var setIdleTimeout: (ms: number) => void;
+    var setFlowName: (name: string) => void;
+    var setDefaultTags: (tags: string[]) => void;
+    var activeFlow: () => FlowHandle | null;
+    var flush: () => void;
 }
-type LogFn = (message: string, dataOrOptions?: unknown, options?: LogCallOptions) => void;
-declare const better: LogAPI;
+declare const betterBase: {
+    (message: string, dataOrOptions?: unknown, options?: LogCallOptions): void;
+    log: typeof logFn;
+    flow(name: string, options?: BetterFlowOptions): FlowHandle;
+    setIdleTimeout: (ms: number) => void;
+    setFlowName: (name: string) => void;
+    setDefaultTags: (tags: string[]) => void;
+    activeFlow: () => FlowHandle | null;
+    flush: () => void;
+    setEnabled: typeof setEnabled;
+    isEnabled: typeof isEnabled;
+};
 
 /** Contract for all renderer implementations */
 interface FlowRenderer {
@@ -233,4 +246,4 @@ declare function toJSON(input: Readonly<FlowTrace> | {
     trace: Readonly<FlowTrace>;
 }): string;
 
-export { type LogAPI as BetterLogAPI, type Clock, type FlowListener, type FlowOptions, type FlowRenderer, type FlowState, type FlowStatus, type FlowTrace, type IdGenerator, type LogCallOptions, NOOP_FLOW, NOOP_STEP, type NoOpFlowHandle, type NoOpStepHandle, type NormalizedError, type SerializeOptions, type StepStatus, type StepTrace, better, createFlow, getRenderer, isEnabled, normalizeError, safeSerialize, setClock, setEnabled, setIdGenerator, setRenderer, subscribe, toJSON };
+export { type BetterFlowOptions, type Clock, type FlowListener, type FlowOptions, type FlowRenderer, type FlowState, type FlowStatus, type FlowTrace, type IdGenerator, type LogCallOptions, NOOP_FLOW, NOOP_STEP, type NoOpFlowHandle, type NoOpStepHandle, type NormalizedError, type SerializeOptions, type StepStatus, type StepTrace, betterBase as better, createFlow, getRenderer, isEnabled, normalizeError, safeSerialize, setClock, setEnabled, setIdGenerator, setRenderer, subscribe, toJSON };

package/dist/index.js

@@ -1,3 +1,3 @@
-function u(e){return e===void 0?{name:"Error",message:"Unknown error"}:e instanceof Error?{name:e.name,message:e.message,stack:e.stack}:typeof e=="string"?{name:"Error",message:e}:{name:"Error",message:String(e)}}var S=class{constructor(t,r){this._trace=t;this._clock=r;this._completed=!1}get isCompleted(){return this._completed}get trace(){return this._trace}success(){this._completed||(this._completed=!0,this._trace.end=this._clock.now(),this._trace.state="completed",this._trace.status="success")}fail(t){this._completed||(this._completed=!0,this._trace.end=this._clock.now(),this._trace.state="completed",this._trace.status="error",this._trace.error=u(t))}};var m=()=>{},g={success:m,fail:m},c={step:()=>g,child:()=>c,tag:m,tags:()=>[],setContext:m,getContext:()=>({}),success:m,fail:m,run:(e,t)=>{try{let r=t();return r instanceof Promise?r:Promise.resolve(r)}catch(r){return Promise.reject(r)}}};function D(e){let t=new WeakMap;function r(n){if(n===null||typeof n!="object")return n;if(n instanceof Date)return new Date(n.getTime());if(n instanceof RegExp)return new RegExp(n.source,n.flags);if(t.has(n))return t.get(n);if(Array.isArray(n)){let s=[];t.set(n,s);for(let o=0;o<n.length;o++)s.push(r(n[o]));return s}let i={};t.set(n,i);for(let s of Object.keys(n))i[s]=r(n[s]);return i}return r(e)}function k(e){if(e===null||typeof e!="object")return e;if(Object.freeze(e),Array.isArray(e))for(let t of e)k(t);else for(let t of Object.keys(e)){let r=e[t];r&&typeof r=="object"&&!Object.isFrozen(r)&&k(r)}return e}function $(e){let t=D(e);return k(t)}var T=new Set;function G(e){return T.add(e),()=>{T.delete(e)}}function V(e){if(T.size!==0)for(let t of T)try{t(e)}catch{}}var y=class e{constructor(t,r,n,i,s){this._trace=t;this._clock=r;this._idGen=n;this._renderer=i;this._options=s;this._completed=!1;this._sequence=0}get isCompleted(){return this._completed}get trace(){return this._trace}step(t,r){if(this._completed)return g;let n=this._options.maxSteps;if(n!==void 0&&this._trace.steps.length>=n)return this._trace.meta===void 0?this._trace.meta={maxStepsExceeded:!0}:this._trace.meta.maxStepsExceeded=!0,g;let i={id:this._idGen.generate(),name:t,sequence:this._sequence++,state:"running",status:"pending",start:this._clock.now(),data:r,children:[]};return this._trace.steps.push(i),new S(i,this._clock)}child(t){if(this._completed)return c;if(this._options.enabled===!1)return c;let r={id:this._idGen.generate(),name:t,parentId:this._trace.id,state:"running",status:void 0,tags:[],start:this._clock.now(),context:{...this._trace.context},steps:[]};return new e(r,this._clock,this._idGen,this._renderer,{...this._options})}tag(t){this._completed||this._trace.tags.includes(t)||this._trace.tags.push(t)}tags(){return[...this._trace.tags]}setContext(t){this._completed||Object.assign(this._trace.context,t)}getContext(){return{...this._trace.context}}success(){this._finalize("success")}fail(t){this._trace.error=u(t),this._finalize("error")}run(t,r){if(this._completed)return Promise.resolve(r());let n=this.step(t);return Promise.resolve(r()).then(i=>(n.success(),i),i=>{throw n.fail(i),i})}_finalize(t){if(this._completed)return;this._completed=!0,this._trace.end=this._clock.now(),this._trace.state="completed",this._trace.status=t;let r=$(this._trace);V(r),this._renderer.render(r)}};var x=class{generate(){return Math.random().toString(36).slice(2,10)}};var h=class{now(){return Date.now()}};function p(e,t){let r=t?.maxDepth??2,n=t?.maxLength??80,i=new WeakSet;function s(o,l){if(typeof o=="function")return`[Fn:${o.name||"?"}]`;if(typeof o=="symbol")return o.toString();if(l>r)return o&&typeof o=="object"?"[...]":o;if(o===null||typeof o!="object")return o;if(o instanceof Map)return`{Map(${o.size})}`;if(o instanceof Set)return`{Set(${o.size})}`;if(o instanceof Date)return o.toISOString();if(o instanceof RegExp)return o.toString();if(i.has(o))return"[Circular]";if(i.add(o),Array.isArray(o))return o.map(f=>s(f,l+1));let _={};for(let f of Object.keys(o)){let v=o[f];_[f]=s(v,l+1)}return _}try{let o=JSON.stringify(s(e,0));return o&&o.length>n?o.slice(0,n)+"\u2026":o}catch{return"[Unserializable]"}}var X=()=>typeof process<"u"&&process.versions!==void 0&&process.versions.node!==void 0,Z=()=>typeof EdgeRuntime<"u",j=()=>typeof caches<"u"&&"default"in caches,ee=()=>typeof window<"u"||typeof self<"u";function A(){return X()?"node":Z()||j()?"edge":ee()?"browser":"node"}var te="\x1B[0m",re="\x1B[32m",ne="\x1B[31m";var oe="\x1B[36m";var ie="\x1B[2m";function se(){return!(A()==="browser"||typeof process<"u"&&process.env?.NO_COLOR)}var ae=se();function R(e,t){return ae?`${t}${e}${te}`:e}function E(e){return R(e,re)}function O(e){return R(e,ne)}function M(e){return R(e,oe)}function N(e){return R(e,ie)}function W(e,t){if(t===void 0)return"\u2014";let r=Math.round(t-e);return r>=1e3?`${(r/1e3).toFixed(1)}s`:`${r}ms`}function J(e,t,r){let n="  ".repeat(t);r.push(`${n}${M("\u2192")} ${e.name}`),e.data!==void 0&&r.push(`${n}  ${N("data:")} ${p(e.data,{maxLength:80})}`);let i=W(e.start,e.end);e.status==="success"?r.push(`${n}${E("\u2713")} ${e.name} (${i})`):e.status==="error"?r.push(`${n}${O("\u2717")} ${e.name} (error: ${e.error?.message??"Unknown error"})`):r.push(`${n}  ${e.name} (${i})`);for(let s of e.children)J(s,t+1,r)}var F=class{constructor(){this.name="console"}render(t){let r=[],n=t.tags.length>0?` [${t.tags.join(", ")}]`:"",i=t.status==="error"?"\u{1F525}":"\u{1F680}";r.push(`${i} [flow:${t.name}]${n} (${N("tid:")} ${t.id})`);for(let l of t.steps)J(l,1,r);let s=W(t.start,t.end),o=t.meta?.maxStepsExceeded?` ${O("\u26A0\uFE0F maxSteps exceeded")}`:"";t.status==="error"?(r.push(`\u{1F3C1} [flow:${t.name}] ${O("failed")} (${s}, error: ${t.error?.message??"Unknown error"})${o}`),console.error(r.join(`
-`))):(r.push(`\u{1F3C1} [flow:${t.name}] ${E("success")} (${s})${o}`),console.log(r.join(`
-`)))}};var b=null;function q(e){b=e}function U(){return b}function B(e){return b??e}var L=new x,z=new h,de=new F,I=!0;function fe(e){I=e}function H(){return I}function ue(e){L=e}function pe(e){z=e}function P(e,t){if(!I)return c;let r=t?.sample??1;if(r<1&&Math.random()>r)return c;if(t?.enabled===!1)return c;let n=B(de),i={id:L.generate(),name:e,state:"running",tags:t?.tags??[],start:z.now(),context:t?.initialContext?{...t.initialContext}:{},steps:[]};return new y(i,z,L,n,t??{})}var w={idleTimeout:100,flowName:"default",defaultTags:[]},a=null;function me(e){if(a&&e===void 0&&!a.completed)return a.flow;let t=e??w.flowName,r=P(t,{tags:[...w.defaultTags]});return a={flow:r,timer:null,lastError:null,completed:!1},r}function ge(){a&&(a.timer&&clearTimeout(a.timer),a.timer=setTimeout(()=>{Y()},w.idleTimeout))}function Y(){!a||a.completed||(a.timer&&(clearTimeout(a.timer),a.timer=null),a.completed=!0,a.lastError?a.flow.fail(a.lastError):a.flow.success(),a=null)}function we(e){return e!==null&&typeof e=="object"&&("flow"in e||"tags"in e)}function C(e,t,r,n){if(!H())return;let i,s;t===void 0?(i=void 0,s=void 0):we(t)?r===void 0?(i=void 0,s=t):(i=void 0,s={...t,...r}):(i=t,s=r);let o=s?.flow,l=me(o);if(s?.tags)for(let v of s.tags)l.tag(v);let _=n&&n!=="info"?`${e} [${n}]`:e,f=l.step(_,i);n==="error"?(f.fail(i),a.lastError=i,l.tag("error")):(f.success(),n&&n!=="info"&&l.tag(n)),ge()}var xe=(e,t,r)=>C(e,t,r),d=xe;d.info=(e,t,r)=>C(e,t,r,"info");d.warn=(e,t,r)=>C(e,t,r,"warn");d.error=(e,t,r)=>C(e,t,r,"error");d.setIdleTimeout=e=>{w.idleTimeout=e};d.setFlowName=e=>{w.flowName=e};d.setDefaultTags=e=>{w.defaultTags=e};d.activeFlow=()=>a?.flow??null;d.flush=()=>{Y()};function he(e){return typeof e=="object"&&e!==null&&"trace"in e&&typeof e.trace=="object"&&e.trace!==null}function K(e){let t=he(e)?e.trace:e;return JSON.stringify({version:1,flow:{id:t.id,name:t.name,...t.parentId!==void 0&&{parentId:t.parentId},state:t.state,...t.status!==void 0&&{status:t.status},tags:t.tags,start:t.start,...t.end!==void 0&&{end:t.end},...t.error!==void 0&&{error:t.error},context:t.context,steps:t.steps.map(Q),...t.meta!==void 0&&{meta:t.meta}}},null,2)}function Q(e){let t={id:e.id,name:e.name,sequence:e.sequence,state:e.state,status:e.status,start:e.start};if(e.end!==void 0&&(t.end=e.end),e.data!==void 0)try{t.data=JSON.parse(p(e.data))}catch{t.data="[Circular or unserializable]"}return e.error!==void 0&&(t.error=e.error),e.children.length>0&&(t.children=e.children.map(Q)),t}export{c as NOOP_FLOW,g as NOOP_STEP,d as better,P as createFlow,U as getRenderer,H as isEnabled,u as normalizeError,p as safeSerialize,pe as setClock,fe as setEnabled,ue as setIdGenerator,q as setRenderer,G as subscribe,K as toJSON};
+function f(e){return e===void 0?{name:"Error",message:"Unknown error"}:e instanceof Error?{name:e.name,message:e.message,stack:e.stack}:typeof e=="string"?{name:"Error",message:e}:{name:"Error",message:String(e)}}var T=class{constructor(r,t){this._trace=r;this._clock=t;this._completed=!1}get isCompleted(){return this._completed}get trace(){return this._trace}success(){this._completed||(this._completed=!0,this._trace.end=this._clock.now(),this._trace.state="completed",this._trace.status="success")}fail(r){this._completed||(this._completed=!0,this._trace.end=this._clock.now(),this._trace.state="completed",this._trace.status="error",this._trace.error=f(r))}};var w=()=>{},g={success:w,fail:w},c={step:()=>g,child:()=>c,tag:w,tags:()=>[],setContext:w,getContext:()=>({}),success:w,fail:w,run:(e,r)=>{try{let t=r();return t instanceof Promise?t:Promise.resolve(t)}catch(t){return Promise.reject(t)}}};function B(e){let r=new WeakMap;function t(n){if(n===null||typeof n!="object")return n;if(n instanceof Date)return new Date(n.getTime());if(n instanceof RegExp)return new RegExp(n.source,n.flags);if(r.has(n))return r.get(n);if(Array.isArray(n)){let s=[];r.set(n,s);for(let o=0;o<n.length;o++)s.push(t(n[o]));return s}let i={};r.set(n,i);for(let s of Object.keys(n))i[s]=t(n[s]);return i}return t(e)}function y(e){if(e===null||typeof e!="object")return e;if(Object.freeze(e),Array.isArray(e))for(let r of e)y(r);else for(let r of Object.keys(e)){let t=e[r];t&&typeof t=="object"&&!Object.isFrozen(t)&&y(t)}return e}function $(e){let r=B(e);return y(r)}var R=new Set;function M(e){return R.add(e),()=>{R.delete(e)}}function ee(e){if(R.size!==0)for(let r of R)try{r(e)}catch{}}var O=class e{constructor(r,t,n,i,s){this._trace=r;this._clock=t;this._idGen=n;this._renderer=i;this._options=s;this._completed=!1;this._sequence=0}get isCompleted(){return this._completed}get trace(){return this._trace}step(r,t){if(this._completed)return g;let n=this._options.maxSteps;if(n!==void 0&&this._trace.steps.length>=n)return this._trace.meta===void 0?this._trace.meta={maxStepsExceeded:!0}:this._trace.meta.maxStepsExceeded=!0,g;let i={id:this._idGen.generate(),name:r,sequence:this._sequence++,state:"running",status:"pending",start:this._clock.now(),data:t,children:[]};return this._trace.steps.push(i),new T(i,this._clock)}child(r){if(this._completed)return c;if(this._options.enabled===!1)return c;let t={id:this._idGen.generate(),name:r,parentId:this._trace.id,state:"running",status:void 0,tags:[],start:this._clock.now(),context:{...this._trace.context},steps:[]};return new e(t,this._clock,this._idGen,this._renderer,{...this._options})}tag(r){this._completed||this._trace.tags.includes(r)||this._trace.tags.push(r)}tags(){return[...this._trace.tags]}setContext(r){this._completed||Object.assign(this._trace.context,r)}getContext(){return{...this._trace.context}}success(){this._finalize("success")}fail(r){this._trace.error=f(r),this._finalize("error")}run(r,t){if(this._completed)return Promise.resolve(t());let n=this.step(r);return Promise.resolve(t()).then(i=>(n.success(),i),i=>{throw n.fail(i),i})}_finalize(r){if(this._completed)return;this._completed=!0,this._trace.end=this._clock.now(),this._trace.state="completed",this._trace.status=r;let t=$(this._trace);ee(t),this._renderer.render(t)}};var F=class{generate(){return Math.random().toString(36).slice(2,10)}};var h=class{now(){return Date.now()}};function p(e,r){let t=r?.maxDepth??2,n=r?.maxLength??80,i=new WeakSet;function s(o,l){if(typeof o=="function")return`[Fn:${o.name||"?"}]`;if(typeof o=="symbol")return o.toString();if(l>t)return o&&typeof o=="object"?"[...]":o;if(o===null||typeof o!="object")return o;if(o instanceof Map)return`{Map(${o.size})}`;if(o instanceof Set)return`{Set(${o.size})}`;if(o instanceof Date)return o.toISOString();if(o instanceof RegExp)return o.toString();if(i.has(o))return"[Circular]";if(i.add(o),Array.isArray(o))return o.map(u=>s(u,l+1));let k={};for(let u of Object.keys(o)){let N=o[u];k[u]=s(N,l+1)}return k}try{let o=JSON.stringify(s(e,0));return o&&o.length>n?o.slice(0,n)+"\u2026":o}catch{return"[Unserializable]"}}var re=()=>typeof process<"u"&&process.versions!==void 0&&process.versions.node!==void 0,te=()=>typeof EdgeRuntime<"u",ne=()=>typeof caches<"u"&&"default"in caches,oe=()=>typeof window<"u"||typeof self<"u";function W(){return re()?"node":te()||ne()?"edge":oe()?"browser":"node"}var ie="\x1B[0m",se="\x1B[32m",ae="\x1B[31m";var le="\x1B[36m";var ce="\x1B[2m";function de(){return!(W()==="browser"||typeof process<"u"&&process.env?.NO_COLOR)}var ue=de();function C(e,r){return ue?`${r}${e}${ie}`:e}function I(e){return C(e,se)}function v(e){return C(e,ae)}function J(e){return C(e,le)}function z(e){return C(e,ce)}function q(e,r){if(r===void 0)return"\u2014";let t=Math.round(r-e);return t>=1e3?`${(t/1e3).toFixed(1)}s`:`${t}ms`}function U(e,r,t){let n="  ".repeat(r);t.push(`${n}${J("\u2192")} ${e.name}`),e.data!==void 0&&t.push(`${n}  ${z("data:")} ${p(e.data,{maxLength:80})}`);let i=q(e.start,e.end);e.status==="success"?t.push(`${n}${I("\u2713")} ${e.name} (${i})`):e.status==="error"?t.push(`${n}${v("\u2717")} ${e.name} (error: ${e.error?.message??"Unknown error"})`):t.push(`${n}  ${e.name} (${i})`);for(let s of e.children)U(s,r+1,t)}var _=class{constructor(){this.name="console"}render(r){let t=[],n=r.tags.length>0?` [${r.tags.join(", ")}]`:"",i=r.status==="error"?"\u{1F525}":"\u{1F680}";t.push(`${i} [flow:${r.name}]${n} (${z("tid:")} ${r.id})`);for(let l of r.steps)U(l,1,t);let s=q(r.start,r.end),o=r.meta?.maxStepsExceeded?` ${v("\u26A0\uFE0F maxSteps exceeded")}`:"";r.status==="error"?(t.push(`\u{1F3C1} [flow:${r.name}] ${v("failed")} (${s}, error: ${r.error?.message??"Unknown error"})${o}`),console.error(t.join(`
+`))):(t.push(`\u{1F3C1} [flow:${r.name}] ${I("success")} (${s})${o}`),console.log(t.join(`
+`)))}};var H=null;function Y(e){H=e}function K(){return H}function Q(e){return H??e}var L=new F,P=new h,me=new _,D=!0;function G(e){D=e}function S(){return D}function we(e){L=e}function ge(e){P=e}function E(e,r){if(!D)return c;let t=r?.sample??1;if(t<1&&Math.random()>t)return c;if(r?.enabled===!1)return c;let n=Q(me),i={id:L.generate(),name:e,state:"running",tags:r?.tags??[],start:P.now(),context:r?.initialContext?{...r.initialContext}:{},steps:[]};return new O(i,P,L,n,r??{})}function xe(e){return e!==null&&typeof e=="object"&&("flow"in e||"tags"in e)}function Fe(e,r,t){if(r.current&&t===void 0&&!r.current.completed)return r.current.flow;let n=t??e.flowName,i=E(n,{tags:[...e.defaultTags]});return r.current={flow:i,timer:null,lastError:null,completed:!1},i}function he(e,r){r.current&&(r.current.timer&&clearTimeout(r.current.timer),r.current.timer=setTimeout(()=>{V(r)},e.idleTimeout))}function V(e){!e.current||e.current.completed||(e.current.timer&&(clearTimeout(e.current.timer),e.current.timer=null),e.current.completed=!0,e.current.lastError?e.current.flow.fail(e.current.lastError):e.current.flow.success(),e.current=null)}function b(e,r,t,n,i,s){if(!S())return;let o,l;n===void 0?(o=void 0,l=void 0):xe(n)?i===void 0?(o=void 0,l=n):(o=void 0,l={...n,...i}):(o=n,l=i);let k=l?.flow,u=Fe(e,r,k);if(l?.tags)for(let j of l.tags)u.tag(j);let N=s&&s!=="info"?`${t} [${s}]`:t,A=u.step(N,o);s==="error"?(A.fail(o),r.current&&(r.current.lastError=o),u.tag("error")):(A.success(),s&&s!=="info"&&u.tag(s)),he(e,r)}var m={idleTimeout:100,flowName:"default",defaultTags:[]},x={current:null};function a(e,r,t){b(m,x,e,r,t)}a.info=(e,r,t)=>b(m,x,e,r,t,"info");a.warn=(e,r,t)=>b(m,x,e,r,t,"warn");a.error=(e,r,t)=>b(m,x,e,r,t,"error");a.setIdleTimeout=e=>{m.idleTimeout=e};a.setFlowName=e=>{m.flowName=e};a.setDefaultTags=e=>{m.defaultTags=e};a.activeFlow=()=>x.current?.flow??null;a.flush=()=>{V(x)};var d=(e,r,t)=>{a(e,r,t)};d.log=a;d.flow=(e,r)=>E(e,r);d.setIdleTimeout=a.setIdleTimeout;d.setFlowName=a.setFlowName;d.setDefaultTags=a.setDefaultTags;d.activeFlow=a.activeFlow;d.flush=a.flush;d.setEnabled=G;d.isEnabled=S;function _e(e){return typeof e=="object"&&e!==null&&"trace"in e&&typeof e.trace=="object"&&e.trace!==null}function X(e){let r=_e(e)?e.trace:e;return JSON.stringify({version:1,flow:{id:r.id,name:r.name,...r.parentId!==void 0&&{parentId:r.parentId},state:r.state,...r.status!==void 0&&{status:r.status},tags:r.tags,start:r.start,...r.end!==void 0&&{end:r.end},...r.error!==void 0&&{error:r.error},context:r.context,steps:r.steps.map(Z),...r.meta!==void 0&&{meta:r.meta}}},null,2)}function Z(e){let r={id:e.id,name:e.name,sequence:e.sequence,state:e.state,status:e.status,start:e.start};if(e.end!==void 0&&(r.end=e.end),e.data!==void 0)try{r.data=JSON.parse(p(e.data))}catch{r.data="[Circular or unserializable]"}return e.error!==void 0&&(r.error=e.error),e.children.length>0&&(r.children=e.children.map(Z)),r}export{c as NOOP_FLOW,g as NOOP_STEP,d as better,E as createFlow,K as getRenderer,S as isEnabled,f as normalizeError,p as safeSerialize,ge as setClock,G as setEnabled,we as setIdGenerator,Y as setRenderer,M as subscribe,X as toJSON};

package/package.json

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