@yuneta/gobj-js 7.9.6 → 7.9.10

package/README.md

@@ -598,6 +598,44 @@ a GUI route framework output — **including the automata/FSM trace, which arriv
 as `debug`** — into its own monitor window while keeping the browser console
 clean (gobj-ui's dev-window "Output" selector does exactly this).
 
+### Tracing: the `machine` trace, and the levels around it
+
+The FSM is where things happen, so the trace of the FSM **is** the execution
+log. The level model is the C kernel's — same names, same bits — so a level
+means one thing on both sides and a habit learned on a node transfers here.
+
+```javascript
+gobj_set_global_trace("machine", true)     // everything
+gobj_set_gclass_trace("C_MY_VIEW", "machine", true)
+gobj_set_gobj_trace(gobj, "ev_kw", true)   // + the kw of each event
+gobj_set_gobj_no_trace(noisy, "machine", true)   // veto, by the SOURCE gobj
+
+gobj_global_trace_level()                  // the mask in force
+gobj_trace_level(gobj)                     // global | gclass | gobj, combined
+gobj_repr_global_trace_levels()            // [{name, bit, description, set}]
+gobj_set_deep_trace(1)                     // everything, everywhere
+gobj_set_trace_machine_format(1)           // 1 = one compact line per transition
+```
+
+Levels: `machine`, `create_delete`, `create_delete2`, `subscriptions`,
+`start_stop`, `ev_kw`, `authzs`, `states`, `gbuffers`, `timer`, `fs`,
+`liburing`, `timer_periodic`, `liburing_timer`, `commands`. The ones that only
+exist on a node keep their bit rather than being dropped — removing them would
+shift every bit above and break that alignment.
+
+A gobj's effective level is the **union** of global, gclass and gobj.
+`timer` / `timer_periodic` light up for their own event only. And the veto is
+asked of the **source**, so one noisy sender can be silenced without turning
+the destination off.
+
+The trace arrives as `debug`, so **`set_log_callback()` is how you read it** —
+that is how a dev panel shows the machine inside the app, and how
+`doc.yuneta.io/navigation` feeds the panel under each of its demos.
+
+> The yuno attrs `tracing` / `trace_timer` / `trace_creation` /
+> `trace_start_stop` predate this and still work (gobj-ui's dev panel writes
+> them); they fold in as one more source of bits.
+
 ### i18n: `refresh_language` and the `data-i18n-*` family
 
 The runtime does not translate anything itself — the **app** owns the

package/dist/gobj-js.cjs.js

@@ -644,6 +644,18 @@ function gobj_set_gobj_trace(gobj, level, set) {
 	else gobj.trace_level &= ~bitmask;
 	return 0;
 }
+function gobj_set_gclass_no_trace(gclass, level, set) {
+	const gclass_ = is_string(gclass) ? gclass_find_by_name(gclass) : gclass;
+	if (!gclass_) {
+		log_error(`gobj_set_gclass_no_trace: gclass NOT FOUND: ${gclass}`);
+		return -1;
+	}
+	const bitmask = trace_bitmask(level, "gobj_set_gclass_no_trace");
+	if (!bitmask) return -1;
+	if (set) gclass_.no_trace_level |= bitmask;
+	else gclass_.no_trace_level &= ~bitmask;
+	return 0;
+}
 function gobj_set_gobj_no_trace(gobj, level, set) {
 	if (!gobj) {
 		log_error(`gobj_set_gobj_no_trace: gobj NULL`);
@@ -5381,10 +5393,22 @@ function create_template_record(template, kw) {
 *          c_timer.js
 *
 *          GClass Timer
-*          High-level, feed timers from periodic time of yuno
-*          IN SECONDS! although the parameter is in milliseconds (msec)
+*          High-level timer, fed by the browser's own timer service
 *
-*          Copyright (c) 2025, ArtGins.
+*          Don't use gobj_start()/gobj_stop(), USE set_timeout..(), clear_timeout()
+*
+*          The CONTRACT is the C one (see c_timer.h), and it is the whole
+*          public surface: set_timeout() arms, clear_timeout() disarms, and
+*          a one-shot is done once it fires. Whether the gobj is running is
+*          an INTERNAL matter of this gclass -- nobody asking for a timeout
+*          has to know it exists, and no caller should have to pair a
+*          set_timeout() with a gobj_start() to make it work.
+*
+*          What feeds the timer is the only thing that differs from C, and
+*          it is deliberately invisible from outside: there the gobj rides
+*          the yuno's one-second heartbeat, here it is a native setTimeout().
+*
+*          Copyright (c) 2025-2026, ArtGins.
 *          All Rights Reserved.
 ****************************************************************************/
 /***************************************************************
@@ -5437,6 +5461,9 @@ function mt_writing$2(gobj, path) {
 			if (priv.msec > 0) priv.timer_id = setTimeout(function() {
 				gobj_send_event(gobj, "EV_TIMEOUT", {}, gobj);
 			}, priv.msec);
+			if (priv.msec > 0) {
+				if (!gobj_is_running(gobj)) gobj_start(gobj);
+			} else if (gobj_is_running(gobj)) gobj_stop(gobj);
 			break;
 	}
 }
@@ -5466,11 +5493,15 @@ function mt_destroy$2(gobj) {}
 function ac_timeout$1(gobj, event, kw, src) {
 	let priv = gobj.priv;
 	let ev = priv.periodic ? "EV_TIMEOUT_PERIODIC" : "EV_TIMEOUT";
-	if (gobj_is_pure_child(gobj)) gobj_send_event(gobj_parent(gobj), ev, {}, gobj);
-	else gobj_publish_event(gobj, ev, {});
-	if (priv.periodic) priv.timer_id = setTimeout(function() {
+	if (priv.periodic && priv.msec > 0) priv.timer_id = setTimeout(function() {
 		gobj_send_event(gobj, "EV_TIMEOUT", {}, gobj);
 	}, priv.msec);
+	else priv.timer_id = -1;
+	if (gobj_is_pure_child(gobj)) gobj_send_event(gobj_parent(gobj), ev, {}, gobj);
+	else gobj_publish_event(gobj, ev, {});
+	if (!priv.periodic && priv.timer_id === -1) {
+		if (gobj_is_running(gobj)) gobj_stop(gobj);
+	}
 	return 0;
 }
 /***************************
@@ -6596,6 +6627,7 @@ exports.gobj_send_event = gobj_send_event;
 exports.gobj_services = gobj_services;
 exports.gobj_set_bottom_gobj = gobj_set_bottom_gobj;
 exports.gobj_set_deep_trace = gobj_set_deep_trace;
+exports.gobj_set_gclass_no_trace = gobj_set_gclass_no_trace;
 exports.gobj_set_gclass_trace = gobj_set_gclass_trace;
 exports.gobj_set_global_no_trace = gobj_set_global_no_trace;
 exports.gobj_set_global_trace = gobj_set_global_trace;