@synet/signal/dist/core/signal.d.ts

Experimental Fractal Architecture pattern for Synet development

import type { SignalInstance, TraceData, TraceEntry, SignalPluginConfig, SignalPlugin } from "./types";
/**
 * Signal is a self-aware data container that tracks its journey through layers
 */
export declare class Signal<T> implements SignalInstance<T> {
    private readonly _value?;
    private readonly _error?;
    private readonly _trace;
    private readonly _metadata;
    private readonly _id;
    static readonly plugins: Map<string, SignalPlugin>;
    constructor(value?: T, error?: Error, trace?: TraceEntry[], metadata?: Record<string, unknown>);
    get id(): string;
    get isSuccess(): boolean;
    get isFailure(): boolean;
    get value(): T | undefined;
    get error(): Error | undefined;
    get traceEntries(): ReadonlyArray<TraceEntry>;
    static open<U>(layer?: string): Signal<U>;
    static success<U>(value: U, layer?: string): Signal<U>;
    static failure<U>(error: Error | string, layer?: string): Signal<U>;
    static fail<U>(error: Error | string, layer?: string): Signal<U>;
    /**
     * Executes the given callback if this is a success result
     * @param fn Function to execute with the success value
     * @returns This result, for method chaining
     */
    onSuccess(fn: (value: T) => void): Signal<T>;
    /**
     * Executes the given callback if this is a failure result
     * @param fn Function to execute with the error details
     * @returns This result, for method chaining
     */
    onFailure(fn: (cause?: Error) => void): Signal<T>;
    /**
     * Create a new signal with a potentially different value type while preserving the trace history
     * @param original The original signal whose trace will be copied
     * @param transformer Optional function to transform the value
     */
    static extend<T, U = T>(original: Signal<T>, transformer?: (value: T | undefined) => U): Signal<U>;
    /**
     * Add a reflection to the trace
     * @param message Message to add to the trace
     * @param context Optional context object to add to the trace
     * @param component Optional component name to add to the trace
     * 	*/
    reflect(message: string, context?: Record<string, unknown>, component?: string): Signal<T>;
    /**
     * Add a new layer to the trace
     */
    layer<U = T>(name: string, context?: Record<string, unknown>): Signal<U>;
    /**
     * Transform this signal into a failure signal
     */
    fail(error: Error | string, layer?: string): Signal<never>;
    success<U = T>(value: U): Signal<U>;
    failure(error: Error | string, layer?: string): Signal<never>;
    map<U>(fn: (value: T) => U): Signal<U>;
    tracedMap<U>(fn: (value: T) => U, layer?: string): Signal<U>;
    private _map;
    /**
     * Apply a function that returns a Signal, flattening the result
     * Preserves the parent-child relationship for tracing
     */
    flatMap<U>(fn: (value: T) => Signal<U>, layer?: string): Signal<U>;
    tracedFlatMap<U>(fn: (value: T) => Signal<U>, layer?: string): Signal<U>;
    _flatMap<U>(fn: (value: T) => Signal<U>, options?: {
        layer?: string;
        trace?: boolean;
    }, layer?: string): Signal<U>;
    /**
     * Format trace for logging
     */
    trace(): string;
    traceData(): Array<TraceData>;
    /**
     * Helper method to extract the calling method name from the stack trace
     */
    private _getMethodName;
    ensure(condition: (value: T) => boolean, message: string): Signal<T>;
    withMeta(key: string, value: unknown): Signal<T>;
    meta(key: string): unknown;
    resolve(): T;
    /**
     * Create a static helper for tracing the call chain through layers
     */
    static chain<U>(value: U, initialLayer: string): Signal<U>;
    /**
     * Record when execution flow takes a specific branch
     */
    branch(branchName: string, condition: string): Signal<T>;
    /**
     * Plugin system
     */
    static registerPlugin<TOptions>(plugin: SignalPlugin<TOptions>): void;
    static unregisterPlugin(pluginId: string): void;
    with<U = T>(pluginConfig: SignalPluginConfig | string): Signal<U>;
}