Improve handlers formatting

[nfroidure]

An handler like

whook/packages/whook-example/src/handlers/putEcho.ts

Lines 12 to 111 in 1cc3956

	/* Architecture Note #3.1.3: Reusable schemas
	This is how to declare a reusable API schema
	to avoid having to write it several times and
	lower your final Open API file weight.
	You simply have to export a variable finishing with
	the `Schema` suffix and assign it the
	`WhookAPISchemaDefinition` type to be guided
	when creating it.
	*/
	export const echoSchema: WhookAPISchemaDefinition<Components.Schemas.Echo> = {
	name: 'Echo',
	example: {
	echo: 'Repeat this!',
	},
	schema: {
	type: 'object',
	required: ['echo'],
	additionalProperties: false,
	properties: {
	echo: {
	type: 'string',
	},
	},
	},
	};
	/* Architecture Note #3.1.4: Reusable responses
	This is how to declare a reusable API response
	to avoid having to write it several times and
	lower your final Open API file weight.
	You simply have to export a variable finishing with
	the `Response` suffix and assign it the
	`WhookAPIResponseDefinition` type to be guided
	when creating it.
	*/
	export const echoResponse: WhookAPIResponseDefinition = {
	name: 'Echo',
	response: {
	description: 'Echo response',
	content: {
	'application/json': {
	schema: refersTo(echoSchema),
	},
	},
	},
	};
	/* Architecture Note #3.1.4: Reusable request bodies
	This is how to declare a reusable API request body
	to avoid having to write it several times and
	lower your final Open API file weight.
	You simply have to export a variable finishing with
	the `RequestBody` suffix and assign it the
	`WhookAPIRequestBodyDefinition` type to be guided
	when creating it.
	*/
	export const echoRequestBody: WhookAPIRequestBodyDefinition = {
	name: 'Echo',
	requestBody: {
	required: true,
	content: {
	'application/json': {
	schema: refersTo(echoSchema),
	},
	},
	},
	};
	/* Architecture Note #3.4.4: putEcho
	Simply outputs its input.
	*/
	export const definition: WhookAPIHandlerDefinition = {
	path: '/echo',
	method: 'put',
	operation: {
	operationId: 'putEcho',
	summary: 'Echoes what it takes.',
	tags: ['example'],
	/* Architecture Note #3.1.3.1: Usage
	To use reusable schemas, you must refer to it
	instead of writing it inline.
	You can use it in request/response bodies,
	inside parameters or even inside other
	schemas as per the OpenAPI specification.
	*/
	requestBody: refersTo(echoRequestBody),
	responses: {
	200: refersTo(echoResponse),
	},
	},
	};

could be rewitten like so:

// putEcho.handler.ts <-- allows Whook to detect it is an handler and to build schemas for it

// ...
import { type Echo, type Handler } from './putEcho.d.ts'; // Needs `schema2dts` update

export const echoSchema = {
  name: 'Echo',
  example: {
    // ...
  },
  schema: {
    // ...
  }
  // `const` allows to keep schema usable as consts
  // `satisfies` allows to type check awaiting more TS module checks
} as const satisfies WhookAPISchemaDefinition<Echo>;

export const METHOD = 'put' as const satisfies WhookAPIMethod;
export const PATH = '/echo' as const satisfies WhookAPIPath;

export const operation = {
  // ...
} as const satisfies WhookAPIOperation;

export const initPutEcho = async (
  { log }: { log: LogService },
) => Promise<Handler> {
  return ({ body }) => {
    // ...
    return {
      status: 200,
      body,
    };
  }
};

// Use service instead of handler that should be removed of knifecycle
export default autoService(initPutEcho);

The satisfies part is aimed to be removed when TypeScript will support pattern based module exports definition (see nfroidure/knifecycle#138).

The same kind of improvements could be done for schemas defined outside of handlers by detecting their file name (srs/lib/api.schemas.ts).