@atlassian/clientside-extensions-debug 2.4.0-69e0f9e-kugbhrvw

package/lib/debug-subjects.test.ts

@@ -0,0 +1,40 @@
+import { Subject } from '@atlassian/clientside-extensions-base';
+import { DebugSubjects, observeDebugSubject, registerDebugSubject } from './debug-subjects';
+
+describe('debug-subject', () => {
+    const debugFactory = (): Subject<string> => new Subject<string>();
+
+    describe('registerDebugSubject', () => {
+        it('should create an register a subject under a given namespace', () => {
+            const subject = registerDebugSubject(DebugSubjects.Logger, debugFactory);
+            expect(subject).toBeInstanceOf(Subject);
+        });
+
+        it('should not create a new instance for a previously registered key', () => {
+            const subject = registerDebugSubject(DebugSubjects.State, debugFactory);
+            const sameSubject = registerDebugSubject(DebugSubjects.State, debugFactory);
+            expect(subject).toBe(sameSubject);
+        });
+    });
+
+    describe('observeDebugSubject', () => {
+        it('should throw if the subject does not exist yet', () => {
+            // @ts-expect-error We are using a wrong subject key here
+            const unregisteredSubject = () => observeDebugSubject('Foo', () => {});
+
+            expect(unregisteredSubject).toThrow(`No subject registered for key: "Foo"`);
+        });
+
+        it('should subscribe to a previously registered subject', () => {
+            const SUBJECT = DebugSubjects.State;
+            const TEST_PAYLOAD = 'some payload';
+
+            const observer = jest.fn();
+            const subject = registerDebugSubject(SUBJECT, debugFactory);
+            observeDebugSubject(SUBJECT, observer);
+
+            subject.notify(TEST_PAYLOAD);
+            expect(observer).toBeCalledWith(TEST_PAYLOAD);
+        });
+    });
+});

package/lib/debug-subjects.ts

@@ -0,0 +1,78 @@
+/* eslint-disable no-underscore-dangle */
+import type { Observer, Subject } from '@atlassian/clientside-extensions-base';
+
+type ExposedClientExtensionSubjects = {
+    __initialized: PropertyDescriptor;
+    subjects: PropertyDescriptor;
+};
+
+export const enum DebugSubjects {
+    Logger = 'logger',
+    State = 'state',
+}
+
+type DebugSubjectsMap<Subject> = {
+    [key in DebugSubjects]: Subject;
+};
+
+declare global {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    interface Window {
+        // Due to historical name changes the "p" still represents the old "plugin" nomenclature
+        ____c_p_s: ExposedClientExtensionSubjects;
+    }
+}
+
+const defineSubjectGlobal = () => {
+    // initialize as boolean
+    const subjectGlobal = Object.create(null);
+
+    const properties: ExposedClientExtensionSubjects = {
+        __initialized: { value: true, writable: false },
+        subjects: {
+            value: subjectGlobal,
+            writable: false,
+        },
+    };
+
+    Object.defineProperties(subjectGlobal, properties);
+
+    window.____c_p_s = subjectGlobal;
+};
+
+if (!('____c_p_s' in window) || !window.____c_p_s.__initialized) {
+    defineSubjectGlobal();
+}
+
+type UnpackPayloadType<SubjectType> = SubjectType extends Subject<infer U> ? U : never;
+
+/**
+ * Registers a debug subject as singleton
+ *
+ * @param key
+ * @param subjectFactory
+ */
+export const registerDebugSubject = <SubjectType extends Subject<PayloadType>, PayloadType = UnpackPayloadType<SubjectType>>(
+    key: DebugSubjects,
+    subjectFactory: () => SubjectType,
+): SubjectType => {
+    const debugSubjects = window.____c_p_s.subjects as DebugSubjectsMap<SubjectType>;
+
+    // good old singletons - ensure we do not register the same subject twice.
+    // we also can't fail as multiple instances might try to access the same, so instead we return the previously registered one.
+    if (!(key in debugSubjects)) {
+        debugSubjects[key] = subjectFactory();
+    }
+
+    return debugSubjects[key];
+};
+
+export const observeDebugSubject = <PayloadType>(key: DebugSubjects, observer: Observer<PayloadType>) => {
+    const debugSubjects = window.____c_p_s.subjects as DebugSubjectsMap<Subject<PayloadType>>;
+
+    if (!(key in debugSubjects)) {
+        throw new Error(`No subject registered for key: "${key}"`);
+    }
+
+    return debugSubjects[key].subscribe(observer);
+};

package/lib/debug.test.ts

@@ -0,0 +1,95 @@
+import { mocked } from 'ts-jest/utils';
+import { getLogLevel, isDebugEnabled, isLoggingEnabled } from './debug-state';
+import { onDebug } from './debug';
+import { LogLevel } from './logger/logger';
+import { observeLogger } from './logger/default-logger';
+
+jest.mock('./debug-state');
+
+describe('onDebug util', () => {
+    const orgConsole = global.console;
+
+    beforeEach(() => {
+        mocked(isDebugEnabled).mockReturnValue(false);
+        mocked(isLoggingEnabled).mockReturnValue(false);
+        mocked(getLogLevel).mockReturnValue(LogLevel.debug);
+
+        // Silent down console
+        global.console = {
+            ...orgConsole,
+            error: jest.fn(),
+            log: jest.fn(),
+            groupCollapsed: jest.fn(),
+        };
+    });
+
+    afterEach(() => {
+        mocked(isDebugEnabled).mockClear();
+        mocked(isLoggingEnabled).mockClear();
+        mocked(getLogLevel).mockClear();
+
+        global.console = orgConsole;
+    });
+
+    it('should only execute the given callback when debug and logging is enabled', () => {
+        const debugCallbackSpy = jest.fn();
+
+        // disable
+        mocked(isDebugEnabled).mockReturnValue(false);
+        mocked(isLoggingEnabled).mockReturnValue(false);
+
+        onDebug(debugCallbackSpy);
+
+        expect(debugCallbackSpy).not.toHaveBeenCalled();
+
+        // enable
+        mocked(isDebugEnabled).mockReturnValue(true);
+        mocked(isLoggingEnabled).mockReturnValue(true);
+
+        onDebug(debugCallbackSpy);
+
+        expect(debugCallbackSpy).toHaveBeenCalled();
+    });
+
+    it('should not notify the observer when logging is disabled', () => {
+        const payload = {
+            message: 'foo',
+            level: LogLevel.error,
+        };
+        const loggerCallback = jest.fn(() => payload);
+        const loggerObserver = jest.fn();
+
+        // need to enable debug in order to run the debugCallback
+        mocked(isDebugEnabled).mockReturnValue(true);
+        // disable
+        mocked(isLoggingEnabled).mockReturnValue(false);
+
+        observeLogger(loggerObserver);
+        onDebug(loggerCallback);
+
+        expect(loggerCallback).not.toHaveBeenCalled();
+        expect(loggerObserver).not.toHaveBeenCalled();
+
+        // enable
+        mocked(isLoggingEnabled).mockReturnValue(true);
+        onDebug(loggerCallback);
+
+        expect(loggerCallback).toHaveBeenCalledTimes(1);
+        expect(loggerObserver).toHaveBeenCalledWith(payload);
+    });
+
+    it('should not throw an error when logger callback fails', () => {
+        mocked(isDebugEnabled).mockReturnValue(true);
+        mocked(isLoggingEnabled).mockReturnValue(true);
+
+        const callOnDebug = () => {
+            const loggerCallback = () => {
+                throw new Error('ups');
+            };
+
+            onDebug(loggerCallback);
+        };
+
+        expect(callOnDebug).not.toThrow();
+    });
+});

package/lib/debug.ts

@@ -0,0 +1,24 @@
+import { isDebugEnabled, isLoggingEnabled } from './debug-state';
+
+import type { LoggerCallback, LoggerPayload } from './logger/logger';
+import { _loggerSubject, LogLevel } from './logger/logger';
+
+// eslint-disable-next-line import/prefer-default-export
+export const onDebug = (callback: LoggerCallback) => {
+    // Return early if both debug and logging is disabled
+    if (!isDebugEnabled() || !isLoggingEnabled()) {
+        return;
+    }
+
+    let payload: LoggerPayload | undefined;
+
+    try {
+        payload = callback(LogLevel);
+    } catch (e) {
+        // eslint-disable-next-line no-empty
+    }
+
+    if (payload) {
+        _loggerSubject.notify(payload);
+    }
+};

package/lib/index.ts

@@ -0,0 +1,23 @@
+export { onDebug } from './debug';
+export type { LoggerPayload } from './logger/logger';
+export { LogLevel } from './logger/logger';
+
+export {
+    /** @deprecated in 2.1.0 */ observeLogger,
+    /** @since in 2.1.0 */ setLogger,
+    _deregisterDefaultLogger,
+} from './logger/default-logger';
+
+export { /** @since in 2.1.0 */ consoleLogger } from './logger/console';
+
+export {
+    isDebugEnabled,
+    isLoggingEnabled,
+    isDiscoveryEnabled,
+    isValidationEnabled,
+    setDebugEnabled,
+    setLoggingEnabled,
+    setDiscoveryEnabled,
+    setValidationEnabled,
+    observeStateChange,
+} from './debug-state';

package/lib/logger/console.test.ts

@@ -0,0 +1,240 @@
+import { mocked } from 'ts-jest/utils';
+import type { LoggerPayload } from './logger';
+import { LogLevel } from './logger';
+import { consoleLogger } from './console';
+import { getLogLevel } from '../debug-state';
+
+jest.mock('../debug-state');
+
+describe('console logger', () => {
+    const orgConsole = global.console;
+
+    beforeEach(() => {
+        global.console = {
+            ...orgConsole,
+            log: jest.fn(),
+            error: jest.fn(),
+            debug: jest.fn(),
+            info: jest.fn(),
+            warn: jest.fn(),
+            groupCollapsed: jest.fn(),
+        };
+    });
+
+    afterEach(() => {
+        mocked(getLogLevel).mockClear();
+
+        global.console = orgConsole;
+    });
+
+    const getEventPayload = (level: LogLevel): LoggerPayload => ({
+        level,
+        message: 'Hello!',
+    });
+
+    describe('"DEBUG" level', () => {
+        it.each([
+            // prettier-ignore-start
+            [LogLevel.debug],
+            // prettier-ignore-end
+        ])('should display "DEBUG" log when log level is set to "%s"', (logLevel: LogLevel) => {
+            // given
+            mocked(getLogLevel).mockReturnValue(logLevel);
+            const event = getEventPayload(LogLevel.debug);
+
+            // when
+            consoleLogger(event);
+
+            // then
+            expect(global.console.debug).toHaveBeenCalledWith(expect.stringContaining('Hello!'));
+            expect(global.console.groupCollapsed).toHaveBeenCalled();
+        });
+
+        it.each([
+            // prettier-ignore-start
+            [LogLevel.error],
+            [LogLevel.warn],
+            [LogLevel.deprecation],
+            [LogLevel.info],
+            // prettier-ignore-end
+        ])('should not display "DEBUG" log when log level is set to "%s"', (logLevel: LogLevel) => {
+            // given
+            mocked(getLogLevel).mockReturnValue(logLevel);
+            const event = getEventPayload(LogLevel.debug);
+
+            // when
+            consoleLogger(event);
+
+            // then
+            expect(global.console.debug).not.toHaveBeenCalled();
+            expect(global.console.groupCollapsed).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('"ERROR" level', () => {
+        it.each([
+            // prettier-ignore-start
+            [LogLevel.debug],
+            [LogLevel.error],
+            // prettier-ignore-end
+        ])('should display "ERROR" log when log level is set to "%s"', (logLevel: LogLevel) => {
+            // given
+            mocked(getLogLevel).mockReturnValue(logLevel);
+            const event = getEventPayload(LogLevel.error);
+
+            // when
+            consoleLogger(event);
+
+            // then
+            expect(global.console.error).toHaveBeenCalledWith(expect.stringContaining('Hello!'));
+
+            if (logLevel === LogLevel.debug) {
+                // eslint-disable-next-line jest/no-conditional-expect
+                expect(global.console.groupCollapsed).toHaveBeenCalled();
+            } else {
+                // eslint-disable-next-line jest/no-conditional-expect
+                expect(global.console.groupCollapsed).not.toHaveBeenCalled();
+            }
+        });
+
+        it.each([
+            // prettier-ignore-start
+            [LogLevel.warn],
+            [LogLevel.deprecation],
+            [LogLevel.info],
+            // prettier-ignore-end
+        ])('should not display "ERROR" log when log level is set to "%s"', (logLevel: LogLevel) => {
+            // given
+            mocked(getLogLevel).mockReturnValue(logLevel);
+            const event = getEventPayload(LogLevel.error);
+
+            // when
+            consoleLogger(event);
+
+            // then
+            expect(global.console.error).not.toHaveBeenCalled();
+            expect(global.console.groupCollapsed).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('"WARN" level', () => {
+        it.each([
+            // prettier-ignore-start
+            [LogLevel.debug],
+            [LogLevel.error],
+            [LogLevel.warn],
+            // prettier-ignore-end
+        ])('should display "WARN" log when log level is set to "%s"', (logLevel: LogLevel) => {
+            // given
+            mocked(getLogLevel).mockReturnValue(logLevel);
+            const event = getEventPayload(LogLevel.warn);
+
+            // when
+            consoleLogger(event);
+
+            // then
+            expect(global.console.warn).toHaveBeenCalledWith(expect.stringContaining('Hello!'));
+
+            if (logLevel === LogLevel.debug) {
+                // eslint-disable-next-line jest/no-conditional-expect
+                expect(global.console.groupCollapsed).toHaveBeenCalled();
+            } else {
+                // eslint-disable-next-line jest/no-conditional-expect
+                expect(global.console.groupCollapsed).not.toHaveBeenCalled();
+            }
+        });
+
+        it.each([
+            // prettier-ignore-start
+            [LogLevel.deprecation],
+            [LogLevel.info],
+            // prettier-ignore-end
+        ])('should not display "WARN" log when log level is set to "%s"', (logLevel: LogLevel) => {
+            // given
+            mocked(getLogLevel).mockReturnValue(logLevel);
+            const event = getEventPayload(LogLevel.warn);
+
+            // when
+            consoleLogger(event);
+
+            // then
+            expect(global.console.warn).not.toHaveBeenCalled();
+            expect(global.console.groupCollapsed).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('"DEPRECATION" level', () => {
+        it.each([
+            // prettier-ignore-start
+            [LogLevel.debug],
+            [LogLevel.error],
+            [LogLevel.warn],
+            // prettier-ignore-end
+        ])('should display "DEPRECATION" log when log level is set to "%s"', (logLevel: LogLevel) => {
+            // given
+            mocked(getLogLevel).mockReturnValue(logLevel);
+            const event = getEventPayload(LogLevel.deprecation);
+
+            // when
+            consoleLogger(event);
+
+            // then
+            expect(global.console.warn).toHaveBeenCalledWith(expect.stringContaining('Hello!'));
+
+            if (logLevel === LogLevel.debug) {
+                // eslint-disable-next-line jest/no-conditional-expect
+                expect(global.console.groupCollapsed).toHaveBeenCalled();
+            } else {
+                // eslint-disable-next-line jest/no-conditional-expect
+                expect(global.console.groupCollapsed).not.toHaveBeenCalled();
+            }
+        });
+
+        it.each([
+            // prettier-ignore-start
+            [LogLevel.info],
+            // prettier-ignore-end
+        ])('should not display "DEPRECATION" log when log level is set to "%s"', (logLevel: LogLevel) => {
+            // given
+            mocked(getLogLevel).mockReturnValue(logLevel);
+            const event = getEventPayload(LogLevel.deprecation);
+
+            // when
+            consoleLogger(event);
+
+            // then
+            expect(global.console.warn).not.toHaveBeenCalled();
+            expect(global.console.groupCollapsed).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('"INFO" level', () => {
+        it.each([
+            // prettier-ignore-start
+            [LogLevel.debug],
+            [LogLevel.error],
+            [LogLevel.warn],
+            [LogLevel.deprecation],
+            [LogLevel.info],
+            // prettier-ignore-end
+        ])('should display "INFO" log when log level is set to "%s"', (logLevel: LogLevel) => {
+            // given
+            mocked(getLogLevel).mockReturnValue(logLevel);
+            const event = getEventPayload(LogLevel.info);
+
+            // when
+            consoleLogger(event);
+
+            // then
+            expect(global.console.info).toHaveBeenCalledWith(expect.stringContaining('Hello!'));
+
+            if (logLevel === LogLevel.debug) {
+                // eslint-disable-next-line jest/no-conditional-expect
+                expect(global.console.groupCollapsed).toHaveBeenCalled();
+            } else {
+                // eslint-disable-next-line jest/no-conditional-expect
+                expect(global.console.groupCollapsed).not.toHaveBeenCalled();
+            }
+        });
+    });
+});

package/lib/logger/console.ts

@@ -0,0 +1,73 @@
+import type { LoggerPayload } from './logger';
+import { LogLevel } from './logger';
+import { getLogLevel } from '../debug-state';
+
+const getLoggingFromLevel = (level: LogLevel): keyof typeof console => {
+    switch (level) {
+        case LogLevel.error:
+            return 'error';
+        case LogLevel.debug:
+            return 'debug';
+        case LogLevel.info:
+            return 'info';
+        case LogLevel.warn:
+        case LogLevel.deprecation:
+            return 'warn';
+        default:
+            return 'debug';
+    }
+};
+
+// Naive implementation but we can't use bitwise operators :(
+const debugLevels = Object.values(LogLevel);
+const errorLevels = debugLevels.filter((level) => level !== LogLevel.debug);
+const warnLevels = errorLevels.filter((level) => level !== LogLevel.error);
+const deprecationLevels = warnLevels.filter((level) => level !== LogLevel.warn);
+const infoLevels = deprecationLevels.filter((level) => level !== LogLevel.deprecation);
+
+const levelsMap: { [key: string]: string[] } = {
+    [LogLevel.debug]: debugLevels,
+    [LogLevel.error]: errorLevels,
+    [LogLevel.warn]: warnLevels,
+    [LogLevel.deprecation]: deprecationLevels,
+    [LogLevel.info]: infoLevels,
+};
+
+function shouldDisplayLog(logLevel: LogLevel, eventLogLevel: LogLevel) {
+    if (logLevel === LogLevel.debug) {
+        return true;
+    }
+
+    const levels = levelsMap[logLevel];
+
+    return Array.isArray(levels) ? levels.includes(eventLogLevel) : false;
+}
+
+// eslint-disable-next-line import/prefer-default-export
+export const consoleLogger = (payload: LoggerPayload) => {
+    const eventLogLevel = payload.level;
+    const logLevel = getLogLevel();
+
+    if (!shouldDisplayLog(logLevel, eventLogLevel)) {
+        return;
+    }
+
+    const consoleKey = getLoggingFromLevel(eventLogLevel);
+    const deprecationWarning =
+        payload.level === LogLevel.deprecation
+            ? `⚠️⚠️⚠️ DEPRECATION WARNING ⚠️⚠️⚠️
+`
+            : '';
+
+    console[consoleKey](`${deprecationWarning}[Atlassian Client-side Extensions]: ${payload.message}`);
+
+    // Verbose logging
+    if (logLevel === LogLevel.debug) {
+        console.groupCollapsed('  <click here for more details about above message>');
+        console.log({
+            components: payload.components,
+            meta: payload.meta,
+        });
+        console.groupEnd();
+    }
+};

package/lib/logger/default-logger.ts

@@ -0,0 +1,67 @@
+/* eslint-disable no-underscore-dangle */
+import type { Observer, Subscription } from '@atlassian/clientside-extensions-base';
+import { consoleLogger } from './console';
+import { DebugSubjects, observeDebugSubject } from '../debug-subjects';
+import type { LoggerPayload } from './logger';
+import { _loggerSubject } from './logger';
+
+declare global {
+    interface Window {
+        // clientside extension default logging deregister
+        ____c_p_d_l_d?: Subscription;
+    }
+}
+
+/**
+ * We need to keep and expose the "observeLogger" function for a legacy reason.
+ * It should be removed in CSEv3
+ *
+ * @deprecated
+ */
+export const observeLogger = (observer: Observer<LoggerPayload>): Subscription => {
+    return observeDebugSubject<LoggerPayload>(DebugSubjects.Logger, observer);
+};
+
+const registerConsoleLogger = (): Subscription => {
+    // Singleton workaround as this module may be executed more than once.
+    // We only ever want one global default logger, however.
+    if (window.____c_p_d_l_d !== undefined) {
+        return window.____c_p_d_l_d;
+    }
+
+    window.____c_p_d_l_d = observeLogger(consoleLogger);
+
+    return window.____c_p_d_l_d;
+};
+
+const deregisterLogger = (): void => {
+    if (window.____c_p_d_l_d === undefined) {
+        return;
+    }
+
+    window.____c_p_d_l_d.unsubscribe();
+};
+
+export const defaultLogger = registerConsoleLogger();
+
+/**
+ * Added in CSE 2.1.0
+ *
+ * @param logger
+ * @public
+ */
+export const setLogger = (logger: Observer<LoggerPayload>): void => {
+    if (typeof logger !== 'function') {
+        throw new Error(`Client-side Extension: The provided logger needs to be a function`);
+    }
+
+    deregisterLogger();
+    _loggerSubject.prune();
+
+    observeDebugSubject<LoggerPayload>(DebugSubjects.Logger, logger);
+};
+
+const deregisterDefaultLogger = () => defaultLogger.unsubscribe();
+
+// @VisibleForTesting
+export { deregisterDefaultLogger as _deregisterDefaultLogger };

package/lib/logger/logger.ts

@@ -0,0 +1,26 @@
+import { ReplaySubject } from '@atlassian/clientside-extensions-base';
+import { DebugSubjects, registerDebugSubject } from '../debug-subjects';
+
+export enum LogLevel {
+    debug = 'DEBUG', // Logs all the things
+    error = 'ERROR',
+    warn = 'WARN',
+    deprecation = 'DEPRECATION',
+    info = 'INFO', // The lowest level
+}
+
+export type LoggerCallback = (levels: typeof LogLevel) => LoggerPayload;
+
+export type LoggerPayload = {
+    level: LogLevel;
+    message: string;
+    components?: string | string[];
+    meta?: {
+        [key: string]: unknown;
+    };
+};
+
+const loggerSubject = registerDebugSubject(DebugSubjects.Logger, () => new ReplaySubject<LoggerPayload>(20));
+
+// Exported for internal use only
+export { loggerSubject as _loggerSubject };