@dxos/functions 0.8.1 → 0.8.2-main.2f9c567

package/src/schema.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Schema } from 'effect';
+
+import { EchoObject, JsonSchemaType, LabelAnnotationId, Ref, TypedObject } from '@dxos/echo-schema';
+import { DataType } from '@dxos/schema';
+
+/**
+ * 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),
+})
+  .annotations({ [LabelAnnotationId]: 'name' })
+  .pipe(
+    EchoObject({
+      typename: 'dxos.org/type/Script',
+      version: '0.1.0',
+    }),
+  );
+
+export type ScriptType = Schema.Schema.Type<typeof ScriptType>;
+
+/**
+ * Function deployment.
+ */
+export class FunctionType extends TypedObject({
+  typename: 'dxos.org/type/Function',
+  version: '0.1.0',
+})({
+  // 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),
+}) {}

package/src/{types/trace.ts → trace.ts}

@@ -2,7 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
-import { EchoObject, Expando, ObjectId, Ref, S } from '@dxos/echo-schema';
+import { Schema } from 'effect';
+
+import { EchoObject, Expando, ObjectId, Ref } from '@dxos/echo-schema';
 import { log } from '@dxos/log';
 
 import { FunctionTrigger, type FunctionTriggerType } from './types';
@@ -19,20 +21,20 @@ export enum InvocationTraceEventType {
   END = 'end',
 }
 
-export const TraceEventException = S.Struct({
-  timestampMs: S.Number,
-  message: S.String,
-  name: S.String,
-  stack: S.optional(S.String),
+export const TraceEventException = Schema.Struct({
+  timestampMs: Schema.Number,
+  message: Schema.String,
+  name: Schema.String,
+  stack: Schema.optional(Schema.String),
 });
-export type TraceEventException = S.Schema.Type<typeof TraceEventException>;
+export type TraceEventException = Schema.Schema.Type<typeof TraceEventException>;
 
-export const InvocationTraceStartEvent = S.Struct({
+export const InvocationTraceStartEvent = Schema.Struct({
   /**
    * Queue message id.
    */
   id: ObjectId,
-  type: S.Literal(InvocationTraceEventType.START),
+  type: Schema.Literal(InvocationTraceEventType.START),
   /**
    * Invocation id, the same for invocation start and end events.
    */
@@ -40,12 +42,12 @@ export const InvocationTraceStartEvent = S.Struct({
   /**
    * Event generation time.
    */
-  timestampMs: S.Number,
+  timestampMs: Schema.Number,
   /**
    * Data passed to function / workflow as an argument.
    */
   // TODO(burdon): Input schema?
-  input: S.Object,
+  input: Schema.Object,
   /**
    * Queue DXN for function/workflow invocation events.
    */
@@ -58,17 +60,17 @@ export const InvocationTraceStartEvent = S.Struct({
   /**
    * Present for automatic invocations.
    */
-  trigger: S.optional(Ref(FunctionTrigger)),
+  trigger: Schema.optional(Ref(FunctionTrigger)),
 }).pipe(EchoObject({ typename: 'dxos.org/type/InvocationTraceStart', version: '0.1.0' }));
 
-export type InvocationTraceStartEvent = S.Schema.Type<typeof InvocationTraceStartEvent>;
+export type InvocationTraceStartEvent = Schema.Schema.Type<typeof InvocationTraceStartEvent>;
 
-export const InvocationTraceEndEvent = S.Struct({
+export const InvocationTraceEndEvent = Schema.Struct({
   /**
    * Trace event id.
    */
   id: ObjectId,
-  type: S.Literal(InvocationTraceEventType.END),
+  type: Schema.Literal(InvocationTraceEventType.END),
   /**
    * Invocation id, will be the same for invocation start and end.
    */
@@ -77,36 +79,36 @@ export const InvocationTraceEndEvent = S.Struct({
    * Event generation time.
    */
   // TODO(burdon): Remove ms suffix.
-  timestampMs: S.Number,
-  outcome: S.Enums(InvocationOutcome),
-  exception: S.optional(TraceEventException),
+  timestampMs: Schema.Number,
+  outcome: Schema.Enums(InvocationOutcome),
+  exception: Schema.optional(TraceEventException),
 }).pipe(EchoObject({ typename: 'dxos.org/type/InvocationTraceEnd', version: '0.1.0' }));
 
-export type InvocationTraceEndEvent = S.Schema.Type<typeof InvocationTraceEndEvent>;
+export type InvocationTraceEndEvent = Schema.Schema.Type<typeof InvocationTraceEndEvent>;
 
 export type InvocationTraceEvent = InvocationTraceStartEvent | InvocationTraceEndEvent;
 
-export const TraceEventLog = S.Struct({
-  timestampMs: S.Number,
-  level: S.String,
-  message: S.String,
-  context: S.optional(S.Object),
+export const TraceEventLog = Schema.Struct({
+  timestampMs: Schema.Number,
+  level: Schema.String,
+  message: Schema.String,
+  context: Schema.optional(Schema.Object),
 });
 
-export const TraceEvent = S.Struct({
+export const TraceEvent = Schema.Struct({
   id: ObjectId,
   // TODO(burdon): Need enum/numeric result (not string).
-  outcome: S.String,
-  truncated: S.Boolean,
+  outcome: Schema.String,
+  truncated: Schema.Boolean,
   /**
    * Time when the event was persisted.
    */
-  ingestionTimestampMs: S.Number,
-  logs: S.Array(TraceEventLog),
-  exceptions: S.Array(TraceEventException),
+  ingestionTimestampMs: Schema.Number,
+  logs: Schema.Array(TraceEventLog),
+  exceptions: Schema.Array(TraceEventException),
 }).pipe(EchoObject({ typename: 'dxos.org/type/TraceEvent', version: '0.1.0' }));
 
-export type TraceEvent = S.Schema.Type<typeof TraceEvent>;
+export type TraceEvent = Schema.Schema.Type<typeof TraceEvent>;
 
 /**
  * Deprecated InvocationTrace event format.

package/src/translations.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-import { ScriptType } from './types';
+import { ScriptType } from './schema';
 
 export default [
   {

package/src/types.ts

@@ -0,0 +1,214 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Schema as S, SchemaAST } from 'effect';
+
+import { Expando, OptionsAnnotationId, TypedObject, DXN, Ref, RawObject } from '@dxos/echo-schema';
+
+import { FunctionType } from './schema';
+
+/**
+ * Type discriminator for TriggerType.
+ * Every spec has a type field of type TriggerKind that we can use to understand which type we're working with.
+ * https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions
+ */
+export enum TriggerKind {
+  Timer = 'timer',
+  Webhook = 'webhook',
+  Subscription = 'subscription',
+  Email = 'email',
+  Queue = 'queue',
+}
+
+// TODO(burdon): Rename prop kind.
+const typeLiteralAnnotations = { [SchemaAST.TitleAnnotationId]: 'Type' };
+
+/**
+ * Cron timer.
+ */
+const TimerTriggerSchema = S.Struct({
+  type: S.Literal(TriggerKind.Timer).annotations(typeLiteralAnnotations),
+  cron: S.String.annotations({
+    [SchemaAST.TitleAnnotationId]: 'Cron',
+    [SchemaAST.ExamplesAnnotationId]: ['0 0 * * *'],
+  }),
+}).pipe(S.mutable);
+
+export type TimerTrigger = S.Schema.Type<typeof TimerTriggerSchema>;
+
+const EmailTriggerSchema = S.Struct({
+  type: S.Literal(TriggerKind.Email).annotations(typeLiteralAnnotations),
+}).pipe(S.mutable);
+
+export type EmailTrigger = S.Schema.Type<typeof EmailTriggerSchema>;
+
+const QueueTriggerSchema = S.Struct({
+  type: S.Literal(TriggerKind.Queue).annotations(typeLiteralAnnotations),
+  queue: DXN,
+}).pipe(S.mutable);
+
+export type QueueTrigger = S.Schema.Type<typeof QueueTriggerSchema>;
+
+/**
+ * Webhook.
+ */
+const WebhookTriggerSchema = S.Struct({
+  type: S.Literal(TriggerKind.Webhook).annotations(typeLiteralAnnotations),
+  method: S.optional(
+    S.String.annotations({
+      [SchemaAST.TitleAnnotationId]: 'Method',
+      [OptionsAnnotationId]: ['GET', 'POST'],
+    }),
+  ),
+  port: S.optional(
+    S.Number.annotations({
+      [SchemaAST.TitleAnnotationId]: 'Port',
+    }),
+  ),
+}).pipe(S.mutable);
+
+export type WebhookTrigger = S.Schema.Type<typeof WebhookTriggerSchema>;
+
+// TODO(burdon): Use ECHO definition (from https://github.com/dxos/dxos/pull/8233).
+const QuerySchema = S.Struct({
+  type: S.optional(S.String.annotations({ [SchemaAST.TitleAnnotationId]: 'Type' })),
+  props: S.optional(S.Record({ key: S.String, value: S.Any })),
+}).annotations({ [SchemaAST.TitleAnnotationId]: 'Query' });
+
+/**
+ * Subscription.
+ */
+const SubscriptionTriggerSchema = S.Struct({
+  type: S.Literal(TriggerKind.Subscription).annotations(typeLiteralAnnotations),
+  // TODO(burdon): Define query DSL (from ECHO). Reconcile with Table.Query.
+  filter: QuerySchema,
+  options: S.optional(
+    S.Struct({
+      // Watch changes to object (not just creation).
+      deep: S.optional(S.Boolean.annotations({ [SchemaAST.TitleAnnotationId]: 'Nested' })),
+      // Debounce changes (delay in ms).
+      delay: S.optional(S.Number.annotations({ [SchemaAST.TitleAnnotationId]: 'Delay' })),
+    }).annotations({ [SchemaAST.TitleAnnotationId]: 'Options' }),
+  ),
+}).pipe(S.mutable);
+
+export type SubscriptionTrigger = S.Schema.Type<typeof SubscriptionTriggerSchema>;
+
+/**
+ * Trigger schema (discriminated union).
+ */
+export const TriggerSchema = S.Union(
+  TimerTriggerSchema,
+  WebhookTriggerSchema,
+  SubscriptionTriggerSchema,
+  EmailTriggerSchema,
+  QueueTriggerSchema,
+).annotations({
+  [SchemaAST.TitleAnnotationId]: 'Trigger',
+});
+export type TriggerType = S.Schema.Type<typeof TriggerSchema>;
+
+export type EventType =
+  | EmailTriggerOutput
+  | WebhookTriggerOutput
+  | QueueTriggerOutput
+  | SubscriptionTriggerOutput
+  | TimerTriggerOutput;
+
+// TODO(burdon): Reuse trigger schema from @dxos/functions (TriggerType).
+export const EmailTriggerOutput = S.mutable(
+  S.Struct({
+    from: S.String,
+    to: S.String,
+    subject: S.String,
+    created: S.String,
+    body: S.String,
+  }),
+);
+export type EmailTriggerOutput = S.Schema.Type<typeof EmailTriggerOutput>;
+
+export const WebhookTriggerOutput = S.mutable(
+  S.Struct({
+    url: S.String,
+    method: S.Literal('GET', 'POST'),
+    headers: S.Record({ key: S.String, value: S.String }),
+    bodyText: S.String,
+  }),
+);
+export type WebhookTriggerOutput = S.Schema.Type<typeof WebhookTriggerOutput>;
+
+export const QueueTriggerOutput = S.mutable(
+  S.Struct({
+    queue: DXN,
+    item: S.Any,
+    cursor: S.String,
+  }),
+);
+export type QueueTriggerOutput = S.Schema.Type<typeof QueueTriggerOutput>;
+
+export const SubscriptionTriggerOutput = S.mutable(S.Struct({ type: S.String, changedObjectId: S.String }));
+export type SubscriptionTriggerOutput = S.Schema.Type<typeof SubscriptionTriggerOutput>;
+
+export const TimerTriggerOutput = S.mutable(S.Struct({ tick: S.Number }));
+export type TimerTriggerOutput = S.Schema.Type<typeof TimerTriggerOutput>;
+
+/**
+ * Function trigger.
+ * Function is invoked with the `payload` passed as input data.
+ * The event that triggers the function is available in the function context.
+ */
+export const FunctionTriggerSchema = S.Struct({
+  /**
+   * Function or workflow to invoke.
+   */
+  // TODO(dmaretskyi): Can be a Ref(FunctionType) or Ref(ComputeGraphType).
+  function: S.optional(Ref(Expando).annotations({ [SchemaAST.TitleAnnotationId]: 'Function' })),
+
+  /**
+   * Only used for workflows.
+   * Specifies the input node in the circuit.
+   * @deprecated Remove and enforce a single input node in all compute graphs.
+   */
+  inputNodeId: S.optional(S.String.annotations({ [SchemaAST.TitleAnnotationId]: 'Input Node ID' })),
+
+  enabled: S.optional(S.Boolean.annotations({ [SchemaAST.TitleAnnotationId]: 'Enabled' })),
+
+  spec: S.optional(TriggerSchema),
+
+  /**
+   * Passed as the input data to the function.
+   * Must match the function's input schema.
+   *
+   * @example
+   * {
+   *   item: '{{$.trigger.event}}',
+   *   instructions: 'Summarize and perform entity-extraction'
+   *   mailbox: { '/': 'dxn:echo:AAA:ZZZ' }
+   * }
+   */
+  input: S.optional(S.mutable(S.Record({ key: S.String, value: S.Any }))),
+});
+
+export type FunctionTriggerType = S.Schema.Type<typeof FunctionTriggerSchema>;
+
+/**
+ * Function trigger.
+ */
+export class FunctionTrigger extends TypedObject({
+  typename: 'dxos.org/type/FunctionTrigger',
+  version: '0.1.0',
+})(FunctionTriggerSchema.fields) {}
+
+// TODO(wittjosiah): Remove?
+
+/**
+ * Function manifest file.
+ */
+export const FunctionManifestSchema = S.Struct({
+  functions: S.optional(S.mutable(S.Array(RawObject(FunctionType)))),
+  triggers: S.optional(S.mutable(S.Array(RawObject(FunctionTrigger)))),
+});
+export type FunctionManifest = S.Schema.Type<typeof FunctionManifestSchema>;
+
+export const FUNCTION_TYPES = [FunctionType, FunctionTrigger];

package/src/{types/url.ts → url.ts}

@@ -29,6 +29,11 @@ export const setUserFunctionUrlInMetadata = (meta: ObjectMeta, functionUrl: stri
   }
 };
 
+/**
+ * NOTE: functionId is backend ID, not ECHO object id.
+ */
+export const makeFunctionUrl = (spaceId: SpaceId, fn: { functionId: string }) => `/${spaceId}/${fn.functionId}`;
+
 export const getInvocationUrl = (functionUrl: string, edgeUrl: string, options: InvocationOptions = {}) => {
   const baseUrl = new URL('functions/', edgeUrl);