@hatua/log 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Gomes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Levelled, categorised diagnostics for the parts of Hatua that decide things
+ * without drawing them.
+ *
+ * The store refuses a command, narrows a publish gate, halts a save, drops a
+ * stale renewal — each for a reason it knows exactly and, until now, kept. What
+ * reaches a screen is the outcome; what is worth having while something is
+ * being worked on is the reasoning that led there, in order, with what it was
+ * looking at.
+ *
+ * ## Silent unless asked
+ *
+ * Hatua renders inside somebody else's product. A library that writes `info` to
+ * a Host's console by default is one every integrator has to go and turn off,
+ * and one whose noise buries their own logs — so nothing below `warn` is
+ * written until a caller asks for it. `warn` and `error` are always through,
+ * because a Host that has wired something wrongly should hear about it without
+ * having to opt in.
+ *
+ * ## Categories are packages
+ *
+ * A category names where the line came from — `services.editing`,
+ * `react.fields` — so a level can be turned up for the thing being chased
+ * without turning it up for everything. Dotted, and matched by prefix:
+ * `services` covers `services.editing`, and `*` covers everything.
+ */
+export type Level = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+/**
+ * What a line is handed to.
+ *
+ * A seam rather than a hard-wired `console`, because a Host that already has
+ * somewhere for diagnostics to go should not have Hatua's arriving somewhere
+ * else — and because a test that asserts what was logged should not have to
+ * read the terminal to do it.
+ */
+export type Sink = (line: Line) => void;
+export interface Line {
+    level: Level;
+    /** Where it came from, dotted: `services.editing`. */
+    category: string;
+    message: string;
+    /** Whatever the call site was looking at when it decided. */
+    detail?: Record<string, unknown>;
+}
+export interface LogConfig {
+    /**
+     * The level a category is written at, by prefix. The longest matching prefix
+     * wins, so `{ '*': 'warn', 'services.editing': 'trace' }` says what it looks
+     * like it says.
+     */
+    levels?: Record<string, Level>;
+    sink?: Sink;
+}
+/**
+ * The settings, held on the global rather than in this module.
+ *
+ * A module holds its state once per instance, and there is no promise that this
+ * module is instantiated once. A dev server resolving symlinked workspace
+ * packages, a Host bundling `@hatua/react` while its own code imports
+ * `@hatua/log`, two copies at different versions in one tree — each gives the
+ * app one table and the packages another, so turning a category up changes a
+ * table nothing reads and the switch appears to do nothing at all.
+ *
+ * A symbol on `globalThis` is the one place every instance can agree on. It is
+ * what the settings are ABOUT — one page, one answer to "what is Hatua writing"
+ * — so sharing them there is the shape of the thing rather than a workaround
+ * for the bundler.
+ */
+interface Settings {
+    levels: Record<string, Level>;
+    sink: Sink;
+}
+/**
+ * Turn categories up or down, or send lines somewhere else.
+ *
+ * Merged into what is already set rather than replacing it, so turning one
+ * category up does not silently reset the rest. Returns what is in force, so a
+ * console can show whether the call took.
+ */
+export declare function configureLogging(config: LogConfig): Readonly<Settings>;
+/**
+ * Turn a level on from code, in one line, with the spec a person types.
+ *
+ * What a `console.log` used to be for. Chasing something means putting a line
+ * where the question is, and going through `configureLogging({ levels: … })`
+ * asks for two imports and a nested object at the moment attention is
+ * elsewhere — so this is the form that gets pasted at the top of a file and
+ * deleted an hour later.
+ *
+ *   import { setLogLevel } from '@hatua/log'
+ *   setLogLevel('*:debug')
+ *
+ * It complains rather than doing nothing when the spec is unusable, because a
+ * diagnostic switch that fails silently is worse than none: the silence reads
+ * as "nothing is happening" when it means "nothing was turned on".
+ */
+export declare function setLogLevel(spec: string): Readonly<Settings>;
+/** Back to silent-unless-asked, and back to the console. What a test resets to. */
+export declare function resetLogging(): void;
+/**
+ * Levels from a short string: `*:debug`, `services.editing:trace,react:debug`.
+ *
+ * Here rather than in whatever is calling it because it is the form a person
+ * types under time pressure — into a console, into a query string, into an
+ * environment variable — and every one of those callers would otherwise write
+ * its own splitter and get a different one wrong.
+ *
+ * A bare level with no category means everything: `debug` is `*:debug`.
+ */
+export declare function levelsFrom(spec: string): Record<string, Level>;
+export interface Logger {
+    error(message: string, detail?: Record<string, unknown>): void;
+    warn(message: string, detail?: Record<string, unknown>): void;
+    info(message: string, detail?: Record<string, unknown>): void;
+    debug(message: string, detail?: Record<string, unknown>): void;
+    trace(message: string, detail?: Record<string, unknown>): void;
+    /** Whether a line at this level would be written, for a caller with work to do to build one. */
+    enabled(level: Level): boolean;
+}
+/**
+ * A logger for one category.
+ *
+ * Held at module scope by its caller — the category is a fact about the file,
+ * not about the call — and it reads the configuration at write time, so turning
+ * a category up affects loggers already made.
+ */
+export declare function logger(category: string): Logger;
+export {};

package/dist/index.js

@@ -0,0 +1,82 @@
+//#region src/index.ts
+var e = {
+	error: 0,
+	warn: 1,
+	info: 2,
+	debug: 3,
+	trace: 4
+}, t = { "*": "warn" }, n = {
+	error: "#e5484d",
+	warn: "#d9a300",
+	info: "#8b8b8b",
+	debug: "#8b8b8b",
+	trace: "#8b8b8b"
+}, r = typeof window < "u", i = ({ level: e, category: t, message: i, detail: a }) => {
+	let o = e === "error" ? console.error : e === "warn" ? console.warn : console.log, s = `[${e.toUpperCase()}][${t}]`;
+	if (!r) {
+		let e = `${s} ${i}`;
+		a === void 0 ? o(e) : o(e, a);
+		return;
+	}
+	let c = `%c${s}%c ${i}`, l = `color:${n[e]};font-weight:bold`, u = `color:${n[e]};font-weight:normal`;
+	a === void 0 ? o(c, l, u) : o(c, l, u, a);
+}, a = Symbol.for("hatua.log.settings"), o = globalThis, s = () => (o[a] ??= {
+	levels: { ...t },
+	sink: i
+}, o[a]);
+function c(e) {
+	let t = s();
+	return e.levels && (t.levels = {
+		...t.levels,
+		...e.levels
+	}), e.sink && (t.sink = e.sink), {
+		levels: { ...t.levels },
+		sink: t.sink
+	};
+}
+function l(e) {
+	let t = f(e);
+	return Object.keys(t).length === 0 && console.warn(`[hatua] nothing usable in the log level "${e}". Try '*:debug'.`), c({ levels: t });
+}
+function u() {
+	o[a] = {
+		levels: { ...t },
+		sink: i
+	};
+}
+var d = (e) => {
+	let { levels: t } = s(), n = t["*"] ?? "warn", r = -1;
+	for (let [i, a] of Object.entries(t)) i !== "*" && (e === i || e.startsWith(`${i}.`)) && i.length > r && (r = i.length, n = a);
+	return n;
+};
+function f(e) {
+	let t = {};
+	for (let n of e.split(",")) {
+		let e = n.trim();
+		if (!e) continue;
+		let r = e.lastIndexOf(":"), i = r < 0 ? "*" : e.slice(0, r).trim(), a = (r < 0 ? e : e.slice(r + 1)).trim();
+		p(a) && (t[i || "*"] = a);
+	}
+	return t;
+}
+var p = (t) => t in e;
+function m(t) {
+	let n = (n, r, i) => {
+		e[n] > e[d(t)] || s().sink({
+			level: n,
+			category: t,
+			message: r,
+			...i === void 0 ? {} : { detail: i }
+		});
+	};
+	return {
+		error: (e, t) => n("error", e, t),
+		warn: (e, t) => n("warn", e, t),
+		info: (e, t) => n("info", e, t),
+		debug: (e, t) => n("debug", e, t),
+		trace: (e, t) => n("trace", e, t),
+		enabled: (n) => e[n] <= e[d(t)]
+	};
+}
+//#endregion
+export { c as configureLogging, f as levelsFrom, m as logger, u as resetLogging, l as setLogLevel };

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,17 +1,31 @@
 {
   "name": "@hatua/log",
-  "version": "0.0.0",
-  "description": "Placeholder reserving the name. Nothing is published here; see 0.1.0 and later.",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Internal to @hatua/react — published because it is an external of its build, not a supported API. Levelled, categorised diagnostics — silent unless a Host asks.",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pedromvgomes/hatua.git",
     "directory": "source/packages/log"
   },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary --coverage.reporter=lcovonly"
+  }
 }

package/README.md

@@ -1,5 +0,0 @@
-# @hatua/log
-
-This version reserves the package name and contains no code.
-
-Install `0.1.0` or later.