simonireilly / compeller Goto Github PK

When need to allow for different request/response formats.

In general, we could have two scenario's:

• #34
• #35

Adapters

Option 1

We could configure the response adapter like:

const api = compeller(spec, {
  adapter: 'apigateway'
});

const { request, response } = api('/api/v1/line-items/{id}', 'get')

Option 2

Design an interface.

If we will hand off the interfaces of statusCode, body?, headers? then we can allow for an adapter to be written like:

const responder = (
  statusCode: number, 
  body: Record<string, unknown> = {}, 
  headers: Record<string, unknown> = {}
) => ({
  statusCode,
  body: JSON.stringify(body),
  headers
})

const api = compeller(spec, {
  responder,
});

const { request, response } = api('/api/v1/line-items/{id}', 'get')

We should publish compeller as beta software, you can use it, it's probably going to have bugs.

Version: 0.0.1-beta.1

This will utilise out existing yarn canary command.

Goals

Get publishing put of the way, so we can focus on features, and performance

Remember to delete all existing tags 👍

It's great to show some examples using the Library in different ways.

Some suggestions include:

• using it to write aws lambda APIs
• using it to generate API documentation
• using it in conjunction with mappers to transform data
• using in conjunction with test suites to show how mocks/fixtures can be generated

This will help both iron out bugs, and inform the development direction

By default compeller should keep an OpenAPI schema document.

It should support hashing the schema JSON file to prevent writing repetitively.

We should encourage a single declaration of the compeller instance in projects.

When the compeller is invoked, it would have a side-effect of writing a file, but, we don't want to do that on readonly file systems such as servers.

Suggest we only allow for dumping when node env is not production, and do a read-only file system check.

Additionally this behaviour should be opt in for the time being.

Implementation

compeller should take an options object, on option should be to keep an OpenAPI JSON file in sync with compeller.

Possible params,

True, use default relative file

Config, specify file path

Currently the type for ajv is inferred, from the type of the object.

This object is inferred from the JSONSchema type. It looks as below:

Ajv.compile<JSONSchemaType<FromSchema<typeof schema>>>(schema)

This double inference might not be necessary, since the schema type is already know.

Investigate if:

Ajv.compile(schema)

Returns the expected type from validation, without supplying a generic

We should be able to support headers as:

• #23
• #24

This should be compatible with the module's responder, requester, and validator.

It would be good to make the responder and requester purer at this junction, and instead of having them be declared inside the scope of compeller, they can be delegated to.

Currently, the responder interface is passive and returns an any type.

In order to allow a typed response, we should infer the type in the actual responder.

This might be a simple case of saying that the return type of a responder should extend any and allowing typescript to narrow the type once the function is actually called.

We should be able to import a schema, simply by splitting out all its existing JSON into separate schemas.

This means we can onboard users quickly.

Ideally, this would tie into a CLI, and support a local .json file or a remote .json URL.

API

npx compeller new --openapi-file ./specification.json

Currently, the typing in compeller has been growing from a what can be made to work type specification but the actual typing needs to enforce the required format of the schema document.

Requirements

• All schemas need to be static, to allow for inference, so must use the JSONSchema type from json-schema-to-ts
• Since paths don't support ref's it should not be possible to put a ref in a path

Essentially, the document should be richly typed

To encourage best practices, we should create a CLI for compeller that will.

• Create a folder for the openapi specification
• Create a layout for organising the specification

Response senders are adapters.

These adapters can be configured on a compeller instance to handle the formation of all responses.

These responses should be those that you are returning to the calling procedure e.g in AWS lambda it will be the return object of the lambda function.

The path object of an OpenAPI specification is associated with the parameters declaration.

Common use cases like ?limit=10&offset=0 should be supported.

• feat: paths can be typed and validated

Since we have a runtime write file, we need to improve that.

Ideally we would have a default export from the compeller file (do we want that, I hate default imports 🤷

Well, we want to be able to run:

yarn compeller export [file-path]

This will export the API to a JSON object.

Since we generate a location for schemas we should make it really easy for users to add schemas.

yarn compeller add-schema [name]

• The new schema should go into the default location for schemas and have a skeleton to fill in the epxorts.
• The CLI might need a configuration entity

We could do with more rich examples to ensure that users get to understand how to use the library.

Compeller needs to support refs, because refs are used heavily in OpenAPI specifications which become very large.

The specification itself will use refs to point at other declarations.

MVP

For an MVP, pointing at:

components.schema

Would be enough, in my opinion, to allow users to dry out their schema's.

Example

import { VersionSchema } from './schemas/version.schema';

export const OpenAPISpecification = {
  info: {
    title: 'New API generated with compeller',
    version: '1.0.0',
  },
  openapi: '3.1.0',
  paths: {
    'v1/version': {
      get: {
        responses: {
          '200': {
            description: 'Get the current API version',
            content: {
              'application/json': {
                schema: {
                  $ref: '#/components/schemas/Version',
                },
              },
            },
          },
        },
      },
    },
  },
  components: {
    schemas: {
      Version: {
        type: 'object',
        required: ['version'],
        additionalProperties: false,
        properties: {
          version: {
            type: 'string',
          },
        },
      } as const,
    },
  },
};

Research

This tool supports refs, and is suggested reading: https://github.com/Q42/openapi-typescript-validator

In principle we would be looking for the schema key to be ref and if so we would want to find the ref in the OpenAPI object, and use the ref type as the schema type.