ckeditor5-symfony 1.0.0

package/src/shared/is-plain-object.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+
+import { isPlainObject } from './is-plain-object';
+
+describe('isPlainObject', () => {
+  it('returns true for plain objects', () => {
+    expect(isPlainObject({})).toBe(true);
+    expect(isPlainObject({ a: 1, b: 2 })).toBe(true);
+    expect(isPlainObject(Object.create(null))).toBe(true);
+  });
+
+  it('returns false for arrays', () => {
+    expect(isPlainObject([])).toBe(false);
+    expect(isPlainObject([1, 2, 3])).toBe(false);
+  });
+
+  it('returns false for null', () => {
+    expect(isPlainObject(null)).toBe(false);
+  });
+
+  it('returns false for primitives', () => {
+    expect(isPlainObject(42)).toBe(false);
+    expect(isPlainObject('string')).toBe(false);
+    expect(isPlainObject(true)).toBe(false);
+    expect(isPlainObject(undefined)).toBe(false);
+    expect(isPlainObject(Symbol('sym'))).toBe(false);
+  });
+
+  it('returns false for class instances', () => {
+    class MyClass {}
+    expect(isPlainObject(new MyClass())).toBe(false);
+  });
+
+  it('returns false for functions', () => {
+    expect(isPlainObject(() => {})).toBe(false);
+    expect(isPlainObject(() => {})).toBe(false);
+  });
+});

package/src/shared/is-plain-object.ts

@@ -0,0 +1,15 @@
+/**
+ * Utility to check if a value is a plain object (not an array, not null, not a class instance).
+ *
+ * @param value The value to check.
+ * @returns True if the value is a plain object, false otherwise.
+ */
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (Object.prototype.toString.call(value) !== '[object Object]') {
+    return false;
+  }
+
+  const proto = Object.getPrototypeOf(value);
+
+  return proto === Object.prototype || proto === null;
+}

package/src/shared/map-object-values.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+
+import { mapObjectValues } from './map-object-values';
+
+describe('mapObjectValues', () => {
+  it('should map object values using the provided mapper function', () => {
+    const input = { a: 1, b: 2, c: 3 };
+    const mapper = (value: number) => value * 2;
+    const result = mapObjectValues(input, mapper);
+
+    expect(result).toEqual({ a: 2, b: 4, c: 6 });
+  });
+
+  it('should pass the key to the mapper function', () => {
+    const input = { x: 'foo', y: 'bar' };
+    const mapper = (value: string, key: string) => `${key}:${value}`;
+    const result = mapObjectValues(input, mapper);
+
+    expect(result).toEqual({ x: 'x:foo', y: 'y:bar' });
+  });
+
+  it('should return an empty object if the input is empty', () => {
+    const input: Record<string, number> = {};
+    const mapper = (value: number) => value * 2;
+    const result = mapObjectValues(input, mapper);
+
+    expect(result).toEqual({});
+  });
+});

package/src/shared/map-object-values.ts

@@ -0,0 +1,19 @@
+/**
+ * Maps the values of an object using a provided mapper function.
+ *
+ * @param obj The object whose values will be mapped.
+ * @param mapper A function that takes a value and its key, and returns a new value.
+ * @template T The type of the original values in the object.
+ * @template U The type of the new values in the object.
+ * @returns A new object with the same keys as the original, but with values transformed by
+ */
+export function mapObjectValues<T, U>(
+  obj: Record<string, T>,
+  mapper: (value: T, key: string) => U,
+): Record<string, U> {
+  const mappedEntries = Object
+    .entries(obj)
+    .map(([key, value]) => [key, mapper(value, key)] as const);
+
+  return Object.fromEntries(mappedEntries);
+}

package/src/shared/once.test.ts

@@ -0,0 +1,116 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { once } from './once';
+
+describe('once', () => {
+  it('should call the original function only once', () => {
+    const mockFn = vi.fn().mockReturnValue('result');
+    const onceFn = once(mockFn);
+
+    onceFn();
+    onceFn();
+    onceFn();
+
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should return the same result on subsequent calls', () => {
+    const mockFn = vi.fn().mockReturnValue('test-result');
+    const onceFn = once(mockFn);
+
+    const result1 = onceFn();
+    const result2 = onceFn();
+    const result3 = onceFn();
+
+    expect(result1).toBe('test-result');
+    expect(result2).toBe('test-result');
+    expect(result3).toBe('test-result');
+  });
+
+  it('should pass arguments to the original function', () => {
+    const mockFn = vi.fn();
+    const onceFn = once(mockFn);
+
+    onceFn('arg1', 'arg2', 'arg3');
+    onceFn('different', 'args');
+
+    expect(mockFn).toHaveBeenCalledTimes(1);
+    expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2', 'arg3');
+  });
+
+  it('should preserve the context (this) when called', () => {
+    const context = { value: 'test-context' };
+    const mockFn = vi.fn(function (this: typeof context) {
+      return this.value;
+    });
+    const onceFn = once(mockFn);
+
+    const result1 = onceFn.call(context);
+    const result2 = onceFn.call({ value: 'different-context' });
+
+    expect(result1).toBe('test-context');
+    expect(result2).toBe('test-context');
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should work with functions that return undefined', () => {
+    const mockFn = vi.fn().mockReturnValue(undefined);
+    const onceFn = once(mockFn);
+
+    const result1 = onceFn();
+    const result2 = onceFn();
+
+    expect(result1).toBeUndefined();
+    expect(result2).toBeUndefined();
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should work with async functions', async () => {
+    const mockFn = vi.fn().mockResolvedValue('async-result');
+    const onceFn = once(mockFn);
+
+    const result1 = await onceFn();
+    const result2 = await onceFn();
+
+    expect(result1).toBe('async-result');
+    expect(result2).toBe('async-result');
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should maintain function signature for type safety', () => {
+    const originalFn = (a: string, b: number): string => `${a}-${b}`;
+    const onceFn = once(originalFn);
+
+    const result = onceFn('test', 42);
+
+    expect(result).toBe('test-42');
+    expect(typeof result).toBe('string');
+  });
+
+  it('should work with functions that have no parameters', () => {
+    let counter = 0;
+    const mockFn = vi.fn(() => ++counter);
+    const onceFn = once(mockFn);
+
+    const result1 = onceFn();
+    const result2 = onceFn();
+
+    expect(result1).toBe(1);
+    expect(result2).toBe(1);
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('should work with functions that return objects', () => {
+    const returnValue = { id: 1, name: 'test' };
+    const mockFn = vi.fn().mockReturnValue(returnValue);
+    const onceFn = once(mockFn);
+
+    const result1 = onceFn();
+    const result2 = onceFn();
+
+    expect(result1).toBe(returnValue);
+    expect(result2).toBe(returnValue);
+    expect(result1).toEqual({ id: 1, name: 'test' });
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+});

package/src/shared/once.ts

@@ -0,0 +1,12 @@
+export function once<T extends (...args: any[]) => any>(fn: T): T {
+  let called = false;
+  let result: ReturnType<T>;
+
+  return function (this: any, ...args: Parameters<T>): ReturnType<T> {
+    if (!called) {
+      called = true;
+      result = fn.apply(this, args);
+    }
+    return result;
+  } as T;
+}

package/src/shared/shallow-equal.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+
+import { shallowEqual } from './shallow-equal';
+
+describe('shallowEqual', () => {
+  it('should return true for identical objects', () => {
+    const obj = { a: 1, b: 2 };
+    expect(shallowEqual(obj, obj)).toBe(true);
+  });
+
+  it('should return true for objects with same primitive values', () => {
+    const objA = { a: 1, b: 'test', c: true };
+    const objB = { a: 1, b: 'test', c: true };
+    expect(shallowEqual(objA, objB)).toBe(true);
+  });
+
+  it('should return false for objects with different values', () => {
+    const objA = { a: 1, b: 2 };
+    const objB = { a: 1, b: 3 };
+    expect(shallowEqual(objA, objB)).toBe(false);
+  });
+
+  it('should return false for objects with different keys', () => {
+    const objA = { a: 1, b: 2 };
+    const objB = { a: 1, c: 2 } as any;
+    expect(shallowEqual(objA, objB)).toBe(false);
+  });
+
+  it('should return false for objects with different number of keys', () => {
+    const objA = { a: 1, b: 2 };
+    const objB = { a: 1 };
+    expect(shallowEqual(objA, objB)).toBe(false);
+  });
+
+  it('should return true for empty objects', () => {
+    expect(shallowEqual({}, {})).toBe(true);
+  });
+
+  it('should return false for nested objects with same structure but different references', () => {
+    const objA = { a: { nested: 1 } };
+    const objB = { a: { nested: 1 } };
+    expect(shallowEqual(objA, objB)).toBe(false);
+  });
+
+  it('should return true for nested objects with same reference', () => {
+    const nested = { value: 1 };
+    const objA = { a: nested };
+    const objB = { a: nested };
+    expect(shallowEqual(objA, objB)).toBe(true);
+  });
+});

package/src/shared/shallow-equal.ts

@@ -0,0 +1,30 @@
+/**
+ * Performs a shallow comparison of two objects.
+ *
+ * @param objA - The first object to compare.
+ * @param objB - The second object to compare.
+ * @returns True if the objects are shallowly equal, false otherwise.
+ */
+export function shallowEqual<T extends Record<string, unknown>>(
+  objA: T,
+  objB: T,
+): boolean {
+  if (objA === objB) {
+    return true;
+  }
+
+  const keysA = Object.keys(objA);
+  const keysB = Object.keys(objB);
+
+  if (keysA.length !== keysB.length) {
+    return false;
+  }
+
+  for (const key of keysA) {
+    if (objA[key] !== objB[key] || !Object.prototype.hasOwnProperty.call(objB, key)) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/shared/timeout.test.ts

@@ -0,0 +1,65 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { timeout } from './timeout.js';
+
+describe('timeout', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should resolve after specified milliseconds', async () => {
+    const promise = timeout(1000);
+
+    vi.advanceTimersByTime(1000);
+
+    await expect(promise).resolves.toBeUndefined();
+  });
+
+  it('should not resolve before specified time', async () => {
+    let resolved = false;
+    const promise = timeout(1000).then(() => {
+      resolved = true;
+    });
+
+    vi.advanceTimersByTime(500);
+
+    expect(resolved).toBe(false);
+
+    vi.advanceTimersByTime(500);
+    await promise;
+
+    expect(resolved).toBe(true);
+  });
+
+  it('should resolve immediately when milliseconds is 0', async () => {
+    const promise = timeout(0);
+
+    vi.advanceTimersByTime(0);
+
+    await expect(promise).resolves.toBeUndefined();
+  });
+
+  it('should handle multiple concurrent timeouts', async () => {
+    const results: number[] = [];
+
+    const promise1 = timeout(100).then(() => results.push(1));
+    const promise2 = timeout(200).then(() => results.push(2));
+    const promise3 = timeout(150).then(() => results.push(3));
+
+    vi.advanceTimersByTime(100);
+    await promise1;
+    expect(results).toEqual([1]);
+
+    vi.advanceTimersByTime(50);
+    await promise3;
+    expect(results).toEqual([1, 3]);
+
+    vi.advanceTimersByTime(50);
+    await promise2;
+    expect(results).toEqual([1, 3, 2]);
+  });
+});

package/src/shared/timeout.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns a promise that resolves after a specified number of milliseconds.
+ *
+ * @param ms The number of milliseconds to wait.
+ * @returns A promise that resolves after the specified time.
+ */
+export function timeout(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve();
+    }, ms);
+  });
+}

package/src/shared/uid.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import { uid } from './uid';
+
+describe('uid', () => {
+  it('should return a string', () => {
+    const id = uid();
+    expect(typeof id).toBe('string');
+  });
+
+  it('should return a non-empty string', () => {
+    const id = uid();
+    expect(id.length).toBeGreaterThan(0);
+  });
+
+  it('should return different values on subsequent calls', () => {
+    const ids = new Set(Array.from({ length: 1000 }, () => uid()));
+    expect(ids.size).toBe(1000);
+  });
+
+  it('should only contain alphanumeric characters', () => {
+    const id = uid();
+    expect(/^[a-z0-9]+$/i.test(id)).toBe(true);
+  });
+});

package/src/shared/uid.ts

@@ -0,0 +1,8 @@
+/**
+ * Generates a unique identifier string
+ *
+ * @returns Random string that can be used as unique identifier
+ */
+export function uid() {
+  return Math.random().toString(36).substring(2);
+}

package/src/shared/wait-for-dom-ready.test.ts

@@ -0,0 +1,87 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { timeout } from './timeout.js';
+import { waitForDOMReady } from './wait-for-dom-ready.js';
+
+describe('waitForDOMReady', () => {
+  let originalReadyState: DocumentReadyState;
+
+  beforeEach(() => {
+    originalReadyState = document.readyState;
+  });
+
+  afterEach(() => {
+    Object.defineProperty(document, 'readyState', {
+      configurable: true,
+      get() { return originalReadyState; },
+    });
+
+    vi.restoreAllMocks();
+  });
+
+  it('should resolve immediately if readyState is "interactive"', async () => {
+    Object.defineProperty(document, 'readyState', {
+      configurable: true,
+      get() { return 'interactive'; },
+    });
+
+    const spy = vi.fn();
+    void waitForDOMReady().then(spy);
+
+    await timeout(0);
+    expect(spy).toHaveBeenCalled();
+  });
+
+  it('should resolve immediately if readyState is "complete"', async () => {
+    Object.defineProperty(document, 'readyState', {
+      configurable: true,
+      get() { return 'complete'; },
+    });
+
+    const spy = vi.fn();
+    void waitForDOMReady().then(spy);
+
+    await new Promise(resolve => setTimeout(resolve, 0));
+    expect(spy).toHaveBeenCalled();
+  });
+
+  it('should wait for DOMContentLoaded event if readyState is "loading"', async () => {
+    Object.defineProperty(document, 'readyState', {
+      configurable: true,
+      get() { return 'loading'; },
+    });
+
+    const addEventListenerSpy = vi.spyOn(document, 'addEventListener');
+    const spy = vi.fn();
+
+    void waitForDOMReady().then(spy);
+
+    expect(addEventListenerSpy).toHaveBeenCalledWith('DOMContentLoaded', expect.any(Function), { once: true });
+    expect(spy).not.toHaveBeenCalled();
+
+    // Simulate the event
+    const handler = addEventListenerSpy.mock.calls[0]?.[1] as EventListener;
+    handler({} as Event);
+
+    await new Promise(resolve => setTimeout(resolve, 0));
+    expect(spy).toHaveBeenCalled();
+  });
+
+  it('should warn and resolve immediately for unexpected readyState', async () => {
+    const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    Object.defineProperty(document, 'readyState', {
+      configurable: true,
+      get() { return 'unexpected'; },
+    });
+
+    const spy = vi.fn();
+    void waitForDOMReady().then(spy);
+
+    await timeout(0);
+    expect(consoleWarnSpy).toHaveBeenCalledWith('Unexpected document.readyState:', 'unexpected');
+    expect(spy).toHaveBeenCalled();
+
+    consoleWarnSpy.mockRestore();
+  });
+});

package/src/shared/wait-for-dom-ready.ts

@@ -0,0 +1,21 @@
+/**
+ * Returns a promise that resolves when the DOM is fully loaded and ready.
+ */
+export function waitForDOMReady(): Promise<void> {
+  return new Promise((resolve) => {
+    switch (document.readyState) {
+      case 'loading':
+        document.addEventListener('DOMContentLoaded', () => resolve(), { once: true });
+        break;
+
+      case 'interactive':
+      case 'complete':
+        setTimeout(resolve, 0);
+        break;
+
+      default:
+        console.warn('Unexpected document.readyState:', document.readyState);
+        setTimeout(resolve, 0);
+    }
+  });
+}

package/src/shared/wait-for.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+
+import { waitFor } from './wait-for.js';
+
+describe('waitFor', () => {
+  it('should resolve when the callback succeeds', async () => {
+    const result = await waitFor(() => Promise.resolve('success'));
+
+    expect(result).toBe('success');
+  });
+
+  it('should reject when the callback throws an error', async () => {
+    await expect(waitFor(() => Promise.reject(new Error('failed')))).rejects.toThrow('failed');
+  });
+
+  it('should reject when the timeout is reached', async () => {
+    await expect(
+      waitFor(() => new Promise(resolve => setTimeout(resolve, 2000)), {
+        timeOutAfter: 200,
+        retryAfter: 100,
+      }),
+    ).rejects.toThrow('Timeout');
+  });
+});

package/src/shared/wait-for.ts

@@ -0,0 +1,56 @@
+import type { CanBePromise } from '../types';
+
+/**
+ * Waits for the provided callback to succeed. The callback is executed multiple times until it succeeds or the timeout is reached.
+ * It's executed immediately and then with a delay defined by the `retry` option.
+ *
+ * @param callback The callback to execute.
+ * @param config Configuration for the function.
+ * @param config.timeOutAfter The maximum time to wait for the callback to succeed, in milliseconds. Default is 500ms.
+ * @param config.retryAfter The time to wait between retries, in milliseconds. Default is 100ms.
+ * @returns A promise that resolves when the callback succeeds.
+ */
+export function waitFor<R>(
+  callback: () => CanBePromise<R>,
+  {
+    timeOutAfter = 500,
+    retryAfter = 100,
+  }: WaitForConfig = {},
+): Promise<R> {
+  return new Promise<R>((resolve, reject) => {
+    const startTime = Date.now();
+    let lastError: Error | null = null;
+
+    const timeoutTimerId = setTimeout(() => {
+      reject(lastError ?? new Error('Timeout'));
+    }, timeOutAfter);
+
+    const tick = async () => {
+      try {
+        const result = await callback();
+        clearTimeout(timeoutTimerId);
+        resolve(result);
+      }
+      catch (err: any) {
+        lastError = err;
+
+        if (Date.now() - startTime > timeOutAfter) {
+          reject(err);
+        }
+        else {
+          setTimeout(tick, retryAfter);
+        }
+      }
+    };
+
+    void tick();
+  });
+}
+
+/**
+ * Configuration for the `waitFor` function.
+ */
+export type WaitForConfig = {
+  timeOutAfter?: number;
+  retryAfter?: number;
+};

package/src/types/can-be-promise.type.ts

@@ -0,0 +1 @@
+export type CanBePromise<T> = T | Promise<T>;

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './can-be-promise.type';
+export * from './required-by.type';

package/src/types/required-by.type.ts

@@ -0,0 +1 @@
+export type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;