h1v3 0.7.6 → 0.9.0

package/README.md

@@ -101,6 +101,175 @@ This allows you to, in the browser, do:
 const meta = import("/store_meta") with { type: "json" }
 ```
 
+## Client-side libraries
+
+You can vendor the (free) dependencies and client files for the library using npx
+
+```bash
+npx h1v3 vendor-deps
+npx h1v3 vendor-client
+```
+
+This will create folders such as:
+ -  `/public/vendor/h1v3@0.7.6` (see below for suggestion on isolating your code from the library version)
+ - `/public/vendor/lit@3.3.1` (see https://lit.dev/)
+
+You will also need to provide a vendored library of WebAwesome Pro:
+
+ - `/public/vendor/webawesome-pro` - for now this is an explicit dependency although you can symlink it to your current version of webawesome-pro. The system expects the `dist` folder to be available at `/public/vendor/webawesome-pro/dist`.
+
+# Usage patterns - Client-side
+
+## Importing the library
+
+When using the library in your website, you may wish to create a single import location which isolates your code from the version of h1v3 you are using. You can also use it to explicitly declare which bits of the library you are depending upon.
+
+e.g. /public/js/h1v3.js
+```javascript
+export { default as bus } from "/vendor/h1v3@0.7.6/client/bus.js";
+export { EVENT_USER_PROFILE_CHANGED } from "/vendor/h1v3@0.7.6/client/events.js";
+export { styled } from "/vendor/h1v3@0.7.6/client/components/partials/wa-utils.js";
+export * from "/vendor/h1v3@0.7.6/client/system.js";
+```
+
+## Firebase configuration
+
+The system expects you to expose your (public) firebase config in an ESM module at `/firebase.config.js`. For example:
+
+```javascript
+export default {
+    apiKey: "AIzaSyCV6FjdJwU50TUZVRcoFCWqQItjhhQKbXQ",
+    authDomain: "ixion-c9e0e.firebaseapp.com",
+    databaseURL: "https://ixion-c9e0e-default-rtdb.europe-west1.firebasedatabase.app",
+    projectId: "ixion-c9e0e",
+    appId: "1:28699144755:web:2ab262d02ccba70979e946"
+};
+```
+
+# Usage Patterns - Firebase functions
+
+## Basic routes
+
+Configure at least the following four event stores:
+ - user_profile - in which a user can maintain details of their profile (as determined by the referenced schema)
+ - user_teams - where the system will maintain a quick lookup list of a user's teams
+ - team_membership - where the system records the master list of users' membership of teams, and their role (member or admin)
+ - team_details - where any admin of a team can maintain details of the team they administer (as determined by the referenced schema).
+
+
+```javascript
+import { onValueWritten } from "firebase-functions/database";
+
+import * as h1v3 from "h1v3";
+
+import paths from "./h1v3.paths.js";
+import userProfileSchema from "./schemas/user-profile-schema.js";
+import teamDetailsSchema from "./schemas/team-details-schema.js";
+import { observe } from "./o11y-provider.js";
+import { region, rtdbInstance } from "./firebase.config.js";
+
+
+const configureEventStore = h1v3.configureEventStore.inject({
+    region,
+    onValueWritten,
+    instance: rtdbInstance,
+    paths,
+    observe,
+});
+
+export const user_profile = configureEventStore(h1v3.userProfile.store, userProfileSchema);
+export const user_teams = configureEventStore(h1v3.userTeams.store);
+export const team_membership = configureEventStore(h1v3.teamMembership.store);
+export const team_details = configureEventStore(h1v3.teamDetails.store, teamDetailsSchema);
+```
+
+### Defining schemas
+
+Schemas for the two built-in event stores user_profile and team_details expect a schema defined using a javascript prototype as shown below. Note that there is no required constraint. Instead the schema is a white-list of keys along with the expected type for the associated value.
+
+```javascript
+export default {
+    name: String,
+    age: Number,
+    favourite: {
+        color: String
+    }
+};
+```
+
+## Observability provider
+
+h1v3 has a built-in observability provider, but it must be initialised using external logging and trace facilities. An example implementation is shown below. This illustrates initialising the provider with (1) emulated versions of tracing and logging and (2)  Google Cloud versions:
+
+```javascript
+import { Logging } from "@google-cloud/logging";
+import { google } from "googleapis";
+
+import * as h1v3 from "h1v3";
+
+import { projectId, serviceName } from "./firebase.config.js";
+
+const [trace, log] = process.env.FUNCTIONS_EMULATOR === "true" ? buildEmulated() : buildReal();
+
+export const observe = h1v3.o11y.provider({
+    trace,
+    log,
+    projectId,
+    serviceName
+});
+
+function buildReal() {
+
+    const scopes = [
+        "https://www.googleapis.com/auth/trace.append",
+        "https://www.googleapis.com/auth/cloud-platform"
+    ];
+
+    google.auth.getClient({ scopes }).then(auth => google.options({ auth })); // we can't await this as firebase will complain
+
+    return [
+        google.cloudtrace("v2"),
+        new Logging().log(serviceName)
+    ];
+
+}
+
+function buildEmulated() {
+
+    return [
+        {
+            projects: {
+                traces: {
+                    spans: {
+                        createSpan(...args) {
+
+                            console.log("[TRACE]", JSON.stringify(args));
+
+                        }
+                    }
+                }
+            }
+        },
+        {
+            entry: (...args) => args,
+            write(entry) {
+
+                console.log("[LOG]", JSON.stringify(entry));
+
+            }
+        }
+    ];
+
+}
+```
+
+
+
+
+
+
+
+
 # Implicit Google API dependencies
 
 Note - this is an incomplete list...

package/dist/browser/client/context.js

@@ -20,14 +20,13 @@ function defaultHandleError(err) {
 
 }
 
-export async function inject({ database, authentication, metaURL, handleError = defaultHandleError }) {
+export async function inject({ database, authentication, metaURL, meta, handleError = defaultHandleError }) {
 
     if (!database) throw new Error("Missing database");
-    if (!metaURL) throw new Error("Missing metaURL");
+    if (!(metaURL || meta)) throw new Error("Missing metaURL");
     if (!authentication) throw new Error("Missing authentication");
 
-    // const meta = await fetch(metaURL).then(resp => resp.json())
-    const { default: meta } = await import(metaURL, { with: { type: "json" } });
+    meta = meta || await import(metaURL, { with: { type: "json" } });
 
     const log = logger(database, authentication, meta.o11y.path);
     const teamMembershipStoreFactory = ({ tid }) => eventStore(database, authentication, populateParameters({ tid }, meta.team.membership.path));

package/dist/browser/client/system.js

@@ -1,16 +1,16 @@
-export const waDist = "/vendor/@shoelace-style/webawesome-pro@3.0.0-beta.6/dist";
+export const waDist = "/vendor/webawesome-pro";
 
 // firebase
 export * from "./firebase.js";
 
 // vendor: webawesome
-import "/vendor/@shoelace-style/webawesome-pro@3.0.0-beta.6/dist/components/button/button.js";
-import "/vendor/@shoelace-style/webawesome-pro@3.0.0-beta.6/dist/components/input/input.js";
-import "/vendor/@shoelace-style/webawesome-pro@3.0.0-beta.6/dist/components/card/card.js";
-import "/vendor/@shoelace-style/webawesome-pro@3.0.0-beta.6/dist/components/divider/divider.js";
-import "/vendor/@shoelace-style/webawesome-pro@3.0.0-beta.6/dist/components/icon/icon.js";
-import "/vendor/@shoelace-style/webawesome-pro@3.0.0-beta.6/dist/components/dialog/dialog.js";
-import "/vendor/@shoelace-style/webawesome-pro@3.0.0-beta.6/dist/components/callout/callout.js";
+import "/vendor/webawesome-pro/components/button/button.js";
+import "/vendor/webawesome-pro/components/input/input.js";
+import "/vendor/webawesome-pro/components/card/card.js";
+import "/vendor/webawesome-pro/components/divider/divider.js";
+import "/vendor/webawesome-pro/components/icon/icon.js";
+import "/vendor/webawesome-pro/components/dialog/dialog.js";
+import "/vendor/webawesome-pro/components/callout/callout.js";
 
 // vendor: lit
 export { html, LitElement, css, render } from "/vendor/lit@3.3.1/dist/lit-core.min.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "h1v3",
-  "version": "0.7.6",
+  "version": "0.9.0",
   "description": "",
   "license": "MIT",
   "author": "",

package/src/configuration/configure-eventStore.js

@@ -35,4 +35,9 @@ export function configureEventStore({ ref, projections, ...rest }, { onValueWrit
     );
 
 }
-configureEventStore.inject = ({ onValueWritten, observe, paths, region, instance }) => (eventStoreFactory, ...args) => configureEventStore(eventStoreFactory(paths, ...args), { onValueWritten, observe, region, instance });
+
+configureEventStore.inject = ({ onValueWritten, observe, paths, region, instance }) =>
+
+    (eventStoreFactory, ...args) =>
+
+        configureEventStore(eventStoreFactory(paths, ...args), { onValueWritten, observe, region, instance });