You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+2-4Lines changed: 2 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -392,8 +392,6 @@ Cache capabilities include:
392
392
- Automatic invalidation after writes.
393
393
- Cache namespace, TTL, and distributed invalidation controls.
394
394
395
-
`withCache()` and `FunctionCache` remain exported for legacy compatibility, but non-database function caching is no longer promoted as a current monSQLize feature area.
396
-
397
395
## Advanced Capabilities
398
396
399
397
### Transactions
@@ -527,9 +525,9 @@ npm run verify:full
527
525
npm run release:preflight
528
526
```
529
527
530
-
Release preflight runs linting, type checks, size guards, runtime checks, compatibility checks, refactor guards, production dependency audit, the default test suite, and `npm pack --dry-run`.
528
+
The package self-check command runs linting, type checks, size guards, runtime checks, compatibility checks, refactor guards, production dependency audit, the default test suite, and `npm pack --dry-run`.
531
529
532
-
`npm run release:publish` runs the preflight gate once and then calls `npm publish --ignore-scripts` so the final publish step does not repeat the full lifecycle gate. Raw `npm publish` is still guarded by `prepublishOnly`.
530
+
`npm run release:publish` runs the package self-check once and then calls `npm publish --ignore-scripts` so the final publish step does not repeat the full lifecycle check. Raw `npm publish` is still guarded by `prepublishOnly`.
|[Find one document](findOne.md)|`findOne()`| Query one document |
38
-
|[Find one by id helper](find-one-by-id.md)|`findOneById()`| Optional reference helper for `_id` lookup; regular `findOne({ _id })` also supports ObjectId auto conversion |
39
-
|[Find by ids helper](find-by-ids.md)|`findByIds()`| Optional reference helper for multiple `_id` values; regular `find({ _id: { $in } })` also supports ObjectId auto conversion |
Copy file name to clipboardExpand all lines: docs/en/cache.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@
4
4
5
5
monSQLize provides database query caching for collection reads, optional local/remote cache composition, manual invalidation and statistics. Cache invalidation is designed to keep read caches fresh enough for common application workloads, but it is not an atomic commit step with MongoDB writes.
6
6
7
-
> ⚠️ If you are migrating public cache compatibility exports, read the [`cache-hub` direct-call migration guide](./cache-hub-migration.md) first. This page covers monSQLize database query cache and multi-layer cache access; `withCache()` / `FunctionCache` are legacy compatibility exports and are outside the current non-database cache path.
7
+
This page covers the current database-runtime cache path: query result cache, bookmark cache, Redis-backed remote cache, distributed invalidation, and cache statistics.
| pool |`pools` / `pool()` / `ConnectionPoolManager`| Declare `pools: PoolConfig[]` in the constructor, route with `pool()`, and use the low-level manager for advanced inspection or manual management |
27
28
| sync |`startSync()` / `stopSync()` / `getSyncStats()`| Supports Change Stream sync start, stop, and status inspection |
`withCache()` and `FunctionCache` remain exported for legacy compatibility, but they are not recommended as current monSQLize capability entry points for new non-database caching usage.
31
-
32
31
## 1. Model
33
32
34
33
Available entries:
35
34
36
35
-`Model.define/get/list/undefine/redefine`
37
36
-`msq.model()`
38
37
- relations / virtuals / populate
39
-
-`findOneById()` / `findByIds()`/`findAndCount()`
38
+
-common model queries such as `findOne()`and`findAndCount()`
> Goal: Give subsequent maintainers a structural diagram of "from entry to capability layer" to avoid continuing to pile logic back to `runtime-core.ts`.
3
+
monSQLize is a database-native runtime layer. It coordinates MongoDB access, model validation, cache, transactions, pools, sync, and observability, but it does not turn those capabilities into one global strict-consistency system.
4
4
5
-
## Module layering
5
+
Use this page to decide which entry point to use and where application-level guarantees are still required.
monSQLize provides runtime coordination helpers, not a global strict-consistency kernel. Current guarantees are:
@@ -40,50 +40,26 @@ monSQLize provides runtime coordination helpers, not a global strict-consistency
40
40
41
41
Use application/framework-level coordination, explicit `DistributedCacheLockManager` business locks, idempotency keys, fencing tokens, durable outbox/journals, or cache bypassing when a flow requires cross-instance strict consistency.
42
42
43
+
## Choosing the right entry point
43
44
44
-
## `runtime-core.ts`
45
-
46
-
Only responsible for:
47
-
48
-
- runtime main class public API
49
-
- Ability assembly
50
-
- Connect / close / collection / db / model and other entry delegates
| Multi-pool routing | Constructor `pools: PoolConfig[]`, then `msq.pool()`|
52
+
| Transactions |`startSession()` and `withTransaction()`|
53
+
| Change Stream fanout |`startSync()`, `stopSync()`, and `getSyncStats()`|
54
+
| Strict business locks |`DistributedCacheLockManager` with an application idempotency/fencing design |
74
55
75
-
## Current hot spot governance results
56
+
## When to add application-level guarantees
76
57
77
-
| Hot Topics | Current Strategies |
78
-
|------|----------|
79
-
|`slow-query-log`| Split into config/queue/records/storage/manager |
80
-
|`writes`| Split into utils/basic/batch |
81
-
|`expression`| The compiler has been separated, and only the public API and traversal remain at the entrance |
82
-
|`collection-accessor`| The writing path has been moved to the helper, and the main file has returned façade |
83
-
|`ModelInstance`| mutation orchestration has moved out of the master file |
58
+
Add explicit application guarantees when a workflow requires all of the following at the same time:
84
59
85
-
## Subsequent maintenance rules
60
+
1. Database write success and cache visibility must be atomic.
61
+
2. Sync targets cannot tolerate replay.
62
+
3. A lock must protect multiple Node.js processes or multiple regions.
63
+
4. A batch operation must behave exactly like a sequence of per-document business operations.
86
64
87
-
1. New capabilities are given priority to enter `capabilities/` or `adapters/`, do not change `runtime-core.ts` first.
88
-
2. When compat-only logic is involved, `runtime-compat-accessors.ts` is entered first.
89
-
3. After hotspot reconstruction, at least add `test:refactor-guard` + corresponding capability layer regression.
65
+
For those paths, combine monSQLize with durable outbox records, idempotency keys, application-level retries, or cache bypassing for the critical read path.
0 commit comments