@thomasfosterau/effect-sitemap 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Foster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# @thomasfosterau/effect-sitemap
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sitemap, sitemap index and JSON Feed 1.1 builders for Effect web applications (rendered or streamed), the low-churn edge cache policy they share, and the `Cache-Tag` purge-on-mutation seam.
+
+Invariant ids in doc comments and below (`CANON-001`, `PERF-CACHE-002`, …) name the rule an export enforces; [`SECURITY.md`](https://github.com/thomasfosterau/effect-web/blob/main/SECURITY.md#invariant-ids) states each rule and the exports that enforce it.
+
+## Install
+
+```sh
+pnpm add @thomasfosterau/effect-sitemap @thomasfosterau/effect-web effect
+```
+
+Peer: `effect` (>= 4.0.0-rc.118). `@thomasfosterau/effect-web` is a dependency (the purge logs through its event logger). One entry, `sideEffects: false`, no top-level statements in `dist/`.
+
+Everything takes a **site-root-relative path** and the **canonical origin** (the configured production origin, never the request origin). `renderSitemap`, `sitemapStream` and `buildJsonFeed` resolve every URL they emit against it (CANON-001). The map from an application's resource types to its route segments (`sitemapPath`, `feedPath`) is application vocabulary and stays in the application.
+
+## Usage
+
+### Sitemaps
+
+```ts
+import * as Stream from "effect/Stream";
+import {
+  lastmodOf,
+  renderSitemap,
+  SITEMAP_CACHE_TAG,
+  sitemapResponse,
+  type SitemapUrl,
+} from "@thomasfosterau/effect-sitemap";
+
+// `base` is the canonical origin (the configured production origin); the rows are the application's.
+const STATIC_PAGES: ReadonlyArray<SitemapUrl> = [{ path: "/" }, { path: "/about" }];
+
+// Whole, for a bounded set:
+const wholeSitemap = (base: string, rows: ReadonlyArray<{ id: string; updatedAt: Date }>) =>
+  renderSitemap(base, [
+    ...STATIC_PAGES,
+    ...rows.map((row) => ({ path: `/people/${row.id}`, lastmod: lastmodOf(row.updatedAt) })),
+  ]);
+
+// Streamed, one chunk per entry, for a large one (run the enumeration before building the response):
+const streamedSitemap = (base: string, entries: ReadonlyArray<SitemapUrl>) =>
+  sitemapResponse(base, Stream.fromIterable(entries), { cacheTag: SITEMAP_CACHE_TAG });
+```
+
+| Export | What it is |
+| --- | --- |
+| `SitemapUrl` | `{ path, lastmod?: "YYYY-MM-DD" }`. |
+| `lastmodOf(value)` | The day of a `Date` or an ISO string; `undefined` (omit `<lastmod>`) otherwise. A parse, never a clock read. |
+| `renderUrl(base, entry)` | One `<url>`, its `<loc>` absolute on `base`. |
+| `renderSitemap(base, entries)` | The whole `<urlset>` with the XML declaration, every `<loc>` absolute on `base` (CANON-001). |
+| `sitemapStream(base, Stream<SitemapUrl>)` | The document as a `Stream<string>`: opening, one chunk per entry, closing — never materialised in the isolate. Every `<loc>` is absolute on `base` (CANON-001). |
+| `sitemapResponse(base, stream, { cacheTag?, cacheControl? })` | The stream as an `HttpServerResponse`: `application/xml`, `LOW_CHURN_CACHE_CONTROL`, the `Cache-Tag`. |
+| `chunkSitemap(entries, size = SITEMAP_MAX_URLS)`, `renderSitemapIndex(base, sitemaps)` | Past 50,000 URLs: split into files and index them. |
+| `URLSET_OPEN`, `URLSET_CLOSE`, `escapeXml` | The pieces, and the escaper for any authored text a consumer decides to emit. Nothing here emits any: `<loc>` is not escaped, because every location is the canonical origin plus a path built from validated ids or a hand-written list. |
+
+### JSON Feed 1.1
+
+```ts
+import {
+  buildJsonFeed,
+  FEED_CACHE_TAG,
+  FEED_ITEM_LIMIT,
+  jsonFeedResponse,
+  type FeedEntry,
+} from "@thomasfosterau/effect-sitemap";
+
+// `rows` are the newest FEED_ITEM_LIMIT changes, newest first.
+const feedResponse = (base: string, rows: ReadonlyArray<FeedEntry>) =>
+  jsonFeedResponse(
+    buildJsonFeed(
+      {
+        base,
+        title: "Example — Latest changes",
+        description: `The ${FEED_ITEM_LIMIT} most recent changes.`,
+      },
+      rows,
+    ),
+    { cacheTag: FEED_CACHE_TAG },
+  );
+```
+
+| Export | What it is |
+| --- | --- |
+| `FeedEntry` | `{ path, publishedAt, updatedAt, title?: string \| null, summary?: string \| null }` — the SQL wire shape, `null` for an absent text. |
+| `buildJsonFeed({ base, title, description, feedPath? = "/feed.json", homePath? = "/" }, entries)` | The document. Item `id` and `url` are the canonical URL on `base`, never the request origin (CANON-001); `title` / `summary` are omitted, never `null`-valued; order is the caller's (newest-first). |
+| `FEED_ITEM_LIMIT` (50) | The item bound: a change-discovery feed, not a corpus listing (DISC-010). |
+| `jsonFeedResponse(feed, { cacheTag?, cacheControl? })` | 2-space pretty-printed `application/feed+json` with the cache headers. The indent is part of the bytes on the wire and in every cached copy. |
+| `JsonFeed`, `JsonFeedItem`, `JSON_FEED_CONTENT_TYPE` | The shapes and the media type. |
+
+### Cache-Tag purge on mutation
+
+```ts
+import {
+  makePurgeTagsForResourceType,
+  purgeCacheTags,
+  type CachePurgeContext,
+} from "@thomasfosterau/effect-sitemap";
+
+// The resource types the sitemap and feed enumerate.
+const purgeTagsForResourceType = makePurgeTagsForResourceType(["posts", "people"]);
+
+// After a mutation to a resource of `type` (and after the response has gone out):
+const purgeAfterMutation = (ctx: CachePurgeContext, type: string) =>
+  purgeCacheTags(ctx, purgeTagsForResourceType(type));
+```
+
+| Export | What it is |
+| --- | --- |
+| `FEED_CACHE_TAG` (`feed`), `SITEMAP_CACHE_TAG` (`sitemap`) | The tags the responses carry and the purge names. |
+| `makePurgeTagsForResourceType(eligibleTypes, tags?)` | `(type) => tags`: both tags for a type the documents enumerate, none otherwise — decided from the type alone, no visibility check (a wasted purge over a missed one). |
+| `CachePurgeContext` | The `{ cache?: { purge({ tags }) } }` subset of a Workers `ExecutionContext`; `cache` is absent in local dev. |
+| `purgeCacheTags(ctx, tags)` | `Effect<void>`: a no-op for no tags or no `cache`; a logged `cache-purge.rejected` (`success: false`) or `cache-purge.failed` (rejection), never a failure — the mutation never sees a dropped purge. The purge half of PERF-CACHE-002. |
+| `purgeCacheTagsPromise(ctx, tags)` | The same as a `Promise`, for `ctx.waitUntil`. |
+| `LOW_CHURN_CACHE_CONTROL` | The document `Cache-Control` (an hour at the edge, a day stale-while-revalidate): the explicit edge TTL of PERF-CACHE-002. |
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,426 @@
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import * as HttpServerResponse from "effect/http/HttpServerResponse";
+//#region src/index.d.ts
+/**
+ * One sitemap entry: a site-root-relative path and an optional
+ * `YYYY-MM-DD` lastmod.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface SitemapUrl {
+  readonly path: string;
+  readonly lastmod?: string | undefined;
+}
+/**
+ * The sitemap protocol's cap on one file: 50,000 URLs (and 50 MB). Split
+ * into an index past it ({@link chunkSitemap}, {@link renderSitemapIndex}).
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export declare const SITEMAP_MAX_URLS = 50000;
+/**
+ * The `Cache-Control` a low-churn generated document (`sitemap.xml`,
+ * `feed.json`, `robots.txt`) is served with: the edge caches the whole
+ * document, bounding any request-time enumeration behind it to at most one
+ * per hour per edge (PERF-CACHE-002). A mutation that could change the
+ * document purges its `Cache-Tag` ({@link purgeCacheTags}) rather than
+ * relying on the TTL alone.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export declare const LOW_CHURN_CACHE_CONTROL = "public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400";
+/**
+ * What a served discovery document is cached under.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface DocumentCacheOptions {
+  /** The `Cache-Tag` a mutation purges ({@link purgeCacheTags}); absent means untagged. */
+  readonly cacheTag?: string | undefined;
+  /** Defaults to {@link LOW_CHURN_CACHE_CONTROL}. */
+  readonly cacheControl?: string | undefined;
+}
+/**
+ * The five XML-reserved characters escaped for element text.
+ *
+ * @example
+ * ```ts
+ * import { escapeXml } from "@thomasfosterau/effect-sitemap"
+ *
+ * escapeXml(`a & b < "c"`) // "a &amp; b &lt; &quot;c&quot;"
+ * ```
+ *
+ * @since 0.1.0
+ * @category rendering
+ */
+export declare const escapeXml: (value: string) => string;
+/**
+ * The `YYYY-MM-DD` day of a `Date` or an ISO timestamp string, or
+ * `undefined` when unparsable — the value `renderUrl` reads as "omit
+ * `<lastmod>`". A parse of an existing value, never a clock read.
+ *
+ * @example
+ * ```ts
+ * import { lastmodOf } from "@thomasfosterau/effect-sitemap"
+ *
+ * lastmodOf("2026-03-04T05:06:07.000Z") // "2026-03-04"
+ * lastmodOf(new Date("2026-03-04T23:59:59Z")) // "2026-03-04"
+ * lastmodOf("not a date") // undefined
+ * ```
+ *
+ * @since 0.1.0
+ * @category rendering
+ */
+export declare const lastmodOf: (value: unknown) => string | undefined;
+/**
+ * One `<url>` element on `base` (the canonical origin, never the request
+ * origin).
+ *
+ * @example
+ * ```ts
+ * import { renderUrl } from "@thomasfosterau/effect-sitemap"
+ *
+ * renderUrl("https://example.com", { path: "/posts/1", lastmod: "2026-03-04" })
+ * // "<url><loc>https://example.com/posts/1</loc><lastmod>2026-03-04</lastmod></url>"
+ * renderUrl("https://example.com", { path: "/" }) // "<url><loc>https://example.com/</loc></url>"
+ * ```
+ *
+ * @since 0.1.0
+ * @category rendering
+ */
+export declare const renderUrl: (base: string, entry: SitemapUrl) => string;
+/**
+ * The XML declaration and `<urlset>` opening tag that begin every sitemap
+ * ({@link renderSitemap}, and the first chunk of {@link sitemapStream}).
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export declare const URLSET_OPEN = "<?xml version=\"1.0\" encoding=\"UTF-8\"?><urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">";
+/**
+ * The `<urlset>` closing tag that ends every sitemap ({@link renderSitemap},
+ * and the last chunk of {@link sitemapStream}).
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export declare const URLSET_CLOSE = "</urlset>";
+/**
+ * The whole `sitemap.xml` on `base`, materialised: every `<loc>` is absolute
+ * on that canonical origin, never the request origin (CANON-001). For a
+ * bounded set (static shells plus a `LIMIT`ed enumeration);
+ * {@link sitemapStream} for a large one.
+ *
+ * @example
+ * ```ts
+ * import { renderSitemap } from "@thomasfosterau/effect-sitemap"
+ *
+ * renderSitemap("https://example.com", [{ path: "/" }, { path: "/posts/1", lastmod: "2026-03-04" }])
+ * // '<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><url><loc>https://example.com/</loc></url><url><loc>https://example.com/posts/1</loc><lastmod>2026-03-04</lastmod></url></urlset>'
+ * ```
+ *
+ * @since 0.1.0
+ * @category rendering
+ */
+export declare const renderSitemap: (base: string, entries: Iterable<SitemapUrl>) => string;
+/**
+ * The `sitemap.xml` as a `Stream` of text chunks — the opening, one chunk
+ * per entry as the source yields it, the closing — so a large enumeration
+ * is never materialised in the isolate before the first byte goes out. Every
+ * `<loc>` is absolute on `base`, the canonical origin (CANON-001). Run
+ * the enumeration before the response is constructed when it needs a
+ * database: the body stream must not touch a per-request runtime that is
+ * tearing down.
+ *
+ * @example
+ * ```ts
+ * import * as Effect from "effect/Effect"
+ * import * as Stream from "effect/Stream"
+ * import { sitemapStream } from "@thomasfosterau/effect-sitemap"
+ *
+ * const chunks = await Effect.runPromise(
+ *   Stream.runCollect(sitemapStream("https://example.com", Stream.fromIterable([{ path: "/a" }, { path: "/b" }]))),
+ * )
+ * chunks.length // 4 — open, two entries, close
+ * ```
+ *
+ * @since 0.1.0
+ * @category streaming
+ */
+export declare const sitemapStream: <E, R>(base: string, entries: Stream.Stream<SitemapUrl, E, R>) => Stream.Stream<string, E, R>;
+/**
+ * The streamed `sitemap.xml` as an `HttpServerResponse` with the
+ * `application/xml` type, {@link LOW_CHURN_CACHE_CONTROL} and, when given,
+ * the `Cache-Tag` a mutation purges.
+ *
+ * @example
+ * ```ts
+ * import * as Effect from "effect/Effect"
+ * import * as Stream from "effect/Stream"
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse"
+ * import { SITEMAP_CACHE_TAG, sitemapResponse } from "@thomasfosterau/effect-sitemap"
+ *
+ * const response = sitemapResponse("https://example.com", Stream.fromIterable([{ path: "/" }]), { cacheTag: SITEMAP_CACHE_TAG })
+ * response.headers["cache-tag"] // "sitemap"
+ * await HttpServerResponse.toWeb(response).text() // the XML document
+ * ```
+ *
+ * @since 0.1.0
+ * @category streaming
+ */
+export declare const sitemapResponse: <E>(base: string, entries: Stream.Stream<SitemapUrl, E>, options?: DocumentCacheOptions) => HttpServerResponse.HttpServerResponse;
+/**
+ * Splits an enumeration into sitemap-sized files (at most `size` URLs each,
+ * default {@link SITEMAP_MAX_URLS}) for a sitemap index.
+ *
+ * @example
+ * ```ts
+ * import { chunkSitemap } from "@thomasfosterau/effect-sitemap"
+ *
+ * chunkSitemap([{ path: "/a" }, { path: "/b" }, { path: "/c" }], 2).map((chunk) => chunk.length) // [2, 1]
+ * ```
+ *
+ * @since 0.1.0
+ * @category rendering
+ */
+export declare const chunkSitemap: (entries: ReadonlyArray<SitemapUrl>, size?: number) => ReadonlyArray<ReadonlyArray<SitemapUrl>>;
+/**
+ * A `sitemap.xml` index over several sitemap files, each a site-root-relative
+ * path (`/sitemaps/posts-1.xml`) with an optional lastmod.
+ *
+ * @example
+ * ```ts
+ * import { renderSitemapIndex } from "@thomasfosterau/effect-sitemap"
+ *
+ * renderSitemapIndex("https://example.com", [{ path: "/sitemap-1.xml", lastmod: "2026-03-04" }, { path: "/sitemap-2.xml" }])
+ * // '<?xml version="1.0" encoding="UTF-8"?><sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><sitemap><loc>https://example.com/sitemap-1.xml</loc><lastmod>2026-03-04</lastmod></sitemap><sitemap><loc>https://example.com/sitemap-2.xml</loc></sitemap></sitemapindex>'
+ * ```
+ *
+ * @since 0.1.0
+ * @category rendering
+ */
+export declare const renderSitemapIndex: (base: string, sitemaps: Iterable<SitemapUrl>) => string;
+/**
+ * A JSON Feed 1.1 item (the subset emitted).
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface JsonFeedItem {
+  readonly id: string;
+  readonly url: string;
+  readonly title?: string;
+  readonly summary?: string;
+  readonly date_published: string;
+  readonly date_modified: string;
+}
+/**
+ * A JSON Feed 1.1 document (the subset emitted).
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface JsonFeed {
+  readonly version: "https://jsonfeed.org/version/1.1";
+  readonly title: string;
+  readonly home_page_url: string;
+  readonly feed_url: string;
+  readonly description: string;
+  readonly items: ReadonlyArray<JsonFeedItem>;
+}
+/**
+ * One feed entry: a site-root-relative path, its timestamps and its text.
+ * `title` / `summary` are `null` when the row has none (the SQL wire shape
+ * an enumeration produces) and omitted from the item.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface FeedEntry {
+  readonly path: string;
+  /** ISO 8601 datetime of the most recent version — the item's `date_modified`. */
+  readonly updatedAt: string;
+  /** ISO 8601 datetime of the earliest version — the item's `date_published`. */
+  readonly publishedAt: string;
+  readonly title?: string | null | undefined;
+  readonly summary?: string | null | undefined;
+}
+/**
+ * What names a feed.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface JsonFeedOptions {
+  /** The canonical origin, never the request origin. */
+  readonly base: string;
+  readonly title: string;
+  readonly description: string;
+  /** The feed's own path. Defaults to `/feed.json`. */
+  readonly feedPath?: string | undefined;
+  /** The home page's path. Defaults to `/`. */
+  readonly homePath?: string | undefined;
+}
+/**
+ * The item bound for a change-discovery feed: "latest changes", not a
+ * complete listing (DISC-010).
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export declare const FEED_ITEM_LIMIT = 50;
+/**
+ * Serialises feed entries into a JSON Feed 1.1 document. Pure. Item `id`
+ * and `url` are the canonical absolute URL on `options.base`, never the
+ * request origin (CANON-001); `title` / `summary` are omitted, never
+ * `null`-valued keys, when absent; entry order is preserved (the caller is
+ * responsible for newest-first).
+ *
+ * @example
+ * ```ts
+ * import { buildJsonFeed } from "@thomasfosterau/effect-sitemap"
+ *
+ * const feed = buildJsonFeed(
+ *   { base: "https://example.com", title: "Example — Latest changes", description: "The 50 most recent changes." },
+ *   [{ path: "/posts/1", publishedAt: "2026-01-01T00:00:00.000Z", updatedAt: "2026-02-01T00:00:00.000Z", title: "Hello", summary: null }],
+ * )
+ * feed.items[0]?.url // "https://example.com/posts/1"
+ * "summary" in (feed.items[0] ?? {}) // false
+ * ```
+ *
+ * @since 0.1.0
+ * @category feed
+ */
+export declare const buildJsonFeed: (options: JsonFeedOptions, entries: ReadonlyArray<FeedEntry>) => JsonFeed;
+/**
+ * The `Content-Type` a JSON Feed is served with.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export declare const JSON_FEED_CONTENT_TYPE = "application/feed+json";
+/**
+ * A JSON Feed as an `HttpServerResponse`: 2-space pretty-printed (a
+ * hand-readable discovery document; changing the indent changes the bytes on
+ * the wire and in every cached copy), `application/feed+json`,
+ * {@link LOW_CHURN_CACHE_CONTROL} and, when given, the `Cache-Tag`.
+ *
+ * @example
+ * ```ts
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse"
+ * import { buildJsonFeed, FEED_CACHE_TAG, jsonFeedResponse } from "@thomasfosterau/effect-sitemap"
+ *
+ * const feed = buildJsonFeed({ base: "https://example.com", title: "t", description: "d" }, [])
+ * const response = jsonFeedResponse(feed, { cacheTag: FEED_CACHE_TAG })
+ * response.headers["content-type"] // "application/feed+json"
+ * const text = await HttpServerResponse.toWeb(response).text()
+ * text.startsWith("{\n  \"version\"") // true
+ * ```
+ *
+ * @since 0.1.0
+ * @category feed
+ */
+export declare const jsonFeedResponse: (feed: JsonFeed, options?: DocumentCacheOptions) => HttpServerResponse.HttpServerResponse;
+/**
+ * The `Cache-Tag` on every `feed.json` response.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export declare const FEED_CACHE_TAG = "feed";
+/**
+ * The `Cache-Tag` on every `sitemap.xml` response.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export declare const SITEMAP_CACHE_TAG = "sitemap";
+/**
+ * Builds a `purgeTagsForResourceType`: the tags a mutation to one resource
+ * of `type` may have staled — both aggregate documents when the type can
+ * appear in them, nothing otherwise. Deliberately decided from the type
+ * alone, with no per-request visibility check: a write to an always-private
+ * resource of an eligible type still purges — a wasted purge, not a missed
+ * one. `eligibleTypes` are the resource-type segments the documents
+ * enumerate against (the values of the application's route-segment map).
+ *
+ * @example
+ * ```ts
+ * import { FEED_CACHE_TAG, makePurgeTagsForResourceType, SITEMAP_CACHE_TAG } from "@thomasfosterau/effect-sitemap"
+ *
+ * const purgeTagsForResourceType = makePurgeTagsForResourceType(["posts", "people"])
+ * purgeTagsForResourceType("posts") // [SITEMAP_CACHE_TAG, FEED_CACHE_TAG]
+ * purgeTagsForResourceType("comments") // []
+ * ```
+ *
+ * @since 0.1.0
+ * @category purging
+ */
+export declare const makePurgeTagsForResourceType: (eligibleTypes: Iterable<string>, tags?: ReadonlyArray<string>) => ((type: string) => ReadonlyArray<string>);
+/**
+ * The subset of a Cloudflare `ExecutionContext` the purge needs — narrowed
+ * so a test can pass a bare `{ cache: { purge } }` rather than a platform
+ * `ExecutionContext`. `cache` is absent in local dev, where Workers Cache is
+ * not emulated.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface CachePurgeContext {
+  readonly cache?: {
+    purge(options: {
+      readonly tags: Array<string>;
+    }): Promise<{
+      readonly success: boolean;
+      readonly errors: ReadonlyArray<unknown>;
+    }>;
+  } | undefined;
+}
+/**
+ * Purges the given `Cache-Tag`s from THIS Worker's Workers Cache (a
+ * `purge({ tags })` purges only the calling Worker's own cache). A no-op
+ * for an empty tag list or an absent `ctx.cache`; a logged, never failing,
+ * outcome otherwise — the purge call rejecting, or *resolving* with
+ * `success: false` (a Cloudflare-side failure resolves rather than rejects).
+ * This is the purge half of PERF-CACHE-002: a mutation purges by
+ * `Cache-Tag` rather than waiting out the TTL. A dropped purge must never
+ * surface on the mutation that triggered it: the surface serves stale
+ * content until its own `s-maxage` elapses, the accepted failure mode.
+ *
+ * @example
+ * ```ts
+ * import * as Effect from "effect/Effect"
+ * import { purgeCacheTags } from "@thomasfosterau/effect-sitemap"
+ *
+ * const purged: Array<ReadonlyArray<string>> = []
+ * const ctx = { cache: { purge: async ({ tags }: { tags: Array<string> }) => { purged.push(tags); return { success: true, errors: [] } } } }
+ * await Effect.runPromise(purgeCacheTags(ctx, ["sitemap", "feed"]))
+ * await Effect.runPromise(purgeCacheTags(undefined, ["sitemap"])) // no cache: no-op
+ * purged // [["sitemap", "feed"]]
+ * ```
+ *
+ * @since 0.1.0
+ * @category purging
+ */
+export declare const purgeCacheTags: (ctx: CachePurgeContext | undefined, tags: ReadonlyArray<string>) => Effect.Effect<void>;
+/**
+ * {@link purgeCacheTags} as a `Promise`, for the plain-JS seam a front
+ * door hands to `ctx.waitUntil` after the response has gone out.
+ *
+ * @example
+ * ```ts
+ * import { purgeCacheTagsPromise } from "@thomasfosterau/effect-sitemap"
+ *
+ * await purgeCacheTagsPromise(undefined, ["sitemap"]) // resolves; nothing to purge against
+ * ```
+ *
+ * @since 0.1.0
+ * @category purging
+ */
+export declare const purgeCacheTagsPromise: (ctx: CachePurgeContext | undefined, tags: ReadonlyArray<string>) => Promise<void>;
+//#endregion

package/dist/index.js

@@ -0,0 +1,410 @@
+import * as Arr from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as HashSet from "effect/HashSet";
+import * as Predicate from "effect/Predicate";
+import * as Stream from "effect/Stream";
+import * as HttpServerResponse from "effect/http/HttpServerResponse";
+import { describeError, logErrorEvent } from "@thomasfosterau/effect-web/observability";
+//#region src/index.ts
+/**
+* `@thomasfosterau/effect-sitemap` — the discovery documents an
+* application serves and the cache they live behind: `sitemap.xml`
+* (rendered whole, or streamed), a sitemap index, `feed.json` (JSON Feed
+* 1.1), and the `Cache-Tag` purge that keeps the edge copies fresh.
+*
+* Everything here takes a site-root-relative `path`; mapping a resource to
+* its route stays in the application.
+*
+* No XML escaping is applied to `<loc>`: every location is the canonical
+* origin plus a path an application derives from validated ids or a
+* hand-maintained list. If authored text (a title) is ever emitted it MUST
+* be escaped first; {@link escapeXml} is here for that.
+*
+* @since 0.1.0
+*/
+/**
+* The sitemap protocol's cap on one file: 50,000 URLs (and 50 MB). Split
+* into an index past it ({@link chunkSitemap}, {@link renderSitemapIndex}).
+*
+* @since 0.1.0
+* @category constants
+*/
+const SITEMAP_MAX_URLS = 5e4;
+/**
+* The `Cache-Control` a low-churn generated document (`sitemap.xml`,
+* `feed.json`, `robots.txt`) is served with: the edge caches the whole
+* document, bounding any request-time enumeration behind it to at most one
+* per hour per edge (PERF-CACHE-002). A mutation that could change the
+* document purges its `Cache-Tag` ({@link purgeCacheTags}) rather than
+* relying on the TTL alone.
+*
+* @since 0.1.0
+* @category constants
+*/
+const LOW_CHURN_CACHE_CONTROL = "public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400";
+/** The cache headers of a served document; the tag only when given. */
+const documentHeaders = (options) => {
+	const control = options.cacheControl ?? "public, max-age=3600, s-maxage=3600, stale-while-revalidate=86400";
+	return options.cacheTag === void 0 ? { "cache-control": control } : {
+		"cache-control": control,
+		"cache-tag": options.cacheTag
+	};
+};
+/**
+* The five XML-reserved characters escaped for element text.
+*
+* @example
+* ```ts
+* import { escapeXml } from "@thomasfosterau/effect-sitemap"
+*
+* escapeXml(`a & b < "c"`) // "a &amp; b &lt; &quot;c&quot;"
+* ```
+*
+* @since 0.1.0
+* @category rendering
+*/
+const escapeXml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
+/**
+* The `YYYY-MM-DD` day of a `Date` or an ISO timestamp string, or
+* `undefined` when unparsable — the value `renderUrl` reads as "omit
+* `<lastmod>`". A parse of an existing value, never a clock read.
+*
+* @example
+* ```ts
+* import { lastmodOf } from "@thomasfosterau/effect-sitemap"
+*
+* lastmodOf("2026-03-04T05:06:07.000Z") // "2026-03-04"
+* lastmodOf(new Date("2026-03-04T23:59:59Z")) // "2026-03-04"
+* lastmodOf("not a date") // undefined
+* ```
+*
+* @since 0.1.0
+* @category rendering
+*/
+const lastmodOf = (value) => {
+	if (Predicate.isDate(value)) return Number.isNaN(value.getTime()) ? void 0 : value.toISOString().slice(0, 10);
+	if (Predicate.isString(value) && /^\d{4}-\d{2}-\d{2}/.test(value)) return value.slice(0, 10);
+};
+/**
+* One `<url>` element on `base` (the canonical origin, never the request
+* origin).
+*
+* @example
+* ```ts
+* import { renderUrl } from "@thomasfosterau/effect-sitemap"
+*
+* renderUrl("https://example.com", { path: "/posts/1", lastmod: "2026-03-04" })
+* // "<url><loc>https://example.com/posts/1</loc><lastmod>2026-03-04</lastmod></url>"
+* renderUrl("https://example.com", { path: "/" }) // "<url><loc>https://example.com/</loc></url>"
+* ```
+*
+* @since 0.1.0
+* @category rendering
+*/
+const renderUrl = (base, entry) => {
+	return `<url><loc>${new URL(entry.path, base).toString()}</loc>${entry.lastmod === void 0 ? "" : `<lastmod>${entry.lastmod}</lastmod>`}</url>`;
+};
+/**
+* The XML declaration and `<urlset>` opening tag that begin every sitemap
+* ({@link renderSitemap}, and the first chunk of {@link sitemapStream}).
+*
+* @since 0.1.0
+* @category constants
+*/
+const URLSET_OPEN = `<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">`;
+/**
+* The `<urlset>` closing tag that ends every sitemap ({@link renderSitemap},
+* and the last chunk of {@link sitemapStream}).
+*
+* @since 0.1.0
+* @category constants
+*/
+const URLSET_CLOSE = `</urlset>`;
+/**
+* The whole `sitemap.xml` on `base`, materialised: every `<loc>` is absolute
+* on that canonical origin, never the request origin (CANON-001). For a
+* bounded set (static shells plus a `LIMIT`ed enumeration);
+* {@link sitemapStream} for a large one.
+*
+* @example
+* ```ts
+* import { renderSitemap } from "@thomasfosterau/effect-sitemap"
+*
+* renderSitemap("https://example.com", [{ path: "/" }, { path: "/posts/1", lastmod: "2026-03-04" }])
+* // '<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><url><loc>https://example.com/</loc></url><url><loc>https://example.com/posts/1</loc><lastmod>2026-03-04</lastmod></url></urlset>'
+* ```
+*
+* @since 0.1.0
+* @category rendering
+*/
+const renderSitemap = (base, entries) => [
+	URLSET_OPEN,
+	...Arr.map(Arr.fromIterable(entries), (entry) => renderUrl(base, entry)),
+	URLSET_CLOSE
+].join("");
+/**
+* The `sitemap.xml` as a `Stream` of text chunks — the opening, one chunk
+* per entry as the source yields it, the closing — so a large enumeration
+* is never materialised in the isolate before the first byte goes out. Every
+* `<loc>` is absolute on `base`, the canonical origin (CANON-001). Run
+* the enumeration before the response is constructed when it needs a
+* database: the body stream must not touch a per-request runtime that is
+* tearing down.
+*
+* @example
+* ```ts
+* import * as Effect from "effect/Effect"
+* import * as Stream from "effect/Stream"
+* import { sitemapStream } from "@thomasfosterau/effect-sitemap"
+*
+* const chunks = await Effect.runPromise(
+*   Stream.runCollect(sitemapStream("https://example.com", Stream.fromIterable([{ path: "/a" }, { path: "/b" }]))),
+* )
+* chunks.length // 4 — open, two entries, close
+* ```
+*
+* @since 0.1.0
+* @category streaming
+*/
+const sitemapStream = (base, entries) => Stream.concat(Stream.concat(Stream.succeed(URLSET_OPEN), Stream.map(entries, (entry) => renderUrl(base, entry))), Stream.succeed(URLSET_CLOSE));
+/**
+* The streamed `sitemap.xml` as an `HttpServerResponse` with the
+* `application/xml` type, {@link LOW_CHURN_CACHE_CONTROL} and, when given,
+* the `Cache-Tag` a mutation purges.
+*
+* @example
+* ```ts
+* import * as Effect from "effect/Effect"
+* import * as Stream from "effect/Stream"
+* import * as HttpServerResponse from "effect/http/HttpServerResponse"
+* import { SITEMAP_CACHE_TAG, sitemapResponse } from "@thomasfosterau/effect-sitemap"
+*
+* const response = sitemapResponse("https://example.com", Stream.fromIterable([{ path: "/" }]), { cacheTag: SITEMAP_CACHE_TAG })
+* response.headers["cache-tag"] // "sitemap"
+* await HttpServerResponse.toWeb(response).text() // the XML document
+* ```
+*
+* @since 0.1.0
+* @category streaming
+*/
+const sitemapResponse = (base, entries, options = {}) => HttpServerResponse.stream(Stream.encodeText(sitemapStream(base, entries)), {
+	contentType: "application/xml",
+	headers: documentHeaders(options)
+});
+/**
+* Splits an enumeration into sitemap-sized files (at most `size` URLs each,
+* default {@link SITEMAP_MAX_URLS}) for a sitemap index.
+*
+* @example
+* ```ts
+* import { chunkSitemap } from "@thomasfosterau/effect-sitemap"
+*
+* chunkSitemap([{ path: "/a" }, { path: "/b" }, { path: "/c" }], 2).map((chunk) => chunk.length) // [2, 1]
+* ```
+*
+* @since 0.1.0
+* @category rendering
+*/
+const chunkSitemap = (entries, size = SITEMAP_MAX_URLS) => Arr.isReadonlyArrayEmpty(entries) ? [] : Arr.chunksOf(entries, size);
+/**
+* A `sitemap.xml` index over several sitemap files, each a site-root-relative
+* path (`/sitemaps/posts-1.xml`) with an optional lastmod.
+*
+* @example
+* ```ts
+* import { renderSitemapIndex } from "@thomasfosterau/effect-sitemap"
+*
+* renderSitemapIndex("https://example.com", [{ path: "/sitemap-1.xml", lastmod: "2026-03-04" }, { path: "/sitemap-2.xml" }])
+* // '<?xml version="1.0" encoding="UTF-8"?><sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"><sitemap><loc>https://example.com/sitemap-1.xml</loc><lastmod>2026-03-04</lastmod></sitemap><sitemap><loc>https://example.com/sitemap-2.xml</loc></sitemap></sitemapindex>'
+* ```
+*
+* @since 0.1.0
+* @category rendering
+*/
+const renderSitemapIndex = (base, sitemaps) => [
+	`<?xml version="1.0" encoding="UTF-8"?><sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">`,
+	...Arr.map(Arr.fromIterable(sitemaps), (sitemap) => {
+		return `<sitemap><loc>${new URL(sitemap.path, base).toString()}</loc>${sitemap.lastmod === void 0 ? "" : `<lastmod>${sitemap.lastmod}</lastmod>`}</sitemap>`;
+	}),
+	`</sitemapindex>`
+].join("");
+/**
+* The item bound for a change-discovery feed: "latest changes", not a
+* complete listing (DISC-010).
+*
+* @since 0.1.0
+* @category constants
+*/
+const FEED_ITEM_LIMIT = 50;
+/**
+* Serialises feed entries into a JSON Feed 1.1 document. Pure. Item `id`
+* and `url` are the canonical absolute URL on `options.base`, never the
+* request origin (CANON-001); `title` / `summary` are omitted, never
+* `null`-valued keys, when absent; entry order is preserved (the caller is
+* responsible for newest-first).
+*
+* @example
+* ```ts
+* import { buildJsonFeed } from "@thomasfosterau/effect-sitemap"
+*
+* const feed = buildJsonFeed(
+*   { base: "https://example.com", title: "Example — Latest changes", description: "The 50 most recent changes." },
+*   [{ path: "/posts/1", publishedAt: "2026-01-01T00:00:00.000Z", updatedAt: "2026-02-01T00:00:00.000Z", title: "Hello", summary: null }],
+* )
+* feed.items[0]?.url // "https://example.com/posts/1"
+* "summary" in (feed.items[0] ?? {}) // false
+* ```
+*
+* @since 0.1.0
+* @category feed
+*/
+const buildJsonFeed = (options, entries) => ({
+	version: "https://jsonfeed.org/version/1.1",
+	title: options.title,
+	home_page_url: new URL(options.homePath ?? "/", options.base).toString(),
+	feed_url: new URL(options.feedPath ?? "/feed.json", options.base).toString(),
+	description: options.description,
+	items: Arr.map(entries, (entry) => feedItem(options.base, entry))
+});
+/** One item; `title` / `summary` are added only when the entry has them. */
+const feedItem = (base, entry) => {
+	const url = new URL(entry.path, base).toString();
+	const item = {
+		id: url,
+		url,
+		date_published: entry.publishedAt,
+		date_modified: entry.updatedAt
+	};
+	if (entry.title !== null && entry.title !== void 0) item.title = entry.title;
+	if (entry.summary !== null && entry.summary !== void 0) item.summary = entry.summary;
+	return item;
+};
+/**
+* The `Content-Type` a JSON Feed is served with.
+*
+* @since 0.1.0
+* @category constants
+*/
+const JSON_FEED_CONTENT_TYPE = "application/feed+json";
+/**
+* A JSON Feed as an `HttpServerResponse`: 2-space pretty-printed (a
+* hand-readable discovery document; changing the indent changes the bytes on
+* the wire and in every cached copy), `application/feed+json`,
+* {@link LOW_CHURN_CACHE_CONTROL} and, when given, the `Cache-Tag`.
+*
+* @example
+* ```ts
+* import * as HttpServerResponse from "effect/http/HttpServerResponse"
+* import { buildJsonFeed, FEED_CACHE_TAG, jsonFeedResponse } from "@thomasfosterau/effect-sitemap"
+*
+* const feed = buildJsonFeed({ base: "https://example.com", title: "t", description: "d" }, [])
+* const response = jsonFeedResponse(feed, { cacheTag: FEED_CACHE_TAG })
+* response.headers["content-type"] // "application/feed+json"
+* const text = await HttpServerResponse.toWeb(response).text()
+* text.startsWith("{\n  \"version\"") // true
+* ```
+*
+* @since 0.1.0
+* @category feed
+*/
+const jsonFeedResponse = (feed, options = {}) => HttpServerResponse.text(JSON.stringify(feed, null, 2), {
+	contentType: JSON_FEED_CONTENT_TYPE,
+	headers: documentHeaders(options)
+});
+/**
+* The `Cache-Tag` on every `feed.json` response.
+*
+* @since 0.1.0
+* @category constants
+*/
+const FEED_CACHE_TAG = "feed";
+/**
+* The `Cache-Tag` on every `sitemap.xml` response.
+*
+* @since 0.1.0
+* @category constants
+*/
+const SITEMAP_CACHE_TAG = "sitemap";
+/**
+* Builds a `purgeTagsForResourceType`: the tags a mutation to one resource
+* of `type` may have staled — both aggregate documents when the type can
+* appear in them, nothing otherwise. Deliberately decided from the type
+* alone, with no per-request visibility check: a write to an always-private
+* resource of an eligible type still purges — a wasted purge, not a missed
+* one. `eligibleTypes` are the resource-type segments the documents
+* enumerate against (the values of the application's route-segment map).
+*
+* @example
+* ```ts
+* import { FEED_CACHE_TAG, makePurgeTagsForResourceType, SITEMAP_CACHE_TAG } from "@thomasfosterau/effect-sitemap"
+*
+* const purgeTagsForResourceType = makePurgeTagsForResourceType(["posts", "people"])
+* purgeTagsForResourceType("posts") // [SITEMAP_CACHE_TAG, FEED_CACHE_TAG]
+* purgeTagsForResourceType("comments") // []
+* ```
+*
+* @since 0.1.0
+* @category purging
+*/
+const makePurgeTagsForResourceType = (eligibleTypes, tags = [SITEMAP_CACHE_TAG, FEED_CACHE_TAG]) => {
+	const eligible = HashSet.fromIterable(eligibleTypes);
+	return (type) => HashSet.has(eligible, type) ? tags : [];
+};
+/**
+* Purges the given `Cache-Tag`s from THIS Worker's Workers Cache (a
+* `purge({ tags })` purges only the calling Worker's own cache). A no-op
+* for an empty tag list or an absent `ctx.cache`; a logged, never failing,
+* outcome otherwise — the purge call rejecting, or *resolving* with
+* `success: false` (a Cloudflare-side failure resolves rather than rejects).
+* This is the purge half of PERF-CACHE-002: a mutation purges by
+* `Cache-Tag` rather than waiting out the TTL. A dropped purge must never
+* surface on the mutation that triggered it: the surface serves stale
+* content until its own `s-maxage` elapses, the accepted failure mode.
+*
+* @example
+* ```ts
+* import * as Effect from "effect/Effect"
+* import { purgeCacheTags } from "@thomasfosterau/effect-sitemap"
+*
+* const purged: Array<ReadonlyArray<string>> = []
+* const ctx = { cache: { purge: async ({ tags }: { tags: Array<string> }) => { purged.push(tags); return { success: true, errors: [] } } } }
+* await Effect.runPromise(purgeCacheTags(ctx, ["sitemap", "feed"]))
+* await Effect.runPromise(purgeCacheTags(undefined, ["sitemap"])) // no cache: no-op
+* purged // [["sitemap", "feed"]]
+* ```
+*
+* @since 0.1.0
+* @category purging
+*/
+const purgeCacheTags = (ctx, tags) => {
+	if (Arr.isReadonlyArrayEmpty(tags)) return Effect.void;
+	const cache = ctx?.cache;
+	if (cache === void 0) return Effect.void;
+	return Effect.tryPromise({
+		try: () => cache.purge({ tags: [...tags] }),
+		catch: (cause) => describeError(cause)
+	}).pipe(Effect.flatMap((result) => result.success ? Effect.void : logErrorEvent("cache-purge.rejected", {
+		tags,
+		errors: result.errors
+	})), Effect.catch((cause) => logErrorEvent("cache-purge.failed", {
+		tags,
+		cause
+	})));
+};
+/**
+* {@link purgeCacheTags} as a `Promise`, for the plain-JS seam a front
+* door hands to `ctx.waitUntil` after the response has gone out.
+*
+* @example
+* ```ts
+* import { purgeCacheTagsPromise } from "@thomasfosterau/effect-sitemap"
+*
+* await purgeCacheTagsPromise(undefined, ["sitemap"]) // resolves; nothing to purge against
+* ```
+*
+* @since 0.1.0
+* @category purging
+*/
+const purgeCacheTagsPromise = (ctx, tags) => Effect.runPromise(purgeCacheTags(ctx, tags));
+//#endregion
+export { FEED_CACHE_TAG, FEED_ITEM_LIMIT, JSON_FEED_CONTENT_TYPE, LOW_CHURN_CACHE_CONTROL, SITEMAP_CACHE_TAG, SITEMAP_MAX_URLS, URLSET_CLOSE, URLSET_OPEN, buildJsonFeed, chunkSitemap, escapeXml, jsonFeedResponse, lastmodOf, makePurgeTagsForResourceType, purgeCacheTags, purgeCacheTagsPromise, renderSitemap, renderSitemapIndex, renderUrl, sitemapResponse, sitemapStream };

package/package.json

@@ -1,6 +1,54 @@
 {
+  "$schema": "https://www.schemastore.org/package",
   "name": "@thomasfosterau/effect-sitemap",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Sitemap, sitemap index and JSON Feed 1.1 builders for Effect web applications (rendered or streamed), the low-churn edge cache policy they share, and the Cache-Tag purge-on-mutation seam.",
+  "keywords": [
+    "effect",
+    "sitemap",
+    "sitemap-index"
+  ],
+  "homepage": "https://github.com/thomasfosterau/effect-web#readme",
+  "bugs": {
+    "url": "https://github.com/thomasfosterau/effect-web/issues"
+  },
+  "license": "MIT",
+  "author": "Thomas Foster <me@thomasfoster.au>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thomasfosterau/effect-web.git",
+    "directory": "packages/sitemap"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@thomasfosterau/effect-web": "^0.1.0"
+  },
+  "devDependencies": {
+    "@effect/language-service": "^0.87.4",
+    "@types/node": "^26.6.5",
+    "@vitest/coverage-istanbul": "4.1.11",
+    "effect": "4.0.3"
+  },
+  "peerDependencies": {
+    "effect": ">=4.0.0-rc.118"
+  },
+  "engines": {
+    "node": ">=22"
+  }
 }