@webqit/webflo 0.11.16 → 0.11.19

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013-present, Yuxi (Evan) You
+
+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

@@ -165,7 +165,7 @@ With [npm available on your terminal](https://docs.npmjs.com/downloading-and-ins
 > System Requirements: Node.js 14.0 or later
 
 ```shell
-$ npm i @webqit/webflo
+npm i @webqit/webflo
 ```
 
 The installation automatically creates a `package.json` file at project root, containing `@webqit/webflo` as a project dependency.
@@ -298,7 +298,7 @@ export default function(event, context, next) {
 <details>
 <summary>How it works...</summary>
 
-> The above function is built as part of your application's JS bundle on running the `npm run generate` command. (It is typically bundled to the file `./public/bundle.js`. And the `--auto-embed` flag in that command gets it automatically embedded on your `./public/index.html` page as `<script type="module" src="/bundle.js"></script>`.) Then it responds from right in the browser on visiting http://localhost:3000.
+> The above function is built as part of your application's client-side script from the `npm run generate` command. It is typically bundled to the file `./public/bundle.js`. And the `--auto-embed` flag in that command gets it automatically embedded on your `./public/index.html` page as `<script type="module" src="/bundle.js"></script>`. Then it responds from right in the browser on visiting http://localhost:3000.
 </details>
 
 For *browser-based* applications that want to support offline usage via Service-Workers (e.g Progressive Web Apps), Webflo allows us to define equivalent handlers for requests hitting the Service Worker. These worker-based handlers go into a directory named `worker`.
@@ -319,7 +319,7 @@ export default function(event, context, next) {
 <details>
 <summary>How it works...</summary>
 
-> The above function is built as part of your application's Service Worker JS bundle on running the `npm run generate` command. (It is typically bundled to the file `./public/worker.js`, and the main application bundle automatically connects to it.) Then it responds from within the Service Worker on visiting http://localhost:3000. (More details [ahead](#service-workers).)
+> The above function is built as part of your application's Service Worker script from the `npm run generate` command. It is typically bundled to the file `./public/worker.js`, and the main application bundle automatically connects to it. Then it responds from within the Service Worker on visiting http://localhost:3000. (More details [ahead](#service-workers).)
 </details>
 
 So, depending on what's being built, an application's handler functions may take the following form (in part or in whole):
@@ -457,7 +457,7 @@ export default async function(event, context, next) {
 </details>
 </details>
 
-But, workflows may be designed with *wildcard* steps using a hyphen `-` as step name. At runtime, a wildcard step matches any URL segment at its level in the layout! A `this.stepname` property could be used to see which URL segment has been matched.
+However, workflows may be designed with *wildcard* steps using a hyphen `-` as step name. At runtime, a wildcard step matches any URL segment at the given level in the layout! A `this.stepname` property could be used to see which URL segment has been matched.
 
 ```js
 /**
@@ -478,12 +478,18 @@ export default function(event, context, next) {
 <details>
 <summary>More details...</summary>
 
-> Every handler function has a `this.stepname` and `this.pathname` property. Server-side handlers have an extra `this.dirname` property.
+> Every handler function has the following contextual properties:
+> + `this.stepname` - The exact name of the current step in the URL path.
+> + `this.pathname` - The pathname to the current step in the URL path.
+> + `next.stepname` - The exact name of the next step in the URL path.
+> + `next.pathname` - The pathname for the rest of the steps in the URL path.
+> Server-side handlers have the following in addition:
+> + `this.dirname` - The filesystem pathname to the current step in the URL path.
 </details>
 
 Additionally, workflows may be designed with as many or as few step functions as necessary; the flow control parameters `next.stepname` and `next.pathname` can be used at any point to handle the rest of an URL that have no corresponding step functions.
 
-For example, it is possible to handle all URLs from the root handler alone.
+This means that it is even possible to handle all URLs from the root handler alone.
 
 ```js
 /**
@@ -513,7 +519,7 @@ export default function(event, context, next) {
 
 Webflo takes a *default action* when `next()` is called at the *edge* of the workflow - the point where there are no more child steps - as in the `return next()` statement above!
 
-For workflows in **the `/server` directory**, the *default action* of `next()`ing at the edge is to go match and return a static file in the `public` directory.
+**For workflows in the `/server` directory**, the *default action* of `next()`ing at the edge is to go match and return a static file in the `public` directory.
 
 So, above, should our handler receive static file requests like `http://localhost:3000/logo.png`, the statement `return next()` would get Webflo to match and return the logo at `public/logo.png`, if any; a `404` response otherwise.
 
@@ -526,7 +532,7 @@ my-app
 > **Note**
 > <br>The root handler effectively becomes the single point of entry to the application - being that it sees even requests for static files!
 
-Now, for workflows in **the `/worker` directory**, the *default action* of `next()`ing at the edge is to send the request through the network to the server. (But Webflo will know to attempt resolving the request from the application's caching system built into the Service Worker.)
+**For workflows in the `/worker` directory**, the *default action* of `next()`ing at the edge is to send the request through the network to the server. (But Webflo will know to attempt resolving the request from the application's caching system built into the Service Worker.)
 
 So, above, if we defined handler functions in the `/worker` directory, we could decide to either handle the received requests or just `next()` them to the server.
 
@@ -565,10 +571,13 @@ my-app
   └── public/logo.png ------------------------- http://localhost:3000/logo.png
 ```
 
-> **Note**
-> <br>Handlers in the `/worker` directory are only designed to see Same-Origin requests since Cross-Origin URLs like `https://auth.example.com/oauth` do not belong in the application's layout! These external URLs, however, benefit from the application's caching system built into the Service Worker.
+<details>
+<summary>More details...</summary>
+
+> Handlers in the `/worker` directory are only designed to see Same-Origin requests since Cross-Origin URLs like `https://auth.example.com/oauth` do not belong in the application's layout! These external URLs, however, benefit from the application's caching system built into the Service Worker.
+</details>
 
-For workflows in **the `/client` directory**, the *default action*  of `next()`ing at the edge is to send the request through the network to the server. But where there is a Service Worker layer, then that becomes the next destination.
+**For workflows in the `/client` directory**, the *default action*  of `next()`ing at the edge is to send the request through the network to the server. But where there is a Service Worker layer, then that becomes the next destination.
 
 So, above, if we defined handler functions in the `/client` directory, we could decide to either handle the navigation requests in-browser or just `next()` them, this time, to the Service Worker layer.
 
@@ -651,8 +660,12 @@ But, we can also access the route in a way that gets the data rendered into the
 <summary>How it works...</summary>
 
 > The `Accept` header hint is already how browsers make requests on every page load. So, it just works!
+</details>
+
+<details>
+<summary>More details...</summary>
 
-> Note that the automatic pairing of an `index.html` file with a route works the same for nested routes! But top-level `index.html` files are implicitly inherited down the hierarchy.)
+> This automatic pairing of an `index.html` file with a route works the same for nested routes! But top-level `index.html` files are implicitly inherited down the hierarchy.)
 </details>
 
 Now, for Single Page Applications, subsequent navigations, after the initial page load, just ask for the data on destination URLs and perform [Client-Side Rendering](#client-and-server-side-rendering) on the same running document. Navigation is sleek and instant!
@@ -660,7 +673,7 @@ Now, for Single Page Applications, subsequent navigations, after the initial pag
 <details>
 <summary>How it works...</summary>
 
-> Unless disabled, [SPA Routing](#spa-routing) is automatically built into your app's JS bundle from the `npm run generate` command. So, it just works!
+> Unless disabled, [SPA Routing](#spa-routing) is automatically built into your application's client-side script from the `npm run generate` command. So, it just works!
 </details>
 
 With no extra work, your application can function as either a *Multi Page App (MPA)* or a *Single Page App (SPA)*!
@@ -873,11 +886,7 @@ my-app
       └── footer.html ------------------------------ <footer></footer> <!-- To appear at bottom of each document root -->
 ```
 
-<details>
-<summary>How it works...</summary>
-
-> The above gives us three document roots: `/index.html`, `/about/index.html`, `/prodcuts/index.html`. The `/prodcuts` route doubles as a Single Page Application such that visiting the `/prodcuts` route loads the document root `/prodcuts/index.html` and lets Webflo SPA routing determine which of `/prodcuts/main.html`, `/prodcuts/free/main.html`, `/prodcuts/paid/main.html` is imported on a given URL.
-</details>
+The above gives us three document roots: `/index.html`, `/about/index.html`, `/prodcuts/index.html`. The `/prodcuts` route doubles as a Single Page Application such that visiting the `/prodcuts` route loads the document root `/prodcuts/index.html` and lets Webflo SPA routing determine which of `/prodcuts/main.html`, `/prodcuts/free/main.html`, `/prodcuts/paid/main.html` is imported on a given URL.
 
 Webflo ensures that only the amount of JavaScript for a document root is actually loaded! So, above, a common JavaScript build is shared across the three document roots alongside an often tiny root-specific build.
 
@@ -929,7 +938,11 @@ public
 </html>
 ```
 
-The Webflo `generate` command automatically figures out a given architecture and generates the appropriate scripts for the application! It also factors into the generated scripts the location of each document root so that [all navigations to these roots are handled as a regular page load](#spa-navigation).
+<details>
+<summary>How it works...</summary>
+
+> The Webflo `generate` command automatically figures out a given architecture and generates the appropriate scripts for the application! It also factors into the generated scripts the location of each document root so that [all navigations to these roots are handled as a regular page load](#spa-navigation).
+</details>
 
 #### Bundling
 
@@ -1376,7 +1389,7 @@ In just a few concepts, Webflo comes ready for any type of application!
 
 #### Client-Side Applications
 
-Web pages that embed the Webflo client JS bundle deliver a great user experience. It's simple: the `npm run generate` command does both the building and embedding of the script, or scripts, for the document root, or document roots (in a [Multi Page](#in-a-multi-page-layout) / [Multi SPA](#in-a-multi-spa-layout) layout)!
+Web pages that embed the Webflo client JS deliver a great user experience. It's simple: the `npm run generate` command does both the building and embedding of the script (or scripts), for the document root (or document roots - in a [Multi Page](#in-a-multi-page-layout) / [Multi SPA](#in-a-multi-spa-layout) layout)!
 
 On being loaded, the state of the application is initialized, or is restored through hydration - where [Server-Side Rendering](#client-and-server-side-rendering) was involved to optimize for first paint, and an app-like experience kicks in! For [Single-Page Applications](#in-a-single-page-layout), [Client-Side Rendering](#client-and-server-side-rendering) is performed on each navigation.
 
@@ -1477,7 +1490,7 @@ On the UI, this could be used to show/hide cute error elements.
 
 This property tells when a client-side redirect is ongoing - see [Scenario 4: Single Page Navigation Requests and Responses](#scenario-4-single-page-navigation-requests-and-responses) - in which case it exposes the destination URL.
 
-On the UI, this could be used to prevent further interactions with the outgoing page.
+On the UI, this could be used to mark the current page as stale and prevent further interactions.
 
 ```html
 <body>
@@ -1513,13 +1526,13 @@ Here are some additional examples with the [Observer API](#the-observer-api).
 
 ```js
 // Visualize the network state
-let onlineVisualizer = changes => {
+let networkVisualizer = changes => {
     changes.forEach(e => {
         console.log(e.name, ':', e.value);
     });
 };
-Observer.observe(document.state.network, onlineVisualizer);
-// Or: Observer.observe(document, [ ['state', 'network'] ], onlineVisualizer, { subtree: true });
+Observer.observe(document.state.network, networkVisualizer);
+// Or: Observer.observe(document, [ ['state', 'network'] ], networkVisualizer, { subtree: true });
 ```
 </details>
 
@@ -1687,7 +1700,7 @@ This strategy tells the Service Worker to always fetch given resources from the
 </details>
 </details>
 
-In all cases above, the convention for specifying URLs for a strategy accepts an [URL patterns](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) - against which URLs can be matched on the fly. For example, to place all files in an `/image` directory (and subdirectories) on the *Cache First* strategy, the pattern `/image/*` can be used. To place all `.svg` files in an `/icons` directory (including subdirectories) on the *Cache Only* strategy, the pattern `/icons/*.svg` can be used. (Specifically for the *Cache Only* strategy, patterns are resolved at Service Worker build-time, and each pattern must match, at least, a file.)
+In all cases above, the convention for specifying URLs for a strategy accepts an [URL pattern](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern) - against which URLs can be matched on the fly. For example, to place all files in an `/image` directory (and subdirectories) on the *Cache First* strategy, the pattern `/image/*` can be used. To place all `.svg` files in an `/icons` directory (including subdirectories) on the *Cache Only* strategy, the pattern `/icons/*.svg` can be used. (Specifically for the *Cache Only* strategy, patterns are resolved at Service Worker build-time, and each pattern must match, at least, a file.)
 
 <details>
 <summary>Example...</summary>
@@ -1703,7 +1716,7 @@ A couple APIs exists in browsers for establishing a two-way communication channe
 
 ###### The `workport` API
 
-This is an object with simple methods for working with *cross-thread* messages, UI and Push Notifications.
+This is an object with simple methods for working with *cross-thread* messages, UI Notifications, and Push Notifications.
 
 On both the client and worker side of your application, the `workport` object is accessible from route handlers as `this.runtime.workport`.
 
@@ -1792,12 +1805,12 @@ workport.nofitications.fire(title, options).then(event => {
 </details>
 
 <details>
-<summary>Method: <code>.nofitications.listen()</code></summary>
+<summary>Method: <code>.nofitications.handle()</code></summary>
 
-The `.nofitications.listen()` method (in Service-Workers) is used for listening to [`notificationclick`](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerGlobalScope/notificationclick_event) events. (Handlers are called each time a notification is clicked.)
+The `.nofitications.handle()` method (in Service-Workers) is used for handling [`notificationclick`](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerGlobalScope/notificationclick_event) events. (Handlers are called each time a notification is clicked.)
 
 ```js
-workport.nofitications.listen(event => {
+workport.nofitications.handle(event => {
     console.log(event.action);
 });
 ```
@@ -1968,7 +1981,7 @@ Webflo applications are often built on/with the following technologies.
 
 [OOHTML](https://github.com/webqit/oohtml) is a proposed set of new features for HTML that makes it fun to hand-author your HTML documents! Within OOHTML are [HTML Modules](https://github.com/webqit/oohtml#html-modules) and [HTML Imports](https://github.com/webqit/oohtml#html-imports), [Reactive Scripts](https://github.com/webqit/oohtml#subscript) and more!
 
-Webflo natively supports OOHTML in full! But it is also possible to switch this to none, or to partial support - when specific features aren't needed anywhere in your application. Server-side and client-side support for OOHTML exist independently. This is good when, for example, your application places more importance on SSR, and less on CSR, in which case a reduced support for OOHTML can reduce the overall client JS bundle size.
+Webflo natively supports OOHTML in full! But it is also possible to switch this to none, or to partial support - when specific features aren't needed anywhere in your application. Server-side and client-side support for OOHTML exist independently. This is good when, for example, your application places more importance on SSR, and less on CSR, in which case a reduced support for OOHTML can reduce the overall client JS size.
 
 <details>
 <summary>Config (Default)</summary>

package/package.json

@@ -12,7 +12,7 @@
     "vanila-javascript"
   ],
   "homepage": "https://webqit.io/tooling/webflo",
-  "version": "0.11.16",
+  "version": "0.11.19",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@octokit/webhooks": "^7.15.1",
-    "@webqit/backpack": "^0.1.0",
+    "@webqit/backpack": "^0.1.2",
     "@webqit/oohtml-ssr": "^1.1.0",
     "@webqit/util": "^0.8.9",
     "client-sessions": "^0.8.0",

package/src/runtime-pi/Router.js

@@ -41,12 +41,13 @@ export default class Router {
     async route(method, event, arg, _default, remoteFetch = null) {
 
         const $this = this;
+        const $runtime = this.cx.runtime;
 
         // ----------------
         // The loop
         // ----------------
         const next = async function(thisTick) {
-            const thisContext = { };
+            const thisContext = { runtime: $runtime };
             if (!thisTick.trail || thisTick.trail.length < thisTick.destination.length) {
                 thisTick = await $this.readTick(thisTick);
                 // -------------

package/src/runtime-pi/client/index.js

@@ -15,4 +15,9 @@ export async function start(clientCallback = null) {
     return new Runtime(Context.create(cx), ( ...args ) => {
         return clientCallback ? clientCallback( ...args.concat( defaultClientCallback ) ) : defaultClientCallback( ...args );
     });
-}
+}
+
+/**
+ * @APIS
+ */
+export * as APIS from './Runtime.js';

package/src/runtime-pi/client/worker/Worker.js

@@ -3,9 +3,21 @@
  * @imports
  */
 import { _any } from '@webqit/util/arr/index.js';
-import { HttpEvent, Request, Response, Observer } from '../Runtime.js';
 import { urlPattern } from '../../util.js';
 import Workport from './Workport.js';
+import { HttpEvent, Request, Response, Observer } from '../Runtime.js';
+export {
+	URL,
+	FormData,
+	ReadableStream,
+	RequestHeaders,
+	ResponseHeaders,
+	Request,
+	Response,
+	fetch,
+	HttpEvent,
+	Observer,
+} from '../Runtime.js';
 
 /**
  * ---------------------------

package/src/runtime-pi/client/worker/WorkerClient.js

@@ -2,7 +2,7 @@
 /**
  * @imports
  */
-import Router from '../Router.js';
+import Router from './Worker.js';
 
 export default class WorkerClient {
 

package/src/runtime-pi/client/worker/Workport.js

@@ -56,7 +56,7 @@ export default class Workport {
                     notification.addEventListener('close', res);
                 });
             },
-            listen: callback => {
+            handle: callback => {
                 self.addEventListener('notificationclick', callback);
                 return this.notifications;
             },

package/src/runtime-pi/client/worker/index.js

@@ -15,4 +15,9 @@ export async function start(clientCallback = null) {
     return new Worker(Context.create(cx), ( ...args ) => {
         return clientCallback ? clientCallback( ...args.concat( defaultClientCallback ) ) : defaultClientCallback( ...args );
     });
-}
+}
+
+/**
+ * @APIS
+ */
+export * as APIS from './Worker.js';

package/src/runtime-pi/server/index.js

@@ -6,20 +6,6 @@ import Context from './Context.js';
 import RuntimeClient from './RuntimeClient.js';
 import Runtime from './Runtime.js';
 
-/**
- * @desc
- */
-export const desc = {
-    config: {
-        headers: 'Configure automatic http headers.',
-        prerendering: 'Configure prerendering.',
-        redirects: 'Configure automatic redirects.',
-        server: 'Configure server settings.',
-        vhosts: 'Configure virtual hosts.',
-    },
-    start: 'Starts the Webflo server.',
-};
-
 /**
  * @start
  */
@@ -32,10 +18,6 @@ export async function start(clientCallback = null) {
 }
 
 /**
- * @exports
+ * @APIS
  */
-export {
-    Context,
-    RuntimeClient,
-    Runtime,
-}
+export * as APIS from './Runtime.js';