hakojs/dist/types/mem/lifetime.d.ts

A secure, embeddable JavaScript engine that runs untrusted code inside WebAssembly sandboxes with fine-grained permissions and resource limits

import type { SuccessOrFail } from "../vm/vm-interface";
/**
 * A container for native values that need deterministic cleanup.
 *
 * NativeBox provides a uniform interface for managing the lifecycle of values
 * that may have associated resources requiring explicit cleanup.
 *
 * @template TValue - The type of value contained in the box
 */
export type NativeBox<TValue> = {
    /**
     * The contained value
     */
    value: TValue;
    /**
     * Indicates if the boxed value is still valid and usable
     */
    alive: boolean;
    /**
     * Releases any resources associated with the boxed value
     */
    dispose(): void;
    /**
     * Implements the Symbol.dispose method for the Disposable interface
     */
    [Symbol.dispose](): void;
};
/**
 * Checks if a value is an instance of AbstractDisposableResult.
 *
 * @param value - The value to check
 * @returns True if the value is an AbstractDisposableResult, false otherwise
 */
export declare function isAbstractDisposableResult(value: unknown): value is AbstractDisposableResult;
/**
 * Abstract base class for disposable result types.
 *
 * This class provides the foundation for creating disposable success and failure
 * result types that can be used for operations that might fail and need resource
 * cleanup regardless of outcome.
 *
 * @implements {Disposable} - Implements the Disposable interface
 */
declare abstract class AbstractDisposableResult implements Disposable {
    /**
     * Creates a success result with the provided value.
     *
     * @template S - Success value type
     * @template F - Failure value type
     * @param value - The success value
     * @returns A disposable success result containing the value
     */
    static success<S, F>(value: S): DisposableSuccess<S>;
    /**
     * Creates a failure result with the provided error.
     *
     * @template S - Success value type
     * @template F - Failure value type
     * @param error - The error value
     * @param onUnwrap - Callback to execute when unwrap is called on this failure
     * @returns A disposable failure result containing the error
     */
    static fail<S, F>(error: F, onUnwrap: (status: SuccessOrFail<S, F>) => void): DisposableFail<F>;
    /**
     * Checks if a result is a DisposableResult.
     *
     * @template S - Success value type
     * @template F - Failure value type
     * @param result - The result to check
     * @returns True if the result is a DisposableResult, false otherwise
     */
    static is<S, F>(result: SuccessOrFail<S, F>): result is DisposableResult<S, F>;
    /**
     * Indicates if the result's contained value is still valid and usable.
     */
    abstract get alive(): boolean;
    /**
     * Releases any resources associated with the result.
     */
    abstract dispose(): void;
    /**
     * Implements the Symbol.dispose method for the Disposable interface.
     */
    [Symbol.dispose](): void;
}
/**
 * Represents a successful operation result with disposable resources.
 *
 * This class wraps a success value and provides methods to safely access or
 * dispose of the contained value.
 *
 * @template S - The type of the success value
 * @extends {AbstractDisposableResult}
 */
export declare class DisposableSuccess<S> extends AbstractDisposableResult {
    readonly value: S;
    /**
     * Indicates this is a success result with no error.
     */
    error?: undefined;
    /**
     * Creates a new DisposableSuccess.
     *
     * @param value - The success value
     */
    constructor(value: S);
    /**
     * Checks if the contained value is still valid and usable.
     *
     * If the value implements the disposable interface, this returns its 'alive' status.
     * Otherwise, it returns true.
     *
     * @returns The alive status of the contained value
     */
    get alive(): boolean;
    /**
     * Disposes of the contained value if it is disposable.
     */
    dispose(): void;
    /**
     * Unwraps the success value.
     *
     * @returns The contained success value
     */
    unwrap(): S;
    /**
     * Unwraps the success value or returns a fallback if this was a failure.
     *
     * Since this is a success result, this always returns the contained value
     * and ignores the fallback.
     *
     * @template T - The type of the fallback value
     * @param _fallback - The fallback value (ignored)
     * @returns The contained success value
     */
    unwrapOr<T>(_fallback: T): S;
}
/**
 * Represents a failed operation result with disposable resources.
 *
 * This class wraps an error value and provides methods to either safely access
 * a fallback value or throw the contained error.
 *
 * @template F - The type of the error value
 * @extends {AbstractDisposableResult}
 */
export declare class DisposableFail<F> extends AbstractDisposableResult {
    readonly error: F;
    private readonly onUnwrap;
    /**
     * Creates a new DisposableFail.
     *
     * @param error - The error value
     * @param onUnwrap - Callback to execute when unwrap is called on this failure
     */
    constructor(error: F, onUnwrap: (status: SuccessOrFail<never, F>) => void);
    /**
     * Checks if the contained error is still valid and usable.
     *
     * If the error implements the disposable interface, this returns its 'alive' status.
     * Otherwise, it returns true.
     *
     * @returns The alive status of the contained error
     */
    get alive(): boolean;
    /**
     * Disposes of the contained error if it is disposable.
     */
    dispose(): void;
    /**
     * Attempts to unwrap the success value, but this will always throw since
     * this is a failure result.
     *
     * @throws The contained error
     * @returns Never returns
     */
    unwrap(): never;
    /**
     * Unwraps the success value or returns a fallback if this was a failure.
     *
     * Since this is a failure result, this always returns the fallback value.
     *
     * @template T - The type of the fallback value
     * @param fallback - The fallback value to return
     * @returns The fallback value
     */
    unwrapOr<T>(fallback: T): T;
}
/**
 * Union type representing either a successful or failed operation result,
 * both with disposable resource management.
 *
 * @template S - The type of the success value
 * @template F - The type of the error value
 */
export type DisposableResult<S, F> = DisposableSuccess<S> | DisposableFail<F>;
/**
 * Factory and utility functions for creating and working with DisposableResults.
 */
export declare const DisposableResult: typeof AbstractDisposableResult;
/**
 * A utility class that helps manage resources with automatic cleanup.
 *
 * Scope collects cleanup functions to be executed when the scope is disposed,
 * ensuring deterministic resource cleanup even in the presence of exceptions.
 * It follows the RAII (Resource Acquisition Is Initialization) pattern.
 *
 * @implements {Disposable} - Implements the Disposable interface
 */
export declare class Scope implements Disposable {
    /**
     * Collection of cleanup functions to be executed on disposal
     * @private
     */
    private cleanupFns;
    /**
     * Flag indicating if the scope has been disposed
     * @private
     */
    private isDisposed;
    /**
     * Adds a cleanup function to be executed when the scope is disposed.
     *
     * Cleanup functions are executed in reverse order (LIFO) during disposal.
     *
     * @param fn - The cleanup function to add
     * @throws Error if the scope has already been disposed
     */
    add(fn: () => void): void;
    /**
     * Executes all cleanup functions and clears the list.
     *
     * Cleanup functions are executed in reverse order (LIFO).
     * If already disposed, this is a no-op.
     * Errors in cleanup functions are caught and logged to avoid masking other errors.
     */
    release(): void;
    /**
     * Registers a disposable value to be managed by this scope.
     *
     * If the value implements the disposable interface, its dispose method
     * will be called when the scope is disposed.
     *
     * @template T - The type of the value to manage
     * @param value - The value to manage
     * @returns The same value, allowing for chained method calls
     */
    manage<T>(value: T): T;
    /**
     * Executes a function within a scope and automatically disposes the scope afterward.
     *
     * This is a convenience method that creates a scope, executes the provided function
     * with the scope as an argument, and ensures the scope is disposed regardless of
     * whether the function succeeds or throws.
     *
     * @template T - The return type of the function
     * @param block - The function to execute within the scope
     * @returns The result of the function
     */
    static withScope<T>(block: (scope: Scope) => T): T;
    /**
     * Implements the Symbol.dispose method for the Disposable interface.
     *
     * This allows the scope to be used with the using statement
     * in environments that support the Disposable pattern.
     */
    [Symbol.dispose](): void;
}
export {};
//# sourceMappingURL=lifetime.d.ts.map