feat(api): domain functions handler core

[riccardoperra]

Handlers

Handlers are domain scoped functions that can be used to extract business logic and make it independent by the rest of the application.

They are registered into a global registry map HandlerRegistry which exposes an add method to register a new handler, and a event property to retrieve the registered handlers

Creating new handlers

Handlers can be created through the HandlerBuilder which use the builder pattern under the hood. In order to create the handler correctly you must define the dependencies, the handler name and it's implementation.

Note the way of creating handler is still experimental and may change

type Deps = { 
 repository: UserRepository
}

// 1. Define handler deps, name and implementation
const handler1 = HandlerBuilder
  .withDependencies<Deps>()
  .withName('handlerName1')
  .withImplementation((dependencies, metadata) => (str: string) => {
    return {
      str,
      a1: 1,
    } as const;
  })
  .build();

// 2. Augment DomainHandlerMap module to register your handler in global types
declare module '@api/domain' {
  interface DomainHandlerMap {
    handlerName: typeof handler1;
  }
}

Registering handlers

Once you have created your handlers, you can register all of them through the registerHandlers helper, which accept a list of handlers, the requested dependencies and the registry

const registry = new HandlerRegistry();

const handlers = registerHandlers(
 [handler1],
 { repository: new UserRepository() },
 registry
)

Handlers can be used from both handlers or registry map

handlers.handlerName1('test'); // ✅ Call handler method with given parameters
handlers.handlerName(1); // ❌ Cannot pass arguments with wrong types.

registry.events.handlerName1('test');

Using in Fastify

1. Define global handler registry plugin

// plugins/handlerRegistry.ts

export default fp(async fastify => {
  fastify.decorate('handlerRegistry', new HandlerRegistry())
})

declare module 'fastify' {
  interface FastifyInstance {
    handlerRegistry: HandlerRegistry;
  }
}

2. Create your handlers

// todo/handlers/add.ts

export const addHandler = HandlerBuilder
  .withDependencies<Deps>()
  .withName('addTodo')
  .withImplementation(...)
  .build();

declare module '@api/domain' {
  interface DomainHandlerMap {
    addTodo: typeof addTodo;
  }
}

// todo/handlers/get.ts

export const getHandler = HandlerBuilder
  .withDependencies<Deps>()
  .withName('getTodos')
  .withImplementation(...)
  .build();

declare module '@api/domain' {
  interface DomainHandlerMap {
    getTodos: typeof getHandler;
  }
}

3. Register your handlers in fastify context

// todo/index.ts
import {getHandler} from './handlers/get.ts';
import {addTodo} from './handlers/add.ts';

const handlers = [getHandler, addTodo] as const;

const todoModule: FastifyPluginAsync = (fastify) => {
  const deps = { };

  fastify.decorate(
    'todoService', 
    registerHandlers(handlers, deps, fastify.handlerRegistry)
  );
}

[codesandbox[bot]]

  Open in CodeSandbox Web Editor | VS Code | VS Code Insiders

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: d6b32e47fc50482657b57e72b75fd4fbebc3f17c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions[bot]]

Deploy preview for codeimage-ui-dev ready!

✅ Preview https://codeimage-ui-pqscs2zvd-riccardoperra.vercel.app https://codeimage-ui-pr-485.vercel.app

Built with commit d6b32e47fc50482657b57e72b75fd4fbebc3f17c. This pull request is being automatically deployed with vercel-action

[github-actions[bot]]

Deploy preview for codeimage-highlight-dev ready!

✅ Preview https://codeimage-highlight-g8f8s7b6w-riccardoperra.vercel.app https://codeimage-highlight-pr-485.vercel.app

Built with commit d6b32e47fc50482657b57e72b75fd4fbebc3f17c. This pull request is being automatically deployed with vercel-action

[github-actions[bot]]

Deploy preview for codeimage ready!

✅ Preview https://codeimage-84dqfflr5-riccardoperra.vercel.app https://codeimage-app-pr-485.vercel.app

Built with commit d6b32e47fc50482657b57e72b75fd4fbebc3f17c. This pull request is being automatically deployed with vercel-action

[github-actions[bot]]

Deploy preview for codeimage-website-dev ready!

✅ Preview https://codeimage-website-2z5slz8nm-riccardoperra.vercel.app https://codeimage-website-pr-485.vercel.app

Built with commit d6b32e47fc50482657b57e72b75fd4fbebc3f17c. This pull request is being automatically deployed with vercel-action