@actuallab/core 12.3.29 → 12.3.31

package/dist/index.d.cts

@@ -16,6 +16,96 @@ declare class DisposableBag implements Disposable, AsyncDisposable {
     disposeAsync(): Promise<void>;
 }
 
+declare enum LogLevel {
+    Debug = 1,
+    Info = 2,
+    Warn = 3,
+    Error = 4,
+    None = 1000
+}
+interface LogRef {
+    target: unknown;
+    id: number;
+}
+declare class Log {
+    readonly scope: string;
+    readonly level: LogLevel;
+    private static isInitialized;
+    private static logRefs;
+    /** User-set overrides (persisted to sessionStorage). Empty by default. */
+    static readonly minLevels: Map<string, LogLevel>;
+    /** Per-scope defaults registered by packages via createLogProvider(). */
+    static readonly scopeDefaults: Map<string, LogLevel>;
+    /** Every scope ever requested via Log.get().  Used by logLevels.dump()
+     *  so devs can discover what's available to override at runtime. */
+    static readonly knownScopes: Set<string>;
+    /** Global baseline for any scope without a default or override. */
+    static defaultMinLevel: LogLevel;
+    static loggerFactory: (scope: string, level: LogLevel) => Log;
+    log: (...data: unknown[]) => void;
+    trace: (...data: unknown[]) => void;
+    constructor(scope: string, level: LogLevel);
+    static get(scope: string): LogScopeFns;
+    static ref(data: object | null | undefined): object | null | undefined;
+    assert(predicate?: boolean, ...data: unknown[]): void;
+}
+interface LogScopeFns {
+    logScope: string;
+    debugLog: Log | null;
+    infoLog: Log | null;
+    warnLog: Log | null;
+    errorLog: Log | null;
+}
+declare function createLogProvider<TScope extends string>(prefix: string, defaults: Record<TScope, LogLevel>): (scope: TScope) => LogScopeFns;
+
+declare function initLogging(): void;
+declare class LogLevelController {
+    private minLevels;
+    constructor(minLevels: Map<string, LogLevel>);
+    /** List the current set of overrides. */
+    list(): Record<string, LogLevel>;
+    /** Print every known scope's effective level to the console as a table.
+     *  Shows: scope, effective level, the source ('override' / 'default-key' /
+     *  'package-default' / 'baseline'), and the package default for reference.
+     *  Use this from the dev console to discover what to pass to override(). */
+    dump(): void;
+    /** Override the level for a single scope.  Persisted to sessionStorage. */
+    override(scope: string, newLevel: LogLevel): void;
+    /** Override the level for every scope whose name starts with scopePrefix
+     *  (e.g. 'rpc.' to enable verbose RPC logging).  Persisted. */
+    overrideAll(scopePrefix: string, newLevel: LogLevel): void;
+    /** Reset all overrides; package defaults take effect again.  Persisted. */
+    reset(): void;
+    /** Clear all overrides (no global default unless `defaultLevel` is given). */
+    clear(defaultLevel?: LogLevel): void;
+}
+
+/** Common interface for types that carry a value-or-error outcome. */
+interface IResult<T> {
+    readonly hasValue: boolean;
+    readonly hasError: boolean;
+    readonly value: T;
+    readonly error: unknown;
+    readonly valueOrUndefined: T | undefined;
+}
+/** Immutable value-or-error container — similar to .NET's Result<T>. */
+declare class Result<T> implements IResult<T> {
+    readonly hasValue: boolean;
+    readonly hasError: boolean;
+    private readonly _value;
+    private readonly _error;
+    constructor(value: T | undefined, error?: unknown);
+    get value(): T;
+    get error(): unknown;
+    get valueOrUndefined(): T | undefined;
+    static ok<T>(value: T): Result<T>;
+    static error<T>(error: unknown): Result<T>;
+}
+declare function result<T>(value: T, error?: unknown): Result<T>;
+declare function errorResult<T>(error: unknown): Result<T>;
+declare function resultFrom<T>(fn: () => T): Result<T>;
+declare function resultFromAsync<T>(fn: () => Promise<T>): Promise<Result<T>>;
+
 /** Typed key for values stored in AsyncContext — each subsystem defines its own keys. */
 declare class AsyncContextKey<T> {
     readonly id: symbol;
@@ -119,32 +209,6 @@ declare class RingBuffer<T> {
     toArray(): T[];
 }
 
-/** Common interface for types that carry a value-or-error outcome. */
-interface IResult<T> {
-    readonly hasValue: boolean;
-    readonly hasError: boolean;
-    readonly value: T;
-    readonly error: unknown;
-    readonly valueOrUndefined: T | undefined;
-}
-/** Immutable value-or-error container — similar to .NET's Result<T>. */
-declare class Result<T> implements IResult<T> {
-    readonly hasValue: boolean;
-    readonly hasError: boolean;
-    private readonly _value;
-    private readonly _error;
-    constructor(value: T | undefined, error?: unknown);
-    get value(): T;
-    get error(): unknown;
-    get valueOrUndefined(): T | undefined;
-    static ok<T>(value: T): Result<T>;
-    static error<T>(error: unknown): Result<T>;
-}
-declare function result<T>(value: T, error?: unknown): Result<T>;
-declare function errorResult<T>(error: unknown): Result<T>;
-declare function resultFrom<T>(fn: () => T): Result<T>;
-declare function resultFromAsync<T>(fn: () => Promise<T>): Promise<Result<T>>;
-
 declare class RetryDelaySeq {
     readonly min: number;
     readonly max: number;
@@ -172,4 +236,4 @@ declare class RetryDelayer {
     cancelDelays(): void;
 }
 
-export { AsyncContext, AsyncContextKey, type AsyncDisposable, AsyncLock, type Disposable, DisposableBag, EventHandlerSet, type IResult, PromiseSource, Result, type RetryDelay, RetryDelayLimitExceeded, RetryDelayNone, RetryDelaySeq, RetryDelayer, RingBuffer, abortSignalKey, errorResult, resolvedVoidPromise, result, resultFrom, resultFromAsync };
+export { AsyncContext, AsyncContextKey, type AsyncDisposable, AsyncLock, type Disposable, DisposableBag, EventHandlerSet, type IResult, Log, LogLevel, LogLevelController, type LogRef, type LogScopeFns, PromiseSource, Result, type RetryDelay, RetryDelayLimitExceeded, RetryDelayNone, RetryDelaySeq, RetryDelayer, RingBuffer, abortSignalKey, createLogProvider, errorResult, initLogging, resolvedVoidPromise, result, resultFrom, resultFromAsync };

package/dist/index.d.ts

@@ -16,6 +16,96 @@ declare class DisposableBag implements Disposable, AsyncDisposable {
     disposeAsync(): Promise<void>;
 }
 
+declare enum LogLevel {
+    Debug = 1,
+    Info = 2,
+    Warn = 3,
+    Error = 4,
+    None = 1000
+}
+interface LogRef {
+    target: unknown;
+    id: number;
+}
+declare class Log {
+    readonly scope: string;
+    readonly level: LogLevel;
+    private static isInitialized;
+    private static logRefs;
+    /** User-set overrides (persisted to sessionStorage). Empty by default. */
+    static readonly minLevels: Map<string, LogLevel>;
+    /** Per-scope defaults registered by packages via createLogProvider(). */
+    static readonly scopeDefaults: Map<string, LogLevel>;
+    /** Every scope ever requested via Log.get().  Used by logLevels.dump()
+     *  so devs can discover what's available to override at runtime. */
+    static readonly knownScopes: Set<string>;
+    /** Global baseline for any scope without a default or override. */
+    static defaultMinLevel: LogLevel;
+    static loggerFactory: (scope: string, level: LogLevel) => Log;
+    log: (...data: unknown[]) => void;
+    trace: (...data: unknown[]) => void;
+    constructor(scope: string, level: LogLevel);
+    static get(scope: string): LogScopeFns;
+    static ref(data: object | null | undefined): object | null | undefined;
+    assert(predicate?: boolean, ...data: unknown[]): void;
+}
+interface LogScopeFns {
+    logScope: string;
+    debugLog: Log | null;
+    infoLog: Log | null;
+    warnLog: Log | null;
+    errorLog: Log | null;
+}
+declare function createLogProvider<TScope extends string>(prefix: string, defaults: Record<TScope, LogLevel>): (scope: TScope) => LogScopeFns;
+
+declare function initLogging(): void;
+declare class LogLevelController {
+    private minLevels;
+    constructor(minLevels: Map<string, LogLevel>);
+    /** List the current set of overrides. */
+    list(): Record<string, LogLevel>;
+    /** Print every known scope's effective level to the console as a table.
+     *  Shows: scope, effective level, the source ('override' / 'default-key' /
+     *  'package-default' / 'baseline'), and the package default for reference.
+     *  Use this from the dev console to discover what to pass to override(). */
+    dump(): void;
+    /** Override the level for a single scope.  Persisted to sessionStorage. */
+    override(scope: string, newLevel: LogLevel): void;
+    /** Override the level for every scope whose name starts with scopePrefix
+     *  (e.g. 'rpc.' to enable verbose RPC logging).  Persisted. */
+    overrideAll(scopePrefix: string, newLevel: LogLevel): void;
+    /** Reset all overrides; package defaults take effect again.  Persisted. */
+    reset(): void;
+    /** Clear all overrides (no global default unless `defaultLevel` is given). */
+    clear(defaultLevel?: LogLevel): void;
+}
+
+/** Common interface for types that carry a value-or-error outcome. */
+interface IResult<T> {
+    readonly hasValue: boolean;
+    readonly hasError: boolean;
+    readonly value: T;
+    readonly error: unknown;
+    readonly valueOrUndefined: T | undefined;
+}
+/** Immutable value-or-error container — similar to .NET's Result<T>. */
+declare class Result<T> implements IResult<T> {
+    readonly hasValue: boolean;
+    readonly hasError: boolean;
+    private readonly _value;
+    private readonly _error;
+    constructor(value: T | undefined, error?: unknown);
+    get value(): T;
+    get error(): unknown;
+    get valueOrUndefined(): T | undefined;
+    static ok<T>(value: T): Result<T>;
+    static error<T>(error: unknown): Result<T>;
+}
+declare function result<T>(value: T, error?: unknown): Result<T>;
+declare function errorResult<T>(error: unknown): Result<T>;
+declare function resultFrom<T>(fn: () => T): Result<T>;
+declare function resultFromAsync<T>(fn: () => Promise<T>): Promise<Result<T>>;
+
 /** Typed key for values stored in AsyncContext — each subsystem defines its own keys. */
 declare class AsyncContextKey<T> {
     readonly id: symbol;
@@ -119,32 +209,6 @@ declare class RingBuffer<T> {
     toArray(): T[];
 }
 
-/** Common interface for types that carry a value-or-error outcome. */
-interface IResult<T> {
-    readonly hasValue: boolean;
-    readonly hasError: boolean;
-    readonly value: T;
-    readonly error: unknown;
-    readonly valueOrUndefined: T | undefined;
-}
-/** Immutable value-or-error container — similar to .NET's Result<T>. */
-declare class Result<T> implements IResult<T> {
-    readonly hasValue: boolean;
-    readonly hasError: boolean;
-    private readonly _value;
-    private readonly _error;
-    constructor(value: T | undefined, error?: unknown);
-    get value(): T;
-    get error(): unknown;
-    get valueOrUndefined(): T | undefined;
-    static ok<T>(value: T): Result<T>;
-    static error<T>(error: unknown): Result<T>;
-}
-declare function result<T>(value: T, error?: unknown): Result<T>;
-declare function errorResult<T>(error: unknown): Result<T>;
-declare function resultFrom<T>(fn: () => T): Result<T>;
-declare function resultFromAsync<T>(fn: () => Promise<T>): Promise<Result<T>>;
-
 declare class RetryDelaySeq {
     readonly min: number;
     readonly max: number;
@@ -172,4 +236,4 @@ declare class RetryDelayer {
     cancelDelays(): void;
 }
 
-export { AsyncContext, AsyncContextKey, type AsyncDisposable, AsyncLock, type Disposable, DisposableBag, EventHandlerSet, type IResult, PromiseSource, Result, type RetryDelay, RetryDelayLimitExceeded, RetryDelayNone, RetryDelaySeq, RetryDelayer, RingBuffer, abortSignalKey, errorResult, resolvedVoidPromise, result, resultFrom, resultFromAsync };
+export { AsyncContext, AsyncContextKey, type AsyncDisposable, AsyncLock, type Disposable, DisposableBag, EventHandlerSet, type IResult, Log, LogLevel, LogLevelController, type LogRef, type LogScopeFns, PromiseSource, Result, type RetryDelay, RetryDelayLimitExceeded, RetryDelayNone, RetryDelaySeq, RetryDelayer, RingBuffer, abortSignalKey, createLogProvider, errorResult, initLogging, resolvedVoidPromise, result, resultFrom, resultFromAsync };