ts-util-core 2.0.0

package/README.md

@@ -0,0 +1,411 @@
+<p align="center">
+  <img src="docs/banner.svg" alt="TS-Util — Type-safe form validation, AJAX, messaging, and view management" width="100%" />
+</p>
+
+<p align="center">
+  <strong>The form infrastructure toolkit for enterprise web apps.</strong><br/>
+  Drop jQuery. Keep the patterns. Ship with confidence.
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a>&ensp;&bull;&ensp;
+  <a href="#live-demo">Live Demo</a>&ensp;&bull;&ensp;
+  <a href="#modules">Modules</a>&ensp;&bull;&ensp;
+  <a href="#api-reference">API Reference</a>&ensp;&bull;&ensp;
+  <a href="docs/good-design-pattern-implementation-after.md">Design Patterns</a>
+</p>
+
+---
+
+## Why TS-Util?
+
+| Pain point | How this library solves it |
+|---|---|
+| **"Our forms need validation, masking, AJAX, dialogs — that's 4 libraries."** | One import. Six modules. Zero dependencies. |
+| **"Dynamic content loaded via AJAX has no validation."** | `VIEW.load()` auto-initializes constraints and formatters on every fragment. |
+| **"Adding a custom input format means touching library internals."** | `Formatter.add({ key, format })` — register from the outside, never fork. |
+| **"Runtime surprises: wrong callback shape, misspelled event name."** | Every event, callback, and option is type-checked at compile time. |
+
+### The deeper reason: discipline at scale
+
+Every frontend project eventually hits the same problem: ten engineers (or ten AI Agents) write ten different ways to make an AJAX call. Should you validate the form before sending? Show a loading overlay? How should errors be handled? Everyone has a different answer, and code review can only do so much.
+
+**TS-Util encodes decisions into infrastructure.** When you call `AJAX.request()`, form validation, loading state management, error broadcasting, and data serialization all happen automatically. You can't skip any of them — and neither can your teammates or your AI coding assistants.
+
+**For teams** — engineers learn one API, new members read one example to get started, and every request flows through the same pipeline. No debates, no divergence.
+
+**For AI Agents** — an Agent emits `AJAX.request({ url, form })` instead of expanding the full fetch + validation + error handling logic every time. Context window is AI's most precious resource; saving tokens preserves quality. The abstraction layer also acts as a guardrail — an Agent cannot "forget" to validate a form because the architecture enforces it automatically.
+
+> **Wrapping isn't about writing less code — it's about making ten people, or ten Agents, produce output that looks like it came from one.**
+
+📖 Read the full article in [six languages](docs/why-wrap-ajax-and-view.md) (繁體中文 · English · 日本語 · 한국어 · Español · Deutsch)
+
+---
+
+## Live Demo
+
+> **[Open `demo.html`](demo.html)** — an interactive single-page guide with live output consoles for every module.
+>
+> ```bash
+> npx serve .        # then open http://localhost:3000/demo.html
+> ```
+
+The demo lets you click through Events, AJAX, Validation, Formatting, MSG dialogs, VIEW injection, and utility functions — with code snippets alongside real-time results.
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+npm install ts-util-core
+```
+
+### Import what you need
+
+```typescript
+import { AJAX, VIEW, MSG, Validation, Formatter, Events } from 'ts-util-core';
+```
+
+### Or use the global namespace (legacy `<script>` tags)
+
+```html
+<script type="module" src="dist/index.js"></script>
+<script>
+  const { AJAX, MSG } = window['#'];
+</script>
+```
+
+### A real-world example in 12 lines
+
+```typescript
+import { AJAX, MSG, Events } from 'ts-util-core';
+
+// Listen for lifecycle events
+Events.on('ajax:before', ({ url }) => showSpinner(url));
+Events.on('ajax:after',  ({ url }) => hideSpinner(url));
+
+// Submit a form with auto-validation
+await AJAX.request({
+  url: '/api/orders',
+  form: document.getElementById('order-form')!,
+  success: () => MSG.info('Order saved!', { autoclose: 3000 }),
+});
+```
+
+That single `AJAX.request()` call will:
+1. Validate all `constraint="required"` fields in the form
+2. Emit `ajax:before` (your spinner appears)
+3. Serialize the form to JSON and POST it
+4. Emit `ajax:after` (spinner hides)
+5. Call your `success` callback
+
+---
+
+## Architecture
+
+```
+                        ┌─────────────────┐
+                        │  EventEmitter   │  ← Typed central bus
+                        │  (Mediator)     │
+                        └──┬──┬──┬──┬─────┘
+                  ┌────────┘  │  │  └────────┐
+                  ▼           ▼  ▼           ▼
+             ┌────────┐  ┌──────┐  ┌───────────┐  ┌───────────┐
+             │  AJAX  │  │ VIEW │  │ Validation │  │ Formatter │
+             │Facade +│  │Observ│  │ Strategy + │  │ Registry  │
+             │Template│  │  er  │  │ Decorator  │  │  Pattern  │
+             └────────┘  └──────┘  └───────────┘  └───────────┘
+                  │           │          │               │
+                  └─────┬─────┘     ┌────┘               │
+                        ▼           ▼                    ▼
+                    ┌───────┐  ┌──────────┐     ┌──────────────┐
+                    │  MSG  │  │  Utils   │     │ HTML attrs   │
+                    │Dialogs│  │sprintf,  │     │ constraint=  │
+                    └───────┘  │formToJSON│     │ format=      │
+                               └──────────┘     └──────────────┘
+```
+
+All modules communicate through the typed `EventEmitter` — no module imports another directly. This makes every piece independently testable and replaceable.
+
+---
+
+## Modules
+
+### Events — the central bus
+
+```typescript
+// Subscribe with full type safety — event names and payloads are checked
+Events.on('ajax:before', ({ url }) => console.log(url));     // url: string
+Events.on('ajax:error',  ({ url, error }) => log(error));    // error: Error
+
+// Unsubscribe
+const off = Events.on('ajax:after', handler);
+off(); // done
+```
+
+**Available events:**
+
+| Event | Payload | Fired when |
+|-------|---------|------------|
+| `ajax:before` | `{ url }` | Request starts (unless `noblock`) |
+| `ajax:after` | `{ url }` | Request completes |
+| `ajax:error` | `{ url, error }` | Request fails |
+| `view:beforeLoad` | `{ context }` | New DOM fragment initializes |
+| `validation:invalid` | `{ labelNames, elements }` | Required fields missing |
+| `validation:textareaTooLong` | `{ labelNames, maxlengths, elements }` | Textarea exceeds limit |
+
+---
+
+### AJAX — fetch with lifecycle
+
+```typescript
+// Simple POST
+await AJAX.request({
+  url: '/api/save',
+  data: { name: 'Alice' },
+  success: (res) => console.log('Done'),
+});
+
+// POST with auto-validation + form serialization
+await AJAX.request({
+  url: '/api/save',
+  form: document.getElementById('myForm')!,
+});
+
+// Typed JSON response
+const user = await AJAX.requestJSON<User>({
+  url: '/api/user/1',
+  success: (data) => { /* data is User, not unknown */ },
+});
+```
+
+---
+
+### Validation — declarative constraints
+
+Declare in HTML, the library does the rest:
+
+```html
+<input constraint="required"             labelName="Name" />
+<input constraint="required number"      labelName="Amount" />
+<input constraint="required upperCase onlyEn" labelName="Code" />
+<input constraint="date"                 labelName="Start Date" />
+<input constraint="time"                 labelName="Meeting Time" />
+```
+
+**Built-in constraints:** `required` `number` `date` `time` `upperCase` `onlyEn`
+
+**Add your own:**
+
+```typescript
+Validation.addConstraint({
+  name: 'email',
+  attach(el) {
+    el.addEventListener('change', () => {
+      if (el.value && !el.value.includes('@')) el.value = '';
+    });
+  },
+});
+// Now use: <input constraint="required email" labelName="Email" />
+```
+
+**Customize error handling:**
+
+```typescript
+Validation.setRequiredInvalidCallback((labelNames, elements) => {
+  // Replace the default alert with your own UI
+  showToast(`Missing: ${labelNames.join(', ')}`);
+  elements[0]?.focus();
+});
+```
+
+---
+
+### Formatting — input masks
+
+Declare in HTML:
+
+```html
+<input format="idNumber" />   <!-- A123456789 -->
+<input format="date" />       <!-- 2026-02-24 (auto-inserts dashes) -->
+<input format="time" />       <!-- 14:30 (auto-inserts colon) -->
+```
+
+**Register custom formatters:**
+
+```typescript
+Formatter.add({
+  key: 'phone',
+  format: (el) => {
+    el.placeholder = '09XX-XXX-XXX';
+    el.addEventListener('input', () => {
+      let v = el.value.replace(/\D/g, '');
+      if (v.length > 4) v = v.slice(0, 4) + '-' + v.slice(4);
+      if (v.length > 8) v = v.slice(0, 8) + '-' + v.slice(8);
+      el.value = v.slice(0, 12);
+    });
+  },
+});
+```
+
+---
+
+### MSG — vanilla DOM dialogs
+
+```typescript
+// Auto-closing notification
+MSG.info('Saved!', { title: 'Success', autoclose: 3000 });
+
+// Modal (must click OK)
+MSG.modal('Session expired.', { title: 'Warning' });
+
+// Confirmation
+MSG.confirm('Delete', 'Are you sure?', () => {
+  deleteRecord();
+});
+
+// Dismiss programmatically
+MSG.dismissModal();
+```
+
+---
+
+### VIEW — dynamic content with auto-init
+
+```typescript
+// Load an HTML fragment — constraints + formatters auto-initialize
+await VIEW.load(document.getElementById('container')!, {
+  url: '/api/partial-view',
+});
+
+// Or inject manually and trigger hooks
+container.innerHTML = htmlString;
+VIEW.invokeBeforeLoad(container);
+
+// Register your own hook
+VIEW.addBeforeLoad((context) => {
+  context.querySelectorAll('.tooltip').forEach(initTooltip);
+});
+```
+
+---
+
+### Utilities
+
+```typescript
+import { sprintf, formToJSON, isDateValid } from 'ts-util-core';
+
+sprintf('Hello %s, you are %d years old', 'Alice', 30);
+// → "Hello Alice, you are 30 years old"
+
+sprintf('Price: $%.2f', 9.5);
+// → "Price: $9.50"
+
+const data = formToJSON(formElement);
+// → { username: "alice", role: "viewer" }
+
+isDateValid('2026-02-24');  // → true
+isDateValid('not-a-date');  // → false
+```
+
+---
+
+## API Reference
+
+### Singletons (pre-wired, ready to use)
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `AJAX` | `Ajax` | HTTP client with form validation integration |
+| `VIEW` | `View` | Dynamic HTML fragment loader |
+| `MSG` | `Message` | DOM dialog system |
+| `Validation` | `Validator` | Form validation engine |
+| `Formatter` | `FormatterRegistry` | Input mask registry |
+| `Events` | `EventEmitter<TSUtilEventMap>` | Typed event bus |
+
+### Utility functions
+
+| Export | Signature | Description |
+|--------|-----------|-------------|
+| `sprintf` | `(fmt: string, ...args) => string` | printf-style string formatting |
+| `formToJSON` | `(container: HTMLElement, options?) => FormDataRecord` | Serialize form inputs to JSON |
+| `isDateValid` | `(value: string) => boolean` | Validate date strings |
+| `parseHTML` | `(html: string) => HTMLElement` | Parse HTML string to DOM |
+| `scrollToElement` | `(el: HTMLElement) => void` | Smooth scroll to element |
+| `defaults` | `<T>(base: T, ...overrides: Partial<T>[]) => T` | Merge defaults with overrides |
+
+### Classes (for advanced use / testing)
+
+| Export | Description |
+|--------|-------------|
+| `EventEmitter<T>` | Create isolated event buses for testing |
+| `Ajax` | Instantiate with a custom emitter |
+| `View` | Instantiate with a custom emitter + ajax |
+| `Message` | Standalone dialog system |
+| `Validator` | Standalone validator with custom emitter |
+| `FormatterRegistry` | Standalone formatter registry |
+
+---
+
+## Project Structure
+
+```
+src/
+├── index.ts                  # Barrel export + singleton wiring
+├── types.ts                  # Shared type definitions
+├── core/
+│   ├── event-emitter.ts      # Typed EventEmitter (Mediator)
+│   ├── ajax.ts               # HTTP client (Facade + Template Method)
+│   ├── view.ts               # Fragment loader (Observer)
+│   └── message.ts            # Dialog system (Facade)
+├── validation/
+│   ├── validator.ts           # Validation engine (Strategy)
+│   └── constraints.ts         # Built-in constraints (Decorator)
+├── formatting/
+│   ├── registry.ts            # Formatter registry (Registry Pattern)
+│   └── formatters.ts          # Built-in formatters
+└── utils/
+    ├── sprintf.ts             # printf-style formatting
+    └── dom.ts                 # DOM helpers
+```
+
+**12 source files &middot; ~1,600 lines &middot; strict TypeScript &middot; ES2022 target &middot; zero dependencies**
+
+---
+
+## Build
+
+```bash
+npm run build          # one-shot compile
+npm run dev            # watch mode
+```
+
+Output goes to `dist/` with `.js`, `.d.ts`, and source maps.
+
+---
+
+## Design Patterns
+
+This library is a teaching-friendly codebase. Every module implements a named GoF pattern:
+
+| Pattern | Module | What it teaches |
+|---------|--------|----------------|
+| **Mediator** | `EventEmitter` | Decoupled inter-module communication |
+| **Facade** | `AJAX`, `MSG` | Hide multi-step complexity behind one call |
+| **Template Method** | `requestJSON()` | Reuse a base algorithm, customize one step |
+| **Observer** | `VIEW.addBeforeLoad()` | Plugin registration without coupling |
+| **Strategy** | `setRequiredInvalidCallback()` | Replace behavior without modifying source |
+| **Registry** | `Formatter` | Extensible key-based lookup |
+| **Decorator** | `constraint="..."` attributes | Composable behavior via HTML |
+
+Deep-dive documentation:
+- **[Before (jQuery)](docs/good-design-pattern-implementation-before.md)** — patterns in the original codebase
+- **[After (TypeScript)](docs/good-design-pattern-implementation-after.md)** — how TypeScript makes them safer
+
+---
+
+## License
+
+MIT

package/dist/core/ajax.d.ts

@@ -0,0 +1,30 @@
+import type { EventEmitter } from './event-emitter.js';
+import type { AppEventMap, AjaxRequestParams, AjaxJsonRequestParams } from '../types.js';
+export declare class Ajax {
+    private emitter;
+    private validateForm;
+    constructor(emitter: EventEmitter<AppEventMap>);
+    /** Register the form validation function (injected by the Validation module). */
+    setValidator(fn: (form: HTMLElement) => boolean): void;
+    /**
+     * Send an HTTP request (POST by default).
+     *
+     * Lifecycle:
+     * 1. Validate form (if `params.form` provided)
+     * 2. Emit `ajax:before`
+     * 3. Serialize form data + merge `params.data`
+     * 4. `fetch()`
+     * 5. Emit `ajax:after` (on success) or `ajax:error` (on failure)
+     * 6. Call `params.success` / `params.error` / `params.complete`
+     *
+     * @returns The raw `Response`, or `undefined` if validation failed.
+     */
+    request(params: AjaxRequestParams): Promise<Response | undefined>;
+    /**
+     * Send a request and parse the response as JSON.
+     *
+     * Template Method — delegates to `request()`, adds JSON parsing.
+     */
+    requestJSON<T = unknown>(params: AjaxJsonRequestParams<T>): Promise<T | undefined>;
+}
+//# sourceMappingURL=ajax.d.ts.map

package/dist/core/ajax.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ajax.d.ts","sourceRoot":"","sources":["../../src/core/ajax.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGzF,qBAAa,IAAI;IACf,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,YAAY,CAAiD;gBAEzD,OAAO,EAAE,YAAY,CAAC,WAAW,CAAC;IAI9C,iFAAiF;IACjF,YAAY,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,GAAG,IAAI;IAItD;;;;;;;;;;;;OAYG;IACG,OAAO,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAkEvE;;;;OAIG;IACG,WAAW,CAAC,CAAC,GAAG,OAAO,EAC3B,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC/B,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;CAW1B"}

package/dist/core/ajax.js

@@ -0,0 +1,110 @@
+// ---------------------------------------------------------------------------
+// AJAX module — fetch-based HTTP client with lifecycle hooks
+//
+// Design patterns used:
+//   - Facade Pattern         : one `request()` call orchestrates validate →
+//                              block → serialize → fetch → unblock
+//   - Template Method Pattern: `requestJSON` / `post` / `postJSON` delegate
+//                              to the base `request` with tweaked options
+//   - Strategy Pattern       : loading overlay behavior is injected via
+//                              the EventEmitter (ajax:before / ajax:after)
+// ---------------------------------------------------------------------------
+import { formToJSON } from '../utils/dom.js';
+export class Ajax {
+    emitter;
+    validateForm = null;
+    constructor(emitter) {
+        this.emitter = emitter;
+    }
+    /** Register the form validation function (injected by the Validation module). */
+    setValidator(fn) {
+        this.validateForm = fn;
+    }
+    /**
+     * Send an HTTP request (POST by default).
+     *
+     * Lifecycle:
+     * 1. Validate form (if `params.form` provided)
+     * 2. Emit `ajax:before`
+     * 3. Serialize form data + merge `params.data`
+     * 4. `fetch()`
+     * 5. Emit `ajax:after` (on success) or `ajax:error` (on failure)
+     * 6. Call `params.success` / `params.error` / `params.complete`
+     *
+     * @returns The raw `Response`, or `undefined` if validation failed.
+     */
+    async request(params) {
+        // 1. Validate
+        if (params.form && this.validateForm) {
+            if (!this.validateForm(params.form))
+                return undefined;
+        }
+        // 2. Before-hook
+        if (!params.noblock) {
+            this.emitter.emit('ajax:before', { url: params.url });
+        }
+        // 3. Build body
+        const body = {};
+        if (params.form) {
+            const formData = formToJSON(params.form, {
+                ignoreDisabled: params.ignoreDisabled,
+            });
+            Object.assign(body, formData);
+        }
+        if (params.data) {
+            Object.assign(body, params.data);
+        }
+        // 4. Fetch
+        const headers = {
+            'Content-Type': 'application/json',
+            'Ajax-Call': 'true',
+            ...params.headers,
+        };
+        try {
+            const response = await fetch(params.url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            // 5a. After-hook (success)
+            if (!params.noblock) {
+                this.emitter.emit('ajax:after', { url: params.url });
+            }
+            params.success?.(response);
+            return response;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            // 5b. After-hook (error)
+            if (!params.noblock) {
+                this.emitter.emit('ajax:after', { url: params.url });
+            }
+            this.emitter.emit('ajax:error', { url: params.url, error });
+            params.error?.(error);
+            return undefined;
+        }
+        finally {
+            params.complete?.();
+        }
+    }
+    /**
+     * Send a request and parse the response as JSON.
+     *
+     * Template Method — delegates to `request()`, adds JSON parsing.
+     */
+    async requestJSON(params) {
+        const response = await this.request({
+            ...params,
+            success: undefined, // we handle success after JSON parse
+        });
+        if (!response)
+            return undefined;
+        const data = (await response.json());
+        params.success?.(data);
+        return data;
+    }
+}
+//# sourceMappingURL=ajax.js.map

package/dist/core/ajax.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ajax.js","sourceRoot":"","sources":["../../src/core/ajax.ts"],"names":[],"mappings":"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"}

package/dist/core/event-emitter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A fully typed event emitter.
+ *
+ * `TEvents` is a map of `{ eventName: payloadType }`.
+ * All `on`, `off`, and `emit` calls are type-checked against this map.
+ *
+ * @example
+ * ```ts
+ * const emitter = new EventEmitter<{ 'ajax:before': { url: string } }>();
+ * emitter.on('ajax:before', ({ url }) => console.log(url));
+ * emitter.emit('ajax:before', { url: '/api' });
+ * ```
+ */
+export declare class EventEmitter<TEvents extends {
+    [K in keyof TEvents]: unknown;
+}> {
+    private listeners;
+    /** Subscribe to an event. Returns an unsubscribe function. */
+    on<K extends keyof TEvents>(event: K, listener: (payload: TEvents[K]) => void): () => void;
+    /** Unsubscribe a specific listener. */
+    off<K extends keyof TEvents>(event: K, listener: (payload: TEvents[K]) => void): void;
+    /** Subscribe to an event — listener is automatically removed after one call. */
+    once<K extends keyof TEvents>(event: K, listener: (payload: TEvents[K]) => void): () => void;
+    /** Emit an event, calling all registered listeners with the payload. */
+    emit<K extends keyof TEvents>(event: K, payload: TEvents[K]): void;
+    /** Remove all listeners for a specific event, or all events if none specified. */
+    clear(event?: keyof TEvents): void;
+}
+//# sourceMappingURL=event-emitter.d.ts.map

package/dist/core/event-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-emitter.d.ts","sourceRoot":"","sources":["../../src/core/event-emitter.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAY,CAAC,OAAO,SAAS;KAAG,CAAC,IAAI,MAAM,OAAO,GAAG,OAAO;CAAE;IACzE,OAAO,CAAC,SAAS,CAGb;IAEJ,8DAA8D;IAC9D,EAAE,CAAC,CAAC,SAAS,MAAM,OAAO,EACxB,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,GACtC,MAAM,IAAI;IAab,uCAAuC;IACvC,GAAG,CAAC,CAAC,SAAS,MAAM,OAAO,EACzB,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,GACtC,IAAI;IAIP,gFAAgF;IAChF,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,EAC1B,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,GACtC,MAAM,IAAI;IASb,wEAAwE;IACxE,IAAI,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IAQlE,kFAAkF;IAClF,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,OAAO,GAAG,IAAI;CAOnC"}

package/dist/core/event-emitter.js

@@ -0,0 +1,67 @@
+// ---------------------------------------------------------------------------
+// Typed EventEmitter — the unified hook / callback system
+//
+// Design patterns used:
+//   - Observer Pattern : multiple listeners subscribe to named events
+//   - Strategy Pattern : consumers replace default behavior via listeners
+//   - Generics         : the event map is fully typed at compile time
+// ---------------------------------------------------------------------------
+/**
+ * A fully typed event emitter.
+ *
+ * `TEvents` is a map of `{ eventName: payloadType }`.
+ * All `on`, `off`, and `emit` calls are type-checked against this map.
+ *
+ * @example
+ * ```ts
+ * const emitter = new EventEmitter<{ 'ajax:before': { url: string } }>();
+ * emitter.on('ajax:before', ({ url }) => console.log(url));
+ * emitter.emit('ajax:before', { url: '/api' });
+ * ```
+ */
+export class EventEmitter {
+    listeners = new Map();
+    /** Subscribe to an event. Returns an unsubscribe function. */
+    on(event, listener) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        const set = this.listeners.get(event);
+        set.add(listener);
+        // Return unsubscribe function for convenience
+        return () => {
+            set.delete(listener);
+        };
+    }
+    /** Unsubscribe a specific listener. */
+    off(event, listener) {
+        this.listeners.get(event)?.delete(listener);
+    }
+    /** Subscribe to an event — listener is automatically removed after one call. */
+    once(event, listener) {
+        const wrapper = ((payload) => {
+            this.off(event, wrapper);
+            listener(payload);
+        });
+        return this.on(event, wrapper);
+    }
+    /** Emit an event, calling all registered listeners with the payload. */
+    emit(event, payload) {
+        const set = this.listeners.get(event);
+        if (!set)
+            return;
+        for (const listener of set) {
+            listener(payload);
+        }
+    }
+    /** Remove all listeners for a specific event, or all events if none specified. */
+    clear(event) {
+        if (event) {
+            this.listeners.delete(event);
+        }
+        else {
+            this.listeners.clear();
+        }
+    }
+}
+//# sourceMappingURL=event-emitter.js.map

package/dist/core/event-emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-emitter.js","sourceRoot":"","sources":["../../src/core/event-emitter.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,0DAA0D;AAC1D,EAAE;AACF,wBAAwB;AACxB,sEAAsE;AACtE,0EAA0E;AAC1E,sEAAsE;AACtE,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,YAAY;IACf,SAAS,GAAG,IAAI,GAAG,EAGxB,CAAC;IAEJ,8DAA8D;IAC9D,EAAE,CACA,KAAQ,EACR,QAAuC;QAEvC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;QACvC,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC;QACvC,GAAG,CAAC,GAAG,CAAC,QAAoC,CAAC,CAAC;QAE9C,8CAA8C;QAC9C,OAAO,GAAG,EAAE;YACV,GAAG,CAAC,MAAM,CAAC,QAAoC,CAAC,CAAC;QACnD,CAAC,CAAC;IACJ,CAAC;IAED,uCAAuC;IACvC,GAAG,CACD,KAAQ,EACR,QAAuC;QAEvC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,QAAoC,CAAC,CAAC;IAC1E,CAAC;IAED,gFAAgF;IAChF,IAAI,CACF,KAAQ,EACR,QAAuC;QAEvC,MAAM,OAAO,GAAG,CAAC,CAAC,OAAmB,EAAE,EAAE;YACvC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YACzB,QAAQ,CAAC,OAAO,CAAC,CAAC;QACpB,CAAC,CAAkC,CAAC;QAEpC,OAAO,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,wEAAwE;IACxE,IAAI,CAA0B,KAAQ,EAAE,OAAmB;QACzD,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,CAAC,GAAG;YAAE,OAAO;QACjB,KAAK,MAAM,QAAQ,IAAI,GAAG,EAAE,CAAC;YAC1B,QAA0C,CAAC,OAAO,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,kFAAkF;IAClF,KAAK,CAAC,KAAqB;QACzB,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACzB,CAAC;IACH,CAAC;CACF"}