@asaidimu/utils-artifacts 8.2.11 → 8.2.12

package/index.d.cts

@@ -0,0 +1,1037 @@
+//#region src/error/error.d.ts
+/**
+ * Severity levels for structured issues and errors.
+ */
+type Severity = "error" | "warning" | "info";
+/**
+ * Represents a detailed validation or operational problem.
+ * Designed to be machine-readable while remaining human-friendly.
+ */
+interface Issue {
+  /** Machine-readable identifier (e.g., `"REQUIRED_FIELD_MISSING"`). */
+  readonly code: string;
+  /** Human-readable description of the problem. */
+  readonly message: string;
+  /** Field path in a document or state (e.g., `"users.0.email"`). */
+  readonly path?: string;
+  /** Optional array index when the issue relates to a specific element. */
+  readonly index?: number;
+  /** Seriousness of the issue. Defaults to `"error"`. */
+  readonly severity?: Severity;
+  /** Optional detailed explanation, can be multi-line. */
+  readonly description?: string;
+  /** Nested issues that caused this one. */
+  readonly cause?: readonly Issue[];
+}
+/**
+ * Standardized error code format: `CATEGORY-XXX[-SUFFIX]`
+ *
+ * @example
+ * ```typescript
+ * // VAL-001 (Validation: required field missing)
+ * // DB-001-NF (Database: not found)
+ * // AUTH-001-DENIED (Auth: permission denied)
+ * ```
+ */
+interface ErrorCodeMetadata {
+  /** The formal unique error code identifier (e.g., `"VAL-001"`). */
+  readonly code: string;
+  /** Human-readable uppercase name for the error type (e.g., `"VALIDATION_FAILED"`). */
+  readonly name: string;
+  /** Detailed description of when and why this error occurs. */
+  readonly description: string;
+  /** Suggested immediate action for engineers or systems to handle or resolve the error. */
+  readonly action?: string;
+  /** HTTP status code mapping for upstream REST APIs (e.g., `404`, `500`). */
+  readonly httpStatus?: number;
+  /** Operational category this error belongs to. */
+  readonly category: ErrorCategory;
+  /** Recommended logging level threshold (`"debug" | "info" | "warn" | "error"`). */
+  readonly logLevel?: "debug" | "info" | "warn" | "error";
+}
+/**
+ * Categories classifying the origin and nature of an error.
+ */
+type ErrorCategory = "validation" | "database" | "auth" | "business" | "system" | "network" | "concurrency" | "custom";
+/**
+ * Configuration options container used when constructing a new `SystemError`.
+ */
+interface SystemErrorParams {
+  /** The unique registered error code identifier (e.g., `ErrorCodes.INTERNAL_ERROR.code`). */
+  code: string;
+  /** Explicit error message overrides. If omitted, defaults to the error code's description. */
+  message?: string;
+  /** Operational severity tier. Defaults to `"error"`. */
+  severity?: Severity;
+  /** State path or key where the operational failure occurred (e.g., `"users.0.email"`). */
+  path?: string;
+  /** The function block, track component, or routing process executing during failure. */
+  operation?: string;
+  /** Flat array of precise granular input issues or schema violations. */
+  issues?: readonly Issue[];
+  /** The underlying trigger cause. Accepts native `Error` instances, custom errors, or concurrent `Error[]` arrays. */
+  cause?: unknown | unknown[];
+  /** Ad-hoc modifications overriding base properties mapped from the code registry. */
+  metadata?: Partial<Omit<ErrorCodeMetadata, "code" | "category">>;
+}
+/**
+ * Primary domain operational error wrapper.
+ * Unfolds historical deep error hierarchies into flat, parallel-aware trace timelines.
+ */
+declare class SystemError extends Error {
+  /** The associated error identifier code (e.g., `"SYS-001"`). */
+  readonly code: string;
+  /** Static documentation mapping and registration rules bound to this code type. */
+  readonly codeMetadata: ErrorCodeMetadata;
+  /** Severity tier grading the operational consequence of this failure. */
+  readonly severity: Severity;
+  /** Target state or document path where processing failed. */
+  readonly path?: string;
+  /** Active system segment, workflow node, or function context executing during failure. */
+  readonly operation?: string;
+  /** Detailed sub-layer list representing structural data validation failures. */
+  readonly issues: readonly Issue[];
+  /** Raw backing trigger, array of concurrent branches, or source error instance. */
+  readonly cause?: unknown | unknown[];
+  /** Exact moment this error was instantiated (ISO string). */
+  readonly timestamp: string;
+  /**
+   * Instantiate a structurally traceable `SystemError`.
+   * @param params - Configuration parameters outlining the error's state context.
+   */
+  constructor(params: SystemErrorParams);
+  /**
+   * Generates a separate immutable clone assigning a target file, state, or field path.
+   */
+  withPath(path: string): SystemError;
+  /**
+   * Generates a separate immutable clone assigning a specific execution block or track tracking context.
+   */
+  withOperation(operation: string): SystemError;
+  /**
+   * Appends an operational validation structural issue to a fresh clone of this error.
+   */
+  withIssue(issue: Issue): SystemError;
+  /**
+   * Appends multiple validation issues onto a fresh clone of this error instance.
+   */
+  withIssues(issues: readonly Issue[]): SystemError;
+  /**
+   * Maps a backing raw trigger or concurrent array tracking set to a fresh clone of this error instance.
+   */
+  withCause(cause: unknown | unknown[]): SystemError;
+  /**
+   * Retrieves the recommended HTTP Status code mapped to this error's code metadata registry.
+   */
+  getHttpStatus(): number | undefined;
+  /**
+   * Unrolls execution hierarchies chronologically, isolating parallel pipelines into clear trace frames.
+   * Always returns an array of trace nodes.
+   */
+  private extractChronologicalTrace;
+  /**
+   * Transforms the error payload into a flattened transmission format.
+   * Strips recursive depth in favor of an array-mapped chronological failure `trace`.
+   */
+  toJSON(): Record<string, unknown>;
+  /**
+   * Generates a flat payload matching `toJSON` format requirements for centralized platform ingestion engines.
+   */
+  toLogEntry(): Record<string, unknown>;
+  /**
+   * Terminal terminal dump representation formatting details cleanly into plain strings.
+   */
+  toString(): string;
+}
+//#endregion
+//#region src/events/types.d.ts
+/**
+ * Interface defining the shape of the EventBus.
+ * @template TEventMap - A record mapping event names to their respective payload types.
+ */
+interface EventBus<TEventMap extends Record<string, any>> {
+  /**
+   * Subscribes to a specific event by name.
+   * @param eventName - The name of the event to subscribe to.
+   * @param callback - The function to call when the event is emitted.
+   * @param options -  Extra options to determine the behaviour of the
+   * subscription
+   * @returns A function to unsubscribe from the event.
+   */
+  subscribe<TEventName extends keyof TEventMap | "*">(eventName: TEventName, callback: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => void;
+  /**
+   * Subscribes to an event and automatically unsubscribes after it fires once.
+   * @param eventName - The name of the event to subscribe to.
+   * @param callback - The function to call when the event is emitted.
+   * @returns A function to cancel the one-shot subscription before it fires.
+   */
+  once<TEventName extends keyof TEventMap | "*">(eventName: TEventName, callback: TEventName extends "*" ? (payload: TEventMap[keyof TEventMap], event: keyof TEventMap) => void : (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions): () => void;
+  /**
+   * Emits an event with a payload to all subscribed listeners.
+   * @param event - An object containing the event name and payload.
+   */
+  emit: <TEventName extends keyof TEventMap>(event: {
+    name: TEventName;
+    payload: TEventMap[TEventName];
+  }) => void;
+  /**
+   * Retrieves metrics about event bus usage.
+   * @returns An object containing various metrics.
+   */
+  metrics: () => EventMetrics;
+  /**
+   * Clears all subscriptions and resets metrics.
+   *
+   * After calling `clear()`, the bus is fully reset and can be reused
+   * cross-tab communication is re-established if it was previously enabled.
+   *
+   * @param options - Optional configuration object.
+   * @param options.permanent - If `true`, the bus becomes permanently unusable after clearing.
+   *                            Defaults to `false`.
+   * @returns {void}
+   */
+  clear: (options?: {
+    permanent?: boolean;
+  }) => void;
+}
+/**
+ * Interface defining the metrics tracked by the EventBus.
+ */
+interface EventMetrics {
+  /** Total number of events emitted (both sync and deferred paths). */
+  totalEvents: number;
+  /** Number of active subscriptions across all event names. */
+  activeSubscriptions: number;
+  /** Map of event names to their emission counts. */
+  eventCounts: Map<string, number>;
+  /** Average duration of event dispatch in milliseconds. */
+  averageEmitDuration: number;
+}
+interface SubscribeOptions {
+  /**
+   * Debounce delay in milliseconds. When multiple events arrive in quick
+   * succession, the callback runs only after the quiet period ends, using the
+   * latest payload. Default = no debouncing.
+   */
+  debounce?: number;
+}
+//#endregion
+//#region src/store/types.d.ts
+/**
+ * Utility type for representing partial updates to the state, allowing deep nesting.
+ * It makes all properties optional and applies the same transformation recursively
+ * to nested objects, allowing for selective updates while
+ * preserving the original structure. It also includes the original type T and
+ * undefined as possibilities for the top level and nested values.
+ */
+type DeepPartial<T> = T extends object ? T extends readonly (infer U)[] ? readonly (DeepPartial<U> | undefined)[] | undefined | T : T extends (infer U)[] ? (DeepPartial<U> | undefined)[] | undefined | T : { [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> | undefined : T[K] | undefined } | undefined | T : T | undefined | symbol;
+/**
+ * Extended store state for monitoring the current execution status (e.g., if an update is in progress).
+ */
+interface StoreExecutionState<T> {
+  /** Indicates if a state update process is currently executing. */
+  executing: boolean;
+  /** The changes (DeepPartial) currently being processed in the execution cycle. Null if none. */
+  changes: DeepPartial<T> | null;
+  /** A queue of pending state update functions/objects to be applied sequentially. */
+  pendingChanges: Array<StateUpdater<T>>;
+  /** Names of all currently registered middlewares. */
+  middlewares: string[];
+  /** Details of the middleware currently running. Null if none. */
+  runningMiddleware: {
+    id: string;
+    name: string;
+    startTime: number;
+  } | null;
+  /** Indicates if the store is currently within an active transaction block. */
+  transactionActive: boolean;
+}
+/**
+ * Event types emitted by the state store for observability and debugging.
+ */
+type StoreEvent = "update:start" | "update:complete" | "middleware:start" | "middleware:complete" | "middleware:error" | "middleware:blocked" | "middleware:executed" | "transaction:start" | "transaction:complete" | "transaction:error" | "persistence:ready" | "persistence:queued" | "persistence:success" | "persistence:retry" | "persistence:failed" | "persistence:queue_cleared" | "persistence:init_error" | "action:start" | "action:complete" | "action:error" | "selector:accessed" | "selector:changed";
+/**
+ * Represents a state update, which can be:
+ * 1. The full new state (`T`).
+ * 2. A partial update object (`DeepPartial<T>`).
+ * 3. A function that receives the current state and returns a partial update (sync or async).
+ */
+type StateUpdater<T> = T | DeepPartial<T> | ((state: T) => DeepPartial<T> | Promise<DeepPartial<T>>);
+/**
+ * Core types for the reactive data store
+ */
+/**
+ * Type for a Transform Middleware function.
+ * It modifies (transforms) the incoming changes and must return a `DeepPartial<T>`.
+ */
+type TransformMiddleware<T> = (state: T, changes: DeepPartial<T>) => Promise<DeepPartial<T>> | DeepPartial<T>;
+/**
+ * Type for a Blocking Middleware function.
+ * It determines whether the state update should proceed or be blocked.
+ * It returns a boolean or an object containing a `block` boolean and an optional `error`.
+ */
+type BlockingMiddleware<T> = (state: T, changes: DeepPartial<T>) => Promise<boolean | {
+  block: boolean;
+  error?: Error;
+}> | boolean | {
+  block: boolean;
+  error?: Error;
+};
+/**
+ * Type representing the configuration object passed to the `use` method to register a middleware.
+ */
+interface MiddlewareConfig<T> {
+  /** The middleware function (can be a transform or blocking middleware). */
+  action: TransformMiddleware<T> | BlockingMiddleware<T>;
+  /** An optional, human-readable name for the middleware. */
+  name?: string;
+  /** If true, the middleware is treated as a blocking middleware (must return a boolean or `{ block: boolean }`). */
+  block?: boolean;
+}
+/**
+ * Interface for a reactive selector result, providing access to the value and subscription capabilities.
+ */
+interface ReactiveSelector<S> {
+  /** Unique identifier for the selector. */
+  id: string;
+  /** Function to get the current computed value of the selector. */
+  get: () => S;
+  /**
+   * Subscribes a callback function to run whenever the selector's result changes.
+   * Returns an unsubscribe function.
+   */
+  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 TransactionOptions {
+  /** If true, blocks resolution until changes are fully committed to the database row */
+  flush?: boolean;
+}
+/**
+ * Interface defining the contract for the core data state store.
+ * T must be an object type.
+ */
+interface DataStore<T extends object> {
+  /**
+   * Gets the current state of the store.
+   * @param clone If true, returns a deep clone of the state; otherwise, returns the internal state reference.
+   * @returns The current state T.
+   */
+  get(clone?: boolean): T;
+  /**
+   * Gets a subset of the store.
+   * @param paths The paths which to include in the returned object.
+   * @param separator Optional separator for paths. Defaults to `.` .
+   * @returns An object of the shape K mapping paths to their current values.
+   */
+  subset<K extends Record<string, any> = Record<string, any>>(paths: Array<string>, separator?: string): K;
+  /**
+   * Registers a named action function that can modify the state.
+   * @param action The action configuration object.
+   * @returns A function to unregister the action.
+   */
+  register<R extends any[]>(action: {
+    name: string;
+    fn: (state: T, ...args: R) => DeepPartial<T> | Promise<DeepPartial<T>>;
+    debounce?: {
+      delay: number;
+      condition?: (previous: R, current: R) => boolean;
+    };
+  }): () => void;
+  /**
+   * Executes (dispatches) a previously registered action by its name.
+   * @param name The name of the action.
+   * @param args The parameters to pass to the action function.
+   * @returns A promise that resolves to the final state after the action and subsequent updates are complete.
+   */
+  dispatch<R extends any[]>(name: string, ...args: R): Promise<T>;
+  /**
+   * Sets or updates the state using a StateUpdater.
+   * @param update The new state, partial state, or a function returning a partial state.
+   * @param options Configuration options for the set operation.
+   * @returns A promise that resolves to the current state when the update is complete.
+   */
+  set(update: StateUpdater<T>, options?: {
+    force?: boolean;
+    actionId?: string;
+  }): Promise<T>;
+  /**
+   * Creates a reactive selector that computes a derived value and tracks dependencies.
+   * @param selector A function to compute the derived state value S from the full state T.
+   * @returns A `ReactiveSelector<S>` object.
+   */
+  select<S>(selector: (state: T) => S): ReactiveSelector<S>;
+  /**
+   * Subscribes a callback to run when the data at the specified path(s) changes.
+   * @param path A single path string or an array of path strings to watch.
+   * @param callback The function to execute when a change occurs in the watched path(s).
+   * @param options Extra options to pass to the event bus
+   * @returns An unsubscribe function.
+   */
+  watch(path: string | Array<string>, callback: (state: T) => void, options?: SubscribeOptions): () => 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).
+   * @param operation The function containing the state updates.
+   * @returns A promise that resolves to the return value of the operation function.
+   */
+  transaction<R>(operation: () => R | Promise<R>, options?: TransactionOptions): Promise<R>;
+  /**
+   * Registers a middleware function to intercept state updates.
+   * @param props The middleware configuration.
+   * @returns A function to unregister the middleware.
+   */
+  use(props: MiddlewareConfig<T>): () => boolean;
+  /**
+   * Subscribes a listener to a specific store event type.
+   * @param event The type of store event to listen for.
+   * @param listener The callback function to execute when the event fires.
+   * @returns An unsubscribe function.
+   */
+  on(event: StoreEvent, listener: (data: any) => void): () => void;
+  /**
+   * Returns the unique identifier of the store instance.
+   */
+  id(): string;
+  /**
+   * Checks whether the store is fully initialized and ready for use.
+   */
+  isReady(): boolean;
+  /**
+   * Returns a promise that resolves once the store is fully initialised.
+   * Safe to call multiple times — all callers share the same latch.
+   *
+   * @param timeout - Optional maximum wait time in milliseconds.
+   * @throws {TimeoutError} If the store does not become ready within the timeout.
+   *
+   * @example
+   * await store.ready();
+   * const state = store.get();
+   */
+  ready(timeout?: number): Promise<void>;
+  /**
+   * Returns a readonly snapshot of the current execution state of the store.
+   */
+  state(): Readonly<StoreExecutionState<T>>;
+  /**
+   * Releases all resources held by the store and renders it unusable
+   */
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region src/artifacts/types.d.ts
+/**
+ * Defines the lifecycle and sharing strategy for an artifact.
+ */
+type ArtifactScope =
+/**
+ * **Singleton:** A single instance of the artifact is created and shared across all resolutions
+ * within the container. It is created once (often lazily) and reused until invalidated.
+ */
+"singleton"
+/**
+ * **Transient:** A new instance of the artifact is created every time it is resolved.
+ * Transient artifacts do not participate in caching or shared state management.
+ */
+| "transient";
+/**
+ * Enumeration of standard artifact scopes for strongly typed configuration.
+ */
+declare enum ArtifactScopes {
+  /** A single instance is shared globally. */
+  Singleton = "singleton",
+  /** A new instance is created on every resolution. */
+  Transient = "transient"
+}
+/**
+ * Represents a snapshot of an artifact's state and dependencies for debugging purposes.
+ * Provides insight into the artifact's current status and its position within the dependency graph.
+ */
+interface ArtifactDebugNode {
+  /** The unique identifier (key) of the artifact. */
+  id: string;
+  /** The scope of the artifact (Singleton or Transient). */
+  scope: ArtifactScope;
+  /**
+   * The current status of the artifact, indicating its lifecycle phase.
+   * - `'active'`: The artifact is successfully built and its instance is available.
+   * - `'error'`: The artifact failed to build due to an external (runtime) error.
+   * - `'idle'`: The artifact has not yet been built (for lazy singletons) or has been disposed.
+   * - `'building'`: The artifact's factory is currently executing.
+   * - `'pending'`: The artifact is waiting to be built, often after an invalidation and before any debounce.
+   */
+  status: "active" | "error" | "idle" | "building" | "pending" | "debouncing";
+  /** A list of artifact keys that this artifact directly depends on. */
+  dependencies: string[];
+  /** A list of artifact keys that directly depend on this artifact (its consumers). */
+  dependents: string[];
+  /** A list of state paths (selectors) that this artifact depends on. */
+  stateDependencies: string[];
+  /** The number of times this artifact's factory has been successfully executed/rebuilt. */
+  buildCount: number;
+}
+/**
+ * Context provided to the `use` callback within an artifact factory.
+ * It allows an artifact to declare dependencies on other artifacts and state slices.
+ * @template TRegistry The type mapping artifact keys to their artifact types.
+ * @template TState The type of the global state managed by the DataStore.
+ */
+interface UseDependencyContext<TRegistry extends Record<string, any>, TState extends object> {
+  /**
+   * Resolves another artifact from the container and registers a dependency on it.
+   * If the dependency changes, the current artifact will be invalidated and rebuilt.
+   * @template K The key of the artifact to resolve.
+   * @param key The key of the artifact to resolve.
+   * @param params Parameters with which to resolve the artifact
+   * @returns A Promise that resolves to a `ResolvedArtifact` containing the instance
+   * or an external error.
+   * @throws {SystemError} if the key is missing or if resolving creates a circular dependency.
+   */
+  resolve<K extends keyof TRegistry>(key: K, params?: any): Promise<ResolvedArtifact<TRegistry[K]>>;
+  /**
+   * Resolves another artifact from the container and registers a dependency on it.
+   * If the dependency changes, the current artifact will be invalidated and rebuilt.
+   * @template K The key of the artifact to resolve.
+   * @param key The key of the artifact to resolve.
+   * @param params Parameters with which to resolve the artifact
+   * @returns A Promise that resolves to a the resolved instance, unlike
+   * resolve, this will throw an error if resolution fails.
+   * @throws {SystemError} if any error occurs during resolution.
+   */
+  require<K extends keyof TRegistry>(key: K, params?: any): Promise<TRegistry[K]>;
+  /**
+   * Selects a slice of the global state and registers a dependency on it.
+   * If the selected state slice changes (based on a deep comparison), the current
+   * artifact will be invalidated and rebuilt.
+   * @template S The type of the selected state slice.
+   * @param selector A function that takes the full state and returns a slice of state.
+   * @returns The selected slice of state.
+   */
+  select<S>(selector: (state: TState) => S, options?: SubscribeOptions): S;
+}
+/**
+ * Context object provided to an artifact stream producer function (`ctx.stream` callback).
+ * It contains methods and properties necessary for managing the stream and communicating
+ * new artifact values to the container and its consumers.
+ *
+ * @template TState The type of the global state.
+ * @template TArtifact The type of the artifact being streamed.
+ */
+type ArtifactStreamContext<TState, TArtifact> = {
+  /**
+   * The current value of the artifact. This is `undefined` before the first value is emitted.
+   * Useful for diffing or migrating state during an update.
+   * @returns The current artifact value or `undefined`.
+   */
+  value: () => TArtifact | undefined;
+  /**
+   * An AbortSignal that indicates if the stream has been cancelled or aborted
+   * from the consumer side (e.g., due to container disposal or artifact invalidation).
+   * Producers should check this signal and stop processing when it is set to prevent leaks.
+   */
+  signal: AbortSignal;
+  /**
+   * A function to asynchronously emit a new value of the artifact to the container.
+   * Calling this function updates the artifact's resolved value, triggers invalidation
+   * for its dependents, and updates the `value()` property for subsequent emissions.
+   *
+   * @param value The new artifact value to emit.
+   * @returns A Promise that resolves when the value has been sent and dependents have been notified.
+   */
+  emit: (value: TArtifact) => Promise<void>;
+  /**
+   * Dispatches a state update to the global store, analogous to a standard `setState`.
+   * **Note:** This does not automatically register a dependency for the current artifact.
+   * @param update A `StateUpdater` function or a partial state object.
+   * @param options Optional settings for the update, including `force` and `actionId`.
+   * @returns A Promise that resolves when the state update is complete.
+   */
+  set(update: StateUpdater<TState>, options?: {
+    force?: boolean;
+    actionId?: string;
+  }): Promise<any>;
+};
+/**
+ * The full context provided to an artifact's factory function.
+ * This context allows the artifact to interact with the container,
+ * declare dependencies, manage its lifecycle, and update its value.
+ * @template TRegistry The type mapping artifact keys to their artifact types.
+ * @template TState The type of the global state managed by the DataStore.
+ * @template TArtifact The type of the artifact being created by the factory.
+ */
+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
+   * unless explicitly selected via `ctx.use` and `ctx.select`.
+   * @returns The current global state.
+   */
+  state(): TState;
+  /**
+   * The previous instance of the artifact if it's a Singleton and is being rebuilt
+   * after an invalidation. This is `undefined` on the initial build.
+   * Useful for diffing, migrating state, or reusing resources during an update.
+   */
+  previous?: TArtifact;
+  /**
+   * Executes a callback within a dependency tracking context.
+   * Any `resolve` or `select` calls made inside this callback will register
+   * dependencies for the current artifact.
+   * @template R The return type of the callback.
+   * @param callback The function to execute to resolve dependencies.
+   * @returns A Promise resolving to the result of the callback.
+   */
+  use<R>(callback: (ctx: UseDependencyContext<TRegistry, TState>) => R | Promise<R>): Promise<R>;
+  /**
+   * Registers a cleanup function to be executed when the **current instance** of the
+   * artifact is invalidated and before its new instance is built. This is useful
+   * for releasing resources (e.g., event listeners) specific to the *previous* instance.
+   * @param cleanup The cleanup function.
+   */
+  onCleanup(cleanup: ArtifactCleanup): void;
+  /**
+   * Registers a dispose function to be executed when the artifact is
+   * permanently removed from the container or the container itself is disposed.
+   * This is for final, permanent resource release.
+   * @param callback The dispose function.
+   */
+  onDispose(callback: ArtifactCleanup): void;
+  /**
+   * Starts a streaming process for a Singleton artifact.
+   * The callback receives an `ArtifactStreamContext` to emit values and manage the
+   * stream's lifecycle. It can return a cleanup function (or a Promise resolving
+   * to one) to handle resource disposal.
+   * * @param callback - The streaming logic implementation. Can be synchronous or
+   * asynchronous, optionally returning a cleanup function.
+   * @throws {SystemError} If called on a Transient artifact, as they do not
+   * support persistent streaming states.
+   */
+  stream(callback: (ctx: ArtifactStreamContext<TState, TArtifact>) => (void | (() => void | Promise<void>)) | Promise<void | (() => void | Promise<void>)>): void;
+  stream(callback: (ctx: ArtifactStreamContext<TState, TArtifact>) => (void | (() => void | Promise<void>)) | Promise<void | (() => void | Promise<void>)>): void;
+  /**
+   * An AbortSignal that indicates if the artifacts has been unregistered
+   */
+  signal: AbortSignal; /** For parameterized artifacts: the parameters that were passed during resolve/watch. */
+  params?: any;
+};
+/**
+ * A function that performs cleanup or disposal logic for an artifact, potentially asynchronously.
+ * Used for `onCleanup` and `onDispose` callbacks.
+ */
+type ArtifactCleanup = () => void | Promise<void>;
+interface ArtifactLifecycleEventMap {
+  "build:start": {
+    key: string;
+    templateKey?: string;
+  };
+  "build:complete": {
+    key: string;
+    instance: unknown;
+  };
+  "build:error": {
+    key: string;
+    error: unknown;
+  };
+  "artifact:invalidated": {
+    key: string;
+    cascade: boolean;
+    replace: boolean;
+  };
+  "artifact:disposed": {
+    key: string;
+  };
+  "artifact:registered": {
+    key: string;
+    scope: ArtifactScope;
+  };
+  "stream:emit": {
+    key: string;
+    value: unknown;
+  };
+  "container:dispose": {};
+}
+/**
+ * Common properties shared across all possible states of a resolved artifact.
+ * @template TArtifact The type of the resolved artifact instance.
+ */
+interface ResolvedArtifactBase {
+  /**
+   * A function to manually trigger cleanup associated with this specific
+   * resolved instance. This is typically only relevant for Transient artifacts
+   * where the consumer is responsible for cleanup.
+   */
+  cleanup?: ArtifactCleanup;
+  /**
+   * Manually invalidates this artifact, triggering its rebuild and
+   * cascading invalidations to its dependents.
+   * @param replace If `true`, forces immediate rebuild without debounce delay.
+   * @param fatal If `true`, the artifact will not be rebuilt until next resolve
+   * regardless of the lazy option during registration.
+   */
+  invalidate(replace?: boolean, fatal?: boolean): Promise<void>;
+}
+/**
+ * State of an artifact that is successfully built and ready for use.
+ * The instance is guaranteed to be present.
+ * @template TArtifact The type of the resolved artifact instance.
+ */
+interface ReadyArtifact<TArtifact> extends ResolvedArtifactBase {
+  /** The successfully resolved instance of the artifact. */
+  instance: TArtifact;
+  /** Indicates whether the artifact is ready and has an instance. */
+  ready: true;
+  error?: undefined;
+}
+/**
+ * State of an artifact that failed to build due to an external error.
+ * The instance is guaranteed to be absent.
+ */
+interface ErrorArtifact extends ResolvedArtifactBase {
+  instance?: undefined;
+  ready: false;
+  /**
+   * Any runtime or external error that occurred during the artifact's factory
+   * execution (e.g., network fetch failed).
+   */
+  error: any;
+}
+/**
+ * State of an artifact that is pending, idle, or currently building.
+ * Both instance and error are absent.
+ */
+interface PendingArtifact extends ResolvedArtifactBase {
+  /** The instance is absent while pending or idle. Always undefined. */
+  instance?: undefined;
+  ready: false;
+  error?: undefined;
+}
+/**
+ * The result of an artifact resolution. This is a union type representing
+ * the artifact in one of three possible states: Ready, Error, or Pending/Idle.
+ *
+ * This structure allows consuming code to narrow the type based on the
+ * boolean flag `ready` or the presence of the `error` property.
+ *
+ * @template TArtifact The type of the resolved artifact instance.
+ */
+type ResolvedArtifact<TArtifact> = ReadyArtifact<TArtifact> | ErrorArtifact | PendingArtifact;
+type KeyedResolvedArtifact<TRegistry, K extends keyof TRegistry> = ResolvedArtifact<TRegistry[K]> & { [P in K]?: TRegistry[K] };
+/**
+ * The factory function responsible for creating an artifact's instance.
+ * It receives an `ArtifactFactoryContext` to interact with the container
+ * and declare dependencies.
+ * @template TRegistry The type mapping artifact keys to their artifact types.
+ * @template TState The type of the global state managed by the DataStore.
+ * @template TArtifact The type of the artifact this factory produces.
+ * @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, 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,
+ * typically used for UI binding or monitoring.
+ * Provides a way to get the current resolved artifact and subscribe to updates.
+ * @template TArtifact The type of the artifact being watched.
+ */
+interface ArtifactObserver<TRegistry, K extends keyof TRegistry> {
+  /** The unique identifier (key) of the artifact being watched. */
+  id: string;
+  /**
+   * Number of active references (watchers) to this observer instance.
+   * Incremented on each `watch()` call, decremented on each `dispose()` call.
+   */
+  count: number;
+  /**
+   * Retrieves the current `ResolvedArtifact` for the watched key.
+   * @param resolve Flag indicating whether we should resolve the artifact
+   * immediately. Defaults to `false`
+   * @returns The resolved artifact, including its instance and status.
+   */
+  get(resolve?: boolean): KeyedResolvedArtifact<TRegistry, K>;
+  /**
+   * Subscribes a callback function to be invoked whenever the artifact's
+   * state (instance, error, or readiness) changes.
+   * @param callback The function to call on updates. It receives the new `ResolvedArtifact`.
+   * @param eager a boolean indicating whether we should immediately call the
+   * callback after subscription. Defaults to `true`
+   * @returns A function to unsubscribe the callback and stop receiving updates.
+   */
+  subscribe(callback: (artifact: KeyedResolvedArtifact<TRegistry, K>) => void, eager?: boolean): () => void;
+  /**
+   * Resolves another artifact from the container and registers a dependency on it.
+   * If the dependency changes, the current artifact will be invalidated and rebuilt.
+   * @returns A Promise that resolves to a `ResolvedArtifact` containing the instance
+   * or an external error.
+   * @throws {SystemError} if resolution fails.
+   */
+  resolve(): Promise<KeyedResolvedArtifact<TRegistry, K>>;
+}
+/**
+ * Configuration options for defining an artifact. These options control
+ * its lifecycle, instantiation, and error handling behavior.
+ * @template TState The type of the global state.
+ * @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 Record<string, any> = Record<string, 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, TExtra>;
+  /**
+   * The scope of the artifact, determining its lifecycle and sharing strategy.
+   * Defaults to `ArtifactScopes.Singleton`.
+   */
+  scope?: ArtifactScope;
+  /**
+   * If `true` (default), the artifact's factory is executed only when the artifact
+   * is first requested (lazy instantiation). If `false`, the artifact is built
+   * immediately upon registration (only applies to Singleton scopes).
+   */
+  lazy?: boolean;
+  /**
+   * Maximum time in milliseconds allowed for the artifact's factory function
+   * to complete execution. If exceeded, the factory will time out.
+   */
+  timeout?: number;
+  /**
+   * Number of times to retry the artifact's factory on failure due to an
+   * external (runtime) error (e.g., an exception in an async dependency).
+   * SystemErrors (e.g., key not found) are not retried. Defaults to `0`.
+   */
+  retries?: number;
+  /**
+   * Base debounce time in milliseconds for invalidation events originating
+   * from this artifact's dependencies. This delays the rebuild process to
+   * aggregate multiple rapid changes.
+   */
+  debounce?: number;
+  /** If defined, the artifact is parameterized. Receives the user‑supplied params and returns a unique string key. */
+  paramKey?: (params: Record<string, unknown>) => string;
+  virtual?: true;
+}
+/**
+ * Extracts the global state type (`TState`) from an `ArtifactTemplate`.
+ */
+type ArtifactStateType<T> = T extends ArtifactTemplate<infer TState, any, any> ? TState : never;
+/**
+ * Extracts the full artifact registry type (`TRegistry`) from an `ArtifactTemplate`.
+ */
+type ArtifactRegistryType<T> = T extends ArtifactTemplate<any, any, infer TRegistry> ? TRegistry : never;
+/**
+ * Extracts the key type (`K`) from an `ArtifactTemplate` (as a string literal if possible).
+ */
+type ArtifactKey<T> = T extends {
+  key: infer K;
+} ? K : never;
+/**
+ * Extracts the scope type (`S`) from an `ArtifactTemplate`, defaulting to `ArtifactScope` if undefined.
+ */
+type ArtifactScopeType<T> = T extends {
+  scope: infer S;
+} ? S extends ArtifactScope ? S : ArtifactScope : ArtifactScope;
+/**
+ * Helper type that creates a properly typed template map where keys correspond to artifact names
+ * and values are their corresponding templates.
+ * @template TState The type of the global state.
+ * @template TRegistry The map of all artifact keys to their resolved types.
+ */
+type ArtifactTemplateMap<TState extends object, TRegistry extends Record<string, any> = Record<string, any>> = { [K in keyof TRegistry]: ArtifactTemplate<TState, TRegistry[K], TRegistry> };
+/**
+ * Extracts the artifact's resolved value type (`TArtifact`) from an object that structurally
+ * resembles an `ArtifactTemplate` (by inspecting the `factory` function's generic arguments).
+ *
+ * @template T The type that contains a factory property.
+ */
+type ArtifactValue<T> = T extends {
+  factory: ArtifactFactory<any, any, infer TArtifact, any>;
+} ? TArtifact : never;
+/**
+ * Infers the complete Artifact Registry type from a map of artifact configuration objects.
+ *
+ * This utility uses the `ArtifactValue` type to determine the resolved type for each key
+ * based on the `factory` function defined in the configuration.
+ *
+ * @template T A map where keys are artifact names and values are their configurations.
+ */
+type InferRegistry<T extends Record<string, {
+  factory: (...args: any[]) => any;
+  [key: string]: any;
+}>> = { [K in keyof T]: ArtifactValue<T[K]> };
+/**
+ * State paths grouped by options passed to the store
+ */
+interface StateGroup {
+  paths: string[];
+  options?: SubscribeOptions;
+}
+interface ExportedArtifact {
+  key: string;
+  instance: any;
+  state: {
+    groups: Array<{
+      paths: string[];
+      options?: SubscribeOptions;
+    }>;
+    hash: string;
+  };
+  dependencies: string[];
+}
+interface ExportedContainerState {
+  version: string;
+  timestamp: number;
+  artifacts: ExportedArtifact[];
+  checksum: string;
+}
+//#endregion
+//#region src/logger/logger.d.ts
+/**
+ * Represents the severity level of a system log entry.
+ * Levels are ordered by increasing severity: trace, debug, info, warn, error.
+ */
+type LogLevel = "trace" | "debug" | "info" | "warn" | "error";
+/**
+ * Structure representing a fully contextualized system log entry ready for sinking.
+ */
+interface SystemLog {
+  /** The severity level of the log. */
+  level: LogLevel;
+  /** A clear, human-readable string identifying the distinct event (e.g., "user_login_failed"). */
+  event: string;
+  /** Additional structured data specific to this log instantiation. */
+  data?: object;
+  /** Contextual data shared across the logger instance (e.g., traceIds, environment). */
+  context?: object;
+  /** Epoch timestamp in milliseconds denoting when the log event occurred. */
+  timestamp: number;
+}
+/**
+ * Primary logger interface providing level-specific log dispatching and context-chaining.
+ */
+interface SystemLogger {
+  /** Logs high-volume, extremely fine-grained diagnostic details. */
+  trace(event: string, data?: object): void;
+  /** Logs diagnostic information useful during local development or debugging. */
+  debug(event: string, data?: object): void;
+  /** Logs standard operational events that track the healthy flow of the system. */
+  info(event: string, data?: object): void;
+  /** Alias for the `info` logging method. */
+  log(event: string, data?: object): void;
+  /** Logs non-fatal operational anomalies or conditions that deserve attention. */
+  warn(event: string, data?: object): void;
+  /** Logs critical errors, failures, or exceptions preventing a transaction/process. */
+  error(event: string, data?: unknown): void;
+  /**
+   * Directly forwards a pre-constructed `SystemLog` record through the logger's pipeline.
+   * Combines instance context before outputting.
+   */
+  write(record: SystemLog): void;
+  /**
+   * Generates a new `SystemLogger` instance that shares the existing sinks and parent
+   * context, deeply merging the newly provided context on top.
+   *
+   * @param context - The metadata to append to all subsequent logs emitted by the child logger.
+   */
+  child(context: object): SystemLogger;
+}
+//#endregion
+//#region src/artifacts/container.d.ts
+declare class ArtifactContainer<TRegistry extends Record<string, any> = Record<string, any>, TState extends object = any> {
+  private readonly registry;
+  private readonly cache;
+  private readonly graph;
+  private readonly manager;
+  private readonly observer;
+  private readonly logger;
+  private readonly store;
+  readonly events: EventBus<ArtifactLifecycleEventMap>;
+  constructor(store: Pick<DataStore<TState>, "watch" | "get" | "set" | "subset">, options?: {
+    logger?: SystemLogger;
+  });
+  debugInfo(): ArtifactDebugNode[];
+  register<K extends keyof TRegistry>(params: ArtifactTemplate<TState, TRegistry[K], TRegistry>): () => void;
+  has<K extends keyof TRegistry>(key: K): boolean;
+  unregister<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>): Promise<void>;
+  resolve<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>): Promise<KeyedResolvedArtifact<TRegistry, K>>;
+  require<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>): Promise<TRegistry[K]>;
+  watch<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>, ttl?: number): ArtifactObserver<TRegistry, K>;
+  peek<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>): TRegistry[K] | undefined;
+  invalidate<K extends keyof TRegistry>(key: K, options?: {
+    replace?: boolean;
+    params?: Record<string, unknown>;
+  }): Promise<void>;
+  on<TEventName extends keyof ArtifactLifecycleEventMap>(eventName: TEventName, callback: (payload: ArtifactLifecycleEventMap[TEventName]) => void): () => void;
+  on(eventName: "*", callback: (payload: ArtifactLifecycleEventMap[keyof ArtifactLifecycleEventMap], event: keyof ArtifactLifecycleEventMap) => void): () => void;
+  once<TEventName extends keyof ArtifactLifecycleEventMap>(eventName: TEventName, callback: (payload: ArtifactLifecycleEventMap[TEventName]) => void): () => void;
+  once(eventName: "*", callback: (payload: ArtifactLifecycleEventMap[keyof ArtifactLifecycleEventMap], event: keyof ArtifactLifecycleEventMap) => void): () => void;
+  notifyObservers(key: string): void;
+  hasWatchers(key: string): boolean;
+  dispose(): Promise<void>;
+  export(): Promise<ExportedContainerState>;
+  private restore;
+  static from<TRegistry extends Record<string, any> = Record<string, any>, TState extends object = any>(options: {
+    store: Pick<DataStore<TState>, "watch" | "get" | "set" | "subset">;
+    bundle?: ExportedContainerState;
+    templates: ArtifactTemplate<TState, any, TRegistry>[];
+    logger?: SystemLogger;
+  }): Promise<ArtifactContainer<TRegistry, TState>>;
+}
+//#endregion
+//#region src/artifacts/errors.d.ts
+declare const ErrorCodes: {
+  readonly NOT_FOUND: "DB-001-NF";
+  readonly DUPLICATE_KEY: "DB-002-DUP";
+  readonly INVALID_COMMAND: "BUS-001";
+  readonly INTERNAL_ERROR: "SYS-001";
+  readonly CONCURRENCY_ERROR: "CON-001";
+};
+declare function artifactNotFound(key: string): SystemError;
+declare function cycleDetected(path: string[]): SystemError;
+declare function illegalScope(message: string): SystemError;
+declare function watcherDisposed(key: string): SystemError;
+declare function timeoutError(message?: string): SystemError;
+declare function keyConflict(key?: string): SystemError;
+declare function notParameterized(key: string): SystemError;
+declare function paramKeyCollision(key: string, computedKey: string): SystemError;
+declare function selfDependency(key: string): SystemError;
+declare function buildStaleAfterRetries(depKey: string): SystemError;
+declare function invalidImport(message: string): SystemError;
+declare function invalidExport(key: string): SystemError;
+declare class SupersededBuildError extends Error {
+  constructor();
+}
+//#endregion
+export { ArtifactCleanup, ArtifactContainer, ArtifactDebugNode, ArtifactFactory, ArtifactFactoryContext, ArtifactInstance, ArtifactKey, ArtifactLifecycleEventMap, ArtifactObserver, ArtifactRegistryType, ArtifactScope, ArtifactScopeType, ArtifactScopes, ArtifactStateType, ArtifactStreamContext, ArtifactTemplate, ArtifactTemplateMap, ArtifactValue, ErrorArtifact, ErrorCodes, ExportedArtifact, ExportedContainerState, InferRegistry, type Issue, KeyedResolvedArtifact, PendingArtifact, ReadyArtifact, ResolvedArtifact, ResolvedArtifactBase, type Severity, StateGroup, SupersededBuildError, SystemError, UseDependencyContext, artifactNotFound, buildStaleAfterRetries, cycleDetected, illegalScope, invalidExport, invalidImport, keyConflict, notParameterized, paramKeyCollision, selfDependency, timeoutError, watcherDisposed };