@gitkraken/core-gitlens 0.1.0

package/src/utils/decorators/log.ts

@@ -0,0 +1,320 @@
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+import { getParameters } from '../function.js';
+import { getDurationMilliseconds, hrtime } from '../hrtime.js';
+import type { LogLevel } from '../logger.js';
+import { customLoggableNameFns, getLoggableName, Logger } from '../logger.js';
+import {
+	createLogScope,
+	getLoggableScopeBlock,
+	getScopedLogger,
+	logScopeIdGenerator,
+	runInScope,
+} from '../logger.scoped.js';
+import { isPromise } from '../promise.js';
+
+export 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 };
+}
+
+// Using Function type to support classes with private/protected constructors
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export function logName<T>(fn: (c: T, name: string) => string): (target: Function & { prototype: T }) => void {
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+	return (target: (abstract new (...args: any[]) => T) | (Function & { prototype: T })): void =>
+		void customLoggableNameFns.set(target, fn);
+}
+
+/**
+ * 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 function loggable<T extends object>(fn?: (instance: T) => string) {
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+	return (target: (abstract new (...args: any[]) => T) | (Function & { prototype: T })): void => {
+		target.prototype.toLoggable = function (this: T): string {
+			const name = getLoggableName(this);
+			if (fn != null) return `${name}(${fn(this)})`;
+			return name;
+		};
+	};
+}
+
+export function info<T extends (...arg: any[]) => any>(
+	options?: LogOptions<T>,
+): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void {
+	return log<T>('info', options);
+}
+
+export function debug<T extends (...arg: any[]) => any>(
+	options?: LogOptions<T>,
+): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void {
+	return log<T>('debug', options);
+}
+
+export function trace<T extends (...arg: any[]) => any>(
+	options?: LogOptions<T>,
+): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void {
+	return log<T>('trace', options);
+}
+
+type PromiseType<T> = T extends Promise<infer U> ? U : T;
+
+function log<T extends (...arg: any[]) => any>(
+	logLevel: Exclude<LogLevel, 'off' | 'error' | 'warn'>,
+	options?: LogOptions<T>,
+): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void {
+	let argsFn: LogOptions<T>['args'] | undefined;
+	let whenFn: LogOptions<T>['when'] | undefined;
+	let exitFn: LogOptions<T>['exit'] | undefined;
+	let prefixFn: LogOptions<T>['prefix'] | undefined;
+	let onlyExit: NonNullable<LogOptions<T>['onlyExit']> | false = false;
+	let timing: NonNullable<LogOptions<T>['timing']> = true;
+	if (options != null) {
+		({ args: argsFn, when: whenFn, exit: exitFn, prefix: prefixFn, onlyExit = false, timing = true } = options);
+	}
+
+	const slowThreshold = typeof timing === 'object' ? timing.warnAfter : defaultSlowCallWarningThreshold;
+	const timed = timing !== false || (typeof onlyExit === 'object' && onlyExit.after > 0);
+
+	const logFn: (message: string, ...params: any[]) => void =
+		logLevel === 'trace' ? Logger.trace : logLevel === 'debug' ? Logger.debug : Logger.info;
+
+	return (_target: any, key: string, descriptor: PropertyDescriptor & Record<string, any>) => {
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+		let fn: Function | undefined;
+		let fnKey: string | undefined;
+		if (typeof descriptor.value === 'function') {
+			fn = descriptor.value;
+			fnKey = 'value';
+		} else if (typeof descriptor.get === 'function') {
+			fn = descriptor.get;
+			fnKey = 'get';
+		}
+		if (fn == null || fnKey == null) throw new Error('Not supported');
+
+		// Only extract parameter names for default formatting (when no args option provided)
+		const parameters = argsFn == null ? getParameters(fn) : [];
+
+		descriptor[fnKey] = function (this: any, ...args: Parameters<T>) {
+			// Always create scope unless logging is completely off (or condition fails)
+			// This ensures scope is available for error logging even at lower log levels
+			if (!Logger.enabled() || (whenFn != null && !whenFn.apply(this, args))) {
+				return fn.apply(this, args);
+			}
+
+			const shouldLog = Logger.enabled(logLevel);
+
+			// Get parent scope
+			const parentScope = getScopedLogger();
+			const prevScopeId = parentScope?.scopeId;
+			const scopeId = logScopeIdGenerator.next();
+
+			const instanceName = this != null ? getLoggableName(this) : undefined;
+
+			let prefix = instanceName
+				? `${getLoggableScopeBlock(scopeId, prevScopeId)} ${instanceName}.${key}`
+				: `${getLoggableScopeBlock(scopeId, prevScopeId)} ${key}`;
+
+			if (prefixFn != null) {
+				prefix = prefixFn(
+					{
+						id: scopeId,
+						instance: this,
+						instanceName: instanceName ?? '',
+						name: key,
+						prefix: prefix,
+					},
+					...args,
+				);
+			}
+
+			const scope = createLogScope(scopeId, prevScopeId, prefix);
+
+			// Lazy parameter formatting — deferred until first use to avoid
+			// expensive Logger.toLoggable() calls when the log won't be emitted
+			let loggableParams: string | undefined;
+			let paramsResolved = false;
+			const resolveParams = (): string | undefined => {
+				if (!paramsResolved) {
+					paramsResolved = true;
+					loggableParams = formatParams(argsFn, args, parameters);
+				}
+				return loggableParams;
+			};
+
+			// For non-onlyExit mode, log entry immediately
+			if (!onlyExit && shouldLog) {
+				const params = resolveParams();
+				logFn.call(Logger, params ? `${prefix}(${params})` : prefix);
+			}
+
+			if (onlyExit || timed || exitFn != null) {
+				const start = timed ? hrtime() : undefined;
+
+				const logError = (ex: unknown) => {
+					const duration = start !== undefined ? ` [${getDurationMilliseconds(start)}ms]` : '';
+					const exitInfo = scope.getExitInfo();
+					if (onlyExit) {
+						const params = resolveParams();
+						Logger.error(
+							ex,
+							params ? `${prefix}(${params})` : prefix,
+							exitInfo?.details ? `failed${exitInfo.details}${duration}` : `failed${duration}`,
+						);
+					} else {
+						Logger.error(
+							ex,
+							prefix,
+							exitInfo?.details ? `failed${exitInfo.details}${duration}` : `failed${duration}`,
+						);
+					}
+				};
+
+				const logResult = (r: any) => {
+					let duration: number | undefined;
+					let exitLogFn: typeof logFn;
+					let durationSuffix;
+					if (start != null) {
+						duration = getDurationMilliseconds(start);
+						if (duration > slowThreshold) {
+							exitLogFn = Logger.warn;
+							durationSuffix = ` [*${duration}ms] (slow)`;
+						} else {
+							exitLogFn = logFn;
+							durationSuffix = ` [${duration}ms]`;
+						}
+					} else {
+						durationSuffix = '';
+						exitLogFn = logFn;
+					}
+
+					const exitInfo = scope.getExitInfo();
+					let exit;
+					if (exitFn != null) {
+						if (typeof exitFn === 'function') {
+							try {
+								exit = exitFn(r);
+							} catch (ex) {
+								exit = `@log.exit error: ${ex}`;
+							}
+						} else if (exitFn === true) {
+							exit = `returned ${Logger.toLoggable(r)}`;
+						}
+					} else if (exitInfo?.failed) {
+						exit = exitInfo.failed;
+						exitLogFn = (message: string, ...params: any[]) => Logger.error(null, message, ...params);
+					} else {
+						exit = 'completed';
+					}
+
+					// Only log if: logging at this level, or slow call warning, or error
+					if (shouldLog || exitLogFn !== logFn) {
+						const params = resolveParams();
+						if (onlyExit) {
+							if (onlyExit === true || onlyExit.after === 0 || duration! > onlyExit.after) {
+								exitLogFn.call(
+									Logger,
+									params
+										? `${prefix}(${params}) ${exit}${exitInfo?.details || ''}${durationSuffix}`
+										: `${prefix} ${exit}${exitInfo?.details || ''}${durationSuffix}`,
+								);
+							}
+						} else {
+							exitLogFn.call(
+								Logger,
+								params
+									? `${prefix}(${params}) ${exit}${exitInfo?.details || ''}${durationSuffix}`
+									: `${prefix} ${exit}${exitInfo?.details || ''}${durationSuffix}`,
+							);
+						}
+					}
+				};
+
+				const execute = () => {
+					let result;
+					try {
+						result = fn.apply(this, args);
+					} catch (ex) {
+						logError(ex);
+						throw ex;
+					}
+
+					if (result != null && isPromise(result)) {
+						result.then(logResult, logError);
+					} else {
+						logResult(result);
+					}
+
+					return result;
+				};
+
+				// Run within scope context
+				return runInScope(scope, execute);
+			}
+
+			return runInScope(scope, () => fn.apply(this, args));
+		};
+	};
+}
+
+function formatParams<T extends (...args: any[]) => any>(
+	argsFn: LogOptions<T>['args'] | undefined,
+	args: Parameters<T>,
+	parameters: string[],
+): string | undefined {
+	if (argsFn === false || !args.length) return undefined;
+
+	// Function form: call it and format the returned Record
+	if (typeof argsFn === 'function') {
+		const result = argsFn(...args);
+		if (result === false) return undefined;
+
+		let formatted = '';
+		for (const [name, value] of Object.entries(result)) {
+			if (formatted.length) {
+				formatted += ', ';
+			}
+			formatted += `${name}=${Logger.toLoggable(value, name)}`;
+		}
+		return formatted || undefined;
+	}
+
+	// Default: use parameter names from getParameters()
+	let formatted = '';
+	let paramIndex = -1;
+	for (const paramValue of args as unknown[]) {
+		const paramName = parameters[++paramIndex];
+		if (formatted.length) {
+			formatted += ', ';
+		}
+		formatted += paramName
+			? `${paramName}=${Logger.toLoggable(paramValue, paramName)}`
+			: Logger.toLoggable(paramValue);
+	}
+	return formatted || undefined;
+}

package/src/utils/decorators/memoize.ts

@@ -0,0 +1,98 @@
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+import { resolveProp } from './resolver.js';
+
+/** Keys for memoize version invalidation */
+export type MemoizeVersionKey = 'providers';
+
+interface MemoizeVersionedEntry {
+	version: number;
+	value: unknown;
+}
+
+const versions = new Map<MemoizeVersionKey, number>();
+
+function getMemoizeVersion(key: MemoizeVersionKey): number {
+	return versions.get(key) ?? 0;
+}
+
+/** Invalidates all memoized values that depend on the given version key */
+export function invalidateMemoized(key: MemoizeVersionKey): void {
+	versions.set(key, (versions.get(key) ?? 0) + 1);
+}
+
+export interface MemoizeOptions<T extends (...arg: any) => any> {
+	/** Custom resolver for generating cache keys from arguments */
+	resolver?: (...args: Parameters<T>) => string;
+	/**
+	 * Version key for cache invalidation.
+	 * When invalidateMemoized(key) is called, all memoized values
+	 * with this version key will be invalidated (cache miss on next call).
+	 */
+	version?: MemoizeVersionKey;
+}
+
+export function memoize(
+	options?: Omit<MemoizeOptions<any>, 'resolver'>,
+): (_target: any, key: string, descriptor: PropertyDescriptor) => void;
+export function memoize<T extends (...args: any[]) => any>(
+	options?: MemoizeOptions<T>,
+): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void;
+export function memoize<T extends (...args: any[]) => any>(
+	options?: MemoizeOptions<T>,
+): (_target: any, key: string, descriptor: PropertyDescriptor) => void {
+	const opts = options ?? {};
+
+	return (_target: any, key: string, descriptor: PropertyDescriptor & Record<string, any>): void => {
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+		let fn: Function | undefined;
+		let fnKey: string | undefined;
+
+		if (typeof descriptor.value === 'function') {
+			fn = descriptor.value;
+			fnKey = 'value';
+		} else if (typeof descriptor.get === 'function') {
+			fn = descriptor.get;
+			fnKey = 'get';
+		} else {
+			throw new Error('Not supported');
+		}
+
+		if (fn == null) throw new Error('Not supported');
+
+		const memoizeKey = `$memoize$${key}`;
+
+		const resolver: MemoizeOptions<T>['resolver'] | undefined = 'resolver' in opts ? opts.resolver : undefined;
+		const versioned = opts.version != null;
+
+		let result;
+		descriptor[fnKey] = function (...args: any[]) {
+			const prop = resolveProp(memoizeKey, resolver, ...(args as Parameters<T>));
+			const version = versioned ? getMemoizeVersion(opts.version!) : undefined;
+
+			if (Object.hasOwn(this, prop)) {
+				const cached = this[prop];
+				if (versioned) {
+					const entry = cached as MemoizeVersionedEntry;
+					if (entry.version === version) {
+						return entry.value;
+					}
+				} else {
+					return cached;
+				}
+			}
+
+			result = fn.apply(this, args);
+			// Note: rejected promises are cached like any other result — this prevents
+			// hammering a failing source on every call. If auto-invalidation on rejection
+			// is needed, add a configurable option here.
+			Object.defineProperty(this, prop, {
+				configurable: true,
+				enumerable: false,
+				writable: versioned,
+				value: versioned ? { version: version, value: result } : result,
+			});
+
+			return result;
+		};
+	};
+}

package/src/utils/decorators/resolver.ts

@@ -0,0 +1,95 @@
+import { getScopedCounter } from '../counter.js';
+import { isLoggable } from '../loggable.js';
+
+export type Resolver<T extends (...args: any[]) => any> = (...args: Parameters<T>) => string;
+
+let _defaultResolverOverride: ((...args: unknown[]) => string) | undefined;
+
+/**
+ * Sets a custom default resolver that will be used by `defaultResolver`, `resolveProp`,
+ * and all decorators that depend on them (`@gate`, `@sequentialize`, `@memoize`).
+ *
+ * Call this early in your application startup to inject environment-specific argument resolution
+ * (e.g., handling VS Code Uri, CancellationToken, or other platform-specific types).
+ */
+export function setDefaultResolver(resolver: ((...args: unknown[]) => string) | undefined): void {
+	_defaultResolverOverride = resolver;
+}
+
+export function resolveProp<T extends (...args: any[]) => any>(
+	key: string,
+	resolver: Resolver<T> | undefined,
+	...args: Parameters<T>
+): string {
+	if (args.length === 0) return key;
+
+	let resolved;
+	if (resolver != null) {
+		try {
+			resolved = resolver(...args);
+		} catch {
+			debugger;
+			resolved = defaultResolver(...args);
+		}
+	} else {
+		resolved = defaultResolver(...args);
+	}
+
+	return `${key}$${resolved}`;
+}
+
+export function defaultResolver(...args: unknown[]): string {
+	if (_defaultResolverOverride != null) return _defaultResolverOverride(...args);
+
+	if (args.length === 0) return '';
+	if (args.length > 1) return safeStringify(args);
+
+	const [arg] = args;
+	if (arg == null) return '';
+
+	switch (typeof arg) {
+		case 'string':
+			return arg;
+
+		case 'number':
+		case 'boolean':
+		case 'undefined':
+		case 'symbol':
+		case 'bigint':
+			return String(arg);
+
+		default:
+			if (arg instanceof Error) return String(arg);
+
+			if (isLoggable(arg)) return arg.toLoggable();
+
+			return safeStringify(arg);
+	}
+}
+
+const _fallbackCounter = getScopedCounter();
+const _objectIds = new WeakMap<object, number>();
+
+/**
+ * JSON.stringify with protection against RangeError from objects
+ * that serialize beyond JavaScript's string length limit.
+ * Returns a stable identity per object via WeakMap.
+ */
+function safeStringify(value: unknown): string {
+	try {
+		return JSON.stringify(value);
+	} catch (ex) {
+		if (ex instanceof RangeError) {
+			if (value != null && typeof value === 'object') {
+				let id = _objectIds.get(value);
+				if (id == null) {
+					id = _fallbackCounter.next();
+					_objectIds.set(value, id);
+				}
+				return `#${id}`;
+			}
+			return `#${_fallbackCounter.next()}`;
+		}
+		throw ex;
+	}
+}

package/src/utils/decorators/sequentialize.ts

@@ -0,0 +1,116 @@
+import { defaultResolver } from './resolver.js';
+
+interface SequentializeState {
+	promise: Promise<any>;
+	waiting?: {
+		key: string;
+		promise: Promise<any>;
+	};
+}
+
+interface SequentializeOptions<T extends (...args: any[]) => any> {
+	/**
+	 * Optional function to resolve arguments into a deduplication key.
+	 * Consecutive duplicate calls (same deduplication key) that haven't started yet are deduplicated and share the same result.
+	 * If omitted, uses the default resolver which deduplicates based on argument values.
+	 */
+	getDedupingKey?: (...args: Parameters<T>) => string;
+
+	/**
+	 * Optional function to resolve arguments into a queue key.
+	 * Calls with the same queue key execute sequentially in that queue.
+	 * Calls with different queue keys execute in parallel (different queues).
+	 * If omitted, all calls share a single queue.
+	 */
+	getQueueKey?: (...args: Parameters<T>) => string;
+}
+
+/**
+ * Method decorator that ensures all calls to the decorated async method are executed sequentially.
+ * If the method is called multiple times before a previous invocation completes, subsequent calls are queued and executed one after another.
+ *
+ * Consecutive duplicate calls (same arguments) that haven't started yet are deduplicated and share the same result.
+ *
+ * @param options Optional options object:
+ *   - getQueueKey: Groups calls into parallel queues
+ *   - getDedupingKey: Deduplicates consecutive calls within each queue
+ *   - If omitted: Uses default resolver for deduplication, single queue for all calls
+ */
+export function sequentialize<T extends (...args: any[]) => any>(
+	options?: SequentializeOptions<T>,
+): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void {
+	const getQueueKey = options?.getQueueKey;
+	const getDedupingKey = options?.getDedupingKey;
+
+	return (_target: any, key: string, descriptor: PropertyDescriptor) => {
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+		let fn: Function | undefined;
+		if (typeof descriptor.value === 'function') {
+			fn = descriptor.value;
+		} else if (typeof descriptor.get === 'function') {
+			fn = descriptor.get;
+		}
+		if (fn === undefined) throw new Error('Not supported');
+
+		const serializeKey = `$sequentialize$${key}`;
+
+		descriptor.value = function (this: any, ...args: any[]) {
+			// Compute queue key (if getQueueKey provided, otherwise use default queue)
+			const queueKey = getQueueKey?.(...(args as Parameters<T>)) ?? '';
+			const prop = queueKey ? `${serializeKey}$${queueKey}` : serializeKey;
+
+			if (!Object.hasOwn(this, prop)) {
+				Object.defineProperty(this, prop, {
+					configurable: false,
+					enumerable: false,
+					writable: true,
+					value: undefined,
+				});
+			}
+
+			const state: SequentializeState | undefined = this[prop];
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-return
+			const run = async () => await fn.apply(this, args);
+
+			// Compute the dedupe key once
+			const dedupeKey = getDedupingKey?.(...(args as Parameters<T>)) ?? defaultResolver(...args);
+
+			// If there's a waiting call, check if we can deduplicate with it and return the same promise as the waiting call
+			if (state?.waiting?.key === dedupeKey) return state.waiting.promise;
+
+			// Chain this call after the current promise (or start fresh if no state)
+			let promise: Promise<any>;
+			if (state == null) {
+				// No existing state, start fresh and don't set waiting (it starts immediately)
+				promise = run();
+				this[prop] = { promise: promise };
+			} else {
+				// Chain after existing promise with a single handler for both success and error
+				const clearWaitingAndRun = () => {
+					// Clear waiting status when this call starts running
+					const s = this[prop];
+					if (s?.waiting?.promise === promise) {
+						s.waiting = undefined;
+					}
+					return run();
+				};
+
+				promise = state.promise.then(clearWaitingAndRun, clearWaitingAndRun);
+
+				// Update state with this call as the new waiting call
+				state.promise = promise;
+				state.waiting = { key: dedupeKey, promise: promise };
+			}
+
+			// Cleanup when done
+			void promise.finally(() => {
+				const s = this[prop];
+				if (s?.promise === promise && s.waiting == null) {
+					this[prop] = undefined;
+				}
+			});
+
+			return promise;
+		};
+	};
+}

package/src/utils/decorators/serializable.ts

@@ -0,0 +1,42 @@
+/* eslint-disable @typescript-eslint/no-unsafe-function-type */
+
+/**
+ * Class decorator that adds a `toJSON()` method materializing all prototype getters into the
+ * serialized output. This ensures that computed properties survive `JSON.stringify` and
+ * structured-clone boundaries (e.g. IPC between extension host and webviews).
+ *
+ * The prototype chain is walked **once at decoration time** — the resulting getter key list is
+ * captured in a closure, so per-instance `toJSON()` is just a fast array loop with no reflection.
+ *
+ * If the class has no prototype getters the decorator returns immediately without modifying the
+ * class — zero cost for pure-data models.
+ */
+export function serializable(target: Function): void {
+	// Walk the prototype chain once at module-load time to find all getter keys
+	const getterKeys = new Set<string>();
+	let proto = target.prototype as object | null;
+	while (proto != null && proto !== Object.prototype) {
+		for (const key of Object.getOwnPropertyNames(proto)) {
+			if (key === 'constructor') continue;
+			const desc = Object.getOwnPropertyDescriptor(proto, key);
+			if (desc?.get != null) {
+				getterKeys.add(key);
+			}
+		}
+		proto = Object.getPrototypeOf(proto) as object | null;
+	}
+
+	// No getters — leave the class untouched
+	if (!getterKeys.size) return;
+
+	// Mutate the prototype directly (same pattern as @loggable)
+	(target.prototype as Record<string, unknown>).toJSON = function (this: object): Record<string, unknown> {
+		const result: Record<string, unknown> = { ...(this as Record<string, unknown>) };
+		for (const key of getterKeys) {
+			if (!Object.hasOwn(result, key)) {
+				result[key] = (this as Record<string, unknown>)[key];
+			}
+		}
+		return result;
+	};
+}