@jasonshimmy/vite-plugin-cer-app 0.23.2 → 0.25.0

package/docs/use-fetch.md

@@ -1,183 +0,0 @@
-# useFetch
-
-`useFetch` is an isomorphic data-fetching composable. It works differently depending on where it is called:
-
-- **Inside a `component()` render function** — returns reactive `data`, `pending`, and `error` refs that update the component automatically when the request settles.
-- **Inside a `loader` or other async server context** — returns a thenable result you can `await` directly to block rendering until data is ready.
-
----
-
-## Basic usage
-
-```ts
-// app/pages/posts.ts
-component('page-posts', () => {
-  const { data: posts, pending, error } = useFetch<Post[]>('/api/posts')
-
-  return html`
-    ${pending.value ? html`<p>Loading…</p>` : ''}
-    ${error.value ? html`<p>Error: ${error.value.message}</p>` : ''}
-    <ul>
-      ${posts.value?.map(p => html`<li>${p.title}</li>`)}
-    </ul>
-  `
-})
-```
-
-The fetch fires automatically when the component mounts (`useOnConnected`). `data`, `pending`, and `error` are reactive — the component re-renders whenever any of them change.
-
----
-
-## Inside a loader
-
-```ts
-// app/pages/posts.ts
-export const loader = async () => {
-  const { data: posts } = await useFetch<Post[]>('/api/posts')
-  return { posts }
-}
-```
-
-When called outside a component context (e.g. in a `loader` or server middleware), `useFetch` returns a thenable `UseFetchResult`. Awaiting it blocks the loader until the fetch completes — the response is serialised into `window.__CER_DATA__` for client hydration.
-
----
-
-## Options
-
-```ts
-useFetch<T>(url: string | (() => string), options?)
-```
-
-The `url` argument can be a static string or a factory function that returns a string. Pass a factory when the URL depends on reactive state — the request will re-issue whenever the function returns a different value.
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `key` | `string` | URL string | Unique cache key for this request. On the server, requests with the same key within one SSR pass are de-duplicated. On the client, matching server-fetched data is consumed once for hydration. |
-| `lazy` | `boolean` | `false` | Skip the server fetch; only fetch on the client. In component context, also skips the auto-fetch on mount — call `refresh()` manually. |
-| `server` | `boolean` | `true` | Equivalent to `lazy: true`. Set `server: false` to skip SSR. |
-| `default` | `() => T` | `() => null` | Factory that returns the initial value before the fetch completes. |
-| `transform` | `(data: unknown) => T` | — | Transform the raw JSON response before storing it. Applied after `pick`. |
-| `pick` | `string[]` | — | Pick a subset of keys from an object response. Applied before `transform`. |
-| `method` | `string` | `'GET'` | HTTP method. |
-| `body` | `unknown` | — | Request body for POST / PUT / PATCH. Serialised to JSON; sets `Content-Type: application/json` automatically. |
-| `headers` | `Record<string, string>` | — | Additional request headers. |
-| `query` | `Record<string, string>` | — | Query parameters appended to the URL via `URLSearchParams`. Included in the default cache key. |
-
----
-
-## Reactive return (component context)
-
-When called inside a `component()` render function, `useFetch` returns a `UseFetchReactiveReturn`:
-
-| Field | Type | Description |
-|---|---|---|
-| `data` | `ReactiveState<T \| null>` | Reactive result. Access via `.data.value`. |
-| `pending` | `ReactiveState<boolean>` | `true` while the request is in-flight. |
-| `error` | `ReactiveState<Error \| null>` | Set when the request fails; `null` on success. |
-| `refresh()` | `() => Promise<void>` | Re-issues the fetch and updates all three refs. |
-
----
-
-## Awaitable return (loader / server context)
-
-When called outside a component, `useFetch` returns a `UseFetchResult` — a `UseFetchReturn` plus a `.then()` method:
-
-| Field | Type | Description |
-|---|---|---|
-| `data` | `T \| null` | Fetch result (available after awaiting). |
-| `pending` | `boolean` | `false` after awaiting. |
-| `error` | `Error \| null` | Set if the fetch failed. |
-| `refresh()` | `() => Promise<UseFetchReturn<T>>` | Re-issues the fetch. |
-
----
-
-## Lazy fetch — manual trigger
-
-Skip the automatic fetch and call `refresh()` manually:
-
-```ts
-component('page-search', () => {
-  const query = ref('')
-
-  const { data: results, pending, refresh } = useFetch<Result[]>(
-    () => `/api/search?q=${encodeURIComponent(query.value)}`,
-    { lazy: true }
-  )
-
-  async function search() {
-    await refresh()
-  }
-
-  return html`
-    <input @input="${(e: InputEvent) => { query.value = (e.target as HTMLInputElement).value }}" />
-    <button @click="${search}">Search</button>
-    ${pending.value ? html`<p>Searching…</p>` : ''}
-    <ul>${results.value?.map(r => html`<li>${r.title}</li>`)}</ul>
-  `
-})
-```
-
----
-
-## POST / mutation
-
-```ts
-component('page-new-post', () => {
-  const { data, pending, error, refresh: submit } = useFetch<Post>('/api/posts', {
-    lazy: true,
-    method: 'POST',
-    body: { title: 'New Post', content: '...' },
-  })
-
-  return html`
-    <button @click="${submit}" :disabled="${pending.value}">
-      ${pending.value ? 'Saving…' : 'Save'}
-    </button>
-    ${error.value ? html`<p>Error: ${error.value.message}</p>` : ''}
-    ${data.value ? html`<p>Created: ${data.value.title}</p>` : ''}
-  `
-})
-```
-
----
-
-## Transforming responses
-
-Use `pick` to extract specific keys, or `transform` for arbitrary reshaping:
-
-```ts
-const { data: name } = useFetch<string>('/api/me', {
-  pick: ['name'],
-  transform: (d) => (d as { name: string }).name,
-})
-```
-
----
-
-## Server-side de-duplication
-
-On the server, multiple `useFetch` calls with the same `key` within a single SSR request are de-duplicated — only the first network request fires. Results are stored in a per-request cache keyed by `key` (which defaults to the full URL including query params).
-
-```ts
-export const loader = async () => {
-  // Only one network request is made even if useFetch('/api/user') appears elsewhere
-  const { data: user } = await useFetch('/api/user', { key: 'current-user' })
-  return { user }
-}
-```
-
----
-
-## TypeScript
-
-```ts
-import { useFetch } from '@jasonshimmy/vite-plugin-cer-app/composables'
-import type {
-  UseFetchOptions,
-  UseFetchReactiveReturn,
-  UseFetchReturn,
-  UseFetchResult,
-} from '@jasonshimmy/vite-plugin-cer-app/composables'
-```
-
-`useFetch` is auto-imported in `app/pages/`, `app/layouts/`, `app/components/`, `app/middleware/`, and `app/composables/`. No import statement is needed in those directories.

package/e2e/cypress/e2e/api.cy.ts

@@ -1,123 +0,0 @@
-/**
- * Server API route tests.
- *
- * Only run in SSR mode — SSG and SPA don't have live API endpoints.
- */
-
-const mode = Cypress.env('mode') as 'spa' | 'ssr' | 'ssg'
-
-if (mode !== 'ssr') {
-  describe('Server API routes', () => {
-    it('skipped — only tested in SSR mode', () => {
-      cy.log(`API tests skipped in ${mode} mode`)
-    })
-  })
-} else {
-  describe('Server API routes (SSR mode)', () => {
-    context('GET /api/health', () => {
-      it('returns 200 with status ok', () => {
-        cy.request('/api/health').then((response) => {
-          expect(response.status).to.eq(200)
-          expect(response.body.status).to.eq('ok')
-          expect(response.body.service).to.eq('kitchen-sink')
-        })
-      })
-    })
-
-    context('GET /api/posts', () => {
-      it('returns 200 with array of posts', () => {
-        cy.request('/api/posts').then((response) => {
-          expect(response.status).to.eq(200)
-          expect(response.body).to.be.an('array')
-          expect(response.body.length).to.be.greaterThan(0)
-        })
-      })
-
-      it('first post has slug, title, excerpt, body', () => {
-        cy.request('/api/posts').then((response) => {
-          const post = response.body[0]
-          expect(post).to.have.property('slug')
-          expect(post).to.have.property('title')
-          expect(post).to.have.property('excerpt')
-          expect(post).to.have.property('body')
-        })
-      })
-
-      it('contains first-post and second-post', () => {
-        cy.request('/api/posts').then((response) => {
-          const slugs = response.body.map((p: any) => p.slug)
-          expect(slugs).to.include('first-post')
-          expect(slugs).to.include('second-post')
-        })
-      })
-    })
-
-    context('GET /api/echo — req.query parsing', () => {
-      it('returns parsed query parameters', () => {
-        cy.request('/api/echo?page=2&limit=10').then((response) => {
-          expect(response.status).to.eq(200)
-          expect(response.body.query).to.deep.eq({ page: '2', limit: '10' })
-        })
-      })
-
-      it('returns empty object when no query string is present', () => {
-        cy.request('/api/echo').then((response) => {
-          expect(response.status).to.eq(200)
-          expect(response.body.query).to.deep.eq({})
-        })
-      })
-    })
-
-    context('POST /api/echo — req.body parsing', () => {
-      it('echoes a JSON body back in the response', () => {
-        cy.request({
-          method: 'POST',
-          url: '/api/echo',
-          body: { message: 'hello', count: 42 },
-          headers: { 'Content-Type': 'application/json' },
-        }).then((response) => {
-          expect(response.status).to.eq(200)
-          expect(response.body.echo).to.deep.eq({ message: 'hello', count: 42 })
-        })
-      })
-
-      it('handles an empty JSON body', () => {
-        cy.request({
-          method: 'POST',
-          url: '/api/echo',
-          body: {},
-          headers: { 'Content-Type': 'application/json' },
-        }).then((response) => {
-          expect(response.status).to.eq(200)
-          expect(response.body.echo).to.deep.eq({})
-        })
-      })
-    })
-
-    context('GET /api/posts/:slug', () => {
-      it('returns the correct post for first-post', () => {
-        cy.request('/api/posts/first-post').then((response) => {
-          expect(response.status).to.eq(200)
-          expect(response.body.slug).to.eq('first-post')
-          expect(response.body.title).to.eq('First Post')
-          expect(response.body.body).to.include('First post body content')
-        })
-      })
-
-      it('returns the correct post for second-post', () => {
-        cy.request('/api/posts/second-post').then((response) => {
-          expect(response.status).to.eq(200)
-          expect(response.body.slug).to.eq('second-post')
-          expect(response.body.title).to.eq('Second Post')
-        })
-      })
-
-      it('returns 404 for unknown slug', () => {
-        cy.request({ url: '/api/posts/not-a-post', failOnStatusCode: false }).then((response) => {
-          expect(response.status).to.eq(404)
-          expect(response.body).to.have.property('error')
-        })
-      })
-    })
-  })
-}

package/e2e/cypress/e2e/async-component.cy.ts

@@ -1,27 +0,0 @@
-/**
- * P2-4: defineAsyncComponent.
- *
- * Tests that components defined with defineAsyncComponent:
- * - Show a loading placeholder while the loader is pending
- * - Show the resolved component after the loader settles
- * - Show the error placeholder when the loader fails
- */
-
-describe('defineAsyncComponent (P2-4)', () => {
-  it('renders the resolved async component content', () => {
-    cy.visit('/async-component-test')
-    // After the loader resolves, the component content should be present
-    cy.get('[data-cy=async-component-content]', { timeout: 5000 }).should('exist')
-  })
-
-  it('shows loading placeholder while the async component is loading', () => {
-    cy.visit('/async-component-test')
-    // The loading state may be very brief — just verify no crash occurs
-    cy.get('body').should('exist')
-  })
-
-  it('shows error placeholder when the async component loader fails', () => {
-    cy.visit('/async-component-error-test')
-    cy.get('[data-cy=async-component-error]', { timeout: 5000 }).should('exist')
-  })
-})

package/e2e/cypress/e2e/component-splitting.cy.ts

@@ -1,50 +0,0 @@
-/**
- * Component code-splitting tests.
- *
- * Verifies that per-page component imports (injected by cerComponentImports) work
- * correctly: components used on a page render; components NOT used on a page do
- * not cause errors.
- *
- * The /about page deliberately uses no <ks-badge> element.
- * The home page (/) uses <ks-badge>.
- */
-
-describe('Component code splitting', () => {
-  context('Home page — uses <ks-badge>', () => {
-    it('renders the ks-badge component via the injected import', () => {
-      cy.visit('/')
-      // Verify the component registered and its shadow DOM rendered.
-      // The span[data-cy=ks-badge] lives inside the component's shadow root;
-      // its existence confirms cerComponentImports injected the import correctly.
-      cy.get('[data-cy=ks-badge]').should('exist')
-    })
-
-    it('page loads without errors', () => {
-      cy.visit('/')
-      cy.on('uncaught:exception', () => false)
-      cy.get('[data-cy=home-heading]').should('exist')
-    })
-  })
-
-  context('About page — does NOT use <ks-badge>', () => {
-    it('renders correctly without loading ks-badge', () => {
-      cy.visit('/about')
-      cy.get('[data-cy=about-heading]').should('contain', 'About')
-    })
-
-    it('page loads without errors even though ks-badge is absent', () => {
-      cy.visit('/about')
-      cy.on('uncaught:exception', () => false)
-      cy.get('[data-cy=about-description]').should('exist')
-    })
-  })
-
-  context('Navigation — component available after routing to page that uses it', () => {
-    it('navigates from /about to / and ks-badge renders', () => {
-      cy.visit('/about')
-      cy.get('[data-cy=about-heading]').should('exist')
-      cy.visit('/')
-      cy.get('[data-cy=ks-badge]').should('exist')
-    })
-  })
-})