plug-code 1.0.3 → 1.1.1

package/README.md

@@ -1,16 +1,116 @@
 # Plug&Code
 
-Plug&Code is a multipurpose framework for React, designed for **scalability, reusability, and organized components**.
+Plug&Code is a multipurpose framework for React designed for **scalability, reusability, and modular organization**. It allows you to build complex applications by "plugging in" features without tightly coupling your codebase.
 
 ## Usage
 
-You are welcome to use Plug&Code in your projects, **personal or commercial**, as long as you **do not modify or redistribute the framework** without explicit permission from the author.  
+You are welcome to use Plug&Code in your projects, **personal or commercial**, as long as you **do not modify or redistribute the framework** without explicit permission from the author.
+
+---
 
 ### Installation
 
-You can install the framework via npm or yarn:
+Install the framework via npm or yarn:
 
 ```bash
 npm install plug-code
 # or
 yarn add plug-code
+
+```
+
+### Core Concepts
+
+Plug&Code is built around the **PLC (Pipeline-Logic-Command)** pattern:
+
+* **Slots (UI Pipeline):** Inject components into pre-defined locations from any feature.
+* **Commands (Logic):** Execute and wrap business actions (e.g., `checkout`, `print`, `save`).
+* **Transforms (Data):** Pass data through named channels to be modified by different features.
+
+---
+
+### Quick Start Guide
+
+#### 1. Initialize your System
+
+Define your system and register features using the fluent API.
+
+```tsx
+import { createPlugAndCode } from 'plug-code';
+
+export const { useSystemPlc, SystemPlcRoot } = createPlugAndCode((api) => {
+  
+  // Define a Sales Feature
+  api.feature("sales", (api) => {
+    // Register a UI component into a slot
+    api.register("header.cart", () => <CartIcon />);
+
+    // Register a business command
+    api.registerCommand("sales.checkout", async (items) => {
+      console.log("Saving items to database...", items);
+      return { success: true };
+    });
+  });
+
+  // Define a Logger Feature that wraps existing logic
+  api.feature("logger", (api) => {
+    api.wrapCommand("sales.checkout", (next) => async (items) => {
+      console.log("Checkout started...");
+      const result = await next(items);
+      console.log("Checkout finished:", result);
+      return result;
+    });
+  });
+});
+
+```
+
+#### 2. Wrap your Application
+
+Use the `useSystemPlc` hook to manage the state and `SystemPlcRoot` to provide the context.
+
+```tsx
+function App() {
+  // Initialize state with initial properties
+  const { api, useSelector } = useSystemPlc({ shopName: "My Store" });
+
+  return (
+    <SystemPlcRoot api={api}>
+      <nav>
+        {/* Render slots from any feature */}
+        {api.render("header.cart")}
+      </nav>
+      <main>
+        <h1>Welcome to {useSelector(s => s.root.shopName)}</h1>
+      </main>
+    </SystemPlcRoot>
+  );
+}
+
+```
+
+---
+
+### API Reference
+
+#### **UI Management (Slots)**
+
+* `api.register(slotName, component)`: Adds a UI component to a slot.
+* `api.render(slotName)`: Renders all components registered in that slot.
+* `api.wrap(slot, wrapper)`: Wraps a slot's content with higher-order components.
+
+#### **Business Logic (Commands)**
+
+* `api.registerCommand(id, fn)`: Registers an executable action.
+* `api.execute(id, payload)`: Runs a command and returns a Promise.
+* `api.wrapCommand(id, (next) => ...)`: Intercepts a command to add side-effects or validations.
+
+#### **Data Processing (Transforms)**
+
+* `api.send(channel, id, fn, priority)`: Adds a data transformer to a specific channel.
+* `api.receive(channel, initialData)`: Pipes data through all transformers in the channel.
+
+#### **State Management**
+
+* `useSelector(selector)`: Reactively listen to state changes.
+* `api.update(key, updater)`: Update store data using Immer-powered drafts.

package/index.d.ts

@@ -1,10 +1 @@
 export * from "./types/plug-code";
-export * from "./types/core/plcAPI";
-export * from "./types/core/plcStore";
-export * from "./types/contexts/pipeline";
-
-export * from "./types/types/api";
-export * from "./types/types/features";
-export * from "./types/types/general";
-export * from "./types/types/pipeline";
-export * from "./types/types/store";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plug-code",
-  "version": "1.0.3",
+  "version": "1.1.1",
   "description": "",
   "main": "src/plug-code.tsx",
   "types": "types/plug-code.d.ts",

package/src/core/plcAPI.tsx

@@ -3,22 +3,57 @@ import type { ObjectType } from "../types/general";
 import { useEffect, useState } from "react";
 import { PlcPipeline } from "./plcPipeline";
 import type { PlcStore } from "./plcStore";
-import type { transformerType } from "../types/api";
+import type { CommandFn, transformerType } from "../types/api";
+
+import type { ChannelRegistry, CommandRegistry, SlotRegistry } from "../types/registry";
+
+type ChannelKey = keyof ChannelRegistry | (string & {});
+type ChannelData<K> = K extends keyof ChannelRegistry ? ChannelRegistry[K] : any;
+
+type CommandKey = keyof CommandRegistry | (string & {});
+type CommandPayload<K> = K extends keyof CommandRegistry
+    ? (CommandRegistry[K] extends { payload: infer P } ? P : any)
+    : any;
+type CommandResult<K> = K extends keyof CommandRegistry
+    ? (CommandRegistry[K] extends { result: infer R } ? R : any)
+    : any;
+
+type SlotKey = keyof SlotRegistry | (string & {});
+
 
 export class PlcAPI<S extends ObjectType> {
     private store: PlcStore<S>
     private pipeline: PlcPipeline<S>
     private substores = new Map<string, any>()
-    private transformers: transformerType[] = []
+
+    private transformers = new Map<string, transformerType[]>()
+    private commands = new Map<string, CommandFn>();
+    private installedFeatures = new Set<string>();
 
     constructor(store: PlcStore<S>) {
         this.store = store
         this.pipeline = new PlcPipeline(store)
     }
 
-    register(slot: string, node: () => React.ReactNode): void;
-    register<K extends string>(slot: string, node: (data: any) => React.ReactNode, dependencyKey: K): void;
-    register(slot: string, node: (data?: any) => React.ReactNode, dependencyKey?: string) {
+    createFeature(name: string, setupFn: (api: PlcAPI<S>) => void): PlcAPI<S> {
+        if (this.installedFeatures.has(name)) {
+            console.warn(`[PlcFramework] La feature '${name}' ya fue registrada. Se omitirá para evitar conflictos.`);
+            return this;
+        }
+
+        try {
+            setupFn(this);
+            this.installedFeatures.add(name);
+        } catch (error) {
+            console.error(`[PlcFramework] 💥 Error crítico inicializando la feature '${name}':`, error);
+        }
+
+        return this;
+    }
+
+    register(slot: SlotKey, node: () => React.ReactNode): void;
+    register<K extends string>(slot: SlotKey, node: (data: any) => React.ReactNode, dependencyKey: K): void;
+    register(slot: SlotKey, node: (data?: any) => React.ReactNode, dependencyKey?: string) {
         if (dependencyKey) {
             const ConnectedWrapper = () => {
                 const [data, setData] = useState(() => this.substores.get(dependencyKey));
@@ -34,12 +69,12 @@ export class PlcAPI<S extends ObjectType> {
             };
 
             this.store.batch(() => {
-                this.pipeline.register(slot, () => <ConnectedWrapper />);
+                this.pipeline.register(slot as string, () => <ConnectedWrapper />);
             });
         }
         else {
             this.store.batch(() => {
-                this.pipeline.register(slot, node as () => React.ReactNode);
+                this.pipeline.register(slot as string, node as () => React.ReactNode);
             });
         }
     }
@@ -48,7 +83,7 @@ export class PlcAPI<S extends ObjectType> {
         get: () => T;
         update: (updater: (draft: T) => void) => void;
         connect: (renderer: (data: T) => React.ReactNode) => React.FC;
-        render: (slotName: string) => React.ReactNode | null;
+        render: (slotName: SlotKey) => React.ReactNode | null;
         receive: (context?: any) => any;
         root: PlcAPI<S>;
     } {
@@ -63,15 +98,15 @@ export class PlcAPI<S extends ObjectType> {
                 return this.connect(key, renderer);
             },
 
-            render: (slotName: string) => {
+            render: (slotName: SlotKey) => {
                 return this.connect(key, (localData) => {
-                    return this.pipeline.render(slotName, localData) as React.ReactNode;
+                    return this.pipeline.render(slotName as string, localData) as React.ReactNode;
                 }) as any;
             },
 
             receive: (context: any = {}) => {
                 const currentData = this.getData(key);
-                return this.receive(currentData, context);
+                return this.receive(key as any, currentData, context);
             },
 
             root: this
@@ -97,43 +132,105 @@ export class PlcAPI<S extends ObjectType> {
         };
     }
 
-    wrap(slot: string, fn: (next: () => React.ReactNode) => () => React.ReactNode) {
+    wrap(slot: SlotKey, fn: (next: () => React.ReactNode) => () => React.ReactNode) {
         this.store.batch(() => {
-            this.pipeline.wrap(slot, fn)
+            this.pipeline.wrap(slot as string, fn)
         })
     }
 
-    after(slot: string, node: () => React.ReactNode) {
+    after(slot: SlotKey, node: () => React.ReactNode) {
         this.store.batch(() => {
-            this.pipeline.register(slot, node)
+            this.pipeline.register(slot as string, node)
         })
     }
 
-    render(slot: string) {
-        return this.pipeline.render(slot)
+    render(slot: SlotKey) {
+        return this.pipeline.render(slot as string)
     }
 
-    invalidate(slot?: string) {
-        this.pipeline.invalidate(slot)
+    invalidate(slot?: SlotKey) {
+        this.pipeline.invalidate(slot as string)
     }
 
-    send(id: string, fn: (data: any, context: any) => any, priority: number) {
-        this.transformers.push({ id, priority, fn });
-        this.transformers.sort((a, b) => a.priority - b.priority);
+    send<K extends ChannelKey>(
+        channel: K,
+        id: string,
+        fn: (data: ChannelData<K>, context: any) => ChannelData<K>,
+        priority: number = 0
+    ) {
+        const channelStr = channel as string;
+        if (!this.transformers.has(channelStr)) {
+            this.transformers.set(channelStr, []);
+        }
+
+        const channelList = this.transformers.get(channelStr)!;
+
+        const existingIdx = channelList.findIndex(t => t.id === id);
+        if (existingIdx >= 0) {
+            channelList[existingIdx] = { id, priority, fn };
+        } else {
+            channelList.push({ id, priority, fn });
+        }
+
+        channelList.sort((a, b) => a.priority - b.priority);
     }
 
-    receive(initialData: any, context: any = {}) {
+    receive<K extends ChannelKey>(
+        channel: K,
+        initialData: ChannelData<K>,
+        context: any = {}
+    ): ChannelData<K> {
         let currentData = initialData;
+        const channelList = this.transformers.get(channel as string) || [];
 
-        for (const transformer of this.transformers) {
+        for (const transformer of channelList) {
             try {
                 currentData = transformer.fn(currentData, context);
             } catch (error) {
-                console.error(`[Pipeline] Error en transformador '${transformer.id}':`, error);
+                console.error(`[PlcAPI] Error en transform '${channel as string}/${transformer.id}':`, error);
             }
         }
 
-        return currentData;
+        return currentData as ChannelData<K>;
+    }
+
+    registerCommand<K extends CommandKey>(
+        id: K,
+        fn: CommandFn<CommandPayload<K>, CommandResult<K>>
+    ) {
+        if (this.commands.has(id as string)) {
+            console.warn(`[PlcAPI] Sobrescribiendo comando '${id as string}'`);
+        }
+        this.commands.set(id as string, fn as any);
+    }
+
+    wrapCommand<K extends CommandKey>(
+        id: K,
+        wrapper: (next: CommandFn<CommandPayload<K>, CommandResult<K>>) => CommandFn<CommandPayload<K>, CommandResult<K>>
+    ) {
+        const currentFn = this.commands.get(id as string);
+        if (!currentFn) {
+            console.error(`[PlcAPI] No se puede envolver '${id as string}', comando no existe.`);
+            return;
+        }
+        this.commands.set(id as string, wrapper(currentFn) as any);
+    }
+
+    async execute<K extends CommandKey>(
+        id: K,
+        payload?: CommandPayload<K>
+    ): Promise<CommandResult<K>> {
+        const fn = this.commands.get(id as string);
+        if (!fn) {
+            throw new Error(`[PlcAPI] Comando '${id as string}' no encontrado.`);
+        }
+
+        try {
+            return await fn(payload);
+        } catch (error) {
+            console.error(`[PlcAPI] Error ejecutando '${id as string}':`, error);
+            throw error;
+        }
     }
 
     getData(key: string): any {

package/src/plug-code.tsx

@@ -1,15 +1,16 @@
 import { enableMapSet } from "immer";
 import type { ObjectType } from "./types/general";
-import type { FeatureType } from "./types/features";
 import { PlcAPI } from "./core/plcAPI";
 import { useEffect, useMemo, useState } from "react";
 import { PlcStore } from "./core/plcStore";
 
-enableMapSet()
-export function createPlugAndCode<S extends ObjectType>(features: FeatureType<S>[]) {
+enableMapSet();
+
+export function createPlugAndCode<S extends ObjectType>(
+    setupSystem: (api: PlcAPI<S>) => void
+) {
     const FeatureHost = ({ api, children }: { api: PlcAPI<any>, children?: React.ReactNode }) => (
         <>
-            {/* Renderizamos el slot principal */}
             {api.render("root")}
             {children}
         </>
@@ -32,9 +33,7 @@ export function createPlugAndCode<S extends ObjectType>(features: FeatureType<S>
 
             api.createData("root", initialProps);
 
-            for (const feature of features) {
-                feature.setup?.(api as any);
-            }
+            setupSystem(api as unknown as PlcAPI<S>);
 
             return api;
         }, []);

package/src/types/api.ts

@@ -1,2 +1,8 @@
 
-export type transformerType = { id: string, priority: number, fn: (data: any, context: any) => any }
+export type transformerType = {
+    id: string,
+    priority: number,
+    fn: (data: any, context: any) => any
+}
+
+export type CommandFn<T = any, R = any> = (payload: T) => Promise<R> | R;

package/src/types/registry.ts

@@ -0,0 +1,4 @@
+
+export interface ChannelRegistry {}
+export interface CommandRegistry {}
+export interface SlotRegistry {}

package/types/plug-code.d.ts

@@ -1,13 +1,156 @@
-import type { ObjectType } from "./types/general";
-import type { FeatureType } from "./types/features";
-import { PlcAPI } from "./core/plcAPI";
-export declare function createPlugAndCode<S extends ObjectType>(features: FeatureType<S>[]): {
-    useSystemPlc: <T extends object>(initialProps: T) => {
-        api: PlcAPI<{}>;
-        useSelector: <Result>(selector: (state: any) => Result) => Result;
-    };
-    SystemPlcRoot: ({ api, children }: {
-        api: PlcAPI<any>;
-        children?: React.ReactNode;
-    }) => import("react/jsx-runtime").JSX.Element;
-};
+import * as React from 'react';
+
+// ==========================================
+// Tipos Generales
+// ==========================================
+
+export type ObjectType = Record<string, any>;
+
+export type Slot = () => React.ReactNode;
+
+/**
+ * Función para ejecutar lógica de negocio (Acciones).
+ * Puede ser síncrona o asíncrona.
+ */
+export type CommandFn<T = any, R = any> = (payload: T) => Promise<R> | R;
+
+/**
+ * Función para transformar datos (Pipes).
+ * Debe ser pura y síncrona preferiblemente.
+ */
+export type TransformerFn<D = any, C = any> = (data: D, context: C) => D;
+
+// ==========================================
+// Core: Store
+// ==========================================
+
+export declare class PlcStore<S extends ObjectType> {
+    constructor(initial: S, debug: boolean);
+
+    get<K extends keyof S>(key: K): S[K];
+    getState(): S;
+    set<K extends keyof S>(key: K, value: S[K]): void;
+
+    /** Agrupa múltiples actualizaciones en un solo evento de notificación */
+    batch(updater: (draft: S) => void): void;
+
+    subscribe(listener: () => void): () => void;
+    subscribe<K extends keyof S>(key: K, listener: () => void): () => void;
+}
+
+// ==========================================
+// Core: API Principal
+// ==========================================
+
+export declare class PlcAPI<S extends ObjectType> {
+    constructor(store: PlcStore<S>);
+
+    // --- Configuración del Sistema (Fluent Interface) ---
+
+    /**
+     * Registra un módulo o feature en el sistema.
+     * @param name Identificador único para debugging y prevención de duplicados.
+     * @param setupFn Función de configuración donde registras slots, comandos, etc.
+     */
+    feature(name: string, setupFn: (api: PlcAPI<S>) => void): PlcAPI<S>;
+
+    // --- Gestión de UI (Slots & Rendering) ---
+
+    register(slot: string, node: () => React.ReactNode): void;
+    register<K extends string>(slot: string, node: (data: any) => React.ReactNode, dependencyKey: K): void;
+
+    /** Envuelve un slot existente (Decorador/Wrapper) */
+    wrap(slot: string, fn: (next: () => React.ReactNode) => () => React.ReactNode): void;
+
+    /** Agrega contenido después de un slot existente */
+    after(slot: string, node: () => React.ReactNode): void;
+
+    /** Renderiza el contenido de un slot */
+    render(slot: string, contextData?: any): React.ReactNode;
+
+    /** Fuerza la regeneración del caché de un slot */
+    invalidate(slot?: string): void;
+
+    // --- Gestión de Datos (Scope & State) ---
+
+    createData<K extends string, T>(key: K, initialState: T): void;
+
+    getData(key: string): any;
+
+    update<K extends keyof S>(key: string & "root", updater: (draft: any) => void, slot?: string): void;
+
+    subscribe(listener: () => void): () => void;
+
+    /**
+     * Obtiene una interfaz tipada para interactuar con una parte específica del estado.
+     */
+    scope<T = any>(key: string): {
+        get: () => T;
+        update: (updater: (draft: T) => void) => void;
+        connect: (renderer: (data: T) => React.ReactNode) => React.FC;
+        render: (slotName: string) => React.ReactNode | null;
+        receive: (context?: any) => any;
+        root: PlcAPI<S>;
+    };
+
+    /** Conecta un componente a una parte del estado (HOC) */
+    connect<T = any>(key: string, renderer: (data: T) => React.ReactNode): React.FC;
+
+    // --- Pipeline de Datos (Transforms) ---
+
+    /**
+     * Registra un transformador en un canal específico.
+     * @param channel Nombre del canal (ej: 'calculo-impuestos')
+     * @param id Identificador único del transformador
+     * @param fn Función transformadora
+     * @param priority Mayor número se ejecuta al final (default: 0)
+     */
+    send(channel: string, id: string, fn: TransformerFn, priority?: number): void;
+
+    /**
+     * Ejecuta la tubería de transformación para un canal.
+     */
+    receive(channel: string, initialData: any, context?: any): any;
+
+    // --- Sistema de Comandos (Actions) ---
+
+    /**
+     * Registra una acción ejecutable.
+     */
+    registerCommand<T = any, R = any>(id: string, fn: CommandFn<T, R>): void;
+
+    /**
+     * Envuelve o intercepta un comando existente.
+     */
+    wrapCommand<T = any, R = any>(id: string, wrapper: (next: CommandFn<T, R>) => CommandFn<T, R>): void;
+
+    /**
+     * Ejecuta una acción registrada.
+     * @returns Promesa con el resultado del comando.
+     */
+    execute<T = any, R = any>(id: string, payload?: T): Promise<R>;
+}
+
+// ==========================================
+// Entry Point & Hooks
+// ==========================================
+
+export type SystemInstance<S extends ObjectType> = {
+    api: PlcAPI<S>;
+    /** Hook para seleccionar datos del store reactivamente */
+    useSelector: <Result>(selector: (state: S) => Result) => Result;
+};
+
+/**
+ * Inicializa el framework.
+ * @param setupSystem Función callback para configurar las features iniciales.
+ */
+export declare function createPlugAndCode<S extends ObjectType>(
+    setupSystem: (api: PlcAPI<S>) => void
+): {
+    useSystemPlc: (initialProps: S) => SystemInstance<S>;
+    SystemPlcRoot: React.FC<{ api: PlcAPI<S>; children?: React.ReactNode }>;
+};
+
+/** Hook para acceder al contexto local dentro de un slot renderizado */
+export declare function useScopeData<T>(): T;

package/types/contexts/pipeline.d.ts

@@ -1,2 +0,0 @@
-export declare const ScopeContext: import("react").Context<any>;
-export declare const useScopeData: <T>() => T;

package/types/core/plcAPI.d.ts

@@ -1,30 +0,0 @@
-import type { ObjectType } from "../types/general";
-import type { PlcStore } from "./plcStore";
-export declare class PlcAPI<S extends ObjectType> {
-    private store;
-    private pipeline;
-    private substores;
-    private transformers;
-    constructor(store: PlcStore<S>);
-    register(slot: string, node: () => React.ReactNode): void;
-    register<K extends string>(slot: string, node: (data: any) => React.ReactNode, dependencyKey: K): void;
-    scope<T = any>(key: string & "root"): {
-        get: () => T;
-        update: (updater: (draft: T) => void) => void;
-        connect: (renderer: (data: T) => React.ReactNode) => React.FC;
-        render: (slotName: string) => React.ReactNode | null;
-        receive: (context?: any) => any;
-        root: PlcAPI<S>;
-    };
-    connect<T = any>(key: string, renderer: (data: T) => React.ReactNode): React.FC;
-    wrap(slot: string, fn: (next: () => React.ReactNode) => () => React.ReactNode): void;
-    after(slot: string, node: () => React.ReactNode): void;
-    render(slot: string): import("react").ReactNode[] | import("react/jsx-runtime").JSX.Element;
-    invalidate(slot?: string): void;
-    send(id: string, fn: (data: any, context: any) => any, priority: number): void;
-    receive(initialData: any, context?: any): any;
-    getData(key: string): any;
-    subscribe(listener: () => void): () => void;
-    createData<K extends string, T>(key: K, initialState: T): void;
-    update<K extends keyof S>(key: string & "root", updater: (draft: any) => void, slot?: string): void;
-}

package/types/core/plcPipeline.d.ts

@@ -1,16 +0,0 @@
-import React from "react";
-import type { ObjectType } from "../types/general";
-import type { Slot } from "../types/pipeline";
-import type { PlcStore } from "./plcStore";
-export declare class PlcPipeline<S extends ObjectType> {
-    private slots;
-    private store;
-    private cache;
-    private scheduleQueue;
-    constructor(store: PlcStore<S>);
-    register(slot: string, fn: Slot, priority?: number): void;
-    wrap(slot: string, wrapper: (next: Slot) => Slot, priority?: number): void;
-    render(slot: string, contextData?: any): React.ReactNode[] | import("react/jsx-runtime").JSX.Element;
-    invalidate(slot?: string): void;
-    private regenerateCache;
-}

package/types/core/plcStore.d.ts

@@ -1,17 +0,0 @@
-import { type Draft } from "immer";
-import type { ObjectType } from "../types/general";
-export declare class PlcStore<S extends ObjectType> {
-    private state;
-    private listeners;
-    private batchQueue;
-    private debug;
-    private isBatching;
-    constructor(initial: S, debug: boolean);
-    get<K extends keyof S>(key: K): S[K];
-    getState(): S;
-    set<K extends keyof S>(key: K, value: S[K]): void;
-    batch(updater: (draft: Draft<S>) => void): void;
-    subscribe(listener: () => void): () => void;
-    subscribe<K extends keyof S>(key: K, listener: () => void): () => void;
-    private emit;
-}

package/types/types/api.d.ts

@@ -1,5 +0,0 @@
-export type transformerType = {
-    id: string;
-    priority: number;
-    fn: (data: any, context: any) => any;
-};

package/types/types/features.d.ts

@@ -1,6 +0,0 @@
-import type { PlcAPI } from "../core/plcAPI";
-import type { ObjectType } from "./general";
-export type FeatureType<S extends ObjectType> = {
-    name: string;
-    setup?: (api: PlcAPI<S>) => void | (() => void);
-};

package/types/types/general.d.ts

@@ -1 +0,0 @@
-export type ObjectType = Record<string, any>;

package/types/types/pipeline.d.ts

@@ -1,6 +0,0 @@
-export type Slot = () => React.ReactNode;
-export type ScheduledSlot = {
-    slot: string;
-    fn: Slot;
-    priority: number;
-};

package/types/types/store.d.ts

@@ -1,4 +0,0 @@
-export type Listener<S> = {
-    key?: keyof S;
-    callback: () => void;
-};