create-foldkit-app 0.37.0 → 0.38.0

package/README.md

@@ -40,6 +40,7 @@ The starter examples apply to `spa` rendering. The `ssg` and `ssr` modes scaffol
 | `job-application`        | Multi-step form with async validation, file uploads, and per-step error indicators                     |
 | `weather`                | HTTP requests with async state handling                                                                |
 | `api-cache`              | Query caching in the Model with stale-while-revalidate, request deduplication, and interval refetching |
+| `api-cache-query`        | The API Cache app rewritten with experimental Query.define                                             |
 | `charting`               | Live GitHub and npm telemetry rendered through an ECharts Mount adapter                                |
 | `routing`                | URL routing with parser combinators and route parameters                                               |
 | `upload`                 | Simulated file uploads with cancellable, restartable interruptible Commands                            |

package/dist/examples.js

@@ -9,6 +9,7 @@ export const EXAMPLE_VALUES = [
     'job-application',
     'weather',
     'api-cache',
+    'api-cache-query',
     'charting',
     'routing',
     'route-transitions',
@@ -81,6 +82,11 @@ export const examples = [
         title: 'api-cache',
         description: 'Query caching in the Model with stale-while-revalidate, request deduplication, invalidation, and interval refetching',
     },
+    {
+        value: 'api-cache-query',
+        title: 'api-cache-query',
+        description: 'The API Cache app rewritten with experimental Query.define. Fetching and retained entries live in Query Submodels',
+    },
     {
         value: 'charting',
         title: 'charting',

package/dist/templates/base/FOLDKIT.md

@@ -159,6 +159,8 @@ Messages are verb-first past-tense. Common prefixes: `Clicked*`, `Updated*` (inp
 
 This project ships with `@foldkit/devtools-mcp` pre-wired. When the dev server is running and the app is open in a browser, `foldkit_*` MCP tools let you inspect Model, Message history, and time-travel. Reach for them before adding `console.log` whenever the question is about state or Message flow.
 
+Treat those tools as privileged access to the application. They can return Models, Message payloads, and Command and Mount arguments to the agent. Keep credentials and private data out of browser state. Use Effect `Redacted` for sensitive values the browser must temporarily hold, and set `devToolsMcpPort: false` in the Foldkit Vite plugin options when an agent should not inspect the running application.
+
 ## Going Deeper
 
 For Submodels and OutMessage, Subscriptions, Mount / ManagedResource / CustomElement, field validation, routing, accessibility, and the full convention set, read the live Foldkit code in `repos/foldkit/`. The `examples/` directory and the production apps (`packages/typing-game/`, `packages/website/`) are the highest-fidelity references for any specific pattern. The `foldkit-skills` plugin's `generate-program` and `audit-program` skills carry written snapshot guides if you want a structured walkthrough.

package/dist/templates/examples/api-cache-query/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "api-cache-query-example",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@effect/platform-browser": "4.0.0",
+    "@foldkit/ui": "workspace:*",
+    "effect": "4.0.0",
+    "foldkit": "workspace:*"
+  },
+  "devDependencies": {
+    "@foldkit/devtools": "workspace:*",
+    "@foldkit/vite-plugin": "workspace:*",
+    "@tailwindcss/vite": "^4.3.3",
+    "happy-dom": "^20.14.5",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.1",
+    "vitest": "^5.0.2"
+  }
+}

package/dist/templates/examples/api-cache-query/src/data.ts

@@ -0,0 +1,112 @@
+import { Array, Duration, Effect, Option, Random, Schema } from 'effect'
+
+export const Post = Schema.Struct({
+  id: Schema.String,
+  title: Schema.String,
+  excerpt: Schema.String,
+})
+export type Post = typeof Post.Type
+
+export const PostDetail = Schema.Struct({
+  id: Schema.String,
+  title: Schema.String,
+  author: Schema.String,
+  body: Schema.String,
+})
+export type PostDetail = typeof PostDetail.Type
+
+export const Stats = Schema.Struct({
+  activeUsers: Schema.Number,
+  requestsPerSecond: Schema.Number,
+  cacheHitRatePercent: Schema.Number,
+})
+export type Stats = typeof Stats.Type
+
+const SERVER_LATENCY = Duration.millis(700)
+const UNAVAILABLE_POST_ID = 'unavailable-post'
+
+type Article = Readonly<{
+  id: string
+  title: string
+  excerpt: string
+  author: string
+  body: string
+}>
+
+const articles: ReadonlyArray<Article> = [
+  {
+    id: 'model-is-the-cache',
+    title: 'The Model Is the Cache',
+    excerpt: 'Why a single source of truth needs no query client.',
+    author: 'Maya Okafor',
+    body: 'A cache is a place where fetched data lives between requests. In The Elm Architecture that place already exists: the Model. Store each query as a small state machine and every view reads the same truth.',
+  },
+  {
+    id: 'stale-while-revalidate',
+    title: 'Stale-While-Revalidate, Explained',
+    excerpt: 'Show the old data while the new data loads.',
+    author: 'Theo Lindqvist',
+    body: 'Dropping back to a spinner throws away perfectly good data. A Refreshing state carries the previous value while the fetch runs, so the screen never goes blank.',
+  },
+  {
+    id: 'query-keys-are-names',
+    title: 'Query Keys Are Just Names',
+    excerpt: 'A Model field per query replaces stringly-typed keys.',
+    author: 'Priya Raman',
+    body: 'When queries are known statically, the field name is the key. Reach for a HashMap keyed by a domain identifier only when the entries are genuinely dynamic, like these post details.',
+  },
+  {
+    id: 'refresh-is-a-message',
+    title: 'Refresh Is a Message',
+    excerpt: 'Requesting newer data is a fact, not hidden framework policy.',
+    author: 'Jonas Weber',
+    body: 'Dispatch a Message, move the entry to Refreshing, and return the fetch Command. The old value stays available while the request runs, and the whole policy remains visible in update.',
+  },
+]
+
+const posts = [
+  ...Array.map(articles, ({ id, title, excerpt }) =>
+    Post.make({ id, title, excerpt }),
+  ),
+  Post.make({
+    id: UNAVAILABLE_POST_ID,
+    title: 'This Post Is Unavailable',
+    excerpt: 'Open it to see the Failure and Retry states.',
+  }),
+]
+
+const postDetails = Array.map(articles, ({ id, title, author, body }) =>
+  PostDetail.make({ id, title, author, body }),
+)
+
+export const fetchPosts = Effect.gen(function* () {
+  yield* Effect.sleep(SERVER_LATENCY)
+
+  return posts
+})
+
+export const fetchPostDetail = (
+  postId: string,
+): Effect.Effect<PostDetail, string> =>
+  Effect.gen(function* () {
+    yield* Effect.sleep(SERVER_LATENCY)
+
+    return yield* Option.match(
+      Array.findFirst(postDetails, ({ id }) => id === postId),
+      {
+        onNone: () =>
+          Effect.fail('This post is unavailable. You can try again.'),
+        onSome: Effect.succeed,
+      },
+    )
+  })
+
+export const fetchStats = Effect.gen(function* () {
+  yield* Effect.sleep(SERVER_LATENCY)
+
+  const activeUsers = yield* Random.nextIntBetween(80, 140)
+  const requestsPerSecond = yield* Random.nextIntBetween(900, 1600)
+  const cacheHitRatePercent = yield* Random.nextIntBetween(86, 99)
+
+  return Stats.make({ activeUsers, requestsPerSecond, cacheHitRatePercent })
+})

package/dist/templates/examples/api-cache-query/src/entry.ts

@@ -0,0 +1,17 @@
+import { Runtime } from 'foldkit'
+
+import { Message, Model, init, subscriptions, update, view } from './main'
+
+const application = Runtime.makeApplication({
+  Model,
+  init,
+  update,
+  view,
+  subscriptions,
+  container: document.getElementById('root'),
+  devTools: {
+    Message,
+  },
+})
+
+Runtime.run(application)

package/dist/templates/examples/api-cache-query/src/main.fixture.ts

@@ -0,0 +1,136 @@
+import { Option, Result } from 'effect'
+import { modifyFields } from 'foldkit/struct'
+
+import { Tabs } from '@foldkit/ui'
+
+import type { Post, PostDetail, Stats } from './data'
+import { Model, TABS_ID, postQuery, postsQuery, statsQuery } from './main'
+
+export const FETCHED_AT = 1_750_000_000_000
+
+export const fixturePosts: ReadonlyArray<Post> = [
+  {
+    id: 'first-post',
+    title: 'First Post',
+    excerpt: 'The first fixture post.',
+  },
+  {
+    id: 'second-post',
+    title: 'Second Post',
+    excerpt: 'The second fixture post.',
+  },
+]
+
+export const firstPostDetail: PostDetail = {
+  id: 'first-post',
+  title: 'First Post',
+  author: 'Grace Hopper',
+  body: 'The whole body of the first fixture post.',
+}
+
+export const fixtureStats: Stats = {
+  activeUsers: 120,
+  requestsPerSecond: 1234,
+  cacheHitRatePercent: 97,
+}
+
+const loadingPostsQueryModel = postsQuery.revalidateOrLoad(
+  postsQuery.init(),
+).model
+
+export const loadingPostsModel = Model.make({
+  tabs: Tabs.init({ id: TABS_ID }),
+  activeTab: 'Posts',
+  posts: loadingPostsQueryModel,
+  postDetails: postQuery.init(),
+  maybeSelectedPostId: Option.none(),
+  stats: statsQuery.init(),
+})
+
+const loadedPostsQueryModel = postsQuery.update(
+  loadingPostsQueryModel,
+  postsQuery.Message.CompletedFetch({
+    generation: loadingPostsQueryModel.generation,
+    result: Result.succeed({ posts: fixturePosts, fetchedAt: FETCHED_AT }),
+  }),
+).model
+
+export const loadedPostsModel = modifyFields(loadingPostsModel, {
+  posts: () => loadedPostsQueryModel,
+})
+
+const failedPostsQueryModel = postsQuery.update(
+  loadingPostsQueryModel,
+  postsQuery.Message.CompletedFetch({
+    generation: loadingPostsQueryModel.generation,
+    result: Result.fail('The server is down.'),
+  }),
+).model
+
+export const failedPostsModel = modifyFields(loadingPostsModel, {
+  posts: () => failedPostsQueryModel,
+})
+
+const firstPostArgs = { postId: 'first-post' }
+const loadingFirstPostQueryModel = postQuery.loadIfMissing(
+  postQuery.init(),
+  firstPostArgs,
+).model
+const loadedFirstPostQueryModel = postQuery.update(
+  loadingFirstPostQueryModel,
+  postQuery.Message.CompletedFetch({
+    args: firstPostArgs,
+    generation: loadingFirstPostQueryModel.generation,
+    result: Result.succeed({
+      post: firstPostDetail,
+      fetchedAt: FETCHED_AT,
+    }),
+  }),
+).model
+
+export const cachedFirstPostModel = modifyFields(loadedPostsModel, {
+  postDetails: () => loadedFirstPostQueryModel,
+})
+
+const failedFirstPostQueryModel = postQuery.update(
+  loadingFirstPostQueryModel,
+  postQuery.Message.CompletedFetch({
+    args: firstPostArgs,
+    generation: loadingFirstPostQueryModel.generation,
+    result: Result.fail('The connection dropped.'),
+  }),
+).model
+
+export const failedFirstPostModel = modifyFields(loadedPostsModel, {
+  postDetails: () => failedFirstPostQueryModel,
+})
+
+const loadingStatsQueryModel = statsQuery.revalidateOrLoad(
+  statsQuery.init(),
+).model
+
+export const loadingStatsModel = modifyFields(loadedPostsModel, {
+  activeTab: () => 'Stats',
+  stats: () => loadingStatsQueryModel,
+})
+
+const loadedStatsQueryModel = statsQuery.update(
+  loadingStatsQueryModel,
+  statsQuery.Message.CompletedFetch({
+    generation: loadingStatsQueryModel.generation,
+    result: Result.succeed({ stats: fixtureStats, fetchedAt: FETCHED_AT }),
+  }),
+).model
+
+export const loadedStatsModel = modifyFields(loadedPostsModel, {
+  activeTab: () => 'Stats',
+  stats: () => loadedStatsQueryModel,
+})
+
+const refreshingStatsQueryModel = statsQuery.revalidate(
+  loadedStatsQueryModel,
+).model
+
+export const refreshingStatsModel = modifyFields(loadedStatsModel, {
+  stats: () => refreshingStatsQueryModel,
+})