@directive-run/core 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -1275,8 +1275,12 @@ interface CreateDerivationsOptions<S extends Schema, D extends DerivationsDef<S>
  * Notifications are deferred during invalidation so listeners always see
  * consistent state across multiple simultaneous fact changes.
  *
- * @param options - Derivation definitions, facts proxy, store, and optional lifecycle callbacks
- * @returns A `DerivationsManager` with get/invalidate/subscribe/getProxy methods
+ * @param options - Derivation definitions, facts proxy, store, and optional
+ *   lifecycle callbacks.
+ * @returns A {@link DerivationsManager} for accessing, invalidating, and
+ *   subscribing to derived values.
+ *
+ * @internal
  */
 declare function createDerivationsManager<S extends Schema, D extends DerivationsDef<S>>(options: CreateDerivationsOptions<S, D>): DerivationsManager<S, D>;
 
@@ -2226,16 +2230,34 @@ declare function createEngine<S extends Schema>(config: SystemConfig<any>): Syst
 
 /**
  * Get the current tracking context.
- * Returns null context if no tracking is active.
+ *
+ * @returns The active {@link TrackingContext}, or a null context (no-op) if
+ *   no tracking is active.
+ *
+ * @internal
  */
 declare function getCurrentTracker(): TrackingContext;
 /**
- * Check if we're currently tracking dependencies.
+ * Check if dependency tracking is currently active.
+ *
+ * @returns `true` if inside a {@link withTracking} call, `false` otherwise.
+ *
+ * @internal
  */
 declare function isTracking(): boolean;
 /**
  * Run a function with dependency tracking.
- * Returns the computed value and the set of dependencies accessed.
+ *
+ * @remarks
+ * Pushes a fresh tracking context onto the stack, executes `fn`, then pops
+ * the context. Any fact reads inside `fn` are recorded as dependencies.
+ * Nesting is supported — inner calls get their own independent context.
+ *
+ * @param fn - The function to execute under tracking.
+ * @returns An object with the computed `value` and a `deps` Set of accessed
+ *   fact keys.
+ *
+ * @internal
  */
 declare function withTracking<T>(fn: () => T): {
     value: T;
@@ -2243,12 +2265,28 @@ declare function withTracking<T>(fn: () => T): {
 };
 /**
  * Run a function without tracking.
- * Useful for reading facts without creating dependencies.
+ *
+ * @remarks
+ * Temporarily clears the tracking stack so that fact reads inside `fn` do
+ * not register as dependencies. The stack is restored after `fn` returns
+ * (even on error). Useful for side-effect reads that should not trigger
+ * derivation invalidation.
+ *
+ * @param fn - The function to execute without tracking.
+ * @returns The return value of `fn`.
+ *
+ * @internal
  */
 declare function withoutTracking<T>(fn: () => T): T;
 /**
  * Track a specific key in the current context.
- * No-op if not currently tracking.
+ *
+ * @remarks
+ * No-op if no tracking context is active.
+ *
+ * @param key - The fact key to record as a dependency.
+ *
+ * @internal
  */
 declare function trackAccess(key: string): void;
 

package/dist/index.d.ts

@@ -1275,8 +1275,12 @@ interface CreateDerivationsOptions<S extends Schema, D extends DerivationsDef<S>
  * Notifications are deferred during invalidation so listeners always see
  * consistent state across multiple simultaneous fact changes.
  *
- * @param options - Derivation definitions, facts proxy, store, and optional lifecycle callbacks
- * @returns A `DerivationsManager` with get/invalidate/subscribe/getProxy methods
+ * @param options - Derivation definitions, facts proxy, store, and optional
+ *   lifecycle callbacks.
+ * @returns A {@link DerivationsManager} for accessing, invalidating, and
+ *   subscribing to derived values.
+ *
+ * @internal
  */
 declare function createDerivationsManager<S extends Schema, D extends DerivationsDef<S>>(options: CreateDerivationsOptions<S, D>): DerivationsManager<S, D>;
 
@@ -2226,16 +2230,34 @@ declare function createEngine<S extends Schema>(config: SystemConfig<any>): Syst
 
 /**
  * Get the current tracking context.
- * Returns null context if no tracking is active.
+ *
+ * @returns The active {@link TrackingContext}, or a null context (no-op) if
+ *   no tracking is active.
+ *
+ * @internal
  */
 declare function getCurrentTracker(): TrackingContext;
 /**
- * Check if we're currently tracking dependencies.
+ * Check if dependency tracking is currently active.
+ *
+ * @returns `true` if inside a {@link withTracking} call, `false` otherwise.
+ *
+ * @internal
  */
 declare function isTracking(): boolean;
 /**
  * Run a function with dependency tracking.
- * Returns the computed value and the set of dependencies accessed.
+ *
+ * @remarks
+ * Pushes a fresh tracking context onto the stack, executes `fn`, then pops
+ * the context. Any fact reads inside `fn` are recorded as dependencies.
+ * Nesting is supported — inner calls get their own independent context.
+ *
+ * @param fn - The function to execute under tracking.
+ * @returns An object with the computed `value` and a `deps` Set of accessed
+ *   fact keys.
+ *
+ * @internal
  */
 declare function withTracking<T>(fn: () => T): {
     value: T;
@@ -2243,12 +2265,28 @@ declare function withTracking<T>(fn: () => T): {
 };
 /**
  * Run a function without tracking.
- * Useful for reading facts without creating dependencies.
+ *
+ * @remarks
+ * Temporarily clears the tracking stack so that fact reads inside `fn` do
+ * not register as dependencies. The stack is restored after `fn` returns
+ * (even on error). Useful for side-effect reads that should not trigger
+ * derivation invalidation.
+ *
+ * @param fn - The function to execute without tracking.
+ * @returns The return value of `fn`.
+ *
+ * @internal
  */
 declare function withoutTracking<T>(fn: () => T): T;
 /**
  * Track a specific key in the current context.
- * No-op if not currently tracking.
+ *
+ * @remarks
+ * No-op if no tracking context is active.
+ *
+ * @param key - The fact key to record as a dependency.
+ *
+ * @internal
  */
 declare function trackAccess(key: string): void;