@gitkraken/core-gitlens 0.1.0

package/dist/utils/debounce.js

@@ -0,0 +1,209 @@
+/**
+ * Creates a debounced function that delays invoking the provided function until after `wait` milliseconds
+ * have elapsed since the last time the debounced function was invoked. The debounced function also has `cancel`,
+ * `flush`, and `pending` methods to control its behavior.
+ *
+ * @template F - The type of function.
+ * @param {F} fn - The function to debounce.
+ * @param {number} wait - The number of milliseconds to delay.
+ * @param {DebounceOptions} options - The options object
+ * @param {AbortSignal} options.cancellation - An optional AbortSignal to cancel the debounced function.
+ * @param {Array<'leading' | 'trailing'>} options.edges - When to invoke the debounced function.
+ * @param {number} options.maxWait - Maximum time to wait before forcing execution.
+ * @param {Function} options.aggregator - Optional function to aggregate arguments from multiple calls.
+ * @returns A new debounced function with additional control methods.
+ *
+ * @example
+ * const debouncedFunction = debounce(() => {
+ *   console.log('Function executed');
+ *   return 'result';
+ * }, 1000, { maxWait: 5000 });
+ *
+ * // Will log 'Function executed' after 1 second if not called again in that time
+ * const result = debouncedFunction();
+ *
+ * // Check if there's a pending execution
+ * if (debouncedFunction.pending()) {
+ *   console.log('Function execution is pending');
+ * }
+ *
+ * // Will not log anything as the previous call is cancelled
+ * debouncedFunction.cancel();
+ *
+ * // With AbortSignal
+ * const controller = new AbortController();
+ * const signal = controller.signal;
+ * const debouncedWithSignal = debounce(() => {
+ *  console.log('Function executed');
+ * }, 1000, { signal });
+ *
+ * debouncedWithSignal();
+ *
+ * // Will cancel the debounced function call
+ * controller.abort();
+ *
+ * // With argument aggregation
+ * const debouncedSum = debounce(
+ *   (numbers: number[]) => console.log(`Sum: ${numbers.reduce((a, b) => a + b, 0)}`),
+ *   1000,
+ *   {
+ *     aggregator: (prev: [number[]], next: [number[]]) => {
+ *       return [[...prev[0], ...next[0]]];
+ *     }
+ *   }
+ * );
+ *
+ * debouncedSum([1, 2]);
+ * debouncedSum([3, 4]);
+ * // After 1 second, will log: "Sum: 10"
+ */
+export function debounce(fn, wait, options) {
+    let lastThis = undefined;
+    let lastArgs;
+    let lastCallTime;
+    let lastInvokeTime = 0;
+    let result;
+    let timer;
+    let maxTimer;
+    let edges;
+    let maxWait;
+    let cancellation;
+    let aggregator;
+    if (options != null) {
+        ({ edges, maxWait, cancellation, aggregator } = options);
+    }
+    edges ??= 'trailing';
+    const leading = edges === 'leading' || edges === 'both';
+    const trailing = edges === 'trailing' || edges === 'both';
+    function invoke() {
+        if (lastArgs != null) {
+            lastInvokeTime = Date.now();
+            const args = lastArgs;
+            const thisArg = lastThis;
+            lastThis = undefined;
+            lastArgs = undefined;
+            result = fn.apply(thisArg, args);
+            return result;
+        }
+        return undefined;
+    }
+    function shouldInvoke(time) {
+        const timeSinceLastCall = time - (lastCallTime ?? 0);
+        const timeSinceLastInvoke = time - lastInvokeTime;
+        // Either this is the first call, activity has stopped and we're at the
+        // trailing edge, the system time has gone backwards and we're treating
+        // it as the trailing edge, or we've hit the maxWait limit
+        return (lastCallTime == null ||
+            timeSinceLastCall >= wait ||
+            timeSinceLastCall < 0 ||
+            (maxWait != null && timeSinceLastInvoke >= maxWait));
+    }
+    function timerExpired() {
+        const time = Date.now();
+        if (shouldInvoke(time)) {
+            if (trailing) {
+                invoke();
+            }
+            cancel();
+            return;
+        }
+        // Timer fired early (setTimeout is not guaranteed to be precise) —
+        // reschedule for the remaining time instead of dropping the pending call
+        timer = setTimeout(() => {
+            timer = undefined;
+            timerExpired();
+        }, wait - (time - (lastCallTime ?? 0)));
+    }
+    function schedule() {
+        cancelTimer();
+        const time = Date.now();
+        lastCallTime = time;
+        // Set up regular debounce timer
+        timer = setTimeout(() => {
+            timer = undefined;
+            timerExpired();
+        }, wait);
+        // Set up maxWait timer if needed
+        if (maxWait != null && !maxTimer) {
+            // Initialize lastInvokeTime on the first call of a new cycle
+            // (0 = initial state or after cancel). Without this, the maxWait
+            // calculation uses epoch 0 and triggers immediate invocation.
+            if (lastInvokeTime === 0) {
+                lastInvokeTime = time;
+            }
+            const timeWaiting = maxWait - (time - lastInvokeTime);
+            if (timeWaiting > 0) {
+                maxTimer = setTimeout(() => {
+                    maxTimer = undefined;
+                    if (trailing && lastArgs != null) {
+                        invoke();
+                    }
+                    // Don't call cancel() here - just reset the maxTimer
+                    lastInvokeTime = Date.now();
+                }, timeWaiting);
+            }
+            else {
+                // If we've already exceeded maxWait, invoke immediately
+                if (trailing && lastArgs != null) {
+                    invoke();
+                }
+                cancel();
+            }
+        }
+    }
+    function cancelTimer() {
+        if (timer != null) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+    }
+    function cancelMaxTimer() {
+        if (maxTimer != null) {
+            clearTimeout(maxTimer);
+            maxTimer = undefined;
+        }
+    }
+    function cancel() {
+        cancelTimer();
+        cancelMaxTimer();
+        lastThis = undefined;
+        lastArgs = undefined;
+        lastCallTime = undefined;
+        lastInvokeTime = 0;
+    }
+    function flush() {
+        cancelTimer();
+        cancelMaxTimer();
+        return invoke();
+    }
+    function pending() {
+        return timer != null || maxTimer != null;
+    }
+    function debounced(...args) {
+        if (cancellation?.aborted)
+            return undefined;
+        const time = Date.now();
+        // Handle argument aggregation if provided
+        if (aggregator != null && lastArgs != null) {
+            lastArgs = aggregator(lastArgs, args);
+        }
+        else {
+            // eslint-disable-next-line @typescript-eslint/no-this-alias
+            lastThis = this;
+            lastArgs = args;
+        }
+        const isFirstCall = timer == null && maxTimer == null;
+        lastCallTime = time;
+        schedule();
+        if (leading && isFirstCall) {
+            return invoke();
+        }
+        return result;
+    }
+    debounced.cancel = cancel;
+    debounced.flush = flush;
+    debounced.pending = pending;
+    cancellation?.addEventListener('abort', cancel, { once: true });
+    return debounced;
+}
+//# sourceMappingURL=debounce.js.map

package/dist/utils/debounce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.js","sourceRoot":"","sources":["../../src/utils/debounce.ts"],"names":[],"mappings":"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"}

package/dist/utils/decorators/debounce.d.ts

@@ -0,0 +1,3 @@
+import type { DebounceOptions } from '../debounce.js';
+export declare function debounce<F extends (...args: any[]) => ReturnType<F>>(wait: number, options?: DebounceOptions<F>): (_target: any, key: string, descriptor: PropertyDescriptor & Record<string, any>) => PropertyDescriptor;
+//# sourceMappingURL=debounce.d.ts.map

package/dist/utils/decorators/debounce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.d.ts","sourceRoot":"","sources":["../../src/decorators/debounce.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGtD,wBAAgB,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,IACvG,SAAS,GAAG,EAAE,KAAK,MAAM,EAAE,YAAY,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAG,kBAAkB,CA0B5G"}

package/dist/utils/decorators/debounce.js

@@ -0,0 +1,21 @@
+import { debounce as _debounce } from '../debounce.js';
+export function debounce(wait, options) {
+    return (_target, key, descriptor) => {
+        if (typeof descriptor.value !== 'function') {
+            throw new Error(`@debounce can only be used on methods, not on ${typeof descriptor.value}`);
+        }
+        const original = descriptor.value;
+        // Replace the descriptor value with a function that creates a debounced version
+        // of the original method for each instance
+        descriptor.value = function (...args) {
+            // Instance-specific storage key
+            const debounceKey = `__debounced_${key}`;
+            // Create the debounced function if it doesn't exist on this instance
+            this[debounceKey] ??= _debounce((...innerArgs) => original.apply(this, innerArgs), wait, options);
+            // Call the per-instance debounced function
+            return this[debounceKey](...args);
+        };
+        return descriptor;
+    };
+}
+//# sourceMappingURL=debounce.js.map

package/dist/utils/decorators/debounce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounce.js","sourceRoot":"","sources":["../../src/decorators/debounce.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,IAAI,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEvD,MAAM,UAAU,QAAQ,CAA8C,IAAY,EAAE,OAA4B;IAC/G,OAAO,CAAC,OAAY,EAAE,GAAW,EAAE,UAAoD,EAAsB,EAAE;QAC9G,IAAI,OAAO,UAAU,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,iDAAiD,OAAO,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC;QAC7F,CAAC;QAED,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC;QAElC,gFAAgF;QAChF,2CAA2C;QAC3C,UAAU,CAAC,KAAK,GAAG,UAAU,GAAG,IAAW;YAC1C,gCAAgC;YAChC,MAAM,WAAW,GAAG,eAAe,GAAG,EAAE,CAAC;YAEzC,qEAAqE;YACrE,IAAI,CAAC,WAAW,CAAC,KAAK,SAAS,CAC9B,CAAC,GAAG,SAAgB,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,SAAS,CAAkB,EACzE,IAAI,EACJ,OAAO,CACP,CAAC;YAEF,2CAA2C;YAC3C,OAAO,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,IAAI,CAAkB,CAAC;QACpD,CAAC,CAAC;QAEF,OAAO,UAAU,CAAC;IACnB,CAAC,CAAC;AACH,CAAC"}

package/dist/utils/decorators/gate.d.ts

@@ -0,0 +1,15 @@
+export interface GateOptions {
+    /** Timeout in milliseconds after which the gate is force-cleared and the promise resolves/rejects */
+    timeout?: number;
+    /** Whether to reject the promise on timeout (default: true) */
+    rejectOnTimeout?: boolean;
+    /** Optional callback invoked on deadlock warnings and timeout aborts */
+    onDeadlock?: (info: {
+        key: string;
+        prop: string;
+        timeout: number;
+        status: 'warning' | 'aborted';
+    }) => void;
+}
+export declare function gate<T extends (...args: any[]) => any>(getGroupingKey?: (...args: Parameters<T>) => string, options?: GateOptions): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void;
+//# sourceMappingURL=gate.d.ts.map

package/dist/utils/decorators/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/decorators/gate.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,WAAW;IAC3B,qGAAqG;IACrG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,wEAAwE;IACxE,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAAA;KAAE,KAAK,IAAI,CAAC;CAC3G;AAKD,wBAAgB,IAAI,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACrD,cAAc,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,EACnD,OAAO,CAAC,EAAE,WAAW,GACnB,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,uBAAuB,CAAC,CAAC,CAAC,KAAK,IAAI,CA6F7E"}

package/dist/utils/decorators/gate.js

@@ -0,0 +1,129 @@
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+import { CancellationError } from '../cancellation.js';
+import { createDisposable } from '../disposable.js';
+import { Logger } from '../logger.js';
+import { isPromise } from '../promise.js';
+import { resolveProp } from './resolver.js';
+// Warning thresholds in seconds for potential deadlock detection
+const deadlockWarningThresholds = [90, 180]; // 1.5 min, 3 min
+export function gate(getGroupingKey, options) {
+    let { timeout, rejectOnTimeout = true, onDeadlock } = options ?? {};
+    // Use default timeout of 5 minutes if not specified
+    timeout ??= 300000;
+    return (_target, key, descriptor) => {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+        let fn;
+        if (typeof descriptor.value === 'function') {
+            fn = descriptor.value;
+        }
+        else if (typeof descriptor.get === 'function') {
+            fn = descriptor.get;
+        }
+        if (fn == null)
+            throw new Error('Not supported');
+        const gateKey = `$gate$${key}`;
+        descriptor.value = function (...args) {
+            const prop = resolveProp(gateKey, getGroupingKey, ...args);
+            if (!Object.hasOwn(this, prop)) {
+                Object.defineProperty(this, prop, {
+                    configurable: false,
+                    enumerable: false,
+                    writable: true,
+                    value: undefined,
+                });
+            }
+            let promise = this[prop];
+            if (promise === undefined) {
+                const originalPromise = fn.apply(this, args);
+                if (originalPromise == null || !isPromise(originalPromise)) {
+                    return originalPromise;
+                }
+                if (timeout > 0) {
+                    // Apply timeout if configured - this prevents indefinite hangs
+                    const timeoutPromise = new Promise((resolve, reject) => {
+                        const timeoutId = setTimeout(() => {
+                            Logger.warn(`[gate] ${key} timeout after ${timeout}ms, forcing gate clear`, `prop=${prop}`);
+                            onDeadlock?.({ key: key, prop: prop, timeout: timeout, status: 'aborted' });
+                            // Clear the gate to allow future calls
+                            this[prop] = undefined;
+                            if (rejectOnTimeout) {
+                                reject(new CancellationError(new Error(`Gate timeout: ${key} exceeded ${timeout}ms`)));
+                            }
+                            else {
+                                // Retry the operation now that the gate is cleared
+                                const retryResult = fn.apply(this, args);
+                                if (isPromise(retryResult)) {
+                                    retryResult.then(resolve, reject);
+                                }
+                                else {
+                                    resolve(retryResult);
+                                }
+                            }
+                        }, timeout);
+                        originalPromise.then((result) => {
+                            clearTimeout(timeoutId);
+                            resolve(result);
+                        }, (error) => {
+                            clearTimeout(timeoutId);
+                            reject(error instanceof Error ? error : new Error(String(error)));
+                        });
+                    });
+                    promise = timeoutPromise;
+                }
+                else {
+                    promise = originalPromise;
+                }
+                this[prop] = promise;
+                const p = promise;
+                void p
+                    .finally(() => {
+                    if (this[prop] === p) {
+                        this[prop] = undefined;
+                    }
+                })
+                    .catch(() => { });
+                // Set up deadlock warning timeouts (only for warnings that would fire before the timeout)
+                const warningsDisposable = scheduleDeadlockWarnings(key, prop, timeout, onDeadlock);
+                void promise.finally(() => warningsDisposable.dispose()).catch(() => { });
+            }
+            return promise;
+        };
+    };
+}
+/**
+ * Schedules escalating warning timeouts for potential deadlock detection.
+ * Uses chained timers to minimize overhead - only one timer active at a time.
+ * Returns a Disposable to cancel any pending timer.
+ */
+function scheduleDeadlockWarnings(key, prop, abortTimeoutMs, onDeadlock) {
+    // Filter to only warnings that would fire before the abort timeout
+    const thresholds = abortTimeoutMs != null
+        ? deadlockWarningThresholds.filter(t => t * 1000 < abortTimeoutMs)
+        : deadlockWarningThresholds;
+    if (!thresholds.length)
+        return createDisposable(() => { });
+    let currentTimeout;
+    let thresholdIndex = 0;
+    function scheduleNext(delayMs) {
+        currentTimeout = setTimeout(() => {
+            const thresholdSecs = thresholds[thresholdIndex];
+            Logger.warn(`[gate] ${key} has been pending for ${thresholdSecs}+ seconds (possible deadlock)`, `prop=${prop}`);
+            onDeadlock?.({ key: key, prop: prop, timeout: thresholdSecs * 1000, status: 'warning' });
+            // Schedule next warning if there are more thresholds
+            thresholdIndex++;
+            if (thresholdIndex < thresholds.length) {
+                const nextDelayMs = (thresholds[thresholdIndex] - thresholdSecs) * 1000;
+                scheduleNext(nextDelayMs);
+            }
+        }, delayMs);
+    }
+    // Start with the first threshold
+    scheduleNext(thresholds[0] * 1000);
+    return createDisposable(() => {
+        if (currentTimeout != null) {
+            clearTimeout(currentTimeout);
+            currentTimeout = undefined;
+        }
+    });
+}
+//# sourceMappingURL=gate.js.map

package/dist/utils/decorators/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/decorators/gate.ts"],"names":[],"mappings":"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"}

package/dist/utils/decorators/log.d.ts

@@ -0,0 +1,46 @@
+export declare const defaultSlowCallWarningThreshold = 1500;
+export interface LogContext {
+    id: number;
+    instance: any;
+    instanceName: string;
+    name: string;
+    prefix: string;
+}
+interface LogOptions<T extends (...args: any[]) => any> {
+    /** Controls parameter formatting in log output. `false` suppresses all params. A function receives the method args and returns named fields to log (or `false` to suppress). When omitted, params are auto-formatted from parameter names. */
+    args?: false | ((...args: Parameters<T>) => Record<string, unknown> | false);
+    /** Conditionally skips logging entirely (scope, timing, everything). Must use a `function` expression (not arrow) — `this` is bound to the class instance via `.apply()`. Annotate `this` with the class type for type safety. */
+    when?(this: unknown, ...args: Parameters<T>): boolean;
+    /** Controls exit/result logging. `true` logs the return value. A function receives the result and returns a custom exit string. */
+    exit?: ((result: PromiseType<ReturnType<T>>) => string) | true;
+    /** Overrides the log line prefix. Receives a {@link LogContext} and the method args. */
+    prefix?(context: LogContext, ...args: Parameters<T>): string;
+    /** Suppresses the entry log line and only logs on exit. `{ after: N }` further suppresses exit unless duration exceeds N ms. */
+    onlyExit?: true | {
+        after: number;
+    };
+    /** Controls duration timing. `false` disables timing. `{ warnAfter: N }` overrides the slow call warning threshold (default 500ms). */
+    timing?: boolean | {
+        warnAfter: number;
+    };
+}
+export declare function logName<T>(fn: (c: T, name: string) => string): (target: Function & {
+    prototype: T;
+}) => void;
+/**
+ * Class decorator that adds a `toLoggable()` method to the prototype at runtime,
+ * making instances compatible with the `Loggable` interface without requiring the
+ * method to appear in the class's structural type.
+ *
+ * @param fn Optional function returning the content inside the parentheses.
+ * Defaults to `id` if the instance has one, otherwise just `ClassName`.
+ */
+export declare function loggable<T extends object>(fn?: (instance: T) => string): (target: (abstract new (...args: any[]) => T) | (Function & {
+    prototype: T;
+})) => void;
+export declare function info<T extends (...arg: any[]) => any>(options?: LogOptions<T>): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void;
+export declare function debug<T extends (...arg: any[]) => any>(options?: LogOptions<T>): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void;
+export declare function trace<T extends (...arg: any[]) => any>(options?: LogOptions<T>): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void;
+type PromiseType<T> = T extends Promise<infer U> ? U : T;
+export {};
+//# sourceMappingURL=log.d.ts.map

package/dist/utils/decorators/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/decorators/log.ts"],"names":[],"mappings":"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"}