@asterflow/plugin 1.0.1

package/README.md

@@ -0,0 +1,155 @@
+<div align="center">
+
+# @asterflow/plugin
+
+![license-info](https://img.shields.io/github/license/AsterFlow/AsterFlow?style=for-the-badge&colorA=302D41&colorB=f9e2af&logoColor=f9e2af)
+![stars-info](https://img.shields.io/github/stars/AsterFlow/AsterFlow?colorA=302D41&colorB=f9e2af&style=for-the-badge)
+
+![last-commit](https://img.shields.io/github/last-commit/AsterFlow/AsterFlow?style=for-the-badge&colorA=302D41&colorB=b4befe)
+![commit-activity](https://img.shields.io/github/commit-activity/y/AsterFlow/AsterFlow?style=for-the-badge&colorA=302D41&colorB=f9e2af)
+![code-size](https://img.shields.io/github/languages/code-size/AsterFlow/AsterFlow?style=for-the-badge&colorA=302D41&colorB=90dceb)
+
+![top-language](https://img.shields.io/github/languages/top/AsterFlow/AsterFlow?style=for-the-badge&colorA=302D41&colorB=90dceb)
+![bundle-size](https://img.shields.io/bundlejs/size/@asterflow/plugin?style=for-the-badge&colorA=302D41&colorB=3ac97b)
+
+</div>
+
+> A modular and typed plugin system for extending AsterFlow functionality.
+
+## 📦 Installation
+
+```bash
+npm install @asterflow/plugin
+# or
+bun install @asterflow/plugin
+```
+
+## 💡 About
+
+`@asterflow/plugin` provides a robust and typed system for extending AsterFlow's functionality. It allows developers to create modular plugins that can inject context, manipulate configurations, and react to application lifecycle events, ensuring seamless and type-safe integration.
+
+## ✨ Features
+
+-   **Extensible Plugin System:** Create modular plugins to add custom functionalities to AsterFlow.
+-   **Dynamic Context:** Inject static values into the plugin's context (`decorate`) or derive complex properties based on configuration and existing context (`derive`).
+-   **Lifecycle Hooks:** Register handlers for specific AsterFlow application events (such as `beforeInitialize`, `afterInitialize`, `onRequest`, and `onResponse`) to extend behavior at different stages.
+-   **Typed Configuration:** Define the plugin's configuration structure and its default values, with automatic type inference.
+-   **Type Safety:** Full TypeScript support to ensure your plugin's context, configuration, and hooks are type-safe.
+-   **Runtime Optimization:** Hooks are efficiently invoked only when the plugin is registered, allowing for performance optimizations.
+
+## 🚀 Usage
+
+`@asterflow/plugin` enables the creation of plugins that extend `AsterFlow` in a modular and type-safe manner. Below are examples of how to create and use plugins.
+
+### Creating a Basic Plugin
+
+```typescript
+import { Plugin } from '@asterflow/plugin'
+
+const myPlugin = Plugin.create({ name: 'my-first-plugin' })
+  .decorate('appName', 'My AsterFlow Application') // Adds a static value to the plugin's context
+  .on('beforeInitialize', (app, context) => {
+    console.log(`Initializing ${context.appName}...`)
+    // app is the AsterFlow instance
+  })
+  .on('afterInitialize', (app, context) => {
+    console.log(`${context.appName} has been initialized!`)
+  })
+
+// This plugin can now be registered with `app.use(myPlugin)`
+```
+
+### Using Configuration and Derivation
+
+Plugins can be configured and can derive values based on their configuration or existing context.
+
+```typescript
+import { Plugin } from '@asterflow/plugin'
+
+interface FeaturePluginConfig {
+  featureEnabled: boolean;
+  featureName: string;
+}
+
+const featureTogglePlugin = Plugin.create({ name: 'feature-toggle' })
+  .withConfig<FeaturePluginConfig>({
+    featureEnabled: true,
+    featureName: 'Awesome Feature'
+  })
+  .derive('statusMessage', (context) => {
+    return context.featureEnabled
+      ? `${context.featureName} is enabled.`
+      : `${context.featureName} is disabled.`
+  })
+  .on('beforeInitialize', (app, context) => {
+    console.log(context.statusMessage) // "Awesome Feature is enabled."
+  })
+
+// This plugin can be configured when registered:
+// app.use(featureTogglePlugin, { featureEnabled: false })
+```
+
+### Lifecycle Hooks
+
+Hooks allow plugins to react to important events in the `AsterFlow` lifecycle.
+
+```typescript
+import { Plugin } from '@asterflow/plugin'
+import { Request } from '@asterflow/request'
+import { Response } from '@asterflow/response'
+
+const loggerPlugin = Plugin.create({ name: 'logger-plugin' })
+  .on('onRequest', (request, response, context) => {
+    // Logs request details
+    console.log(`[REQ] ${request.getMethod()} ${request.getPathname()}`)
+  })
+  .on('onResponse', (request, response, context) => {
+    // Logs response details
+    console.log(`[RES] ${response.getStatus()} ${request.getPathname()}`)
+  })
+
+// Register this plugin for global logging
+// app.use(loggerPlugin)
+```
+
+### Integrating with AsterFlow
+
+To use the created plugins, you register them with the `AsterFlow` instance.
+
+```typescript
+import { AsterFlow } from '@asterflow/core'
+import { adapters } from '@asterflow/adapter'
+import fastify from 'fastify'
+// Import your plugins here
+// import { myPlugin, featureTogglePlugin, loggerPlugin } from './your-plugins'
+
+const server = fastify()
+const app = new AsterFlow({
+  driver: adapters.fastify
+})
+
+// Example plugin registration
+app.use(myPlugin) // No additional configuration
+app.use(featureTogglePlugin, { featureEnabled: false }) // With overridden configuration
+app.use(loggerPlugin)
+
+app.listen(server, { port: 3000 }, (err) => {
+  if (err) {
+    console.error(err)
+    process.exit(1)
+  }
+  console.log('AsterFlow server with plugins listening on port 3000!')
+})
+```
+
+## 🔗 Related Packages
+
+-   [@asterflow/core](https://www.npmjs.com/package/@asterflow/core) - The heart of the AsterFlow framework.
+-   [@asterflow/adapter](https://www.npmjs.com/package/@asterflow/adapter) - HTTP adapters for different runtimes.
+-   [@asterflow/router](https://www.npmjs.com/package/@asterflow/router) - Type-safe routing system.
+-   [@asterflow/request](https://www.npmjs.com/package/@asterflow/request) - Unified HTTP request system.
+-   [@asterflow/response](https://www.npmjs.com/package/@asterflow/response) - Type-safe HTTP response system.
+
+## 📄 License
+
+MIT - See [LICENSE](https://github.com/AsterFlow/AsterFlow/blob/main/LICENSE) for more details.

package/dist/cjs/index.cjs

@@ -0,0 +1,90 @@
+"use strict";
+var r = Object.defineProperty;
+var f = Object.getOwnPropertyDescriptor;
+var u = Object.getOwnPropertyNames;
+var d = Object.prototype.hasOwnProperty;
+var g = (t, e) => {
+  for (var o in e)
+    r(t, o, { get: e[o], enumerable: !0 });
+}, C = (t, e, o, n) => {
+  if (e && typeof e == "object" || typeof e == "function")
+    for (let s of u(e))
+      !d.call(t, s) && s !== o && r(t, s, { get: () => e[s], enumerable: !(n = f(e, s)) || n.enumerable });
+  return t;
+};
+var x = (t) => C(r({}, "__esModule", { value: !0 }), t);
+// packages/plugin/src/index.ts
+var y = {};
+g(y, {
+  Plugin: () => a
+});
+module.exports = x(y);
+// packages/plugin/src/controllers/Plugin.ts
+var a = class t {
+  name;
+  resolvers;
+  defaultConfig;
+  hooks;
+  constructor(e, o, n, s) {
+    this.name = e, this.resolvers = o, this.hooks = n, this.defaultConfig = s;
+  }
+  withConfig(e) {
+    return new t(
+      this.name,
+      this.resolvers,
+      this.hooks,
+      e
+    );
+  }
+  decorate(e, o) {
+    let n = (s, i) => ({
+      ...i,
+      [e]: o
+    });
+    return new t(
+      this.name,
+      [...this.resolvers, n],
+      this.hooks,
+      this.defaultConfig
+    );
+  }
+  derive(e, o) {
+    let n = (s, i) => {
+      let l = { ...i, ...s }, h = o(l);
+      return {
+        ...i,
+        [e]: h
+      };
+    };
+    return new t(
+      this.name,
+      [...this.resolvers, n],
+      this.hooks,
+      this.defaultConfig
+    );
+  }
+  on(e, o) {
+    return this.hooks[e] || (this.hooks[e] = []), this.hooks[e].push(o), new t(
+      this.name,
+      this.resolvers,
+      this.hooks,
+      this.defaultConfig
+    );
+  }
+  _build(e) {
+    let o = { ...this.defaultConfig, ...e }, n = {};
+    for (let s of this.resolvers)
+      n = s(o, n);
+    return {
+      name: this.name,
+      context: n,
+      hooks: this.hooks
+    };
+  }
+  static create(e) {
+    return new t(e.name, [], {}, {});
+  }
+};
+0 && (module.exports = {
+  Plugin
+});

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/mjs/index.js

@@ -0,0 +1,69 @@
+// packages/plugin/src/controllers/Plugin.ts
+var r = class s {
+  name;
+  resolvers;
+  defaultConfig;
+  hooks;
+  constructor(e, o, t, n) {
+    this.name = e, this.resolvers = o, this.hooks = t, this.defaultConfig = n;
+  }
+  withConfig(e) {
+    return new s(
+      this.name,
+      this.resolvers,
+      this.hooks,
+      e
+    );
+  }
+  decorate(e, o) {
+    let t = (n, i) => ({
+      ...i,
+      [e]: o
+    });
+    return new s(
+      this.name,
+      [...this.resolvers, t],
+      this.hooks,
+      this.defaultConfig
+    );
+  }
+  derive(e, o) {
+    let t = (n, i) => {
+      let a = { ...i, ...n }, l = o(a);
+      return {
+        ...i,
+        [e]: l
+      };
+    };
+    return new s(
+      this.name,
+      [...this.resolvers, t],
+      this.hooks,
+      this.defaultConfig
+    );
+  }
+  on(e, o) {
+    return this.hooks[e] || (this.hooks[e] = []), this.hooks[e].push(o), new s(
+      this.name,
+      this.resolvers,
+      this.hooks,
+      this.defaultConfig
+    );
+  }
+  _build(e) {
+    let o = { ...this.defaultConfig, ...e }, t = {};
+    for (let n of this.resolvers)
+      t = n(o, t);
+    return {
+      name: this.name,
+      context: t,
+      hooks: this.hooks
+    };
+  }
+  static create(e) {
+    return new s(e.name, [], {}, {});
+  }
+};
+export {
+  r as Plugin
+};

package/dist/mjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/types/controllers/Plugin.d.ts

@@ -0,0 +1,54 @@
+import type { AnyPluginHooks } from '../types/plugin';
+/**
+ * A factory for creating plugins that can be configured and attached to AsterFlow.
+ * Plugins are defined with a series of resolvers (`decorate`, `derive`) and lifecycle
+ * hooks (`on`) that build up its context and runtime behavior.
+ */
+export declare class Plugin<Path extends string, Config extends Record<string, any> = {}, Context extends Record<string, any> = {}, THooks extends AnyPluginHooks = {}> {
+    readonly name: Path;
+    private readonly resolvers;
+    readonly defaultConfig: Partial<Config>;
+    readonly hooks: THooks;
+    private constructor();
+    /**
+     * Defines the shape of the configuration and its default values for this plugin.
+     */
+    withConfig<C extends Record<string, any>>(defaultConfig: C): Plugin<Path, C, Context, THooks>;
+    /**
+     * Adds a new static value to the plugin's context (decoration).
+     */
+    decorate<Key extends string, Value>(key: Key, value: Value): Plugin<Path, Config, Context & { [K in Key]: Value; }, THooks>;
+    /**
+     * Adds a new property to the context that is derived from the configuration and the existing context.
+     * The resolver function is executed lazily when the plugin is registered via `app.use()`.
+     */
+    derive<Key extends string, Value>(key: Key, resolverFn: (context: Context & Config) => Value): Plugin<Path, Config, Context & { [K in Key]: Value; }, THooks>;
+    /**
+     * Registers a handler for a specific lifecycle event.
+     * Adding a hook makes the plugin "runtime-aware". AsterFlow can optimize by only
+     * invoking plugins that have registered hooks for a given event.
+     *
+     * @example
+     * const routingPlugin = Plugin.create({ name: 'dynamic-routes' })
+     * .on('beforeInitialize', (app, context) => {
+     * // `app` is the AsterFlow instance
+     * const dynamicRouter = createDynamicRouter();
+     * app.controller(dynamicRouter);
+     * });
+     */
+    on<Event extends keyof AnyPluginHooks, Handler extends NonNullable<AnyPluginHooks[Event]> extends (infer F)[] ? F : never>(event: Event, handler: Handler): Plugin<Path, Config, Context, THooks>;
+    /**
+     * Builds the final context and hooks from the provided configuration.
+     */
+    _build(config: any): {
+        name: Path;
+        context: Context;
+        hooks: THooks;
+    };
+    /**
+     * Creates a new Plugin instance. This is the entry point for building a plugin.
+     */
+    static create<Path extends string>(options: {
+        name: Path;
+    }): Plugin<Path, {}, {}, {}>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './controllers/Plugin';
+export * from './types/plugin';

package/dist/types/types/plugin.d.ts

@@ -0,0 +1,29 @@
+import type { AsterFlow } from '@asterflow/core';
+import type { Request } from '@asterflow/request';
+import type { Response } from '@asterflow/response';
+import type { Plugin } from '../controllers/Plugin';
+export type AnyPlugin = Plugin<string>;
+export type AnyPluginHooks = PluginHooks<any, any, any, any>;
+/**
+ * Tipo para extrair o objeto de configuração de um plugin.
+ * Ele torna as propriedades com valores padrão opcionais.
+ */
+export type ConfigArgument<P extends AnyPlugin> = P extends Plugin<any, any, any, infer C> ? Omit<C, keyof P['defaultConfig']> & Partial<Pick<C, keyof P['defaultConfig'] & keyof C>> : never;
+/**
+ * Tipo para o plugin após seu contexto ter sido construído.
+ */
+export type ResolvedPlugin<P extends AnyPlugin> = ReturnType<P['_build']>;
+/**
+ * Defines the available lifecycle hooks a plugin can register.
+ */
+export type PluginHooks<Instance extends AsterFlow<any>, Context extends Record<string, any>, Responser extends Response, Requester extends Request<unknown>> = {
+    beforeInitialize?: ((app: Instance, context: Context) => void | Promise<void>)[];
+    afterInitialize?: ((app: Instance, context: Context) => void | Promise<void>)[];
+    onRequest?: ((request: Requester, response: Responser, context: Context) => void | Promise<void>)[];
+    onResponse?: ((request: Requester, response: Responser, context: Context) => void | Promise<void>)[];
+};
+/**
+ * Represents a function that resolves a part of the plugin's context.
+ * @internal
+ */
+export type Resolver = (config: any, context: any) => Record<string, any>;

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@asterflow/plugin",
+  "version": "1.0.1",
+  "main": "dist/cjs/index.cjs",
+  "module": "dist/mjs/index.js",
+  "types": "dist/types/index.d.ts",
+  "typings": "dist/types/index.d.ts",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/mjs/index.js",
+      "require": "./dist/cjs/index.cjs"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@asterflow/core": "1.0.5",
+    "@asterflow/response": "1.0.2",
+    "@asterflow/request": "1.0.5"
+  },
+  "peerDependencies": {
+    "typescript": "^5.8.3"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "lib": [
+      "ESNext"
+    ],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  },
+  "include": [
+    "dist"
+  ]
+}