@zerotal/arch 1.7.4 → 1.8.0

package/docs/broadcasting/client.md

@@ -59,7 +59,7 @@ rules and signs the result with the app's `APP_KEY`, and the client echoes the s
 or other headers via `auth.headers`, or set `authEndpoint: false` to skip the fetch and rely on
 connection-level authorization instead:
 
-```ts
+```ts fragment
 // in your client code
 const socket = new Socket({
   auth: { headers: { "X-CSRF-TOKEN": csrf } }, // sent on POST /broadcasting/auth
@@ -76,7 +76,7 @@ client.
 The server is also Pusher-protocol compatible, so the reference
 [pusher-js](https://github.com/pusher/pusher-js) client works unchanged:
 
-```ts
+```ts fragment
 // in your client code
 import Pusher from "pusher-js";
 

package/docs/broadcasting/events.md

@@ -7,7 +7,7 @@ description: Write a broadcast event, dispatch it, and broadcast model changes a
 
 You only have to implement `broadcastOn()`; the rest default sensibly.
 
-```ts
+```ts fragment
 // app/events/OrderShipmentStatusUpdated.ts
 import { BroadcastingEvent, privateChannel } from "@zerotal/broadcasting";
 import type { Order } from "../models/Order.ts";
@@ -48,7 +48,7 @@ export class OrderShipmentStatusUpdated extends BroadcastingEvent {
 
 Three ways to broadcast, in order of ergonomics:
 
-```ts
+```ts fragment
 // in a controller
 import { broadcast, Broadcast } from "@zerotal/broadcasting";
 
@@ -75,7 +75,7 @@ several statements; otherwise treat `broadcast(...)` as the whole call.
 
 A broadcastable event emitted on the [event bus](/docs/events) is broadcast automatically:
 
-```ts
+```ts fragment
 // in a controller
 import { Events } from "zerotal";
 
@@ -84,7 +84,7 @@ Events.emit(new OrderShipmentStatusUpdated(order)); // runs listeners AND broadc
 
 Broadcast to multiple channels by returning an array from `broadcastOn()`:
 
-```ts
+```ts fragment
 // in an event's broadcastOn()
 broadcastOn() {
   return [privateChannel(`orders.${this.order.id}`), privateChannel(`users.${this.order.userId}`)];
@@ -95,7 +95,7 @@ broadcastOn() {
 
 When a full event class is overkill, broadcast inline:
 
-```ts
+```ts fragment
 // in a controller
 Broadcast.on(`orders.${order.id}`).as("OrderPlaced").with(order).toOthers().send();
 Broadcast.private(`orders.${order.id}`).as("OrderPlaced").with({ id: order.id }).send();
@@ -110,7 +110,7 @@ Broadcast.to("posts", "PostViewed", { id: post.id, viewedAt: Date.now() });
 Get the members currently subscribed to a presence channel (real driver only —
 returns `[]` under the fake/null driver):
 
-```ts
+```ts fragment
 // in a controller
 const members = Broadcast.getMembers("presence-chat.room1");
 // → [{ id, info }, …]
@@ -122,7 +122,7 @@ Broadcast a model's lifecycle changes by mapping them to a `BroadcastingEvent` t
 `dispatchesEvents`. When the model fires the event on the [event bus](/docs/events), it is
 broadcast automatically (see [dispatching](#dispatching-events)) — no manual broadcast call.
 
-```ts
+```ts fragment
 // app/events/PostCreated.ts
 import { BroadcastingEvent, privateChannel } from "@zerotal/broadcasting";
 import type { Post } from "../models/Post.ts";
@@ -140,7 +140,7 @@ export class PostCreated extends BroadcastingEvent {
 }
 ```
 
-```ts
+```ts fragment
 // app/models/Post.ts
 @table("posts")
 export class Post extends Model {
@@ -164,7 +164,6 @@ import { broadcastsModelEvents, privateChannel } from "@zerotal/broadcasting";
 
 @table("orders")
 export class Order extends Model {
-  @column() id!: number;
   @column() status!: string;
 }
 
@@ -179,7 +178,7 @@ broadcastsModelEvents(Order, {
 The wire event name defaults to `${ModelName}${Event}` (e.g. `OrderUpdated`) and the payload to
 `{ order }` (the model under its camel-cased name). On the client:
 
-```ts
+```ts fragment
 // in your client code
 Socket.private(`orders.${id}`).listen("OrderUpdated", (e) => render(e.order));
 ```

package/docs/broadcasting/index.md

@@ -125,7 +125,7 @@ import {
 Extend `BroadcastingEvent`, implement `broadcastOn()`, and dispatch — every subscribed client on
 that channel receives the payload:
 
-```ts
+```ts fragment
 // app/events/OrderShipmentStatusUpdated.ts
 import { BroadcastingEvent, privateChannel } from "@zerotal/broadcasting";
 import type { Order } from "../models/Order.ts";

package/docs/broadcasting/testing.md

@@ -11,7 +11,7 @@ live manager for an in-memory recorder, so the code under test broadcasts exactl
 as it normally would and the test inspects what came out — no Redis, no Pusher
 credentials, and no waiting on a socket.
 
-```ts
+```ts fragment
 // in a test
 import { Broadcast } from "@zerotal/broadcasting";
 
@@ -31,7 +31,7 @@ Broadcast.resetFake();
 `afterEach` — otherwise the first test to fake broadcasting silently mutes every
 test that follows it.
 
-```ts
+```ts fragment
 afterEach(() => Broadcast.resetFake());
 ```
 
@@ -76,7 +76,7 @@ Proving a broadcast did _not_ happen is often the more valuable test, because a
 stray broadcast reaches real users. Both negative assertions are worth reaching
 for:
 
-```ts
+```ts fragment
 it("does not broadcast when validation fails", async () => {
   const fake = Broadcast.fake();
 
@@ -102,7 +102,7 @@ no special handling — save the model and assert. The event name is whatever
 `broadcastAs()` returns and the payload whatever `broadcastWith()` builds, so
 asserting on both is what pins that mapping down:
 
-```ts
+```ts fragment
 const fake = Broadcast.fake();
 
 await Post.create({ title: "Hello" });
@@ -117,7 +117,7 @@ its socket id along. The fake records the broadcast either way, so a test that o
 asserts the event fired will pass whether or not `toOthers()` was used. To pin that
 behaviour down, read the recorded entries directly:
 
-```ts
+```ts fragment
 const [entry] = fake.recorded();
 expect(entry.event).toBe("PostUpdated");
 ```

package/docs/cache.md

@@ -45,7 +45,9 @@ import { CacheConfig } from "@zerotal/cache";
 import { env } from "zerotal";
 
 export default CacheConfig({
-  driver: env("CACHE_DRIVER", "sqlite"), // 'sqlite' | 'redis' | 'memory'
+  // One of 'sqlite' | 'redis' | 'memory', written literally: the field is that
+  // union and `env()` returns a plain string.
+  driver: "sqlite",
   prefix: env("CACHE_PREFIX", "zerotal:"), // prepended to every key
   ttl: env("CACHE_TTL", 3600), // default TTL in seconds (1 hour)
 
@@ -66,7 +68,7 @@ export default CacheConfig({
 
 ## Basic operations
 
-```ts
+```ts fragment
 // in a controller or service
 import { Cache } from "@zerotal/cache";
 
@@ -93,13 +95,13 @@ await Cache.flush();
 
 `remember()` checks the cache and, on a miss, calls the factory, stores the result, and returns it. Under high concurrency, multiple callers for the same key coalesce — the factory runs exactly once:
 
-```ts
+```ts fragment
 function remember<T>(key: string, ttl: number, fn: () => Promise<T> | T): Promise<T>;
 ```
 
 > **Tip** — Reach for `remember()` instead of a manual `get`/`set` pair. It avoids the cache stampede where many requests miss at once and all hit the database.
 
-```ts
+```ts fragment
 // in a controller
 import { Cache } from "@zerotal/cache";
 import { Post } from "../app/models/Post.ts";
@@ -130,7 +132,7 @@ const stats = await Cache.remember(`user:${userId}:stats`, 60, async () => {
 
 Group related keys under named tags so you can invalidate them together. `Cache.tags()` returns a `TaggedCache` whose keys all share a tag prefix — useful when several cache entries depend on the same underlying data:
 
-```ts
+```ts fragment
 // in a controller
 import { Cache } from "@zerotal/cache";
 
@@ -156,7 +158,7 @@ await Cache.tags([`user:${userId}`]).flush();
 
 ### Tag-based invalidation in model hooks
 
-```ts
+```ts fragment
 // app/models/Post.ts — inside a lifecycle hook or observer
 async afterCreate(post: Post) {
   await Cache.tags(["posts"]).flush();
@@ -171,7 +173,7 @@ async afterUpdate(post: Post) {
 
 There is no multi-get primitive — batch with `Promise.all` to cut round-trips to the backend:
 
-```ts
+```ts fragment
 // in a controller
 import { Cache } from "@zerotal/cache";
 
@@ -211,7 +213,7 @@ await Promise.all([
 
 The `Cache` facade always uses the configured driver. To use a different driver for one use case, construct a `CacheManager` directly:
 
-```ts
+```ts fragment
 // in a service
 import { CacheManager, MemoryDriver } from "@zerotal/cache";
 
@@ -220,7 +222,7 @@ const local = new CacheManager(new MemoryDriver(), "req:", 30);
 await local.set("computed-total", total);
 ```
 
-```ts
+```ts fragment
 new CacheManager(driver: CacheDriver, prefix?: string, defaultTtl?: number)
 ```
 
@@ -230,7 +232,7 @@ new CacheManager(driver: CacheDriver, prefix?: string, defaultTtl?: number)
 
 `with()` needs a `CacheManager` instance — resolve the framework's bound manager from the container with `app.container.makeSync("cache")`:
 
-```ts
+```ts fragment
 // routes/api.ts
 import { IdempotencyMiddleware, CacheManager } from "@zerotal/cache";
 
@@ -283,7 +285,7 @@ A replayed response includes `Idempotency-Replay: true` so clients can distingui
 
 Pre-populate the cache at boot so the first real request is always fast. Call from a provider's `onStarted()`, which runs after the application has finished booting:
 
-```ts
+```ts fragment
 // bootstrap/providers/AppServiceProvider.ts
 import { ServiceProvider } from "zerotal";
 import { Cache } from "@zerotal/cache";
@@ -305,7 +307,7 @@ Use the `memory` driver in tests for speed and isolation — it never persists b
 
 To swap the cache for a single suite, rebind the `cache` singleton on the container before resolving the facade, then flush between tests to avoid bleed:
 
-```ts
+```ts fragment
 // in test setup
 import { Application } from "zerotal";
 import { Cache, CacheManager, MemoryDriver } from "@zerotal/cache";
@@ -354,7 +356,7 @@ Cache errors extend `CacheError`, which extends the framework's `ZerotalError`.
 | `CacheSerializationError`   | `E_CACHE_SERIALIZATION`   | A value cannot be serialised for storage.                    |
 | `CacheDeserializationError` | `E_CACHE_DESERIALIZATION` | A stored value cannot be read back — usually a shape change. |
 
-```typescript
+```typescript fragment
 // in a service
 import { CacheDeserializationError } from "@zerotal/cache";
 

package/docs/carbon.md

@@ -28,7 +28,7 @@ import { Carbon, CarbonInterval } from "zerotal/carbon";
 The constructor accepts a string, a millisecond timestamp, a native `Date`, a
 Temporal type, or another Carbon. A second argument sets the timezone.
 
-```typescript
+```typescript fragment
 // anywhere in your app
 // Current date and time (system timezone)
 const now = new Carbon();
@@ -60,7 +60,7 @@ const d8 = new Carbon(Temporal.Now.instant());
 Named static factories cover the common boundary cases (all accept an optional
 timezone string):
 
-```typescript
+```typescript fragment
 // anywhere in your app
 Carbon.today(); // today at 00:00:00
 Carbon.tomorrow(); // tomorrow at 00:00:00
@@ -79,7 +79,7 @@ Carbon.create(input); // same as new Carbon(input)
 Every modifier returns a **new** Carbon. Chain freely — the base instance never
 changes.
 
-```typescript
+```typescript fragment
 // anywhere in your app
 const base = new Carbon("2026-01-15");
 const nextWeek = base.addDays(7);
@@ -95,7 +95,7 @@ deadline.format("YYYY-MM-DD"); // '2026-02-15'
 A Carbon carries its timezone; converting produces a new instance pointing at the
 same instant.
 
-```typescript
+```typescript fragment
 // anywhere in your app
 // Read the timezone of an instance
 const tz = Carbon.now("Asia/Tokyo").timezone; // 'Asia/Tokyo'
@@ -117,7 +117,7 @@ Reading a Carbon never changes it. Calendar fields are plain properties, so they
 carry no parentheses; the three counts that depend on the surrounding calendar are
 methods, because they compute an answer rather than expose a stored field.
 
-```typescript
+```typescript fragment
 // anywhere in your app
 const d = new Carbon("2026-06-15 09:30:45.123");
 
@@ -162,7 +162,7 @@ out and comparing them by hand.
 
 ### Predicates
 
-```typescript
+```typescript fragment
 // anywhere in your app
 d.isToday();
 d.isTomorrow();
@@ -221,7 +221,7 @@ ranges, where inclusive bounds would place a boundary value in both buckets.
 
 All arithmetic returns a new Carbon.
 
-```typescript
+```typescript fragment
 // anywhere in your app
 d.addNanoseconds(1)       d.subtractNanoseconds(1)
 d.addMicroseconds(1)      d.subtractMicroseconds(1)
@@ -245,7 +245,7 @@ either direction from a computed value without branching.
 
 To add a [CarbonInterval](#carboninterval), use `add()` / `subtract()`:
 
-```typescript
+```typescript fragment
 // anywhere in your app
 const interval = CarbonInterval.days(3).andHours(6);
 
@@ -259,7 +259,7 @@ Months and years are calendar units rather than fixed spans, so adding one lands
 on the same day number in the target month — and clamps when that day does not
 exist there:
 
-```typescript
+```typescript fragment
 new Carbon("2026-01-31").addMonths(1); // → 2026-02-28
 new Carbon("2024-02-29").addYears(1); // → 2025-02-28
 ```
@@ -267,7 +267,7 @@ new Carbon("2024-02-29").addYears(1); // → 2025-02-28
 Clamping discards information, which makes month arithmetic asymmetric. Adding a
 month and taking it back does not always return the original date:
 
-```typescript
+```typescript fragment
 new Carbon("2026-01-31").addMonths(1).subtractMonths(1); // → 2026-01-28
 ```
 
@@ -285,7 +285,7 @@ and always reverse cleanly.
 
 Snap to the start or end of a time period — all return a new Carbon.
 
-```typescript
+```typescript fragment
 // anywhere in your app
 d.startOfMinute(); // :00.000
 d.endOfMinute(); // :59.999999999
@@ -325,7 +325,7 @@ day without also catching midnight the next morning.
 
 The `with` prefix signals a new instance is returned.
 
-```typescript
+```typescript fragment
 // anywhere in your app
 d.withYear(2030);
 d.withMonth(12); // 1-indexed
@@ -351,7 +351,7 @@ of setters.
 All numeric diff methods return a **number** — positive when `this` is after
 `other`.
 
-```typescript
+```typescript fragment
 // anywhere in your app
 const a = new Carbon("2026-01-01");
 const b = new Carbon("2026-06-15");
@@ -373,7 +373,7 @@ b.diffInYears(a); // ~0.42
 For a calendar-aware breakdown use `diffAsCarbonInterval`, which delegates to
 Temporal's `until()`:
 
-```typescript
+```typescript fragment
 // anywhere in your app
 const age = birthday.diffAsCarbonInterval(Carbon.now(), "year");
 // → CarbonInterval { years: 28, months: 3, days: 12, … }
@@ -394,7 +394,7 @@ The `largestUnit` defaults to `'day'` and accepts `'year'`, `'month'`, `'week'`,
 Returns a human-readable relative string using `Intl.RelativeTimeFormat`. With no
 argument it compares against now.
 
-```typescript
+```typescript fragment
 // anywhere in your app
 const posted = new Carbon("2026-06-08");
 posted.diffForHumans(); // '1 week ago'
@@ -407,7 +407,7 @@ a.diffForHumans(b); // '5 months ago'
 
 Pass an options object to tune the output:
 
-```typescript
+```typescript fragment
 // anywhere in your app
 a.diffForHumans(b, {
   parts: 2, // include up to 2 units → '5 months, 1 week ago'
@@ -419,7 +419,7 @@ a.diffForHumans(b, {
 });
 ```
 
-```typescript
+```typescript fragment
 // anywhere in your app
 const future = Carbon.now().addDays(3);
 future.diffForHumans(); // '3 days from now'
@@ -434,7 +434,7 @@ future.diffForHumans({ absolute: true }); // '3 days'
 
 ### Token-based
 
-```typescript
+```typescript fragment
 // anywhere in your app
 d.format(); // '2026-06-15 09:30:00'  (default)
 d.format("YYYY-MM-DD"); // '2026-06-15'
@@ -472,7 +472,7 @@ d.format("YYYY-MM-DDTHH:mm:ssZ"); // '2026-06-15T09:30:00+02:00'
 
 `intlFormat` delegates to `Intl.DateTimeFormat`:
 
-```typescript
+```typescript fragment
 // anywhere in your app
 d.intlFormat("en-US", { dateStyle: "full" });
 // → 'Monday, June 15, 2026'
@@ -489,7 +489,7 @@ d.intlFormat("ja-JP", { year: "numeric", month: "long", day: "numeric" });
 
 ### Convenience formatters
 
-```typescript
+```typescript fragment
 // anywhere in your app
 d.toDateString(); // '2026-06-15'
 d.toDateTimeString(); // '2026-06-15 09:30:00'
@@ -509,7 +509,7 @@ d.toLongDate(); // '15 June 2026'
 
 ## Serialisation
 
-```typescript
+```typescript fragment
 // anywhere in your app
 d.toDate(); // native Date
 d.toISOString(); // '2026-06-15T07:30:00+00:00' (UTC)
@@ -529,7 +529,7 @@ d.toPlainDate(); // Temporal.PlainDate (loses time + timezone)
 
 `valueOf()` enables direct comparison with `<`, `>`, `-`:
 
-```typescript
+```typescript fragment
 // anywhere in your app
 const a = new Carbon("2026-01-01");
 const b = new Carbon("2026-06-15");
@@ -544,7 +544,7 @@ Math.min(+a, +b) === +a; // true
 `CarbonInterval` is an immutable duration value object backed by
 `Temporal.Duration`. Every method returns a new instance.
 
-```typescript
+```typescript fragment
 // anywhere in your app
 import { CarbonInterval } from "zerotal/carbon";
 
@@ -575,7 +575,7 @@ const built = new CarbonInterval({ years: 1, months: 6, days: 3 });
 
 Chain `and*` methods to compose multi-unit intervals:
 
-```typescript
+```typescript fragment
 // anywhere in your app
 CarbonInterval.days(3).andHours(6).andMinutes(30);
 // → 3 days 6 hours 30 minutes
@@ -592,7 +592,7 @@ Available: `andYears`, `andMonths`, `andWeeks`, `andDays`, `andHours`,
 
 ### Interval getters
 
-```typescript
+```typescript fragment
 // anywhere in your app
 const i = CarbonInterval.fromISO("P1Y2M3DT4H5M6S");
 
@@ -613,7 +613,7 @@ i.isZero; // false
 
 ### Interval arithmetic
 
-```typescript
+```typescript fragment
 // anywhere in your app
 const a = CarbonInterval.hours(2);
 const b = CarbonInterval.minutes(30);
@@ -630,7 +630,7 @@ CarbonInterval.abs(a.negate()); // 2 hours  (all fields positive)
 `cascade()` rolls excess sub-units up into higher ones. It needs a reference date
 for calendar-aware units (months, years) and defaults to now in UTC.
 
-```typescript
+```typescript fragment
 // anywhere in your app
 CarbonInterval.seconds(90).cascade();
 // → { minutes: 1, seconds: 30 }
@@ -653,7 +653,7 @@ CarbonInterval.days(32).cascade(Carbon.today().inTimezone("UTC").toZonedDateTime
 
 Calendar units (years, months) are approximated as average lengths.
 
-```typescript
+```typescript fragment
 // anywhere in your app
 CarbonInterval.hours(2).andMinutes(30).totalMinutes(); // 150
 CarbonInterval.days(3).andHours(6).totalHours(); // 78
@@ -667,7 +667,7 @@ i.totalWeeks();
 
 ### Interval comparison
 
-```typescript
+```typescript fragment
 // anywhere in your app
 const a = CarbonInterval.hours(2);
 const b = CarbonInterval.minutes(90);
@@ -681,7 +681,7 @@ CarbonInterval.compare(a, b); // 1 (a > b), -1 (a < b), 0 (equal)
 
 ### Human-readable output
 
-```typescript
+```typescript fragment
 // anywhere in your app
 CarbonInterval.days(1).andHours(2).andMinutes(30).forHumans();
 // → '1 day 2 hours 30 minutes'
@@ -697,7 +697,7 @@ i.toString(); // alias for forHumans()
 
 ### Interval serialisation
 
-```typescript
+```typescript fragment
 // anywhere in your app
 CarbonInterval.days(1).andHours(2).toISO();
 // → 'P1DT2H'
@@ -715,7 +715,7 @@ An interval is what [`add()` and `subtract()`](#add-and-subtract) accept, and wh
 [`diffAsCarbonInterval()`](#differences) returns — the two directions between the
 types:
 
-```typescript
+```typescript fragment
 // anywhere in your app
 const interval = CarbonInterval.days(3).andHours(6);
 
@@ -732,7 +732,7 @@ immutable and pure, so it needs no application — but a test that reaches for
 **Pin the instant.** Pass a fixed input rather than using the current time, and
 the assertion holds forever:
 
-```typescript
+```typescript fragment
 // tests/dates/BillingPeriod.test.ts
 import { test, expect } from "bun:test";
 import { Carbon } from "zerotal/carbon";
@@ -751,7 +751,7 @@ test("a mid-month signup bills to the end of the month", () => {
 calls `Carbon.now()` internally can only be tested by waiting or by mocking; one
 that accepts a `now` parameter is tested by passing a date:
 
-```typescript
+```typescript fragment
 // app/services/billing.ts
 export function periodFor(signedUp: Carbon, now: Carbon = Carbon.now()): Period {
   // …
@@ -766,7 +766,7 @@ month end.
 transitions are where date code breaks, and none of them appear in a test written
 around today:
 
-```typescript
+```typescript fragment
 // tests/dates/BillingPeriod.test.ts
 test("handles a leap day", () => {
   expect(Carbon.create("2028-02-29T12:00:00Z").addYears(1).toDateString()).toBe("2029-02-28");