@dxos/functions 0.8.4-main.ead640a → 0.8.4-main.ef1bc66f44

package/src/handler.ts

@@ -1,225 +0,0 @@
-//
-// 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 * as Types from 'effect/Types';
-
-import { Obj, Type } from '@dxos/echo';
-import { type HasId } from '@dxos/echo/internal';
-import { type EchoDatabase } from '@dxos/echo-db';
-import { assertArgument } from '@dxos/invariant';
-import { type DXN, type SpaceId } from '@dxos/keys';
-import { type QueryResult } from '@dxos/protocols';
-
-import { FunctionType } from './schema';
-import { type Services } from './services';
-import { getUserFunctionIdInMetadata, setUserFunctionIdInMetadata } from './url';
-
-// 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
-
-/**
- * Function handler.
- */
-export type FunctionHandler<TData = {}, TOutput = any> = (params: {
-  /**
-   * Services and 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, Services>;
-
-/**
- * Function context.
- */
-export interface FunctionContext {
-  /**
-   * Space from which the function was invoked.
-   */
-  space: SpaceAPI | undefined;
-
-  /**
-   * Resolves a service available to the function.
-   * @throws if the service is not available.
-   */
-  getService: <T extends Context.Tag<any, any>>(tag: T) => Context.Tag.Service<T>;
-
-  getSpace: (spaceId: SpaceId) => Promise<SpaceAPI>;
-}
-
-export interface FunctionContextAi {
-  // TODO(dmaretskyi): Refer to cloudflare AI docs for more comprehensive typedefs.
-  run(model: string, inputs: any, options?: any): Promise<any>;
-}
-
-//
-// API.
-//
-
-// TODO(dmaretskyi): Temporary API to get the queues working.
-// TODO(dmaretskyi): To be replaced with integrating queues into echo.
-export interface QueuesAPI {
-  queryQueue(queue: DXN, options?: {}): Promise<QueryResult>;
-  insertIntoQueue(queue: DXN, objects: HasId[]): Promise<void>;
-}
-
-/**
- * Space interface available to functions.
- */
-export interface SpaceAPI {
-  get id(): SpaceId;
-  get db(): EchoDatabase;
-
-  // TODO(dmaretskyi): Align with echo api: queues.get(id).append(items);
-  get queues(): QueuesAPI;
-}
-
-// TODO(wittjosiah): Queues are incompatible.
-const __assertFunctionSpaceIsCompatibleWithTheClientSpace = () => {
-  // const _: SpaceAPI = {} as Space;
-};
-
-const typeId = Symbol.for('@dxos/functions/FunctionDefinition');
-
-export type FunctionDefinition<T = any, O = any> = {
-  [typeId]: true;
-  key: string;
-  name: string;
-  description?: string;
-  inputSchema: Schema.Schema<T, any>;
-  outputSchema?: Schema.Schema<O, any>;
-  handler: FunctionHandler<T, O>;
-  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 `FunctionType` object's metadata under the
-     *   `FUNCTIONS_META_KEY` and retrieved with `getUserFunctionIdInMetadata`.
-     */
-    deployedFunctionId?: string;
-  };
-};
-
-// TODO(dmaretskyi): Output type doesn't get typechecked.
-export const defineFunction: {
-  <I, O>(params: {
-    key: string;
-    name: string;
-    description?: string;
-    inputSchema: Schema.Schema<I, any>;
-    outputSchema?: Schema.Schema<O, any>;
-    handler: Types.NoInfer<FunctionHandler<I, O>>;
-  }): FunctionDefinition<I, O>;
-} = ({ key, name, description, inputSchema, outputSchema = Schema.Any, handler }) => {
-  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,
-  };
-};
-
-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): FunctionType => {
-    assertArgument(FunctionDefinition.isFunction(functionDef), 'functionDef');
-    return serializeFunction(functionDef);
-  },
-  deserialize: (functionObj: FunctionType): FunctionDefinition.Any => {
-    assertArgument(Obj.instanceOf(FunctionType, functionObj), 'functionObj');
-    return deserializeFunction(functionObj);
-  },
-};
-export declare namespace FunctionDefinition {
-  export type Any = FunctionDefinition<any, any>;
-  export type Input<T extends FunctionDefinition> = T extends FunctionDefinition<infer I, any> ? I : never;
-  export type Output<T extends FunctionDefinition> = T extends FunctionDefinition<any, infer O> ? O : never;
-}
-
-export const serializeFunction = (functionDef: FunctionDefinition<any, any>): FunctionType => {
-  const fn = Obj.make(FunctionType, {
-    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),
-  });
-  if (functionDef.meta?.deployedFunctionId) {
-    setUserFunctionIdInMetadata(Obj.getMeta(fn), functionDef.meta.deployedFunctionId);
-  }
-  return fn;
-};
-
-export const deserializeFunction = (functionObj: FunctionType): 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: () => {},
-    meta: {
-      deployedFunctionId: getUserFunctionIdInMetadata(Obj.getMeta(functionObj)),
-    },
-  };
-};

package/src/schema.ts

@@ -1,71 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import * as Schema from 'effect/Schema';
-
-import { Type } from '@dxos/echo';
-import { JsonSchemaType, LabelAnnotation, Ref } from '@dxos/echo/internal';
-import { DataType } from '@dxos/schema';
-
-// TODO(burdon): Create namespace and remove Type suffix.
-
-/**
- * Source script.
- */
-export const ScriptType = Schema.Struct({
-  name: Schema.optional(Schema.String),
-  description: Schema.optional(Schema.String),
-  // TODO(burdon): Change to hash of deployed content.
-  // Whether source has changed since last deploy.
-  changed: Schema.optional(Schema.Boolean),
-  source: Ref(DataType.Text),
-}).pipe(
-  Type.Obj({
-    typename: 'dxos.org/type/Script',
-    version: '0.1.0',
-  }),
-  LabelAnnotation.set(['name']),
-);
-
-export interface ScriptType extends Schema.Schema.Type<typeof ScriptType> {}
-
-/**
- * Function deployment.
- */
-export const FunctionType = Schema.Struct({
-  /**
-   * Global registry ID.
-   * NOTE: The `key` property refers to the original registry entry.
-   */
-  // TODO(burdon): Create Format type for DXN-like ids, such as this and schema type.
-  // TODO(dmaretskyi): Consider making it part of ECHO meta.
-  // TODO(dmaretskyi): Make required.
-  key: Schema.optional(Schema.String).annotations({
-    description: 'Unique registration key for the blueprint',
-  }),
-
-  // TODO(burdon): Rename to id/uri?
-  name: Schema.NonEmptyString,
-  version: Schema.String,
-
-  description: Schema.optional(Schema.String),
-
-  // Reference to a source script if it exists within ECHO.
-  // TODO(burdon): Don't ref ScriptType directly (core).
-  source: Schema.optional(Ref(ScriptType)),
-
-  inputSchema: Schema.optional(JsonSchemaType),
-  outputSchema: Schema.optional(JsonSchemaType),
-
-  // Local binding to a function name.
-  binding: Schema.optional(Schema.String),
-}).pipe(
-  Type.Obj({
-    typename: 'dxos.org/type/Function',
-    version: '0.1.0',
-  }),
-  LabelAnnotation.set(['name']),
-);
-
-export interface FunctionType extends Schema.Schema.Type<typeof FunctionType> {}

package/src/services/database.ts

@@ -1,175 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import * as Context from 'effect/Context';
-import * as Effect from 'effect/Effect';
-import * as Layer from 'effect/Layer';
-import * as Option from 'effect/Option';
-import type * as Schema from 'effect/Schema';
-
-import {
-  type Filter,
-  type Live,
-  Obj,
-  ObjectNotFoundError,
-  type Query,
-  type Ref,
-  type Relation,
-  type Type,
-} from '@dxos/echo';
-import type { EchoSchema } from '@dxos/echo/internal';
-import type { EchoDatabase, FlushOptions, OneShotQueryResult, QueryResult, SchemaRegistryQuery } from '@dxos/echo-db';
-import type { SchemaRegistryPreparedQuery } from '@dxos/echo-db';
-import { promiseWithCauseCapture } from '@dxos/effect';
-import { invariant } from '@dxos/invariant';
-import type { DXN } from '@dxos/keys';
-
-export class DatabaseService extends Context.Tag('@dxos/functions/DatabaseService')<
-  DatabaseService,
-  {
-    readonly db: EchoDatabase;
-  }
->() {
-  static notAvailable = Layer.succeed(DatabaseService, {
-    get db(): EchoDatabase {
-      throw new Error('Database not available');
-    },
-  });
-
-  static make = (db: EchoDatabase): Context.Tag.Service<DatabaseService> => {
-    return {
-      get db() {
-        return db;
-      },
-    };
-  };
-
-  static layer = (db: EchoDatabase): Layer.Layer<DatabaseService> => {
-    return Layer.succeed(DatabaseService, DatabaseService.make(db));
-  };
-
-  /**
-   * Resolves an object by its DXN.
-   */
-  static resolve: {
-    // No type check.
-    (dxn: DXN): Effect.Effect<Obj.Any | Relation.Any, never, DatabaseService>;
-    // Check matches schema.
-    <S extends Type.Obj.Any | Type.Relation.Any>(
-      dxn: DXN,
-      schema: S,
-    ): Effect.Effect<Schema.Schema.Type<S>, ObjectNotFoundError, DatabaseService>;
-  } = (<S extends Type.Obj.Any | Type.Relation.Any>(
-    dxn: DXN,
-    schema?: S,
-  ): Effect.Effect<Schema.Schema.Type<S>, ObjectNotFoundError, DatabaseService> =>
-    Effect.gen(function* () {
-      const { db } = yield* DatabaseService;
-      const object = yield* promiseWithCauseCapture(() =>
-        db.graph
-          .createRefResolver({
-            context: {
-              space: db.spaceId,
-            },
-          })
-          .resolve(dxn),
-      );
-
-      if (!object) {
-        return yield* Effect.fail(new ObjectNotFoundError(dxn));
-      }
-      invariant(!schema || Obj.instanceOf(schema, object), 'Object type mismatch.');
-      return object as any;
-    })) as any;
-
-  /**
-   * Loads an object reference.
-   */
-  static load: <T>(ref: Ref.Ref<T>) => Effect.Effect<T, ObjectNotFoundError, never> = Effect.fn(function* (ref) {
-    const object = yield* promiseWithCauseCapture(() => ref.tryLoad());
-    if (!object) {
-      return yield* Effect.fail(new ObjectNotFoundError(ref.dxn));
-    }
-    return object;
-  });
-
-  /**
-   * Loads an object reference option.
-   */
-  // TODO(burdon): Option?
-  static loadOption: <T>(ref: Ref.Ref<T>) => Effect.Effect<Option.Option<T>, never, never> = Effect.fn(function* (ref) {
-    const object = yield* DatabaseService.load(ref).pipe(
-      Effect.catchTag('OBJECT_NOT_FOUND', () => Effect.succeed(undefined)),
-    );
-    return Option.fromNullable(object);
-  });
-
-  // TODO(burdon): Can we create a proxy for the following methods on EchoDatabase? Use @inheritDoc?
-  // TODO(burdon): Figure out how to chain query().run();
-
-  /**
-   * @link EchoDatabase.add
-   */
-  static add = <T extends Obj.Any | Relation.Any>(obj: T): Effect.Effect<T, never, DatabaseService> =>
-    DatabaseService.pipe(Effect.map(({ db }) => db.add(obj)));
-
-  /**
-   * @link EchoDatabase.remove
-   */
-  static remove = <T extends Obj.Any | Relation.Any>(obj: T): Effect.Effect<void, never, DatabaseService> =>
-    DatabaseService.pipe(Effect.map(({ db }) => db.remove(obj)));
-
-  /**
-   * @link EchoDatabase.flush
-   */
-  static flush = (opts?: FlushOptions) =>
-    DatabaseService.pipe(Effect.flatMap(({ db }) => promiseWithCauseCapture(() => db.flush(opts))));
-
-  /**
-   * @link EchoDatabase.getObjectById
-   */
-  static getObjectById = <T extends Obj.Any | Relation.Any>(
-    id: string,
-  ): Effect.Effect<Live<T> | undefined, never, DatabaseService> => {
-    return DatabaseService.pipe(Effect.map(({ db }) => db.getObjectById(id)));
-  };
-
-  /**
-   * Creates a `QueryResult` object that can be subscribed to.
-   */
-  static query: {
-    <Q extends Query.Any>(query: Q): Effect.Effect<QueryResult<Live<Query.Type<Q>>>, never, DatabaseService>;
-    <F extends Filter.Any>(filter: F): Effect.Effect<QueryResult<Live<Filter.Type<F>>>, never, DatabaseService>;
-  } = (queryOrFilter: Query.Any | Filter.Any) =>
-    DatabaseService.pipe(
-      Effect.map(({ db }) => db.query(queryOrFilter as any)),
-      Effect.withSpan('DatabaseService.query'),
-    );
-
-  /**
-   * Executes the query once and returns the results.
-   */
-  static runQuery: {
-    <Q extends Query.Any>(query: Q): Effect.Effect<OneShotQueryResult<Live<Query.Type<Q>>>, never, DatabaseService>;
-    <F extends Filter.Any>(filter: F): Effect.Effect<OneShotQueryResult<Live<Filter.Type<F>>>, never, DatabaseService>;
-  } = (queryOrFilter: Query.Any | Filter.Any) =>
-    DatabaseService.query(queryOrFilter as any).pipe(
-      Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())),
-    );
-
-  static schemaQuery = <Q extends SchemaRegistryQuery>(
-    query: Q,
-  ): Effect.Effect<SchemaRegistryPreparedQuery<EchoSchema>, never, DatabaseService> =>
-    DatabaseService.pipe(
-      Effect.map(({ db }) => db.schemaRegistry.query(query)),
-      Effect.withSpan('DatabaseService.schemaQuery'),
-    );
-
-  static runSchemaQuery = <Q extends SchemaRegistryQuery>(
-    query: Q,
-  ): Effect.Effect<EchoSchema[], never, DatabaseService> =>
-    DatabaseService.schemaQuery(query).pipe(
-      Effect.flatMap((queryResult) => promiseWithCauseCapture(() => queryResult.run())),
-    );
-}

package/src/services/function-invocation-service.test.ts

@@ -1,81 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { describe, expect, it } from '@effect/vitest';
-import * as Effect from 'effect/Effect';
-import * as Layer from 'effect/Layer';
-import * as Schema from 'effect/Schema';
-
-import { AiService } from '@dxos/ai';
-
-import { defineFunction } from '../handler';
-import { TestDatabaseLayer } from '../testing';
-
-import { FunctionInvocationService } from './function-invocation-service';
-import { FunctionImplementationResolver } from './local-function-execution';
-
-const TestLayer = Layer.mergeAll(AiService.model('@anthropic/claude-opus-4-0')).pipe(
-  Layer.provideMerge(
-    Layer.mergeAll(
-      TestDatabaseLayer({
-        indexing: { vector: true },
-        types: [],
-      }),
-      FunctionInvocationService.layer,
-    ),
-  ),
-);
-
-describe('FunctionInvocationService', () => {
-  it(
-    'should be defined',
-    Effect.fnUntraced(function* () {
-      const service = yield* FunctionInvocationService;
-      expect(service).toBeDefined();
-    }, Effect.provide(TestLayer)),
-  );
-
-  it(
-    'routes to local when implementation is available',
-    Effect.fnUntraced(function* () {
-      const add = defineFunction({
-        key: 'example.org/function/add',
-        name: 'add',
-        inputSchema: Schema.Struct({ a: Schema.Number, b: Schema.Number }),
-        outputSchema: Schema.Number,
-        handler: ({ data }) => data.a + data.b,
-      });
-
-      const layer = TestLayer.pipe(Layer.provideMerge(FunctionImplementationResolver.layerTest({ functions: [add] })));
-
-      const result = yield* Effect.gen(function* () {
-        return yield* FunctionInvocationService.invokeFunction(add, { a: 2, b: 3 });
-      }).pipe(Effect.provide(layer));
-
-      expect(result).toEqual(5);
-    }),
-  );
-
-  it(
-    'routes to remote when no local implementation is found',
-    Effect.fnUntraced(function* () {
-      // This function is not deployed, so mock layer will be used.
-      const echo = defineFunction({
-        key: 'example.org/function/echo',
-        name: 'function-that-is-deployed',
-        inputSchema: Schema.Unknown,
-        outputSchema: Schema.Unknown,
-        handler: () => {},
-      });
-
-      // No resolver provided → resolveFunctionImplementation will fail → remote path is used.
-      const result = yield* Effect.gen(function* () {
-        return yield* FunctionInvocationService.invokeFunction(echo, { hello: 'world' });
-      }).pipe(Effect.provide(TestLayer));
-
-      // RemoteFunctionExecutionService.mock echos input back.
-      expect(result).toEqual({ hello: 'world', resolved: 'remote' });
-    }),
-  );
-});