toiljs 0.0.103 → 0.0.104
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/CHANGELOG.md +5 -0
- package/build/compiler/.tsbuildinfo +1 -1
- package/build/compiler/toil-docs.generated.js +8 -8
- package/docs/introduction/README.md +35 -21
- package/docs/introduction/design-principles.md +34 -32
- package/docs/introduction/distributed.md +37 -29
- package/docs/introduction/how-it-works.md +32 -32
- package/docs/introduction/hyperscale.md +23 -23
- package/docs/introduction/modern-stack.md +19 -15
- package/docs/introduction/vs-other-frameworks.md +17 -17
- package/docs/introduction/why-toil.md +30 -30
- package/package.json +1 -1
- package/src/compiler/toil-docs.generated.ts +8 -8
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
# The modern stack: what toil gives you that others do not
|
|
2
2
|
|
|
3
|
-
Most frameworks give you a way to write code
|
|
3
|
+
Most frameworks give you a way to write code, then send you shopping. A database, an auth provider, email, a rate limiter, analytics, a realtime service, a job runner. Each one is its own account, its own bill, and its own SDK, and you keep them all in sync.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
toil owns those parts instead. They ship in the framework, they are toil's own code, and they run from the first line with no configuration. Nothing third-party sits on your critical path.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
The good version is the default version. A solo builder gets the same baseline a funded team would rent from ten vendors, with nothing to assemble or babysit. This page is the full catalog. For how the edge and worldwide distribution work, see [How toil works](./how-it-works.md) and [How toil is distributed](./distributed.md).
|
|
8
|
+
|
|
9
|
+
## Built-in backend features
|
|
8
10
|
|
|
9
11
|
Your TypeScript backend declares what it needs with a decorator or a one-line config flag. toil provides the machinery.
|
|
10
12
|
|
|
@@ -24,7 +26,7 @@ Your TypeScript backend declares what it needs with a decorator or a one-line co
|
|
|
24
26
|
|
|
25
27
|
### The seven ToilDB families
|
|
26
28
|
|
|
27
|
-
One database, seven shapes
|
|
29
|
+
One database, seven shapes. Each family is tuned to its own access pattern instead of forced out of a single table model.
|
|
28
30
|
|
|
29
31
|
| Family | For |
|
|
30
32
|
| --- | --- |
|
|
@@ -36,7 +38,7 @@ One database, seven shapes, each tuned to its access pattern rather than bent ou
|
|
|
36
38
|
| [Capacity](../database/capacity.md) | Bounded resources and seat/slot allocation. |
|
|
37
39
|
| [View](../database/views.md) | Read models materialized by `@derive`. |
|
|
38
40
|
|
|
39
|
-
##
|
|
41
|
+
## Built-in frontend features
|
|
40
42
|
|
|
41
43
|
The React client is Vite-fast and typed end to end. The pieces that usually take a build config, a fetch layer, and an SEO plugin are already wired.
|
|
42
44
|
|
|
@@ -51,9 +53,9 @@ The React client is Vite-fast and typed end to end. The pieces that usually take
|
|
|
51
53
|
| [Page search](../frontend/search.md) | A static index of each route's title, description, keywords, and Open Graph, generated at build. | In-app search with no search vendor (see the caveat below). |
|
|
52
54
|
| [SHA-384 SRI](../concepts/security.md) | Subresource Integrity plus importmap integrity on every shipped script, preload, and stylesheet, across the whole module graph. | A tampered asset simply does not run, even if a CDN or cache hop is compromised. |
|
|
53
55
|
|
|
54
|
-
##
|
|
56
|
+
## toil versus a typical stack
|
|
55
57
|
|
|
56
|
-
Everything above is toil's own code on your critical path
|
|
58
|
+
Everything above is toil's own code on your critical path. You can inspect it, patch it, and secure it. The table below draws the difference.
|
|
57
59
|
|
|
58
60
|
| Capability | toil (built in, zero setup) | Typical stack (you assemble it) |
|
|
59
61
|
| --- | --- | --- |
|
|
@@ -65,17 +67,19 @@ Everything above is toil's own code on your critical path, not a black box you c
|
|
|
65
67
|
| Frontend integrity and SEO | Automatic SHA-384 SRI, Image/LQIP, metadata, page search | Plugins and services bolted on per concern |
|
|
66
68
|
| Critical-path ownership | The core is toil's own | A mix of vendors you cannot inspect or fix |
|
|
67
69
|
|
|
68
|
-
|
|
70
|
+
Owned means the core of a working app is toil's. It does not mean outside services are banned. You can still call a payment provider or any other API.
|
|
69
71
|
|
|
70
|
-
##
|
|
72
|
+
## Honest limits
|
|
71
73
|
|
|
72
|
-
toil grades itself on honesty
|
|
74
|
+
toil grades itself on honesty. Read these before you count on anything.
|
|
73
75
|
|
|
74
|
-
- **Distributed writes are built, live multi-cell is config-gated.** The home-region model and its core logic are real and tested
|
|
75
|
-
- **Analytics is a dev stub locally.** It is real on the edge
|
|
76
|
-
- **Auth secrets ship as dev placeholders.** The session HMAC, OPRF seed, and ML-KEM key are clearly
|
|
76
|
+
- **Distributed writes are built, live multi-cell is config-gated.** The home-region model and its core logic are real and tested. Live multi-region deployment (WAN routing, the ScyllaDB backing) is opt-in, not on by default. The local dev database is a single in-process store. toil is built to distribute writes worldwide. Not every app is running a live global write cluster today.
|
|
77
|
+
- **Analytics is a dev stub locally.** It is real on the edge. The local dev server returns sample data.
|
|
78
|
+
- **Auth secrets ship as dev placeholders.** The session HMAC, OPRF seed, and ML-KEM key are clearly insecure placeholders so `toiljs dev` just works. A real deployment must set its own. Per-tenant auto-generation at domain registration is the plan.
|
|
77
79
|
- **Page search indexes static metadata only.** Routes whose metadata comes from a dynamic `generateMetadata` are not in the index.
|
|
78
80
|
|
|
79
|
-
## Why
|
|
81
|
+
## Why these ship by default
|
|
82
|
+
|
|
83
|
+
None of this is an upgrade you unlock later. toil grades itself against [RSG](./design-principles.md), the Resilience and Scale Grade. Its one rule: your grade is your weakest axis, never the average. These built-in parts exist so no single axis quietly caps the whole.
|
|
80
84
|
|
|
81
|
-
|
|
85
|
+
The trades are real. ToilDB is not general SQL. The server language is a strict TypeScript subset. The catalog is younger than long-established platforms. Where those trades fit your project, the built-in stack earns its place. [Why toil](./why-toil.md) covers where it does not.
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
# toil versus other stacks
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
This page compares toil to the stacks you already use, axis by axis. Every tool below is good at what it was built for. The aim is to be concrete about what you gain and what you give up. toil is younger than all of them, and that shows in a few rows.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
toil trades a large, mature ecosystem for one owned framework. That framework distributes writes and ships fast, safe defaults for free. Whether the trade fits your project is the question this page answers.
|
|
6
6
|
|
|
7
|
-
## The comparison
|
|
7
|
+
## The comparison table
|
|
8
8
|
|
|
9
9
|
| Axis | A typical modern stack | toil |
|
|
10
10
|
| --- | --- | --- |
|
|
@@ -20,25 +20,25 @@ The short story: toil trades a large, mature ecosystem for one owned framework t
|
|
|
20
20
|
| Integration catalog | Large, mature, well documented | Smaller and younger |
|
|
21
21
|
| Single-region app | Dead simple, nothing to distribute | Distribution you may not need |
|
|
22
22
|
|
|
23
|
-
The top rows lean toil's way
|
|
23
|
+
The top rows lean toil's way. The bottom rows lean the incumbents' way. toil wins the structural axes: one owned stack, distributed writes, a multi-tenant sandbox, end-to-end types, and built-in modern auth. It concedes the ecosystem axes that maturity buys: SQL, the Node universe, and catalog size.
|
|
24
24
|
|
|
25
|
-
##
|
|
25
|
+
## How toil compares to each stack
|
|
26
26
|
|
|
27
|
-
**Next.js / Vercel.** Superb React DX and global edge reads. The ceiling is the write path
|
|
27
|
+
**Next.js / Vercel.** Superb React DX and global edge reads. The ceiling is the write path. Pages cache worldwide, but a write still resolves against one primary region. A comment, an order, a flash-sale click all crawl back to that box. Serverless cold starts add latency and per-invocation cost right when a spike hits. toil keeps a React-first client and moves the write to a home region near the data.
|
|
28
28
|
|
|
29
|
-
**Rails / Django.** Mature, productive, batteries included,
|
|
29
|
+
**Rails / Django.** Mature, productive, and batteries included, with a deep hiring pool. If one region suits you, this is a great and boring choice. The default shape is a single-region monolith with one primary that every write must reach. You can add replicas and standbys to scale, but distributed writes are not in the model.
|
|
30
30
|
|
|
31
|
-
**Serverless functions (Lambda, Cloud Functions).** Elastic, stateless compute that scales to zero.
|
|
31
|
+
**Serverless functions (Lambda, Cloud Functions).** Elastic, stateless compute that scales to zero. It still sits in front of a central database, so a write burst bottlenecks on that store. Each cold invocation bills and lags on its own.
|
|
32
32
|
|
|
33
|
-
**Edge runtimes (Workers, Deno Deploy).** The closest in spirit to toil's compute model: your code runs near users. The catch is
|
|
33
|
+
**Edge runtimes (Workers, Deno Deploy).** The closest in spirit to toil's compute model: your code runs near users. The catch is the database you attach. It is usually single-region, so edge compute becomes a faster front door to the same central write bottleneck.
|
|
34
34
|
|
|
35
|
-
Cloudflare Durable Objects and D1 are the closest mainstream analog to toil's idea, and credit is due
|
|
35
|
+
Cloudflare Durable Objects and D1 are the closest mainstream analog to toil's idea, and credit is due. A Durable Object gives one object a single-writer home that orders its writes, the same shape as ToilDB's per-key home. The difference is packaging. With the edge-runtime approach you assemble the pieces yourself: runtime, object or database product, auth, email, and realtime. toil ships distributed writes, the seven database families, auth, email, streaming, and background jobs as one owned stack. Which you prefer is a real trade-off.
|
|
36
36
|
|
|
37
37
|
**Backend-as-a-service (Supabase, Firebase).** The fastest thing to start with, and often the right call for a prototype. The convenience is a managed service on your critical path that you cannot inspect or patch, and writes still resolve against a primary.
|
|
38
38
|
|
|
39
|
-
##
|
|
39
|
+
## What incumbents do better
|
|
40
40
|
|
|
41
|
-
toil does not win every axis
|
|
41
|
+
toil does not win every axis. Some gaps are real today:
|
|
42
42
|
|
|
43
43
|
- **Mature ecosystems.** More tutorials, more answered questions, more hosting options, and more people who already know the tool.
|
|
44
44
|
- **SQL and joins.** If your data is relational and you live in ad-hoc queries and joins, a SQL database is the right tool. ToilDB is seven purpose-built families, not a relational engine (see the [database overview](../database/README.md)).
|
|
@@ -48,15 +48,15 @@ toil does not win every axis, and some gaps are real today. Be honest about them
|
|
|
48
48
|
|
|
49
49
|
None of these are permanent, and the right tool is the one that fits the job in front of you.
|
|
50
50
|
|
|
51
|
-
## toil
|
|
51
|
+
## The trade toil makes
|
|
52
52
|
|
|
53
|
-
Most stacks cap in
|
|
53
|
+
Most stacks cap in the same place. The write path is one box in one region, or the critical path leans on services you rent and cannot fix. toil refuses both. It owns the whole stack and distributes the writes, so the structural caps are designed out. The limits left are the ones your own code sets.
|
|
54
54
|
|
|
55
|
-
|
|
55
|
+
One caveat, to keep the mechanism honest. The home-region model and its core logic are real and tested. Live multi-region deployment is configuration-gated rather than on by default: the WAN routing and the ScyllaDB backing are opt-in, and the local dev database is a single in-process store. Compute works the same way. Your code runs at the edge on every request, while the regional, continental, and global-daemon tiers are opt-in. So the honest claim is that toil is built to distribute writes worldwide and the mechanism is real. It does not mean every app is already running a live global write cluster today.
|
|
56
56
|
|
|
57
|
-
Whether
|
|
57
|
+
Whether the trade fits your project is the checklist in [Why toil](./why-toil.md).
|
|
58
58
|
|
|
59
|
-
## Related
|
|
59
|
+
## Related pages
|
|
60
60
|
|
|
61
61
|
- [Why toil? Who is it for?](./why-toil.md): the problem toil solves and the honest cases where you should not use it.
|
|
62
62
|
- [The modern stack](./modern-stack.md): the full, verified catalog of what is built in.
|
|
@@ -1,44 +1,44 @@
|
|
|
1
1
|
# Why toil? Who is it for?
|
|
2
2
|
|
|
3
|
-
toil is a full-stack framework
|
|
3
|
+
toil is a full-stack framework. You write a React frontend and a TypeScript backend in one project, and toil runs both, plus a database, close to every user worldwide.
|
|
4
4
|
|
|
5
|
-
The thesis
|
|
5
|
+
The thesis is simple. toil is the modern full-stack tooling a developer actually wants: AAA-grade from the first line, and built to scale to the whole planet. Even a simple pizza site gets top-tier infrastructure with zero setup. Distributed writes are one pillar of that. The stack that just works is the core.
|
|
6
6
|
|
|
7
|
-
## The problem with
|
|
7
|
+
## The problem with modern stacks
|
|
8
8
|
|
|
9
|
-
Shipping a good app today means fighting your own infrastructure.
|
|
9
|
+
Shipping a good app today means fighting your own infrastructure. It fights back in five ways.
|
|
10
10
|
|
|
11
|
-
**Reads go global, writes go to one region.** Your pages load fast from caches worldwide
|
|
11
|
+
**Reads go global, writes go to one region.** Your pages load fast from caches worldwide. A write does not. A comment, a like, or an order has to crawl back to a single database in a single region. A user in Sydney writing to Virginia pays for the whole round trip. That one region is also a single point of failure for everyone.
|
|
12
12
|
|
|
13
|
-
**You
|
|
13
|
+
**You become a systems integrator by accident.** A production stack is a dozen rented services stitched together: a frontend host, serverless functions, a managed database, auth, email, a queue, a cache, analytics, realtime. Each has its own account, bill, SDK, and outage. Every one on your critical path is a black box you cannot inspect, patch, or secure. When it is slow, you are slow. When it is breached, part of you is breached.
|
|
14
14
|
|
|
15
|
-
**It runs on yesterday's tooling.** The typical stack sits on a decade of
|
|
15
|
+
**It runs on yesterday's tooling.** The typical stack sits on a decade of legacy: bundler configs, transpiler shims, CommonJS-versus-ESM interop, framework churn, and a `node_modules` folder heavier than the app itself. You fight the toolchain and chase version bumps instead of building. The web platform moved on. The stack did not.
|
|
16
16
|
|
|
17
|
-
**
|
|
17
|
+
**Every layer adds overhead.** Heavy runtimes, slow builds, serverless cold starts, oversized JavaScript in the browser, and a network hop between every service. Each layer adds latency and cost. The user feels it and you debug it.
|
|
18
18
|
|
|
19
|
-
**Fast and safe are opt-in, never
|
|
19
|
+
**Fast and safe are opt-in, never default.** Good performance and real security are things you assemble by hand: a CDN here, a cache there, careful data fetching, region tuning, hardened auth, current cryptography. Miss a piece and you are slow or exposed. The good version is always extra work, so most people ship the lesser one.
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
A solo builder and a funded startup hit the same wall. Top-tier infrastructure means assembling and babysitting a lot of parts, so most settle for less.
|
|
22
22
|
|
|
23
|
-
## What toil
|
|
23
|
+
## What toil delivers
|
|
24
24
|
|
|
25
|
-
Every design decision in toil serves one goal: AAA-grade infrastructure
|
|
25
|
+
Every design decision in toil serves one goal: AAA-grade infrastructure by default, not something you assemble by hand. One framework instead of ten rented vendors. Zero configuration. No distributed-systems or networking expertise required. It works out of the box, quantum-proof login included.
|
|
26
26
|
|
|
27
|
-
Four pillars.
|
|
27
|
+
Four pillars carry it.
|
|
28
28
|
|
|
29
|
-
###
|
|
29
|
+
### AAA-grade infrastructure by default
|
|
30
30
|
|
|
31
|
-
Top-tier infrastructure on day one, on the smallest project, with zero setup
|
|
31
|
+
Top-tier infrastructure on day one, on the smallest project, with zero setup. Your code runs at the edge near users worldwide. A global database is already there. Every shipped asset is tamper-proofed automatically with SHA-384 Subresource Integrity. Login is quantum-proof in about one line.
|
|
32
32
|
|
|
33
|
-
That login is real post-quantum cryptography. Your password is stretched into a signing key on your device and never reaches the server in a usable form
|
|
33
|
+
That login is real post-quantum cryptography. Your password is stretched into a signing key on your device and never reaches the server in a usable form. The handshake uses ML-DSA and ML-KEM, the NIST-standardized algorithms meant to survive a quantum computer. Most stacks bolt current crypto on by hand, if at all. Here it is the default.
|
|
34
34
|
|
|
35
|
-
A pizza site and a planet-scale app start from the same baseline.
|
|
35
|
+
A pizza site and a planet-scale app start from the same baseline. AAA-grade is the actual bar toil grades itself against. See [design principles](./design-principles.md).
|
|
36
36
|
|
|
37
|
-
###
|
|
37
|
+
### Everything built in, and owned
|
|
38
38
|
|
|
39
|
-
Auth, database, email, rate limiting, analytics, realtime streaming, and background jobs are all built in and
|
|
39
|
+
Auth, database, email, rate limiting, analytics, realtime streaming, and background jobs are all built in, and all toil's own. Nothing third-party sits on your critical path.
|
|
40
40
|
|
|
41
|
-
Because they are one system, the parts already fit. You are not gluing ten SDKs together and
|
|
41
|
+
Because they are one system, the parts already fit. You are not gluing ten SDKs together and hoping they agree. Full catalog: [The modern stack](./modern-stack.md).
|
|
42
42
|
|
|
43
43
|
```mermaid
|
|
44
44
|
flowchart TB
|
|
@@ -60,19 +60,19 @@ flowchart TB
|
|
|
60
60
|
end
|
|
61
61
|
```
|
|
62
62
|
|
|
63
|
-
Honest boundary:
|
|
63
|
+
Honest boundary: owned means the core of a working app is toil's, not that outside services are banned. Call a payment provider or another API and you still can.
|
|
64
64
|
|
|
65
|
-
###
|
|
65
|
+
### Modern tooling that just works
|
|
66
66
|
|
|
67
|
-
Built on today's web platform, not a decade of
|
|
67
|
+
Built on today's web platform, not a decade of legacy. TypeScript end to end, one repo, one deploy, wired by types. Change a field on the server and the frontend stops compiling until you fix it. The bug surfaces at your desk as a compile error, not in production.
|
|
68
68
|
|
|
69
|
-
The toolchain is set up for you: ESLint, Prettier
|
|
69
|
+
The toolchain is set up for you: ESLint, Prettier with a plugin for toil's decorators, an editor plugin, one CLI, and a `doctor` command that fixes common problems in place. The docs are LLM-friendly too, so an AI assistant reads your current conventions instead of guessing. More in [The modern stack](./modern-stack.md).
|
|
70
70
|
|
|
71
|
-
###
|
|
71
|
+
### Hyper-scale and distributed writes
|
|
72
72
|
|
|
73
|
-
Your backend compiles to a tiny sandboxed **WebAssembly** module
|
|
73
|
+
Your backend compiles to a tiny sandboxed **WebAssembly** module, a compact locked-down binary that runs at near-native speed. That is modern tech, not a heavyweight legacy runtime. One edge box safely runs many apps, so running near everyone stays affordable.
|
|
74
74
|
|
|
75
|
-
|
|
75
|
+
The database, **ToilDB**, distributes the writes, not just the reads. Every key has one **home** region that orders its writes, while data replicates outward for fast local reads. Distributing writes is the hard part almost nobody does. toil is built to do it worldwide, and the mechanism is real and tested. Live multi-region deployment is configuration-gated rather than on by default. Once it is on, a far read can lag a few milliseconds: the eventual-consistency trade. See [How toil works](./how-it-works.md) and [How toil is distributed](./distributed.md).
|
|
76
76
|
|
|
77
77
|
## Who it is for
|
|
78
78
|
|
|
@@ -81,16 +81,16 @@ And the database, **ToilDB**, distributes the *writes*, not just the reads: ever
|
|
|
81
81
|
- **Global apps:** logic and data near users on every continent.
|
|
82
82
|
- **Realtime apps:** chat, presence, and live cursors on built-in streaming, not a bolted-on vendor.
|
|
83
83
|
|
|
84
|
-
Same install for the smallest project and the largest. You grow into the scale
|
|
84
|
+
Same install for the smallest project and the largest. You grow into the scale. You do not rebuild to reach it.
|
|
85
85
|
|
|
86
86
|
## When not to use toil
|
|
87
87
|
|
|
88
88
|
- **You need SQL or heavy joins.** ToilDB is seven purpose-built families, not a general SQL engine. See the [database overview](../database/README.md).
|
|
89
|
-
- **You lean on the Node ecosystem.** The server is a strict TypeScript subset compiled to WebAssembly
|
|
89
|
+
- **You lean on the Node ecosystem.** The server is a strict TypeScript subset compiled to WebAssembly. No arbitrary npm packages, no Node APIs, built-in globals instead.
|
|
90
90
|
- **You are happy single-region and simple.** If one region already fits, toil's distribution is effort you do not need.
|
|
91
91
|
- **You need a big integration catalog today.** toil is younger, and that catalog is smaller.
|
|
92
92
|
|
|
93
|
-
None of these are permanent
|
|
93
|
+
None of these are permanent. The right tool is the one that fits the job in front of you.
|
|
94
94
|
|
|
95
95
|
## Related
|
|
96
96
|
|
package/package.json
CHANGED