sfr-core v1.0.5

Schema First Rest

Schema First Rest (SFR) allows you to build your REST APIs using graphql schema.

The magic of SFR is the plugin ecosystem around it. You can install plugins that expose graphql decorators and can emit code based on your schema.

Schema

The following code uses the @sfr/controller plugin, which exposes a controller, request, and auth decorators:

type User @controller(path: "user") {
  login(request: LoginRequest!): LoginResponse!
    @request(method: POST, path: "login")

  getUser(request: GetUserRequest!): UserResponse!
    @request(method: GET, path: "user")
    @auth

  updateUser(request: UpdateUserRequest!): UserResponse!
    @request(method: POST, path: "update-user")
    @auth
}

type LoginRequest {
  username: String!
}
type LoginResponse {
  authorized: Boolean!
  jwt: String!
}
type GetUserRequest {
  userId: String!
}

type UpdateUserRequest {
  email: String!
  eyeColor: Int!
}
type UserResponse {
  user: UserModel!
}
type UserModel {
  email: String!
  eyeColor: Int!
}

This will give the plugin (and the plugins that depend on it) information about your REST API. For instance, the plugins @sfr/raw-fetch and @sfr/models uses the metadata produced by the @sfr/controller plugin to build a typescript file to make requests to your api.

Config

You define the plugins via an sfc.yml config file at the root of your projects directory:

schema: ./schema/*.graphql # the schemas you want to act on
prettier: ./.prettierrc    # an optional prettier file
config:
  @sfr/raw-fetch:          # config values for the plugins
    baseClientLocation: ./baseClient
generates:
  api/api.ts:              # the name of the file to generate
    plugins:               # the plugins to use on this file 
      - @sfr/raw-fetch
      - @sfr/models

The above sfc.yml file will create a file named api/api.ts and will contain the fetch code as well as the typescript models from your schema file.

Plugins

Plugins are trivial to create. While you can use our plugins, we encourage you to create your own to fill the needs of your projects use cases.

Plugins can define schema, typically in the form of directives, as seen in the @sfr/controller/schema.graphql plugin. They can also emit code as seen in the @sfr/raw-fetch/index.ts plugin. All you do is export a plugin function and a config object:

import {PluginConfig, PluginOptions} from '@sfr/core';

export function plugin(options: PluginOptions, config: {baseClientLocation: string}) {
  return options.actions.map(action=>`${action.name}`) 
}

export const config: PluginConfig = {
  dependsOn: ['@sfr/controller'],
};

PluginOptions contains an array of actions, which are graphql types that have at least one directive. Each action all the declared directives, and all of the fields within it. You can iterate through these and emit your code as needed.

For complex plugins we recommend using ejs as a template language.