@asaidimu/utils-artifacts 8.1.1 → 8.1.2

package/index.d.mts

@@ -85,6 +85,17 @@ interface ReactiveSelector<S> {
      */
     subscribe: (callback: (state: S) => void) => () => void;
 }
+interface ActionWatcher {
+    /** Unique identifier for the action */
+    name: string;
+    /** Function to get the current computed value of the action. */
+    status: () => boolean;
+    /**
+     * Subscribes a callback function to run whenever the action's status changes.
+     * Returns an unsubscribe function.
+     */
+    subscribe: (callback: () => void) => () => void;
+}
 /**
  * Interface defining the contract for the core data state store.
  * T must be an object type.
@@ -139,6 +150,28 @@ interface DataStore<T extends object> {
      * @returns An unsubscribe function.
      */
     watch(path: string | Array<string>, callback: (state: T) => void): () => void;
+    /**
+     * Subscribes to execution‑status changes of a registered action.
+     *
+     * The provided callback is called **every time** the action transitions
+     * between idle and running (i.e. on `action:start`, `action:complete`, or
+     * `action:error` for the given name). The current status can also be read
+     * synchronously with `isActionRunning(name)`.
+     *
+     * **Deferred listener teardown**
+     * To avoid unnecessary churn when subscriptions are rapidly created and
+     * destroyed, the underlying event listeners are not removed immediately
+     * on unsubscribe. Instead, a *pending reset* is queued via `queueMicrotask`.
+     * If a new subscription for the same action arrives before that microtask
+     * executes, the reset is silently cancelled and the already‑established
+     * listeners are reused. This keeps the subscription infrastructure stable
+     * and prevents cascading notifications that could otherwise arise from
+     * repeated subscribe‑unsubscribe‑subscribe cycles.
+     *
+     * @param name - The name of the action to watch.
+     * @returns An ActionWatcher
+     */
+    watchAction(name: string): ActionWatcher;
     /**
      * Executes an operation function within a transaction block.
      * All state updates (`set` or actions) within the transaction are batched and applied atomically (all or nothing).
@@ -326,7 +359,7 @@ type ArtifactStreamContext<TState, TArtifact> = {
  * @template TState The type of the global state managed by the DataStore.
  * @template TArtifact The type of the artifact being created by the factory.
  */
-interface ArtifactFactoryContext<TRegistry extends Record<string, any>, TState extends object, TArtifact> {
+type ArtifactFactoryContext<TRegistry extends Record<string, any>, TState extends object, TArtifact, TExtra extends Record<string, any> = {}> = TExtra & {
     /**
      * Returns the current global state object. This is a non-reactive read;
      * changes to the state will not automatically invalidate the artifact
@@ -379,7 +412,7 @@ interface ArtifactFactoryContext<TRegistry extends Record<string, any>, TState e
      * An AbortSignal that indicates if the artifacts has been unregistered
      */
     signal: AbortSignal;
-}
+};
 /**
  * A function that performs cleanup or disposal logic for an artifact, potentially asynchronously.
  * Used for `onCleanup` and `onDispose` callbacks.
@@ -463,7 +496,7 @@ type KeyedResolvedArtifact<TRegistry, K extends keyof TRegistry> = ResolvedArtif
  * @param context The context for creating the artifact.
  * @returns The artifact instance or a Promise resolving to it.
  */
-type ArtifactFactory<TRegistry extends Record<string, any>, TState extends object, TArtifact> = (context: ArtifactFactoryContext<TRegistry, TState, TArtifact>) => TArtifact | Promise<TArtifact>;
+type ArtifactFactory<TRegistry extends Record<string, any>, TState extends object, TArtifact, TExtra extends Record<string, any> = {}> = (context: ArtifactFactoryContext<TRegistry, TState, TArtifact, TExtra>) => TArtifact | Promise<TArtifact>;
 type ArtifactInstance<R> = R extends PromiseLike<infer T> ? T : R;
 /**
  * An interface for observing changes to an artifact without direct resolution,
@@ -511,11 +544,11 @@ interface ArtifactObserver<TRegistry, K extends keyof TRegistry> {
  * @template TArtifact The resolved type of the artifact instance.
  * @template TRegistry The type mapping of all artifacts in the container.
  */
-interface ArtifactTemplate<TState extends object, TArtifact, TRegistry extends object = any> {
+interface ArtifactTemplate<TState extends object, TArtifact, TRegistry extends object = any, TExtra extends Record<string, any> = {}> {
     /** The unique key identifying this artifact within the registry. */
     key: keyof TRegistry;
     /** The factory function responsible for creating the artifact's instance. */
-    factory: ArtifactFactory<TRegistry, TState, TArtifact>;
+    factory: ArtifactFactory<TRegistry, TState, TArtifact, TExtra>;
     /**
      * The scope of the artifact, determining its lifecycle and sharing strategy.
      * Defaults to `ArtifactScopes.Singleton`.
@@ -581,7 +614,7 @@ type ArtifactTemplateMap<TState extends object, TRegistry extends Record<string,
  * @template T The type that contains a factory property.
  */
 type ArtifactValue<T> = T extends {
-    factory: ArtifactFactory<any, any, infer TArtifact>;
+    factory: (...args: any[]) => infer TArtifact;
 } ? TArtifact : never;
 /**
  * Infers the complete Artifact Registry type from a map of artifact configuration objects.
@@ -592,7 +625,7 @@ type ArtifactValue<T> = T extends {
  * @template T A map where keys are artifact names and values are their configurations.
  */
 type InferRegistry<T extends Record<string, {
-    factory: ArtifactFactory<any, any, any>;
+    factory: (...args: any[]) => any;
     [key: string]: any;
 }>> = {
     [K in keyof T]: ArtifactValue<T[K]>;

package/index.d.ts

@@ -85,6 +85,17 @@ interface ReactiveSelector<S> {
      */
     subscribe: (callback: (state: S) => void) => () => void;
 }
+interface ActionWatcher {
+    /** Unique identifier for the action */
+    name: string;
+    /** Function to get the current computed value of the action. */
+    status: () => boolean;
+    /**
+     * Subscribes a callback function to run whenever the action's status changes.
+     * Returns an unsubscribe function.
+     */
+    subscribe: (callback: () => void) => () => void;
+}
 /**
  * Interface defining the contract for the core data state store.
  * T must be an object type.
@@ -139,6 +150,28 @@ interface DataStore<T extends object> {
      * @returns An unsubscribe function.
      */
     watch(path: string | Array<string>, callback: (state: T) => void): () => void;
+    /**
+     * Subscribes to execution‑status changes of a registered action.
+     *
+     * The provided callback is called **every time** the action transitions
+     * between idle and running (i.e. on `action:start`, `action:complete`, or
+     * `action:error` for the given name). The current status can also be read
+     * synchronously with `isActionRunning(name)`.
+     *
+     * **Deferred listener teardown**
+     * To avoid unnecessary churn when subscriptions are rapidly created and
+     * destroyed, the underlying event listeners are not removed immediately
+     * on unsubscribe. Instead, a *pending reset* is queued via `queueMicrotask`.
+     * If a new subscription for the same action arrives before that microtask
+     * executes, the reset is silently cancelled and the already‑established
+     * listeners are reused. This keeps the subscription infrastructure stable
+     * and prevents cascading notifications that could otherwise arise from
+     * repeated subscribe‑unsubscribe‑subscribe cycles.
+     *
+     * @param name - The name of the action to watch.
+     * @returns An ActionWatcher
+     */
+    watchAction(name: string): ActionWatcher;
     /**
      * Executes an operation function within a transaction block.
      * All state updates (`set` or actions) within the transaction are batched and applied atomically (all or nothing).
@@ -326,7 +359,7 @@ type ArtifactStreamContext<TState, TArtifact> = {
  * @template TState The type of the global state managed by the DataStore.
  * @template TArtifact The type of the artifact being created by the factory.
  */
-interface ArtifactFactoryContext<TRegistry extends Record<string, any>, TState extends object, TArtifact> {
+type ArtifactFactoryContext<TRegistry extends Record<string, any>, TState extends object, TArtifact, TExtra extends Record<string, any> = {}> = TExtra & {
     /**
      * Returns the current global state object. This is a non-reactive read;
      * changes to the state will not automatically invalidate the artifact
@@ -379,7 +412,7 @@ interface ArtifactFactoryContext<TRegistry extends Record<string, any>, TState e
      * An AbortSignal that indicates if the artifacts has been unregistered
      */
     signal: AbortSignal;
-}
+};
 /**
  * A function that performs cleanup or disposal logic for an artifact, potentially asynchronously.
  * Used for `onCleanup` and `onDispose` callbacks.
@@ -463,7 +496,7 @@ type KeyedResolvedArtifact<TRegistry, K extends keyof TRegistry> = ResolvedArtif
  * @param context The context for creating the artifact.
  * @returns The artifact instance or a Promise resolving to it.
  */
-type ArtifactFactory<TRegistry extends Record<string, any>, TState extends object, TArtifact> = (context: ArtifactFactoryContext<TRegistry, TState, TArtifact>) => TArtifact | Promise<TArtifact>;
+type ArtifactFactory<TRegistry extends Record<string, any>, TState extends object, TArtifact, TExtra extends Record<string, any> = {}> = (context: ArtifactFactoryContext<TRegistry, TState, TArtifact, TExtra>) => TArtifact | Promise<TArtifact>;
 type ArtifactInstance<R> = R extends PromiseLike<infer T> ? T : R;
 /**
  * An interface for observing changes to an artifact without direct resolution,
@@ -511,11 +544,11 @@ interface ArtifactObserver<TRegistry, K extends keyof TRegistry> {
  * @template TArtifact The resolved type of the artifact instance.
  * @template TRegistry The type mapping of all artifacts in the container.
  */
-interface ArtifactTemplate<TState extends object, TArtifact, TRegistry extends object = any> {
+interface ArtifactTemplate<TState extends object, TArtifact, TRegistry extends object = any, TExtra extends Record<string, any> = {}> {
     /** The unique key identifying this artifact within the registry. */
     key: keyof TRegistry;
     /** The factory function responsible for creating the artifact's instance. */
-    factory: ArtifactFactory<TRegistry, TState, TArtifact>;
+    factory: ArtifactFactory<TRegistry, TState, TArtifact, TExtra>;
     /**
      * The scope of the artifact, determining its lifecycle and sharing strategy.
      * Defaults to `ArtifactScopes.Singleton`.
@@ -581,7 +614,7 @@ type ArtifactTemplateMap<TState extends object, TRegistry extends Record<string,
  * @template T The type that contains a factory property.
  */
 type ArtifactValue<T> = T extends {
-    factory: ArtifactFactory<any, any, infer TArtifact>;
+    factory: (...args: any[]) => infer TArtifact;
 } ? TArtifact : never;
 /**
  * Infers the complete Artifact Registry type from a map of artifact configuration objects.
@@ -592,7 +625,7 @@ type ArtifactValue<T> = T extends {
  * @template T A map where keys are artifact names and values are their configurations.
  */
 type InferRegistry<T extends Record<string, {
-    factory: ArtifactFactory<any, any, any>;
+    factory: (...args: any[]) => any;
     [key: string]: any;
 }>> = {
     [K in keyof T]: ArtifactValue<T[K]>;

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@asaidimu/utils-artifacts",
-  "version": "8.1.1",
+  "version": "8.1.2",
   "description": "Reactive artifact container.",
   "main": "index.js",
   "module": "index.mjs",
   "types": "index.d.ts",
   "dependencies": {
-    "@asaidimu/utils-events": "^1.1.0"
+    "@asaidimu/utils-events": "1.1.0"
   },
   "keywords": [
     "typescript",