@webqit/webflo 0.11.61 → 0.20.2-next.0

package/site/api/webflo-routing/handler/next.md

@@ -0,0 +1,54 @@
+# Handler::`next()`
+
+Delegate to next step or make inbound calls.
+
+## Signature
+
+```js
+await next();
+// url can be string or URL
+// url can be relative when string
+// init can be Request instance or Request init
+await next(url, init?);
+await next(request);
+await next({ redirect?: url = next.pathname, with?: init });
+```
+
+## Arguments
+
+| Argument          | Tyoe          | Default       | Description                   |
+| :---------------- | :------------ | :------------ | :---------------------------- |
+
+## Properties
+
+| Property        | Type            | Description                                                       |
+| :-------------- | :-------------- | ----------------------------------------------------------------- |
+| `next.stepname` | `string`        | The name of the next segment in the URL.                          |
+| `next.pathname` | `string`        | The full path _beyond_ the the active step.                       |
+
+
+::: info See Also
+[`this`](../handler#the-this-context)
+:::
+
+## Return Value
+
+Depends on the step handler's return value. If:
+
+| Condition                                  | Return type                   |
+| :----------------------------------------- | :---------------------------- |
+| Step handler is generator function         | `Generator` object            |
+| Step handler is Quantum function           | `State` object                |
+| Step handler uses `event.respondWith()`    | `LiveResponse`                |
+| Step handler returns `LiveResponse`        | `LiveResponse`                |
+| Step handler returns `Response`            | `Response`                    |
+| Step handler returns any other value.      | That value                    |
+
+## Differences from `fetch()`:
+
+intro
+
+| `next()`                                   | `fetch()`                                |
+| :----------------------------------------- | :--------------------------------------- |
+| Makes only inbound calls.                  | Can make both inbound or outbound calls. |
+| Inherits current request.                  |                                          |

package/site/api/webflo-routing/handler.md

@@ -0,0 +1,119 @@
+# Handler API
+
+Handlers are the entry point for all requests in Webflo. This page documents the formal contract for handler functions.
+
+## Signature
+
+```js
+export default async function(event, next, fetch) { /* ... */ }
+```
+
+## Naming
+
+A route may provide named exports to map specific HTTP requests to specific handlers:
+
+```js
+export async function GET(event, next, fetch) { /* ... */ }
+export async function POST(event, next, fetch) { /* ... */ }
+// PUT, PATCH, DELETE, OPTIONS, HEAD are also supported
+```
+
+| Name      | Description                                  |
+| :-------- | :------------------------------------------- |
+| `GET`     | Handle HTTP GET requests                      |
+| `POST`    | Handle HTTP POST requests                     |
+| `PUT`     | Handle HTTP PUT requests                      |
+| `PATCH`   | Handle HTTP PATCH requests                    |
+| `DELETE`  | Handle HTTP DELETE requests                   |
+| `OPTIONS` | Handle HTTP OPTIONS requests                  |
+| `HEAD`    | Handle HTTP HEAD requests                     |
+
+If a named export is not provided for an incoming method, Webflo falls back to the `default` export, if present.
+
+## Parameters
+
+| Parameter | Type                                                | Description                                              |
+| :-------- | :-------------------------------------------------- | :------------------------------------------------------- |
+| `event`   | [`HttpEvent`](/api/webflo-routing/HttpEvent)        | Current HTTP event.                                      |
+| `next`    | [`next`](/api/webflo-routing/handler/next)          | Control delegation function.                             |
+| `fetch`   | [`fetch`](/api/webflo-routing/handler/fetch)        | Context-aware fetch API for inbound and outbound calls.  |
+
+## The `this` Context
+
+Contextual properties are available on the `this` context:
+
+| Property        | Type       | Description                                                       |
+| :-------------- | :--------- | :---------------------------------------------------------------- |
+| `this.stepname` | `string`   | The current directory segment being handled.                      |
+| `this.pathname` | `string`   | The current URL pathname up to the active step.                   |
+| `this.filename` | `string`   | The filename of the executing handler (server-side only).         |
+
+::: info See also
+[`next`](/api/webflo-routing/handler/next#properties)
+:::
+
+## Return Types
+
+Handlers can return one of the following:
+
+| Type            | Description |
+| :-------------- | :---------- |
+| Plain value     | A JSON-serializable value or plain object used as the page's data binding. |
+| `Response`      | A standard Web Fetch API `Response`. |
+| `LiveResponse`  | A streaming/live response that can emit multiple payloads over time. |
+
+## Return Styles
+
+You can deliver values in two ways:
+
+| Style                  | When to use |
+| :--------------------- | :---------- |
+| `return`               | Return a single value (`object`, `Response`, or `LiveResponse`). |
+| `event.respondWith()`  | Emit one or more responses, including progressive/streamed updates. See [/docs/concepts/realtime](/docs/concepts/realtime). |
+
+### `event.respondWith()` forms
+
+- `event.respondWith(data)` — immediately deliver `data`.
+- `event.respondWith(data, { done: false })` — deliver `data` and keep the channel open for more.
+- `event.respondWith(data, (proxy) => { /* write to proxy */ })` — low-level streaming; complete when callback resolves or another `respondWith` is called.
+
+## Generator and Live Functions
+
+Handlers may be expressed as generators or "live" functions to naturally produce multiple values over time.
+
+- Generator: `export function* GET(event) { yield {...}; return {...}; }`
+- Live function: `export live function GET(event) { return {...} }`  
+See [/docs/concepts/realtime](/docs/concepts/realtime) for details.
+
+## Lifecycle
+
+- Streams, generators, and live functions end when `HttpEvent.signal` aborts.
+- The root `HttpEvent` is aborted when all handlers in the subtree complete, the request is aborted, or realtime closes.
+
+## Examples
+
+Return plain data (rendered into templates via `document.bindings.data`):
+
+```js
+export async function GET(event) {
+  return { title: 'Hello', greeting: 'Hello World!' };
+}
+```
+
+Return a `Response`:
+
+```js
+export async function GET() {
+  return Response.json({ ok: true });
+}
+```
+
+Progressively stream values:
+
+```js
+export async function GET(event) {
+  event.respondWith({ step: 1 }, { done: false });
+  await new Promise(r => setTimeout(r, 200));
+  event.respondWith({ step: 2 }); // done by default
+}
+```

package/site/api.md

@@ -0,0 +1,26 @@
+# API Reference
+
+Browse the API by area.
+
+## Routing
+- [Handler](/api/webflo-routing/handler)
+- [HttpEvent](/api/webflo-routing/HttpEvent)
+- [next](/api/webflo-routing/handler/next)
+- [fetch (handler)](/api/webflo-routing/handler/fetch)
+- [HttpState](/api/webflo-routing/HttpState)
+- [HttpSession](/api/webflo-routing/HttpSession)
+- [HttpUser](/api/webflo-routing/HttpUser)
+- [HttpCookies](/api/webflo-routing/HttpCookies)
+
+## Fetch
+- [fetch](/api/webflo-fetch/fetch)
+- [Request](/api/webflo-fetch/Request)
+- [Response](/api/webflo-fetch/Response)
+- [LiveResponse](/api/webflo-fetch/LiveResponse)
+- [FormData](/api/webflo-fetch/FormData)
+- [Headers](/api/webflo-fetch/Headers)
+
+## Messaging
+- [MessageChannel](/api/webflo-messaging/MessageChannel)
+- [MessagePort](/api/webflo-messaging/MessagePort)
+- [MessageEvent](/api/webflo-messaging/MessageEvent)

package/site/contributing.md

@@ -0,0 +1,16 @@
+# Contributing
+
+Thanks for your interest!
+
+## Development
+- Clone the repo
+- Install dependencies
+- Run tests and the docs site
+
+## Issues and PRs
+- Open an issue for discussion first where helpful
+- Keep PRs focused; include tests where possible
+
+Links:
+- GitHub: https://github.com/webqit/webflo
+- Issues: https://github.com/webqit/webflo/issues

package/site/docs/advanced/lifecycles.md

@@ -0,0 +1,20 @@
+# Webflo Lifecycles
+
+A place to see all the various lifecycles
+
+
++ HttpEvent.signal aborts when
+    + parent event's signal aborts
+    + request's signal aborts
+    + HttpEvent.abort() is called
+    + handler returns, plus all handlers in subtree return; i.e. all handlers complete their lifecycle
++ root HttpEvent is aborted on any of the above or when Realtime closes
+
++ Realtime closes when
+    + is closed from client
+    + Httpevent.client's `navigation` event fires and is not default-prevented
+    + root event completes its lifecycle
+
++ Quantum state and Generators auto end when
+    + HttpEvent.signal aborts
+

package/site/docs/advanced/routing.md

@@ -0,0 +1 @@
+# Advanced Routing

package/site/docs/advanced.md

@@ -0,0 +1,9 @@
+# Advanced Concepts
+
+Talk about:
++ HTTP State
+    + Cookies
+    + Session
+    + User
++ Redirects
++ Lifecycles