Add an operation

By the end of this page the + menu creates links through an operation, and a Mark as read operation marks a link as read.

Background

An operation is a named action with a typed input and output. The plugin defines it once and contributes a handler. After that, a button, the command palette and the assistant all run it the same way, through the framework’s operation invoker. Operations explains why.

Creating an object is an operation too. The Space plugin defines SpaceOperation.AddObject, and a plugin uses it to put a new object in a space.

Steps

1. Define an operation. The key is a DXN. The input and output are schemas; an agent reads their descriptions to learn what to pass. The input is a reference to a link rather than the link itself, so the assistant can pass one by its id.

   src/types/StashedLinkOperation.ts

   import * as Schema from 'effect/Schema';
   
   import * as Operation from '@dxos/compute/Operation';
   import { Database, DXN, Ref } from '@dxos/echo';
   
   import { StashedLink } from './StashedLink.ts';
   
   export const MarkRead = Operation.make({
     meta: {
       key: DXN.make('com.example.operation.stashedLink.markRead'),
       name: 'Mark as read',
       description: 'Mark a link as read.',
       icon: 'ph--check-circle--regular',
     },
     // The handler resolves the reference in the link's space.
     services: [Database.Service],
     input: Schema.Struct({
       link: Ref.Ref(StashedLink).annotate({
         description: 'The link that was read.',
       }),
     }),
     output: Schema.Void,
   });
   
   

2. Implement the handler. Operation.withHandler attaches an Effect to the definition. Operations are built on Effect, and Effect.gen reads like an async function, with yield* in place of await. This one looks the reference up in the space’s database with Database.resolve and sets the link’s read field. The operation’s services list what the handler uses from the context, here the space’s database.

   src/operations/mark-read.ts

   import * as Effect from 'effect/Effect';
   
   import * as Operation from '@dxos/compute/Operation';
   import { Database, Obj } from '@dxos/echo';
   
   import { StashedLink } from '../types/StashedLink.ts';
   import { MarkRead } from '../types/StashedLinkOperation.ts';
   
   const handler: Operation.WithHandler<typeof MarkRead> = MarkRead.pipe(
     Operation.withHandler(({ link: ref }) =>
       Effect.gen(function* () {
         // The assistant passes a reference by id, so look it up in the space.
         const link = yield* Database.resolve(ref, StashedLink);
         Obj.update(link, (link) => {
           link.read = true;
         });
       }),
     ),
   );
   
   export default handler;
   
   

3. Contribute the handler. A handler set lists the plugin’s handlers. Operation.lazyHandler loads the handler’s file the first time the operation runs, not when the plugin starts.

   src/operations/index.ts

   import * as Operation from '@dxos/compute/Operation';
   import * as OperationHandlerSet from '@dxos/compute/OperationHandlerSet';
   
   import { MarkRead } from '../types/StashedLinkOperation.ts';
   
   export const StashOperationHandlerSet = OperationHandlerSet.lazy([
     MarkRead.pipe(Operation.lazyHandler(() => import('./mark-read.ts'))),
   ]);
   
   

   src/capabilities/operation-handler.ts

   import * as Effect from 'effect/Effect';
   
   import * as Capabilities from '@dxos/app-framework/Capabilities';
   import * as Capability from '@dxos/app-framework/Capability';
   
   import { StashOperationHandlerSet } from '../operations/index.ts';
   
   export default Capability.makeModule(() =>
     Effect.succeed(
       Capability.contribute(
         Capabilities.OperationHandler,
         StashOperationHandlerSet,
       ),
     ),
   );
   
   

4. Create a link through an operation. The create-object module adds the type to the + menu and says how to create one: it invokes SpaceOperation.AddObject with a new link from make. Invoking the operation, rather than adding to the database directly, puts the link wherever the person asked, such as inside a collection.

   src/capabilities/create-object.ts

   import * as Effect from 'effect/Effect';
   
   import * as Capability from '@dxos/app-framework/Capability';
   import * as Operation from '@dxos/compute/Operation';
   import { Type } from '@dxos/echo';
   import * as SpaceCapabilities from '@dxos/plugin-space/SpaceCapabilities';
   import * as SpaceOperation from '@dxos/plugin-space/SpaceOperation';
   
   import { StashedLink, make } from '../types/StashedLink.ts';
   
   export default Capability.makeModule(() =>
     Effect.succeed(
       Capability.contribute(SpaceCapabilities.CreateObjectEntry, {
         id: Type.getTypename(StashedLink),
         createObject: (props, options) =>
           Operation.invoke(
             SpaceOperation.AddObject,
             { object: make(props), target: options.target },
             { spaceId: options.db.spaceId },
           ),
       }),
     ),
   );
   
   

5. Add the modules to the manifest.

   dx.config.ts

   import * as AppCapability from '@dxos/app-toolkit/AppCapability';
   import * as AppSurface from '@dxos/app-toolkit/AppSurface';
   import * as SpaceCapability from '@dxos/plugin-space/SpaceCapability';
   
   import { StashNamespace } from './src/namespace.ts';
   
   const config: Plugin.PluginConfig = Plugin.config({
     plugin: {
       key: StashNamespace.key,
       name: 'Stash',
       author: 'Example',
       description:
         'A reading list: save links with a note, and mark them as read.',
       icon: { key: 'ph--tray-arrow-down--regular', hue: 'indigo' },
       tags: ['labs'],
     },
     modules: [
       AppCapability.translations(
         () => import('./src/translations.ts', { with: { type: 'module-url' } }),
       ),
       AppCapability.schema(
         () =>
           import('./src/capabilities/schema.ts', {
             with: { type: 'module-url' },
           }),
       ),
       AppCapability.operationHandler(
         () =>
           import('./src/capabilities/operation-handler.ts', {
             with: { type: 'module-url' },
           }),
       ),
       SpaceCapability.createObject(
         () =>
           import('./src/capabilities/create-object.ts', {
             with: { type: 'module-url' },
           }),
       ),
   
   

6. Run it. Load or reload your plugin below. Click New in the header: the inspector runs the create-object module, as Composer’s + menu would, and a link named “New link” becomes the sample object that every module is shown with. Select Operations. The form is built from the operation’s input schema, and its link field takes the sample. Click Run: the operation has no output, so the inspector shows the sample after it ran, with read set to true.

   The links have no view yet. The next page lists them in the navigation tree and puts Mark as read on each link’s toolbar, and the page after that adds a view.

What you can do now

• Define an operation with schemas for its input and output, taking an object by reference.
• Implement a handler and load it lazily.
• Create an object of the plugin’s type through the Space plugin’s operation.