comes 0.0.3 → 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

@@ -18,7 +18,7 @@ export type ES_ValueType = {
      * 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.

package/build/index.js

@@ -8,13 +8,9 @@ exports.es = exports.EventSystem = void 0;
  * @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.
@@ -53,7 +49,7 @@ class EventSystem {
      * @param event The value to send to listeners
      */
     async send(id, event) {
-        let inters = [...(this.inters[''] || []), ...(this.inters[id] || [])];
+        let inters = (this.inters[''] || []).concat(this.inters[id] || []);
         let newValue = event;
         try {
             for (let inte of inters) {
@@ -61,18 +57,18 @@ class EventSystem {
             }
         }
         catch (err) {
-            console.error(`error on interceptor of ${id}`, err);
+            console.error(`inter:${id}`, err);
             throw err;
         }
         let esData = this.get(id);
         esData.last = newValue;
-        esData.date = new Date();
+        esData.date = Date.now();
         for (let func of esData.listeners) {
             try {
                 await func(newValue);
             }
             catch (err) {
-                console.error(`Error on listener of ${id}, ${func}`, err);
+                console.error(`listen:${id}`, err);
                 throw err;
             }
         }

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.3",
+  "version": "0.0.4",
   "description": "Simple Event System Communication",
   "keywords": [
     "event",