@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/agents/examples/timezones.md

@@ -0,0 +1,366 @@
+<!-- Generated by `bun run gen:agent-docs` from samples/recipes/timezones. Do not edit. -->
+
+# timezones
+
+Every time-aware field type on one entity, plus the ctx.tz handler API.
+
+## README
+
+# Timezones
+
+Every time-aware field type on one entity, plus the `ctx.tz` handler API. The
+recipe ships a `delivery` entity that carries four different kinds of time and
+two feature-level queries that reach for `ctx.tz` directly.
+
+Dates are the field type people get wrong most often — "10:00" means nothing
+without a zone, a birthday has no time at all, and "now" is a single instant
+seen differently around the world. The framework gives each of those its own
+field type so the ambiguity is gone at the schema, not patched in handlers.
+
+## What it shows
+
+- **Four time field types**, each for a distinct shape of time:
+  - `createLocatedTimestampField()` — a **wall-clock time at a place**
+    (`pickup`). One schema field becomes two columns (`pickup_utc` +
+    `pickup_tz`) and three read fields (`{ at, tz, utc }`). Write `{ at, tz }`
+    and the framework computes the UTC instant; read it back and you get the
+    original wall-clock, the zone, **and** the UTC instant.
+  - `createDateField()` — a **calendar date** with no time and no zone
+    (`dropoffOn`). A birthday, a due date.
+  - `createTimestampField()` — a **UTC instant**, a single point on the
+    timeline (`bookedAt`). When something happened.
+  - `createTzField()` — a bare **IANA zone name** (`homeZone`), e.g.
+    `"Europe/Berlin"`.
+- **IANA validation at the write boundary** — an invalid zone name (in a `tz`
+  field or in a located field's `tz`) is rejected with a `validation_error`
+  before it ever reaches the database, via `Intl.supportedValuesOf`.
+- **`ctx.tz` in handlers** — the time API feature code uses instead of
+  `new Date()`:
+  - `ctx.tz.todayRange(zone)` / `ctx.tz.today(zone)` — the `day-window` query
+    returns today's UTC range for a zone, ready to drop into a `BETWEEN` over
+    the `pickup_utc` column. It crosses DST and the date line correctly.
+  - `ctx.tz.fromCoordinates(coords)` — the `zone-at` query resolves lat/lng to
+    an IANA zone through an injected `GeoTzProvider`.
+
+## The located field, end to end
+
+```
+write   { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" }
+stored  pickup_utc = 2026-04-15T09:00:00Z   pickup_tz = "Europe/Lisbon"
+read    { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon", utc: "2026-04-15T09:00:00Z" }
+```
+
+Lisbon is on summer time (UTC+1) on that date, so 10:00 local is 09:00 UTC —
+and the recipe's integration test pins exactly that, proving the conversion is
+DST-aware rather than a fixed offset. The wall-clock you wrote comes back
+unchanged; the `utc` field is there when you need to sort or range-query.
+
+The renderer pairs this field with a date-time + zone picker out of the box, so
+a form binding to `pickup` gets the combined control with no extra wiring — see
+the `use-all-bundled` sample app for the live picker.
+
+## The GeoTzProvider seam
+
+`ctx.tz.fromCoordinates` / `ctx.tz.fromAddress` delegate to an optional
+provider you inject via the app context — there is no built-in geocoder, so v1
+ships nothing that phones home:
+
+```ts illustration
+runProdApp({ /* … */, extraContext: { geoTzProvider: myProvider } })
+// or buildServer({ context: { geoTzProvider: myProvider } })
+```
+
+`fromCoordinates` is the primary method because offline geo-tz libraries
+resolve **lat/lng**, not postal addresses; `fromAddress` is optional, for
+geocoding-API providers. With no provider configured, both throw a clear,
+actionable error. The recipe's test injects a tiny fake provider to exercise
+the seam end to end.
+
+## Flow
+
+1. Define the entity with `createEntity({ fields: { … } })` mixing the four
+   time field types.
+2. Register CRUD via `defineEntity*Handler` — create/update accept the located
+   field as `{ at, tz }`; the write boundary computes UTC.
+3. Add feature-level queries with `r.queryHandler` that call `ctx.tz` —
+   `day-window` (todayRange) and `zone-at` (fromCoordinates). Their names carry
+   no entity prefix, so they return their own shape instead of being filtered
+   against the entity's fields.
+
+## Tests
+
+```bash
+bun kumiko test integration samples/timezones
+```
+
+Integration tests under `src/__tests__/` prove the located round-trip with
+DST-aware UTC, all four field types preserved, IANA rejection at the write
+boundary, the `todayRange` day-window, and the `fromCoordinates` provider seam.
+
+## Related samples
+
+- [basic-entity](/en/samples/recipes-basic-entity/) — the CRUD baseline these
+  time fields sit on top of.
+- [custom-handlers](/en/samples/recipes-custom-handlers/) — more on
+  `r.writeHandler` / `r.queryHandler` with business logic.
+
+## Source files
+
+### src/__tests__/feature.integration.test.ts
+
+```ts
+// Timezones Sample — Integration Test
+// Proves: located round-trip with computed UTC across DST, all four time field
+// types preserved, IANA validation at the write boundary, the todayRange
+// day-window query, and the fromCoordinates GeoTzProvider seam.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import type { SaveContext } from "@cosmicdrift/kumiko-framework/engine";
+import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  setupTestStack,
+  type TestStack,
+  TestUsers,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import type { GeoTzProvider } from "@cosmicdrift/kumiko-framework/time";
+import { deliveryEntity, timezonesFeature } from "../feature";
+
+let stack: TestStack;
+
+const admin = TestUsers.admin;
+
+// A stand-in for an offline geo-tz library: positive latitude → northern
+// example zone, negative → southern. Real providers resolve true lat/lng;
+// this one only has to prove the injection seam threads through to ctx.tz.
+const fakeGeoTz: GeoTzProvider = {
+  fromCoordinates: (coords) => (coords.latitude >= 0 ? "Europe/Berlin" : "America/Sao_Paulo"),
+};
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [timezonesFeature],
+    extraContext: { geoTzProvider: fakeGeoTz },
+  });
+  await unsafeCreateEntityTable(stack.db, deliveryEntity);
+  await createEventsTable(stack.db);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(() => {
+  stack.events.reset();
+});
+
+// --- locatedTimestamp round-trip ---
+
+describe("located round-trip", () => {
+  test("write { at, tz } reads back { at, tz, utc } with UTC computed across DST", async () => {
+    // Lisbon is on WEST (UTC+1) on 2026-04-15, so 10:00 local is 09:00 UTC.
+    const created = await stack.http.writeOk<SaveContext>(
+      "timezones:write:delivery:create",
+      { label: "DST check", pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" } },
+      admin,
+    );
+
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "timezones:query:delivery:detail",
+      { id: created.id },
+      admin,
+    );
+
+    const pickup = detail["pickup"] as { at: string; tz: string; utc: string };
+    expect(pickup.tz).toBe("Europe/Lisbon");
+    expect(pickup.at).toBe("2026-04-15T10:00:00");
+    expect(pickup.utc).toBe("2026-04-15T09:00:00Z");
+  });
+});
+
+// --- all four time field types ---
+
+describe("field types", () => {
+  test("date, timestamp and tz fields each preserve their value", async () => {
+    const created = await stack.http.writeOk<SaveContext>(
+      "timezones:write:delivery:create",
+      {
+        label: "Full record",
+        pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" },
+        dropoffOn: "2026-04-20",
+        bookedAt: "2026-04-15T08:30:00Z",
+        homeZone: "Europe/Berlin",
+      },
+      admin,
+    );
+
+    const detail = await stack.http.queryOk<Record<string, unknown>>(
+      "timezones:query:delivery:detail",
+      { id: created.id },
+      admin,
+    );
+
+    // A `date` field carries a calendar day, no time-of-day/timezone
+    // component — it round-trips as a plain "yyyy-mm-dd" (kumiko-framework#1924).
+    expect(detail["dropoffOn"]).toBe("2026-04-20");
+    expect(detail["homeZone"]).toBe("Europe/Berlin");
+    expect(detail["bookedAt"]).toBe("2026-04-15T08:30:00Z");
+  });
+});
+
+// --- IANA validation at the write boundary ---
+
+describe("IANA validation", () => {
+  test("invalid bare tz field is rejected with validation_error", async () => {
+    const error = await stack.http.writeErr(
+      "timezones:write:delivery:create",
+      {
+        label: "Bad zone",
+        pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon" },
+        homeZone: "Mars/Olympus",
+      },
+      admin,
+    );
+    expect(error.code).toBe("validation_error");
+  });
+
+  test("invalid located-field tz is rejected with validation_error", async () => {
+    const error = await stack.http.writeErr(
+      "timezones:write:delivery:create",
+      { label: "Bad located zone", pickup: { at: "2026-04-15T10:00:00", tz: "Nowhere/Nope" } },
+      admin,
+    );
+    expect(error.code).toBe("validation_error");
+  });
+});
+
+// --- ctx.tz.todayRange — day-window query ---
+
+describe("day-window query (todayRange)", () => {
+  test("returns the zone's calendar date and a 24h UTC window", async () => {
+    const window = await stack.http.queryOk<{
+      zone: string;
+      date: string;
+      start: string;
+      end: string;
+    }>("timezones:query:day-window", { zone: "Asia/Tokyo" }, admin);
+
+    expect(window.zone).toBe("Asia/Tokyo");
+    expect(window.date).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+    expect(window.start.endsWith("Z")).toBe(true);
+    expect(window.end.endsWith("Z")).toBe(true);
+    // Tokyo has no DST, so today's window is exactly 24 hours.
+    expect(Date.parse(window.end) - Date.parse(window.start)).toBe(24 * 60 * 60 * 1000);
+  });
+
+  test("invalid zone is rejected with validation_error, not a raw RangeError", async () => {
+    const res = await stack.http.query(
+      "timezones:query:day-window",
+      { zone: "Nowhere/Nope" },
+      admin,
+    );
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("validation_error");
+  });
+});
+
+// --- ctx.tz.fromCoordinates — GeoTzProvider seam ---
+
+describe("fromCoordinates (injected GeoTzProvider)", () => {
+  test("northern coordinates resolve to the provider's northern zone", async () => {
+    const result = await stack.http.queryOk<{ zone: string }>(
+      "timezones:query:zone-at",
+      { latitude: 52.52, longitude: 13.405 },
+      admin,
+    );
+    expect(result.zone).toBe("Europe/Berlin");
+  });
+
+  test("southern coordinates resolve to the provider's southern zone", async () => {
+    const result = await stack.http.queryOk<{ zone: string }>(
+      "timezones:query:zone-at",
+      { latitude: -23.55, longitude: -46.63 },
+      admin,
+    );
+    expect(result.zone).toBe("America/Sao_Paulo");
+  });
+});
+```
+
+### src/feature.ts
+
+```ts
+import {
+  createDateField,
+  createEntity,
+  createLocatedTimestampField,
+  createTextField,
+  createTimestampField,
+  createTzField,
+  defineEntityDeleteHandler,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { isValidIanaTimeZone } from "@cosmicdrift/kumiko-framework/time";
+import { z } from "zod";
+
+export const deliveryEntity = createEntity({
+  table: "read_sample_deliveries",
+  fields: {
+    label: createTextField({ personal: false, reason: "is_business_data", required: true }),
+    pickup: createLocatedTimestampField({ required: true }),
+    dropoffOn: createDateField(),
+    bookedAt: createTimestampField(),
+    homeZone: createTzField(),
+  },
+  softDelete: true,
+});
+
+const write = { access: { roles: ["Admin", "User"] } } as const;
+const adminWrite = { access: { roles: ["Admin"] } } as const;
+const openRead = {
+  access: {
+    openToAll: {
+      reason:
+        "any signed-in user may list deliveries and query the timezone helpers below; " +
+        "writes are still gated by the roles above",
+    },
+  },
+} as const;
+
+export const timezonesFeature = defineFeature("timezones", (r) => {
+  r.crud("delivery", deliveryEntity, {
+    write,
+    read: openRead,
+    verbs: { delete: false, restore: false },
+  });
+  r.writeHandler(defineEntityDeleteHandler("delivery", deliveryEntity, adminWrite));
+
+  r.queryHandler(
+    "day-window",
+    z.object({
+      zone: z.string().refine(isValidIanaTimeZone, { message: "Invalid IANA timezone" }),
+    }),
+    async (query, ctx) => {
+      const { start, end } = ctx.tz.todayRange(query.payload.zone);
+      return {
+        zone: query.payload.zone,
+        date: ctx.tz.today(query.payload.zone).toString(),
+        start: start.toString(),
+        end: end.toString(),
+      };
+    },
+    openRead,
+  );
+
+  r.queryHandler(
+    "zone-at",
+    z.object({ latitude: z.number(), longitude: z.number() }),
+    async (query, ctx) => {
+      const zone = await ctx.tz.fromCoordinates(query.payload);
+      return { zone };
+    },
+    openRead,
+  );
+});
+```