@bquery/bquery 1.7.0 → 1.8.1

package/src/plugin/registry.ts

@@ -1,269 +1,284 @@
-/**
- * Global plugin registry for bQuery.
- *
- * Provides `use()` to register plugins and query helpers consumed by
- * other modules (e.g. the view module reads custom directives from here).
- *
- * @module bquery/plugin
- */
-
-import { registerCustomDirectiveResolver } from '../view/custom-directives';
-import type {
-  BQueryPlugin,
-  CustomDirective,
-  CustomDirectiveHandler,
-  PluginInstallContext,
-} from './types';
-
-// ---------------------------------------------------------------------------
-// Internal registries
-// ---------------------------------------------------------------------------
-
-/** Set of installed plugin names — prevents double-install. */
-const installedPlugins = new Set<string>();
-
-/** Custom directives contributed by plugins. */
-const customDirectives = new Map<string, CustomDirectiveHandler>();
-
-type PendingComponentRegistration = {
-  tagName: string;
-  constructor: CustomElementConstructor;
-  options?: ElementDefinitionOptions;
-};
-
-registerCustomDirectiveResolver((name) => customDirectives.get(name));
-
-/**
- * Restore the directive registry to a previously captured snapshot.
- *
- * Used to roll back partial plugin installation when `install()` or staged
- * `customElements.define()` calls fail after directives were already registered.
- *
- * @internal
- */
-const restoreDirectiveSnapshot = (
-  directivesSnapshot: ReadonlyMap<string, CustomDirectiveHandler>
-): void => {
-  customDirectives.clear();
-  for (const [name, handler] of directivesSnapshot) {
-    customDirectives.set(name, handler);
-  }
-};
-
-// ---------------------------------------------------------------------------
-// Install context factory
-// ---------------------------------------------------------------------------
-
-/**
- * Build the `PluginInstallContext` handed to each plugin's `install()`.
- * @internal
- */
-const createInstallContext = (
-  pendingComponents: PendingComponentRegistration[]
-): PluginInstallContext => ({
-  directive(name: string, handler: CustomDirectiveHandler): void {
-    if (typeof name !== 'string' || name.length === 0) {
-      throw new Error('bQuery plugin directive: name must be a non-empty string');
-    }
-    if (name.startsWith('bq-')) {
-      const suggestedName = name.slice(3);
-      throw new Error(
-        `bQuery plugin directive: name "${name}" must be provided without the "bq-" prefix` +
-          (suggestedName ? ` (use "${suggestedName}")` : '')
-      );
-    }
-    if (typeof handler !== 'function') {
-      throw new Error(`bQuery plugin directive: handler for "${name}" must be a function`);
-    }
-    if (customDirectives.has(name)) {
-      throw new Error(`bQuery plugin directive: a directive named "${name}" is already registered`);
-    }
-    customDirectives.set(name, handler);
-  },
-
-  component(
-    tagName: string,
-    constructor: CustomElementConstructor,
-    options?: ElementDefinitionOptions
-  ): void {
-    if (typeof tagName !== 'string' || tagName.length === 0) {
-      throw new Error('bQuery plugin component: tagName must be a non-empty string');
-    }
-    if (!tagName.includes('-')) {
-      throw new Error(
-        `bQuery plugin component: tagName "${tagName}" must be a valid custom element name containing a hyphen`
-      );
-    }
-    if (typeof constructor !== 'function') {
-      throw new Error(`bQuery plugin component: constructor for "${tagName}" must be a function`);
-    }
-    if (typeof customElements === 'undefined') {
-      if (typeof console !== 'undefined' && typeof console.warn === 'function') {
-        console.warn(
-          `[bQuery] plugin component "${tagName}" was not registered because customElements is not available in this environment.`
-        );
-      }
-      return;
-    }
-    // Idempotent — skip if already defined or already staged during this install
-    if (
-      !customElements.get(tagName) &&
-      !pendingComponents.some((entry) => entry.tagName === tagName)
-    ) {
-      pendingComponents.push({ tagName, constructor, options });
-    }
-  },
-});
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Register a bQuery plugin.
- *
- * Plugins are installed at most once (identified by `plugin.name`).
- * Duplicate calls with the same name are silently ignored.
- *
- * @param plugin - The plugin object implementing `{ name, install }`.
- * @param options - Optional configuration forwarded to `plugin.install()`.
- * @throws If `plugin` is not a valid plugin object.
- *
- * @example
- * ```ts
- * import { use } from '@bquery/bquery/plugin';
- *
- * use({
- *   name: 'highlight',
- *   install(ctx) {
- *     ctx.directive('highlight', (el, expr) => {
- *       (el as HTMLElement).style.background = String(expr);
- *     });
- *   },
- * });
- * ```
- */
-export const use = <TOptions = unknown>(
-  plugin: BQueryPlugin<TOptions>,
-  options?: TOptions
-): void => {
-  if (!plugin || typeof plugin !== 'object') {
-    throw new Error('bQuery plugin: use() expects a plugin object with { name, install }');
-  }
-  if (typeof plugin.name !== 'string' || plugin.name.length === 0) {
-    throw new Error('bQuery plugin: plugin must have a non-empty "name" property');
-  }
-  if (typeof plugin.install !== 'function') {
-    throw new Error(`bQuery plugin: plugin "${plugin.name}" must have an "install" function`);
-  }
-
-  // Deduplicate
-  if (installedPlugins.has(plugin.name)) return;
-
-  const pendingComponents: PendingComponentRegistration[] = [];
-  const ctx = createInstallContext(pendingComponents);
-  const directivesSnapshot = new Map(customDirectives);
-
-  try {
-    plugin.install(ctx, options);
-  } catch (error) {
-    restoreDirectiveSnapshot(directivesSnapshot);
-    throw error;
-  }
-
-  try {
-    for (const entry of pendingComponents) {
-      if (!customElements.get(entry.tagName)) {
-        customElements.define(entry.tagName, entry.constructor, entry.options);
-      }
-    }
-  } catch (error) {
-    restoreDirectiveSnapshot(directivesSnapshot);
-    throw error;
-  }
-
-  installedPlugins.add(plugin.name);
-};
-
-/**
- * Check whether a plugin with the given name has been installed.
- *
- * @param name - The plugin name to check.
- * @returns `true` if the plugin was previously installed via `use()`.
- *
- * @example
- * ```ts
- * import { isInstalled } from '@bquery/bquery/plugin';
- *
- * if (!isInstalled('my-plugin')) {
- *   use(myPlugin);
- * }
- * ```
- */
-export const isInstalled = (name: string): boolean => installedPlugins.has(name);
-
-/**
- * Return a read-only snapshot of all installed plugin names.
- *
- * @returns Array of plugin name strings.
- *
- * @example
- * ```ts
- * import { getInstalledPlugins } from '@bquery/bquery/plugin';
- * console.log(getInstalledPlugins()); // ['my-plugin', 'other-plugin']
- * ```
- */
-export const getInstalledPlugins = (): readonly string[] => [...installedPlugins];
-
-/**
- * Retrieve the handler for a custom directive registered by a plugin.
- *
- * This is used internally by the view module's `processElement` to
- * resolve directives that aren't built-in.
- *
- * @param name - Directive name **without** prefix (e.g. `'tooltip'`).
- * @returns The handler, or `undefined` if none is registered.
- *
- * @example
- * ```ts
- * import { getCustomDirective } from '@bquery/bquery/plugin';
- * const handler = getCustomDirective('tooltip');
- * ```
- */
-export const getCustomDirective = (name: string): CustomDirectiveHandler | undefined =>
-  customDirectives.get(name);
-
-/**
- * Return a read-only snapshot of all registered custom directives.
- *
- * @returns Array of `{ name, handler }` descriptors.
- *
- * @example
- * ```ts
- * import { getCustomDirectives } from '@bquery/bquery/plugin';
- * for (const { name, handler } of getCustomDirectives()) {
- *   console.log(`Directive: bq-${name}`);
- * }
- * ```
- */
-export const getCustomDirectives = (): readonly CustomDirective[] =>
-  [...customDirectives.entries()].map(([name, handler]) => ({ name, handler }));
-
-/**
- * Reset all plugin registrations.
- *
- * Clears all installed plugins and custom directives.
- *
- * This utility is primarily intended for tests and other isolated environments
- * that need to reinitialize plugin state between runs.
- *
- * @example
- * ```ts
- * import { resetPlugins } from '@bquery/bquery/plugin';
- * afterEach(() => resetPlugins());
- * ```
- */
-export const resetPlugins = (): void => {
-  installedPlugins.clear();
-  customDirectives.clear();
-};
+/**
+ * Global plugin registry for bQuery.
+ *
+ * Provides `use()` to register plugins and query helpers consumed by
+ * other modules (e.g. the view module reads custom directives from here).
+ *
+ * @module bquery/plugin
+ */
+
+import { registerCustomDirectiveResolver } from '../view/custom-directives';
+import type {
+  BQueryPlugin,
+  CustomDirective,
+  CustomDirectiveHandler,
+  PluginInstallContext,
+} from './types';
+
+// ---------------------------------------------------------------------------
+// Internal registries
+// ---------------------------------------------------------------------------
+
+/** Set of installed plugin names — prevents double-install. */
+const installedPlugins = new Set<string>();
+
+/** Custom directives contributed by plugins. */
+const customDirectives = new Map<string, CustomDirectiveHandler>();
+
+type PendingComponentRegistration = {
+  tagName: string;
+  constructor: CustomElementConstructor;
+  options?: ElementDefinitionOptions;
+};
+
+/**
+ * Ensure the view pipeline resolves plugin directives against the current registry.
+ *
+ * This is intentionally idempotent so tests or internal modules can temporarily
+ * clear the resolver without leaving plugin/view integration in a broken state.
+ *
+ * @internal
+ */
+const attachCustomDirectiveResolver = (): void => {
+  registerCustomDirectiveResolver((name) => customDirectives.get(name));
+};
+
+attachCustomDirectiveResolver();
+
+/**
+ * Restore the directive registry to a previously captured snapshot.
+ *
+ * Used to roll back partial plugin installation when `install()` or staged
+ * `customElements.define()` calls fail after directives were already registered.
+ *
+ * @internal
+ */
+const restoreDirectiveSnapshot = (
+  directivesSnapshot: ReadonlyMap<string, CustomDirectiveHandler>
+): void => {
+  customDirectives.clear();
+  for (const [name, handler] of directivesSnapshot) {
+    customDirectives.set(name, handler);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Install context factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the `PluginInstallContext` handed to each plugin's `install()`.
+ * @internal
+ */
+const createInstallContext = (
+  pendingComponents: PendingComponentRegistration[]
+): PluginInstallContext => ({
+  directive(name: string, handler: CustomDirectiveHandler): void {
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new Error('bQuery plugin directive: name must be a non-empty string');
+    }
+    if (name.startsWith('bq-')) {
+      const suggestedName = name.slice(3);
+      throw new Error(
+        `bQuery plugin directive: name "${name}" must be provided without the "bq-" prefix` +
+          (suggestedName ? ` (use "${suggestedName}")` : '')
+      );
+    }
+    if (typeof handler !== 'function') {
+      throw new Error(`bQuery plugin directive: handler for "${name}" must be a function`);
+    }
+    if (customDirectives.has(name)) {
+      throw new Error(`bQuery plugin directive: a directive named "${name}" is already registered`);
+    }
+    customDirectives.set(name, handler);
+  },
+
+  component(
+    tagName: string,
+    constructor: CustomElementConstructor,
+    options?: ElementDefinitionOptions
+  ): void {
+    if (typeof tagName !== 'string' || tagName.length === 0) {
+      throw new Error('bQuery plugin component: tagName must be a non-empty string');
+    }
+    if (!tagName.includes('-')) {
+      throw new Error(
+        `bQuery plugin component: tagName "${tagName}" must be a valid custom element name containing a hyphen`
+      );
+    }
+    if (typeof constructor !== 'function') {
+      throw new Error(`bQuery plugin component: constructor for "${tagName}" must be a function`);
+    }
+    if (typeof customElements === 'undefined') {
+      if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+        console.warn(
+          `[bQuery] plugin component "${tagName}" was not registered because customElements is not available in this environment.`
+        );
+      }
+      return;
+    }
+    // Idempotent — skip if already defined or already staged during this install
+    if (
+      !customElements.get(tagName) &&
+      !pendingComponents.some((entry) => entry.tagName === tagName)
+    ) {
+      pendingComponents.push({ tagName, constructor, options });
+    }
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Register a bQuery plugin.
+ *
+ * Plugins are installed at most once (identified by `plugin.name`).
+ * Duplicate calls with the same name are silently ignored.
+ *
+ * @param plugin - The plugin object implementing `{ name, install }`.
+ * @param options - Optional configuration forwarded to `plugin.install()`.
+ * @throws If `plugin` is not a valid plugin object.
+ *
+ * @example
+ * ```ts
+ * import { use } from '@bquery/bquery/plugin';
+ *
+ * use({
+ *   name: 'highlight',
+ *   install(ctx) {
+ *     ctx.directive('highlight', (el, expr) => {
+ *       (el as HTMLElement).style.background = String(expr);
+ *     });
+ *   },
+ * });
+ * ```
+ */
+export const use = <TOptions = unknown>(
+  plugin: BQueryPlugin<TOptions>,
+  options?: TOptions
+): void => {
+  attachCustomDirectiveResolver();
+
+  if (!plugin || typeof plugin !== 'object') {
+    throw new Error('bQuery plugin: use() expects a plugin object with { name, install }');
+  }
+  if (typeof plugin.name !== 'string' || plugin.name.length === 0) {
+    throw new Error('bQuery plugin: plugin must have a non-empty "name" property');
+  }
+  if (typeof plugin.install !== 'function') {
+    throw new Error(`bQuery plugin: plugin "${plugin.name}" must have an "install" function`);
+  }
+
+  // Deduplicate
+  if (installedPlugins.has(plugin.name)) return;
+
+  const pendingComponents: PendingComponentRegistration[] = [];
+  const ctx = createInstallContext(pendingComponents);
+  const directivesSnapshot = new Map(customDirectives);
+
+  try {
+    plugin.install(ctx, options);
+  } catch (error) {
+    restoreDirectiveSnapshot(directivesSnapshot);
+    throw error;
+  }
+
+  try {
+    for (const entry of pendingComponents) {
+      if (!customElements.get(entry.tagName)) {
+        customElements.define(entry.tagName, entry.constructor, entry.options);
+      }
+    }
+  } catch (error) {
+    restoreDirectiveSnapshot(directivesSnapshot);
+    throw error;
+  }
+
+  installedPlugins.add(plugin.name);
+};
+
+/**
+ * Check whether a plugin with the given name has been installed.
+ *
+ * @param name - The plugin name to check.
+ * @returns `true` if the plugin was previously installed via `use()`.
+ *
+ * @example
+ * ```ts
+ * import { isInstalled } from '@bquery/bquery/plugin';
+ *
+ * if (!isInstalled('my-plugin')) {
+ *   use(myPlugin);
+ * }
+ * ```
+ */
+export const isInstalled = (name: string): boolean => installedPlugins.has(name);
+
+/**
+ * Return a read-only snapshot of all installed plugin names.
+ *
+ * @returns Array of plugin name strings.
+ *
+ * @example
+ * ```ts
+ * import { getInstalledPlugins } from '@bquery/bquery/plugin';
+ * console.log(getInstalledPlugins()); // ['my-plugin', 'other-plugin']
+ * ```
+ */
+export const getInstalledPlugins = (): readonly string[] => [...installedPlugins];
+
+/**
+ * Retrieve the handler for a custom directive registered by a plugin.
+ *
+ * This is used internally by the view module's `processElement` to
+ * resolve directives that aren't built-in.
+ *
+ * @param name - Directive name **without** prefix (e.g. `'tooltip'`).
+ * @returns The handler, or `undefined` if none is registered.
+ *
+ * @example
+ * ```ts
+ * import { getCustomDirective } from '@bquery/bquery/plugin';
+ * const handler = getCustomDirective('tooltip');
+ * ```
+ */
+export const getCustomDirective = (name: string): CustomDirectiveHandler | undefined =>
+  customDirectives.get(name);
+
+/**
+ * Return a read-only snapshot of all registered custom directives.
+ *
+ * @returns Array of `{ name, handler }` descriptors.
+ *
+ * @example
+ * ```ts
+ * import { getCustomDirectives } from '@bquery/bquery/plugin';
+ * for (const { name, handler } of getCustomDirectives()) {
+ *   console.log(`Directive: bq-${name}`);
+ * }
+ * ```
+ */
+export const getCustomDirectives = (): readonly CustomDirective[] =>
+  [...customDirectives.entries()].map(([name, handler]) => ({ name, handler }));
+
+/**
+ * Reset all plugin registrations.
+ *
+ * Clears all installed plugins and custom directives.
+ *
+ * This utility is primarily intended for tests and other isolated environments
+ * that need to reinitialize plugin state between runs.
+ *
+ * @example
+ * ```ts
+ * import { resetPlugins } from '@bquery/bquery/plugin';
+ * afterEach(() => resetPlugins());
+ * ```
+ */
+export const resetPlugins = (): void => {
+  installedPlugins.clear();
+  customDirectives.clear();
+  attachCustomDirectiveResolver();
+};