@chidchanun/bcp 0.2.13 → 0.2.15

package/packages/client/src/plugins.mjs

@@ -0,0 +1,811 @@
+// packages/server/src/plugins.ts
+var PluginDependencyError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PluginDependencyError";
+  }
+};
+var PluginLifecycleError = class extends Error {
+  plugin;
+  phase;
+  cause;
+  constructor(plugin, phase, cause) {
+    super(
+      `BCP Plugins: ${phase} failed for plugin "${plugin}": ${formatError(cause)}`
+    );
+    this.name = "PluginLifecycleError";
+    this.plugin = plugin;
+    this.phase = phase;
+    this.cause = cause;
+  }
+};
+function definePlugin(definition) {
+  validatePluginDefinition(
+    definition
+  );
+  return definition;
+}
+function defineModule(module) {
+  if (!module || typeof module !== "object") {
+    throw new TypeError(
+      "BCP Plugins: module must be an object."
+    );
+  }
+  normalizeName(
+    module.name,
+    "module name"
+  );
+  if (!Array.isArray(module.plugins)) {
+    throw new TypeError(
+      "BCP Plugins: module plugins must be an array."
+    );
+  }
+  for (const plugin of module.plugins) {
+    validatePluginDefinition(plugin);
+  }
+  return module;
+}
+function createPluginServiceRegistry(initial) {
+  const values = /* @__PURE__ */ new Map();
+  if (initial) {
+    for (const [key, value] of initial) {
+      assertServiceKey(key);
+      if (values.has(key)) {
+        throw new Error(
+          `BCP Plugins: duplicate initial service ${formatServiceKey(key)}.`
+        );
+      }
+      values.set(key, value);
+    }
+  }
+  const registry = {
+    provide(key, value, options = {}) {
+      assertServiceKey(key);
+      if (values.has(key) && !options.replace) {
+        throw new Error(
+          `BCP Plugins: service ${formatServiceKey(key)} is already registered.`
+        );
+      }
+      values.set(key, value);
+    },
+    get(key) {
+      assertServiceKey(key);
+      if (!values.has(key)) {
+        throw new Error(
+          `BCP Plugins: service ${formatServiceKey(key)} is not registered.`
+        );
+      }
+      return values.get(key);
+    },
+    optional(key) {
+      assertServiceKey(key);
+      return values.get(key);
+    },
+    has(key) {
+      assertServiceKey(key);
+      return values.has(key);
+    },
+    delete(key) {
+      assertServiceKey(key);
+      return values.delete(key);
+    },
+    keys() {
+      return [
+        ...values.keys()
+      ];
+    }
+  };
+  return registry;
+}
+function createPluginHookBus() {
+  const hooks = /* @__PURE__ */ new Map();
+  const bus = {
+    on(name, handler) {
+      const normalized = normalizeName(
+        name,
+        "hook name"
+      );
+      if (typeof handler !== "function") {
+        throw new TypeError(
+          "BCP Plugins: hook handler must be a function."
+        );
+      }
+      let group = hooks.get(normalized);
+      if (!group) {
+        group = /* @__PURE__ */ new Set();
+        hooks.set(
+          normalized,
+          group
+        );
+      }
+      group.add(
+        handler
+      );
+      return () => {
+        group?.delete(
+          handler
+        );
+        if (group?.size === 0) {
+          hooks.delete(normalized);
+        }
+      };
+    },
+    async emit(name, payload) {
+      const normalized = normalizeName(
+        name,
+        "hook name"
+      );
+      const group = hooks.get(normalized);
+      if (!group) {
+        return;
+      }
+      for (const handler of [
+        ...group
+      ]) {
+        await handler(payload);
+      }
+    },
+    listenerCount(name) {
+      return hooks.get(
+        normalizeName(
+          name,
+          "hook name"
+        )
+      )?.size ?? 0;
+    },
+    clear(name) {
+      if (name === void 0) {
+        hooks.clear();
+        return;
+      }
+      hooks.delete(
+        normalizeName(
+          name,
+          "hook name"
+        )
+      );
+    }
+  };
+  return bus;
+}
+function createPluginHost(options = {}) {
+  const now = options.now ?? Date.now;
+  const services = createPluginServiceRegistry(
+    options.services
+  );
+  const hooks = createPluginHookBus();
+  const entries = /* @__PURE__ */ new Map();
+  const configs = {
+    ...options.configs ?? {}
+  };
+  let setupCompleted = false;
+  let started = false;
+  let closed = false;
+  let lifecycleActive = false;
+  let fatalError = null;
+  const host = {
+    services,
+    hooks,
+    get started() {
+      return started;
+    },
+    use(extension) {
+      assertMutable();
+      if (isPluginModule(extension)) {
+        defineModule(extension);
+        for (const plugin of extension.plugins) {
+          register(plugin);
+        }
+        return host;
+      }
+      register(extension);
+      return host;
+    },
+    resolveOrder() {
+      return resolvePluginOrder(
+        entries
+      );
+    },
+    async setup() {
+      assertOpen();
+      assertHealthy();
+      if (setupCompleted) {
+        return;
+      }
+      assertNotActive();
+      lifecycleActive = true;
+      try {
+        const order = resolvePluginOrder(
+          entries
+        );
+        for (const name of order) {
+          const entry = requireInternal(name);
+          if (entry.record.state !== "registered") {
+            continue;
+          }
+          entry.record.state = "setting-up";
+          try {
+            const context = createContext(entry);
+            entry.context = context;
+            await entry.definition.setup?.(
+              context
+            );
+            entry.record.state = "ready";
+            entry.record.setupAt = timestamp();
+          } catch (error) {
+            markFailed(
+              entry,
+              error
+            );
+            const lifecycleError = error instanceof PluginLifecycleError ? error : new PluginLifecycleError(
+              name,
+              "setup",
+              error
+            );
+            fatalError = lifecycleError;
+            await disposePrepared(
+              order,
+              name
+            );
+            throw lifecycleError;
+          }
+        }
+        setupCompleted = true;
+      } finally {
+        lifecycleActive = false;
+      }
+    },
+    async start() {
+      assertOpen();
+      assertHealthy();
+      if (started) {
+        return;
+      }
+      if (!setupCompleted) {
+        await host.setup();
+      }
+      assertHealthy();
+      assertNotActive();
+      lifecycleActive = true;
+      const order = resolvePluginOrder(
+        entries
+      );
+      const startedNames = [];
+      try {
+        for (const name of order) {
+          const entry = requireInternal(name);
+          if (entry.record.state !== "ready" && entry.record.state !== "stopped") {
+            continue;
+          }
+          entry.record.state = "starting";
+          try {
+            await entry.definition.start?.(
+              requireContext(entry)
+            );
+            entry.record.state = "started";
+            entry.record.startedAt = timestamp();
+            entry.record.error = void 0;
+            startedNames.push(name);
+          } catch (error) {
+            markFailed(
+              entry,
+              error
+            );
+            const lifecycleError = new PluginLifecycleError(
+              name,
+              "start",
+              error
+            );
+            fatalError = lifecycleError;
+            await stopNames(
+              [
+                ...startedNames
+              ].reverse()
+            );
+            throw lifecycleError;
+          }
+        }
+        started = true;
+      } finally {
+        lifecycleActive = false;
+      }
+    },
+    async stop() {
+      if (closed || !started) {
+        return;
+      }
+      assertNotActive();
+      lifecycleActive = true;
+      try {
+        const errors = await stopNames(
+          resolvePluginOrder(
+            entries
+          ).reverse()
+        );
+        started = false;
+        if (errors.length > 0) {
+          throw new AggregateError(
+            errors,
+            "BCP Plugins: one or more plugin stop hooks failed."
+          );
+        }
+      } finally {
+        lifecycleActive = false;
+      }
+    },
+    async close() {
+      if (closed) {
+        return;
+      }
+      const errors = [];
+      if (started) {
+        try {
+          await host.stop();
+        } catch (error) {
+          if (error instanceof AggregateError) {
+            errors.push(
+              ...error.errors
+            );
+          } else {
+            errors.push(error);
+          }
+        }
+      }
+      assertNotActive();
+      lifecycleActive = true;
+      try {
+        const order = resolvePluginOrder(
+          entries
+        ).reverse();
+        for (const name of order) {
+          const entry = requireInternal(name);
+          if (entry.disposed || !entry.context) {
+            continue;
+          }
+          try {
+            await entry.definition.dispose?.(
+              entry.context
+            );
+          } catch (error) {
+            errors.push(
+              new PluginLifecycleError(
+                name,
+                "dispose",
+                error
+              )
+            );
+          } finally {
+            entry.disposed = true;
+          }
+        }
+        hooks.clear();
+        closed = true;
+      } finally {
+        lifecycleActive = false;
+      }
+      if (errors.length > 0) {
+        throw new AggregateError(
+          errors,
+          "BCP Plugins: one or more plugin shutdown hooks failed."
+        );
+      }
+    },
+    plugin(name) {
+      const entry = entries.get(
+        normalizeName(
+          name,
+          "plugin name"
+        )
+      );
+      return entry ? cloneRecord(
+        entry.record
+      ) : null;
+    },
+    plugins() {
+      return [
+        ...entries.values()
+      ].map(
+        (entry) => cloneRecord(
+          entry.record
+        )
+      ).sort(
+        (left, right) => left.registeredAt - right.registeredAt || left.name.localeCompare(
+          right.name
+        )
+      );
+    }
+  };
+  for (const module of options.modules ?? []) {
+    host.use(module);
+  }
+  for (const plugin of options.plugins ?? []) {
+    host.use(plugin);
+  }
+  return host;
+  function register(definition) {
+    validatePluginDefinition(
+      definition
+    );
+    const name = normalizeName(
+      definition.name,
+      "plugin name"
+    );
+    if (entries.has(name)) {
+      throw new Error(
+        `BCP Plugins: plugin "${name}" is already registered.`
+      );
+    }
+    const requires = normalizeDependencyList(
+      definition.requires,
+      name,
+      "requires"
+    );
+    const optional = normalizeDependencyList(
+      definition.optional,
+      name,
+      "optional"
+    );
+    entries.set(
+      name,
+      {
+        definition: {
+          ...definition,
+          name,
+          requires,
+          optional
+        },
+        record: {
+          name,
+          version: normalizeOptionalVersion(
+            definition.version
+          ),
+          state: "registered",
+          requires,
+          optional,
+          registeredAt: timestamp()
+        },
+        disposed: false
+      }
+    );
+  }
+  function createContext(entry) {
+    const rawConfig = Object.prototype.hasOwnProperty.call(
+      configs,
+      entry.record.name
+    ) ? configs[entry.record.name] : entry.definition.config;
+    const config = parseConfig(
+      entry.definition.schema,
+      rawConfig,
+      entry.record.name
+    );
+    return {
+      name: entry.record.name,
+      config,
+      services,
+      hooks,
+      host
+    };
+  }
+  async function stopNames(names) {
+    const errors = [];
+    for (const name of names) {
+      const entry = requireInternal(name);
+      if (entry.record.state !== "started") {
+        continue;
+      }
+      entry.record.state = "stopping";
+      try {
+        await entry.definition.stop?.(
+          requireContext(entry)
+        );
+        entry.record.state = "stopped";
+        entry.record.stoppedAt = timestamp();
+      } catch (error) {
+        markFailed(
+          entry,
+          error
+        );
+        errors.push(
+          new PluginLifecycleError(
+            name,
+            "stop",
+            error
+          )
+        );
+      }
+    }
+    return errors;
+  }
+  async function disposePrepared(order, failedName) {
+    const index = order.indexOf(failedName);
+    const names = order.slice(
+      0,
+      Math.max(0, index) + 1
+    ).reverse();
+    for (const name of names) {
+      const entry = requireInternal(name);
+      if (entry.disposed || !entry.context) {
+        continue;
+      }
+      try {
+        await entry.definition.dispose?.(
+          entry.context
+        );
+      } catch {
+      } finally {
+        entry.disposed = true;
+      }
+    }
+  }
+  function requireInternal(name) {
+    const entry = entries.get(name);
+    if (!entry) {
+      throw new Error(
+        `BCP Plugins: plugin "${name}" is not registered.`
+      );
+    }
+    return entry;
+  }
+  function timestamp() {
+    const value = now();
+    if (!Number.isFinite(value)) {
+      throw new TypeError(
+        "BCP Plugins: now() must return a finite number."
+      );
+    }
+    return value;
+  }
+  function assertOpen() {
+    if (closed) {
+      throw new Error(
+        "BCP Plugins: plugin host is closed."
+      );
+    }
+  }
+  function assertHealthy() {
+    if (fatalError) {
+      throw fatalError;
+    }
+  }
+  function assertMutable() {
+    assertOpen();
+    if (setupCompleted || lifecycleActive || fatalError) {
+      throw new Error(
+        "BCP Plugins: plugins cannot be registered after setup begins or after a lifecycle failure."
+      );
+    }
+  }
+  function assertNotActive() {
+    if (lifecycleActive) {
+      throw new Error(
+        "BCP Plugins: another lifecycle transition is already running."
+      );
+    }
+  }
+}
+function resolvePluginOrder(entries) {
+  for (const entry of entries.values()) {
+    for (const dependency of entry.record.requires) {
+      if (!entries.has(dependency)) {
+        throw new PluginDependencyError(
+          `BCP Plugins: plugin "${entry.record.name}" requires missing plugin "${dependency}".`
+        );
+      }
+    }
+  }
+  const visiting = /* @__PURE__ */ new Set();
+  const visited = /* @__PURE__ */ new Set();
+  const order = [];
+  const stack = [];
+  const visit = (name) => {
+    if (visited.has(name)) {
+      return;
+    }
+    if (visiting.has(name)) {
+      const start = stack.indexOf(name);
+      const cycle = [
+        ...stack.slice(
+          Math.max(0, start)
+        ),
+        name
+      ];
+      throw new PluginDependencyError(
+        `BCP Plugins: dependency cycle detected: ${cycle.join(" -> ")}.`
+      );
+    }
+    const entry = entries.get(name);
+    if (!entry) {
+      return;
+    }
+    visiting.add(name);
+    stack.push(name);
+    for (const dependency of [
+      ...entry.record.requires,
+      ...entry.record.optional.filter(
+        (candidate) => entries.has(candidate)
+      )
+    ]) {
+      visit(dependency);
+    }
+    stack.pop();
+    visiting.delete(name);
+    visited.add(name);
+    order.push(name);
+  };
+  for (const name of entries.keys()) {
+    visit(name);
+  }
+  return order;
+}
+function validatePluginDefinition(definition) {
+  if (!definition || typeof definition !== "object") {
+    throw new TypeError(
+      "BCP Plugins: plugin definition must be an object."
+    );
+  }
+  const name = normalizeName(
+    definition.name,
+    "plugin name"
+  );
+  normalizeDependencyList(
+    definition.requires,
+    name,
+    "requires"
+  );
+  normalizeDependencyList(
+    definition.optional,
+    name,
+    "optional"
+  );
+  for (const hook of [
+    "setup",
+    "start",
+    "stop",
+    "dispose"
+  ]) {
+    const value = definition[hook];
+    if (value !== void 0 && typeof value !== "function") {
+      throw new TypeError(
+        `BCP Plugins: plugin "${name}" ${hook} must be a function.`
+      );
+    }
+  }
+  if (definition.schema !== void 0 && typeof definition.schema !== "function" && (!definition.schema || typeof definition.schema.parse !== "function")) {
+    throw new TypeError(
+      `BCP Plugins: plugin "${name}" schema must be a parser function or object with parse().`
+    );
+  }
+}
+function normalizeDependencyList(value, plugin, field) {
+  if (value === void 0) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new TypeError(
+      `BCP Plugins: plugin "${plugin}" ${field} must be an array.`
+    );
+  }
+  const normalized = value.map(
+    (item) => normalizeName(
+      item,
+      `${field} dependency`
+    )
+  );
+  if (new Set(normalized).size !== normalized.length) {
+    throw new Error(
+      `BCP Plugins: plugin "${plugin}" ${field} contains duplicate dependencies.`
+    );
+  }
+  if (normalized.includes(plugin)) {
+    throw new PluginDependencyError(
+      `BCP Plugins: plugin "${plugin}" cannot depend on itself.`
+    );
+  }
+  return normalized;
+}
+function parseConfig(parser, raw, plugin) {
+  if (!parser) {
+    return raw;
+  }
+  try {
+    return typeof parser === "function" ? parser(raw) : parser.parse(raw);
+  } catch (error) {
+    throw new PluginLifecycleError(
+      plugin,
+      "config",
+      error
+    );
+  }
+}
+function requireContext(entry) {
+  if (!entry.context) {
+    throw new Error(
+      `BCP Plugins: plugin "${entry.record.name}" has not been set up.`
+    );
+  }
+  return entry.context;
+}
+function markFailed(entry, error) {
+  entry.record.state = "failed";
+  entry.record.error = formatError(error);
+}
+function cloneRecord(record) {
+  return {
+    ...record,
+    requires: [
+      ...record.requires
+    ],
+    optional: [
+      ...record.optional
+    ]
+  };
+}
+function isPluginModule(value) {
+  return Boolean(
+    value && typeof value === "object" && Array.isArray(
+      value.plugins
+    )
+  );
+}
+function normalizeName(value, field) {
+  const text = String(value ?? "").trim();
+  if (!text) {
+    throw new TypeError(
+      `BCP Plugins: ${field} must be a non-empty string.`
+    );
+  }
+  if (text.length > 200) {
+    throw new TypeError(
+      `BCP Plugins: ${field} must not exceed 200 characters.`
+    );
+  }
+  return text;
+}
+function normalizeOptionalVersion(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return normalizeName(
+    value,
+    "plugin version"
+  );
+}
+function assertServiceKey(key) {
+  if (typeof key === "string") {
+    normalizeName(
+      key,
+      "service key"
+    );
+    return;
+  }
+  if (typeof key !== "symbol") {
+    throw new TypeError(
+      "BCP Plugins: service key must be a string or symbol."
+    );
+  }
+}
+function formatServiceKey(key) {
+  return typeof key === "symbol" ? String(key) : `"${key}"`;
+}
+function formatError(error) {
+  if (error instanceof Error) {
+    return error.message || error.name;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  try {
+    return JSON.stringify(error) ?? String(error);
+  } catch {
+    return String(error);
+  }
+}
+export {
+  PluginDependencyError,
+  PluginLifecycleError,
+  createPluginHookBus,
+  createPluginHost,
+  createPluginServiceRegistry,
+  defineModule,
+  definePlugin
+};