@gitkraken/core-gitlens 0.1.0

package/dist/utils/decorators/log.js

@@ -0,0 +1,238 @@
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+import { getParameters } from '../function.js';
+import { getDurationMilliseconds, hrtime } from '../hrtime.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;
+// Using Function type to support classes with private/protected constructors
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export function logName(fn) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+    return (target) => 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(fn) {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+    return (target) => {
+        target.prototype.toLoggable = function () {
+            const name = getLoggableName(this);
+            if (fn != null)
+                return `${name}(${fn(this)})`;
+            return name;
+        };
+    };
+}
+export function info(options) {
+    return log('info', options);
+}
+export function debug(options) {
+    return log('debug', options);
+}
+export function trace(options) {
+    return log('trace', options);
+}
+function log(logLevel, options) {
+    let argsFn;
+    let whenFn;
+    let exitFn;
+    let prefixFn;
+    let onlyExit = false;
+    let 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 = logLevel === 'trace' ? Logger.trace : logLevel === 'debug' ? Logger.debug : Logger.info;
+    return (_target, key, descriptor) => {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+        let fn;
+        let fnKey;
+        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 (...args) {
+            // 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;
+            let paramsResolved = false;
+            const resolveParams = () => {
+                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) => {
+                    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) => {
+                    let duration;
+                    let exitLogFn;
+                    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, ...params) => 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(argsFn, args, parameters) {
+    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) {
+        const paramName = parameters[++paramIndex];
+        if (formatted.length) {
+            formatted += ', ';
+        }
+        formatted += paramName
+            ? `${paramName}=${Logger.toLoggable(paramValue, paramName)}`
+            : Logger.toLoggable(paramValue);
+    }
+    return formatted || undefined;
+}
+//# sourceMappingURL=log.js.map

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

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

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

@@ -0,0 +1,17 @@
+/** Keys for memoize version invalidation */
+export type MemoizeVersionKey = 'providers';
+/** Invalidates all memoized values that depend on the given version key */
+export declare function invalidateMemoized(key: MemoizeVersionKey): void;
+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 declare function memoize(options?: Omit<MemoizeOptions<any>, 'resolver'>): (_target: any, key: string, descriptor: PropertyDescriptor) => void;
+export declare function memoize<T extends (...args: any[]) => any>(options?: MemoizeOptions<T>): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void;
+//# sourceMappingURL=memoize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memoize.d.ts","sourceRoot":"","sources":["../../src/decorators/memoize.ts"],"names":[],"mappings":"AAGA,4CAA4C;AAC5C,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC;AAa5C,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAE/D;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,CAAC,GAAG,GAAG,EAAE,GAAG,KAAK,GAAG;IAC7D,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC;IAC9C;;;;OAIG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC5B;AAED,wBAAgB,OAAO,CACtB,OAAO,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,UAAU,CAAC,GAC7C,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,kBAAkB,KAAK,IAAI,CAAC;AACvE,wBAAgB,OAAO,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACxD,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,uBAAuB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC"}

package/dist/utils/decorators/memoize.js

@@ -0,0 +1,63 @@
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+import { resolveProp } from './resolver.js';
+const versions = new Map();
+function getMemoizeVersion(key) {
+    return versions.get(key) ?? 0;
+}
+/** Invalidates all memoized values that depend on the given version key */
+export function invalidateMemoized(key) {
+    versions.set(key, (versions.get(key) ?? 0) + 1);
+}
+export function memoize(options) {
+    const opts = options ?? {};
+    return (_target, key, descriptor) => {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+        let fn;
+        let fnKey;
+        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 = 'resolver' in opts ? opts.resolver : undefined;
+        const versioned = opts.version != null;
+        let result;
+        descriptor[fnKey] = function (...args) {
+            const prop = resolveProp(memoizeKey, resolver, ...args);
+            const version = versioned ? getMemoizeVersion(opts.version) : undefined;
+            if (Object.hasOwn(this, prop)) {
+                const cached = this[prop];
+                if (versioned) {
+                    const entry = cached;
+                    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;
+        };
+    };
+}
+//# sourceMappingURL=memoize.js.map

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

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

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

@@ -0,0 +1,12 @@
+export type Resolver<T extends (...args: any[]) => any> = (...args: Parameters<T>) => string;
+/**
+ * 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 declare function setDefaultResolver(resolver: ((...args: unknown[]) => string) | undefined): void;
+export declare function resolveProp<T extends (...args: any[]) => any>(key: string, resolver: Resolver<T> | undefined, ...args: Parameters<T>): string;
+export declare function defaultResolver(...args: unknown[]): string;
+//# sourceMappingURL=resolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/decorators/resolver.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC;AAI7F;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,CAAC,GAAG,SAAS,GAAG,IAAI,CAE/F;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAC5D,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS,EACjC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GACpB,MAAM,CAgBR;AAED,wBAAgB,eAAe,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CA2B1D"}

package/dist/utils/decorators/resolver.js

@@ -0,0 +1,85 @@
+import { getScopedCounter } from '../counter.js';
+import { isLoggable } from '../loggable.js';
+let _defaultResolverOverride;
+/**
+ * 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) {
+    _defaultResolverOverride = resolver;
+}
+export function resolveProp(key, resolver, ...args) {
+    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) {
+    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();
+/**
+ * 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) {
+    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;
+    }
+}
+//# sourceMappingURL=resolver.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../src/decorators/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAI5C,IAAI,wBAAsE,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAsD;IACxF,wBAAwB,GAAG,QAAQ,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,WAAW,CAC1B,GAAW,EACX,QAAiC,EACjC,GAAG,IAAmB;IAEtB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IAElC,IAAI,QAAQ,CAAC;IACb,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;QACtB,IAAI,CAAC;YACJ,QAAQ,GAAG,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACR,QAAQ,CAAC;YACT,QAAQ,GAAG,eAAe,CAAC,GAAG,IAAI,CAAC,CAAC;QACrC,CAAC;IACF,CAAC;SAAM,CAAC;QACP,QAAQ,GAAG,eAAe,CAAC,GAAG,IAAI,CAAC,CAAC;IACrC,CAAC;IAED,OAAO,GAAG,GAAG,IAAI,QAAQ,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAG,IAAe;IACjD,IAAI,wBAAwB,IAAI,IAAI;QAAE,OAAO,wBAAwB,CAAC,GAAG,IAAI,CAAC,CAAC;IAE/E,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;IAEhD,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IACnB,IAAI,GAAG,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IAE3B,QAAQ,OAAO,GAAG,EAAE,CAAC;QACpB,KAAK,QAAQ;YACZ,OAAO,GAAG,CAAC;QAEZ,KAAK,QAAQ,CAAC;QACd,KAAK,SAAS,CAAC;QACf,KAAK,WAAW,CAAC;QACjB,KAAK,QAAQ,CAAC;QACd,KAAK,QAAQ;YACZ,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QAEpB;YACC,IAAI,GAAG,YAAY,KAAK;gBAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;YAE7C,IAAI,UAAU,CAAC,GAAG,CAAC;gBAAE,OAAO,GAAG,CAAC,UAAU,EAAE,CAAC;YAE7C,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;AACF,CAAC;AAED,MAAM,gBAAgB,GAAG,gBAAgB,EAAE,CAAC;AAC5C,MAAM,UAAU,GAAG,IAAI,OAAO,EAAkB,CAAC;AAEjD;;;;GAIG;AACH,SAAS,aAAa,CAAC,KAAc;IACpC,IAAI,CAAC;QACJ,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,EAAE,EAAE,CAAC;QACb,IAAI,EAAE,YAAY,UAAU,EAAE,CAAC;YAC9B,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAChD,IAAI,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBAC/B,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC;oBAChB,EAAE,GAAG,gBAAgB,CAAC,IAAI,EAAE,CAAC;oBAC7B,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBAC3B,CAAC;gBACD,OAAO,IAAI,EAAE,EAAE,CAAC;YACjB,CAAC;YACD,OAAO,IAAI,gBAAgB,CAAC,IAAI,EAAE,EAAE,CAAC;QACtC,CAAC;QACD,MAAM,EAAE,CAAC;IACV,CAAC;AACF,CAAC"}

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

@@ -0,0 +1,29 @@
+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 declare function sequentialize<T extends (...args: any[]) => any>(options?: SequentializeOptions<T>): (_target: any, key: string, descriptor: TypedPropertyDescriptor<T>) => void;
+export {};
+//# sourceMappingURL=sequentialize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sequentialize.d.ts","sourceRoot":"","sources":["../../src/decorators/sequentialize.ts"],"names":[],"mappings":"AAUA,UAAU,oBAAoB,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG;IAC/D;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC;IAEpD;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC;CACjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAC9D,OAAO,CAAC,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC/B,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,uBAAuB,CAAC,CAAC,CAAC,KAAK,IAAI,CA2E7E"}

package/dist/utils/decorators/sequentialize.js

@@ -0,0 +1,81 @@
+import { defaultResolver } from './resolver.js';
+/**
+ * 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(options) {
+    const getQueueKey = options?.getQueueKey;
+    const getDedupingKey = options?.getDedupingKey;
+    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 === undefined)
+            throw new Error('Not supported');
+        const serializeKey = `$sequentialize$${key}`;
+        descriptor.value = function (...args) {
+            // Compute queue key (if getQueueKey provided, otherwise use default queue)
+            const queueKey = getQueueKey?.(...args) ?? '';
+            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 = 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) ?? 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;
+            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;
+        };
+    };
+}
+//# sourceMappingURL=sequentialize.js.map

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

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

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

@@ -0,0 +1,13 @@
+/**
+ * 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 declare function serializable(target: Function): void;
+//# sourceMappingURL=serializable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serializable.d.ts","sourceRoot":"","sources":["../../src/decorators/serializable.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CA4BnD"}

package/dist/utils/decorators/serializable.js

@@ -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) {
+    // Walk the prototype chain once at module-load time to find all getter keys
+    const getterKeys = new Set();
+    let proto = target.prototype;
+    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);
+    }
+    // No getters — leave the class untouched
+    if (!getterKeys.size)
+        return;
+    // Mutate the prototype directly (same pattern as @loggable)
+    target.prototype.toJSON = function () {
+        const result = { ...this };
+        for (const key of getterKeys) {
+            if (!Object.hasOwn(result, key)) {
+                result[key] = this[key];
+            }
+        }
+        return result;
+    };
+}
+//# sourceMappingURL=serializable.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serializable.js","sourceRoot":"","sources":["../../src/decorators/serializable.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAE/D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,MAAgB;IAC5C,4EAA4E;IAC5E,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,IAAI,KAAK,GAAG,MAAM,CAAC,SAA0B,CAAC;IAC9C,OAAO,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,EAAE,CAAC;QACpD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,CAAC;YACrD,IAAI,GAAG,KAAK,aAAa;gBAAE,SAAS;YACpC,MAAM,IAAI,GAAG,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACzD,IAAI,IAAI,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC;gBACvB,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACrB,CAAC;QACF,CAAC;QACD,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAkB,CAAC;IACvD,CAAC;IAED,yCAAyC;IACzC,IAAI,CAAC,UAAU,CAAC,IAAI;QAAE,OAAO;IAE7B,4DAA4D;IAC3D,MAAM,CAAC,SAAqC,CAAC,MAAM,GAAG;QACtD,MAAM,MAAM,GAA4B,EAAE,GAAI,IAAgC,EAAE,CAAC;QACjF,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC9B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;gBACjC,MAAM,CAAC,GAAG,CAAC,GAAI,IAAgC,CAAC,GAAG,CAAC,CAAC;YACtD,CAAC;QACF,CAAC;QACD,OAAO,MAAM,CAAC;IACf,CAAC,CAAC;AACH,CAAC"}