h1v3 0.1.0 → 0.2.1

package/README.md

@@ -1,2 +1,29 @@
 # h1v3
 A firebase web platform
+
+# Install
+
+```
+npm install h1v3
+```
+
+# Event stores
+Built on Firebase Real-time Database allowing simple projections updated when events are written. See [event-stores.md](event-stores.md).
+
+# Web platform
+The web platform covers the following (headless) functionality:
+ - message bus
+ - login
+ - firebase initialisation
+
+You can install the web platform using `npx h1v3 vendor-web`
+
+**Note** if using the Web UI platform, the web platform will be installed and used by default
+
+# Web UI platform
+The following components build on the headless web platform:
+ - login
+ - error notifications
+ - Styling and registration of Web Awesome components
+
+You can install the web platform UI (and headlesss) platform using `npx h1v3 vendor-webui`

package/event-stores.md

@@ -0,0 +1,238 @@
+[Home](README.md)
+
+# Event store architecture
+Events are written to `/events` and must contain a `type` property (string)
+Projections are read from `/projections/the_projection_nmae`
+
+When an event is written, a trigger is fired which updates all the defined projections. This means that an updated projection may take some time to synchronise with the written events. Typically this is a few ms, but code patterns need to follow an asynchronous pattern. Although it is possible to fetch a snapshot of a projection using the `getProjection` method of the event store client, it is preferred to subscribe using the `onProjectionValue` callback.
+
+# Identify event sourced collections using conviguration
+
+e.g. Below we configure three event stores:
+
+`user_profile`: A store of events at /h1v3_dev/users/$uid/profile with a single projection "current". Read and Write are both only if $uid == auth.uid.
+
+`teams_data_docs`: at /h1v3_dev/teams/$tid/data/$did - storing events pertaining to a particular document for a particular team. Both read and write are determined by if my user id is present in the "members" projection of the teams_membership event store.
+
+`teams_membership`: at /h1v3_dev/teams/$tid/membership - stores events pertaining to team membership. There are two projections: "members" (a flat list of user ids) and "details" (which holds details of the role within a team - admin, owner etc.)
+
+```javascript
+import { onValueWritten } from "firebase-functions/database";
+import { logger } from "firebase-functions";
+import { configure, ifUserIdExists, passThroughView } from "h1v3";
+
+import { membershipDetails, members } from "./storage-dev-sample-projections/team-membership.js";
+import { current } from "./storage-dev-sample-projections/user-profile.js";
+
+const ifMyTeam = ifUserIdExists("/h1v3_dev/teams/$tid/membership/projections/members");
+const ifAdminInThisTeam = ifUserIdExists("/h1v3_dev/teams/$tid/membership/projections/details/admins");
+const ifMe = "$uid == auth.uid";
+
+const stores = {
+
+    user_profile: {
+
+        ref: "/h1v3_dev/users/$uid/profile",
+        projections: {
+            current
+        },
+        write: ifMe,
+        read: ifMe
+
+    },
+
+    teams_membership: {
+        ref: "/h1v3_dev/teams/$tid/membership",
+        projections: {
+            "details": membershipDetails,
+            members
+        },
+        write: ifAdminInThisTeam,
+        read: ifAdminInThisTeam
+    },
+
+    teams_data_docs: {
+
+        ref: "/h1v3_dev/teams/$tid/data/$did",
+        projections: {
+            "all": passThroughView
+        },
+        write: ifMyTeam,
+        read: ifMyTeam
+
+    }
+
+};
+
+export const user_profile = configure(stores.user_profile, onValueWritten, logger);
+export const teams_membership = configure(stores.teams_membership, onValueWritten, logger);
+export const teams_data_docs = configure(stores.teams_data_docs, onValueWritten, logger);
+```
+
+# Generate database rules
+
+Once you have configured your event stores, you can generate Firebase database rules like so:
+
+```bash
+npx h1v3 rules --snippet
+
+    "h1v3_dev": {
+        "teams": {
+            "$tid": {
+                "data": {
+                    "$did": {
+                        ".read": false,
+                        ".write": false,
+                        "events": {
+                            "$eid": {
+                                ".write": "!data.exists() && (root.child('/h1v3_dev/teams/' + $tid + '/membership/projections/members/' + auth.uid).exists())",
+                                ".validate": "newData.child('type').isString()"
+                            }
+                        },
+                        "projections": {
+                            "$pid": {
+                                ".read": "root.child('/h1v3_dev/teams/' + $tid + '/membership/projections/members/' + auth.uid).exists()"
+                            }
+                        }
+                    }
+                },
+                "membership": {
+                    ".read": false,
+                    ".write": false,
+                    "events": {
+                        "$eid": {
+                            ".write": "!data.exists() && (root.child('/h1v3_dev/teams/' + $tid + '/membership/projections/details/admins/' + auth.uid).exists())",
+                            ".validate": "newData.child('type').isString()"
+                        }
+                    },
+                    "projections": {
+                        "$pid": {
+                            ".read": "root.child('/h1v3_dev/teams/' + $tid + '/membership/projections/details/admins/' + auth.uid).exists()"
+                        }
+                    }
+                }
+            }
+        },
+        "users": {
+            "$uid": {
+                "profile": {
+                    ".read": false,
+                    ".write": false,
+                    "events": {
+                        "$eid": {
+                            ".write": "!data.exists() && ($uid == auth.uid)",
+                            ".validate": "newData.child('type').isString()"
+                        }
+                    },
+                    "projections": {
+                        "$pid": {
+                            ".read": "$uid == auth.uid"
+                        }
+                    }
+                }
+            }
+        }
+    }
+```
+
+# Server-side event store access
+
+h1v3 provides a server-side client library compatible with Firebase's admin-sdk for node.js. Below is an example where we record an event "DETAILS_UPDATED" against the user profile event store for the `testAlice` user:
+
+```javascript
+import { initializeApp } from "firebase-admin/app";
+import { getAuth } from "firebase-admin/auth";
+import { getDatabase } from "firebase-admin/database";
+
+import { node } from "h1v3/client";
+
+const app = initializeApp();
+
+const auth = getAuth(app);
+const testAlice = await auth.createUser({
+    uid: "test-alice"
+});
+
+const db = getDatabase();
+const store = node.eventStore(db, `/h1v3_dev/users/${testAlice.uid}/profile`);
+await store.record(
+    "DETAILS_UPDATED",
+    {
+        name: "Alice",
+        favourite: {
+            color: "pink"
+        }
+    }
+);
+
+// note - may be stale, consider using `onProjectionValue` instead
+const currentProfile = await store.getProjection("current");
+```
+
+# Client-side event store access
+
+Similarly, the client-side event store provides the same access but using h1v3's exposed Firebase instance. You can install the client-side javascript components using `npx h1v3 vendor-eventstore` and `npx h1v3 vendor-web`.
+
+```bash
+npx h1v3 vendor-eventstore # ./public/vendor/h1v3@1.2.3/event-store
+npx h1v3 vendor-web # ./public/vendor/h1v3@1.2.3/web
+```
+
+```javascript
+<script type="module">
+
+    import { eventStore } from "/vendor/h1v3@1.2.3/event-store/modular.js";
+    import { firebase } from "/vendor/h1v3@1.2.3/web/system.js";
+
+    const store = eventStore(firebase.database, eventStorePathValue);
+    await store.record(
+        "DETAILS_UPDATED",
+        {
+            name: "Alice",
+            favourite: {
+                color: "pink"
+            }
+        }
+    );
+
+    // note - may be stale, consider using `onProjectionValue` instead
+    const currentProfile = await store.getProjection("current");
+</script>
+```
+
+# Creating projections
+Projections need a method which can apply an event to a view in event written order. For example, the user profile projection "current" could be defined as follows:
+
+
+```javascript
+import { deleteByPath, filterBySchema, schemaAllowsPath } from "h1v3/schema";
+
+const schema = {
+    "name": String,
+    "age": Number,
+    "favourite": {
+        "color": String
+    }
+};
+
+export const current = {
+
+    "DETAILS_UPDATED": (view, { payload }) => {
+
+        if (!payload || typeof payload !== "object") return view;
+        view = Object.assign(view, filterBySchema(schema, payload));
+        if(payload?.unset)
+            payload.unset.forEach(path => {
+
+                if (schemaAllowsPath(schema, path))
+                    deleteByPath(view, path);
+                else
+                    console.warn("Unset path not allowed by schema", path);
+
+            });
+        return view;
+
+    }
+
+};
+```

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "h1v3",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "",
-  "license": "ISC",
+  "license": "MIT",
   "author": "",
   "type": "module",
   "exports": {