@dxos/functions 0.8.4-main.e098934 → 0.8.4-main.e8ec1fe

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dxos/functions",
-  "version": "0.8.4-main.e098934",
-  "description": "Functions API and runtime.",
+  "version": "0.8.4-main.e8ec1fe",
+  "description": "Functions API.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
   "license": "MIT",
@@ -14,83 +14,29 @@
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs"
-    },
-    "./bundler": {
-      "source": "./src/bundler/index.ts",
-      "types": "./dist/types/src/bundler/index.d.ts",
-      "browser": "./dist/lib/browser/bundler/index.mjs",
-      "node": "./dist/lib/node-esm/bundler/index.mjs"
-    },
-    "./edge": {
-      "source": "./src/edge/index.ts",
-      "types": "./dist/types/src/edge/index.d.ts",
-      "browser": "./dist/lib/browser/edge/index.mjs",
-      "node": "./dist/lib/node-esm/edge/index.mjs"
-    },
-    "./testing": {
-      "source": "./src/testing/index.ts",
-      "types": "./dist/types/src/testing/index.d.ts",
-      "browser": "./dist/lib/browser/testing/index.mjs",
-      "node": "./dist/lib/node-esm/testing/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "bundler": [
-        "dist/types/src/bundler/index.d.ts"
-      ],
-      "edge": [
-        "dist/types/src/edge/index.d.ts"
-      ]
-    }
-  },
   "files": [
     "dist",
     "schema",
     "src"
   ],
   "dependencies": {
-    "@effect/platform": "0.90.2",
-    "@preact/signals-core": "^1.9.0",
-    "cron": "^3.1.6",
-    "cron-schedule": "^5.0.4",
-    "effect": "3.17.7",
-    "esbuild-wasm": "^0.16.14",
-    "express": "^4.19.2",
-    "get-port-please": "^3.1.1",
-    "i18next": "^24.2.1",
-    "iso-did": "^1.6.0",
-    "ws": "^8.14.2",
-    "@dxos/ai": "0.8.4-main.e098934",
-    "@dxos/client": "0.8.4-main.e098934",
-    "@dxos/async": "0.8.4-main.e098934",
-    "@dxos/client-protocol": "0.8.4-main.e098934",
-    "@dxos/context": "0.8.4-main.e098934",
-    "@dxos/debug": "0.8.4-main.e098934",
-    "@dxos/crypto": "0.8.4-main.e098934",
-    "@dxos/echo-db": "0.8.4-main.e098934",
-    "@dxos/echo-pipeline": "0.8.4-main.e098934",
-    "@dxos/echo": "0.8.4-main.e098934",
-    "@dxos/echo-protocol": "0.8.4-main.e098934",
-    "@dxos/echo-schema": "0.8.4-main.e098934",
-    "@dxos/edge-client": "0.8.4-main.e098934",
-    "@dxos/effect": "0.8.4-main.e098934",
-    "@dxos/errors": "0.8.4-main.e098934",
-    "@dxos/invariant": "0.8.4-main.e098934",
-    "@dxos/keys": "0.8.4-main.e098934",
-    "@dxos/live-object": "0.8.4-main.e098934",
-    "@dxos/kv-store": "0.8.4-main.e098934",
-    "@dxos/log": "0.8.4-main.e098934",
-    "@dxos/node-std": "0.8.4-main.e098934",
-    "@dxos/protocols": "0.8.4-main.e098934",
-    "@dxos/schema": "0.8.4-main.e098934",
-    "@dxos/util": "0.8.4-main.e098934"
-  },
-  "devDependencies": {
-    "@types/express": "^4.17.17",
-    "@types/ws": "^7.4.0",
-    "@dxos/agent": "0.8.4-main.e098934"
+    "@effect/platform": "0.92.1",
+    "effect": "3.18.3",
+    "@dxos/ai": "0.8.4-main.e8ec1fe",
+    "@dxos/echo-db": "0.8.4-main.e8ec1fe",
+    "@dxos/effect": "0.8.4-main.e8ec1fe",
+    "@dxos/errors": "0.8.4-main.e8ec1fe",
+    "@dxos/invariant": "0.8.4-main.e8ec1fe",
+    "@dxos/echo": "0.8.4-main.e8ec1fe",
+    "@dxos/keys": "0.8.4-main.e8ec1fe",
+    "@dxos/node-std": "0.8.4-main.e8ec1fe",
+    "@dxos/log": "0.8.4-main.e8ec1fe",
+    "@dxos/schema": "0.8.4-main.e8ec1fe",
+    "@dxos/types": "0.8.4-main.e8ec1fe",
+    "@dxos/protocols": "0.8.4-main.e8ec1fe"
   },
   "publishConfig": {
     "access": "public"

package/src/{examples → example}/fib.ts

@@ -2,12 +2,14 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Effect, Schema } from 'effect';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
 
-import { defineFunction } from '../handler';
+import { defineFunction } from '../sdk';
 
 export default defineFunction({
-  name: 'example.org/function/fib',
+  key: 'example.org/function/fib',
+  name: 'Fibonacci',
   description: 'Function that calculates a Fibonacci number',
   inputSchema: Schema.Struct({
     iterations: Schema.optional(Schema.Number).annotations({

package/src/example/forex-effect.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @ts-ignore
+import { S, defineFunction } from 'dxos:functions';
+import {
+  FetchHttpClient,
+  HttpClient,
+  HttpClientRequest,
+  // @ts-ignore
+} from 'https://esm.sh/@effect/platform@0.89.0?deps=effect@3.17.0&bundle=false';
+// @ts-ignore
+import { Effect, Schedule } from 'https://esm.sh/effect@3.17.0?bundle=false';
+
+export default defineFunction({
+  key: 'dxos.org/script/forex-effect',
+  name: 'Forex Effect',
+  description: 'Returns the exchange rate between two currencies.',
+
+  inputSchema: S.Struct({
+    from: S.String.annotations({ description: 'The source currency' }),
+    to: S.String.annotations({ description: 'The target currency' }),
+  }),
+
+  outputSchema: S.String.annotations({ description: 'The exchange rate between the two currencies' }),
+
+  handler: async ({ data: { from, to } }: any) =>
+    Effect.gen(function* () {
+      const res = yield* HttpClientRequest.get(`https://free.ratesdb.com/v1/rates?from=${from}&to=${to}`).pipe(
+        HttpClient.execute,
+        Effect.flatMap((res: any) => res.json),
+        Effect.timeout('1 second'),
+        Effect.retry(Schedule.exponential(1_000).pipe(Schedule.compose(Schedule.recurs(3)))),
+        Effect.scoped,
+      );
+
+      return res.data.rates[to].toString();
+    }).pipe(Effect.provide(FetchHttpClient.layer)),
+});

package/src/example/index.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { default as fib$ } from './fib';
+import { default as reply$ } from './reply';
+import { default as sleep$ } from './sleep';
+
+export namespace Example {
+  export const fib = fib$;
+  export const reply = reply$;
+  export const sleep = sleep$;
+}

package/src/{examples → example}/reply.ts

@@ -2,12 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Console, Effect, Schema } from 'effect';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
 
-import { defineFunction } from '../handler';
+import { defineFunction } from '../sdk';
 
 export default defineFunction({
-  name: 'example.org/function/reply',
+  key: 'example.org/function/reply',
+  name: 'Reply',
   description: 'Function that echoes the input',
   inputSchema: Schema.Any,
   outputSchema: Schema.Any,

package/src/{examples → example}/sleep.ts

@@ -2,12 +2,14 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Effect, Schema } from 'effect';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
 
-import { defineFunction } from '../handler';
+import { defineFunction } from '../sdk';
 
 export default defineFunction({
-  name: 'example.org/function/sleep',
+  key: 'example.org/function/sleep',
+  name: 'Sleep',
   description: 'Function that sleeps for a given amount of time',
   inputSchema: Schema.Struct({
     duration: Schema.optional(Schema.Number).annotations({

package/src/index.ts

@@ -3,12 +3,8 @@
 //
 
 export * from './errors';
-export * from './handler';
-export * from './schema';
-export * from './trace';
-export * from './types';
-export * from './url';
-export * from './triggers';
+export * from './example';
+export * from './sdk';
 export * from './services';
-export * from './executor';
-export * as exampleFunctions from './examples';
+export * from './types';
+export * from './protocol';

package/src/{executor → protocol}/index.ts

@@ -2,4 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './executor';
+export * from './protocol';

package/src/protocol/protocol.test.ts

@@ -0,0 +1,59 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { FunctionError } from '../errors';
+import fibFunc from '../example/fib';
+import replyFunc from '../example/reply';
+
+import { wrapFunctionHandler } from './protocol';
+
+describe('wrapFunctionHandler', () => {
+  test('wraps reply function and executes handler', async ({ expect }) => {
+    const wrapped = wrapFunctionHandler(replyFunc);
+
+    expect(wrapped.meta.key).toBe('example.org/function/reply');
+    expect(wrapped.meta.name).toBe('Reply');
+
+    const testData = { message: 'hello' };
+    const result = await wrapped.handler({
+      data: testData,
+      context: {
+        services: {},
+      },
+    });
+
+    expect(result).toEqual(testData);
+  });
+
+  test('wraps fibonacci function with valid input', async ({ expect }) => {
+    const wrapped = wrapFunctionHandler(fibFunc);
+
+    expect(wrapped.meta.key).toBe('example.org/function/fib');
+    expect(wrapped.meta.name).toBe('Fibonacci');
+
+    const result = await wrapped.handler({
+      data: { iterations: 10 },
+      context: {
+        services: {},
+      },
+    });
+
+    expect(result).toEqual({ result: '55' });
+  });
+
+  test('throws FunctionError on invalid input schema for fibonacci', async ({ expect }) => {
+    const wrapped = wrapFunctionHandler(fibFunc);
+
+    await expect(
+      wrapped.handler({
+        data: { iterations: 'invalid' },
+        context: {
+          services: {},
+        },
+      }),
+    ).rejects.toThrow(FunctionError);
+  });
+});

package/src/protocol/protocol.ts

@@ -0,0 +1,145 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { AiService } from '@dxos/ai';
+import { Type } from '@dxos/echo';
+import { EchoClient } from '@dxos/echo-db';
+import { acquireReleaseResource } from '@dxos/effect';
+import { failedInvariant, invariant } from '@dxos/invariant';
+import { PublicKey } from '@dxos/keys';
+import { type FunctionProtocol } from '@dxos/protocols';
+
+import { FunctionError } from '../errors';
+import { FunctionDefinition, type FunctionServices } from '../sdk';
+import { CredentialsService, DatabaseService, FunctionInvocationService, TracingService } from '../services';
+import { QueueService } from '../services';
+
+/**
+ * Wraps a function handler made with `defineFunction` to a protocol that the functions-runtime expects.
+ */
+export const wrapFunctionHandler = (func: FunctionDefinition): FunctionProtocol.Func => {
+  if (!FunctionDefinition.isFunction(func)) {
+    throw new TypeError('Invalid function definition');
+  }
+
+  return {
+    meta: {
+      key: func.key,
+      name: func.name,
+      description: func.description,
+      inputSchema: Type.toJsonSchema(func.inputSchema),
+      outputSchema: func.outputSchema === undefined ? undefined : Type.toJsonSchema(func.outputSchema),
+      services: func.services,
+    },
+    handler: async ({ data, context }) => {
+      if (
+        (func.services.includes(DatabaseService.key) || func.services.includes(QueueService.key)) &&
+        (!context.services.dataService || !context.services.queryService)
+      ) {
+        throw new FunctionError({
+          message: 'Services not provided: dataService, queryService',
+        });
+      }
+
+      try {
+        if (!SchemaAST.isAnyKeyword(func.inputSchema.ast)) {
+          Schema.validateSync(func.inputSchema)(data);
+        }
+
+        let result = await func.handler({
+          // TODO(dmaretskyi): Fix the types.
+          context: context as any,
+          data,
+        });
+
+        if (Effect.isEffect(result)) {
+          result = await Effect.runPromise(
+            (result as Effect.Effect<unknown, unknown, FunctionServices>).pipe(
+              Effect.orDie,
+              Effect.provide(createServiceLayer(context)),
+            ),
+          );
+        }
+
+        if (func.outputSchema && !SchemaAST.isAnyKeyword(func.outputSchema.ast)) {
+          Schema.validateSync(func.outputSchema)(result);
+        }
+
+        return result;
+      } catch (error) {
+        if (FunctionError.is(error)) {
+          throw error;
+        } else {
+          throw new FunctionError({
+            cause: error,
+            context: { func: func.key },
+          });
+        }
+      }
+    },
+  };
+};
+
+/**
+ * Creates a layer of services for the function.
+ */
+const createServiceLayer = (context: FunctionProtocol.Context): Layer.Layer<FunctionServices> => {
+  return Layer.unwrapScoped(
+    Effect.gen(function* () {
+      let client: EchoClient | undefined;
+
+      if (context.services.dataService && context.services.queryService) {
+        client = yield* acquireReleaseResource(() => {
+          invariant(context.services.dataService && context.services.queryService);
+          // TODO(dmaretskyi): Queues service.
+          return new EchoClient().connectToService({
+            dataService: context.services.dataService,
+            queryService: context.services.queryService,
+            queueService: context.services.queueService,
+          });
+        });
+      }
+
+      const db =
+        client && context.spaceId
+          ? yield* acquireReleaseResource(() =>
+              client.constructDatabase({
+                spaceId: context.spaceId ?? failedInvariant(),
+                spaceKey: PublicKey.fromHex(context.spaceKey ?? failedInvariant('spaceKey missing in context')),
+                reactiveSchemaQuery: false,
+              }),
+            )
+          : undefined;
+
+      if (db) {
+        console.log('Setting space root', context.spaceRootUrl);
+        yield* Effect.promise(() =>
+          db!.setSpaceRoot(context.spaceRootUrl ?? failedInvariant('spaceRootUrl missing in context')),
+        );
+      }
+
+      const queues = client && context.spaceId ? client.constructQueueFactory(context.spaceId) : undefined;
+
+      const dbLayer = db ? DatabaseService.layer(db) : DatabaseService.notAvailable;
+      const queuesLayer = queues ? QueueService.layer(queues) : QueueService.notAvailable;
+      const credentials = dbLayer
+        ? CredentialsService.layerFromDatabase().pipe(Layer.provide(dbLayer))
+        : CredentialsService.configuredLayer([]);
+      const functionInvocationService = MockedFunctionInvocationService;
+      const aiService = AiService.notAvailable;
+      const tracing = TracingService.layerNoop;
+
+      return Layer.mergeAll(dbLayer, queuesLayer, credentials, functionInvocationService, aiService, tracing);
+    }),
+  );
+};
+
+const MockedFunctionInvocationService = Layer.succeed(FunctionInvocationService, {
+  invokeFunction: () => Effect.die('Calling functions from functions is not implemented yet.'),
+});

package/src/sdk.ts

@@ -0,0 +1,226 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import type * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { type AiService } from '@dxos/ai';
+import { Obj, Type } from '@dxos/echo';
+import { type DatabaseService } from '@dxos/echo-db';
+import { assertArgument, failedInvariant } from '@dxos/invariant';
+
+import {
+  type CredentialsService,
+  type FunctionInvocationService,
+  type QueueService,
+  type TracingService,
+} from './services';
+import { Function } from './types';
+import { getUserFunctionIdInMetadata, setUserFunctionIdInMetadata } from './types';
+
+// TODO(burdon): Model after http request. Ref Lambda/OpenFaaS.
+// https://docs.aws.amazon.com/lambda/latest/dg/typescript-handler.html
+// https://www.serverless.com/framework/docs/providers/aws/guide/serverless.yml/#functions
+// https://www.npmjs.com/package/aws-lambda
+
+/**
+ * Services that are provided at the function call site by the caller.
+ */
+export type InvocationServices = TracingService;
+
+/**
+ * Services that are available to invoked functions.
+ */
+export type FunctionServices =
+  | InvocationServices
+  | AiService.AiService
+  | CredentialsService
+  | DatabaseService
+  | QueueService
+  | FunctionInvocationService;
+
+/**
+ * Function handler.
+ */
+export type FunctionHandler<TData = {}, TOutput = any, S extends FunctionServices = FunctionServices> = (params: {
+  /**
+   * Context available to the function.
+   */
+  context: FunctionContext;
+
+  /**
+   * Data passed as the input to the function.
+   * Must match the function's input schema.
+   * This will be the payload from the trigger or other data passed into the function in a workflow.
+   */
+  data: TData;
+}) => TOutput | Promise<TOutput> | Effect.Effect<TOutput, any, S>;
+
+/**
+ * Function context.
+ */
+export interface FunctionContext {
+  // TODO(dmaretskyi): Consider what we should put into context.
+}
+
+const typeId = Symbol.for('@dxos/functions/FunctionDefinition');
+
+export type FunctionDefinition<T = any, O = any, S extends FunctionServices = FunctionServices> = {
+  [typeId]: true;
+  key: string;
+  name: string;
+  description?: string;
+  inputSchema: Schema.Schema<T, any>;
+  outputSchema?: Schema.Schema<O, any>;
+
+  /**
+   * Keys of the required services.
+   */
+  services: readonly string[];
+
+  handler: FunctionHandler<T, O, S>;
+  meta?: {
+    /**
+     * Tools that are projected from functions have this annotation.
+     *
+     * deployedFunctionId:
+     * - Backend deployment ID assigned by the EDGE function service (typically a UUID).
+     * - Used for remote invocation via `FunctionInvocationService` → `RemoteFunctionExecutionService`.
+     * - Persisted on the corresponding ECHO `Function.Function` object's metadata under the
+     *   `FUNCTIONS_META_KEY` and retrieved with `getUserFunctionIdInMetadata`.
+     */
+    deployedFunctionId?: string;
+  };
+};
+
+export declare namespace FunctionDefinition {
+  export type Any = FunctionDefinition<any, any, any>;
+  export type Input<T extends Any> = T extends FunctionDefinition<infer I, infer _O, infer _S> ? I : never;
+  export type Output<T extends Any> = T extends FunctionDefinition<infer _I, infer O, infer _S> ? O : never;
+  export type Services<T extends Any> = T extends FunctionDefinition<infer _I, infer _O, infer S> ? S : never;
+}
+
+export type FunctionProps<T, O> = {
+  key: string;
+  name: string;
+  description?: string;
+  inputSchema: Schema.Schema<T, any>;
+  outputSchema?: Schema.Schema<O, any>;
+  // TODO(dmaretskyi): This currently doesn't cause a compile-time error if the handler requests a service that is not specified
+  services?: readonly Context.Tag<any, any>[];
+
+  handler: FunctionHandler<T, O, FunctionServices>;
+};
+
+// TODO(dmaretskyi): Output type doesn't get typechecked.
+export const defineFunction: {
+  <I, O>(params: FunctionProps<I, O>): FunctionDefinition<I, O, FunctionServices>;
+} = ({ key, name, description, inputSchema, outputSchema = Schema.Any, handler, services }) => {
+  if (!Schema.isSchema(inputSchema)) {
+    throw new Error('Input schema must be a valid schema');
+  }
+  if (typeof handler !== 'function') {
+    throw new Error('Handler must be a function');
+  }
+
+  // Captures the function definition location.
+  const limit = Error.stackTraceLimit;
+  Error.stackTraceLimit = 2;
+  const traceError = new Error();
+  Error.stackTraceLimit = limit;
+  let cache: false | string = false;
+  const captureStackTrace = () => {
+    if (cache !== false) {
+      return cache;
+    }
+    if (traceError.stack !== undefined) {
+      const stack = traceError.stack.split('\n');
+      if (stack[2] !== undefined) {
+        cache = stack[2].trim();
+        return cache;
+      }
+    }
+  };
+
+  const handlerWithSpan = (...args: any[]) => {
+    const result = (handler as any)(...args);
+    if (Effect.isEffect(result)) {
+      return Effect.withSpan(result, `${key ?? name}`, {
+        captureStackTrace,
+      });
+    }
+    return result;
+  };
+
+  return {
+    [typeId]: true,
+    key,
+    name,
+    description,
+    inputSchema,
+    outputSchema,
+    handler: handlerWithSpan,
+    services: !services ? [] : getServiceKeys(services),
+  } satisfies FunctionDefinition.Any;
+};
+
+const getServiceKeys = (services: readonly Context.Tag<any, any>[]) => {
+  return services.map((tag: any) => {
+    if (typeof tag.key === 'string') {
+      return tag.key;
+    }
+    console.log(tag);
+    failedInvariant();
+  });
+};
+
+export const FunctionDefinition = {
+  make: defineFunction,
+  isFunction: (value: unknown): value is FunctionDefinition.Any => {
+    return typeof value === 'object' && value !== null && Symbol.for('@dxos/functions/FunctionDefinition') in value;
+  },
+  serialize: (functionDef: FunctionDefinition.Any): Function.Function => {
+    assertArgument(FunctionDefinition.isFunction(functionDef), 'functionDef');
+    return serializeFunction(functionDef);
+  },
+  deserialize: (functionObj: Function.Function): FunctionDefinition.Any => {
+    assertArgument(Obj.instanceOf(Function.Function, functionObj), 'functionObj');
+    return deserializeFunction(functionObj);
+  },
+};
+
+export const serializeFunction = (functionDef: FunctionDefinition.Any): Function.Function => {
+  const fn = Function.make({
+    key: functionDef.key,
+    name: functionDef.name,
+    version: '0.1.0',
+    description: functionDef.description,
+    inputSchema: Type.toJsonSchema(functionDef.inputSchema),
+    outputSchema: !functionDef.outputSchema ? undefined : Type.toJsonSchema(functionDef.outputSchema),
+    services: functionDef.services,
+  });
+  if (functionDef.meta?.deployedFunctionId) {
+    setUserFunctionIdInMetadata(Obj.getMeta(fn), functionDef.meta.deployedFunctionId);
+  }
+  return fn;
+};
+
+export const deserializeFunction = (functionObj: Function.Function): FunctionDefinition<unknown, unknown> => {
+  return {
+    [typeId]: true,
+    // TODO(dmaretskyi): Fix key.
+    key: functionObj.key ?? functionObj.name,
+    name: functionObj.name,
+    description: functionObj.description,
+    inputSchema: !functionObj.inputSchema ? Schema.Unknown : Type.toEffectSchema(functionObj.inputSchema),
+    outputSchema: !functionObj.outputSchema ? undefined : Type.toEffectSchema(functionObj.outputSchema),
+    // TODO(dmaretskyi): This should throw error.
+    handler: () => {},
+    services: functionObj.services ?? [],
+    meta: {
+      deployedFunctionId: getUserFunctionIdInMetadata(Obj.getMeta(functionObj)),
+    },
+  };
+};