ts-util-core 2.0.1 → 2.0.2
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 +89 -26
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,56 +1,107 @@
|
|
|
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
|
+
### For AI Agents
|
|
89
|
+
|
|
90
|
+
| Before | After |
|
|
91
|
+
|--------|-------|
|
|
92
|
+
| Agent expands 15 lines of fetch + validation + error handling | Agent emits 1 line: `AJAX.request({ url, form })` |
|
|
93
|
+
| Context window burned on boilerplate | Tokens preserved for business logic |
|
|
94
|
+
| Different Agents produce different patterns | All Agents produce identical pipeline calls |
|
|
95
|
+
| Must audit every Agent's output for missing steps | Pipeline guarantees completeness — **guardrail by design** |
|
|
96
|
+
| Agent "forgets" loading overlay | Impossible — architecture enforces it |
|
|
97
|
+
|
|
98
|
+
### The Core Insight
|
|
99
|
+
|
|
100
|
+
> **Discipline is not "remembering to do the right thing." Discipline is making the right thing the only thing that can happen.**
|
|
48
101
|
>
|
|
49
|
-
>
|
|
50
|
-
> npx serve . # then open http://localhost:3000/demo.html
|
|
51
|
-
> ```
|
|
102
|
+
> That's what TS-Util does — for your team today, and for the AI Agents that will write most of your code tomorrow.
|
|
52
103
|
|
|
53
|
-
|
|
104
|
+
📖 Read the full article in [six languages](https://github.com/MattAtAIEra/TS-Util/blob/main/docs/why-wrap-ajax-and-view.md) (繁體中文 · English · 日本語 · 한국어 · Español · Deutsch)
|
|
54
105
|
|
|
55
106
|
---
|
|
56
107
|
|
|
@@ -77,7 +128,7 @@ import { AJAX, VIEW, MSG, Validation, Formatter, Events } from 'ts-util-core';
|
|
|
77
128
|
</script>
|
|
78
129
|
```
|
|
79
130
|
|
|
80
|
-
### A real-world example
|
|
131
|
+
### A real-world example
|
|
81
132
|
|
|
82
133
|
```typescript
|
|
83
134
|
import { AJAX, MSG, Events } from 'ts-util-core';
|
|
@@ -103,6 +154,18 @@ That single `AJAX.request()` call will:
|
|
|
103
154
|
|
|
104
155
|
---
|
|
105
156
|
|
|
157
|
+
## Live Demo
|
|
158
|
+
|
|
159
|
+
> **[Open `demo.html`](demo.html)** — an interactive single-page guide with live output consoles for every module.
|
|
160
|
+
>
|
|
161
|
+
> ```bash
|
|
162
|
+
> npx serve . # then open http://localhost:3000/demo.html
|
|
163
|
+
> ```
|
|
164
|
+
|
|
165
|
+
The demo lets you click through Events, AJAX, Validation, Formatting, MSG dialogs, VIEW injection, and utility functions — with code snippets alongside real-time results.
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
106
169
|
## Architecture
|
|
107
170
|
|
|
108
171
|
```
|
|
@@ -323,7 +386,7 @@ isDateValid('not-a-date'); // → false
|
|
|
323
386
|
| `MSG` | `Message` | DOM dialog system |
|
|
324
387
|
| `Validation` | `Validator` | Form validation engine |
|
|
325
388
|
| `Formatter` | `FormatterRegistry` | Input mask registry |
|
|
326
|
-
| `Events` | `EventEmitter<
|
|
389
|
+
| `Events` | `EventEmitter<AppEventMap>` | Typed event bus |
|
|
327
390
|
|
|
328
391
|
### Utility functions
|
|
329
392
|
|