@dxos/compute 0.8.4-main.9be5663bfe → 0.8.4-main.abd8ff62ef

package/src/Trigger.ts

@@ -0,0 +1,207 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { Annotation, Feed, Obj, QueryAST, Ref, Type, type Query } from '@dxos/echo';
+import { OptionsAnnotationId, SystemTypeAnnotation } from '@dxos/echo/internal';
+import { failedInvariant } from '@dxos/invariant';
+import { DXN } from '@dxos/keys';
+
+/**
+ * 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 const Kinds = ['email', 'queue', 'subscription', 'timer', 'webhook'] as const;
+export type Kind = (typeof Kinds)[number];
+
+const kindLiteralAnnotations = { title: 'Kind' };
+
+export const EmailSpec = Schema.Struct({
+  kind: Schema.Literal('email').annotations(kindLiteralAnnotations),
+});
+export type EmailSpec = Schema.Schema.Type<typeof EmailSpec>;
+
+/**
+ * Construct an Email trigger spec.
+ */
+export const specEmail = (): EmailSpec => ({ kind: 'email' });
+
+// TODO(burdon): Change to Feed.
+// TODO(wittjosiah): Remove. Migrate to Subscription triggers once EDGE supports them for feed queries.
+export const QueueSpec = Schema.Struct({
+  kind: Schema.Literal('queue').annotations(kindLiteralAnnotations),
+
+  // TODO(dmaretskyi): Rename to `feed` and change to a reference.
+  queue: DXN.Schema,
+});
+export type QueueSpec = Schema.Schema.Type<typeof QueueSpec>;
+
+/**
+ * Construct a Queue trigger spec from a queue DXN string.
+ */
+export const specQueue = (queueDxn: string): QueueSpec => ({
+  kind: 'queue',
+  queue: queueDxn,
+});
+
+/**
+ * Construct a Queue trigger spec from a Feed object.
+ */
+export const specFeed = (feed: Feed.Feed): QueueSpec =>
+  specQueue(Feed.getQueueDxn(feed)?.toString() ?? failedInvariant(new Error('Could not extract DXN from feed')));
+
+/**
+ * Subscription.
+ */
+export const SubscriptionSpec = Schema.Struct({
+  kind: Schema.Literal('subscription').annotations(kindLiteralAnnotations),
+  query: Schema.Struct({
+    raw: Schema.optional(Schema.String.annotations({ title: 'Query' })),
+    ast: QueryAST.Query,
+  }),
+  options: Schema.optional(
+    Schema.Struct({
+      // Watch changes to object (not just creation).
+      deep: Schema.optional(Schema.Boolean.annotations({ title: 'Nested' })),
+      // Debounce changes (delay in ms).
+      delay: Schema.optional(Schema.Number.annotations({ title: 'Delay' })),
+    }).annotations({ title: 'Options' }),
+  ),
+});
+export type SubscriptionSpec = Schema.Schema.Type<typeof SubscriptionSpec>;
+
+/**
+ * Construct a Subscription trigger spec from a Query object.
+ */
+export const specSubscription = (
+  query: Query.Query<any>,
+  options?: { deep?: boolean; delay?: number },
+): SubscriptionSpec => ({
+  kind: 'subscription',
+  query: {
+    ast: query.ast,
+  },
+  options: options
+    ? {
+        deep: options.deep,
+        delay: options.delay,
+      }
+    : undefined,
+});
+
+/**
+ * Cron timer.
+ */
+export const TimerSpec = Schema.Struct({
+  kind: Schema.Literal('timer').annotations(kindLiteralAnnotations),
+  cron: Schema.String.annotations({
+    title: 'Cron',
+    [SchemaAST.ExamplesAnnotationId]: ['0 0 * * *'],
+  }),
+});
+export type TimerSpec = Schema.Schema.Type<typeof TimerSpec>;
+
+/**
+ * Construct a Timer trigger spec from a cron string.
+ */
+export const specTimer = (cron: string): TimerSpec => ({ kind: 'timer', cron });
+
+/**
+ * Webhook.
+ */
+export const WebhookSpec = Schema.Struct({
+  kind: Schema.Literal('webhook').annotations(kindLiteralAnnotations),
+  method: Schema.optional(
+    Schema.String.annotations({
+      title: 'Method',
+      [OptionsAnnotationId]: ['GET', 'POST'],
+    }),
+  ),
+  port: Schema.optional(
+    Schema.Number.annotations({
+      title: 'Port',
+    }),
+  ),
+});
+export type WebhookSpec = Schema.Schema.Type<typeof WebhookSpec>;
+
+/**
+ * Construct a Webhook trigger spec from a method and port.
+ */
+export const specWebhook = (opts?: { method?: string; port?: number }): WebhookSpec => ({
+  kind: 'webhook',
+  method: opts?.method,
+  port: opts?.port,
+});
+
+/**
+ * Trigger schema.
+ */
+export const Spec = Schema.Union(EmailSpec, QueueSpec, SubscriptionSpec, TimerSpec, WebhookSpec).annotations({
+  title: 'Trigger',
+});
+export type Spec = Schema.Schema.Type<typeof Spec>;
+
+/**
+ * Function trigger.
+ * Function is invoked with the `payload` passed as input data.
+ * The event that triggers the function is available in the function context.
+ */
+const TriggerSchema = Schema.Struct({
+  /**
+   * Function or workflow to invoke.
+   */
+  // TODO(dmaretskyi): Can be a Ref(FunctionType) or Ref(ComputeGraphType).
+  function: Schema.optional(Ref.Ref(Obj.Unknown).annotations({ title: 'Function' })),
+
+  /**
+   * Only used for workflowSchema.
+   * Specifies the input node in the circuit.
+   * @deprecated Remove and enforce a single input node in all compute graphSchema.
+   */
+  inputNodeId: Schema.optional(Schema.String.annotations({ title: 'Input Node ID' })),
+
+  // TODO(burdon): NO BOOLEAN PROPERTIES (enabld/disabled/paused, etc.)
+  //  Need lint rule; or agent rule to require PR review for "boolean" key word.
+  enabled: Schema.optional(Schema.Boolean.annotations({ title: 'Enabled' })),
+
+  spec: Schema.optional(Spec),
+
+  concurrency: Schema.optional(
+    Schema.Number.annotations({
+      title: 'Concurrency',
+      default: 1,
+      description:
+        'Maximum number of concurrent invocations of the trigger. For Feed triggers, this will process Feed items in parallel.',
+    }),
+  ),
+
+  /**
+   * Passed as the input data to the function.
+   * Must match the function's input schema.
+   *
+   * @example
+   * {
+   *   item: '{{event.item}}',
+   *   instructions: 'Summarize and perform entity-extraction'
+   *   mailbox: { '/': 'dxn:echo:AAA:ZZZ' }
+   * }
+   */
+  input: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Any })),
+}).pipe(
+  Type.object({
+    typename: 'org.dxos.type.trigger',
+    version: '0.1.0',
+  }),
+  Annotation.IconAnnotation.set({ icon: 'ph--lightning--regular', hue: 'yellow' }),
+  SystemTypeAnnotation.set(true),
+);
+
+export interface Trigger extends Schema.Schema.Type<typeof TriggerSchema> {}
+export const Trigger: Type.Obj<Trigger> = TriggerSchema as any;
+
+export const make = (props: Obj.MakeProps<typeof Trigger>) => Obj.make(Trigger, props);

package/src/TriggerEvent.ts

@@ -0,0 +1,62 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { DXN, Obj, Ref } from '@dxos/echo';
+
+// TODO(wittjosiah): Review this type.
+//   - Should be discriminated union.
+//   - Should be more consistent (e.g. subject vs item).
+//   - Should re-use schemas if possible.
+
+// TODO(burdon): Reuse trigger schema from @dxos/functions (TriggerType).
+export const EmailEvent = Schema.Struct({
+  from: Schema.String,
+  to: Schema.String,
+  subject: Schema.String,
+  created: Schema.String,
+  body: Schema.String,
+});
+export type EmailEvent = Schema.Schema.Type<typeof EmailEvent>;
+
+export const QueueEvent = Schema.Struct({
+  queue: DXN.Schema,
+  item: Schema.Any,
+  cursor: Schema.String,
+});
+export type QueueEvent = Schema.Schema.Type<typeof QueueEvent>;
+
+export const SubscriptionEvent = Schema.Struct({
+  /**
+   * Type of the mutation.
+   */
+  // TODO(dmaretskyi): Specify enum.
+  type: Schema.String,
+
+  /**
+   * Reference to the object that was changed or created.
+   */
+  subject: Ref.Ref(Obj.Unknown),
+
+  /**
+   * @deprecated
+   */
+  changedObjectId: Schema.optional(Schema.String),
+});
+export type SubscriptionEvent = Schema.Schema.Type<typeof SubscriptionEvent>;
+
+export const TimerEvent = Schema.Struct({ tick: Schema.Number });
+export type TimerEvent = Schema.Schema.Type<typeof TimerEvent>;
+
+export const WebhookEvent = Schema.Struct({
+  url: Schema.String,
+  method: Schema.Literal('GET', 'POST'),
+  headers: Schema.Record({ key: Schema.String, value: Schema.String }),
+  bodyText: Schema.String,
+});
+export type WebhookEvent = Schema.Schema.Type<typeof WebhookEvent>;
+
+export const TriggerEvent = Schema.Union(EmailEvent, QueueEvent, SubscriptionEvent, TimerEvent, WebhookEvent);
+export type TriggerEvent = Schema.Schema.Type<typeof TriggerEvent>;

package/src/errors.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { BaseError, type BaseErrorOptions } from '@dxos/errors';
+
+// Errors from @dxos/operation.
+
+export class InvokerNotInitializedError extends BaseError.extend(
+  'InvokerNotInitializedError',
+  'Invoker not initialized',
+) {
+  constructor() {
+    super();
+  }
+}
+
+export class NoHandlerError extends BaseError.extend('NoHandlerError', 'No handler found for operation. ') {
+  constructor(operationKey: string) {
+    super({ context: { operationKey } });
+  }
+}
+
+// Errors from @dxos/functions.
+
+export class ServiceNotAvailableError extends BaseError.extend('ServiceNotAvailable', 'Service not available') {
+  constructor(service: string, options?: Omit<BaseErrorOptions, 'context'>) {
+    super({ context: { service }, ...options, message: `Service not available: ${service}` });
+  }
+}
+
+export class FunctionNotFoundError extends BaseError.extend('FunctionNotFound', 'Function not found') {
+  constructor(functionKey: string, options?: Omit<BaseErrorOptions, 'context'>) {
+    super({ context: { function: functionKey }, ...options });
+  }
+}
+
+export class FunctionError extends BaseError.extend('FunctionError', 'Function invocation error') {}
+
+export class InvalidOperationInputError extends BaseError.extend(
+  'InvalidOperationInput',
+  'Operation input did not match schema',
+) {}
+
+export class InvalidOperationOutputError extends BaseError.extend(
+  'InvalidOperationOutput',
+  'Operation output did not match schema',
+) {}
+
+export class TriggerStateNotFoundError extends BaseError.extend('TriggerStateNotFound', 'Trigger state not found') {}

package/src/index.ts

@@ -1,9 +1,19 @@
 //
-// Copyright 2024 DXOS.org
+// Copyright 2026 DXOS.org
 //
 
-export * from './compute-graph';
-export * from './compute-graph-registry';
-export * from './compute-node';
-export * from './functions';
-export * from './types';
+export * as Blueprint from './Blueprint';
+export * as Credential from './Credential';
+export * from './errors';
+export * as Operation from './Operation';
+export * as OperationHandlerSet from './OperationHandlerSet';
+export * as OperationRegistry from './OperationRegistry';
+export * as Process from './Process';
+export * as Routine from './Routine';
+export * as Script from './Script';
+export * as ServiceResolver from './ServiceResolver';
+export * as StorageService from './StorageService';
+export * as Template from './Template';
+export * as Trace from './Trace';
+export * as Trigger from './Trigger';
+export * as TriggerEvent from './TriggerEvent';

package/src/testing/definitions.ts

@@ -0,0 +1,49 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import * as Operation from '../Operation';
+
+export const Fibonacci = Operation.make({
+  meta: {
+    key: 'org.example.function.fib',
+    name: 'Fibonacci',
+    description: 'Function that calculates a Fibonacci number',
+  },
+  input: Schema.Struct({
+    iterations: Schema.optional(Schema.Number).annotations({
+      description: 'Number of iterations',
+      default: 100_000,
+    }),
+  }),
+  output: Schema.Struct({
+    result: Schema.String,
+  }),
+});
+
+export const Reply = Operation.make({
+  meta: {
+    key: 'org.example.function.reply',
+    name: 'Reply',
+    description: 'Function that echoes the input',
+  },
+  input: Schema.Any,
+  output: Schema.Any,
+});
+
+export const Sleep = Operation.make({
+  meta: {
+    key: 'org.example.function.sleep',
+    name: 'Sleep',
+    description: 'Function that sleeps for a given amount of time',
+  },
+  input: Schema.Struct({
+    duration: Schema.optional(Schema.Number).annotations({
+      description: 'Milliseconds to sleep',
+      default: 100_000,
+    }),
+  }),
+  output: Schema.Void,
+});

package/src/testing/fib.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Operation from '../Operation';
+import { Fibonacci } from './definitions';
+
+export default Fibonacci.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ iterations = 100_000 }) {
+      let a = 0n;
+      let b = 1n;
+      for (let i = 0; i < iterations; i++) {
+        a += b;
+        b = a - b;
+      }
+      return { result: a.toString() };
+    }),
+  ),
+);

package/src/testing/index.ts

@@ -1,8 +1,16 @@
 //
-// Copyright 2024 DXOS.org
+// Copyright 2025 DXOS.org
 //
 
-export * from './test-builder';
-export * from './test-plugin';
-export * from './util';
-export * from './test-runtime';
+import * as OperationHandlerSet from '../OperationHandlerSet';
+
+export { Fibonacci, Reply, Sleep } from './definitions';
+export { default as FibonacciHandler } from './fib';
+export { default as ReplyHandler } from './reply';
+export { default as SleepHandler } from './sleep';
+
+export const ExampleHandlers = OperationHandlerSet.lazy(
+  () => import('./fib'),
+  () => import('./reply'),
+  () => import('./sleep'),
+);

package/src/testing/reply.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+
+import * as Operation from '../Operation';
+import { Reply } from './definitions';
+
+export default Reply.pipe(
+  Operation.withHandler(
+    Effect.fn(function* (input) {
+      yield* Console.log('reply', { input });
+      return input;
+    }),
+  ),
+);

package/src/testing/sleep.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Operation from '../Operation';
+import { Sleep } from './definitions';
+
+export default Sleep.pipe(
+  Operation.withHandler(
+    Effect.fn(function* ({ duration = 100_000 }) {
+      yield* Effect.sleep(duration);
+    }),
+  ),
+);

package/src/umbrella.test.ts

@@ -0,0 +1,51 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import {
+  Blueprint,
+  Credential,
+  FunctionNotFoundError,
+  Operation,
+  OperationHandlerSet,
+  OperationRegistry,
+  Process,
+  Routine,
+  Script,
+  ServiceResolver,
+  StorageService,
+  Template,
+  Trace,
+  Trigger,
+  TriggerEvent,
+} from './index';
+
+describe('umbrella re-exports', () => {
+  test('top-level re-exports preserve source-package namespace nesting', ({ expect }) => {
+    // Operation primitives.
+    expect(Operation).toBeDefined();
+    expect(OperationHandlerSet).toBeDefined();
+    expect(OperationRegistry).toBeDefined();
+
+    // Blueprint primitives.
+    expect(Blueprint).toBeDefined();
+    expect(Blueprint.make).toBeTypeOf('function');
+    expect(Routine).toBeDefined();
+    expect(Template).toBeDefined();
+
+    // Function primitives.
+    expect(Process).toBeDefined();
+    expect(Trigger).toBeDefined();
+    expect(TriggerEvent).toBeDefined();
+    expect(Script).toBeDefined();
+    expect(Trace).toBeDefined();
+    expect(ServiceResolver).toBeDefined();
+    expect(StorageService).toBeDefined();
+    expect(Credential).toBeDefined();
+
+    // Error classes exported top-level.
+    expect(FunctionNotFoundError).toBeDefined();
+  });
+});