{"protocol":"clank-doc/1","frameworkVersion":"0.24.0","slug":"runnable-examples","title":"Runnable documentation examples","description":"npm run docs:examples compiles and executes every explicitly marked clank run code fence under docs/ . The full local check runs the same gate against the built package. Each example starts a fresh Node process in a temporary directory, wit","group":{"id":"project","title":"Project"},"url":"https://docs.clank.run/docs/runnable-examples","source":"docs/runnable-examples.md","headings":["Schema validation","Reactive state","Atomic database changes","Localized values","Calendar recurrence","Delivery controls","Compiler contract"],"tableOfContents":[{"id":"schema-validation","title":"Schema validation","level":2},{"id":"atomic-database-changes","title":"Atomic database changes","level":2},{"id":"calendar-recurrence","title":"Calendar recurrence","level":2},{"id":"compiler-contract","title":"Compiler contract","level":2}],"markdown":"# Runnable documentation examples\n\n`npm run docs:examples` compiles and executes every explicitly marked `clank-run` code fence under `docs/`. The full local check runs the same gate against the built package. Each example starts a fresh Node process in a temporary directory, with a ten-second timeout and bounded output. This is a verification runner for trusted repository documentation, not a sandbox for third-party code.\n\nUse a unique lowercase ID within each guide and import public package entry points. Assertions make the expected behavior executable. Ordinary illustrative snippets without the marker are not executed.\n\n## Schema validation\n\n```ts clank-run=schema-validation\nimport assert from \"node:assert/strict\";\nimport { s } from \"@clank.run/framework\";\nconst name = s.string({ min: 1, max: 20 });\nassert.equal(name.parse(\"Ada\"), \"Ada\");\nassert.equal(name.safeParse(42).success, false);\n```\n\n## Reactive state\n\n```ts clank-run=reactive-state\nimport assert from \"node:assert/strict\";\nimport { signal, computed } from \"@clank.run/framework\";\nconst count = signal(2);\nconst doubled = computed(() => count.value * 2);\nassert.equal(doubled.value, 4);\ncount.value = 3;\nassert.equal(doubled.value, 6);\n```\n\n## Atomic database changes\n\n```ts clank-run=atomic-database\nimport assert from \"node:assert/strict\";\nimport { defineDatabase, defineTable, openSQLite, s } from \"@clank.run/framework\";\nconst schema = defineDatabase({ notes: defineTable({ title: s.string() }) });\nconst db = await openSQLite(schema, { path: \":memory:\" });\ntry {\n  assert.throws(() => db.transaction(tx => { tx.table(\"notes\").insert({ title: \"Uncommitted\" }); throw new Error(\"abort\"); }));\n  assert.equal(db.read(tx => tx.table(\"notes\").collect()).length, 0);\n} finally { db.close(); }\n```\n\n## Localized values\n\n```ts clank-run=localized-values\nimport assert from \"node:assert/strict\";\nimport { createI18n, defineMessages } from \"@clank.run/framework/i18n\";\nconst i18n = createI18n({ defaultLocale: \"en\", messages: defineMessages({ greeting: \"Hello, {name}\" }) });\nassert.equal(i18n.t(\"greeting\", { name: \"Ada\" }), \"Hello, Ada\");\n```\n\n## Calendar recurrence\n\n```ts clank-run=calendar-recurrence\nimport assert from \"node:assert/strict\";\nimport { previewSchedule } from \"@clank.run/framework/schedules\";\nconst schedule = previewSchedule({ frequency: \"daily\", startDate: \"2026-03-07\", time: \"02:30\", timeZone: \"America/New_York\" }, { after: Date.parse(\"2026-03-07T00:00:00Z\"), limit: 2 });\nassert.equal(schedule.occurrences[1].local, \"2026-03-09T02:30\");\nassert.equal(schedule.skipped[0].reason, \"daylight-saving-gap\");\n```\n\n## Delivery controls\n\n```ts clank-run=quiet-hours\nimport assert from \"node:assert/strict\";\nimport { nextNotificationDelivery } from \"@clank.run/framework/notifications\";\nconst at = nextNotificationDelivery({ timeZone: \"UTC\", quietHours: { start: \"22:00\", end: \"08:00\" } }, Date.parse(\"2026-10-03T23:00:00Z\"));\nassert.equal(new Date(at).toISOString(), \"2026-10-04T08:00:00.000Z\");\n```\n\n## Compiler contract\n\n```ts clank-run=compiler-contract\nimport assert from \"node:assert/strict\";\nimport { compile } from \"@clank.run/framework/compiler\";\nconst code = compile(\"export const answer: number = 42;\", { filename: \"answer.ts\", sourceMap: false });\nconst result = await import(`data:text/javascript,${encodeURIComponent(code)}`);\nassert.equal(result.answer, 42);\n```\n"}