h1v3 0.8.0 → 0.9.0

package/README.md

@@ -101,9 +101,9 @@ This allows you to, in the browser, do:
 const meta = import("/store_meta") with { type: "json" }
 ```
 
-## Vendor the client-side libraries
+## Client-side libraries
 
-You can install (free) dependencies and client files for the library using npx
+You can vendor the (free) dependencies and client files for the library using npx
 
 ```bash
 npx h1v3 vendor-deps
@@ -118,7 +118,7 @@ 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
+# Usage patterns - Client-side
 
 ## Importing the library
 
@@ -132,6 +132,143 @@ export { styled } from "/vendor/h1v3@0.7.6/client/components/partials/wa-utils.j
 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
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "h1v3",
-  "version": "0.8.0",
+  "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 });