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]

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: d6b32e4

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]

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 d6b32e4.
This pull request is being automatically deployed with vercel-action

[github-actions]

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 d6b32e4.
This pull request is being automatically deployed with vercel-action

[github-actions]

Deploy preview for codeimage ready!

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

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

[github-actions]

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 d6b32e4.
This pull request is being automatically deployed with vercel-action

[hackpirodev]

@riccardoperra what do you think instead cast to unknown if we create a function to get typed entries?
something like this:

declare type Entries<T> = {
  [K in keyof T]: [K, T[K]];
}[keyof T][];

export const entries = <
  T extends Record<string, unknown> | Map<string, unknown>,
>(
  obj: T,
): Entries<T> => Object.entries(obj) as any;

[riccardoperra]

I'm not sure this works because the #entries type is Map<string, GenericHandler>, we need to force the cast because it should resolve the type based on "T", assuming that you are registering ALL handlers you are defining.

Thinks of that Registry contains handlers from multiple modules, and you can call the registryHandlers from difference files

[riccardoperra]

@hackpirodev I also noticed that the current implementation doesn't need as unknown, so it's basically the same. we can remove it using the same fromEntries() fn