ckeditor5-symfony 1.0.0

package/src/shared/async-registry.ts

@@ -0,0 +1,353 @@
+/**
+ * Generic async registry for objects with an async destroy method.
+ * Provides a way to register, unregister, and execute callbacks on objects by ID.
+ */
+export class AsyncRegistry<T extends Destructible> {
+  /**
+   * Map of registered items.
+   */
+  private readonly items = new Map<RegistryId | null, T>();
+
+  /**
+   * Map of initialization errors for items that failed to register.
+   */
+  private readonly initializationErrors = new Map<RegistryId | null, any>();
+
+  /**
+   * Map of pending callbacks waiting for items to be registered or fail.
+   */
+  private readonly pendingCallbacks = new Map<RegistryId | null, PendingCallbacks<T>>();
+
+  /**
+   * Set of watchers that observe changes to the registry.
+   */
+  private readonly watchers = new Set<RegistryWatcher<T>>();
+
+  /**
+   * Executes a function on an item.
+   * If the item is not yet registered, it will wait for it to be registered.
+   *
+   * @param id The ID of the item.
+   * @param onSuccess The function to execute.
+   * @param onError Optional error callback.
+   * @returns A promise that resolves with the result of the function.
+   */
+  execute<R, E extends T = T>(
+    id: RegistryId | null,
+    onSuccess: (item: E) => R,
+    onError?: (error: any) => void,
+  ): Promise<Awaited<R>> {
+    const item = this.items.get(id);
+    const error = this.initializationErrors.get(id);
+
+    // If error exists and callback provided, invoke it immediately.
+    if (error) {
+      onError?.(error);
+      return Promise.reject(error);
+    }
+
+    // If item exists, invoke callback immediately (synchronously via Promise.resolve).
+    if (item) {
+      return Promise.resolve(onSuccess(item as E));
+    }
+
+    // Item not ready yet - queue the callbacks.
+    return new Promise((resolve, reject) => {
+      const pending = this.getPendingCallbacks(id);
+
+      pending.success.push(async (item: T) => {
+        resolve(await onSuccess(item as E));
+      });
+
+      if (onError) {
+        pending.error.push(onError);
+      }
+      else {
+        pending.error.push(reject);
+      }
+    });
+  }
+
+  /**
+   * Registers an item.
+   *
+   * @param id The ID of the item.
+   * @param item The item instance.
+   */
+  register(id: RegistryId | null, item: T): void {
+    if (this.items.has(id)) {
+      throw new Error(`Item with ID "${id}" is already registered.`);
+    }
+
+    this.resetErrors(id);
+    this.items.set(id, item);
+
+    // Execute all pending callbacks for this item (synchronously).
+    const pending = this.pendingCallbacks.get(id);
+
+    if (pending) {
+      pending.success.forEach(callback => callback(item));
+      this.pendingCallbacks.delete(id);
+    }
+
+    // Register the first item as the default item (null ID).
+    this.registerAsDefault(id, item);
+    this.notifyWatchers();
+  }
+
+  /**
+   * Registers an error for an item.
+   *
+   * @param id The ID of the item.
+   * @param error The error to register.
+   */
+  error(id: RegistryId | null, error: any): void {
+    this.items.delete(id);
+    this.initializationErrors.set(id, error);
+
+    // Execute all pending error callbacks for this item.
+    const pending = this.pendingCallbacks.get(id);
+
+    if (pending) {
+      pending.error.forEach(callback => callback(error));
+      this.pendingCallbacks.delete(id);
+    }
+
+    // Set as default error if this is the first error and no items exist.
+    if (this.initializationErrors.size === 1 && !this.items.size) {
+      this.error(null, error);
+    }
+
+    // Notify watchers about the error state.
+    this.notifyWatchers();
+  }
+
+  /**
+   * Resets errors for an item.
+   *
+   * @param id The ID of the item.
+   */
+  resetErrors(id: RegistryId | null): void {
+    const { initializationErrors } = this;
+
+    // Clear default error if it's the same as the specific error.
+    if (initializationErrors.has(null) && initializationErrors.get(null) === initializationErrors.get(id)) {
+      initializationErrors.delete(null);
+    }
+
+    initializationErrors.delete(id);
+  }
+
+  /**
+   * Un-registers an item.
+   *
+   * @param id The ID of the item.
+   */
+  unregister(id: RegistryId | null): void {
+    if (!this.items.has(id)) {
+      throw new Error(`Item with ID "${id}" is not registered.`);
+    }
+
+    // If unregistering the default item, clear it.
+    if (id && this.items.get(null) === this.items.get(id)) {
+      this.unregister(null);
+    }
+
+    this.items.delete(id);
+    this.pendingCallbacks.delete(id);
+
+    this.notifyWatchers();
+  }
+
+  /**
+   * Gets all registered items.
+   *
+   * @returns An array of all registered items.
+   */
+  getItems(): T[] {
+    return Array.from(this.items.values());
+  }
+
+  /**
+   * Checks if an item with the given ID is registered.
+   *
+   * @param id The ID of the item.
+   * @returns `true` if the item is registered, `false` otherwise.
+   */
+  hasItem(id: RegistryId | null): boolean {
+    return this.items.has(id);
+  }
+
+  /**
+   * Gets a promise that resolves with the item instance for the given ID.
+   * If the item is not registered yet, it will wait for it to be registered.
+   *
+   * @param id The ID of the item.
+   * @param timeout Optional timeout in milliseconds.
+   * @returns A promise that resolves with the item instance.
+   */
+  waitFor<E extends T = T>(id: RegistryId | null, timeout?: number): Promise<E> {
+    return new Promise<E>((resolve, reject) => {
+      let exceedTimeout = false;
+      let timer: ReturnType<typeof setTimeout> | null = null;
+
+      void this.execute(
+        id,
+        (value: E) => {
+          if (exceedTimeout) {
+            return;
+          }
+
+          if (timer !== null) {
+            clearTimeout(timer!);
+          }
+
+          (resolve as (value: E) => void)(value);
+        },
+        (error: any) => {
+          if (exceedTimeout) {
+            return;
+          }
+
+          if (timer !== null) {
+            clearTimeout(timer!);
+          }
+
+          reject(error);
+        },
+      );
+
+      if (timeout) {
+        timer = setTimeout(() => {
+          exceedTimeout = true;
+          reject(new Error(`Timeout waiting for item with ID "${id}" to be registered.`));
+        }, timeout);
+      }
+    });
+  }
+
+  /**
+   * Destroys all registered items and clears the registry.
+   * This will call the `destroy` method on each item.
+   */
+  async destroyAll() {
+    const promises = (
+      Array
+        .from(new Set(this.items.values()))
+        .map(item => item.destroy())
+    );
+
+    this.items.clear();
+    this.pendingCallbacks.clear();
+
+    await Promise.all(promises);
+
+    this.notifyWatchers();
+  }
+
+  /**
+   * Registers a watcher that will be called whenever the registry changes.
+   *
+   * @param watcher The watcher function to register.
+   * @returns A function to unregister the watcher.
+   */
+  watch(watcher: RegistryWatcher<T>): () => void {
+    this.watchers.add(watcher);
+
+    // Call the watcher immediately with the current state.
+    watcher(
+      new Map(this.items),
+      new Map(this.initializationErrors),
+    );
+
+    return this.unwatch.bind(this, watcher);
+  }
+
+  /**
+   * Un-registers a watcher.
+   *
+   * @param watcher The watcher function to unregister.
+   */
+  unwatch(watcher: RegistryWatcher<T>): void {
+    this.watchers.delete(watcher);
+  }
+
+  /**
+   * Resets the registry by clearing all items, errors, and pending callbacks.
+   */
+  reset(): void {
+    this.items.clear();
+    this.initializationErrors.clear();
+    this.pendingCallbacks.clear();
+    this.notifyWatchers();
+  }
+
+  /**
+   * Notifies all watchers about changes to the registry.
+   */
+  private notifyWatchers(): void {
+    this.watchers.forEach(
+      watcher => watcher(
+        new Map(this.items),
+        new Map(this.initializationErrors),
+      ),
+    );
+  }
+
+  /**
+   * Gets or creates pending callbacks for a specific ID.
+   *
+   * @param id The ID of the item.
+   * @returns The pending callbacks structure.
+   */
+  private getPendingCallbacks(id: RegistryId | null): PendingCallbacks<T> {
+    let pending = this.pendingCallbacks.get(id);
+
+    if (!pending) {
+      pending = { success: [], error: [] };
+      this.pendingCallbacks.set(id, pending);
+    }
+
+    return pending;
+  }
+
+  /**
+   * Registers an item as the default (null ID) item if it's the first one.
+   *
+   * @param id The ID of the item being registered.
+   * @param item The item instance.
+   */
+  private registerAsDefault(id: RegistryId | null, item: T): void {
+    if (this.items.size === 1 && id !== null) {
+      this.register(null, item);
+    }
+  }
+}
+
+/**
+ * Interface for objects that can be destroyed.
+ */
+export type Destructible = {
+  destroy: () => Promise<any>;
+};
+
+/**
+ * Identifier of the registry item.
+ */
+type RegistryId = string;
+
+/**
+ * Structure holding pending success and error callbacks for an item.
+ */
+type PendingCallbacks<T> = {
+  success: Array<(item: T) => void>;
+  error: Array<(error: Error) => void>;
+};
+
+/**
+ * Callback type for watching registry changes.
+ */
+type RegistryWatcher<T> = (
+  items: Map<RegistryId | null, T>,
+  errors: Map<RegistryId | null, Error>,
+) => void;

package/src/shared/camel-case.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+
+import { camelCase } from './camel-case';
+
+describe('camelCase', () => {
+  it('converts kebab-case to camelCase', () => {
+    expect(camelCase('foo-bar-baz')).toBe('fooBarBaz');
+  });
+
+  it('converts snake_case to camelCase', () => {
+    expect(camelCase('foo_bar_baz')).toBe('fooBarBaz');
+  });
+
+  it('converts space separated to camelCase', () => {
+    expect(camelCase('foo bar baz')).toBe('fooBarBaz');
+  });
+
+  it('returns already camelCase string unchanged', () => {
+    expect(camelCase('fooBarBaz')).toBe('fooBarBaz');
+  });
+
+  it('handles single word', () => {
+    expect(camelCase('foo')).toBe('foo');
+  });
+
+  it('handles empty string', () => {
+    expect(camelCase('')).toBe('');
+  });
+
+  it('handles leading/trailing separators', () => {
+    expect(camelCase('-foo-bar-')).toBe('fooBar');
+    expect(camelCase('_foo_bar_')).toBe('fooBar');
+    expect(camelCase(' foo bar ')).toBe('fooBar');
+  });
+});

package/src/shared/camel-case.ts

@@ -0,0 +1,11 @@
+/**
+ * Converts a string to camelCase.
+ *
+ * @param str The string to convert
+ * @returns The camelCased string
+ */
+export function camelCase(str: string): string {
+  return str
+    .replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ''))
+    .replace(/^./, m => m.toLowerCase());
+}

package/src/shared/debounce.test.ts

@@ -0,0 +1,72 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { debounce } from './debounce';
+
+describe('debounce', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('should not call the callback immediately', () => {
+    const callback = vi.fn();
+    const debounced = debounce(100, callback);
+
+    debounced();
+
+    expect(callback).not.toHaveBeenCalled();
+  });
+
+  it('should call the callback after the specified delay', () => {
+    const callback = vi.fn();
+    const debounced = debounce(100, callback);
+
+    debounced();
+
+    vi.advanceTimersByTime(100);
+
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('should call the callback only once for multiple calls within the delay period', () => {
+    const callback = vi.fn();
+    const debounced = debounce(100, callback);
+
+    debounced();
+    debounced();
+    debounced();
+
+    vi.advanceTimersByTime(100);
+
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('should reset the timeout on subsequent calls', () => {
+    const callback = vi.fn();
+    const debounced = debounce(100, callback);
+
+    debounced();
+    vi.advanceTimersByTime(50);
+    debounced();
+    vi.advanceTimersByTime(50);
+    expect(callback).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(50);
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('should pass the arguments to the callback', () => {
+    const callback = vi.fn();
+    const debounced = debounce(100, callback);
+    const args = [1, 'test', { a: 2 }];
+
+    debounced(...args);
+
+    vi.advanceTimersByTime(100);
+
+    expect(callback).toHaveBeenCalledWith(...args);
+  });
+});

package/src/shared/debounce.ts

@@ -0,0 +1,16 @@
+export function debounce<T extends (...args: any[]) => any>(
+  delay: number,
+  callback: T,
+): (...args: Parameters<T>) => void {
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+  return (...args: Parameters<T>): void => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+
+    timeoutId = setTimeout(() => {
+      callback(...args);
+    }, delay);
+  };
+}

package/src/shared/deep-camel-case-keys.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+
+import { deepCamelCaseKeys } from './deep-camel-case-keys';
+
+describe('deepCamelCaseKeys', () => {
+  it('converts keys of a flat object', () => {
+    expect(deepCamelCaseKeys({ 'foo_bar': 1, 'baz-qux': 2 })).toEqual({ fooBar: 1, bazQux: 2 });
+  });
+
+  it('converts keys deeply in nested objects', () => {
+    const input = { foo_bar: { nested_key: 1 }, arr: [{ snake_case: 2 }] };
+    const expected = { fooBar: { nestedKey: 1 }, arr: [{ snakeCase: 2 }] };
+    expect(deepCamelCaseKeys(input)).toEqual(expected);
+  });
+
+  it('converts keys in arrays of objects', () => {
+    const input = [{ foo_bar: 1 }, { baz_qux: 2 }];
+    const expected = [{ fooBar: 1 }, { bazQux: 2 }];
+    expect(deepCamelCaseKeys(input)).toEqual(expected);
+  });
+
+  it('leaves primitives untouched', () => {
+    expect(deepCamelCaseKeys(42)).toBe(42);
+    expect(deepCamelCaseKeys('string')).toBe('string');
+    expect(deepCamelCaseKeys(null)).toBe(null);
+    expect(deepCamelCaseKeys(undefined)).toBe(undefined);
+  });
+
+  it('leaves class instances untouched', () => {
+    class MyClass { a = 1; }
+    const instance = new MyClass();
+    expect(deepCamelCaseKeys(instance)).toBe(instance);
+  });
+});

package/src/shared/deep-camel-case-keys.ts

@@ -0,0 +1,26 @@
+import { camelCase } from './camel-case';
+import { isPlainObject } from './is-plain-object';
+
+/**
+ * Recursively converts all keys of a plain object or array to camelCase.
+ * Skips class instances and leaves them untouched.
+ *
+ * @param input The object or array to process
+ */
+export function deepCamelCaseKeys<T>(input: T): T {
+  if (Array.isArray(input)) {
+    return input.map(deepCamelCaseKeys) as unknown as T;
+  }
+
+  if (isPlainObject(input)) {
+    const result: Record<string, unknown> = Object.create(null);
+
+    for (const [key, value] of Object.entries(input)) {
+      result[camelCase(key)] = deepCamelCaseKeys(value);
+    }
+
+    return result as T;
+  }
+
+  return input;
+}

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

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+
+import { filterObjectValues } from './filter-object-values';
+
+describe('filterObjectValues', () => {
+  it('should filter object values using the provided filter function', () => {
+    const obj = {
+      a: 1,
+      b: null,
+      c: undefined,
+      d: [],
+    };
+
+    const filteredObj = filterObjectValues(
+      obj,
+      value => value !== null,
+    );
+
+    expect(filteredObj).toEqual({
+      a: 1,
+      c: undefined,
+      d: [],
+    });
+  });
+});

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

@@ -0,0 +1,17 @@
+/**
+ * Filters the values of an object based on a provided filter function.
+ *
+ * @param obj The object to filter.
+ * @param filter The filter function that determines whether a value should be included.
+ * @returns A new object containing only the key-value pairs that passed the filter.
+ */
+export function filterObjectValues<T>(
+  obj: Record<string, T>,
+  filter: (value: T, key: string) => boolean,
+): Record<string, T> {
+  const filteredEntries = Object
+    .entries(obj)
+    .filter(([key, value]) => filter(value, key));
+
+  return Object.fromEntries(filteredEntries);
+}

package/src/shared/index.ts

@@ -0,0 +1,14 @@
+export * from './async-registry';
+export * from './camel-case';
+export * from './debounce';
+export * from './deep-camel-case-keys';
+export * from './filter-object-values';
+export * from './is-empty-object';
+export * from './is-plain-object';
+export * from './map-object-values';
+export * from './once';
+export * from './shallow-equal';
+export * from './timeout';
+export * from './uid';
+export * from './wait-for';
+export * from './wait-for-dom-ready';

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

@@ -0,0 +1,78 @@
+import { describe, expect, it } from 'vitest';
+
+import { isEmptyObject } from './is-empty-object';
+
+describe('isEmptyObject', () => {
+  it('should return true for empty object', () => {
+    const result = isEmptyObject({});
+    expect(result).toBe(true);
+  });
+
+  it('should return false for object with properties', () => {
+    const result = isEmptyObject({ key: 'value' });
+    expect(result).toBe(false);
+  });
+
+  it('should return false for object with multiple properties', () => {
+    const result = isEmptyObject({
+      name: 'test',
+      age: 25,
+      active: true,
+    });
+
+    expect(result).toBe(false);
+  });
+
+  it('should return false for object with undefined values', () => {
+    const result = isEmptyObject({ key: undefined });
+    expect(result).toBe(false);
+  });
+
+  it('should return false for object with null values', () => {
+    const result = isEmptyObject({ key: null });
+    expect(result).toBe(false);
+  });
+
+  it('should return false for object with empty string values', () => {
+    const result = isEmptyObject({ key: '' });
+    expect(result).toBe(false);
+  });
+
+  it('should return false for object with numeric keys', () => {
+    const result = isEmptyObject({ 0: 'value' });
+    expect(result).toBe(false);
+  });
+
+  it('should return false for arrays', () => {
+    const result = isEmptyObject([] as any);
+    expect(result).toBe(false);
+  });
+
+  it('should return false for arrays with elements', () => {
+    const result = isEmptyObject([1, 2, 3] as any);
+    expect(result).toBe(false);
+  });
+
+  it('should return false for Date objects', () => {
+    const result = isEmptyObject(new Date() as any);
+    expect(result).toBe(false);
+  });
+
+  it('should return false for custom class instances', () => {
+    class TestClass {}
+    const result = isEmptyObject(new TestClass() as any);
+    expect(result).toBe(false);
+  });
+
+  it('should return false for objects created with Object.create', () => {
+    const result = isEmptyObject(Object.create(null));
+    expect(result).toBe(false);
+  });
+
+  it('should return true for objects with inherited properties only', () => {
+    const proto = { inheritedProp: 'value' };
+    const obj = Object.create(proto);
+    const result = isEmptyObject(obj);
+    expect(result).toBe(true);
+  });
+});

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

@@ -0,0 +1,3 @@
+export function isEmptyObject(obj: Record<string, unknown>): boolean {
+  return Object.keys(obj).length === 0 && obj.constructor === Object;
+}