webspresso 0.0.108 → 0.0.110
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/LICENSE +21 -0
- package/README.md +3 -3
- package/bin/commands/add-esbuild.js +7 -3
- package/bin/commands/add-tailwind.js +9 -5
- package/bin/commands/build.js +20 -4
- package/bin/commands/dev.js +57 -7
- package/bin/commands/doctor.js +42 -1
- package/bin/commands/favicon-generate.js +10 -3
- package/bin/commands/new.js +8 -3
- package/bin/commands/start.js +3 -1
- package/bin/utils/add-command.js +16 -0
- package/core/app.js +45 -3
- package/core/auth/authenticate.js +3 -3
- package/core/auth/hash.js +167 -43
- package/core/auth/index.js +13 -1
- package/core/auth/jwt.js +21 -2
- package/core/auth/manager.js +63 -14
- package/core/auth/middleware.js +4 -2
- package/core/auth/oauth.js +5 -1
- package/core/auth/tokens.js +7 -2
- package/core/auth/totp.js +42 -6
- package/core/auth/user-agent.js +2 -0
- package/core/client/adapter/datastar.js +1401 -0
- package/core/client/api.js +1337 -0
- package/core/client/controller.js +1706 -0
- package/core/client/debug.js +367 -0
- package/core/client/devtool.js +1134 -0
- package/core/client/forms.js +1164 -0
- package/core/client/fragments.js +894 -0
- package/core/client/index.d.ts +59 -0
- package/core/client/index.js +391 -0
- package/core/client/lite.js +175 -0
- package/core/client/server-fragments.js +868 -0
- package/core/client/storage.js +339 -0
- package/core/client/utils.js +281 -0
- package/core/compression/middleware.js +277 -26
- package/core/context/app-context.js +25 -3
- package/core/context/request.js +32 -4
- package/core/errors/middleware.js +14 -0
- package/core/events/dispatcher.js +33 -0
- package/core/forms/flash.js +136 -102
- package/core/health/middleware.js +36 -6
- package/core/http/pipeline.js +45 -6
- package/core/index.js +25 -7
- package/core/kernel/view.js +41 -10
- package/core/metrics/middleware.js +30 -6
- package/core/metrics/registry.js +13 -5
- package/core/orm/cache/fingerprint.js +32 -11
- package/core/orm/cache/layer.js +19 -2
- package/core/orm/hidden.js +145 -0
- package/core/orm/model.js +48 -2
- package/core/orm/query-builder.js +343 -6
- package/core/orm/query-filters.js +14 -2
- package/core/orm/repository.js +64 -13
- package/core/orm/schema-helpers.js +9 -6
- package/core/orm/transaction.js +50 -6
- package/core/orm/types.js +4 -0
- package/core/queue/adapters/database.js +184 -2
- package/core/queue/adapters/memory.js +153 -5
- package/core/queue/adapters/redis.js +59 -4
- package/core/queue/job.js +14 -1
- package/core/queue/manager.js +115 -0
- package/core/resilience/circuit-breaker.js +27 -8
- package/core/services/builtins/exchange.js +174 -7
- package/core/services/builtins/file-manager.js +36 -0
- package/core/services/builtins/mail.js +27 -0
- package/core/services/builtins/queue.js +144 -0
- package/core/services/builtins/security.js +118 -0
- package/core/services/builtins/webhook.js +110 -0
- package/core/services/executor.js +38 -16
- package/core/services/index.js +4 -1
- package/core/sse/stream.js +28 -5
- package/core/utils/timeout.js +8 -1
- package/core/validation/compiler.js +10 -7
- package/index.d.ts +1320 -74
- package/index.js +128 -8
- package/package.json +75 -27
- package/plugins/admin-panel/client/parts/08-record-list.js +717 -70
- package/plugins/admin-panel/index.js +19 -8
- package/plugins/csrf/index.js +3 -3
- package/plugins/data-exchange/export.js +214 -0
- package/plugins/data-exchange/import.js +48 -5
- package/plugins/data-exchange/index.js +70 -28
- package/plugins/data-exchange/preview.js +266 -0
- package/plugins/data-exchange/template.js +242 -0
- package/plugins/email/admin-component.js +783 -141
- package/plugins/email/api-handlers.js +51 -1
- package/plugins/email/index.js +5 -0
- package/plugins/email/service.js +48 -0
- package/plugins/file-manager/admin-component.js +1546 -70
- package/plugins/file-manager/api-handlers.js +166 -1
- package/plugins/file-manager/core.js +598 -8
- package/plugins/file-manager/index.js +8 -0
- package/plugins/index.js +7 -0
- package/plugins/mcp/auth.js +3 -3
- package/plugins/oauth/index.js +36 -3
- package/plugins/queue/admin-component.js +1092 -0
- package/plugins/queue/api-handlers.js +248 -0
- package/plugins/queue/index.js +69 -0
- package/plugins/rest-resources/index.js +7 -2
- package/plugins/security/admin-component.js +689 -0
- package/plugins/security/api-handlers.js +169 -0
- package/plugins/security/audit.js +153 -0
- package/plugins/security/bruteforce.js +244 -0
- package/plugins/security/firewall.js +459 -0
- package/plugins/security/headers.js +214 -0
- package/plugins/security/honeypot.js +234 -0
- package/plugins/security/incident-recorder.js +137 -0
- package/plugins/security/index.js +211 -0
- package/plugins/seo-checker/analyzer.js +20 -7
- package/plugins/upload/index.js +36 -0
- package/plugins/webhooks/admin-component.js +702 -175
- package/plugins/webhooks/api-handlers.js +75 -1
- package/plugins/webhooks/dispatcher.js +290 -11
- package/plugins/webhooks/index.js +37 -2
- package/plugins/webhooks/sender.js +56 -0
- package/plugins/xlsx/engine.js +19 -4
- package/src/api/api-loader.js +19 -1
- package/src/bundle/index.js +443 -17
- package/src/client-runtime/bootstrap-swup.js +9 -0
- package/src/client-runtime/mount.js +15 -20
- package/src/client-runtime/resolve.js +3 -2
- package/src/dev/api-typegen.js +1300 -0
- package/src/dev/banner.js +10 -1
- package/src/dev/colors.js +1 -1
- package/src/dev/index.js +7 -1
- package/src/dev/typegen.js +173 -17
- package/src/dev-reload/index.js +1 -1
- package/src/discovery/file-route-parser.js +17 -3
- package/src/discovery/scan-routes.js +4 -1
- package/src/file-router.js +253 -69
- package/src/helpers.js +46 -26
- package/src/njk-frontmatter.js +30 -4
- package/src/routing/cascading.js +26 -8
- package/src/routing/mount-discovered-routes.js +76 -0
- package/src/server.js +231 -70
- package/views/partials/webspresso-client-runtime.njk +1 -9
- package/.agents/ADMIN.md +0 -426
- package/.agents/AGENTS.md +0 -96
- package/.agents/ARCHITECTURE.md +0 -163
- package/.agents/AUTH.md +0 -581
- package/.agents/CACHE.md +0 -148
- package/.agents/CLI.md +0 -649
- package/.agents/COMPRESSION.md +0 -59
- package/.agents/CONTEXT.md +0 -152
- package/.agents/CONVENTIONS.md +0 -50
- package/.agents/EARLY_HINTS.md +0 -120
- package/.agents/EMAIL.md +0 -223
- package/.agents/ERRORS.md +0 -260
- package/.agents/EVENTS.md +0 -179
- package/.agents/FLAGS.md +0 -118
- package/.agents/HEALTH.md +0 -118
- package/.agents/LIMITS.md +0 -109
- package/.agents/LOGGING.md +0 -93
- package/.agents/MCP.md +0 -103
- package/.agents/METRICS.md +0 -127
- package/.agents/MIGRATION_JOBS.md +0 -95
- package/.agents/ORM.md +0 -700
- package/.agents/PLUGINS.md +0 -729
- package/.agents/QUEUE.md +0 -290
- package/.agents/RATE_LIMIT.md +0 -147
- package/.agents/REALTIME.md +0 -213
- package/.agents/RESILIENCE.md +0 -235
- package/.agents/ROUTING.md +0 -605
- package/.agents/SCALE_OUT.md +0 -109
- package/.agents/SECRETS.md +0 -117
- package/.agents/SERVICES.md +0 -341
- package/.agents/SHUTDOWN.md +0 -74
- package/.agents/STREAMING.md +0 -108
- package/.agents/WORKFLOW.md +0 -27
- package/.agents/internal/DOCUMENTATION_REVIEW.md +0 -485
- package/.agents/internal/TECHNICAL_REVIEW.md +0 -428
- package/.agents/skills/webspresso-admin-and-plugins/SKILL.md +0 -122
- package/.agents/skills/webspresso-framework/SKILL.md +0 -89
- package/.agents/skills/webspresso-orm-and-database/SKILL.md +0 -127
- package/.agents/skills/webspresso-routing-and-api/SKILL.md +0 -130
- package/.agents/skills/webspresso-services/SKILL.md +0 -134
- package/.cursorrules +0 -14
- package/AGENTS.md +0 -203
- package/CLAUDE.md +0 -54
- package/core/kernel/run-demo.js +0 -58
- package/plugins/admin-panel/styles.js +0 -9
- package/plugins/data-exchange/export-xlsx.js +0 -119
- package/src/client-runtime/bootstrap-alpine-swup.js +0 -34
package/.agents/CACHE.md
DELETED
|
@@ -1,148 +0,0 @@
|
|
|
1
|
-
# High-Performance In-Memory LRU & Tagged Cache Engine (`core/cache`)
|
|
2
|
-
|
|
3
|
-
Webspresso includes a zero-dependency, memory-bounded, leak-free in-memory cache engine featuring O(1) Least-Recently-Used (LRU) eviction, byte budget constraints (`maxBytes` / `maxMemoryMb`), TTL expiration, stampede protection (thundering herd prevention), and O(1) bidirectional tag-based invalidation.
|
|
4
|
-
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
## 🎯 Key Capabilities & Design Guarantees
|
|
8
|
-
|
|
9
|
-
1. **True O(1) LRU Eviction**: Built on V8's native insertion-order Map mechanics with zero extra memory allocation for linked-list node wrappers.
|
|
10
|
-
2. **Dual Capacity Boundaries**:
|
|
11
|
-
- **`maxEntries`**: Restricts the maximum number of items stored.
|
|
12
|
-
- **`maxBytes` / `maxMemoryMb`**: Enforces strict memory budgets using `approximateByteSize` to prevent process Out-Of-Memory (OOM) crashes under heavy or large payload loads.
|
|
13
|
-
- **Zero-Overhead Fast Path**: When `maxBytes` is 0 (unlimited byte budget, count-only LRU), deep recursive byte size calculations are automatically bypassed (`0` byte allocation overhead), maximizing throughput on large query and JSON payloads unless explicitly requested via `trackBytes: true`.
|
|
14
|
-
3. **Symmetrical Tag Cleanup (Zero Leaks)**: When an item is evicted via LRU, expired via TTL, or deleted, all associated tag index sets are automatically pruned. Empty tag sets are deleted immediately, preventing the classic "dangling Set memory leak".
|
|
15
|
-
4. **Stampede / Thundering Herd Protection**: `getOrSet(key, asyncFactory)` coalesces concurrent requests for the same missing key, invoking the expensive calculation or DB query exactly once.
|
|
16
|
-
5. **Universal Integration**:
|
|
17
|
-
- **ORM Query Cache**: Powers `core/orm/cache/memory-provider.js` with true LRU and memory budgets.
|
|
18
|
-
- **Zod Schema Cache**: Powers `core/schema-cache.js` with bounded 2,000 schemas capacity.
|
|
19
|
-
- **Application & Context**: Automatically mounted on `app.cache`, `req.cache`, and `req.context.cache` unless `cache: false` is configured.
|
|
20
|
-
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
## 🚀 Quick Usage
|
|
24
|
-
|
|
25
|
-
### 1. Standalone `LruCache`
|
|
26
|
-
```javascript
|
|
27
|
-
const { createLruCache } = require('webspresso');
|
|
28
|
-
|
|
29
|
-
const cache = createLruCache({
|
|
30
|
-
maxEntries: 1000,
|
|
31
|
-
maxMemoryMb: 50, // 50 MB byte budget
|
|
32
|
-
defaultTtl: '15m', // 15 minutes default TTL
|
|
33
|
-
clone: false, // Set true if cached objects must not be mutated
|
|
34
|
-
});
|
|
35
|
-
|
|
36
|
-
cache.set('user:42', { name: 'Alice', role: 'admin' });
|
|
37
|
-
|
|
38
|
-
const user = cache.get('user:42'); // Refreshes LRU position
|
|
39
|
-
const peekUser = cache.peek('user:42'); // Reads without refreshing LRU position
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
### 2. Tagged Invalidation (`TaggedLruCache`)
|
|
43
|
-
```javascript
|
|
44
|
-
const { createTaggedLruCache } = require('webspresso');
|
|
45
|
-
|
|
46
|
-
const cache = createTaggedLruCache({
|
|
47
|
-
maxEntries: 5000,
|
|
48
|
-
maxMemoryMb: 100,
|
|
49
|
-
});
|
|
50
|
-
|
|
51
|
-
// Tag items by model and primary key
|
|
52
|
-
cache.set('query:users:active', usersList, { tags: ['model:User', 'q:active'] });
|
|
53
|
-
cache.set('user:1:profile', userProfile, { tags: ['model:User', 'pk:1'] });
|
|
54
|
-
|
|
55
|
-
// Invalidate single primary key
|
|
56
|
-
cache.invalidateTag('pk:1');
|
|
57
|
-
|
|
58
|
-
// Invalidate all queries related to the User model
|
|
59
|
-
cache.invalidateTags(['model:User']);
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
### 3. Stampede / Thundering Herd Protection (`getOrSet`)
|
|
63
|
-
```javascript
|
|
64
|
-
// 50 concurrent requests for 'expensive:report' will execute the factory only once:
|
|
65
|
-
const report = await cache.getOrSet('expensive:report', async (key) => {
|
|
66
|
-
return await generateHeavyReport();
|
|
67
|
-
}, { ttl: '1h' });
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
---
|
|
71
|
-
|
|
72
|
-
## ⚙️ Application Configuration (`createApp`)
|
|
73
|
-
|
|
74
|
-
Configure the process-wide cache directly when bootstrapping Webspresso:
|
|
75
|
-
|
|
76
|
-
```javascript
|
|
77
|
-
const { createApp } = require('webspresso');
|
|
78
|
-
|
|
79
|
-
const app = createApp({
|
|
80
|
-
pagesDir: './pages',
|
|
81
|
-
cache: {
|
|
82
|
-
maxEntries: 5000,
|
|
83
|
-
maxMemoryMb: 64, // 64 MB budget
|
|
84
|
-
defaultTtl: '10m',
|
|
85
|
-
},
|
|
86
|
-
});
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
To disable the app cache completely:
|
|
90
|
-
```javascript
|
|
91
|
-
const app = createApp({
|
|
92
|
-
pagesDir: './pages',
|
|
93
|
-
cache: false,
|
|
94
|
-
});
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
---
|
|
98
|
-
|
|
99
|
-
## 🌐 Context & Route Usage
|
|
100
|
-
|
|
101
|
-
Inside page loaders, services, or API route handlers:
|
|
102
|
-
|
|
103
|
-
```javascript
|
|
104
|
-
// In API routes (pages/api/stats.get.js)
|
|
105
|
-
module.exports = defineApi({
|
|
106
|
-
handler: async (req, res) => {
|
|
107
|
-
const stats = await req.cache.getOrSet('site:stats', async () => {
|
|
108
|
-
return await req.db.getRepository('Order').getSummaryStats();
|
|
109
|
-
}, { ttl: '5m', tags: ['stats', 'model:Order'] });
|
|
110
|
-
|
|
111
|
-
return res.json(stats);
|
|
112
|
-
},
|
|
113
|
-
});
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
```javascript
|
|
117
|
-
// From any background job or script using app-context
|
|
118
|
-
const { getCache } = require('webspresso');
|
|
119
|
-
|
|
120
|
-
const cache = getCache();
|
|
121
|
-
if (cache) {
|
|
122
|
-
cache.invalidateTag('stats');
|
|
123
|
-
}
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
---
|
|
127
|
-
|
|
128
|
-
## 📊 Telemetry & Observability Metrics
|
|
129
|
-
|
|
130
|
-
Access real-time cache performance and memory metrics:
|
|
131
|
-
|
|
132
|
-
```javascript
|
|
133
|
-
const stats = app.cache.getStats();
|
|
134
|
-
console.log(stats);
|
|
135
|
-
// {
|
|
136
|
-
// entries: 42,
|
|
137
|
-
// tags: 5,
|
|
138
|
-
// currentBytes: 124850,
|
|
139
|
-
// maxBytes: 67108864,
|
|
140
|
-
// maxEntries: 5000,
|
|
141
|
-
// hits: 1540,
|
|
142
|
-
// misses: 23,
|
|
143
|
-
// hitRate: 0.985,
|
|
144
|
-
// sets: 65,
|
|
145
|
-
// evictions: 0,
|
|
146
|
-
// expirations: 12
|
|
147
|
-
// }
|
|
148
|
-
```
|