ts-util-core 2.0.1 → 2.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +99 -26
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,56 +1,117 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<img src="docs/banner.svg" alt="TS-Util —
|
|
2
|
+
<img src="https://raw.githubusercontent.com/MattAtAIEra/TS-Util/main/docs/banner.svg" alt="TS-Util — Agent Discipline for Humans and AI" width="100%" />
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
5
|
<p align="center">
|
|
6
|
-
<strong>
|
|
7
|
-
Drop jQuery. Keep the patterns. Ship with confidence.
|
|
6
|
+
<strong>One pipeline. Same guardrails. Whether it's your team or your AI Agents writing the code.</strong>
|
|
8
7
|
</p>
|
|
9
8
|
|
|
10
9
|
<p align="center">
|
|
10
|
+
<a href="#1-why-agent-discipline">Why</a> • 
|
|
11
|
+
<a href="#2-how-it-works">How</a> • 
|
|
12
|
+
<a href="#3-advantages">Advantages</a> • 
|
|
11
13
|
<a href="#quick-start">Quick Start</a> • 
|
|
12
14
|
<a href="#live-demo">Live Demo</a> • 
|
|
13
15
|
<a href="#modules">Modules</a> • 
|
|
14
|
-
<a href="#api-reference">API
|
|
15
|
-
<a href="https://github.com/MattAtAIEra/TS-Util/blob/main/docs/good-design-pattern-implementation-after.md">Design Patterns</a>
|
|
16
|
+
<a href="#api-reference">API</a>
|
|
16
17
|
</p>
|
|
17
18
|
|
|
18
19
|
---
|
|
19
20
|
|
|
20
|
-
## Why
|
|
21
|
+
## 1. Why Agent Discipline?
|
|
21
22
|
|
|
22
|
-
|
|
23
|
+
You don't have a code quality problem. You have a **consistency problem.**
|
|
24
|
+
|
|
25
|
+
Ten engineers write ten different AJAX calls. Ten AI Agents generate ten different fetch patterns. Some validate forms, some don't. Some show loading overlays, some forget. Some handle errors gracefully, some swallow them silently.
|
|
26
|
+
|
|
27
|
+
Code review catches some of it. **Architecture catches all of it.**
|
|
28
|
+
|
|
29
|
+
| The real problem | What actually happens |
|
|
23
30
|
|---|---|
|
|
24
|
-
|
|
|
25
|
-
|
|
|
26
|
-
|
|
|
27
|
-
|
|
|
31
|
+
| "Every developer does AJAX differently." | Validation gets skipped. Loading spinners are inconsistent. Error handling is a coin flip. |
|
|
32
|
+
| "AI Agents generate verbose, repetitive code." | Each Agent expands `fetch` + validation + error handling + loading from scratch, burning context tokens on boilerplate. |
|
|
33
|
+
| "New team members break conventions." | They didn't know there *was* a convention — it was tribal knowledge, not enforced infrastructure. |
|
|
34
|
+
| "We can't tell if the Agent forgot something." | You'd have to audit every generated function. At scale, that's impossible. |
|
|
28
35
|
|
|
29
|
-
|
|
36
|
+
**The solution is not more code review. The solution is making wrong code impossible to write.**
|
|
30
37
|
|
|
31
|
-
|
|
38
|
+
---
|
|
32
39
|
|
|
33
|
-
|
|
40
|
+
## 2. How It Works
|
|
34
41
|
|
|
35
|
-
|
|
42
|
+
TS-Util wraps AJAX, VIEW, validation, formatting, and messaging into **a single enforced pipeline**. When anyone — human or AI — calls `AJAX.request()`, the following happens automatically:
|
|
36
43
|
|
|
37
|
-
|
|
44
|
+
```
|
|
45
|
+
AJAX.request({ url, form })
|
|
46
|
+
│
|
|
47
|
+
▼
|
|
48
|
+
┌─ 1. Validate form ──────── can't skip
|
|
49
|
+
├─ 2. Emit ajax:before ───── loading overlay
|
|
50
|
+
├─ 3. Serialize + POST ───── consistent format
|
|
51
|
+
├─ 4. Emit ajax:after ────── overlay hides
|
|
52
|
+
└─ 5. Error broadcasting ─── centralized handling
|
|
53
|
+
```
|
|
38
54
|
|
|
39
|
-
|
|
55
|
+
```typescript
|
|
56
|
+
// This is ALL the code an engineer or AI Agent needs to write:
|
|
57
|
+
await AJAX.request({
|
|
58
|
+
url: '/api/orders',
|
|
59
|
+
form: document.getElementById('order-form')!,
|
|
60
|
+
success: () => MSG.info('Saved!', { autoclose: 3000 }),
|
|
61
|
+
});
|
|
40
62
|
|
|
41
|
-
|
|
63
|
+
// Everything else — validation, loading state, error events,
|
|
64
|
+
// data serialization — is handled by the pipeline.
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The same principle applies to `VIEW.load()` — every dynamically loaded HTML fragment automatically goes through constraint binding, input formatting, and custom hook execution. No manual initialization. No "forgetting" to set up validation on new content.
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
// Load HTML fragment — validation + formatting auto-initialize
|
|
71
|
+
await VIEW.load(container, { url: '/api/partial-view' });
|
|
72
|
+
```
|
|
42
73
|
|
|
43
74
|
---
|
|
44
75
|
|
|
45
|
-
##
|
|
76
|
+
## 3. Advantages
|
|
46
77
|
|
|
47
|
-
|
|
78
|
+
### For Engineering Teams
|
|
79
|
+
|
|
80
|
+
| Before | After |
|
|
81
|
+
|--------|-------|
|
|
82
|
+
| 10 engineers, 10 AJAX patterns | 1 API: `AJAX.request()` |
|
|
83
|
+
| New hire reads 10 scattered patterns | New hire reads 1 example, ships on day one |
|
|
84
|
+
| "Did you add the loading overlay?" | Loading overlay is automatic — can't forget |
|
|
85
|
+
| "Did you validate the form?" | Validation is automatic — can't skip |
|
|
86
|
+
| Code review debates on style | Architecture enforces the style |
|
|
87
|
+
|
|
88
|
+
- **Eliminates divergence**: Engineers learn one API — no debates over implementation details.
|
|
89
|
+
- **Enforces consistency**: Every request passes through the same pipeline, ensuring loading overlays aren't missed and validation isn't skipped.
|
|
90
|
+
- **Reduces onboarding cost**: A new team member reads one `AJAX.request()` example and is ready to go, instead of deciphering ten scattered patterns.
|
|
91
|
+
|
|
92
|
+
### For AI Agents
|
|
93
|
+
|
|
94
|
+
| Before | After |
|
|
95
|
+
|--------|-------|
|
|
96
|
+
| Agent expands 15 lines of fetch + validation + error handling | Agent emits 1 line: `AJAX.request({ url, form })` |
|
|
97
|
+
| Context window burned on boilerplate | Tokens preserved for business logic |
|
|
98
|
+
| Different Agents produce different patterns | All Agents produce identical pipeline calls |
|
|
99
|
+
| Must audit every Agent's output for missing steps | Pipeline guarantees completeness — **guardrail by design** |
|
|
100
|
+
| Agent "forgets" loading overlay | Impossible — architecture enforces it |
|
|
101
|
+
|
|
102
|
+
When multiple AI Agents co-produce code, this abstraction layer becomes even more critical:
|
|
103
|
+
|
|
104
|
+
- **Token efficiency**: An Agent only needs to emit `AJAX.request({ url, form })` — one line — instead of expanding the full `fetch` + validation + error handling + loading logic every time. Context window is AI's most precious resource; saving tokens means preserving quality.
|
|
105
|
+
- **Predictable behavior**: Code generated by different Agents flows through the same pipeline, guaranteeing consistent results. You don't need to audit whether each Agent correctly implemented the loading overlay.
|
|
106
|
+
- **Guardrail effect**: The abstraction layer itself acts as a guardrail. An Agent cannot "forget" to validate a form because `AJAX.request()` does it automatically. Discipline is enforced by architecture, not memory.
|
|
107
|
+
|
|
108
|
+
### The Core Insight
|
|
109
|
+
|
|
110
|
+
> **Discipline is not "remembering to do the right thing." Discipline is making the right thing the only thing that can happen.**
|
|
48
111
|
>
|
|
49
|
-
>
|
|
50
|
-
> npx serve . # then open http://localhost:3000/demo.html
|
|
51
|
-
> ```
|
|
112
|
+
> That's what TS-Util does — for your team today, and for the AI Agents that will write most of your code tomorrow.
|
|
52
113
|
|
|
53
|
-
|
|
114
|
+
📖 Read this article in [other languages](https://github.com/MattAtAIEra/TS-Util/blob/main/docs/why-wrap-ajax-and-view.md) (繁體中文 · 日本語 · 한국어 · Español · Deutsch)
|
|
54
115
|
|
|
55
116
|
---
|
|
56
117
|
|
|
@@ -77,7 +138,7 @@ import { AJAX, VIEW, MSG, Validation, Formatter, Events } from 'ts-util-core';
|
|
|
77
138
|
</script>
|
|
78
139
|
```
|
|
79
140
|
|
|
80
|
-
### A real-world example
|
|
141
|
+
### A real-world example
|
|
81
142
|
|
|
82
143
|
```typescript
|
|
83
144
|
import { AJAX, MSG, Events } from 'ts-util-core';
|
|
@@ -103,6 +164,18 @@ That single `AJAX.request()` call will:
|
|
|
103
164
|
|
|
104
165
|
---
|
|
105
166
|
|
|
167
|
+
## Live Demo
|
|
168
|
+
|
|
169
|
+
> **[Open `demo.html`](demo.html)** — an interactive single-page guide with live output consoles for every module.
|
|
170
|
+
>
|
|
171
|
+
> ```bash
|
|
172
|
+
> npx serve . # then open http://localhost:3000/demo.html
|
|
173
|
+
> ```
|
|
174
|
+
|
|
175
|
+
The demo lets you click through Events, AJAX, Validation, Formatting, MSG dialogs, VIEW injection, and utility functions — with code snippets alongside real-time results.
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
106
179
|
## Architecture
|
|
107
180
|
|
|
108
181
|
```
|
|
@@ -323,7 +396,7 @@ isDateValid('not-a-date'); // → false
|
|
|
323
396
|
| `MSG` | `Message` | DOM dialog system |
|
|
324
397
|
| `Validation` | `Validator` | Form validation engine |
|
|
325
398
|
| `Formatter` | `FormatterRegistry` | Input mask registry |
|
|
326
|
-
| `Events` | `EventEmitter<
|
|
399
|
+
| `Events` | `EventEmitter<AppEventMap>` | Typed event bus |
|
|
327
400
|
|
|
328
401
|
### Utility functions
|
|
329
402
|
|