comes 0.0.2 → 0.0.4

package/CLAUDE.md

@@ -0,0 +1,35 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**comes** is a TypeScript event system library for simple pub/sub communication. It provides an `EventSystem` class with address-based events, lazy loaders, and interceptors.
+
+## Commands
+
+- **Build:** `npm run build` (cleans `build/` then runs `tsc`)
+- **Test:** `npm test` (runs vitest with coverage enabled by default)
+- **Run single test:** `npx vitest run -t "Test name"` or `npx vitest run test/simple-emit.test.ts`
+
+## Architecture
+
+Single-file library (`src/index.ts`) exporting:
+
+- **`EventSystem`** class — the core. Manages a `data` map (keyed by string "address") where each address holds an `ES_ValueType` containing the last value, listeners array, optional loader, and loader error handler.
+- **`es`** — a default singleton `EventSystem` instance exported for convenience.
+
+Key concepts:
+- **Addresses** are string keys identifying event channels.
+- **`send(id, event)`** — async; runs interceptors (chain of responsibility), then notifies all listeners. Both interceptors and listeners are awaited sequentially.
+- **`listen(id, listener)`** — registers a listener. If a value was already sent (has a `date`), the listener is immediately called with the cached `last` value. If no value exists but a loader is configured, the loader is triggered. Returns an unregister function.
+- **Interceptors** (`addInter`) — transform/validate events before they reach listeners. The empty string `""` address matches all events. Throwing in an interceptor stops the chain and prevents listener notification.
+- **Loaders** (`setLoader`) — lazy data fetchers invoked when the first listener registers on an address that has no value yet. `loaderCatch` handles loader errors and can optionally return a fallback value.
+
+## Build Output
+
+TypeScript compiles from `src/` to `build/` (ES2017, Node16 modules). Declarations (`.d.ts`) are generated. Entry point: `build/index.js`.
+
+## Test Structure
+
+Tests are in `test/` using vitest. A single test file (`test/simple-emit.test.ts`) covers: send/get, listen before/after emit, unregistering, listener errors, loader lifecycle (with/without error handlers), and interceptor chains.

package/README.md

@@ -1,3 +1,272 @@
 # comes - Communication Event System
 
+A simple, lightweight event system for TypeScript/JavaScript applications. It provides address-based pub/sub communication with built-in value caching, lazy loaders, and interceptors.
 
+## Installation
+
+```bash
+npm install comes
+```
+
+## Quick Start
+
+```ts
+import { es } from 'comes';
+
+// Send a value to an address
+await es.send('user/name', 'Alice');
+
+// Listen for values on an address
+const unregister = es.listen('user/name', (value) => {
+  console.log(value); // "Alice" (immediately, from cache)
+});
+
+// Stop listening
+unregister();
+```
+
+## Core Concepts
+
+- **Address**: A string key that identifies an event channel (e.g. `'user/name'`, `'app/status'`).
+- **Value caching**: The last value sent to each address is cached. When a new listener registers, it immediately receives the cached value.
+- **Interceptors**: Middleware functions that can transform, validate, or monitor values before they reach listeners.
+- **Loaders**: Lazy data fetchers that run automatically when the first listener registers on an address that has no value yet.
+
+## API
+
+### Importing
+
+```ts
+// Use the default singleton instance
+import { es } from 'comes';
+
+// Or create your own isolated instance
+import { EventSystem } from 'comes';
+const es = new EventSystem();
+```
+
+---
+
+### `send<T>(id: string, event: T): Promise<T>`
+
+Sends a value to all listeners of the given address. Interceptors are executed first (in order), then each listener is called with the resulting value. The final value (after interceptors) is cached.
+
+Returns the value after interceptor transformations.
+
+```ts
+await es.send('counter', 1);
+await es.send('user/profile', { name: 'Alice', age: 30 });
+```
+
+If an interceptor or listener throws an error, `send` will throw that error.
+
+---
+
+### `listen(id: string, listener: EventListenerType): () => void`
+
+Registers a listener on the given address. Returns an **unregister function** to remove the listener later.
+
+**Behavior on registration:**
+- If a value was already sent to this address, the listener is **immediately called** with the cached value.
+- If no value exists but a **loader** is configured, the loader is triggered to fetch the initial value.
+- If neither exists, the listener simply waits for the next `send`.
+
+```ts
+// Basic usage
+const unregister = es.listen('counter', (value) => {
+  console.log('Counter:', value);
+});
+
+// Later, stop listening
+unregister();
+```
+
+---
+
+### `unlisten(id: string, listener: EventListenerType): void`
+
+Removes a specific listener from the given address. This is useful when you need to unregister **inside** the listener itself, where the unregister function returned by `listen` may not be assigned yet.
+
+```ts
+const listener = (value: string) => {
+  es.unlisten('my-event', listener); // safe to call here
+  console.log('Received once:', value);
+};
+es.listen('my-event', listener);
+```
+
+---
+
+### `get(id: string): ES_ValueType`
+
+Returns a reference to the internal state object for the given address. Useful for inspecting the current cached value, the listener list, or the loader state.
+
+```ts
+await es.send('status', 'online');
+
+const data = es.get('status');
+console.log(data.last);       // "online"
+console.log(data.date);       // Date when last value was sent
+console.log(data.listeners);  // Array of registered listeners
+```
+
+**`ES_ValueType` fields:**
+
+| Field | Type | Description |
+|---|---|---|
+| `last` | `any` | The last value sent to this address |
+| `listeners` | `EventListenerType[]` | Array of registered listeners |
+| `date` | `Date \| undefined` | Timestamp of the last `send`. `undefined` means no value was sent yet |
+| `loader` | `Function \| undefined` | The loader function, if configured |
+| `loaderCatch` | `Function \| undefined` | The loader error handler, if configured |
+| `loaderProm` | `Promise \| undefined` | The loader promise, while the loader is running |
+
+---
+
+### `addInter(id: string, interceptor: EventInterceptorType): () => void`
+
+Adds an interceptor for the given address. Interceptors are called **before** listeners, in the order they were added. Each interceptor receives the value, can transform it, and must return the (possibly modified) value for the next interceptor in the chain.
+
+Returns an **unregister function** to remove the interceptor.
+
+**Special address `""`:** An interceptor registered with an empty string `""` as the address is called for **every** event on the `EventSystem`, regardless of address.
+
+```ts
+// Transform values before listeners receive them
+es.addInter('counter', async (id, event, es) => {
+  return event * 2; // double the value
+});
+
+es.listen('counter', (value) => {
+  console.log(value); // 20
+});
+
+await es.send('counter', 10);
+```
+
+**Interceptor chain:**
+
+```ts
+es.addInter('price', async (id, event, es) => {
+  return event + 1; // first: add 1
+});
+
+es.addInter('price', async (id, event, es) => {
+  return event * 10; // second: multiply by 10
+});
+
+await es.send('price', 5); // (5 + 1) * 10 = 60
+```
+
+**Global interceptor (logging example):**
+
+```ts
+es.addInter('', async (id, event, es) => {
+  console.log(`[${id}]`, event);
+  return event; // pass through unchanged
+});
+```
+
+If an interceptor throws an error, the chain stops and listeners are **not** called.
+
+---
+
+### `removeInter(id: string, interceptor: EventInterceptorType): void`
+
+Removes a specific interceptor from the given address.
+
+```ts
+const interceptor = async (id: string, event: number, es: EventSystem) => {
+  return event + 1;
+};
+
+es.addInter('counter', interceptor);
+es.removeInter('counter', interceptor);
+```
+
+---
+
+### `setLoader(id: string, loader, loaderCatch?): void`
+
+Configures a **loader** function for the given address. The loader is a lazy data fetcher that runs automatically when:
+
+1. The first listener registers on an address, **and**
+2. No value has been sent to that address yet.
+
+If a value was already sent before the first listener, the loader is **never** called.
+
+The loader function receives the address `id` as the first argument, and should call `es.send(id, value)` to deliver the loaded value.
+
+```ts
+es.setLoader('user/profile', async (id) => {
+  const response = await fetch('/api/profile');
+  const data = await response.json();
+  es.send(id, data);
+});
+
+// The loader runs automatically when the first listener registers
+es.listen('user/profile', (profile) => {
+  console.log(profile); // data from API
+});
+```
+
+**With error handler (`loaderCatch`):**
+
+The optional third argument is an error handler invoked when the loader throws. It has three possible behaviors:
+
+- **Return a value**: The loader resolves successfully with that value (sent to listeners).
+- **Return `undefined`** (or no return): The loader rejects with the original error.
+- **Throw a new error**: The loader rejects with the new error, and the original error is attached as `error.loaderEx`.
+
+```ts
+es.setLoader(
+  'user/profile',
+  async (id) => {
+    throw new Error('Network error');
+  },
+  async (id, error) => {
+    console.warn('Loader failed:', error.message);
+    return { name: 'Guest' }; // fallback value sent to listeners
+  }
+);
+```
+
+---
+
+### `setLoaderCatch(id: string, loaderCatch): void`
+
+Sets (or replaces) the error handler for the loader of a given address, independently from `setLoader`.
+
+```ts
+es.setLoaderCatch('user/profile', async (id, error) => {
+  return { name: 'Default' }; // fallback value
+});
+```
+
+---
+
+### `load<T>(id: string, ...args: any[]): Promise<T>`
+
+Manually triggers the loader for the given address. Extra arguments are forwarded to the loader function.
+
+If no loader is configured, returns the current cached value immediately.
+
+```ts
+es.setLoader('data', async (id, page, limit) => {
+  const res = await fetch(`/api/data?page=${page}&limit=${limit}`);
+  es.send(id, await res.json());
+});
+
+// Manually trigger with parameters
+await es.load('data', 1, 20);
+```
+
+## Types
+
+```ts
+// Listener function signature
+type EventListenerType<T = any> = (event: T) => void;
+
+// Interceptor function signature
+type EventInterceptorType<T = any> = (id: string, event: T, es: EventSystem) => T;
+```

package/build/index.d.ts

@@ -1,9 +1,5 @@
-/**
- * Function to exclude an item from the array.
- * @param item Item that will be removed
- * @param list Array where to find the item
- */
-export declare function deleteFromArray(item: any, list: any[]): void;
+export type EventListenerType<T = any> = (event: T) => void;
+export type EventInterceptorType<T = any> = (id: string, event: T, es: EventSystem) => T;
 /**
  * Type that holds the value for an event address.
  */
@@ -15,14 +11,14 @@ export type ES_ValueType = {
     /**
      * Listeners of this event.
      */
-    listeners: ((event: any) => void)[];
+    listeners: EventListenerType[];
     /**
      * Last time an event was emitted.
      *
      * If this value is "null" or "undefined" so no event/value was emitted yet.
      * In this case, the "last" field will be "null" or "undefined" also.
      */
-    date?: Date;
+    date?: number;
     /**
      * Loader to run when the first listeners is registered and no event was
      * emitted yet.
@@ -72,6 +68,19 @@ export declare class EventSystem {
     data: {
         [id: string]: ES_ValueType;
     };
+    /**
+     * Interceptors to transform data.
+     * Interceptors are called in the installation order.
+     * The special empty string event address will be called for all events sent.
+     *
+     * The interceptors exists to transform, monitor, prepare or validate (or many other uses)
+     * the event sent to an address. The sequence of interceptors will be called like a
+     * "chain of responsibility" pattern, if any exception is thrown the following interceptors
+     * will not be executed, and the listeners not called.
+     */
+    inters: {
+        [id: string]: EventInterceptorType[];
+    };
     /**
      * Gets a reference to {@link ES_ValueType} of the address informed.
      * @param id The address name of the event
@@ -81,9 +90,8 @@ export declare class EventSystem {
      * Sends the value to the listeners of the event address.
      * @param id The address name of the event
      * @param event The value to send to listeners
-     * @returns The value informed
      */
-    emit<T>(id: string, event: T): T;
+    send<T>(id: string, event: T): Promise<T>;
     /**
      * Register a listener for the address.
      * The listener will receive the last value emitted.
@@ -95,7 +103,7 @@ export declare class EventSystem {
      * @param listener The listener, will be called every time a new value is emitted to this address
      * @returns An unregister function. Use this function to remove the listener
      */
-    listen(id: string, listener: (event: any) => void): () => void;
+    listen(id: string, listener: EventListenerType): () => void;
     /**
      * Remove the listener from the list of this event address.
      *
@@ -115,7 +123,33 @@ export declare class EventSystem {
      * @param id The address name of the event
      * @param listener Listener to remove
      */
-    unlisten(id: string, listener: (event: any) => void): void;
+    unlisten(id: string, listener: EventListenerType): void;
+    /**
+     * Add an interceptor to transform data.
+     * Interceptors are called in the installation order.
+     * The special empty string event address will be called for all events sent.
+     *
+     * The interceptors exists to transform, monitor, prepare or validate (or many other uses)
+     * the event sent to an address. The sequence of interceptors will be called like a
+     * "chain of responsibility" pattern, if any exception is thrown the following interceptors
+     * will not be executed, and the listeners not called.
+     *
+     * Interceptors will be executed synchronous in the call of the {@link send} method.
+     * So any exception thrown will be thrown also in the {@link send} call.
+     *
+     * @param id The address name of the event
+     * @param listener Interceptor to add
+     * @returns An unregister function. Use this function to remove the interceptor
+     */
+    addInter(id: string, listener: EventInterceptorType): () => void;
+    /**
+     * Remove an interceptor.
+     *
+     * @param id The address name of the event
+     * @param listener Interceptor to add
+     * @returns An unregister function. Use this function to remove the interceptor
+     */
+    removeInter(id: string, listener: EventInterceptorType): void;
     /**
      * Configure a {@link ES_ValueType.loader loader} to execute when the first listener is registered and no value exists yet.
      *

package/build/index.js

@@ -1,7 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.es = exports.EventSystem = void 0;
-exports.deleteFromArray = deleteFromArray;
 // -------
 /**
  * Function to exclude an item from the array.
@@ -9,13 +8,9 @@ exports.deleteFromArray = deleteFromArray;
  * @param list Array where to find the item
  */
 function deleteFromArray(item, list) {
-    for (let i = list.length; i > -1; i--) {
-        let it = list[i];
-        if (it === item) {
-            list.splice(i, 1);
-            break;
-        }
-    }
+    const i = list.indexOf(item);
+    if (i !== -1)
+        list.splice(i, 1);
 }
 /**
  * Class that creates the field through which communication will occur.
@@ -27,6 +22,17 @@ class EventSystem {
          * holds the last value for the address.
          */
         this.data = {};
+        /**
+         * Interceptors to transform data.
+         * Interceptors are called in the installation order.
+         * The special empty string event address will be called for all events sent.
+         *
+         * The interceptors exists to transform, monitor, prepare or validate (or many other uses)
+         * the event sent to an address. The sequence of interceptors will be called like a
+         * "chain of responsibility" pattern, if any exception is thrown the following interceptors
+         * will not be executed, and the listeners not called.
+         */
+        this.inters = {};
     }
     /**
      * Gets a reference to {@link ES_ValueType} of the address informed.
@@ -41,15 +47,32 @@ class EventSystem {
      * Sends the value to the listeners of the event address.
      * @param id The address name of the event
      * @param event The value to send to listeners
-     * @returns The value informed
      */
-    emit(id, event) {
+    async send(id, event) {
+        let inters = (this.inters[''] || []).concat(this.inters[id] || []);
+        let newValue = event;
+        try {
+            for (let inte of inters) {
+                newValue = await inte(id, newValue, this);
+            }
+        }
+        catch (err) {
+            console.error(`inter:${id}`, err);
+            throw err;
+        }
         let esData = this.get(id);
-        esData.last = event;
-        esData.date = new Date();
-        for (let func of esData.listeners)
-            func(event);
-        return event;
+        esData.last = newValue;
+        esData.date = Date.now();
+        for (let func of esData.listeners) {
+            try {
+                await func(newValue);
+            }
+            catch (err) {
+                console.error(`listen:${id}`, err);
+                throw err;
+            }
+        }
+        return newValue;
     }
     /**
      * Register a listener for the address.
@@ -94,6 +117,39 @@ class EventSystem {
         let esData = this.get(id);
         deleteFromArray(listener, esData.listeners);
     }
+    /**
+     * Add an interceptor to transform data.
+     * Interceptors are called in the installation order.
+     * The special empty string event address will be called for all events sent.
+     *
+     * The interceptors exists to transform, monitor, prepare or validate (or many other uses)
+     * the event sent to an address. The sequence of interceptors will be called like a
+     * "chain of responsibility" pattern, if any exception is thrown the following interceptors
+     * will not be executed, and the listeners not called.
+     *
+     * Interceptors will be executed synchronous in the call of the {@link send} method.
+     * So any exception thrown will be thrown also in the {@link send} call.
+     *
+     * @param id The address name of the event
+     * @param listener Interceptor to add
+     * @returns An unregister function. Use this function to remove the interceptor
+     */
+    addInter(id, listener) {
+        if (!this.inters[id])
+            this.inters[id] = [];
+        this.inters[id].push(listener);
+        return () => this.removeInter(id, listener);
+    }
+    /**
+     * Remove an interceptor.
+     *
+     * @param id The address name of the event
+     * @param listener Interceptor to add
+     * @returns An unregister function. Use this function to remove the interceptor
+     */
+    removeInter(id, listener) {
+        deleteFromArray(listener, this.inters[id]);
+    }
     /**
      * Configure a {@link ES_ValueType.loader loader} to execute when the first listener is registered and no value exists yet.
      *
@@ -149,7 +205,7 @@ class EventSystem {
                     try {
                         const catchRes = await esData.loaderCatch(id, ex);
                         if (catchRes !== undefined) {
-                            this.emit(id, catchRes);
+                            this.send(id, catchRes);
                             res(catchRes);
                         }
                     }

package/nul

@@ -0,0 +1,2 @@
+ERRO: Argumento/op��o inv�lido - 'F:/'.
+Digite "TASKKILL /?" para obter detalhes sobre o uso.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "comes",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Simple Event System Communication",
   "keywords": [
     "event",