nanoeffects 0.0.0-stage → 0.2.0

package/docs/tracing.md

@@ -0,0 +1,117 @@
+# Tracing
+
+## Tracing
+
+Pass `trace` to `createBus` to observe every task phase. Make it with `createTracer` from `nanoeffects/trace`, which takes a logger (a function) or an array of them. The tracing code lives in that entry, so a bus without `trace` does not carry it.
+
+```ts
+import { createBus } from "nanoeffects";
+import { createTracer } from "nanoeffects/trace";
+
+const bus = createBus<Events>({
+  trace: createTracer((event) => console.log(event)),
+});
+```
+
+Each `TraceEvent` has:
+
+| Field     | Meaning                                                              |
+| --------- | -------------------------------------------------------------------- |
+| `id`      | Unique task id within the bus.                                       |
+| `parent`  | Id of the task that started this one (absent for handler tasks).     |
+| `type`    | Event type the task works on.                                        |
+| `effect`  | `latest`, `debounce`, `throttle`, `leading`, `run`, `all` or `race`. |
+| `phase`   | `start`, `done`, `error`, `cancel` or `drop`.                        |
+| `payload` | Event payload.                                                       |
+| `error`   | Thrown value, only for `error`.                                      |
+
+Phases:
+
+- `start`: the work began.
+- `done` / `error`: it finished or threw.
+- `cancel`: it was aborted after it started (superseded by `latest`, parent aborted, lost a `race`).
+- `drop`: it never started (`leading` while busy, a `throttle` call replaced by a newer one, a `debounce` call replaced before its delay ended).
+
+`all` and `race` are traced when you pass them the handler `ctx`: the group is one task, every starter is a child `run` task.
+
+```ts
+bus.on("load", async (id, ctx) => {
+  await all(ctx, { user: () => fetchUser(id), posts: () => fetchPosts(id) });
+});
+```
+
+## Loggers
+
+A logger is a function `(event: TraceEvent) => void` (the `TraceLogger` type). `createTracer` takes one logger or an array; a logger that throws is reported to `console.error` and never breaks the task or the other loggers.
+
+```ts
+import { createBus } from "nanoeffects";
+import { consoleLogger, createTracer, reduxDevtools } from "nanoeffects/trace";
+
+const bus = createBus<Events>({
+  trace: createTracer([reduxDevtools({ name: "app" }), consoleLogger()]),
+});
+```
+
+`nanoeffects/trace` ships `createTracer` and these loggers, each a factory that returns a `TraceLogger`:
+
+| Logger                  | What it does                                                                         |
+| ----------------------- | ------------------------------------------------------------------------------------ |
+| `reduxDevtools()`       | Sends tasks to Redux DevTools as `type/effect/phase`; state is `{ running }`.        |
+| `consoleLogger()`       | Prints one line per phase, indented by task depth.                                   |
+| `performanceLogger()`   | Records User Timing measures for the Timings track of the browser Performance panel. |
+| `createTraceRecorder()` | Keeps events in `recorder.events`, for tests.                                        |
+
+### Production: filter and sampling
+
+`createTracer(loggers, options)` can cut the volume:
+
+```ts
+createTracer(logger, {
+  sample: 0.05, // trace 5% of the handler calls (a share, or a function of { type, payload })
+  filter: (event) => event.phase === "error", // and keep only failures
+});
+```
+
+- `sample` is decided once per root task (one handler call) and every task below it follows, so a trace is never cut in the middle. Tasks that are not sampled cost almost nothing: their effects run without tracing.
+- `filter` runs on each event before any logger sees it.
+
+Notes on `reduxDevtools`: it is read-only (the bus owns no state, so there is no time travel) and does nothing when the extension is not installed. It has its own instance in the DevTools picker, apart from your store.
+
+It is quiet by default, so the log stays readable:
+
+- **A task is one action**, sent when it ends (`done`, `error`, `cancel`, `drop`). The tasks that are running are in the state, `{ running }`. `starts: true` also sends every start.
+- **Only the top is shown**: the handler tasks and the effects they start (`retry`, `timeout`, ...). The attempts and starters under them are hidden. `depth: 0` shows the handler tasks only, `depth: 3` more, `Infinity` everything.
+- `maxAge: 200` sets how many actions DevTools keeps (its own default is 50).
+
+```ts
+reduxDevtools({ name: "app", depth: 0 }); // one line per handler call
+reduxDevtools({ name: "app", starts: true, depth: Infinity }); // everything, for a hunt for a bug
+```
+
+For more control, `createTracer(logger, { filter, sample })` cuts events before any logger sees them.
+
+To write your own, return a `TraceLogger`:
+
+```ts
+import type { TraceLogger } from "nanoeffects";
+
+const errorsOnly = (): TraceLogger => (event) => {
+  if (event.phase === "error") report(event.error);
+};
+```
+
+## Removing tracing from a build
+
+Without a tracer the hooks cost almost nothing (a lookup that finds no tracer), and `nanoeffects/trace` is a separate entry that is only bundled when imported. To also drop the tracing code from the core, use the `notrace` export condition: the package ships a second build of `index`, `effects`, `policies` and `actions` made with `__NANOEFFECTS_TRACE__` set to `false`, so the bundler removes the tracer calls.
+
+```ts
+// vite / rolldown
+resolve: { conditions: ["notrace"] }
+// webpack
+resolve: { conditionNames: ["notrace", "import", "..."] }
+// esbuild
+conditions: ["notrace"]
+```
+
+In a build of your own from the sources, `define: { __NANOEFFECTS_TRACE__: "false" }` does the same. With the condition set, the types of that build have no `trace` option: `createBus({ trace })` is a type error, so tracing cannot be left on by mistake (`scripts/notrace-types.mjs` makes `BusOptions.trace` `never` there). `nanoeffects/trace` has no `notrace` build. The saving is about 0.4 kB gzip of the whole library.

package/package.json

@@ -1,6 +1,185 @@
 {
-  "name": "nanoeffects",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "nanoeffects",
+	"version": "0.2.0",
+	"description": "Typed event bus where every handler is a task with an AbortSignal, plus policies (latest, debounce, throttle, queue), effects (retry, timeout, poll) and tracing. About 1.2 kB gzip.",
+	"keywords": [
+		"event-bus",
+		"event-emitter",
+		"effects",
+		"abort-signal",
+		"abortcontroller",
+		"debounce",
+		"throttle",
+		"queue",
+		"retry",
+		"side-effects",
+		"typescript"
+	],
+	"license": "MIT",
+	"author": "Vladimir Yazykov <neizerth@gmail.com>",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/nanoeffects/nanoeffects.git"
+	},
+	"bugs": {
+		"url": "https://github.com/nanoeffects/nanoeffects/issues"
+	},
+	"homepage": "https://github.com/nanoeffects/nanoeffects#readme",
+	"engines": {
+		"node": ">=18"
+	},
+	"type": "module",
+	"packageManager": "pnpm@11.13.0",
+	"sideEffects": false,
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE",
+		"docs"
+	],
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"notrace": {
+				"types": "./dist/notrace/index.d.ts",
+				"default": "./dist/notrace/index.js"
+			},
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./effects": {
+			"notrace": {
+				"types": "./dist/notrace/effects.d.ts",
+				"default": "./dist/notrace/effects.js"
+			},
+			"types": "./dist/effects.d.ts",
+			"import": "./dist/effects.js"
+		},
+		"./policies": {
+			"notrace": {
+				"types": "./dist/notrace/policies.d.ts",
+				"default": "./dist/notrace/policies.js"
+			},
+			"types": "./dist/policies.d.ts",
+			"import": "./dist/policies.js"
+		},
+		"./actions": {
+			"notrace": {
+				"types": "./dist/notrace/actions.d.ts",
+				"default": "./dist/notrace/actions.js"
+			},
+			"types": "./dist/actions.d.ts",
+			"import": "./dist/actions.js"
+		},
+		"./trace": {
+			"types": "./dist/trace.d.ts",
+			"import": "./dist/trace.js"
+		},
+		"./redux": {
+			"notrace": {
+				"types": "./dist/notrace/redux.d.ts",
+				"default": "./dist/notrace/redux.js"
+			},
+			"types": "./dist/redux.d.ts",
+			"import": "./dist/redux.js"
+		},
+		"./observable": {
+			"types": "./dist/observable.d.ts",
+			"import": "./dist/observable.js"
+		},
+		"./dev": {
+			"production": {
+				"types": "./dist/dev.d.ts",
+				"default": "./dist/production/dev.js"
+			},
+			"types": "./dist/dev.d.ts",
+			"import": "./dist/dev.js"
+		}
+	},
+	"scripts": {
+		"build": "tsdown && node scripts/notrace-types.mjs",
+		"prepublishOnly": "pnpm build",
+		"check": "biome check ./src ./examples ./integration ./scripts",
+		"format": "npx @biomejs/biome check --write --unsafe ./src ./examples ./integration ./scripts",
+		"tsgo": "tsc --noEmit",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"prepare": "lefthook install",
+		"lint:package": "publint && attw --pack . --profile esm-only",
+		"size": "size-limit",
+		"verify": "pnpm tsgo && pnpm check && pnpm test && pnpm build && pnpm test:integration && pnpm smoke && pnpm lint:package && pnpm size",
+		"test:integration": "vitest run --config vitest.integration.config.ts",
+		"smoke": "node scripts/smoke.mjs && node scripts/smoke.mjs --notrace",
+		"consumer-check": "node scripts/consumer-check.mjs"
+	},
+	"devDependencies": {
+		"@arethetypeswrong/cli": "^0.18.5",
+		"@biomejs/biome": "2.5.15",
+		"@commitlint/cli": "21.2.3",
+		"@commitlint/config-conventional": "21.2.3",
+		"@reduxjs/toolkit": "^2.13.0",
+		"@size-limit/esbuild": "^14.2.0",
+		"@size-limit/file": "^14.2.0",
+		"jotai": "^3.0.1",
+		"lefthook": "2.2.1",
+		"lodash": "4.17.21",
+		"mobx": "^7.0.6",
+		"publint": "^0.3.25",
+		"redux": "^5.0.1",
+		"size-limit": "^14.2.0",
+		"tsdown": "0.23.1",
+		"typescript": "7.0.2",
+		"unplugin-unused": "^0.6.0",
+		"vite": "^8.3.4",
+		"vitest": "5.0.5",
+		"webpack": "^5.112.0",
+		"zustand": "^5.0.15"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"size-limit": [
+		{
+			"name": "createBus",
+			"path": "dist/index.js",
+			"import": "{ createBus }",
+			"limit": "1.2 kB"
+		},
+		{
+			"name": "policies (all)",
+			"path": "dist/policies.js",
+			"limit": "2.6 kB"
+		},
+		{
+			"name": "effects (all)",
+			"path": "dist/effects.js",
+			"limit": "2.3 kB"
+		},
+		{
+			"name": "actions (all)",
+			"path": "dist/actions.js",
+			"limit": "1.8 kB"
+		},
+		{
+			"name": "redux",
+			"path": "dist/redux.js",
+			"limit": "1.5 kB"
+		},
+		{
+			"name": "observable",
+			"path": "dist/observable.js",
+			"limit": "0.5 kB"
+		},
+		{
+			"name": "dev",
+			"path": "dist/dev.js",
+			"limit": "1 kB"
+		},
+		{
+			"name": "dev (production)",
+			"path": "dist/production/dev.js",
+			"limit": "100 B"
+		}
+	]
+}