@graphrefly/graphrefly 0.9.0 → 0.11.0

package/dist/{meta-BJEU8fYz.d.cts → meta-BcuDhtwu.d.cts}

@@ -345,6 +345,12 @@ declare function advanceVersion(info: NodeVersionInfo, newValue: unknown, hashFn
 /** Type guard: is this V1 versioning info? */
 declare function isV1(info: NodeVersionInfo): info is V1;
 
+/**
+ * Branded symbol that marks a {@link CleanupResult} wrapper.
+ * Used internally by {@link cleanupResult} — prevents duck-type collisions
+ * with domain objects that happen to have a `cleanup` property.
+ */
+declare const CLEANUP_RESULT: unique symbol;
 /** Lifecycle status of a node. */
 type NodeStatus = "disconnected" | "dirty" | "settled" | "resolved" | "completed" | "errored";
 /** Callback that receives downstream message batches. */
@@ -513,6 +519,32 @@ interface Node<T = unknown> {
     /** Versioning info (GRAPHREFLY-SPEC §7). `undefined` when versioning is not enabled. */
     readonly v: Readonly<NodeVersionInfo> | undefined;
 }
+/**
+ * Explicit cleanup wrapper. When a node fn returns `{ cleanup, value? }`,
+ * `cleanup` is registered as the teardown/recompute cleanup and `value`
+ * (if present) is emitted as data. This avoids the ambiguity where returning
+ * a plain function is silently consumed as cleanup instead of emitted as data.
+ *
+ * Use the {@link cleanupResult} factory to create instances — it stamps the
+ * branded {@link CLEANUP_RESULT} symbol so that domain objects with a `cleanup`
+ * property are never misinterpreted.
+ *
+ * Plain function returns are still treated as cleanup for backward compatibility.
+ */
+type CleanupResult<T = unknown> = {
+    readonly [CLEANUP_RESULT]: true;
+    cleanup: () => void;
+    value?: T;
+};
+/**
+ * Create a branded {@link CleanupResult}.
+ *
+ * ```ts
+ * node([dep], () => cleanupResult(() => release(), computedValue))
+ * ```
+ */
+declare function cleanupResult<T>(cleanup: () => void): CleanupResult<T>;
+declare function cleanupResult<T>(cleanup: () => void, value: T): CleanupResult<T>;
 /**
  * Creates a reactive {@link Node} — the single GraphReFly primitive (GRAPHREFLY-SPEC §2).
  *
@@ -631,4 +663,4 @@ declare function metaSnapshot(node: Node): Record<string, unknown>;
  */
 declare function describeNode(node: Node, includeFields?: Set<string> | null): DescribeNodeOutput;
 
-export { policy as $, type Actor as A, createVersioning as B, COMPLETE as C, DATA as D, ERROR as E, defaultHash as F, type GuardAction as G, type HashFn as H, INVALIDATE as I, describeNode as J, isKnownMessageType as K, isPhase2Message as L, type Message as M, type Node as N, type OnMessageHandler as O, PAUSE as P, isTerminalMessage as Q, RESOLVED as R, type SubscribeHints as S, TEARDOWN as T, isV1 as U, type V0 as V, knownMessageTypes as W, messageTier as X, metaSnapshot as Y, node as Z, normalizeActor as _, type NodeOptions as a, policyFromRules as a0, propagatesToMeta as a1, resolveDescribeFields as a2, type NodeInspectorHook as a3, type NodeActions as b, type NodeFn as c, DEFAULT_ACTOR as d, DIRTY as e, type DescribeDetail as f, type DescribeField as g, type DescribeNodeOutput as h, GuardDenied as i, type GuardDeniedDetails as j, type Messages as k, type NodeDescribeKind as l, type NodeGuard as m, type NodeSink as n, type NodeStatus as o, type NodeTransportOptions as p, type NodeVersionInfo as q, type PolicyAllow as r, type PolicyDeny as s, type PolicyRuleData as t, RESUME as u, type V1 as v, type VersioningLevel as w, type VersioningOptions as x, accessHintForGuard as y, advanceVersion as z };
+export { metaSnapshot as $, type Actor as A, accessHintForGuard as B, CLEANUP_RESULT as C, DATA as D, ERROR as E, advanceVersion as F, type GuardAction as G, type HashFn as H, INVALIDATE as I, cleanupResult as J, createVersioning as K, defaultHash as L, type Message as M, type Node as N, type OnMessageHandler as O, PAUSE as P, describeNode as Q, RESOLVED as R, type SubscribeHints as S, TEARDOWN as T, isKnownMessageType as U, type V0 as V, isPhase2Message as W, isTerminalMessage as X, isV1 as Y, knownMessageTypes as Z, messageTier as _, type NodeOptions as a, node as a0, normalizeActor as a1, policy as a2, policyFromRules as a3, propagatesToMeta as a4, resolveDescribeFields as a5, type NodeInspectorHook as a6, type NodeActions as b, type NodeFn as c, COMPLETE as d, type CleanupResult as e, DEFAULT_ACTOR as f, DIRTY as g, type DescribeDetail as h, type DescribeField as i, type DescribeNodeOutput as j, GuardDenied as k, type GuardDeniedDetails as l, type Messages as m, type NodeDescribeKind as n, type NodeGuard as o, type NodeSink as p, type NodeStatus as q, type NodeTransportOptions as r, type NodeVersionInfo as s, type PolicyAllow as t, type PolicyDeny as u, type PolicyRuleData as v, RESUME as w, type V1 as x, type VersioningLevel as y, type VersioningOptions as z };

package/dist/{meta-BJEU8fYz.d.ts → meta-BcuDhtwu.d.ts}

@@ -345,6 +345,12 @@ declare function advanceVersion(info: NodeVersionInfo, newValue: unknown, hashFn
 /** Type guard: is this V1 versioning info? */
 declare function isV1(info: NodeVersionInfo): info is V1;
 
+/**
+ * Branded symbol that marks a {@link CleanupResult} wrapper.
+ * Used internally by {@link cleanupResult} — prevents duck-type collisions
+ * with domain objects that happen to have a `cleanup` property.
+ */
+declare const CLEANUP_RESULT: unique symbol;
 /** Lifecycle status of a node. */
 type NodeStatus = "disconnected" | "dirty" | "settled" | "resolved" | "completed" | "errored";
 /** Callback that receives downstream message batches. */
@@ -513,6 +519,32 @@ interface Node<T = unknown> {
     /** Versioning info (GRAPHREFLY-SPEC §7). `undefined` when versioning is not enabled. */
     readonly v: Readonly<NodeVersionInfo> | undefined;
 }
+/**
+ * Explicit cleanup wrapper. When a node fn returns `{ cleanup, value? }`,
+ * `cleanup` is registered as the teardown/recompute cleanup and `value`
+ * (if present) is emitted as data. This avoids the ambiguity where returning
+ * a plain function is silently consumed as cleanup instead of emitted as data.
+ *
+ * Use the {@link cleanupResult} factory to create instances — it stamps the
+ * branded {@link CLEANUP_RESULT} symbol so that domain objects with a `cleanup`
+ * property are never misinterpreted.
+ *
+ * Plain function returns are still treated as cleanup for backward compatibility.
+ */
+type CleanupResult<T = unknown> = {
+    readonly [CLEANUP_RESULT]: true;
+    cleanup: () => void;
+    value?: T;
+};
+/**
+ * Create a branded {@link CleanupResult}.
+ *
+ * ```ts
+ * node([dep], () => cleanupResult(() => release(), computedValue))
+ * ```
+ */
+declare function cleanupResult<T>(cleanup: () => void): CleanupResult<T>;
+declare function cleanupResult<T>(cleanup: () => void, value: T): CleanupResult<T>;
 /**
  * Creates a reactive {@link Node} — the single GraphReFly primitive (GRAPHREFLY-SPEC §2).
  *
@@ -631,4 +663,4 @@ declare function metaSnapshot(node: Node): Record<string, unknown>;
  */
 declare function describeNode(node: Node, includeFields?: Set<string> | null): DescribeNodeOutput;
 
-export { policy as $, type Actor as A, createVersioning as B, COMPLETE as C, DATA as D, ERROR as E, defaultHash as F, type GuardAction as G, type HashFn as H, INVALIDATE as I, describeNode as J, isKnownMessageType as K, isPhase2Message as L, type Message as M, type Node as N, type OnMessageHandler as O, PAUSE as P, isTerminalMessage as Q, RESOLVED as R, type SubscribeHints as S, TEARDOWN as T, isV1 as U, type V0 as V, knownMessageTypes as W, messageTier as X, metaSnapshot as Y, node as Z, normalizeActor as _, type NodeOptions as a, policyFromRules as a0, propagatesToMeta as a1, resolveDescribeFields as a2, type NodeInspectorHook as a3, type NodeActions as b, type NodeFn as c, DEFAULT_ACTOR as d, DIRTY as e, type DescribeDetail as f, type DescribeField as g, type DescribeNodeOutput as h, GuardDenied as i, type GuardDeniedDetails as j, type Messages as k, type NodeDescribeKind as l, type NodeGuard as m, type NodeSink as n, type NodeStatus as o, type NodeTransportOptions as p, type NodeVersionInfo as q, type PolicyAllow as r, type PolicyDeny as s, type PolicyRuleData as t, RESUME as u, type V1 as v, type VersioningLevel as w, type VersioningOptions as x, accessHintForGuard as y, advanceVersion as z };
+export { metaSnapshot as $, type Actor as A, accessHintForGuard as B, CLEANUP_RESULT as C, DATA as D, ERROR as E, advanceVersion as F, type GuardAction as G, type HashFn as H, INVALIDATE as I, cleanupResult as J, createVersioning as K, defaultHash as L, type Message as M, type Node as N, type OnMessageHandler as O, PAUSE as P, describeNode as Q, RESOLVED as R, type SubscribeHints as S, TEARDOWN as T, isKnownMessageType as U, type V0 as V, isPhase2Message as W, isTerminalMessage as X, isV1 as Y, knownMessageTypes as Z, messageTier as _, type NodeOptions as a, node as a0, normalizeActor as a1, policy as a2, policyFromRules as a3, propagatesToMeta as a4, resolveDescribeFields as a5, type NodeInspectorHook as a6, type NodeActions as b, type NodeFn as c, COMPLETE as d, type CleanupResult as e, DEFAULT_ACTOR as f, DIRTY as g, type DescribeDetail as h, type DescribeField as i, type DescribeNodeOutput as j, GuardDenied as k, type GuardDeniedDetails as l, type Messages as m, type NodeDescribeKind as n, type NodeGuard as o, type NodeSink as p, type NodeStatus as q, type NodeTransportOptions as r, type NodeVersionInfo as s, type PolicyAllow as t, type PolicyDeny as u, type PolicyRuleData as v, RESUME as w, type V1 as x, type VersioningLevel as y, type VersioningOptions as z };

package/dist/patterns/reactive-layout/index.cjs

@@ -548,6 +548,7 @@ function advanceVersion(info, newValue, hashFn) {
 
 // src/core/node.ts
 var NO_VALUE = /* @__PURE__ */ Symbol.for("graphrefly/NO_VALUE");
+var CLEANUP_RESULT = /* @__PURE__ */ Symbol.for("graphrefly/CLEANUP_RESULT");
 function createIntBitSet() {
   let bits = 0;
   return {
@@ -610,6 +611,7 @@ function createBitSet(size) {
 }
 var isNodeArray = (value) => Array.isArray(value);
 var isNodeOptions = (value) => typeof value === "object" && value != null && !Array.isArray(value);
+var isCleanupResult = (value) => typeof value === "object" && value !== null && CLEANUP_RESULT in value;
 var isCleanupFn = (value) => typeof value === "function";
 var statusAfterMessage = (status, msg) => {
   const t = msg[0];
@@ -1025,6 +1027,14 @@ var NodeImpl = class {
       this._lastDepValues = depValues;
       this._inspectorHook?.({ kind: "run", depValues });
       const out = this._fn(depValues, this._actions);
+      if (isCleanupResult(out)) {
+        this._cleanup = out.cleanup;
+        if (this._manualEmitUsed) return;
+        if ("value" in out) {
+          this._emitAutoValue(out.value);
+        }
+        return;
+      }
       if (isCleanupFn(out)) {
         this._cleanup = out;
         return;
@@ -1667,7 +1677,6 @@ function resolveDescribeFields(detail, fields) {
     case "full":
       return null;
     // null = include everything
-    case "minimal":
     default:
       return /* @__PURE__ */ new Set(["type", "deps"]);
   }