@dxos/functions 0.8.2-main.2f9c567 → 0.8.2-main.36232bc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/functions",
-  "version": "0.8.2-main.2f9c567",
+  "version": "0.8.2-main.36232bc",
   "description": "Functions API and runtime.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -23,6 +23,16 @@
       "types": "./dist/types/src/edge/index.d.ts",
       "browser": "./dist/lib/browser/edge/index.mjs",
       "node": "./dist/lib/node-esm/edge/index.mjs"
+    },
+    "./testing": {
+      "types": "./dist/types/src/testing/index.d.ts",
+      "browser": "./dist/lib/browser/testing/index.mjs",
+      "node": "./dist/lib/node-esm/testing/index.mjs"
+    },
+    "./types": {
+      "types": "./dist/types/src/types/index.d.ts",
+      "browser": "./dist/lib/browser/types/index.mjs",
+      "node": "./dist/lib/node-esm/types/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -33,6 +43,12 @@
       ],
       "edge": [
         "dist/types/src/edge/index.d.ts"
+      ],
+      "testing": [
+        "dist/types/src/testing/index.d.ts"
+      ],
+      "types": [
+        "dist/types/src/types/index.d.ts"
       ]
     }
   },
@@ -45,34 +61,34 @@
     "@preact/signals-core": "^1.6.0",
     "cron": "^3.1.6",
     "cron-schedule": "^5.0.4",
-    "effect": "3.14.21",
+    "effect": "3.13.3",
     "esbuild-wasm": "^0.16.14",
     "express": "^4.19.2",
     "get-port-please": "^3.1.1",
     "iso-did": "^1.6.0",
     "ws": "^8.14.2",
-    "@dxos/assistant": "0.8.2-main.2f9c567",
-    "@dxos/async": "0.8.2-main.2f9c567",
-    "@dxos/client": "0.8.2-main.2f9c567",
-    "@dxos/context": "0.8.2-main.2f9c567",
-    "@dxos/echo-db": "0.8.2-main.2f9c567",
-    "@dxos/echo-schema": "0.8.2-main.2f9c567",
-    "@dxos/echo-protocol": "0.8.2-main.2f9c567",
-    "@dxos/edge-client": "0.8.2-main.2f9c567",
-    "@dxos/crypto": "0.8.2-main.2f9c567",
-    "@dxos/invariant": "0.8.2-main.2f9c567",
-    "@dxos/keys": "0.8.2-main.2f9c567",
-    "@dxos/log": "0.8.2-main.2f9c567",
-    "@dxos/node-std": "0.8.2-main.2f9c567",
-    "@dxos/live-object": "0.8.2-main.2f9c567",
-    "@dxos/protocols": "0.8.2-main.2f9c567",
-    "@dxos/schema": "0.8.2-main.2f9c567",
-    "@dxos/util": "0.8.2-main.2f9c567"
+    "@dxos/assistant": "0.8.2-main.36232bc",
+    "@dxos/async": "0.8.2-main.36232bc",
+    "@dxos/client": "0.8.2-main.36232bc",
+    "@dxos/crypto": "0.8.2-main.36232bc",
+    "@dxos/echo-db": "0.8.2-main.36232bc",
+    "@dxos/echo-protocol": "0.8.2-main.36232bc",
+    "@dxos/echo-schema": "0.8.2-main.36232bc",
+    "@dxos/context": "0.8.2-main.36232bc",
+    "@dxos/keys": "0.8.2-main.36232bc",
+    "@dxos/invariant": "0.8.2-main.36232bc",
+    "@dxos/edge-client": "0.8.2-main.36232bc",
+    "@dxos/live-object": "0.8.2-main.36232bc",
+    "@dxos/node-std": "0.8.2-main.36232bc",
+    "@dxos/protocols": "0.8.2-main.36232bc",
+    "@dxos/log": "0.8.2-main.36232bc",
+    "@dxos/util": "0.8.2-main.36232bc",
+    "@dxos/schema": "0.8.2-main.36232bc"
   },
   "devDependencies": {
     "@types/express": "^4.17.17",
     "@types/ws": "^7.4.0",
-    "@dxos/agent": "0.8.2-main.2f9c567"
+    "@dxos/agent": "0.8.2-main.36232bc"
   },
   "publishConfig": {
     "access": "public"

package/schema/functions.json

@@ -0,0 +1,211 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [],
+  "properties": {
+    "functions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "uri",
+          "route",
+          "handler"
+        ],
+        "properties": {
+          "uri": {
+            "type": "string",
+            "description": "a string",
+            "title": "string"
+          },
+          "route": {
+            "type": "string",
+            "description": "a string",
+            "title": "string"
+          },
+          "handler": {
+            "type": "string",
+            "description": "a string",
+            "title": "string"
+          },
+          "description": {
+            "type": "string",
+            "description": "a string",
+            "title": "string"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "triggers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "function",
+          "spec"
+        ],
+        "properties": {
+          "function": {
+            "type": "string",
+            "description": "Function",
+            "title": "string"
+          },
+          "enabled": {
+            "type": "boolean",
+            "description": "a boolean",
+            "title": "boolean"
+          },
+          "meta": {
+            "$ref": "#/$defs/object"
+          },
+          "spec": {
+            "anyOf": [
+              {
+                "type": "object",
+                "required": [
+                  "type",
+                  "cron"
+                ],
+                "properties": {
+                  "type": {
+                    "const": "timer"
+                  },
+                  "cron": {
+                    "type": "string",
+                    "description": "a string",
+                    "title": "string"
+                  }
+                },
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "required": [
+                  "type",
+                  "method"
+                ],
+                "properties": {
+                  "type": {
+                    "const": "webhook"
+                  },
+                  "method": {
+                    "type": "string",
+                    "description": "a string",
+                    "title": "string"
+                  },
+                  "port": {
+                    "type": "number",
+                    "description": "a number",
+                    "title": "number"
+                  }
+                },
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "required": [
+                  "type",
+                  "url"
+                ],
+                "properties": {
+                  "type": {
+                    "const": "websocket"
+                  },
+                  "url": {
+                    "type": "string",
+                    "description": "a string",
+                    "title": "string"
+                  },
+                  "init": {
+                    "type": "object",
+                    "required": [],
+                    "properties": {},
+                    "additionalProperties": {
+                      "$id": "/schemas/any",
+                      "title": "any"
+                    }
+                  }
+                },
+                "additionalProperties": false
+              },
+              {
+                "type": "object",
+                "required": [
+                  "type",
+                  "filter"
+                ],
+                "properties": {
+                  "type": {
+                    "const": "subscription"
+                  },
+                  "filter": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": [
+                        "type"
+                      ],
+                      "properties": {
+                        "type": {
+                          "type": "string",
+                          "description": "a string",
+                          "title": "string"
+                        },
+                        "props": {
+                          "type": "object",
+                          "required": [],
+                          "properties": {},
+                          "additionalProperties": {
+                            "$id": "/schemas/any",
+                            "title": "any"
+                          }
+                        }
+                      },
+                      "additionalProperties": false
+                    }
+                  },
+                  "options": {
+                    "type": "object",
+                    "required": [],
+                    "properties": {
+                      "deep": {
+                        "type": "boolean",
+                        "description": "a boolean",
+                        "title": "boolean"
+                      },
+                      "delay": {
+                        "type": "number",
+                        "description": "a number",
+                        "title": "number"
+                      }
+                    },
+                    "additionalProperties": false
+                  }
+                },
+                "additionalProperties": false
+              }
+            ]
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "object": {
+      "$id": "/schemas/object",
+      "oneOf": [
+        {
+          "type": "object"
+        },
+        {
+          "type": "array"
+        }
+      ],
+      "description": "an object in the TypeScript meaning, i.e. the `object` type",
+      "title": "object"
+    }
+  }
+}

package/src/browser/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from '../types';

package/src/edge/index.ts

@@ -2,8 +2,4 @@
 // Copyright 2024 DXOS.org
 //
 
-// NOTE: This module is separate because it uses the edge client.
-//  This means it cannot be used on edge itself.
-// TODO(wittjosiah): Factor out.
-
 export * from './functions';

package/src/function/function-registry.test.ts

@@ -0,0 +1,118 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+
+import { Trigger } from '@dxos/async';
+import { type Client } from '@dxos/client';
+import { TestBuilder } from '@dxos/client/testing';
+import { Context } from '@dxos/context';
+import { Filter } from '@dxos/echo-db';
+import { live } from '@dxos/live-object';
+import { range } from '@dxos/util';
+
+import { FunctionRegistry } from './function-registry';
+import { createInitializedClients } from '../testing';
+import { FunctionDef, type FunctionManifest } from '../types';
+
+const testManifest: FunctionManifest = {
+  functions: [
+    {
+      uri: 'dxos.functions.test/hello',
+      route: '/hello',
+      handler: 'test',
+    },
+  ],
+};
+
+describe('function registry', () => {
+  let ctx: Context;
+  let testBuilder: TestBuilder;
+
+  beforeEach(async () => {
+    ctx = new Context();
+    testBuilder = new TestBuilder();
+  });
+
+  afterEach(async () => {
+    await ctx.dispose();
+    await testBuilder.destroy();
+  });
+
+  test('getUniqueByUri', async () => {
+    const client = (await createInitializedClients(testBuilder))[0];
+    const registry = createRegistry(client);
+    await registry.open();
+    for (let i = 0; i < 2; i++) {
+      const space = await client.spaces.create();
+      await registry.register(space, testManifest.functions);
+    }
+    const definitions = registry.getUniqueByUri();
+    expect(definitions.length).to.eq(testManifest.functions?.length);
+  });
+
+  describe('register', () => {
+    test('creates new functions', async () => {
+      const client = (await createInitializedClients(testBuilder))[0];
+      const registry = createRegistry(client);
+      const space = await client.spaces.create();
+      await registry.register(space, testManifest.functions);
+      const { objects: definitions } = await space.db.query(Filter.schema(FunctionDef)).run();
+      expect(definitions.length).to.eq(1);
+      expect(definitions[0].uri).to.eq(testManifest.functions?.[0]?.uri);
+    });
+
+    test('de-duplicates by function URI', async () => {
+      const client = (await createInitializedClients(testBuilder))[0];
+      const registry = createRegistry(client);
+      const space = await client.spaces.create();
+      const existing = space.db.add(live(FunctionDef, testManifest.functions![0]));
+      await registry.register(space, testManifest.functions);
+      const { objects: definitions } = await space.db.query(Filter.schema(FunctionDef)).run();
+      expect(definitions.length).to.eq(1);
+      expect(definitions[0].uri).to.eq(existing.uri);
+    });
+  });
+
+  describe('onFunctionsRegistered', () => {
+    test('called with all registered when opened', async () => {
+      const client = (await createInitializedClients(testBuilder))[0];
+      const registry = createRegistry(client);
+      const space = await client.spaces.create();
+      const definitions = range(3, () => live(FunctionDef, testManifest.functions![0]));
+      definitions.forEach((def) => space.db.add(def));
+
+      const functionRegistered = new Trigger<FunctionDef[]>();
+      registry.registered.on((fn) => {
+        functionRegistered.wake(fn.added);
+      });
+      void registry.open(ctx);
+      const functions = await functionRegistered.wait();
+      const expected = definitions.map((def) => def.uri).sort();
+      expect(functions.map((fn) => fn.uri).sort()).to.deep.eq(expected);
+    });
+
+    test('called when a new functions is added', async () => {
+      const client = (await createInitializedClients(testBuilder))[0];
+      const registry = createRegistry(client);
+      const space = await client.spaces.create();
+
+      const functionRegistered = new Trigger<FunctionDef>();
+      registry.registered.on((fn) => {
+        expect(fn.added.length).to.eq(1);
+        functionRegistered.wake(fn.added[0]);
+      });
+      await registry.open(ctx);
+      await registry.register(space, testManifest.functions);
+      const registered = await functionRegistered.wait();
+      expect(registered.uri).to.eq(testManifest.functions![0].uri);
+    });
+  });
+
+  const createRegistry = (client: Client) => {
+    const registry = new FunctionRegistry(client);
+    ctx.onDispose(() => registry.close());
+    return registry;
+  };
+});

package/src/function/function-registry.ts

@@ -0,0 +1,104 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Event } from '@dxos/async';
+import { type Client } from '@dxos/client';
+import { live, Filter, type Space } from '@dxos/client/echo';
+import { type Context, Resource } from '@dxos/context';
+import { PublicKey } from '@dxos/keys';
+import { log } from '@dxos/log';
+import { ComplexMap, diff } from '@dxos/util';
+
+import { FunctionDef, type FunctionManifest } from '../types';
+
+export type FunctionsRegisteredEvent = {
+  space: Space;
+  added: FunctionDef[];
+};
+
+export class FunctionRegistry extends Resource {
+  private readonly _functionBySpaceKey = new ComplexMap<PublicKey, FunctionDef[]>(PublicKey.hash);
+
+  public readonly registered = new Event<FunctionsRegisteredEvent>();
+
+  constructor(private readonly _client: Client) {
+    super();
+  }
+
+  public getFunctions(space: Space): FunctionDef[] {
+    return this._functionBySpaceKey.get(space.key) ?? [];
+  }
+
+  public getUniqueByUri(): FunctionDef[] {
+    const uniqueByUri = [...this._functionBySpaceKey.values()]
+      .flatMap((defs) => defs)
+      .reduce((acc, v) => {
+        acc.set(v.uri, v);
+        return acc;
+      }, new Map<string, FunctionDef>());
+    return [...uniqueByUri.values()];
+  }
+
+  /**
+   * Loads function definitions from the manifest into the space.
+   * We first load all the definitions from the space to deduplicate by functionId.
+   */
+  public async register(space: Space, functions: FunctionManifest['functions']): Promise<void> {
+    log('register', { space: space.key, functions: functions?.length ?? 0 });
+    if (!functions?.length) {
+      return;
+    }
+    if (!space.db.graph.schemaRegistry.hasSchema(FunctionDef)) {
+      space.db.graph.schemaRegistry.addSchema([FunctionDef]);
+    }
+
+    // Sync definitions.
+    const { objects: existing } = await space.db.query(Filter.schema(FunctionDef)).run();
+    const { added } = diff(existing, functions, (a, b) => a.uri === b.uri);
+    // TODO(burdon): Update existing templates.
+    added.forEach((def) => space.db.add(live(FunctionDef, def)));
+
+    if (added.length > 0) {
+      await space.db.flush({ indexes: true, updates: true });
+    }
+  }
+
+  protected override async _open(): Promise<void> {
+    log.info('opening...');
+    const spacesSubscription = this._client.spaces.subscribe(async (spaces) => {
+      for (const space of spaces) {
+        if (this._functionBySpaceKey.has(space.key)) {
+          continue;
+        }
+
+        const registered: FunctionDef[] = [];
+        this._functionBySpaceKey.set(space.key, registered);
+        await space.waitUntilReady();
+        if (this._ctx.disposed) {
+          break;
+        }
+
+        // Subscribe to updates.
+        this._ctx.onDispose(
+          space.db.query(Filter.schema(FunctionDef)).subscribe(({ objects }) => {
+            const { added } = diff(registered, objects, (a, b) => a.uri === b.uri);
+            // TODO(burdon): Update and remove.
+            if (added.length > 0) {
+              registered.push(...added);
+              this.registered.emit({ space, added });
+            }
+          }),
+        );
+      }
+    });
+
+    // TODO(burdon): API: Normalize unsubscribe methods.
+    this._ctx.onDispose(() => spacesSubscription.unsubscribe());
+  }
+
+  protected override async _close(_: Context): Promise<void> {
+    log.info('closing...');
+    this._functionBySpaceKey.clear();
+  }
+}

package/src/function/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './function-registry';