Add derived fields in PostGraphile
Branch: master
Clone or download

README.md

Package on npm CircleCI

postgraphile-plugin-derived-field

This plugin provides an interface for adding derived fields to the schema generated by PostGraphile v4.

The term "derived fields" is used to differentiate this approach from the standard Computed Columns support in PostGraphile. This plugin effectively adds "computed columns in JavaScript" to your toolbelt.

Getting Started

Define your derived fields in the derivedFieldDefinitions property of graphileBuildOptions:

const express = require("express");
const { postgraphile } = require("postgraphile");
const PostGraphileDerivedFieldPlugin = require("postgraphile-plugin-derived-field");

const app = express();

app.use(
  postgraphile(pgConfig, schema, {
    graphiql: true,
    appendPlugins: [PostGraphileDerivedFieldPlugin],
    graphileBuildOptions: {
      derivedFieldDefinitions: [
        // your definitions here
      ]
    }
  })
);

app.listen(5000);

Provide derivedFieldDefinitions as an array of objects with the following structure:

type DerivedFieldDefinition = {
  identifiers: Array<Identifier>,
  inflect: function,
  resolve: function,
  description?: string
  returnTypeName?: string
}

The Scenarios section below provides guidance on structuring identifiers, inflect, and resolve for your specific use case.

Use description to populate the field description in the schema.

Use returnTypeName to specify the name of the GraphQL type that resolve function returns. Default: "String"

Scenarios

Derive a new field from one database column

{
  identifiers: [
    {
      table: "my_schema.my_table",
      columns: ["my_column"],
    },
  ],
  inflect: fieldName => `derivedFrom${fieldName}`,
  resolve: val => `Value derived from ${val}`,
}

Derive a new field from multiple database columns

{
  identifiers: [
    {
      table: "my_schema.my_table",
      columns: ["my_column", "my_other_column"],
    },
  ],
  inflect: (...fieldNames) =>
    `derivedFrom${fieldNames.map(upperFirst).join("And")}`,
  resolve: (my_column, my_other_column) =>
    `Value derived from ${my_column} and ${my_other_column}`,
}

Derive a new field from columns that have a specific tag

This approach uses the "smart comments" feature of PostGraphile to match columns that have been assigned a specific tag.

{
  identifiers: [
    {
      tag: "mytag",
    },
  ],
  inflect: fieldName => `derivedFrom${fieldName}`,
  resolve: val => `Value derived from ${val}`,
}

Alternative syntax

Column names can be provided as a string: "my_schema.my_table.my_column". This syntax does not support generating a derived field from multiple database columns.

Tag names can be provided as a string: "@mytag"

Examples

Generate pre-signed URLs for client-side S3 GET requests
const express = require("express");
const { postgraphile } = require("postgraphile");
const PostGraphileDerivedFieldPlugin = require("postgraphile-plugin-derived-field");

const AWS = require("aws-sdk");
const s3 = new AWS.S3();
const bucket = "postgraphile-plugin-test";

const app = express();

app.use(
  postgraphile(pgConfig, schema, {
    graphiql: true,
    appendPlugins: [PostGraphileDerivedFieldPlugin],
    graphileBuildOptions: {
      derivedFieldDefinitions: [
        {
          identifiers: ["my_schema.my_table.my_column"],
          inflect: fieldName => `${fieldName}SignedUrl`,
          resolve: val => s3.getSignedUrl('getObject', {Bucket: bucket, Key: val, Expires: 900})
        }
      ]
    }
  })
);

app.listen(5000);