Add live demo documentation

.github/workflows/cicd.yml

@@ -34,3 +34,26 @@ jobs:
         run: npm install
       - name: Run tests
         run: npm test
+
+  # Type-checks and executes every docs example (www/src/examples/**)
+  # against this branch's ElectroDB, including expected-error assertions
+  # declared in each example's expect.json. Runs unconditionally (unlike
+  # the path-filtered docs workflow) so it can serve as a required check
+  # on every PR. Node 24: scripts/test-examples.ts runs via native type
+  # stripping (Node >= 23.6).
+  docs-examples:
+    timeout-minutes: 15
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - name: Install library dependencies
+        run: npm ci --omit=dev
+      - name: Install docs dependencies
+        run: npm ci
+        working-directory: www
+      - name: Type-check and execute docs examples
+        run: npm run test:examples
+        working-directory: www

.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+name: docs
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - "www/**"
+      - "index.js"
+      - "index.d.ts"
+      - "src/**"
+      - "playground/**"
+      - "package.json"
+      - "package-lock.json"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    branches: [master]
+    paths:
+      - "www/**"
+      - "index.js"
+      - "index.d.ts"
+      - "src/**"
+      - "playground/**"
+      - "package.json"
+      - "package-lock.json"
+      - ".github/workflows/docs.yml"
+
+jobs:
+  docs:
+    timeout-minutes: 15
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      # The docs examples execute against this repository's ElectroDB, so the
+      # library's (small) runtime dependency set is installed at the root.
+      - name: Install library dependencies
+        run: npm ci --omit=dev
+      - name: Install docs dependencies
+        run: npm ci
+        working-directory: www
+      - name: Type-check docs and examples
+        run: npm run check
+        working-directory: www
+      - name: Execute docs examples
+        run: npm run test:examples
+        working-directory: www
+      - name: Build docs site
+        run: npm run build
+        working-directory: www

examples/versionControl/index.ts

@@ -73,7 +73,7 @@ export async function closePullRequest(user: string, pr: PullRequestIds) {
 }
 
 // Get all user info, repos, pull requests, and issues in one query
-export async function getFirstPageLoad(username: string) {
+export async function getOwnedItems(username: string) {
   const results: OwnedItems = {
     issue: [],
     pullRequest: [],
@@ -114,11 +114,11 @@ const MaxDate = "9999-99-99";
 // Get unread comment replies
 export async function getUnreadComments(user: string) {
   const start = {
-    createdAt: MinDate,
+    updatedAt: MinDate,
     replyViewed: NotYetViewed,
   };
   const end = {
-    createdAt: MaxDate,
+    updatedAt: MaxDate,
     replyViewed: NotYetViewed,
   };
   let [issues, pullRequests] = await Promise.all([
@@ -177,40 +177,17 @@ export async function approvePullRequest(
   pullRequestNumber: string,
   username: string,
 ) {
-  const pullRequest = await VersionControl.entities.pullRequest
-    .get({ repoOwner, repoName, pullRequestNumber })
-    .go();
-
-  if (!pullRequest.data || !pullRequest.data.reviewers) {
-    return false;
-  }
-
-  let index: number = -1;
-
-  for (let i = 0; i < pullRequest.data.reviewers.length; i++) {
-    const reviewer = pullRequest.data.reviewers[i];
-    if (reviewer.username === username) {
-      index = i;
-    }
-  }
-
-  if (index === -1) {
-    return false;
-  }
-
   return VersionControl.entities.pullRequest
-    .update({ repoOwner, repoName, pullRequestNumber })
-    .data(({ reviewers }, { set }) => {
-      set(reviewers[index].approved, true);
-    })
-    .where(
-      ({ reviewers }, { eq }) => `
-            ${eq(reviewers[index].username, username)};
-        `,
+    .patch({ repoOwner, repoName, pullRequestNumber })
+    .data(({ reviewers }, { set }) =>
+      set(reviewers[username], {
+        approved: true,
+        updatedAt: moment.utc().format(),
+      }),
     )
-    .go()
-    .then(() => true)
-    .catch(() => false);
+    .where(({ reviewers }, { exists }) => exists(reviewers[username]))
+    .go({ returnOnConditionCheckFailure: true })
+    .then(({ rejected }) => !rejected);
 }
 
 export async function followRepository(

examples/versionControl/models/issue.ts

@@ -211,7 +211,7 @@ export const IssueComment = new Entity(
           field: "gsi2pk",
         },
         sk: {
-          composite: ["createdAt", "replyViewed"],
+          composite: ["updatedAt", "replyViewed"],
           field: "gsi2sk",
         },
       },

examples/versionControl/models/pullrequest.ts

@@ -2,7 +2,12 @@
 import moment from "moment";
 import { v4 as uuid } from "uuid";
 import { faker } from "@faker-js/faker";
-import { Entity, CreateEntityItem, EntityItem } from "../../../";
+import {
+  Entity,
+  CreateEntityItem,
+  CustomAttributeType,
+  EntityItem,
+} from "../../../";
 import {
   NotYetViewed,
   TicketTypes,
@@ -13,6 +18,13 @@ import {
 } from "./types";
 import { table, client } from "../../common";
 
+export type PullRequestReviewer = {
+  approved: boolean;
+  updatedAt: string;
+};
+
+export type PullRequestReviews = Record<string, PullRequestReviewer>;
+
 export const PullRequest = new Entity(
   {
     model: {
@@ -56,25 +68,7 @@ export const PullRequest = new Entity(
         get: (val) => toStatusString(val),
       },
       reviewers: {
-        type: "list",
-        items: {
-          type: "map",
-          properties: {
-            username: {
-              type: "string",
-              required: true,
-            },
-            approved: {
-              type: "boolean",
-              required: true,
-            },
-            createdAt: {
-              type: "string",
-              default: () => moment.utc().format(),
-              readOnly: true,
-            },
-          },
-        },
+        type: CustomAttributeType<PullRequestReviews>("any"),
       },
       createdAt: {
         type: "string",
@@ -231,7 +225,7 @@ export const PullRequestComment = new Entity(
           field: "gsi2pk",
         },
         sk: {
-          composite: ["createdAt", "replyViewed"],
+          composite: ["updatedAt", "replyViewed"],
           field: "gsi2sk",
         },
       },
@@ -257,13 +251,12 @@ export function createMockPullRequest(
     status: faker.helpers.arrayElement(["Open", "Closed"]),
     ticketType: faker.helpers.arrayElement(["Issue", "PullRequest"]),
     username: faker.internet.userName(),
-    reviewers: [
-      {
-        username: faker.internet.userName(),
-        createdAt: faker.date.recent().toDateString(),
+    reviewers: {
+      [faker.internet.userName()]: {
         approved: faker.helpers.arrayElement([true, false]),
+        updatedAt: faker.date.recent().toISOString(),
       },
-    ],
+    },
     ...overrides,
   };
 }