Skip to content

[Feature]: Promote plugin to Stable — freeze the hook-bus / DI / directive APIs #145

Description

@JosunLP

Pre-flight checklist

  • I searched existing issues and did not find a duplicate request.
  • I explained the problem or use case, not just the desired API.

Problem or use case
plugin is Beta and is the extensibility contract the whole ecosystem would build on — yet its surface is one minor old: the hook bus, DI container, async install, namespaced directives, and unuse/uninstall all arrived in 1.14.0. Third-party plugin authors cannot target a moving extension API; the contract must be frozen before an ecosystem can form.

Proposed solution
Freeze the plugin API (hook bus, DI container, install/uninstall lifecycle, namespaced directive registration) for at least one minor cycle and publish a plugin-author guide documenting the lifecycle, hook timing, DI resolution rules, and directive-namespacing conventions. Add coverage for install/uninstall symmetry (no leaked hooks/directives after uninstall). Exit criteria: frozen surface, author guide, tested lifecycle symmetry.

Possible API or UX shape

import { definePlugin } from "@bquery/bquery/plugin";

export default definePlugin({
  name: "my-plugin",
  async install(ctx) {
    ctx.provide("token", service);
    ctx.directive("my:thing", handler);
    ctx.hook("view:updated", fn);
  },
  uninstall(ctx) { /* must cleanly remove all of the above */ }
});

Alternatives considered
Promoting before freezing — would strand early plugin authors on a changing contract. Expanding the hook surface further first — fine while Beta, but it must stop for a cycle to earn Stable.

Relevant area
plugin

Additional context
A stable plugin API is a prerequisite for any community ecosystem, which is itself one of bQuery's adoption gaps versus the established frameworks. Lifecycle symmetry (clean uninstall) is the highest-risk area to test.

Metadata

Metadata

Assignees

No one assigned

    Labels

    pluginChanges to the plugin module

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions